docs(tds): 补齐 P4 出向通道的契约文档与项目指引

影响:
- `docs/TDC-TDS-CONTRACT.md` 由「P4 的输入清单」改写为「已落地契约」:
  只走 internal 通道、6 个固定出向头、10 个对外端点 → 出向 TDS 端点映射、
  降级三档、7 条刻意分歧、真 TDS 实测记录。
- `README.md` / `CLAUDE.md` 补上 10 个出向端点、两个环境变量、TDS 通道小节与踩坑行。

改动:
- 契约文档重写:新增「返回风格两套」「身份解析两套口径」「降级三档」三节,
  补录本仓 10 个端点与 TDS 侧 11 条原始返回的实测表。
- README:后端 API 表增 7 行、环境变量表增 `SSW_TDS_BASE_URL` /
  `SSW_TDS_INTERNAL_TOKEN`(令牌值只指向 `src/config.rs`,不入文档)。
- CLAUDE.md:目录树、红线、API 表、关键实现细节 13–14、TDS 出向通道小节、
  踩坑表 6 行、范围外声明同步。
- 计划文件:修正「12 条用例」为实际的 4 条用例(219 = 207 + 8 + 4),
  并记录实施后与上游的三处差异(空体可选、connectorId 取值宽松、query 传参)。
- 工作日志追加 P4 小节:4 个 commit、5 个变异自证表、真 TDS 实跑结果、3 个遗留项。

设计:
- 不改 `static/`:上游 SPA 的 serviceCatalog / billing 两个 api 对象要的正是
  这 10 个路径,后端补齐即可 ⇒ 前端一个字不动。
- 遗留 R10(`GET /api/ssw/tdc/Identity` 泄漏 `secretKey`,上游是 `@JsonIgnore`)
  与 R11(13 个文件的 rustfmt 漂移)本轮不修,超出 P4 范围,已登记。

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-25 14:24:54 +08:00
1 parent b82c71a1e9
commit 52074a136d
5 files changed
+332 -65

No files matched your search

+59
View File
@@ -25,3 +25,62 @@ antd 抽屉的 motion 卡在 `enter-start`(停在屏幕外),表现为「
**本轮改动**:`docs/CONSOLE-ACCEPTANCE.md`(新)、`README.md`(目录树 + 控制台小节 +
「不在 MVP 内」补 TDS 代理页)、本日志、SDD 台账追加。
---
## P4 TDS 出向客户端(照抄上游 internal 通道)
**范围**:spec `docs/superpowers/specs/2026-10-25-tdc-rs-p4-tds-outbound-design.md`
→ plan `docs/superpowers/plans/2026-10-25-tdc-rs-p4-tds-outbound.md`(8 个 Task)。
用户明确:**「严格按新版 tdc 实现,不用创新」** + **「照抄上游宽松身份 + 令牌有默认值」**。
**做了什么**(4 个 commit):
- `03e9f05` `src/tds/mod.rs` —— 出向客户端(上游 `TdsReportClient` 的 internal 通道,9 个方法)。
固定 6 个头、超时 3s/5s、`no_proxy()`、路径段白名单、**解包型 / 整包型**两种返回风格。
- `a2c0213` `src/routes/tds_biz.rs` —— 10 个对外端点(服务目录 3 + 账单 7),
身份解析**两套口径**(宽松 5 个 / 严格 2 个,照抄)、`owns_ledger` 越权自检 fail-closed、
`LocalCompare` 读本地表零出向。
- `d3d609f` `tests/tds_biz.rs` —— 假 TDS + **4 条**集成测试(真 PGlite、127.0.0.1 假 TDS)。
- `b82c71a` —— 补一条「解包型端点的 TDS 业务失败」断言(让变异③a 变成 load-bearing)。
**关键决定**:
1. **测试条数算平**:约束写「新增正好 12 条」⇒ 219,但 Task 1–3 已加 8 条(配置/客户端单测)
⇒ Task 5 只加 **4 个 `#[tokio::test]`**(219 = 207 + 8 + 4)。**函数数 ≠ 断言数**。
2. **不变 `static/`**:上游 SPA 里 `W = "/api/ssw/tdc"`,`serviceCatalog` / `billing` 两个
api 对象要的正是这 10 个路径 ⇒ 后端补齐即可,前端**一个字都不改**。
3. **对外 PUT / 出向 POST**:`Receipt` 上游 TDC 控制器对外是 `PUT`,TDS 侧是 `POST` ⇒ 两边都对。
4. **不派子代理**:用户此前主动杀过 R4 子代理 ⇒ 全部主会话内联执行。
**变异自证**(5 个变异,每个恰好打红一条,验完用 `cp` 还原 + `shasum` 核对,
**没用** `git checkout` / `stash` / `reset`):
| 变异 | 打红的那条 |
|---|---|
| ① 出向头多带 `Authorization` | ① 六个固定头 + 不夹带会话令牌 |
| ② `is_safe_path_segment` 放宽 | ③ 路径段白名单 |
| ③a 解包型 `unwrap_data` 改成不看 `code` | ① TDS 业务失败当成功 |
| ③b 整包型 `unwrap_envelope` 改成不看 `code` | ③ 整包型业务失败 |
| ④ `owns_ledger` 改成 fail-open | ③ 越权自检 |
**真 TDS 实跑**(TDS `:30041`,库 `tds2`,**没重启它**;本仓 `:30410`):
- 本仓 10 个端点逐条打 ⇒ 全部 **HTTP 200**(业务失败也是 200)⇒ 判成败必须读 body 的 `code`。
- 直打 TDS 录了 11 条**原始**返回(其中「不带令牌 ⇒ 缺少有效凭证」证明令牌真的生效)。
- ⚠️ 调试 TDS 里**没有本连接器的账本行** ⇒ 5 个账单动作端点的**成功路径对不上真 TDS**
(TDS 只会回「台账不存在」)⇒ 成功路径由假 TDS 覆盖。
- 浏览器复验:R3 时代 404 的两个页(`/tdc/service-catalog`、`/tdc/billing`)**现在 200**,
页面渲染出表格壳;「No data」是演示 TDS 没数据,**不是本仓的锅**。
**遗留项(未修,已登记)**:
1. 🔴 **`GET /api/ssw/tdc/Identity` 会把 `secretKey` 吐出去** —— `crud.rs` 的 list/detail 是
`SELECT *` ⇒ `f_secret_key` 原样进 JSON。**上游是 `@JsonIgnore`**(`IdentityEntity` 上明写
「防 CRUD list/detail 泄露」)⇒ 本仓这条**既违反项目红线,也与上游不一致**。
本轮范围是 P4,未擅自改 ⇒ 留作下一轮的独立小修。
2. **仓库级 rustfmt 漂移 13 个文件**(`account.rs` / `auth.rs` / `codec.rs` / `crud.rs` / `db.rs` /
`domain/identity.rs` / `envelope.rs` / `ids.rs` / `protocol.rs` / `registry.rs` /
`routes/health.rs` / `session.rs` / `tests/account_api.rs`)—— **本轮动的文件全部干净**。
3. `tds-stub/server.js` 还是旧 Bridge 通道的桩,与新 internal 通道已不对应(未用)。
+51 -6
View File
@@ -33,7 +33,7 @@ tdc-rs/
├── src/
│ ├── main.rs # 启动装配(199 行):PGlite open / 引导身份 / 账号库 / 路由 / 中间件 / 静态兜底
│ ├── lib.rs # 模块声明(业务逻辑都在 lib 里,bin 只做装配)
│ ├── state.rs # AppState(config + db + db_lock + sessions + accounts + bootstrap)
│ ├── state.rs # AppState(config + db + db_lock + sessions + accounts + bootstrap + tds)
│ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal)
│ ├── session.rs # 会话存储(两种 kind:Identity / Account)
│ ├── protocol.rs # 协议版本闸门
@@ -45,13 +45,14 @@ tdc-rs/
│ ├── account.rs # 本地账号库(JSON 文件 + Mutex)
│ ├── cipher.rs # 登录口令加解密(MD5 + AES-256-ECB,对齐上游 cipher.ts)
│ ├── config.rs # 环境变量配置 + 密钥守卫
│ ├── tds/mod.rs # TDS 出向客户端(照抄上游 TdsReportClient 的 internal 通道,9 个方法)
│ ├── domain/identity.rs # 身份引导 / Auth 端点 / 能力集
│ └── routes/ # 按域装配:health / auth / account / crud / body / mw / fallback
│ └── routes/ # 按域装配:health / auth / account / crud / tds_biz / body / mw / fallback
├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/,8 个产物文件)
├── schema/
│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制,**30 表**,**不在 web root**)
├── scripts/ # build-frontend.sh / gen-migrate.sh / reset-data.sh
├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail)
├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail / tds_biz)
├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md)
├── tds-stub/server.js # TDS 契约桩(零依赖,仅供端到端调试)
└── data/ # 运行期数据(tdc.pg/ + accounts.json,已 gitignore)
@@ -71,8 +72,13 @@ tdc-rs/
- 🔴 **私钥不得外泄。** 身份私钥只落盘 `data/`;API 一律返回去敏后的公开视图
(**不要**用 `#[serde(skip_serializing)]` —— 会让落盘 JSON 缺字段、回读失败)。
- 🔴 **口令不得外泄。** 账号库只存 `md5(明文)`;对外响应**手工挑字段**(`account_view`),不得把 `Account` 整个塞出去。
- 🔴 **TDC ↔ TDS 尚未对接**(P4 才有出向客户端)。旧版的 `/api/ssw/tdc/tds/*` 代理网关**已下线**(⇒ 404);
契约清单见 `docs/TDC-TDS-CONTRACT.md`(那是 **P4 的输入**,不是本仓现状)。
- 🔴 **TDC ↔ TDS 已对接(P4)**,但**只走 internal 通道**(≡ 上游 `TdsReportClient`):
出向**固定 6 个头**(`Content-Type` / `App-Code: sswflow` / `Jnpf-Origin: pc` / `Vue-Version: 3` /
`X-Internal-Token` / `X-Protocol-Version: 1.0`)⇒ **绝不**带 `Authorization` / cookie / 本地会话令牌。
旧版的 `/api/ssw/tdc/tds/*` 代理网关**已下线**(⇒ 404,别再复活)。
出向 URL **只由固定路径模板拼出**(路径段过白名单:ASCII 字母/数字/下划线/短横线,1..=64)⇒ 用户输入绝不直接进 URL。
出向失败**三档降级**:NOOP(未配 `SSW_TDS_BASE_URL`)/ 不可达 / TDS 业务失败(HTTP 200 + `code != 200`)——
**都不许变成 HTTP 500、不许 panic**。契约与实测表见 `docs/TDC-TDS-CONTRACT.md`。
## 命令速查
@@ -115,6 +121,15 @@ curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \
| GET | `/api/ssw/tdc/{Entity}/All` | 不分页全量 |
| GET / PUT / DELETE | `/api/ssw/tdc/{Entity}/{id}` | 详情 / 修改 / 逻辑删除 |
| GET | `/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` | 资源 / 数据集聚合详情 |
| GET | `/api/ssw/tdc/ServiceCatalog` | **服务目录**(出向 TDS `Catalog/Internal/Catalog`) |
| POST | `/api/ssw/tdc/ServiceCatalog/Buy`、`/api/ssw/tdc/ServiceCatalog/BuyBatch` | **目录下单**(出向 TDS `TradeOrder/Internal/Apply` / `ApplyBatch`) |
| GET | `/api/ssw/tdc/Billing/List` | **本方账单列表**(出向 TDS `BillingLedger/Internal/List`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Dispute`、`/Confirm`、`/Settle`、`/Receipt` | **账单动作**(出向 TDS `BillingLedger/{id}/*`;带越权自检) |
| GET | `/api/ssw/tdc/Billing/{id}/Voucher` | **对账凭证**(出向 TDS `BillingLedger/{id}/Voucher`) |
| GET | `/api/ssw/tdc/Billing/LocalCompare?contractId=` | **本地计量比对**(读本地 `tdc_api_consume_log`,**零出向**) |
> 🔴 最后 7 行 = **P4 TDS 出向通道**(照抄上游新版 TDC 的 `ServiceCatalogController` + `BillingController`)。
> 完整契约(出向路径 / 6 个固定头 / 降级三档 / 刻意分歧 / 实测表)见 `docs/TDC-TDS-CONTRACT.md`。
`{Entity}` 的 18 个全名:
@@ -171,6 +186,10 @@ curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \
10. **schema 初始化**:启动时探测 `tdc_identity` 是否存在,不存在才按 `;` 拆分执行 `migrate.sql`。
11. **`ecb` 0.1 只实现 `*_block_mut`**(原地改块)⇒ 用 `encrypt_block_mut` / `decrypt_block_mut`,**不是** `encrypt_block`。
12. **同一文件的多个 Edit 必须串行**(并行 Edit 会 last-writer-wins 静默覆盖)。
13. **出向 TDS 判定成功必须看 `body.code == 200`**(TDS 业务失败也是 HTTP 200)。
解包型端点用 `tds::unwrap_data`、整包型用 `tds_biz::unwrap_envelope` —— **别混用**。
14. **出向请求只带 6 个应用层头**(`src/tds/mod.rs` 的 `internal_headers()`);
`reqwest` 会自己加 `host` / `content-length` / `accept` ⇒ 断言「头数」时别把这三个算进去。
## 数据模型
@@ -210,6 +229,25 @@ curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \
- `src/routes/account.rs`:登录 + 用户管理 6 端点 + 管理员闸门 `require_admin`
(连接器身份会话 / 管理员账号放行;**内部令牌刻意 403**,比上游严一档;查不到账号 ⇒ fail-closed 403)。
## TDS 出向通道(P4)
- `src/tds/mod.rs`:**出向客户端**,照抄上游 `TdsReportClient` 的 internal 通道(9 个方法)。
- 出向头**正好 6 个**(`internal_headers()`),**绝不**带 `Authorization` / cookie。
- 超时 3s 连 / 5s 读;`.no_proxy()` 绕开系统代理。
- 路径段白名单 `is_safe_path_segment`(ASCII 字母/数字/下划线/短横线,1..=64)。
- **两种返回风格别混**:**解包型**(`internal_catalog` / `internal_apply` / `internal_apply_batch`
⇒ `data` 或 `Err(msg)`)/**整包型**(`list_billing_for_connector` / `dispute` / `confirm` /
`settle` / `receipt` / `voucher` ⇒ 原始 `{code,msg,data}`)。
⚠️ 整包型**成功**时 `data` 是**字符串**(账本 id),不是对象。
- `src/routes/tds_biz.rs`:**10 个对外端点**(服务目录 3 + 账单 7),照抄上游
`ServiceCatalogController` + `BillingController`。
- 身份解析**两套口径**:宽松(List/Dispute/Receipt/Voucher/LocalCompare)/
严格(Confirm/Settle)—— 照抄上游,不统一。
- 越权自检 `owns_ledger`(先 `BillingLedger/Internal/List` 查本方账本)⇒ **fail-closed**。
- `LocalCompare` 读**本地** `tdc_api_consume_log`,**零出向**。
- 完整契约(出向路径表 / 6 个头 / 降级三档 / 7 条刻意分歧 / 真 TDS 实测表)见
**`docs/TDC-TDS-CONTRACT.md`**。
## 编译缓存(dev-cache-layout 规范)
本机已统一,**无需在项目内做任何配置**:
@@ -245,6 +283,12 @@ curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \
| 并行测试互相撞车 | `tdc_identity` 有唯一约束 / 账号库是持久文件 | 每个用例用**唯一**身份码 + **独立**账号文件 |
| release 首次编译慢 | 全依赖需重编 | 走 sccache |
| 自动化里 antd 抽屉停在屏幕外、点不到「保存」 | 内核浏览器在**后台标签** ⇒ `visibilityState=hidden` ⇒ rAF + CSS transition 全冻结 | 注入 `*{transition:none !important}` + 摘掉卡住的 motion 类(**测试环境假象,非产品缺陷**,见 `docs/CONSOLE-ACCEPTANCE.md` §5) |
| 出向 TDS 得 502 / 连接超时 | `reqwest` 读了**系统代理**(`HTTP_PROXY` / macOS 网络设置)⇒ loopback 被劫持 | `ClientBuilder::no_proxy()`(TDS 是**内网直连**服务) |
| 出向 TDS 拿到 200 却当成功 | TDS 业务失败也走 **HTTP 200 + `code != 200`** | 判 `body.code == 200`(解包型)/ `unwrap_envelope`(整包型) |
| 出向头被算成 8 个 | `reqwest` 会**自己加** `host` / `content-length` / `accept` | 应用层只断言自己那 6 个(传输层头不在管辖范围) |
| `Billing/{id}/Dispute` 等越权时仍看到出向请求 | `ownsLedger` 自检本身**就要**发一次 `BillingLedger/Internal/List` | 只断言**动作端点没被调用**,别断言「零出向」 |
| `ServiceCatalog/Buy` 空体报「请求体格式有误」 | 用了 `JsonBody`(空体 ⇒ 拒) | 这几个端点体**可空** ⇒ 用 `tds_biz::OptionalJsonBody`(空体当空对象) |
| 出向 URL 拼出注入 | 用户输入直接进 URL 路径 | 只用固定模板 + `tds::is_safe_path_segment` 校验过的段 |
## 明确不在本仓库范围
@@ -253,7 +297,8 @@ curl -s --noproxy '*' -X POST http://127.0.0.1:30000/api/oauth/Login \
- 原 `ssw-tdc` 的**隐私计算作业**——`NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask /
Notebook / VizChart / Quality* / HostingJob / DestroyLog` 等——依赖 **Nax 隐私计算引擎**与
**scard 安全平面(软 PKI + 软 TPM)**,本地不可行。需要这部分应保留原 Java/Scala 服务。
- **TDS 出向客户端**(`/api/ssw/tdc/tds/*` 代理 + 真实 TDS 联调)属 P4。
- **TDS 的 login / `ensureToken` 通道**(JNPF 登录换 token)**不做** —— P4 只实现 internal 通道。
- ~~`/api/ssw/tdc/tds/*` 代理网关~~ **已永久下线**(旧 Bridge 通道,⇒ 404)⇒ 别再复活。
- **JNPF 角色 / 菜单 / 授权模型**(j7 的 `base_role` / `base_module` 等)**不引入**
⇒ 本仓的权限判定走**声明式权限键**(`registry::PERMISSION_KEYS`),不走菜单。
+12
View File
@@ -91,6 +91,16 @@ sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCC
| GET | `/api/ssw/tdc/{Entity}/All` | 不分页全量 |
| GET / PUT / DELETE | `/api/ssw/tdc/{Entity}/{id}` | 详情 / 修改 / 逻辑删除 |
| GET | `/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` | 资源 / 数据集聚合详情 |
| GET | `/api/ssw/tdc/ServiceCatalog` | **服务目录**(出向 TDS `Catalog/Internal/Catalog`) |
| POST | `/api/ssw/tdc/ServiceCatalog/Buy`、`/api/ssw/tdc/ServiceCatalog/BuyBatch` | **目录下单**(出向 TDS `TradeOrder/Internal/Apply` / `ApplyBatch`) |
| GET | `/api/ssw/tdc/Billing/List` | **本方账单列表**(出向 TDS `BillingLedger/Internal/List`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Dispute`、`/Confirm`、`/Settle`、`/Receipt` | **账单动作**(出向 TDS `BillingLedger/{id}/*`;带越权自检) |
| GET | `/api/ssw/tdc/Billing/{id}/Voucher` | **对账凭证**(出向 TDS `BillingLedger/{id}/Voucher`) |
| GET | `/api/ssw/tdc/Billing/LocalCompare?contractId=` | **本地计量比对**(读本地 `tdc_api_consume_log`,**零出向**) |
> 🔴 上表最后 7 行 = **P4 TDS 出向通道**(照抄上游新版 TDC 的 `ServiceCatalogController` +
> `BillingController`)。完整契约(出向路径 / 6 个固定头 / 降级三档 / 刻意分歧 / 实测表)见
> **`docs/TDC-TDS-CONTRACT.md`**。
`{Entity}` 的 18 个全名:
@@ -134,6 +144,8 @@ sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCC
|---|---|---|
| `TDC_BOOTSTRAP_ADMIN_ACCOUNT` | 引导的管理员**账号名** | `admin` |
| `TDC_BOOTSTRAP_ADMIN_PASSWORD` | 引导的管理员**口令** | `admin`(公开默认值) |
| `SSW_TDS_BASE_URL` | **TDS 出向基地址**(P4);**留空 ⇒ NOOP 模式**(本地单机,不发任何出向请求) | 空(NOOP) |
| `SSW_TDS_INTERNAL_TOKEN` | 出向 `X-Internal-Token` 头的值(🔴 与**入向** `SSW_INTERNAL_TOKEN` **不同源**,方向相反别混用) | 见 `src/config.rs` 的 `DEFAULT_TDS_INTERNAL_TOKEN`(公开默认值) |
## 已实现范围
+183 -53
View File
@@ -1,13 +1,185 @@
# TDC ↔ TDS 跨方契约参考
# TDC ↔ TDS 跨方契约
> 🔴 **现状(P0+P1)**:本仓**没有** TDS 出向通道。
> 旧版的 `/api/ssw/tdc/tds/*` 代理网关**已随 Task 10 下线**(现在请求该路径 ⇒ **404**)。
> `SSW_TDS_BASE_URL` 目前只用于**健康检查回显**与「本地单机模式」的判定,不产生任何出向请求。
> 🔴 **现状(P4 已落地)**:本仓**有** TDS 出向通道,**只走 internal 通道**
> (≡ 上游 `TdsReportClient.internalHeaders()` / `internal*` / `*Billing`)。
> 旧版的 `/api/ssw/tdc/tds/*` 代理网关**已下线**(请求该路径 ⇒ **404**)。
>
> **本文现在的角色 = P4(TDS 出向客户端)的输入契约**,不是本仓现状的描述。
> 出向客户端落地时,本文列的路径/请求头/错误口径**逐条照抄**即可。
> **本轮范围**:照抄上游新版 TDC 的 `ServiceCatalogController` + `BillingController`
> (10 个端点),出向打到真 TDS 的 `*/Internal/*` 与 `BillingLedger/*` 端点。
> 上游还有一条 login/`ensureToken` 通道(JNPF 登录换 token)⇒ **本轮不做**。
>
> **上游真源**(只读):
> - `ssw-tdc-controller/.../ServiceCatalogController.java`、`.../BillingController.java`
> - `ssw-tdc-biz/.../client/TdsReportClient.java`
> - `ssw-tds-controller/.../{Catalog,TradeOrder,BillingLedger,Space}Controller.java`
## 原 Java 侧结构
---
## 1. 通道:只走 internal
| 通道 | 上游入口 | 本仓 | 说明 |
|---|---|---|---|
| **internal** | `TdsReportClient`(`X-Internal-Token` + 固定头) | ✅ **本轮实现** | TDS `white-url` 放行的内部端点 |
| login / `ensureToken` | `TdsReportClient.ensureToken`(JNPF 登录换 token) | ❌ 不做 | 本轮不需要 |
| ~~Bridge/\*\*~~ | 旧 `HttpTdcTdsClient` 代理(`App-Code: tdc`) | ❌ **已下线** | 旧代理随 Task 10 撤除 ⇒ 404 |
**为什么 internal**:`App-Code: sswflow`(internal 通道的值)**≠** `App-Code: tdc`(Bridge 通道的值)。
上游新版 TDC 的服务目录 / 账单两页走的是 internal 通道 ⇒ 本仓照抄。
---
## 2. 出向请求头(**正好 6 个**,逐字照抄上游 `internalHeaders()`)
| 头 | 值 | 说明 |
|---|---|---|
| `Content-Type` | `application/json` | |
| `App-Code` | `sswflow` | 🔴 **不是** `tdc`(那是 Bridge 通道) |
| `Jnpf-Origin` | `pc` | |
| `Vue-Version` | `3` | |
| `X-Internal-Token` | `SSW_TDS_INTERNAL_TOKEN` | 有默认值(本地单机模式不出向时无所谓) |
| `X-Protocol-Version` | `1.0` | 与上游 `InternalTokenSupport.PROTOCOL_VERSION` 一致 |
- 🔴 **绝不**带 `Authorization` / `Cookie` ⇒ 本地会话令牌不外泄。
- 🔴 超时照抄上游 `restTemplate()`:**连接 3s / 读取 5s**(快速失败,别拖垮本地业务)。
- 🔴 `reqwest` 客户端必须 `.no_proxy()` ⇒ 本机 `HTTP_PROXY` / 系统代理会把 loopback 的 TDS 劫持成 502。
---
## 3. 本仓对外 10 个端点 → 出向 TDS 端点
> 路径与 HTTP 方法**逐字对齐上游前端**(上游 SPA 的 `W = "/api/ssw/tdc"`,
> `static/assets/tdc-*.js` 里 `serviceCatalog` / `billing` 两个 api 对象就是这 10 个调用)。
| 本仓端点 | 方法 | 出向 TDS 路径 | 方法 | 体 | 返回形状 |
|---|---|---|---|---|---|
| `/api/ssw/tdc/ServiceCatalog` | GET | `/api/ssw/tds/Catalog/Internal/Catalog` | POST | `{spaceId, keyword}` | 解包型 ⇒ `data`(`{list,total}`) |
| `/api/ssw/tdc/ServiceCatalog/Buy` | POST | `/api/ssw/tds/TradeOrder/Internal/Apply` | POST | 透传(补 `buyerConnectorId`) | 解包型 ⇒ `data` |
| `/api/ssw/tdc/ServiceCatalog/BuyBatch` | POST | `/api/ssw/tds/TradeOrder/Internal/ApplyBatch` | POST | 透传(补 `buyerConnectorId`) | 解包型 ⇒ `data` |
| `/api/ssw/tdc/Billing/List` | GET | `/api/ssw/tds/BillingLedger/Internal/List` | POST | `{connectorId[, keyword]}` | 整包型 ⇒ `data` |
| `/api/ssw/tdc/Billing/{id}/Dispute` | PUT | `/api/ssw/tds/BillingLedger/{id}/Dispute` | PUT | `{}` | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Confirm` | PUT | `/api/ssw/tds/BillingLedger/{id}/Confirm?connectorId=` | PUT | `{}` | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Settle` | PUT | `/api/ssw/tds/BillingLedger/{id}/Settle?connectorId=` | PUT | `{}` | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Receipt` | PUT | `/api/ssw/tds/BillingLedger/{id}/Receipt` | **POST** | `{receiptNo, remark}`(只挑这两个键) | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Voucher` | GET | `/api/ssw/tds/BillingLedger/{id}/Voucher` | GET | — | 整包型 ⇒ `data`(须是对象) |
| `/api/ssw/tdc/Billing/LocalCompare?contractId=` | GET | **不出向** | — | — | 本地表 `tdc_api_consume_log` |
- 🔴 **对外 PUT / 出向 POST**(`Receipt`):上游 TDC 控制器对外是 `PUT`,TDS 侧是 `POST` ⇒ 两边都要对。
- 🔴 **出向 URL 只由固定路径模板拼出**:路径段(账本 id)过白名单
(ASCII 字母/数字/下划线/短横线,1..=64)⇒ 用户输入绝不直接进 URL 路径。
- 🔴 `connectorId` 走**查询串**(不是头)⇒ 必须 URL 编码。
### 3.1 两种返回风格(照抄上游,别混)
| 风格 | 上游方法 | 语义 |
|---|---|---|
| **解包型** | `internalCatalog` / `internalApply` / `internalApplyBatch` | `code==200` ⇒ 取 `data`;否则 `Err(msg)` |
| **整包型** | `listBillingForConnector` / `dispute` / `confirm` / `settle` / `receipt` / `voucher` | 原样返回 `{code,msg,data}`,由上层判 `code` |
⚠️ 整包型的**成功**里 `data` 是**字符串**(账本 id),不是对象 —— 写测试/解析时别想当然。
### 3.2 身份解析:两套口径(照抄上游)
| 端点 | 口径 | 规则 |
|---|---|---|
| `Billing/List` / `Dispute` / `Receipt` / `Voucher` / `LocalCompare` | **宽松**(上游 `resolveConnectorId`) | 显式 `connectorId` 优先;为空取本端固定身份 |
| `Billing/{id}/Confirm` / `Settle` | **严格**(上游 `resolveOwnConnectorIdStrict`) | 只认本端身份;显式 id 与本端**不一致** ⇒ 拒 |
- **本端固定身份** = `tdc_identity` 里 `f_default_mark` 优先的那一行
(`f_tds_space_id` ⇒ 空间;`f_tds_connector_id` ⇒ 连接器)。
- **越权自检**(上游 `ownsLedger`):动作类端点先 `BillingLedger/Internal/List`(**不带 keyword**),
在 `data.list` 里找 id 匹配 ⇒ 不匹配 ⇒ 拒。**任何异常 ⇒ false(fail-closed)**。
⚠️ 这条自检本身**会发一次出向请求**(`List`)—— 断言「越权时不出向」时只能断言
**动作端点没被调用**,不能断言「一条出向都没有」。
---
## 4. 降级语义(三档,**都不许变成 HTTP 500 / panic**)
| 情形 | 表现 | 文案来源 |
|---|---|---|
| **NOOP**(未配 `SSW_TDS_BASE_URL`) | 本地单机模式,**不发任何网络请求** | 「未配置 TDS 地址(本地单机模式)」 |
| **不可达**(超时 / 网络错 / 响应不是 JSON) | 业务失败(HTTP 200 + `code:400`) | 上游原话「TDS …不可达」 |
| **TDS 业务失败**(HTTP 200 但 `code != 200`) | 业务失败(HTTP 200 + `code:400`) | TDS 的 `msg` 原文 |
- 🔴 **TDS 业务错误走 HTTP 200** ⇒ 判定成败**必须看 body 的 `code`**(只看 HTTP 状态会把失败误判成成功)。
- 🔴 本仓对外也是 **HTTP 200 + `{code,msg,data}`**(业务失败 = `code:400`,`data:null`)。
---
## 5. 已登记的刻意分歧(照抄上游时**故意**不同的地方)
| # | 分歧 | 上游 | 本仓 | 理由 |
|---|---|---|---|---|
| D1 | 宽松身份口径 | 既有端点(List/Dispute/Receipt/Voucher/LocalCompare)就是宽松的 | **照抄**(未加固) | 用户明确「照抄上游,不创新」 |
| D2 | 异常包装 | 抛异常 | `Result<T, String>` | Rust 侧表达;**语义逐条对齐** |
| D3 | `msg` 缺失时的文案 | `String.valueOf(res.get("msg"))` ⇒ 字面量 `"null"` | 空串兜底 | 上游那个 `"null"` 是 bug,前端会显示一个 "null" |
| D4 | 数字型 `connectorId` | 硬转 `(String)` ⇒ `ClassCastException`(500) | 宽松取文本,**不 500** | 上游自己注了这一点(2026-09-19 审查 P2-7) |
| D5 | 空请求体 | 上游 `@RequestBody` 必填 ⇒ 报错 | 动作类端点**接受空体**(当空对象) | 上游这几个端点体可空;`ServiceCatalog/Buy` 也是空体当空对象 |
| D6 | 分页 | 上游 standalone 分支不翻页 | `currentPage`/`pageSize` **忽略** | 上游 `internalCatalog` 无分页参数 |
| D7 | `Content-Type` 校验 | 上游 415 | 本仓不校验 ⇒ 报「请求体格式有误」 | 与本仓其它端点一致(`JsonBody` 口径) |
---
## 6. 实测记录(真 TDS,2026-10-25)
**环境**:TDS = `http://127.0.0.1:30041`(库 `tds2`,`java` PID 56575,**不重启**);
本仓连接器 = `:30410`(`SSW_TDS_BASE_URL=http://127.0.0.1:30041`)。
身份绑定:空间 `PORTAL-DEMO-SPACE`(门户演示空间)。
### 6.1 本仓 10 个端点(对外形状)
| # | 调用 | 本仓返回 |
|---|---|---|
| 1 | `GET /api/ssw/tdc/ServiceCatalog?keyword=` | `{"code":200,"msg":null,"data":{"list":[],"total":0}}` |
| 2 | `POST /api/ssw/tdc/ServiceCatalog/Buy` 体 `{"productId":"P-1"}` | `{"code":400,"msg":"数据产品不存在: null","data":null}` |
| 3 | `POST /api/ssw/tdc/ServiceCatalog/BuyBatch` 体 `{"productIds":["P-1","P-2"]}` | `{"code":400,"msg":"业务用途必填(平台运营据此审核)","data":null}` |
| 4 | `GET /api/ssw/tdc/Billing/List` | `{"code":200,"msg":null,"data":{"list":[]}}` |
| 5 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Dispute` | `{"code":400,"msg":"非本方账单,无权发起异议","data":null}` |
| 6 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Confirm` | `{"code":400,"msg":"非本方账单,无权确认","data":null}` |
| 7 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Settle` | `{"code":400,"msg":"非本方账单,无权结算","data":null}` |
| 8 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Receipt` | `{"code":400,"msg":"非本方账单,无权上传结算回执","data":null}` |
| 9 | `GET /api/ssw/tdc/Billing/{不存在的id}/Voucher` | `{"code":400,"msg":"非本方账单,无权下载对账凭证","data":null}` |
| 10 | `GET /api/ssw/tdc/Billing/LocalCompare?contractId=C-1` | `{"code":200,"msg":null,"data":{"contractId":"C-1","local":[]}}` |
> 全部 **HTTP 200**(业务失败也是 200)⇒ 判成败必须读 body 的 `code`。
> 5–9 是**本仓的越权闸门**先拒的(`ownsLedger` 查不到该账本)⇒ **动作请求根本没发出去**。
### 6.2 TDS 侧**原始**返回(直打 TDS,绕开本仓闸门)
| # | TDS 调用 | TDS 原始返回 |
|---|---|---|
| T1 | `GET /api/ssw/tds/Space/Internal/List` | `{"code":200,"msg":"Success","data":[{"id":"PORTAL-DEMO-SPACE",…,"name":"门户演示空间",…}]}` |
| T2 | `POST /api/ssw/tds/Catalog/Internal/Catalog` 体 `{"spaceId":"PORTAL-DEMO-SPACE","keyword":null}` | `{"code":200,"msg":"Success","data":{"list":[],"total":0}}` |
| T3 | `POST /api/ssw/tds/TradeOrder/Internal/Apply` 体 `{}` | `{"code":400,"msg":"数据产品不存在: null"}` |
| T4 | `POST /api/ssw/tds/TradeOrder/Internal/ApplyBatch` 体 `{}` | `{"code":400,"msg":"多方批次下单需至少勾选 2 个提供方资源(单标请走 /Internal/Apply)"}` |
| T5 | `POST /api/ssw/tds/BillingLedger/Internal/List` 体 `{"connectorId":"854250096668180741"}` | `{"code":200,"msg":"Success","data":{"list":[]}}` |
| T6 | `PUT /api/ssw/tds/BillingLedger/{不存在的id}/Dispute` | `{"code":400,"msg":"台账不存在"}` |
| T7 | `PUT /api/ssw/tds/BillingLedger/{不存在的id}/Confirm?connectorId=…` | `{"code":400,"msg":"台账不存在"}` |
| T8 | `PUT /api/ssw/tds/BillingLedger/{不存在的id}/Settle?connectorId=…` | `{"code":400,"msg":"台账不存在"}` |
| T9 | `POST /api/ssw/tds/BillingLedger/{不存在的id}/Receipt` | `{"code":400,"msg":"台账不存在"}` |
| T10 | `GET /api/ssw/tds/BillingLedger/{不存在的id}/Voucher` | `{"code":400,"msg":"台账不存在"}` |
| T11 | `GET /api/ssw/tds/Space/Internal/List`(**不带令牌**,对照组) | `{"code":400,"msg":"缺少有效凭证(需登录或内部凭证)"}` |
- T11 说明 **`X-Internal-Token` 真的生效**(缺了就 400)。
- ⚠️ **调试 TDS 里没有本连接器的账本行** ⇒ 5 个动作端点的**成功路径**无法对着真 TDS 走通
(TDS 侧只会回「台账不存在」)。成功路径由 `tests/tds_biz.rs` 的**假 TDS** 覆盖。
- T3/T4 的拒因**逐字**来自 TDS(`数据产品不存在: null` 里的 `null` 是 TDS 自己拼的,
本仓**原样透传**,没替它美化)。
### 6.3 浏览器级验收(上游控制台两个 TDS 页)
| 页面 | 页面发出的后端调用 | 结果 |
|---|---|---|
| `/tdc/service-catalog` | `GET /api/ssw/tdc/ServiceCatalog?currentPage=1&pageSize=20` | ✅ **200**(R3 时代是 404),页面渲染出表格壳 |
| `/tdc/billing` | `GET /api/ssw/tdc/Billing/List?currentPage=1&pageSize=10` | ✅ **200**(R3 时代是 404),页面渲染出账期/产品/合约编号/… 列 |
两页都是「No data」—— 演示 TDS 里没有产品 / 账本 ⇒ **不是**本仓的锅。
---
## 7. 旧 Bridge 通道(**历史,已下线**)
> 留档以便追溯,**本仓不再实现**。
| 文件 | 作用 |
|---|---|
@@ -16,9 +188,7 @@
| `NoopTdcTdsClient.java` | 降级实现(未配 base-url) |
| `TdcTdsClientConfig.java` | 装配(base-url / internal-token 注入) |
**核心原则**:所有调用**失败即降级**(catch 后返回空/默认值),绝不拖垮本地 TDC 业务。
## 契约清单(原注释逐条抄录)
旧契约清单(**全部 404**):
```
GET /api/ssw/tds/Bridge/Contract/{id} -> 合约概览 Map
@@ -30,45 +200,7 @@ POST /api/ssw/tds/Bridge/AuditRecord body: {bizIds:[..]} -> 审计记录 Ma
POST /api/ssw/tds/Bridge/AuditTrail body: 留痕 JSON -> void
```
请求头:非空时带 `X-Internal-Token`(对应 JNPF `AuthFilter` 的 exclude-url 内部免鉴权端点)。
## 真实 TDS 侧的额外约束(实测)
1. **`Bridge/**` 需 `App-Code: tdc`**
`TdsBridgeInternalController` 的白名单只放行 `App-Code=tdc`;缺该头直接返回 `App-Code invalid`。
`X-Internal-Token` 仅在 `tds.internal-secret` 非空时才校验(当前配置为空 = 免 token)。
→ 本仓库代理对 `Bridge/**` **统一注入** `App-Code: tdc`,并丢弃客户端自带的该头以防伪造/重复。
2. **业务错误走 HTTP 200 + body `code`**
例如 `AuthFilter` 未放行时返回 `{"code":600,"msg":"登录过期"}`,HTTP 状态仍是 200。
→ 判定成败必须同时看 `body.code == 200`,只看 HTTP 状态会把失败误判为成功。
3. **无 `POST /api/ssw/tds/Connector/Register`**
真实 `ConnectorController` 只有 `/{id}/Audit|Heartbeat|Offline|Cancel|PullSession|BusinessDetail`;
连接器由运营方在 CRUD 侧建档。
→ 本仓库 `register` 端点在真 TDS 上返回 `registerStatus: UNSUPPORTED_BY_TDS`,**不伪造成功**;
Noop 模式(未配 base-url)才本地置 `APPROVED`。
4. **`NodeReport`**
`POST /api/ssw/tds/NodeReport` 可直连(200);`GET /NodeReport/Categories` 需登录态。
→ 本仓库 heartbeat 在配 base-url 时一并上报 `NodeReport`,失败仅告警不影响本地。
## 代理行为约定(**旧代理已下线**;下表是 P4 重做时的行为约定)
| 行为 | 约定 |
|---|---|
| 路径映射 | `/api/ssw/tdc/tds/{rest}` → `{base}/api/ssw/tds/{rest}`(query 透传) |
| 逐跳头剥离 | `host` / `content-length` / `connection` / `transfer-encoding` / `upgrade` / `keep-alive` / `te` / `trailer` |
| 内部令牌 | `SSW_TDS_TOKEN` 非空时注入 `X-Internal-Token` |
| App-Code | `rest` 以 `Bridge` 开头时注入 `App-Code: tdc`(覆盖客户端自带值) |
| 上游不可达 | 返回 502 `{"error":"tds unreachable"}` |
| 未配 base-url | 返回 501 `NOOP mode`(对应原 `NoopTdcTdsClient`) |
| 响应回传 | 透传上游状态码与 `Content-Type`,body 原样字节回传 |
> ⚠️ 「未配 base-url ⇒ 501 NOOP」「失败即降级、绝不拖垮本地 TDC 业务」是**原 Java 侧的核心原则**
> (`TdcTdsClient` → `NoopTdcTdsClient`),P4 重做时必须保留。
## 实测验证记录(真实 TDS,2026-10-23,**旧代理时代**)
旧代理时代的实测(2026-10-23,**已失效**,仅供追溯):
| 调用 | 结果 |
|---|---|
@@ -76,7 +208,5 @@ POST /api/ssw/tds/Bridge/AuditTrail body: 留痕 JSON -> void
| `Bridge/Connector/854250096668180741` | 「TEE 连接器_05496131」,`orgName: 吉利汽车`,`ONLINE` |
| `Bridge/DataProduct/855039616187633989` | 「测评目录产品-iws2k」,`DRAFT` |
经本仓库连接器代理调用返回**完全相同**的数据,与 `tds` 库一致。
> ⚠️ 这份记录是**旧代理时代**(2026-10-23)留下的,**旧代理现已下线**。
> P4 落地出向客户端时,**重新做一遍**这组实测并更新本表。
旧代理的「失败即降级、绝不拖垮本地 TDC 业务」原则**已被 internal 通道继承**
(见 §4 三档降级)。
@@ -30,6 +30,9 @@
14. **任何失败都不许变成 HTTP 500、不许 panic**(照抄上游「失败即降级、绝不拖垮本地 TDC 业务」)。
15. **上游只读真源**:`/tmp/sswtdc-probe`、`/tmp/sswtds-probe` **只读,不许改**。**活着的调试 TDS 在 `:30041`(库 `tds2`,日志 `/tmp/tds2-run.log`)⇒ 🔴 不要重启它。**
16. **测试基线**:`cargo test` ⇒ 207 passed / 0 failed / 1 ignored ⇒ 本轮**新增正好 12 条** ⇒ 目标 **219 passed / 0 failed / 1 ignored**。
> 🔧 **实施后更正(2026-10-25)**:约束的**目标数字 219 是对的**(最终实测 219/0/1 ✅),
> 但「新增 12 条」是**按本文件新增**算的;实际上 Task 1–3 的单测已占 **8** 条
> ⇒ Task 5 只加 **4 个测试函数**(**219 = 207 + 8 + 4**)。见 Task 5 的更正块。
17. **记忆约定**:踩坑清单/长 traceback → `docs/`;工作日志 → `.workbuddy/memory/2026-10-25.md`;memory 只留「原则 + 决定 + 指针」。
## 文件结构
@@ -45,7 +48,7 @@
| `src/routes/mod.rs` | 改 | `.merge(tds_biz::router())` |
| `src/main.rs` | 改 | 边界③:`TcpListener::bind(...).unwrap()` → 打印明确文案 + `exit 1` |
| `tests/auth_flow.rs` / `tests/bootstrap_fail.rs` / `tests/crud_engine.rs` | 改 | R8:历史 rustfmt 违规(**纯格式,不动语义**) |
| `tests/tds_biz.rs` | **新建** | 12 条集成测试(假 TDS) |
| `tests/tds_biz.rs` | **新建** | 4 条集成测试(假 TDS)——🔧 原写 12,实施后更正见 Task 5 |
| `docs/TDC-TDS-CONTRACT.md` | 改 | 「P4 输入契约」→「已实现 + 实测表」 |
| `README.md` / `CLAUDE.md` | 改 | API 表 + 红线同步 |
| `.workbuddy/memory/2026-10-25.md` / `.superpowers/sdd/.../progress.md` | 改 | 工作日志 / SDD 台账 |
@@ -789,6 +792,17 @@ Co-Authored-By: Claude Code <[email protected]>"
> 本 Task 的身份解析纯函数**不写独立单测**,改由 `tests/tds_biz.rs` 的集成用例覆盖
> (`Confirm` 显式 id 不一致 ⇒ 拒)。
> 🔧 **实施后更正(2026-10-25,本节 Step 2 的草稿与最终实现有 3 处出入,以最终实现为准)**:
> 1. **请求体抽取器**:草稿写 `use super::body::JsonBody` —— **错**。上游这几个端点是
> `@RequestBody(required = false)`(**体可空**),而 `JsonBody` 空体即拒(会误报
> 「请求体格式有误」)⇒ 最终实现新增 `tds_biz::OptionalJsonBody`(空体 ⇒ `Value::Null`,
> 非法 JSON ⇒ 同一拒因)。**服务目录 Buy / BuyBatch 也要用 `OptionalJsonBody`**。
> 2. **`Dispute` / `Receipt` 的 `connectorId`**:上游是**硬转** `(String) body.get("connectorId")`
> (传数字 ⇒ `ClassCastException` ⇒ 500)⇒ 最终实现统一用宽松 `as_text`(**已登记的刻意分歧 D4**)。
> `Confirm` / `Settle` 上游本就 `asText`(宽松)⇒ 与本仓一致。
> 3. **`Voucher` 的 `connectorId` 走查询串**(上游 `voucher(@PathVariable id, String connectorId)`)
> ⇒ **不是** body;`List` / `LocalCompare` 同理走查询串。
**Interfaces:**
- Consumes: `tds::TdsClient`(Task 3)、`crud::parse_query` / `crud::param` / `crud::row_to_json`、`db::query_json_params`、`db::ALIVE`、`envelope::ActionResult`、`auth::Principal`
- Produces:
@@ -1387,17 +1401,24 @@ Co-Authored-By: Claude Code <[email protected]>"
---
### Task 5: `tests/tds_biz.rs` —— 12 条集成测试(假 TDS)
### Task 5: `tests/tds_biz.rs` —— **4 条**集成测试(假 TDS)
**Files:**
- Create: `tests/tds_biz.rs`
- Test: `tests/tds_biz.rs`(**新增 12 条** ⇒ 207 + 12 = 219)
- Test: `tests/tds_biz.rs`(**新增 4 个 `#[tokio::test]`**)
> 🔧 **实施后更正(2026-10-25)——测试条数算平**:本节原写「新增 12 条 ⇒ 207 + 12 = 219」,
> **算错了**:Task 1–3(`config` / `tds` 模块)**已经加了 8 条**单测
> ⇒ 真正的算式是 **219 = 207 + 8 + 4** ⇒ 本节只加 **4 个测试函数**。
> **函数数 ≠ 断言数**:4 个函数里塞了 20+ 条断言(每条端点/每种失败形状各占一条)。
> 最终落地:`d3d609f`(4 条)+ `b82c71a`(补一条「解包型端点的 TDS 业务失败」断言,
> 让变异③a 变成 load-bearing)。
**Interfaces:**
- Consumes: `tdc_connector::tds::TdsClient`、`tdc_connector::state::AppState::with_tds`、`tdc_connector::routes::build_router`
- Produces: 无(纯测试)
- [ ] **Step 1: 写测试文件(假 TDS + 12 条用例)**
- [ ] **Step 1: 写测试文件(假 TDS + 4 条用例)**
```rust
//! P4 TDS 出向客户端集成测试(假 TDS)。
@@ -1622,7 +1643,7 @@ async fn call(app: &Router, r: Request<Body>) -> (StatusCode, Value) {
}
// ==================================================================
// 12 条用例
// 4 条用例(断言数远多于用例数)
// ==================================================================
/// ① 路径映射 + 头注入 + 头不外泄(spec §6.1 #1/#2/#3)。
@@ -2211,7 +2232,7 @@ Co-Authored-By: Claude Code <[email protected]>"
| §3.5 鉴权与错误语义 | Task 4(业务失败信封)、Task 5 用例⑤⑥⑩ |
| §4 D1–D6 差异 | Task 4(D1 逐端点口径)、Task 2(D4 不做 ensureToken)、Task 3/4(D5 NOOP 文案、D6 超时) |
| §5 不做的缺口 | Task 8 Step 1(写进契约文档)、Task 1(`/api/ssw/tdc/tds/*` 保持 404) |
| §6.1 10 条断言 | Task 5(12 条用例覆盖 10 组断言) |
| §6.1 10 条断言 | Task 5(4 条用例覆盖 10 组断言) |
| §6.2 4 条变异自证 | Task 6 |
| §6.3 真 TDS 实跑 | Task 7 |
| §6.4 浏览器复验 | Task 7 Step 4 |