docs(mobile-app): 完善认种密码校验相关代码注释

- PasswordVerifyDialog: 补充类级文档、onVerify 字段说明、_handleConfirm 流程注释
- account_service.verifyLoginPassword: 补充参数、响应格式、行为说明
- planting_location_page._verifyPasswordThenSubmit: 说明在认种流程中的插入位置与作用

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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<bool> verifyLoginPassword(String password) async {
     debugPrint('$_tag verifyLoginPassword() - 开始验证登录密码');
     try {

frontend/mobile-app/lib/features/planting/presentation/pages/planting_location_page.dart

@@ -243,7 +243,11 @@ class _PlantingLocationPageState extends ConsumerState<PlantingLocationPage> {
     }
   }
 
-  /// 验证密码后再提交认种
+  /// 验证登录密码后再提交认种
+  ///
+  /// 插入在 [PlantingConfirmDialog] 确认与 [_submitPlanting] 之间：
+  /// 弹出 [PasswordVerifyDialog] → 密码正确才调用 [_submitPlanting]，
+  /// 取消或验证失败则停留在当前页，不触发任何提交逻辑。
   Future<void> _verifyPasswordThenSubmit() async {
     final verified = await PasswordVerifyDialog.show(
       context: context,

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<bool> 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<PasswordVerifyDialog> {
   }
 
   /// 点击确认按钮
+  ///
+  /// 流程：
+  /// 1. 校验输入不为空
+  /// 2. 调用 [onVerify] 发起网络请求
+  /// 3. valid=true → 关闭弹窗并返回 true（调用方继续提交认种）
+  /// 4. valid=false → 展示"密码错误"提示，留在弹窗
+  /// 5. 抛出异常（网络错误等）→ 展示系统错误提示，留在弹窗
   Future<void> _handleConfirm() async {
     final password = _passwordController.text.trim();
     if (password.isEmpty) {
@@ -62,14 +86,17 @@ class _PasswordVerifyDialogState extends State<PasswordVerifyDialog> {
       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;