docs: cleanup old plans and add new design docs
This commit is contained in:
qzl
@@ -0,0 +1,404 @@
|
||||
# 注册验证码流程 UX 优化实现计划
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** 优化注册流程的界面响应速度和重发验证码按钮的交互体验
|
||||
|
||||
**Architecture:** 乐观跳转策略 + Timer 倒计时状态管理，后台异步发送验证码
|
||||
|
||||
**Tech Stack:** Flutter, dart:async Timer, flutter_bloc
|
||||
|
||||
---
|
||||
|
||||
## Task 1: 扩展 RegisterCubit 状态
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/auth/presentation/cubits/register_cubit.dart`
|
||||
- Modify: `apps/test/features/auth/presentation/cubits/register_cubit_test.dart`
|
||||
|
||||
**Step 1: 添加 isSending 状态字段**
|
||||
|
||||
在 `RegisterState` 中添加 `isSending` 字段：
|
||||
|
||||
```dart
|
||||
// RegisterState
|
||||
final bool isSending;
|
||||
|
||||
const RegisterState({
|
||||
// ... existing fields
|
||||
this.isSending = false,
|
||||
});
|
||||
|
||||
// copyWith
|
||||
bool? isSending,
|
||||
|
||||
// copyWith return
|
||||
isSending: isSending ?? this.isSending,
|
||||
|
||||
// props
|
||||
isSending,
|
||||
```
|
||||
|
||||
**Step 2: 添加 sendCodeSilently 方法**
|
||||
|
||||
在 `RegisterCubit` 中添加不阻塞的发送方法：
|
||||
|
||||
```dart
|
||||
Future<void> sendCodeSilently() async {
|
||||
if (!state.isStep1Valid) return;
|
||||
|
||||
emit(state.copyWith(isSending: true));
|
||||
|
||||
try {
|
||||
final response = await _repository.signupStart(
|
||||
SignupStartRequest(
|
||||
username: state.username.value,
|
||||
email: state.email.value,
|
||||
password: state.password.value,
|
||||
),
|
||||
);
|
||||
emit(
|
||||
state.copyWith(
|
||||
isSending: false,
|
||||
pendingEmail: response.email,
|
||||
codeSent: true,
|
||||
errorMessage: null,
|
||||
),
|
||||
);
|
||||
} catch (e) {
|
||||
final message = e is ApiException ? e.message : '验证码发送失败，请重试';
|
||||
emit(
|
||||
state.copyWith(
|
||||
isSending: false,
|
||||
errorMessage: message,
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: 添加测试**
|
||||
|
||||
```dart
|
||||
// 在 register_cubit_test.dart 添加
|
||||
|
||||
group('sendCodeSilently', () {
|
||||
blocTest<RegisterCubit, RegisterState>(
|
||||
'sets isSending to true then false on success',
|
||||
build: () => cubit,
|
||||
seed: () => RegisterState(
|
||||
username: const Username.dirty('testuser'),
|
||||
email: const Email.dirty('test@example.com'),
|
||||
password: const Password.dirty('password123'),
|
||||
),
|
||||
setUp: () {
|
||||
when(() => mockRepository.signupStart(any()))
|
||||
.thenAnswer((_) async => SignupStartResponse(email: 'test@example.com'));
|
||||
},
|
||||
act: (c) => c.sendCodeSilently(),
|
||||
verify: (_) {
|
||||
verify(() => mockRepository.signupStart(any())).called(1);
|
||||
},
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
**Step 4: 运行测试**
|
||||
|
||||
Run: `cd apps && flutter test test/features/auth/presentation/cubits/register_cubit_test.dart`
|
||||
Expected: PASS
|
||||
|
||||
**Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/auth/presentation/cubits/register_cubit.dart apps/test/features/auth/presentation/cubits/register_cubit_test.dart
|
||||
git commit -m "feat(auth): add sendCodeSilently with isSending state"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: 实现乐观跳转
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/auth/ui/screens/register_screen.dart`
|
||||
|
||||
**Step 1: 修改 _handleNext 方法**
|
||||
|
||||
将同步等待改为乐观跳转：
|
||||
|
||||
```dart
|
||||
Future<void> _handleNext() async {
|
||||
final cubit = context.read<RegisterCubit>();
|
||||
cubit.usernameChanged(_nicknameController.text);
|
||||
cubit.emailChanged(_emailController.text);
|
||||
cubit.passwordChanged(_passwordController.text);
|
||||
|
||||
if (!cubit.state.isStep1Valid) {
|
||||
return;
|
||||
}
|
||||
|
||||
// 乐观跳转：立即跳转到验证码界面
|
||||
if (mounted) {
|
||||
context.push('/register/verification', extra: cubit);
|
||||
}
|
||||
|
||||
// 后台发送验证码
|
||||
cubit.sendCodeSilently();
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/auth/ui/screens/register_screen.dart
|
||||
git commit -m "feat(auth): optimistic navigation to verification screen"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: 实现倒计时状态管理
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/auth/ui/screens/register_verification_screen.dart`
|
||||
|
||||
**Step 1: 添加 Timer 状态**
|
||||
|
||||
在 `_RegisterVerificationViewState` 中添加：
|
||||
|
||||
```dart
|
||||
import 'dart:async';
|
||||
|
||||
// 状态变量
|
||||
Timer? _countdownTimer;
|
||||
int _countdown = 60;
|
||||
|
||||
@override
|
||||
void initState() {
|
||||
super.initState();
|
||||
_startCountdown();
|
||||
}
|
||||
|
||||
@override
|
||||
void dispose() {
|
||||
_countdownTimer?.cancel();
|
||||
_codeController.dispose();
|
||||
super.dispose();
|
||||
}
|
||||
|
||||
void _startCountdown() {
|
||||
setState(() {
|
||||
_countdown = 60;
|
||||
});
|
||||
_countdownTimer?.cancel();
|
||||
_countdownTimer = Timer.periodic(const Duration(seconds: 1), (timer) {
|
||||
if (_countdown > 0) {
|
||||
setState(() {
|
||||
_countdown--;
|
||||
});
|
||||
} else {
|
||||
timer.cancel();
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/auth/ui/screens/register_verification_screen.dart
|
||||
git commit -m "feat(auth): add countdown timer for resend button"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: 优化重发按钮样式
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/auth/ui/screens/register_verification_screen.dart`
|
||||
|
||||
**Step 1: 重构 _buildCodeInput 方法**
|
||||
|
||||
替换重发按钮部分：
|
||||
|
||||
```dart
|
||||
Widget _buildCodeInput(RegisterState state) {
|
||||
final canResend = _countdown == 0 && state.status != FormzSubmissionStatus.inProgress;
|
||||
|
||||
return Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: [
|
||||
const Text(
|
||||
'邮箱验证码',
|
||||
style: TextStyle(
|
||||
fontSize: 13,
|
||||
fontWeight: FontWeight.w500,
|
||||
color: Color(0xFF475569),
|
||||
),
|
||||
),
|
||||
const SizedBox(height: 6),
|
||||
Row(
|
||||
children: [
|
||||
Expanded(
|
||||
child: SizedBox(
|
||||
height: 40,
|
||||
child: TextField(
|
||||
controller: _codeController,
|
||||
keyboardType: TextInputType.number,
|
||||
decoration: const InputDecoration(
|
||||
hintText: '输入验证码',
|
||||
contentPadding: EdgeInsets.symmetric(
|
||||
horizontal: 12,
|
||||
vertical: 10,
|
||||
),
|
||||
),
|
||||
),
|
||||
),
|
||||
),
|
||||
const SizedBox(width: 8),
|
||||
_buildResendButton(canResend),
|
||||
],
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
Widget _buildResendButton(bool canResend) {
|
||||
final borderColor = canResend ? AppColors.primary : AppColors.slate300;
|
||||
final textColor = canResend ? AppColors.primary : AppColors.slate400;
|
||||
final text = canResend ? '重新发送' : '$_countdown s';
|
||||
|
||||
return SizedBox(
|
||||
width: 90,
|
||||
height: 40,
|
||||
child: OutlinedButton(
|
||||
onPressed: canResend ? _handleResendCode : null,
|
||||
style: OutlinedButton.styleFrom(
|
||||
backgroundColor: AppColors.background,
|
||||
side: BorderSide(color: borderColor),
|
||||
shape: RoundedRectangleBorder(
|
||||
borderRadius: BorderRadius.circular(8),
|
||||
),
|
||||
),
|
||||
child: Text(
|
||||
text,
|
||||
style: TextStyle(
|
||||
fontSize: 13,
|
||||
fontWeight: FontWeight.w500,
|
||||
color: textColor,
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/auth/ui/screens/register_verification_screen.dart
|
||||
git commit -m "feat(auth): improve resend button style with countdown"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: 添加 Toast 错误提示
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/lib/features/auth/ui/screens/register_verification_screen.dart`
|
||||
|
||||
**Step 1: 添加 BlocListener 监听错误**
|
||||
|
||||
用 `BlocConsumer` 替换 `BlocBuilder`，添加监听：
|
||||
|
||||
```dart
|
||||
import '../../../../shared/widgets/toast/toast.dart';
|
||||
|
||||
Widget _buildFormContainer() {
|
||||
return BlocConsumer<RegisterCubit, RegisterState>(
|
||||
listener: (context, state) {
|
||||
// 监听后台发送验证码的错误
|
||||
if (state.errorMessage != null && !state.isStep2Valid) {
|
||||
Toast.show(context, state.errorMessage!, type: ToastType.error);
|
||||
}
|
||||
},
|
||||
builder: (context, state) {
|
||||
return SizedBox(
|
||||
width: 327,
|
||||
child: Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.stretch,
|
||||
children: [
|
||||
_buildCodeInput(state),
|
||||
const SizedBox(height: 12),
|
||||
_buildStepIndicator(),
|
||||
const SizedBox(height: 12),
|
||||
AppButton(
|
||||
text: '完成注册',
|
||||
onPressed: state.status == FormzSubmissionStatus.inProgress
|
||||
? null
|
||||
: _handleComplete,
|
||||
),
|
||||
],
|
||||
),
|
||||
);
|
||||
},
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: 修改 _handleResendCode 重置倒计时**
|
||||
|
||||
```dart
|
||||
Future<void> _handleResendCode() async {
|
||||
final cubit = context.read<RegisterCubit>();
|
||||
await cubit.resendCode();
|
||||
|
||||
// 重发成功后重置倒计时
|
||||
if (cubit.state.codeSent && mounted) {
|
||||
_startCountdown();
|
||||
Toast.show(context, '验证码已发送', type: ToastType.success);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add apps/lib/features/auth/ui/screens/register_verification_screen.dart
|
||||
git commit -m "feat(auth): add toast feedback for code sending"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: 集成测试与验收
|
||||
|
||||
**Step 1: 运行全部测试**
|
||||
|
||||
Run: `cd apps && flutter test`
|
||||
Expected: All tests PASS
|
||||
|
||||
**Step 2: 手动验收清单**
|
||||
|
||||
- [ ] 点击"下一步"后立即跳转到验证码界面
|
||||
- [ ] 验证码界面显示倒计时按钮 "60 s" ... "1 s"
|
||||
- [ ] 倒计时期间按钮禁用
|
||||
- [ ] 倒计时结束后显示"重新发送"，可点击
|
||||
- [ ] 点击重发后重新开始 60 秒倒计时
|
||||
- [ ] 发送失败时 Toast 提示错误
|
||||
|
||||
**Step 3: Final commit**
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat(auth): complete register verification UX optimization"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件变更汇总
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `register_cubit.dart` | 添加 `isSending` 状态、`sendCodeSilently` 方法 |
|
||||
| `register_screen.dart` | 乐观跳转，后台发送 |
|
||||
| `register_verification_screen.dart` | Timer 倒计时、按钮样式、Toast 提示 |
|
||||
| `register_cubit_test.dart` | 新增 `sendCodeSilently` 测试 |
|
||||
Reference in New Issue
Block a user