# 移动端错误提示中文化操作日志

操作时间：2026-09-02 20:56:00
操作类型：修改、扩展
影响模块：用户端 App、工作人员端 App、移动端需求文档

## 操作前状态

用户端和工作人员端的 HTTP 客户端会直接展示服务端 `message`。当接口返回 `Invalid Argument`、`Password Incorrect` 等 SDK 英文错误时，页面直接向用户暴露英文技术信息。登录页未在本地校验后端要求的纯 11 位中国大陆手机号，输入带 `+86` 的号码后只能得到服务端通用参数错误。

工作区原有 `apps/service_app/pubspec.lock` 修改，本次未覆盖或调整。

## 具体操作

1. 在两个 App 的 `ApiClient` 中增加稳定错误码到中文提示的统一映射，覆盖当前 BSM SDK 的请求、业务、令牌、基础设施和标准状态错误码。
2. 保留服务端返回的中文业务提示；无法识别的纯英文消息统一显示“操作失败，请稍后重试”。
3. 将网络连接异常和无效 JSON 响应转换为明确中文提示。
4. 在两个登录页提交前校验纯 11 位中国大陆手机号，格式错误时在手机号输入框下显示“请输入正确的11位手机号”。按已确认方案，不增加 `+86` 自动转换或兼容。
5. 登录接口返回密码错误码 `1108` 时统一提示“手机号或密码错误”，避免泄露账号是否存在。
6. 补充 Widget 与错误映射回归测试，并同步两类 App 的错误处理需求。

## 操作后状态

- `Invalid Argument` 不再直接显示；登录页会在请求前给出手机号中文格式提示。
- 两个 App 的已知接口错误按稳定错误码展示中文。
- 未知英文接口消息不再透传到界面。
- 后端路由、请求体、响应结构和错误码保持不变，公共接口兼容。

## 代码变更

- `apps/user_app/lib/data/services/api_client.dart`
  - `localizeApiErrorMessage`：新增错误码中文映射和未知英文兜底。
  - `ApiClient._sendRequest`、`ApiClient._decode`：统一处理网络异常、响应解析和中文错误。
- `apps/user_app/lib/ui/features/auth/login_page.dart`
  - `_LoginPageState._login`：新增手机号校验和登录密码错误专用提示。
  - 手机号输入框：新增字段级错误展示与输入后清除行为。
- `apps/service_app/lib/data/services/api_client.dart`
  - 与用户端保持一致的错误码中文映射和请求异常处理。
- `apps/service_app/lib/ui/features/auth/login_page.dart`
  - 与用户端保持一致的手机号校验和登录错误提示。
- `apps/user_app/test/ui/login_page_test.dart`
  - 新增手机号格式错误和接口错误中文化测试。
- `apps/service_app/test/ui/login_page_test.dart`
  - 新增手机号格式错误和接口错误中文化测试。
- `docs/03-用户端App需求.md`、`docs/04-服务端App需求.md`
  - 补充移动端接口错误中文化和登录手机号校验要求。

## 行为变化

| 场景 | 修改前 | 修改后 |
| --- | --- | --- |
| 登录手机号带 `+86` | 服务端返回并展示 `Invalid Argument` | 输入框提示“请输入正确的11位手机号”，不发起请求 |
| 密码错误 | 展示 `Password Incorrect` | 展示“手机号或密码错误” |
| 已知 SDK 接口错误 | 可能展示英文原文 | 按稳定错误码展示中文 |
| 未知纯英文错误 | 直接展示英文原文 | 展示“操作失败，请稍后重试” |
| 中文业务错误 | 直接展示中文原文 | 保持中文原文 |

## 验证结果

- `apps/user_app` 执行 `flutter analyze`：通过，无问题。
- `apps/user_app` 执行 `flutter test`：4 个测试全部通过。
- `apps/service_app` 执行 `flutter analyze`：通过，无问题。
- `apps/service_app` 执行 `flutter test`：5 个测试全部通过。
- 执行 `git diff --check`：未发现空白符错误；仅提示仓库现有的 LF/CRLF 转换规则。
- 边界测试覆盖：带 `+86` 的手机号、参数错误码、密码错误码、未知中文业务消息和未知英文消息。

## 风险评估

- 当前手机号规则与后端保持一致，仅接受纯 11 位号码；系统自动填充带 `+86` 时仍需用户手动修改，这是已确认的产品选择。
- 未知英文消息会被安全兜底文案替代，客户端界面不再包含原始诊断信息；排障应依赖稳定错误码和服务端日志。
- 两个 App 目前各自维护同一份映射；后端 SDK 新增错误码时需要同步补充两端映射及测试。
- 本次不修改认证逻辑、令牌、服务端错误码或数据库，影响仅限客户端输入校验和错误展示。