From d91ff7b83a8b3d8693287da9b27c85f6c46cf8ce Mon Sep 17 00:00:00 2001 From: hailin Date: Thu, 5 Mar 2026 05:55:07 -0800 Subject: [PATCH] =?UTF-8?q?docs(mobile-app):=20=E5=AE=8C=E5=96=84=E8=AE=A4?= =?UTF-8?q?=E7=A7=8D=E5=AF=86=E7=A0=81=E6=A0=A1=E9=AA=8C=E7=9B=B8=E5=85=B3?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PasswordVerifyDialog: 补充类级文档、onVerify 字段说明、_handleConfirm 流程注释 - account_service.verifyLoginPassword: 补充参数、响应格式、行为说明 - planting_location_page._verifyPasswordThenSubmit: 说明在认种流程中的插入位置与作用 Co-Authored-By: Claude Sonnet 4.6 --- .../lib/core/services/account_service.dart | 9 +++++- .../pages/planting_location_page.dart | 6 +++- .../widgets/password_verify_dialog.dart | 31 +++++++++++++++++-- 3 files changed, 42 insertions(+), 4 deletions(-) diff --git a/frontend/mobile-app/lib/core/services/account_service.dart b/frontend/mobile-app/lib/core/services/account_service.dart index 02b346d6..00771270 100644 --- a/frontend/mobile-app/lib/core/services/account_service.dart +++ b/frontend/mobile-app/lib/core/services/account_service.dart @@ -2097,7 +2097,14 @@ class AccountService { /// 验证登录密码 (POST /user/verify-password) /// - /// 返回 true 表示密码正确，false 表示密码错误，抛出异常表示网络/系统错误 + /// 用于敏感操作的二次身份验证，目前用于认种前校验。 + /// + /// [password] 用户输入的密码明文 + /// + /// 后端响应格式：{ "valid": true/false } + /// - 返回 true：密码正确 + /// - 返回 false：密码错误（valid=false） + /// - 抛出异常：网络/系统错误（ApiException 或其他） Future verifyLoginPassword(String password) async { debugPrint('$_tag verifyLoginPassword() - 开始验证登录密码'); try { diff --git a/frontend/mobile-app/lib/features/planting/presentation/pages/planting_location_page.dart b/frontend/mobile-app/lib/features/planting/presentation/pages/planting_location_page.dart index 5dbe79f1..fec8343f 100644 --- a/frontend/mobile-app/lib/features/planting/presentation/pages/planting_location_page.dart +++ b/frontend/mobile-app/lib/features/planting/presentation/pages/planting_location_page.dart @@ -243,7 +243,11 @@ class _PlantingLocationPageState extends ConsumerState { } } - /// 验证密码后再提交认种 + /// 验证登录密码后再提交认种 + /// + /// 插入在 [PlantingConfirmDialog] 确认与 [_submitPlanting] 之间： + /// 弹出 [PasswordVerifyDialog] → 密码正确才调用 [_submitPlanting]， + /// 取消或验证失败则停留在当前页，不触发任何提交逻辑。 Future _verifyPasswordThenSubmit() async { final verified = await PasswordVerifyDialog.show( context: context, diff --git a/frontend/mobile-app/lib/features/planting/presentation/widgets/password_verify_dialog.dart b/frontend/mobile-app/lib/features/planting/presentation/widgets/password_verify_dialog.dart index 9de78291..2df6569c 100644 --- a/frontend/mobile-app/lib/features/planting/presentation/widgets/password_verify_dialog.dart +++ b/frontend/mobile-app/lib/features/planting/presentation/widgets/password_verify_dialog.dart @@ -1,12 +1,29 @@ import 'package:flutter/material.dart'; /// 认种密码验证回调类型 -/// 返回 true 表示密码正确，false 表示密码错误，抛出异常表示网络/系统错误 +/// +/// [password] 用户输入的密码明文 +/// 返回 true 表示密码正确，false 表示密码错误（如 valid=false）， +/// 抛出异常表示网络/系统错误（由弹窗捕获并展示提示） typedef PasswordVerifyCallback = Future Function(String password); /// 认种密码校验弹窗 -/// 在用户确认认种前，要求输入登录密码进行身份验证 +/// +/// 在 [PlantingConfirmDialog] 用户点击"确认认种"之后、实际提交之前弹出， +/// 要求用户输入登录密码进行二次身份验证，防止误操作或他人操作。 +/// +/// 调用方式： +/// ```dart +/// final verified = await PasswordVerifyDialog.show( +/// context: context, +/// onVerify: (password) => accountService.verifyLoginPassword(password), +/// ); +/// if (verified == true) _submitPlanting(); +/// ``` +/// +/// 后端接口：POST /user/verify-password → { valid: bool } class PasswordVerifyDialog extends StatefulWidget { + /// 密码校验回调，由调用方注入（通常调用 accountService.verifyLoginPassword） final PasswordVerifyCallback onVerify; const PasswordVerifyDialog({ @@ -46,6 +63,13 @@ class _PasswordVerifyDialogState extends State { } /// 点击确认按钮 + /// + /// 流程： + /// 1. 校验输入不为空 + /// 2. 调用 [onVerify] 发起网络请求 + /// 3. valid=true → 关闭弹窗并返回 true（调用方继续提交认种） + /// 4. valid=false → 展示"密码错误"提示，留在弹窗 + /// 5. 抛出异常（网络错误等）→ 展示系统错误提示，留在弹窗 Future _handleConfirm() async { final password = _passwordController.text.trim(); if (password.isEmpty) { @@ -62,14 +86,17 @@ class _PasswordVerifyDialogState extends State { final success = await widget.onVerify(password); if (!mounted) return; if (success) { + // 密码正确：关闭弹窗，返回 true 通知调用方继续提交 Navigator.pop(context, true); } else { + // 密码错误（valid=false）：提示用户重试 setState(() { _isVerifying = false; _errorMessage = '密码错误，请重试'; }); } } catch (e) { + // 网络/系统异常：提示检查网络 if (!mounted) return; setState(() { _isVerifying = false;