From f8c32e6346b138eab7eafac5f74063373f35fd29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Fri, 2 Oct 2026 11:50:34 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E7=99=BB=E5=BD=95?= =?UTF-8?q?=E8=B7=AF=E7=94=B1429=E5=BD=92=E4=B8=9A=E5=8A=A1=E5=8F=98?= =?UTF-8?q?=E4=BD=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 命令错误结构化 ADR 补 429 按路由判定的口径：发码是频控、登录是验证码次数耗尽、其余才落未识别拒绝 - 决策记录同步追加 2026-10-02 的 429 归类 --- docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md | 3 +++ docs/project-memory/shared-memory/decision-log.md | 1 + 2 files changed, 4 insertions(+) diff --git a/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md b/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md index a6de13786..261fc15e1 100644 --- a/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md +++ b/docs/adr/【ADR】AGC命令错误结构化与错误报告口径-2026-10-01.md @@ -53,6 +53,9 @@ DirectProject 已经解决过同一类问题（[`【ADR】DirectProject命令接 - 变体按**可判定的事实**命名。服务端 400 只提供 `status + message`（`AppError.code` 仍是通用 `BAD_REQUEST`），所以 400 变体按"哪条请求的输入被拒"命名（如 `passwordLoginRejected`）， 不假装能区分密码长度/手机号格式；**任何地方都不允许对错误文案做判断**。 +- `429` 同样按路由判定：发码路由是频控（`smsCodeThrottled`），登录路由是「验证码错误次数过多」 + （复用 `phoneCodeLoginRejected`，仍是用户可修正的输入问题、不进池），其余路由的 `429` 才落到 + `unexpectedRejection`。 - 本地前置校验只做布尔判定、拿不到更细事实时不编字段：手机号校验 `phone_is_valid` 只回 true/false， 所以 `phoneNumberInvalid` 保持无字段，提示由调用方给固定文案；编不出事实的"细分原因"不硬造。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index bc5dcbcde..4c4825cc7 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -11,6 +11,7 @@ - 决策（2026-10-01，JS 侧载体与抛出时机）：认证命令统一经 `invokeClientAuth(command, args)` 调用；拒绝值原样装进已有的 `ClientAuthErrorWrapper`（载体只有一个 `ClientAuthError` 类型的 `error` 字段，值就是 ts-rs 生成的判别联合；不读变体字段、不塞 `context`，构造时把整份载荷 `JSON.stringify` 进 `Error.message`，上报事件因此拿到机器事实），**不新增手写错误类**（`ClientAuthFailure` 已删除），形状完全信任 tauri + ts-rs 映射、不做运行时嗅探。形状读取 / 文案回落 / 提示分类三层（`isClientAuthError`、`getClientAuthErrorMessage`、`presentAuthFailure`）全部删除。 - 决策（2026-10-01，判定位置与出口）：要不要上报只由 catch 子句里的 `switch (failure.type)` 判，`failure = error.error`；无字段业务 / 会话变体用本 catch 的固定文案，带载荷变体先 `as` 取自己的具名类型、再用它自己的 `reason` / `serverMessage` / `status` / `detail` 拼上本次操作的上下文前缀（`reason` 是枚举时再 `switch (payload.reason)`）；Rust 不预拼用户可见文案、服务端原文缺失就是 `null`（无兜底文案）。系统变体原样 `throw` 经全局 `unhandledrejection` 入池（`captureClientError` 用 `instanceof` 解包 `error` 字段取原始错误），`default: expectNever(failure)` 让漏接变体编译失败。取代"未识别变体上调是故意的"。 - 决策（2026-10-01，Rust 侧不再降级）：`refresh_session_inner` 的非权威失败直接 `Err(ClientAuthError)`，`ClientAuthStateView` / `ClientAuthRefreshView` 删除 `errorMessage`，续期结果删除 `failed`；`ClientAuthState` 收敛为 `authenticated | unauthenticated`，`ClientAuthRefreshResult` 收敛为 `refreshed | unauthenticated | stale`。 +- 追加（2026-10-02，429 按路由判定）：`/api/auth/phone/login` 验证码错误次数耗尽返回的 429 是用户可修正的输入问题，映射为 `phoneCodeLoginRejected`（复用现有业务变体、不进错误池）；发码路由仍是 `smsCodeThrottled`，其余路由的 429 仍是 `unexpectedRejection`。 - 影响范围（2026-10-01 第二轮）：`apps/ai-game-creator-shell/src/services/{clientAuth.ts,platformSession.ts}`（`clientAuthError.ts` 删除）、`apps/ai-game-creator-shell/src/app/AuthenticatedClient.tsx`、`apps/ai-game-creator-shell/src-tauri/src/auth_session.rs`、对应 vitest 用例。 ## 2026-10-01 DirectProject 审批拒绝原因留痕