Files
tdc-rs/docs/contract.md
T
admin 4b32b40bd6 feat(tds): 同步 ssw-tdc 最新 internal 契约并完成真 TDS 联调验证
- 协议版本收敛为单一常量 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
2026-11-05 17:53:15 +08:00

33 KiB
Raw Blame History

对外契约(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.md L7 (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):

  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 的每一行仍是:

{ "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/ 重建(探针只在首次建表时跑; 半途失败的迁移会留下「建了一半」的库 ⇒ 此后每次启动都跳过迁移)。