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