Files
tdc-rs/docs/contract.md
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。

新增文档:

- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
  唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。

新增尺子(第四把 + 两把专项):

- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。

影响:

- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
  (`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
  ⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
  吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
  POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
  失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
  **不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。

实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。

⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 00:56:09 +08:00

441 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 对外契约(contract)
> 🔴 本文件是 **tdc-rs 对外可观测契约的唯一真源**:端点全表 / 响应形状 / 命名契约 /
> 权限口径 / 数据模型。
> 与 `docs/decisions.md`(为什么这么定)/ `docs/known-limitations.md`(已知偏差)配套读。
> 操作层面看 `docs/runbook.md`;账号层看 `docs/ACCOUNT-LAYER.md`;
> 迁移与加实体看 `MIGRATION.md` / `HOWTO_ENTITY.md`。
>
> **当前状态**:v3 改造批次 **B5 文档层**(本文件即其产物)。
---
## 端点全表(132 条)
**分组**:健康检查 1 + 连接器身份 4 + 账号层 7 + 实体 CRUD 110(18 实体 × 6 + 2 个只读聚合体)
+ TDS 出向 10 = **132**。
| 组 | 段 | 条数 | 装配处 |
|---|---|---|---|
| 健康检查 | `/api/health` | 1 | `src/tdc/controller/health.rs:23` |
| 连接器身份 | `/api/ssw/tdc/Auth/*` | 4 | `src/tdc/controller/auth.rs:11` |
| 账号层 | `/api/oauth/*` + `/api/permission/*` | 7 | `src/tdc/controller/account.rs:42` |
| 实体 CRUD | `/api/ssw/tdc/{Entity}/*` | 110 | `src/tdc/controller/crud.rs:27`(遍历 `entity::ALL_SPECS`) |
| TDS 出向 | `/api/ssw/tdc/ServiceCatalog/*` + `/api/ssw/tdc/Billing/*` | 10 | `src/tdc/controller/tds_biz.rs:36` |
<!-- BEGIN ENDPOINTS -->
| GET | `/api/health` | 健康检查(**裸对象**,非业务信封) |
| POST | `/api/ssw/tdc/Auth/Login` | 连接器身份登录(软 PKI,签发会话令牌) |
| GET | `/api/ssw/tdc/Auth/Me` | 当前身份视图(**去敏**:不含私钥/一次性密钥;带 `roles`) |
| GET | `/api/ssw/tdc/Auth/Spaces` | 环境空间列表 |
| GET | `/api/ssw/tdc/Auth/SsoConfig` | SSO 配置(本仓恒 `enabled:false`) |
| POST | `/api/oauth/Login` | JNPF 兼容登录(表单:`account`/`password`(密文 hex)/`grant_type=password`) |
| GET | `/api/permission/Users` | 用户管理 · 列表(**仅管理员**) |
| POST | `/api/permission/Users` | 用户管理 · 新建(**仅管理员**) |
| PUT | `/api/permission/Users/{id}` | 用户管理 · 改资料(**仅管理员**) |
| DELETE | `/api/permission/Users/{id}` | 用户管理 · 删账号(**仅管理员**,逻辑删除) |
| POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 用户管理 · 重设口令(**仅管理员**) |
| PUT | `/api/permission/Users/{id}/Actions/State` | 用户管理 · 启用/禁用(**仅管理员**) |
| GET | `/api/ssw/tdc/ApiConsumeLog` | ApiConsumeLog · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/ApiConsumeLog/All` | ApiConsumeLog · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/ApiConsumeLog/{id}` | ApiConsumeLog · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/ApiConsumeLog` | ApiConsumeLog · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/ApiConsumeLog/{id}` | ApiConsumeLog · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/ApiConsumeLog/{id}` | ApiConsumeLog · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/AuditLog` | AuditLog · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/AuditLog/All` | AuditLog · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/AuditLog/{id}` | AuditLog · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/AuditLog` | AuditLog · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/AuditLog/{id}` | AuditLog · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/AuditLog/{id}` | AuditLog · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Contract` | Contract · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Contract/All` | Contract · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Contract/{id}` | Contract · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Contract` | Contract · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Contract/{id}` | Contract · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Contract/{id}` | Contract · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Credential` | Credential · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Credential/All` | Credential · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Credential/{id}` | Credential · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Credential` | Credential · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Credential/{id}` | Credential · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Credential/{id}` | Credential · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/DataInterface` | DataInterface · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/DataInterface/All` | DataInterface · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/DataInterface/{id}` | DataInterface · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/DataInterface` | DataInterface · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/DataInterface/{id}` | DataInterface · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/DataInterface/{id}` | DataInterface · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Dataset` | Dataset · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Dataset/All` | Dataset · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Dataset/{id}` | Dataset · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Dataset` | Dataset · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Dataset/{id}` | Dataset · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Dataset/{id}` | Dataset · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Datasource` | Datasource · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Datasource/All` | Datasource · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Datasource/{id}` | Datasource · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Datasource` | Datasource · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Datasource/{id}` | Datasource · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Datasource/{id}` | Datasource · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/DeliveryLog` | DeliveryLog · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/DeliveryLog/All` | DeliveryLog · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/DeliveryLog/{id}` | DeliveryLog · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/DeliveryLog` | DeliveryLog · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/DeliveryLog/{id}` | DeliveryLog · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/DeliveryLog/{id}` | DeliveryLog · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/DeliveryTask` | DeliveryTask · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/DeliveryTask/All` | DeliveryTask · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/DeliveryTask/{id}` | DeliveryTask · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/DeliveryTask` | DeliveryTask · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/DeliveryTask/{id}` | DeliveryTask · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/DeliveryTask/{id}` | DeliveryTask · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/DestroyLog` | DestroyLog · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/DestroyLog/All` | DestroyLog · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/DestroyLog/{id}` | DestroyLog · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/DestroyLog` | DestroyLog · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/DestroyLog/{id}` | DestroyLog · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/DestroyLog/{id}` | DestroyLog · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Identity` | Identity · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Identity/All` | Identity · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Identity/{id}` | Identity · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Identity` | Identity · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Identity/{id}` | Identity · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Identity/{id}` | Identity · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Notification` | Notification · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Notification/All` | Notification · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Notification/{id}` | Notification · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Notification` | Notification · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Notification/{id}` | Notification · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Notification/{id}` | Notification · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Order` | Order · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Order/All` | Order · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Order/{id}` | Order · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Order` | Order · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Order/{id}` | Order · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Order/{id}` | Order · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Policy` | Policy · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Policy/All` | Policy · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Policy/{id}` | Policy · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Policy` | Policy · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Policy/{id}` | Policy · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Policy/{id}` | Policy · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/PolicyCheckLog` | PolicyCheckLog · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/PolicyCheckLog/All` | PolicyCheckLog · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/PolicyCheckLog/{id}` | PolicyCheckLog · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/PolicyCheckLog` | PolicyCheckLog · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/PolicyCheckLog/{id}` | PolicyCheckLog · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/PolicyCheckLog/{id}` | PolicyCheckLog · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/PolicyTemplate` | PolicyTemplate · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/PolicyTemplate/All` | PolicyTemplate · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/PolicyTemplate/{id}` | PolicyTemplate · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/PolicyTemplate` | PolicyTemplate · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/PolicyTemplate/{id}` | PolicyTemplate · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/PolicyTemplate/{id}` | PolicyTemplate · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Product` | Product · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Product/All` | Product · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Product/{id}` | Product · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Product` | Product · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Product/{id}` | Product · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Product/{id}` | Product · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Resource` | Resource · 分页列表(业务信封 `data.list` + `data.pagination`) |
| GET | `/api/ssw/tdc/Resource/All` | Resource · 全量列表(不分页,仍是业务信封) |
| GET | `/api/ssw/tdc/Resource/{id}` | Resource · 详情(部分实体带子表挂载 ⇒ 见 §子表聚合) |
| POST | `/api/ssw/tdc/Resource` | Resource · 新增(`no_create` 的实体拒绝) |
| PUT | `/api/ssw/tdc/Resource/{id}` | Resource · 修改(`no_update` 的实体拒绝;冻结列拒改) |
| DELETE | `/api/ssw/tdc/Resource/{id}` | Resource · 逻辑删除(`no_delete` 的实体拒绝) |
| GET | `/api/ssw/tdc/Dataset/{id}/Detail` | Dataset · 只读聚合体(挂子表:见 §子表聚合) |
| GET | `/api/ssw/tdc/Resource/{id}/Detail` | Resource · 只读聚合体(挂子表:见 §子表聚合) |
| GET | `/api/ssw/tdc/Billing/List` | 本方账单列表(出向 TDS `BillingLedger/Internal/List`) |
| GET | `/api/ssw/tdc/Billing/LocalCompare` | 本地计量比对(读本地 `tdc_api_consume_log`,**零出向**) |
| PUT | `/api/ssw/tdc/Billing/{id}/Confirm` | 账单确认(出向 TDS `BillingLedger/{id}/Confirm`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Dispute` | 账单异议(出向 TDS `BillingLedger/{id}/Dispute`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Receipt` | 收据(出向 TDS `BillingLedger/{id}/Receipt`) |
| PUT | `/api/ssw/tdc/Billing/{id}/Settle` | 账单结算(出向 TDS `BillingLedger/{id}/Settle`) |
| GET | `/api/ssw/tdc/Billing/{id}/Voucher` | 对账凭证(出向 TDS `BillingLedger/{id}/Voucher`) |
| GET | `/api/ssw/tdc/ServiceCatalog` | 服务目录(出向 TDS `Catalog/Internal/Catalog`) |
| POST | `/api/ssw/tdc/ServiceCatalog/Buy` | 目录下单(出向 TDS `TradeOrder/Internal/Apply`) |
| POST | `/api/ssw/tdc/ServiceCatalog/BuyBatch` | 目录批量下单(出向 TDS `TradeOrder/Internal/ApplyBatch`) |
<!-- END ENDPOINTS -->
### 🔴 端点数**不许**手工维护(用脚本对账)
```bash
bash scripts/check-contract.sh # 起真进程 → 逐条探测 → 与本表对账
```
对账内容(`scripts/contract_probe.py`):
| 项 | 判据 |
|---|---|
| **路径完整性** | 源码里的**每个路由路径**都必须在表里(双向:不多不少) |
| **方法准确性** | 每个 (方法, 路径) 必须**真的注册**(运行时 404 ⇒ 未注册 ⇒ 判红) |
| **方法集合** | 每个路径上「运行时注册的方法集合」== 表里的方法集合 |
| **端点总数** | 表里行数 == **132** |
🔴 **为什么用运行时探测而不是静态解析 Rust 源码**:`.route(p, get(..).post(..))` 的链式调用
跨多行、括号套嵌,正则脆得一碰就碎 ⇒ **方法以运行时为准**,静态侧只负责路径全集。
---
## 响应形状(4 种 + 1 变体)
| # | 场景 | HTTP | body 形状 | 代码位置 |
|---|---|---|---|---|
| **① 业务信封** | 业务成功 / 业务失败 | **200** | `{"code":…,"msg":…,"data":…}` | `src/platform/envelope.rs:27`(`ok`)/ `:46`(`fail`)/ `:54`(`fail_code`) |
| **② 鉴权 / 授权失败** | 三道门任一不过 / 管理员位不过 | **401 / 403** | `{"success":false,"code":…,"msg":"…"}` —— **无 `data` 键** | `src/platform/auth.rs:132`(`reject`) |
| **③ 未命中** | `/api/**` 没这条路由 | **404** | `{"success":false,"code":404,"msg":"接口不存在"}` —— **无 `data` 键** | `src/platform/fallback.rs:96`(`api_not_found`) |
| **④ 裸对象** | 健康检查 | **200** | `{"status","service","version","protocolVersion","tdsMode","tdsBaseUrl","db","tables","baseTables"}` —— **无 `code`/`msg`/`data`** | `src/tdc/controller/health.rs:53` |
**变体 ④′(405 方法不允许)**:HTTP **405** + `{"code":405,"msg":"方法不被允许","data":null}`
—— **有 `data`、无 `success`**(与 ①②③ 都不像,判红时注意)。
位置 `src/platform/mw.rs:50`(`method_not_allowed_body`)/ `:59`(`json_method_not_allowed`)。
🔴 **最容易踩的一条**:**业务失败也是 HTTP 200** ⇒ 只看 HTTP 状态会把失败误判成成功
⇒ **必须同时判 body 的 `code`**(上游 TDS 同款)。
> 🔴 **最常见的真实实例**:**26 条上游动作端点**(`/{Entity}/{action}` 形状,
> 如 `PolicyTemplate/Options` · `Resource/Enabled` · `Datasource/Types`)
> **本仓未实现**,但路径**被通用详情路由 `/{Entity}/{id}` 先匹配上** ⇒
> **GET** 返回 **200 + `code:400`**「记录不存在或已删除」(**不是 404**),
> **POST** 返回 **405**(`{id}` 上没注册 POST)⇒
> 上游前端的**下拉框会静默变空**。逐条清单见 `docs/known-limitations.md` **L7**
> (`python3 scripts/upstream-action-census.py` 可复算)。
### 分页信封(形状 ① 的 `data` 特例)
```json
{ "code": 200, "msg": "操作成功",
"data": { "pagination": { "currentPage": 2, "pageSize": 20, "total": 41 },
"list": [ … ] } }
```
- 位置:`src/platform/envelope.rs:63`(`ActionResult::page`)/ `:76`(`Pagination`)。
- `/All` **不分页** ⇒ `data` 是**裸数组**(不是 `{list:…}`)。
- 分页入参:`pageSize` / `currentPage`(camelCase,见下节)。
---
## 命名契约(`f_` ↔ camelCase)
| 方向 | 规则 | 位置 |
|---|---|---|
| 列 → JSON 键 | `f_real_name` ⇒ `realName`;`f_id` ⇒ `id` | `src/platform/db.rs:278`(`column_to_json_key`) |
| JSON 键 → 列 | `realName` ⇒ `f_real_name` | `src/platform/db.rs:296`(`json_key_to_column`) |
- 🔴 **入参**一律 camelCase(前端送什么就收什么);**出参**一律 camelCase。
- 🔴 请求结构体加 `#[serde(rename_all = "camelCase")]`。
**例外**:`/api/oauth/Login` 的表单字段名就是 `grant_type`(上游送的就是这个)
⇒ 不能加 camelCase,用 `#[serde(default, alias = "grantType")]`。
- 🔴 **出参不许带密钥**:上游标了 `@JsonIgnore` 的属性(`Identity.secretKey` /
`DeliveryTask.devUrl` / `devToken`)在 `registry::TableSpec::hidden_fields` 登记
⇒ 出参**整条删键**、入参**静默忽略**(照抄 Jackson 双向语义)。
- **numeric 列输出 JSON 数字**(不是字符串)—— D16 的取证结论。
---
## 时间口径
仓里有**两套**时间口径,**不是随手写的**——各对应上游的一个具体行为:
| 面 | 口径 | 代码位置 | 上游对照 | 为什么是它 |
|---|---|---|---|---|
| 业务编码(`PRO-` / `RES-` / `API-` / `DS-` 的日期与时刻段) | **服务器本地时区** | `src/tdc/util/code.rs:37`(`day_prefix`)、`src/tdc/util/code.rs:58`(`format_code`)⇒ `Local::now()` | `TdcCodeUtil.dayPrefix` / `TdcCodeUtil.format` 用 `LocalDateTime.now()`(Java,服务器本地) | 编码里的 `yyyyMMdd-HHmmss` 要与上游**同一天同刻**;差一个时区偏移时,跨零点的 8 小时里日期段会直接变成前一天 |
| DB 审计列(`f_creator_time` / `f_modify_time` / `f_delete_time` …) | **服务器本地时区** | `src/tdc/service/crud.rs`、`:520`、`:524`、`:530`、`:624`、`:688` ⇒ SQL `now()` | JNPF `BaseEntity` 自动填充用 `new Date()`(服务器本地) | 审计列的时间戳要与上游同一量纲,便于两边的日志按时间轴对齐 |
| 账号层的审计列(`base_user.f_creator_time` / `f_last_modify_time` / `f_delete_time`) | **服务器本地时区** | `src/tdc/service/account.rs`(SQL `now()`) | 上游 j7 的 `base_user` 走 MySQL 填充(服务器本地) | B4 之后账号层落 `base_user` ⇒ **以表为准**(与上游 j7 同口径) |
🔴 **收敛后的规矩**(v3 spec §2.3.1 C12):
1. **仓里不再手写日历算法** —— 一律用 `chrono`(已依赖 `chrono 0.4`,`features = ["clock"]`)。
此前 `account.rs` 自己实现了一套天元纪日 → 公历的换算(`civil_from_days`)⇒ 重复造轮子,
且与 `code.rs` 的时区口径不一致(一个 UTC 一个本地)⇒ 手工算法与它的推论一起删除。
2. **口径写在代码注释里**(不是只在文档里):谁想改时区,必须先改那处的注释 ⇒ 评审时看得见。
3. ⚠️ **别把 Local 写成 UTC**:业务编码、DB 审计列、账号层审计列都必须留在**服务器本地时区**,
否则同一时刻生成的编码与上游对不上(见上表第一行)。
4. ⚠️ **别在别处手写 `Utc::now()` 填时间戳**:仓里**已无** UTC 口径的字段
(B4 之前账号层是本机 JSON 文件、自有 `creator_time` 字段用 UTC;B4 之后账号层落表 ⇒ 该字段消失)。
---
## 子表聚合(挂载点口径)
上游有 **7 张「没有独立控制器」的子表** ⇒ 它们的可见性**全部挂在父实体的响应里**。
本仓**不新增端点**,照抄上游的挂载位置(v3 spec §6.2 B3)。
| 父实体 | 挂载面 | 输出键 | 子表 | 外键列 → 父行取值列 | 排序 | 上游出处 |
|---|---|---|---|---|---|---|
| `Resource` / `Dataset` | `GET /{id}/Detail` | `fieldRules` | `tdc_resource_field` | `f_resource_id` → `f_id` | `f_sort_code` | `ResourceServiceImpl#withChildren` |
| `Resource` / `Dataset` | `GET /{id}/Detail` | `maskRules` | `tdc_resource_mask_rule` | `f_resource_id` → `f_id` | `f_sort_code` | 同上 |
| `DataInterface` | `GET /{id}` | `params` | `tdc_data_interface_param` | `f_interface_id` → `f_id` | `f_sort_code` | `DataInterfaceServiceImpl#withChildren`(`DataInterfaceController#detail` 覆写调用) |
| `DataInterface` | `GET /{id}` | `fields` | `tdc_data_interface_field` | `f_interface_id` → `f_id` | `f_sort_code` | 同上 |
| `DeliveryTask` | `GET /{id}` + 列表 | `participants` | `tdc_delivery_task_participant` | `f_tds_task_id` → **`f_tds_task_id`** | `f_connector_id` | `TdcDeliveryTaskParticipantServiceImpl#attachParticipants` |
| `DeliveryTask` | `GET /{id}` | `outbox` | `tdc_delivery_outbox` | `local_task_id` → `f_id` | `seq` | 🔴 **本仓扩展**(上游不挂,见 §偏离) |
| `tdc_demo_car_insurance` | — | — | — | **无父外键** | — | 🔴 挂不了(见 §偏离) |
**规矩**:
1. 🔴 **挂载面逐父子不同,不是「都挂详情」**——
`Resource` 的子表**只在 `/Detail` 聚合体**(普通 `GET /{id}` **不带**);
`DataInterface` 的子表**只在普通详情**(上游没有 `/Detail` 聚合体路由)。
2. 🔴 **父行取值列可以不是 `f_id`**:参与方按**平台任务号**(`f_tds_task_id`)挂 ⇒
任务没有平台任务号时,参与方是**空集合**(上游同口径,不是"查一次再判空")。
3. 🔴 **存活谓词逐表不同**:四张「资源 / 接口」子表**没有** `f_delete_mark`(上游物理删除)
⇒ 不加谓词;参与方表有 ⇒ 按本仓 `ALIVE` 过滤。
4. 🔴 **列表挂载是批量查**(一次 `IN` + 分组)⇒ 不产生 N+1(上游 `listByTdsTaskIds` 同款)。
**代码位置**(`file:line`):
- 声明结构:`src/tdc/entity/mod.rs:60`(`ChildMount`)、`src/tdc/entity/mod.rs:74`(`ChildTable`)、
`src/tdc/entity/mod.rs:145`(`TableSpec::child_tables`)、`src/tdc/entity/mod.rs:164`(`children_on`)。
- 引擎:`src/tdc/service/crud.rs:322`(父行取值)、`:344`(单父取子行)、`:373`(批量取子行)、
`:414`(单行回填)、`:433`(列表回填)。
- 逐实体声明:`src/tdc/entity/resource.rs:34`、`src/tdc/entity/dataset.rs:28`、
`src/tdc/entity/data_interface.rs:26`、`src/tdc/entity/delivery_task.rs:55`。
### 偏离
| 项 | 上游 | 本仓 | 为什么 |
|---|---|---|---|
| `outbox`(待发队列)挂详情 | **不挂**(上游是内部重试队列,只由 `DeliveryOutboxRetryTicker` 消费) | 挂在 `DeliveryTask` 详情(键 `outbox`) | 它货真价实是任务的子表(`local_task_id` = 任务 `f_id`),且本仓**不实现**交付执行 ⇒ 队列恒空 ⇒ 挂了也不产生噪声;将来接入重试时这条挂载即生效 |
| `tdc_demo_car_insurance` | **不挂**(它是 `SandboxSessionServiceImpl` 的**降级演示数据源**,无父外键) | **不挂** | 上游 Sandbox / Nax 隐私计算属本仓**明确排除**范围(见 `CLAUDE.md`「明确不在本仓库范围」)⇒ 该表在本仓无父、无消费者 ⇒ 挂不上也不该硬挂 |
---
## 账号层(B4:`base_user` 载体)
### 载体与端点
| 面 | 端点 | 载体 | 说明 |
|---|---|---|---|
| JNPF 账号根 | `POST /api/oauth/Login` | **`base_user`** | 账号口令登录(form-urlencoded:`account` / `password`(密文 hex) / `grant_type=password`) |
| 用户管理 | `/api/permission/Users*`(6 个端点) | **`base_user`** | 列表 / 新建 / 改资料 / 删 / 改密 / 启停 |
| 连接器身份根 | `POST /api/ssw/tdc/Auth/Login` | `tdc_identity` | **不动**(双账号根,v3 spec §4.4) |
🔴 **存量 `data/accounts.json` 不导入**(D5/D8):文件**保留不删**,但**后端不再读取**。
### 口令:官方双 md5 公式
| 环节 | 口径 |
|---|---|
| 前端加密 | `md5(明文)` → AES-256-ECB-PKCS7 → hex(`src/platform/cipher.rs`,**一字不改**) |
| 服务端解密 | 密文 hex → `md5(明文)`(32 个小写 hex) |
| **入库** | `f_password = md5(lower(md5(明文)) + lower(f_secretkey))` |
| 登录比对 | 解密得 `md5(明文)` → 拼 `lower(secretkey)` → 再 `md5` → 与 `f_password` 比 |
- `f_secretkey` = **每账号随机**(UUID v4 大写连字符,36 字符)。
- 🔴 **改密不换 secretkey**(与官方一致)⇒ 改密只重算 `f_password`。
- 🔴 **一次性换算单向不可逆**:`f_password = md5(lower(旧裸 md5 hex) || lower(新 secretkey))`
⇒ 从旧裸 md5 换到新公式需要**旧 md5**(前端手里那份)+ 新 secretkey。
**代码位置**(`file:line`):
- 公式:`src/tdc/service/account.rs`(`official_password_hash`)
- 登录比对:`src/tdc/controller/account.rs`(`login`)
- 改密:`src/tdc/service/account.rs`(`reset_password`)
- 独立向量自证:`src/tdc/service/account.rs`(单测 `official_password_hash_matches_the_upstream_formula`,
两个向量用系统 `md5` 独立算出 ⇒ **不是自证自洽**)
### 引导与管理员位
- **首次启动**(`base_user` 无存活行时)引导**一个**管理员:
`f_account='admin'`、`f_is_administrator=1`、`f_enabled_mark=1`、口令按上面的公式入库。
🔴 引导**幂等**:库里有账号就不动(重复启动不覆盖既有账号)。
- **角色**:`base_role` 种上游 `V1.0.1__connector_seed.sql` 的三行
(`tdcProvider` / `tdcConsumer` / `user`)⇒ **逐字照抄**(含固定 id)。
- **管理员绑角色**:`base_role_relation` 写一行
(`f_object_type='user'`、`f_object_id=<admin f_id>`、`f_role_id` = `user` 角色的 `f_id`)。
- **管理员判据** = `base_user.f_is_administrator = 1`(`f_delete_mark IS NULL OR = 0`),
**查询异常 ⇒ false(fail-closed)** ⇒ 守 `/api/permission/Users*` 六个端点。
### 出参形状(**不变**)
`/api/permission/Users` 的每一行仍是:
```json
{ "id", "account", "realName", "gender", "mobilePhone", "enabledMark", "creatorTime", "description" }
```
🔴 **不得**回显 `f_password` / `f_secretkey`(出参整条删键,不是置 null)。
🔴 `creatorTime` 是 `to_char(f_creator_time,'YYYY-MM-DD HH24:MI:SS')` 的**字符串**(形状不变)。
---
## 权限模型(三件套,v3 spec §5)
| 面 | 判据 | 代码位置 |
|---|---|---|
| **登录态** | 内部令牌 **或** 已登录主体(连接器身份会话 / 本地账号会话) | `src/platform/auth.rs:243`(`require_menu_permission`) |
| **角色码** | `base_role.f_en_code` ∈ {`tdcProvider`,`tdcConsumer`,`tdsReadOnly`}(经 `base_role_relation` 关联) | `src/tdc/service/account.rs:320`(`role_codes`) |
| **管理员位** | `base_user.f_is_administrator = 1`(**fail-closed**) | `src/tdc/service/account.rs:289`(`is_administrator`) |
🔴 写操作的闸门 = **同一个** `require_menu_permission`
(写:`src/tdc/service/crud.rs:524` create / `:672` update / `:772` delete;
读:`:213` list / `:282` all / `:467` detail / `:831` aggregate)
⇒ 读写**同闸门**,与上游 `TdcCrudController.requireMenuPermission()`(`permissionGuard == null` 时)同构。
### ⚠️ 实体级写权限**没有隔离**(D6 / D11,**显式记账**)
**除管理员端点外,任何登录用户可写全部 18 个实体。**
- 这**不是**收紧,也**不是**放权 ⇒ 是**拆掉一层「看起来在管、实际没管」的假权限层**:
旧的 18 条实体→权限键(`entity::PERMISSION_KEYS`)+ `identity::capabilities()` +
`crud::require_write_permission()` **整条链路已删**。
- 删除后与上游**完全同构**(上游 `TdcCrudController.requireMenuPermission()` 在
`permissionGuard == null` 时只校验「有登录态或内部令牌」)。
- 只读/只写分档(`no_create` / `no_update` / `no_delete`)**仍在**。
- 🔴 **部署退出门槛**:账号发放**只给受信人**(默认口令 `admin` 是公开已知的)。
详见 `docs/known-limitations.md` L4。
### 角色码的悬空码(D9 / S7)
判据里的三个码与种子里的三个角色**不是同一组**(上游自身的不一致,照抄):
| | `tdcProvider` | `tdcConsumer` | `tdsReadOnly` | `user` |
|---|---|---|---|---|
| **判据**(`role_codes` 的 `IN` 列表) | ✅ | ✅ | ✅ | ❌ |
| **种子**(`SEED_ROLES`) | ✅ | ✅ | ❌ | ✅ |
⇒ **引导管理员绑的是 `user` 角色 ⇒ 它的 `/Auth/Me` 角色码数组是空的**(上游同口径,不是 bug)。
### 鉴权失败形状(**不变**)
HTTP 401/403 + 裸 `{"success":false,"code":…,"msg":"…"}`(**无 `data` 键**)。
业务失败仍是 HTTP 200 + `{code,msg,data}`。⇒ 详见 §响应形状 ②。
---
## 数据模型(30 + 3 张表)
`schema/migrate.sql` = 上游 `tdc_*` schema(**30 张业务表**)**+ 账号层 3 张 `base_*` 表**。
| 域 | 表 |
|---|---|
| 身份 / 凭据 | `tdc_identity`、`tdc_credential`、`tdc_p2p_session` |
| 数据源 / 接口 | `tdc_datasource`、`tdc_data_interface`、`tdc_data_interface_field`、`tdc_data_interface_param` |
| 资源 / 脱敏 | `tdc_resource`、`tdc_resource_field`、`tdc_resource_mask_rule` |
| 目录 / 交易 | `tdc_product`、`tdc_order`、`tdc_contract` |
| 策略 | `tdc_policy`、`tdc_policy_template`、`tdc_policy_check_log` |
| 交付 | `tdc_delivery_task`、`tdc_delivery_task_participant`、`tdc_delivery_log`、`tdc_delivery_outbox` |
| 执行 / 销毁 | `tdc_privacy_exec_run`、`tdc_sandbox_exec_run`、`tdc_destroy_log` |
| 日志 / 通知 | `tdc_audit_log`、`tdc_api_consume_log`、`tdc_sync_log`、`tdc_notify` |
| 上游示例 | `tdc_demo_car_insurance`、`tdc_demo_insurance_claims`、`tdc_demo_pii` |
| **账号层** | `base_user`、`base_role`、`base_role_relation` |
- 🔴 **逻辑删除位** = `f_delete_mark`;存活谓词 = `(f_delete_mark IS NULL OR f_delete_mark = 0)`。
- 🔴 **24 张**带齐 10 个系统列(`f_id` / `f_tenant_id` / `f_sort_code` + 创建·修改·删除审计列),
其余 **6 张**为精简变体。
- 🔴 **`Dataset` 不是独立表** —— 它是 `tdc_resource` 的**只读视图**(`TableSpec.table = "tdc_resource"`),
⇒ 注册表里 **18 个实体**只对应 **17 张**业务表(`Resource` 与 `Dataset` 共用 `tdc_resource`)
+ `base_*` 3 张。
- 🔴 **30 张 `tdc_*` 里有 13 张没有对应实体**:其中 **6 张是挂载的子表**
(`tdc_resource_field` / `tdc_resource_mask_rule` / `tdc_data_interface_field` /
`tdc_data_interface_param` / `tdc_delivery_task_participant` / `tdc_delivery_outbox`
⇒ 见 §子表聚合),其余 7 张是**上游示例 / 隐私计算 / P2P / 同步日志**
(`tdc_demo_car_insurance` / `tdc_demo_insurance_claims` / `tdc_demo_pii` /
`tdc_privacy_exec_run` / `tdc_sandbox_exec_run` / `tdc_p2p_session` / `tdc_sync_log`)
⇒ 隐私计算那几张属**明确排除**范围(见 `CLAUDE.md`)。
- 🔴 **表名白名单**:任何拼进 SQL 的标识符都要过 `valid_table()`,
且启动时由 `entity::validate()` 自检(不过 ⇒ 秒退)。
- 🔴 **改 `migrate.sql` 必须清空 `data/` 重建**(探针只在首次建表时跑;
半途失败的迁移会留下「建了一半」的库 ⇒ 此后每次启动都跳过迁移)。