把 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]>
441 lines
33 KiB
Markdown
441 lines
33 KiB
Markdown
# 对外契约(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/` 重建**(探针只在首次建表时跑;
|
||
半途失败的迁移会留下「建了一半」的库 ⇒ 此后每次启动都跳过迁移)。
|