From 52074a136d74b374c525bcc8957de95054ef6ab6 Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 25 Oct 2026 14:24:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(tds):=20=E8=A1=A5=E9=BD=90=20P4=20?= =?UTF-8?q?=E5=87=BA=E5=90=91=E9=80=9A=E9=81=93=E7=9A=84=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8E=E9=A1=B9=E7=9B=AE=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 影响: - `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 --- .workbuddy/memory/2026-10-25.md | 59 +++++ CLAUDE.md | 57 ++++- README.md | 12 + docs/TDC-TDS-CONTRACT.md | 236 ++++++++++++++---- .../2026-10-25-tdc-rs-p4-tds-outbound.md | 33 ++- 5 files changed, 332 insertions(+), 65 deletions(-) diff --git a/.workbuddy/memory/2026-10-25.md b/.workbuddy/memory/2026-10-25.md index 0ea1cab..b12df65 100644 --- a/.workbuddy/memory/2026-10-25.md +++ b/.workbuddy/memory/2026-10-25.md @@ -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 通道已不对应(未用)。 + diff --git a/CLAUDE.md b/CLAUDE.md index 08c7cca..3123793 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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`),不走菜单。 diff --git a/README.md b/README.md index b78361e..4b7ab61 100644 --- a/README.md +++ b/README.md @@ -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`(公开默认值) | ## 已实现范围 diff --git a/docs/TDC-TDS-CONTRACT.md b/docs/TDC-TDS-CONTRACT.md index dc40859..aace920 100644 --- a/docs/TDC-TDS-CONTRACT.md +++ b/docs/TDC-TDS-CONTRACT.md @@ -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` | 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 三档降级)。 diff --git a/docs/superpowers/plans/2026-10-25-tdc-rs-p4-tds-outbound.md b/docs/superpowers/plans/2026-10-25-tdc-rs-p4-tds-outbound.md index 7560fa6..ea9b7f7 100644 --- a/docs/superpowers/plans/2026-10-25-tdc-rs-p4-tds-outbound.md +++ b/docs/superpowers/plans/2026-10-25-tdc-rs-p4-tds-outbound.md @@ -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 " > 本 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 " --- -### 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) -> (StatusCode, Value) { } // ================================================================== -// 12 条用例 +// 4 条用例(断言数远多于用例数) // ================================================================== /// ① 路径映射 + 头注入 + 头不外泄(spec §6.1 #1/#2/#3)。 @@ -2211,7 +2232,7 @@ Co-Authored-By: Claude Code " | §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 |