文档:认证失败载体类改名 ClientAuthErrorWrapper

- ADR、README、技术方案、决策记录与排障记忆统一新类名
- auth_session.rs 注释同步
This commit is contained in:
2026-10-02 01:40:14 +08:00
parent 45774f1c02
commit 2a51f0b98c
7 changed files with 14 additions and 14 deletions
@@ -52,7 +52,7 @@ DirectProject 已经解决过同一类问题([`【ADR】DirectProject命令接
- **预期业务拒绝**(用户输入、前置条件、预期 4xx):由调用方消化并给用户反馈,**永不进池**。
- **真故障**(网络不可达、5xx、写盘/运行时安装失败、agent 终态失败):由调用方带上文交给错误池
(`ClientActionError` + `captureClientError`);`window.onerror` / `unhandledrejection` 只兜底
(`ClientAuthErrorWrapper` + `captureClientError`);`window.onerror` / `unhandledrejection` 只兜底
没人接手的错误。Rust 侧 agent 终态失败仍由失败投影入池。
- **WebView 全局 handler 是兜底**:任何没人 catch 的错误都进池。
- **408/5xx/网络的判定由调用方在 catch 里做**:AGC shell 的 WebView 侧没有 fetch 边界的自动判定
@@ -63,12 +63,12 @@ DirectProject 已经解决过同一类问题([`【ADR】DirectProject命令接
- 本节原先的"调用方用 `isClientAuthError` 读形状、`switch (error.type)` 分流、`default` 交池"已被
[`【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01`](./【ADR】AGC认证失败的JS侧载体与抛出时机-2026-10-01.md)
取代:`invokeClientAuth` 把结构化拒绝装进 `ClientActionError`(`cause` 是判别联合),判定只写在
取代:`invokeClientAuth` 把结构化拒绝装进 `ClientAuthErrorWrapper`(`cause` 是判别联合),判定只写在
catch 子句里,每个 `case` 用 `as` 取具名载荷类型。
- "未识别变体上调是**故意**的"不再成立:`default` 改为 `expectNever(error.payload)`,漏接变体是
**编译错误**,不再是运行时报进池。
- 系统变体与非结构化拒绝仍由调用方原样 `throw`,经全局 `unhandledrejection` 入池;
`captureClientError` 的 `instanceof ClientActionError` 解包保持不变。
`captureClientError` 的 `instanceof ClientAuthErrorWrapper` 解包保持不变。
- 删除 `shouldCaptureClientError`:不再存在"叶子自己判定要不要报"的口径。
### 4. 报告面板与通知行为不变
@@ -28,7 +28,7 @@ ts-rs 已经把 `ClientAuthError` 生成成判别联合(`src/services/generate
`payload` / `cause` 的一层别名,给同一个事实源挂第二个名字。
原始拒绝值是普通对象,直接 `throw` 会被上报链路降级成 `String(obj)`;所以包装层把它装进
**已有**的 `ClientActionError`,载体只持有一个 `ClientAuthError` 类型的 `error` 字段,值就是原始拒绝值(也就是那个
**已有**的 `ClientAuthErrorWrapper`,载体只持有一个 `ClientAuthError` 类型的 `error` 字段,值就是原始拒绝值(也就是那个
判别联合)。它**不读、不产任何派生值**:不读变体上的 `message`(变体不保证都有这个字段),
不塞 `context`,`Error.message` 留空。上报的 `source` / `action` 由调用 `captureClientError`
时的显式入参决定;catch 里 `error.error as ClientAuthError` 直接分流。
@@ -49,7 +49,7 @@ async function invokeClientAuth<T>(command, args): Promise<T> {
return await invoke(command, args);
} catch (error) {
// 原样把 Rust 的拒绝装成 JS Error;不读字段、不加字段。
throw new ClientActionError(error);
throw new ClientAuthErrorWrapper(error);
}
}
```
@@ -68,7 +68,7 @@ async function invokeClientAuth<T>(command, args): Promise<T> {
```ts
catch (error) {
if (!(error instanceof ClientActionError)) throw error; // 超时 / 桥未装等我们自己的错误
if (!(error instanceof ClientAuthErrorWrapper)) throw error; // 超时 / 桥未装等我们自己的错误
const failure = error.error as ClientAuthError;
switch (failure.type) {
case 'phoneNumberInvalid': {
@@ -106,7 +106,7 @@ catch (error) {
`failed` 状态(`authoritative` 只在"未登录"上为 true,`failed` 恒为 false,删除它不丢信息)。
- `ClientAuthState` 收敛为 `authenticated | unauthenticated`:读状态失败就是命令失败,由
`invokeClientAuth` 装进 `ClientActionError`(`error` 是判别联合),不再有第三种
`invokeClientAuth` 装进 `ClientAuthErrorWrapper`(`error` 是判别联合),不再有第三种
"unavailable 投影"。
- `ClientAuthRefreshResult` 收敛为 `refreshed | unauthenticated | stale`。