docs(spec): 对齐 spec 自审修订(词表以代码为准、库级 COMMENT 过时口径标注)

- §2.1/§5.1:登录主体 = 连接器身份,删除「另立本地用户/角色表」残留表述;
  补身份词表 f_status/f_register_status 实测取值
- §10.3/§10.6:标注 tdc_order.f_status、tdc_policy.f_priority 库级 COMMENT 为过时口径,
  明确以控制器常量 / ExecutionPolicyGate 源码为准
- §11.3:数据源类型词表对齐上游 SUPPORTED_TYPES(13 种,POSTGRESQL 非 POSTGRES,
  KAFKA/ES/OSS 不在其中);补 JDBC/API/FILE/SFTP/未实现分流与同步前置校验
- §5.1:f_register_status 引导值 APPROVED → REGISTERED

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-24 12:04:03 +08:00
1 parent 217c891d11
commit d03eedd959
1 file changed
+336 -67
@@ -57,7 +57,23 @@
`tdc_*` 存活 30 张(`tdc_resource_field` 曾删除后以完全不同的 7 列形状重建;`tdc_delivery_task` 35 → 99 列,
承载三套列名空间互不重叠的并行状态机)。
`tdc_demand` / `tdc_space` / `tdc_member` / `tdc_mask_rule` / `tdc_api_service` 及 7 张 dev-center 表**已下线**,不实现。
**30 张表全清单**(上游 box 快照与本地迁移产出逐一同名,零差异):
| 分组 | 表 |
|---|---|
| 身份与凭据 | `tdc_identity` `tdc_credential` |
| 数据接入 | `tdc_datasource` `tdc_sync_log` `tdc_resource` `tdc_resource_field` `tdc_resource_mask_rule` |
| 数据服务 | `tdc_data_interface` `tdc_data_interface_field` `tdc_data_interface_param` |
| 产品与合约 | `tdc_product` `tdc_policy` `tdc_policy_template` `tdc_policy_check_log` `tdc_contract` `tdc_order` |
| 交付 | `tdc_delivery_task` `tdc_delivery_task_participant` `tdc_delivery_log` `tdc_delivery_outbox` `tdc_api_consume_log` `tdc_destroy_log` |
| 执行 | `tdc_sandbox_exec_run` `tdc_privacy_exec_run` `tdc_p2p_session` |
| 通知与审计 | `tdc_notify` `tdc_audit_log` |
| 演示数据 | `tdc_demo_car_insurance` `tdc_demo_insurance_claims` `tdc_demo_pii` |
- 3 张 `tdc_demo_*`:**保留 DDL**(上游 box 快照含之,便于对账),但**无控制台入口、不灌演示数据**。
- `tdc_demand` / `tdc_space` / `tdc_member` / `tdc_mask_rule` / `tdc_api_service` 及 7 张 dev-center 表**已下线**,不实现。
- ⚠️ **无 `tdc_dataset` 表**(派生视图,见 §10.5)、**无 `tdc_file` 表**(文件走 `tdc_resource` + 本地文件目录)、
**无 `tdc_space` / `tdc_member`**(登录主体 = 连接器身份 `tdc_identity`,见 §5.1,**不另立用户/角色表**)。
### 2.2 API:18 个 CRUD 实体 + 约 130 个自定义动词
@@ -67,13 +83,24 @@ CRUD 实体(后端 `TdcCrudController` 子类):`ApiConsumeLog` `AuditLog`
`Dataset` **不是表**——是 `tdc_resource` 上的派生只读视图(见 §10.5),写操作一律失败。
**自定义动词的权威清单**(不靠估数,实施时逐条对齐):
| 来源 | 用途 | 权威性 |
|---|---|---|
| 上游 `frontend/web/src/views/ssw/api/tdc.ts`(512 行) | 控制台**实际调用**的端点全集 | **第一权威**(控制台要能跑通) |
| 上游 `boot/ssw-tdc/ssw-tdc-controller/**` | 后端**已实现**的端点全集 | 第二权威(补控制台未覆盖的) |
| 上游 `boot/ssw-tds/ssw-tds-controller/**`(45 个 Controller) | 平台侧端点 | 出向客户端依据(§8) |
⚠️ `tdc.ts` 中 `views/ssw/api/tdc.ts:339` 直接调**平台** `POST /api/ssw/tds/DeliveryTask/{tdsTaskId}/Algorithm/Void`
——Rust 控制台**不得**直连平台,必须由连接器后端代转(§8.4 `DeliveryTask/Internal/VoidAlgorithm`)。
### 2.3 语义(最容易做错的部分)
| 语义 | 新版口径 |
|---|---|
| 交付状态 | 平台唯一权威;连接器只上报事件 + 接受 `statusVersion` **严格更高**的推送 |
| 合约 | `tds_contract` 的镜像,带 `f_sync_status` / `f_content_hash` 防篡改 |
| 策略 | **无匹配即 DENY**(fail-closed),不是"没查到规则就放行" |
| 合约 | 平台合约在 `tdc_contract` 的**本地镜像**,带 `f_sync_status` / `f_content_hash` 防篡改;本地 id 与平台 `contractId` 是**两个不同的 id** |
| 策略 | 平台侧"按 target 缺动态权限行 ⇒ `RULE_DENY`"(fail-closed);连接器本地"无动态策略 ⇒ `NOT_APPLICABLE`(**非放行**,回退远程)" |
| 配额 | "已用量"从 `tdc_api_consume_log` 聚合,纪元哨兵 `1970-01-01`;**只有 API 类参与配额** |
| 审计日志 | **append-only + 哈希链**,禁止改 / 删 |
| 业务错误 | HTTP 200 + body `code != 200`,一律 fail-closed |
@@ -97,7 +124,7 @@ src/
session.rs X-Auth-Token 会话存储
registry.rs 18 实体 × 表元数据注册表
crud.rs 通用 CRUD 引擎
crypto.rs EC P-256 / HMAC / AES / SHA-256 / MD5
crypto.rs EC P-256 / HMAC / AES / SHA-256
audit.rs 审计哈希链 + 审计写入
tds.rs 类型化 TDS 出向客户端
policy.rs PolicyEngine + ExecutionPolicyGate
@@ -110,9 +137,11 @@ src/
topology.rs p2p.rs bridge.rs
routes/ 按域的 axum Router
static/
index.html app.js style.css migrate.sql
index.html app.js style.css
migrate.sql 生成产物(上游 30 张 tdc_* 表,唯一 schema 来源)
scripts/
gen-migrate.sh 迁移 → migrate.sql 生成器
gen-migrate.sh 上游迁移 → migrate.sql 生成器
reset-data.sh 清空 data/tdc.pg 重建
```
### 3.2 表注册表(`TdcCrudController` 的 Rust 等价物)
@@ -195,8 +224,41 @@ axum 层统一把业务错误转成 HTTP 200 + `code != 200`(**不**用 `Statu
| `require_internal_or_user` | `X-Internal-Token` **或** 已登录 | `auth.rs::require_internal_or_user` |
| `require_internal_only` | **只**认 `X-Internal-Token` | `auth.rs::require_internal_only` |
菜单权限:Java 侧按 Controller 类名匹配 JNPF 菜单 URL(双向 `startsWith`)。Rust 无 j7 ⇒ 用**声明式权限键**:
每个实体/端点在注册表里声明 `permission_key`(如 `product`),本地用户表持有角色→权限键映射。
菜单权限:Java 侧按 Controller 类名匹配 JNPF 菜单 URL(双向 `startsWith`),**依赖 JNPF `j7` 的菜单表**。
**Rust 侧的取舍(与上游的一处显式分歧)**:
上游 standalone TDC 的控制台菜单由 **JNPF 门户账号的角色**(`tdcProvider` / `tdcConsumer`)驱动,
而角色来自 `j7` 的 `base_role_relation` / `base_role` / `base_module_scheme` 三跳链路(§7.9)。
`j7` 已明确列为**不做**(§15)⇒ **不虚构本地用户/角色表**,改为:
- **登录主体 = 连接器身份**(忠实上游 `AuthController#login`):`identityCode` + `secretKey`,
凭据存在 `tdc_identity.f_identity_code` / `f_secret_key`(**30 张表内已有,不新增表**)。
- **权限 = 声明式权限键 + 连接器身份的角色集**。每个实体/端点在注册表里声明 `permission_key`
(如 `product` / `contract` / `delivery_task`);连接器身份的角色集由 `tdc_identity.f_capability`
解析(上游把能力存这里),解析不出 ⇒ **fail-open**(对齐 `SswPermissionGuard` 的"菜单未映射即放行"口径)。
- 控制台**不做按角色裁剪菜单**(无 j7 就没有角色体系),一律展示全部 TDC 模块;
权限键只用于**服务端二次校验**(写操作按权限键判定),不用于隐藏菜单。
- 审计操作人 = 登录的连接器身份(`f_identity_code` / `f_subject_id`),非登录态走 §5.4 的解析顺序。
⇒ **首次启动自动引导身份**(否则无法登录):若无存活 `tdc_identity` 行 ⇒ 建一条本地身份:
| 字段 | 取值 |
|---|---|
| `f_identity_code` | `TDC_IDENTITY_CODE`,缺省 `LOCAL-CONNECTOR` |
| `f_secret_key` | `TDC_IDENTITY_SECRET`,缺省**随机生成 32 字节十六进制**并**只打印一次**到 stdout |
| `f_name` / `f_subject_name` | `TDC_IDENTITY_NAME`,缺省 `本地连接器` |
| `f_status` / `f_register_status` | `ONLINE` / `REGISTERED` |
| `f_default_mark` | `1` |
⚠️ 随机密钥**只打印一次**、之后不可找回(只能 `Identity/{id}/RotateSecret` 重置)——与上游密钥轮换口径一致。
⚠️ 明文密钥**只落 `tdc_identity.f_secret_key` 一处**,不进日志、不回显给除登录外的任何端点。
(`Identity` 的查询走 `identity_view()` 去敏,`f_secret_key` **不在**回显字段里。)
⚠️ 身份词表(上游实证,别自造):
- `f_status` ∈ {`ONLINE`, `OFFLINE`, `FROZEN`}(`FROZEN` = 冻结,**登录时拒**)
- `f_register_status` ∈ {`UNREGISTERED`(库默认值), `REGISTERING`, `REGISTERED`, `REJECTED`, `FAIL`, `CANCELLED`}
(`REJECTED` / `CANCELLED` 是**拒态**,登录时拒)
- 实例上下文(`TdcInstanceContext`)取 `f_delete_mark IS NULL AND f_register_status <> 'CANCELLED'`
### 5.2 内部令牌
@@ -218,35 +280,113 @@ axum 层统一把业务错误转成 HTTP 200 + `code != 200`(**不**用 `Statu
⚠️ 细节:**只比 major,但 minor 解析失败会连累整体**(`"1.x"` ⇒ 不可解析 ⇒ 不兼容)。
`"1.2.3"` ⇒ minor 段 `"2.3"` 解析失败 ⇒ 不兼容。
- 拒绝时:**HTTP 401** + `{"code":401,"msg":"跨端协议版本不兼容(对端 X,本端 1.0),请升级对端","data":null}`。
- 拒绝时:**HTTP 401**。**两侧响应体不同,务必分开实现**:
| 侧 | 响应体 |
|---|---|
| **连接器入向**(Rust 要实现,`TdcAuthFilter.reject401`) | `{"success":false,"code":401,"msg":"跨端协议版本不兼容,请升级对端"}` |
| **平台入向**(Rust 调平台时看到,`AuthFilter.setError`) | `{"code":401,"msg":"跨端协议版本不兼容(对端 2.0,本端 1.0),请升级对端","data":null}` |
- ⚠️ **闸门只作用于 `X-Internal-Token` 通道**(跨端流量)。
白名单路径、`X-Auth-Token` 浏览器通道**都不过闸门**(JNPF 登录通道不实现,§5.4)。
- 一次性 WARN:`warnOnce` 语义,同一 key 只告警一次,上限 256 条。
### 5.4 用户态与操作人
- 登录:`POST /api/oauth/Login`(form-urlencoded `account` / `password` / `grant_type=password`)。
密码按 JNPF 口径加密:`md5(plain)` → AES-256-ECB/PKCS7(key = `md5("EY8WePvjM5GGwQzn")` 的 32 字节)→ hex。
返回 `{token, expiresIn, userInfo}`。
- 连接器自有会话:`X-Auth-Token`(`TdcSessionStore`,内存,**30 分钟 TTL**),控制台走这条。
- 操作人解析顺序:`X-Internal-Operator` header → 会话用户 → standalone 固定身份 → `"SYSTEM"`。
- **登录(唯一入口)**:`POST /api/ssw/tdc/Auth/Login`(**在白名单里**,免 `X-Internal-Token`)。
请求体 `{"identityCode": "...", "secretKey": "..."}`;服务端校验:
1. 身份存在(`f_delete_mark IS NULL`,`limit 1`);
2. 身份**已配置登录密钥** ⇒ 否则失败并提示"请先调用 `Identity/{id}/RotateSecret` 重置"(**不**笼统报"校验失败");
3. `secretKey` 相等(**常量时间比较**);
4. 身份状态可登录:`f_status != FROZEN` 且 `f_register_status ∉ {REJECTED, CANCELLED}`。
成功返回 `{token, identityId, identityCode}`,token **30 分钟 TTL**(内存 `TdcSessionStore`,进程重启即失效)。
- **不实现** `POST /api/oauth/Login`(JNPF 框架登录,依赖 j7 用户库 ⇒ 随 j7 一并排除)。
⇒ 相应地,§5.5 的"JNPF 登录态"通道在 Rust 侧**不存在**;`TdcAuthFilter` 的第 5 步不实现。
- **会话**:`X-Auth-Token` 头回带;控制台存 `localStorage`。
- **`GET /api/ssw/tdc/Auth/Me`**:返回当前登录身份(`identityId` / `identityCode` / `subjectId` / `subjectName` /
`capability` / 角色集),供控制台显示与权限键判定。**不返回** `secretKey` / `private_key`。
- **`GET /api/ssw/tdc/Auth/SsoConfig`**:返回 `{enabled:false, authorizeUrl:null, redirectUri:null}`
(MaxKey SSO 随 j7 一并排除 ⇒ fail-visible:明确告诉前端"没开",前端不显示入口)。
- 操作人解析顺序:`X-Internal-Operator` header → 会话身份(`f_identity_code`)→ standalone 固定身份 → `"SYSTEM"`。
`AuditContext` 取不到就**留 null**,不得写 `0` / `"system"` / `"unknown"`。
### 5.5 白名单(免鉴权)
### 5.5 连接器入向闸门(`TdcAuthFilter` 的 Rust 等价物)
`/api/health` · `/api/ssw/tdc/Portal/**` · `/api/ssw/tdc/Gateway/Invoke` ·
`/api/ssw/tdc/Gateway/ProviderInvoke` · `/api/ssw/tdc/Topology/Internal/TopologyCheck` ·
`/api/ssw/tdc/Auth/SsoConfig` · `OPTIONS` 预检。
**执行顺序**(照搬 `ssw/tdc/filter/TdcAuthFilter.java`):
```
1. OPTIONS 预检 → 放行
2. gateway.white-url 命中 → 放行(🔴 不过协议版本闸门)
3. X-Internal-Token == 本值 → 过协议版本闸门(不兼容 ⇒ HTTP 401)→ 放行
4. X-Auth-Token 有效 → 放行(🔴 不过协议版本闸门——不是跨端流量)
5. 都不满足 → HTTP 401
```
(上游第 5 步的 JNPF 登录通道**不实现**——j7 已排除,见 §5.4。)
**Rust 侧白名单**(对齐上游 `gateway.white-url`,Ant 风格):
```
/api/ssw/tdc/Auth/Login
/api/ssw/tdc/Auth/SsoConfig
/api/ssw/tdc/Gateway/Invoke
/api/ssw/tdc/Gateway/ProviderInvoke
/api/ssw/tdc/P2P/Handshake
/api/ssw/tdc/P2P/Transfer/Prepare
/api/ssw/tdc/P2P/Transfer/*/Chunk
/api/ssw/tdc/P2P/Transfer/*/Receipt
/api/ssw/tdc/P2P/Download/*
/api/ssw/tdc/Portal/**
/api/ssw/tdc/Topology/Internal/TopologyCheck
```
外加 `/api/health`(探活用)与 `OPTIONS`。
⚠️ 白名单路径**带自身业务认证**(数据面三件套 / 验证码 / 平台回调令牌),**不是裸奔**——
Rust 侧必须实现这些端点自己的认证,不得因为"在白名单里"就跳过。
**401 / 403 的响应体与信封不同**(上游如此,Rust 侧照抄,否则前端解析会错):
```json
{"success": false, "code": 401, "msg": "内部接口凭证无效"}
{"success": false, "code": 403, "msg": "仅管理员可管理连接器用户"}
```
⚠️ 注意:**没有 `data` 字段**,且多了 `success:false`。
这与 §4.1 的业务信封(`{code,msg,data}`)是两套形状——鉴权失败走 HTTP 状态码 + 裸三字段,
业务失败走 HTTP 200 + 完整信封。**必须分开实现。**
### 5.6 平台侧入向鉴权(联调前置条件,Rust 侧须知晓)
平台 `AuthFilter` 的"内部请求不拦截"分支读的是 **`SA-SAME-TOKEN`**,**不是** `X-Internal-Token`。
⇒ 调用平台的内部端点必须**同时**满足:
平台 `AuthFilter`(`boot/ssw-common/ssw-common-controller/.../filter/AuthFilter.java`)的执行顺序:
1. 路径已登记在平台 `gateway.white-url`(现有 **93 条**,已覆盖 TDC 现有全部调用);
2. 请求带 `X-Internal-Token`(由平台 controller 内的 `requireInternalOnly` / 内联比对校验)。
```
1. 协议版本闸门 —— 在白名单 stop() 之前,覆盖全部路径
2. block-url 拦截
3. SaRouter.match(gatewayWhite.getWhiteUrl()).stop() ← 白名单免 JNPF 登录
4. SaRouter.match(读 SA-SAME-TOKEN 且 SaSameUtil.isValid).stop() ← 同源令牌免登录
5. app-secret-url 校验
6. StpUtil.checkLogin() ← 兜底:要求 JNPF 登录
```
⚠️ **第 4 步读的是 `SA-SAME-TOKEN`(`jnpf.consts.AuthConsts.INNER_TOKEN_KEY`),不认 `X-Internal-Token`。**
⇒ 连接器调用平台的内部端点必须**同时**满足:
1. 路径**已登记**在平台 `gateway.white-url`(现有 **93 条**,已覆盖 TDC 现有全部调用)——
否则被第 6 步拦下,恒 `code=600`「登录过期,请重新登录」,
**带了对的 `X-Internal-Token` 也一样**(平台 `application.yml:329` 有实测记录:
`PUT /DataProduct/{id}/Submit` 未登记 ⇒ `code=600`;已登记的 `*/Offline` ⇒ 正常进 controller);
2. 请求带 `X-Internal-Token`(由平台 controller 内的 `requireInternalOnly` / `requireInternalOrUser` 校验)。
⇒ 平台端点是**双闸门**:white-url 放行 + controller 层令牌校验。white-url 里没有的路径,
Rust 侧**一律不调用**。
**Rust 侧若新增对平台的调用路径,平台侧必须同步加 white-url 行**,否则恒 `code:600`。
(本设计不新增平台端点,故无需改平台 white-url;若实施中发现缺失,单独记录并在联调前补齐。)
⚠️ 平台侧还有一条**平台内部回环**通道(`RemoteNaxComputeEngine` 打 `http://localhost:30001` 走
`SA-SAME-TOKEN`),那是平台自己的事,连接器**不涉及**、**不要**去发 `SA-SAME-TOKEN`。
---
## 6. 通用 CRUD 引擎
@@ -288,10 +428,12 @@ axum 层统一把业务错误转成 HTTP 200 + `code != 200`(**不**用 `Statu
| SHA-256 | `sha2` |
| HMAC-SHA256 | `hmac` |
| AES-256-ECB / AES-256-GCM | `aes` + `ecb` / `aes-gcm` |
| MD5(JNPF 登录密码口径) | `md-5` |
| Base64(标准字母表,带 padding) | `base64` |
| 常量时间比较 | `subtle` |
⚠️ **不需要 MD5**:MD5 只出现在 JNPF 登录口令加密链路(`utils/cipher.ts`),该链路随
`/api/oauth/Login` 一并排除(§5.4);`SswCryptoUtils` 本身不含 MD5。
### 7.1 `InternalTokenSupport`
见 §5.3。`is_internal(req, token)` 只读 header。
@@ -517,6 +659,19 @@ BillingLedger(6 个)。
| GET | `/api/ssw/tdc/Identity?currentPage=1&pageSize=1` | 平台探测连接器身份 |
| POST | `/api/ssw/tdc/Identity/AutoProvision` | 连接器自动建档 |
**回调 URL 的注册(易漏点)**:上表两行 `PUT {product.callbackUrl}` / `PUT {connector.callbackUrl}` 的
URL 是**平台侧存下来的配置**,不是固定常量。Rust 连接器必须:
1. 暴露**固定**路径:`/api/ssw/tdc/Product/{id}/PublishCallback` 与 `/api/ssw/tdc/Identity/{id}/RegisterCallback`;
2. 在**连接器注册**(§8.4 `Connector/Register`)时把本连接器的 callbackUrl 上报给平台;
3. 在**产品上架**(`Product/PublishToTds`)时把 `f_callback_url` 一并带给平台,平台落库后按该 URL 回推。
⇒ 平台回推的 URL 与 Rust 暴露的路径必须**逐字一致**,否则平台侧拿到 404。
Rust 侧从 `TDC_PUBLIC_BASE_URL`(缺省 `http://127.0.0.1:<PORT>`)拼出这两个 URL,注册与上架时上报。
**回推端点的幂等与去重**:平台对同一 `statusVersion` 可能重复回推(重试)。
Rust 侧按 §9.1 的 `statusVersion` 严格比较天然去重(重复版本号被忽略)。
### 9.1 权威状态下发 payload(`TradeOrderBridge/DeliveryTask/Status`)
平台按**接收方**逐份生成 payload。Rust 侧按 `selfConnectorId` / `selfRole` 定位自己的那一行。
@@ -547,49 +702,131 @@ BillingLedger(6 个)。
### 10.1 交付任务
- 状态集合:`PENDING` `RUNNING` `DELIVERED` `COMPLETED` `FAIL` `CANCELLED`;终态 = `{COMPLETED, CANCELLED}`。
- 参与方:`initStatus` {PENDING/CREATED/FAILED/BLOCKED}、`readyStatus` {NONE/READY/READY_SIMULATED/FAILED}、
`deliverStatus` {PENDING/RUNNING/DELIVERED/FAIL/CANCELLED}、`destroyStatus` {NONE/DONE}。
- **任务状态**(`DeliveryTaskStatus`,6 态):`PENDING`(待初始化)→ `RUNNING`(执行中)→
`DELIVERED`(已交付,**待使用方确认,稳定态非终态**)→ `COMPLETED`(已完成);
异常路径 `FAIL`(可被 `RE_DELIVERY_STARTED` 复位)/ `CANCELLED`(终局)。
**终局集合 `TERMINAL = {COMPLETED, CANCELLED}`**(`DELIVERED` 不在内)。
- **参与方**(`tdc_delivery_task_participant`):
- `f_role`:`PROVIDER` / `CONSUMER`(⚠️ 常量名叫 `ROLE_PROVIDER`/`ROLE_CONSUMER`,**值不带 `ROLE_` 前缀**);
- `f_init_status`:`PENDING` / `CREATED` / `FAILED` / `BLOCKED`;
- `f_ready_status`:`NONE` / `READY` / `READY_SIMULATED` / `FAILED`;
- `f_deliver_status`:`PENDING` / `RUNNING` / `DELIVERED` / `FAIL` / `CANCELLED`;
- `f_destroy_status`:`NONE` / `DONE`;
- `f_engine_mode`:`REAL` / `SIMULATED`。
- `READY_SIMULATED` **不得当作"就绪"**。
- 引擎模式 `REAL` / `SIMULATED` / `FAILED`;`f_sync_stale` 标记本地模拟。
- `f_sync_stale` 标记本地模拟(单机模式)。
### 10.2 合约
- 状态码:`01` 待签署 / `02` 已生效 / `0301` 变更中 / `0302` 变更完成 / `05` 已终止 / `06` 已过期。
- **"可发起交付"只认 `02` / `0302`**(不含 `0301`);"存续"口径 `02`/`0302`/`0301`;
"动态权限生效"只认 `02`/`0302`。
- 策略规则的合约状态判据**只接受 `"02"` / `"0302"`**。
- 状态码(`ContractEntity` 常量):`01` 待签署 / `02` 已生效 / `0301` 变更中 /
`0302` 变更完成 / `05` 已终止 / `06` 已过期。
- **"可发起交付"只认 `02` / `0302`**(**不含 `0301`**)——三处独立判据一致:
`ExecutionPolicyGate` 规则 2、`TdsReportClient:1822`、订单 ticker 的合约生效前置。
- `05` / `06` ⇒ 合约终止/过期,**拒绝一切新动作**(`ContractController:154`)。
- 合约同步 ticker 的拉取集 = `01` / `02` / `0301` / `0302`(`ContractSyncTicker:57`)。
### 10.3 订单
`PENDING → APPROVED/REJECTED → CONFIRMING → CONFIRMED → SIGNING_A/SIGNING_B → SIGNED → TO_DELIVER → DELIVERING → COMPLETED`(+ `CANCELLED`)。
`SIGNED → TO_DELIVER` 由 **CAS ticker** 完成,**不是**用户动作。
状态集(`OrderController` 常量,**9 个**,无 `CONFIRMED` / 无 `SIGNING_A|SIGNING_B`):
```
PENDING ──Approve──▶ APPROVED ──ConfirmPayment──▶ CONFIRMING ──Sign──▶ SIGNED
└──Reject──▶ REJECTED
SIGNED ──(CAS ticker)──▶ TO_DELIVER ──▶ DELIVERING ──▶ COMPLETED
(另有 CANCELLED)
```
- 每个跃迁都有**前置态校验**,不满足即 `ActionResult.fail("订单当前状态不允许…")`(HTTP 200 + `code=400`)。
- ⚠️ **库级 COMMENT 是过时的**:`tdc_order.f_status` 的 COMMENT 列了 **12** 个值
(含 `CONFIRMED` / `SIGNING_A` / `SIGNING_B`),但 `OrderController` 的常量**只有 9 个**,那三个**不存在**。
**以控制器常量为准,不建 `CONFIRMED` / `SIGNING_*` 状态、不写相关跃迁分支。**
- **`SIGNED → TO_DELIVER` 由 `TdcOrderSignTicker` 的 CAS 完成,不是用户动作**:
- 前置:拉到合约且 `status == "02"`(缺一方签 ⇒ 等下一轮,不动);
- CAS:`UPDATE tdc_order SET f_status='TO_DELIVER' WHERE f_id=? AND f_status='SIGNED'`
⇒ 受影响 0 行则跳过(防并发重复建任务)。
- standalone 模式下**只改订单状态,不本地建任务**——交付由平台 TDS 桥编排并回填 `order.deliveryTaskId`。
- `TO_DELIVER` / `DELIVERING` → `COMPLETED` 由 `OrderServiceImpl.completeByDelivery` 兜底。
### 10.4 产品
两个**正交**维度:`f_status`(上架维度)· `f_publish_status`(审核维度)。
**升级驳回不得把已 PUBLISHED 的产品下架**。
平台侧产品状态:`DRAFT` / `PENDING` / `ONLINE` / `OFFLINE` / `REJECTED` / `DESTROYED`。
两个**正交**维度:
| 列 | 语义 | 取值 |
|---|---|---|
| `f_status` | 资源启停 | `ENABLED` / `DISABLED` |
| `f_publish_status` | 发布/审核态 | `DRAFT` / `PUBLISHING` / `PUBLISHED` / `OFFLINE` / `REJECTED` |
- **审核驳回不得把已 `PUBLISHED` 的产品下架**(驳回只改 `f_publish_status`,`f_status` 不动)。
- **平台侧**产品状态是另一套词汇:`DRAFT` / `PENDING` / `ONLINE` / `OFFLINE` / `REJECTED` / `DESTROYED`
⇒ 出向映射时**逐个显式转换**,不要假设两套同名同义。
### 10.5 Dataset(派生只读视图)
无 `tdc_dataset` 表。谓词:
`alive ∧ f_status='ENABLED' ∧ (f_source_kind='DATASOURCE' OR f_source_kind IS NULL) ∧ f_mount_status='MOUNTED' ∧ f_dataset_name IS NOT NULL ∧ EXISTS(enabled datasource)`。
**写操作一律失败。**
无 `tdc_dataset` 表。**复用 `tdc_resource`**(`DatasetController extends TdcCrudController<ResourceEntity>`),
谓词(判据单点):
```
alive
∧ f_status = 'ENABLED'
∧ (f_source_kind = 'DATASOURCE' OR f_source_kind IS NULL) ← 必须写全,NULL 视作 DATASOURCE
∧ f_mount_status = 'MOUNTED'
∧ f_dataset_name IS NOT NULL
∧ EXISTS (SELECT 1 FROM tdc_datasource d
WHERE d.f_id = tdc_resource.f_datasource_id
AND d.f_status = 'ENABLED' AND (d.f_delete_mark IS NULL OR d.f_delete_mark = 0))
```
- **关键词列 = `f_dataset_name`**(不是 `f_name`)。
- 三个写端点**真拒**,报文固定:`ActionResult.fail("数据集为只读视图,不支持新增/编辑/删除")`
⇒ `code=400`,`data=null`。**不得**让基类的 `POST` 顺手造一条 `tdc_resource`。
### 10.6 策略(fail-closed)
`ExecutionPolicyGate` 是**唯一**决策点,14 条规则;决策 `ALLOW` / `DENY` / `LIMIT` / `OBLIGATION` / `NOT_APPLICABLE`;
拒绝码 `INVALID_POLICY` / `INVALID_CONTRACT` / `EXPIRED` / `RULE_DENY` / `QUOTA_EXCEED` / `COUNTER_UNAVAILABLE`。
**无匹配策略 ⇒ DENY**(不是放行)。
`PolicyTemplate` 只有 2 种策略类型:`startTimeLimit` / `ipWhitelistLimit`,**最多 2 项**。
**连接器本地**(`ExecutionPolicyGate`,**唯一**本地决策点):
- 规则表 **14 条**,`RULE_NAMES` 与 `RULES` **按下标一一对应**(新增必须追加在**末尾**,否则后续拒因名字整体错位):
`POLICY_VALID` `CONTRACT_STATUS` `CONTRACT_EXPIRE` `VALID_UNTIL` `TARGET_GUARD` `USE_COUNT` `DURATION`
`EXPORT` `FIELD_SCOPE` `VOLUME` `AGGREGATE` `RATE_QPS` `RATE_FREQUENCY` `CONTRACT_QUOTA`。
- 决策取值域固定:`ALLOW` / `DENY` / `LIMIT` / `OBLIGATION` / `NOT_APPLICABLE`。
`allowed()` = `ALLOW | LIMIT | OBLIGATION`。
- 拒绝码:`INVALID_POLICY` / `INVALID_CONTRACT` / `EXPIRED` / `RULE_DENY` / `QUOTA_EXCEED` / `COUNTER_UNAVAILABLE`。
- **执行顺序**:
1. `in == null` ⇒ `NOT_APPLICABLE`("无判定输入");
2. `dynamicPolicy` 为 null/blank ⇒ **`NOT_APPLICABLE`**("本地无动态策略")——
⚠️ **不是 DENY**;本地判不了,调用方**回退远程**(平台)判。本地判定**永不等于放行**。
3. `dynamicPolicy` JSON **解析失败** ⇒ `DENY` / `RULE_DENY`("动态权限解析失败: …",安全兜底);
4. 规则**逐条**跑(按 `deliveryType` 的类型闸门跳过不适用项),**第一条产出 Deny 立即返回 DENY**
并在 `detail.rule` 记规则名;
5. 全部通过 ⇒ 放行,并装配义务(`outputFields` / `maxRows` / `aggregation` …)。
- 规则 1(`POLICY_VALID`):`policy` 是**空对象**(`{}`)或 JSON null ⇒ `INVALID_POLICY`
("动态履约策略为空/无效(不得视为无约束放行)");`policy == null`(Java null)交由第 2 步处理。
⚠️ **库级注释是过时的,照着它实现必错**:`tdc_policy.f_priority` 的 COMMENT 写的是
"任一 DENY 即整体拒绝, **无匹配策略时兜底拒绝**"——这是**旧口径**。
现行代码口径是第 2 步:本地无动态策略 ⇒ **`NOT_APPLICABLE`**,**不是**拒绝,也不是放行。
**以 `ExecutionPolicyGate` 源码为准,不以 schema COMMENT 为准。**
**平台侧**(`ContractDynamicPermissionServiceImpl`):合约配了动态条款、但某个 target **没有对应的
动态权限行** ⇒ `RULE_DENY`("按 target 缺行=拒");合约配了动态条款却整体没生成权限行 ⇒ `RULE_DENY`
("绝不误放行本该有约束的合约")。参与方服务未就绪、判不出合约形态 ⇒ `RULE_DENY`(fail-closed)。
**`PolicyTemplate`**:策略类型白名单**只有两类**——`startTimeLimit` / `ipWhitelistLimit`
(`callLimit` / `accessTimeLimit` **本批不做**,不得进白名单);同类不可重复,**上限 2 项**
(`MAX_STRATEGY_ITEMS = 2`);模板名 ≤ 200 字符。
### 10.7 配额
两级解析:`f_quota_total` → `termsContent.callRules.<termsKey>`;都没有 ⇒ "未约定" ⇒ **降级(不拦)**。
**只有 API 参与配额**(`DeliveryMetric.quota_applies`)。"已用量" = `f_quota_anchor_at` 之后的
`tdc_api_consume_log` 聚合(纪元哨兵 `1970-01-01`);`f_contract_id` 用 **TDS 合约 id**(不是本地副本 id)。
台账三列:`quantity` / `normalQty = min(u, tier)` / `excessQty = max(0, u - tier)`。
- **阈值两级链**(`ContractQuotaService`):① `tdc_contract.f_quota_total`(签约落值)→
② `termsContent.callRules.<termsKey>`(条款解析)。
⚠️ `null` / **`≤ 0`** 一律视为"**未约定**" ⇒ **降级不拦**(**不是**"配额 0 ⇒ 全拒")。
⚠️ `f_quota_total` 是"一类合约一列",语义随该合约交付类型(次数 / 字节)。
两级都无 ⇒ `Source::NONE` ⇒ 不限。
- **参与判据唯一入口**:`DeliveryMetric.quota_applies(deliveryType)` ⇒ **只有 API 参与配额**。
- "已用量" = `f_quota_anchor_at` 之后的 `tdc_api_consume_log` 聚合(纪元哨兵 `1970-01-01`);
`f_contract_id` 用 **TDS 合约 id**(不是本地副本 id)。
- ⚠️ **分档台账(`quantity` / `normalQty = min(u, tier)` / `excessQty = max(0, u - tier)`)是平台侧的**
(`BillingLedgerEntity`,在 `ssw-tds` 仓)。连接器**只**算用量并上报(`UsageMetric/Report`),
**不建账本表**、不自行分档。
### 10.8 审计
@@ -624,14 +861,25 @@ append-only + 哈希链。`tdc_audit_log` 禁止改 / 删。链指纹与载荷
### 11.3 数据源探活 / 同步(不伪装成功)
| 类型 | 行为 |
|---|---|
| `API` | **真探活**(HTTP) |
| `FILE` | **真读** |
| `POSTGRES` | **真连**(`tokio-postgres`) |
| `MYSQL` / `ORACLE` / `SQLSERVER` / `DM` / `KINGBASE` / `HIVE` / `KAFKA` / `MONGODB` / `ES` / `SFTP` / `OSS` | **明确返回"本部署未实现该类型探活"**(HTTP 200 + `code:400` + 真实原因),**不返回假 SUCCESS** |
对齐上游 `DatasourceController.SUPPORTED_TYPES`(**13 种**,`GET /api/ssw/tdc/Datasource/Types` 原样返回该列表):
`MYSQL / POSTGRESQL / ORACLE / SQLSERVER / DM / KINGBASE / CLICKHOUSE / DORIS / HIVE / MONGODB / API / FILE / SFTP`。
同步:仅 `POSTGRES` / `API` 真同步(枚举真实表/字段 → 生成 `tdc_resource` + `tdc_resource_field`)。
⚠️ 是 **`POSTGRESQL`** 不是 `POSTGRES`;`KAFKA` / `ES` / `OSS` **不在**支持列表内。
⚠️ `tdc_datasource.f_type` 是 `varchar(20)` 无 CHECK 约束(库级注释还是旧词表 `MYSQL/POSTGRES/.../OSS`)⇒ **校验责任全在应用层**,Rust 侧必须照 `SUPPORTED_TYPES` 拦,写入非白名单类型返回上游同款 `"不支持的数据源类型: X"`。
| 上游分类 | 类型 | 上游行为 | 本部署行为 |
|---|---|---|---|
| JDBC 直连(8) | `MYSQL` / `POSTGRESQL` / `ORACLE` / `SQLSERVER` / `DM` / `KINGBASE` / `CLICKHOUSE` / `DORIS` | 真 JDBC 探活(连接超时 5s) | 仅 `POSTGRESQL` 真连(`tokio-postgres`);其余 → **明确返回"本部署未实现该类型探活"** |
| API | `API` | 真 HTTP 探活 | 同上游(真探活) |
| 文件 | `FILE` / `SFTP` | `FILE` 真读本地文件;`SFTP` 真连 + 远端文件可读 | `FILE` 真读;`SFTP` → 未实现(无 jsch 等价物) |
| 未实现 | `HIVE` / `MONGODB` | 上游也返回 `"该类型暂不支持探活: X"` | 同上游 |
「未实现」一律走 HTTP 200 + `code:400` + 真实原因文案,**不返回假 SUCCESS**。
同步:上游 `isReadableType` = `JDBC_TYPES ∪ {FILE, API, SFTP}`。本部署只让 `POSTGRESQL` / `API` 真同步(枚举真实表/字段 → 生成 `tdc_resource` + `tdc_resource_field`);
其余返回上游同款 `"该类型数据源同步链路待实现: X"`;且**必须先 `testStatus == SUCCESS` 才允许同步**(上游同款前置校验)。
连接型数据源(`CONNECTION_TYPES` = JDBC 8 种 + `HIVE` + `MONGODB`)额外要求 `host` / `port` / `dbName` 必填(上游 TC_DS_003 校验)。
---
@@ -660,7 +908,14 @@ append-only + 哈希链。`tdc_audit_log` 禁止改 / 删。链指纹与载荷
| 与上游 box 快照 `deploy/box-pg/schema/tdc_box.sql` 对账 | **逐一同名,零差异** |
| 合并 DDL | 92 KB |
### 12.3 初始化语义(沿用现有约定)
### 12.3 本地扩展 DDL
**无**。30 张 `tdc_*` 表之外**不新增任何表**:
登录凭据、连接器身份、公私钥都在 `tdc_identity` 里(§5.1);本地用户/角色表因 j7 排除而不虚构(§5.1)。
⇒ `static/migrate.sql` 是**唯一**的 schema 来源,可由 `scripts/gen-migrate.sh` 全量重生成而不丢任何东西。
### 12.4 初始化语义(沿用现有约定)
- 启动探测 `tdc_identity` 是否存在;不存在才执行 `migrate.sql`。
- **schema 变更 ⇒ 必须清空 `data/tdc.pg` 重建**(`CREATE TABLE IF NOT EXISTS` 不会改已有表)。
@@ -677,17 +932,29 @@ append-only + 哈希链。`tdc_audit_log` 禁止改 / 删。链指纹与载荷
### 13.1 API 层
- 统一走 `/api/ssw/tdc/*`;请求头 `App-Code: sswflow` / `Jnpf-Origin: pc` / `Vue-Version: 3` +
`X-Auth-Token`(连接器会话)优先,否则 `Authorization: bearer <jnpf token>`。
`X-Auth-Token`(连接器会话)。
(**不带** `Authorization: bearer`——JNPF 登录通道不实现,§5.4。)
- 响应拦截器口径(照搬上游 Vue 版 `request.ts`):
`code === 600` → 清 token 跳登录;`code !== 200` → 抛 `body.msg`;否则取 `body.data`。
另:`HTTP 401` 同样视作未登录。
另:`HTTP 401` 同样视作未登录(注意 401 的 body **没有 `data`**、多了 `success:false`,见 §5.5)。
- 列表读 `res.list`(兼容 `res.records` / 裸数组)+ `res.pagination.total`。
- 分页参数名 `currentPage` / `pageSize`。
### 13.2 页面
- **登录页**:`POST /api/oauth/Login`,密码按 JNPF 口径加密(§5.4)。
- **30 表**通用 CRUD(按表注册表驱动)+ 按域生命周期动作(发布/下架/审核、订单流转、合约生效/终止/变更/协商、
- **登录页**:`POST /api/ssw/tdc/Auth/Login`,填 **连接器身份编码 + 登录密钥**(§5.4)。
密钥**明文**输入(连接器本地控制台,不走浏览器加密那一套)⇒ **不实现** JNPF 的
`AES-ECB` 口令加密链路(那只服务于 `/api/oauth/Login`,已随 j7 排除)。
登录成功把 `token` 存 `localStorage`,后续请求带 `X-Auth-Token`;`GET /Auth/Me` 拿身份信息做顶栏。
- **表清单**(30 张 `tdc_*` + 派生的 `Dataset` 视图)按表注册表驱动通用 CRUD:
- **可编辑**:Identity / Datasource / Resource / DataInterface / Product / Policy / PolicyTemplate /
Credential / Contract / Order / DeliveryTask(受限);
- **只读**(系统写入,控制台仅查阅):ApiConsumeLog / AuditLog / DeliveryLog / PolicyCheckLog /
DestroyLog / Notify / SyncLog / DataInterfaceField / DataInterfaceParam / ResourceField /
ResourceMaskRule / DeliveryTaskParticipant / DeliveryOutbox / SandboxExecRun / PrivacyExecRun /
P2PSession;
- **隐藏**(无控制台入口):3 张 `tdc_demo_*`。
- 按域生命周期动作(发布/下架/审核、订单流转、合约生效/终止/变更/协商、
交付任务策略校验/完成/取消/销毁、策略与模板、凭据签发/吊销、数据源探活/同步、资源挂载/分级/脱敏、数据接口预览)。
- 展示**审计哈希链校验**结果(`AuditLog/Verify`)。
- 常驻**本地单机模式提示**条(§11.1)。
@@ -699,10 +966,10 @@ append-only + 哈希链。`tdc_audit_log` 禁止改 / 删。链指纹与载荷
| 阶段 | 交付 | 验收 |
|---|---|---|
| **P0** schema + 模块拆分 | 30 表 `migrate.sql`(生成)、字面量感知切分器、`src/` 模块化、`scripts/gen-migrate.sh`、`scripts/reset-data.sh` | 启动建表成功;`/api/health` 报 30 表;`data/` 可重置重建 |
| **P1** 契约骨架 | 信封 / 三道门 / 协议版本闸门 / 通用 CRUD 引擎 / 18 实体注册表 / 登录与会话 / 权限键 | 18 实体 CRUD 全部符合新版信封与软删语义;协议不兼容返 HTTP 401 |
| **P2** 纯本地域端点 | Identity / Datasource / Resource / Dataset / Product / Order / Policy / PolicyTemplate / Credential / DataInterface / AuditLog / DeliveryLog / PolicyCheckLog / Notify / DestroyLog / ApiConsumeLog / File | 各域自定义动词可用;审计哈希链可校验;探活不返回假成功 |
| **P3** 状态机与交付域 | DeliveryTask + participant / Contract 状态机与本地签名 / ExecutionPolicyGate / 配额聚合 / 计量 / outbox | 状态流转按 CAS + `statusVersion`;**无匹配策略 DENY**;只有 API 参与配额 |
| **P0** schema + 模块拆分 | 30 表 `migrate.sql`(生成)、字面量感知切分器、`src/` 模块化、`scripts/gen-migrate.sh`、`scripts/reset-data.sh` | 启动建表成功;`/api/health` 报 30 张表;`data/` 可重置重建;生成脚本可重放 |
| **P1** 契约骨架 | 信封 / 三道门 / 协议版本闸门 / 通用 CRUD 引擎 / 18 实体注册表 / 身份登录与会话 / 权限键 / 首次启动身份引导 | 18 实体 CRUD 全部符合新版信封与软删语义;协议不兼容返 HTTP 401;`Auth/Login` 拿到 `X-Auth-Token`;首次启动自动引导身份并打印一次密钥 |
| **P2** 纯本地域端点 | Identity / Datasource / Resource / Dataset / Product / Order / Policy / PolicyTemplate / Credential / DataInterface / AuditLog / DeliveryLog / PolicyCheckLog / Notify / DestroyLog / ApiConsumeLog / File(上传落本地目录 + `tdc_resource`,无 `tdc_file` 表) | 各域自定义动词可用;审计哈希链可校验;探活不返回假成功 |
| **P3** 状态机与交付域 | DeliveryTask + participant / Contract 状态机与本地签名 / ExecutionPolicyGate / 配额聚合 / 计量 / outbox | 状态流转按 CAS + `statusVersion`;本地无策略 ⇒ `NOT_APPLICABLE`(**非放行**)回退远程;只有 API 参与配额 |
| **P4** TDS 出向客户端 | 类型化 TDS 客户端(§8.4)+ 三个签名单独实现(心跳 / 交付事件 / 数据面) | 对真 TDS 打通注册 / 心跳 / 产品上架 / 合约;D1–D4 缺陷已修 |
| **P4.5** 平台反向回调 | §9 全部入向端点 | 平台能推权威状态,连接器按 `statusVersion` 接受;不兼容版本拒绝 |
| **P5** 数据面与引擎 | Gateway/Invoke + ProviderInvoke + DataInterface 执行器 + 真实探活/同步 + Portal + Topology + P2P + 引擎作业(本地进程或显式降级) | 签名校验 + 策略闸门 + 计量落库闭环;`READY_SIMULATED` 不当就绪 |
@@ -720,8 +987,9 @@ P5 的策略闸门依赖 P3;P6 依赖全部后端阶段。
| Go `connector-agent/`(盒端 agent) | 独立仓,独立语言 |
| Python `nax/` + Ray 隐私计算 | 需 Ray 集群;本地做"诚实降级" |
| Vue 3 前端(`frontend/web/`) | 沿用静态控制台(§13) |
| MaxKey SSO | 用本地账号口令替代;`Auth/SsoConfig` 返回 `{enabled:false}`(fail-visible,不显示入口) |
| JNPF `j7` 331 张框架表 | 只保留**最小本地用户/角色表**支撑登录与权限键 |
| MaxKey SSO | `Auth/SsoConfig` 返回 `{enabled:false}`(fail-visible,不显示入口);不实现 `grant_type=maxkey` |
| JNPF `j7` 331 张框架表 | 不实现,也不虚构本地替代表;登录改用**连接器身份**(`identityCode` + `secretKey`,§5.4) |
| JNPF `/api/oauth/Login` | 随 j7 一并排除(框架登录,依赖 j7 用户库) |
| K8s / kata / flannel / vnet | 无集群;接口形状保留 |
| TDS 平台侧 | 独立仓,独立部署 |
| 旧 `/api/db/*` · `/api/ssw/tdc/node/identity*` · `/api/ssw/tdc/tds/*` | 全部换成新版契约(已批准) |
@@ -771,10 +1039,11 @@ P5 的策略闸门依赖 P3;P6 依赖全部后端阶段。
## 17. 验收
1. `cargo build --release` 通过;二进制仍为**单文件、零外部服务**。
2. 启动后 30 张 `tdc_*` 表就绪;`data/` 可重置重建。
2. 启动后 30 张 `tdc_*` 表就绪;`data/` 可重置重建;首次启动自动引导一个连接器身份并打印一次登录密钥。
3. 18 个实体的 CRUD 响应形状与新版**逐字段**一致(`{code,msg,data}` + `{list,pagination}` + camelCase)。
4. 协议版本不兼容 ⇒ HTTP 401 + `code:401`;未声明 ⇒ 放行 + 一次性 WARN。
5. 策略**无匹配即 DENY**;只有 API 参与配额。
5. 策略判定:本地无动态策略 ⇒ `NOT_APPLICABLE`(**非放行**,回退远程);空/无效策略 ⇒ `INVALID_POLICY` DENY;
解析失败 ⇒ `RULE_DENY` DENY;只有 API 参与配额。
6. 交付状态**只**由平台推送(`statusVersion` 严格更高)驱动,本地不裁决(单机模式除外且显式标记)。
7. 12 个协议类的 Rust 实现与 Java 实现在**同一输入上产生逐字节相同的输出**(对拍测试,见 §18)。
8. 对真 TDS 完成:连接器注册 → 心跳(签名验过)→ 产品上架 → 合约创建/签署 → 交付任务下发 → 权威状态回推闭环。