platforms/docs/项目文档_移动端登录密码必填校验_v1.0.md

移动端登录密码必填校验项目文档 v1.0

1. 项目概述

• 项目名称：用户端与工作人员端登录密码必填校验。
• 主要功能：在手机号密码登录请求发出前完成字段级校验，阻止空密码请求并提供明确中文反馈。
• 技术栈：Flutter、Dart、Material 组件、Flutter Widget Test。
• 运行环境：项目当前 Flutter SDK 与 Web 构建环境。
• 实施范围：user_app 与 service_app 登录页面及其组件测试；后端接口、会话公共接口和数据库均不修改。

2. 目录结构说明

platforms/
├── apps/
│   ├── user_app/
│   │   ├── lib/ui/features/auth/login_page.dart   # 用户端登录校验与交互
│   │   └── test/ui/login_page_test.dart           # 用户端登录组件回归测试
│   └── service_app/
│       ├── lib/ui/features/auth/login_page.dart   # 工作人员端登录校验与交互
│       └── test/ui/login_page_test.dart           # 工作人员端登录组件回归测试
└── docs/
    ├── 03-用户端App需求.md                         # 用户端登录验收口径
    ├── 04-服务端App需求.md                         # 工作人员端登录验收口径
    └── 操作日志_移动端登录密码必填校验_20260904.md  # 本次实施与验证记录

3. 核心文件说明

用户端登录页

• _login 同时校验手机号格式和密码是否为空；任一字段无效时立即返回，不调用 UserSession.login。
• 手机号和密码各自维护字段错误，允许同时展示，并聚焦第一个无效字段。
• 修改任一登录凭据会清除旧的接口级错误；修改对应字段会清除该字段错误。
• 密码框回车和“安全登录”按钮共用 _login，密码内容不做裁剪或长度变换。

工作人员端登录页

• 与用户端采用相同的校验、清错和聚焦规则。
• 密码框新增回车提交，并与“进入工作台”按钮共用 _login。
• 继续调用既有 StaffSession.login，不改变会话及接口协议。

登录页组件测试

• 使用记录型会话替身统计登录调用，证明空密码时调用次数为零。
• 覆盖双字段错误、合法手机号配空密码、首个错误字段聚焦、对应错误清除、回车提交及密码原样传递。

4. 变更记录

v1.0（2026-09-04）

• 两个 App 新增密码必填字段错误“请输入密码”。
• 两个 App 统一双字段校验、首错聚焦和凭据编辑清错行为。
• 工作人员端补齐密码框回车登录。
• 新增两端登录页回归测试，不改变后端登录错误码和既有会话接口。

5. 维护指南

• 后续新增登录入口时，应复用同一提交函数，禁止绕过字段校验直接调用会话登录方法。
• 登录密码是精确凭据，不应使用 trim、大小写转换或注册阶段的最短长度规则处理。
• 若未来支持验证码登录，应按登录模式分别校验密码或验证码，避免把两种凭据同时设为必填。
• 修改交互后至少运行两端 flutter analyze --no-pub、登录页定向测试和完整测试。

6. 已知边界

• 本次仅在客户端阻止空密码请求，后端仍维持现有统一认证失败语义。
• 本次不修改手机号规则、密码注册规则、忘记密码流程或验证码登录能力。
• 非空但错误的密码仍由后端统一返回认证失败，客户端不会推断账户是否存在。