- 协议版本收敛为单一常量 3.2,移除联调期自创的 env 覆盖 - 按真源同步 5 项契约:Dispute 下线、Billing/List 增 side、internalCatalog 6 过滤字段、新增 ServiceCatalog/Detail、出向方法收敛 - 修正 /api/** 未命中非 GET 请求被静态兜底判成 405 的偏差,恢复 404 契约 - 新增上游用例跨进程验证脚本与 4 份联调文档;部署级凭据只从环境变量读取 - 全量测试 308 passed;132 端点契约一致;真 TDS 21 条用例 19 PASS / 1 FAIL / 1 INFO
33 KiB
对外契约(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 |
| 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}/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) |
| GET | /api/ssw/tdc/ServiceCatalog/Detail/{productCode} | 目录详情(出向 TDS Catalog/Detail/{productCode}?spaceId=) |
🔴 端点数不许手工维护(用脚本对账)
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.mdL7 (python3 scripts/upstream-action-census.py可复算)。
分页信封(形状 ① 的 data 特例)
{ "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):
- 仓里不再手写日历算法 —— 一律用
chrono(已依赖chrono 0.4,features = ["clock"])。 此前account.rs自己实现了一套天元纪日 → 公历的换算(civil_from_days)⇒ 重复造轮子, 且与code.rs的时区口径不一致(一个 UTC 一个本地)⇒ 手工算法与它的推论一起删除。 - 口径写在代码注释里(不是只在文档里):谁想改时区,必须先改那处的注释 ⇒ 评审时看得见。
- ⚠️ 别把 Local 写成 UTC:业务编码、DB 审计列、账号层审计列都必须留在服务器本地时区, 否则同一时刻生成的编码与上游对不上(见上表第一行)。
- ⚠️ 别在别处手写
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 |
— | — | — | 无父外键 | — | 🔴 挂不了(见 §偏离) |
规矩:
- 🔴 挂载面逐父子不同,不是「都挂详情」——
Resource的子表只在/Detail聚合体(普通GET /{id}不带);DataInterface的子表只在普通详情(上游没有/Detail聚合体路由)。 - 🔴 父行取值列可以不是
f_id:参与方按平台任务号(f_tds_task_id)挂 ⇒ 任务没有平台任务号时,参与方是空集合(上游同口径,不是"查一次再判空")。 - 🔴 存活谓词逐表不同:四张「资源 / 接口」子表没有
f_delete_mark(上游物理删除) ⇒ 不加谓词;参与方表有 ⇒ 按本仓ALIVE过滤。 - 🔴 列表挂载是批量查(一次
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 的每一行仍是:
{ "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.mdL4。
角色码的悬空码(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/重建(探针只在首次建表时跑; 半途失败的迁移会留下「建了一半」的库 ⇒ 此后每次启动都跳过迁移)。