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

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

操作前状态

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

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

具体操作

在两个 App 的 ApiClient 中增加稳定错误码到中文提示的统一映射，覆盖当前 BSM SDK 的请求、业务、令牌、基础设施和标准状态错误码。
保留服务端返回的中文业务提示；无法识别的纯英文消息统一显示“操作失败，请稍后重试”。
将网络连接异常和无效 JSON 响应转换为明确中文提示。
在两个登录页提交前校验纯 11 位中国大陆手机号，格式错误时在手机号输入框下显示“请输入正确的11位手机号”。按已确认方案，不增加 +86 自动转换或兼容。
登录接口返回密码错误码 1108 时统一提示“手机号或密码错误”，避免泄露账号是否存在。
补充 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 新增错误码时需要同步补充两端映射及测试。
本次不修改认证逻辑、令牌、服务端错误码或数据库，影响仅限客户端输入校验和错误展示。

4.5 KiB Raw Permalink Blame History Unescape Escape