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

## 1. 项目概述

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

## 2. 目录结构说明

```text
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. 已知边界

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