diff --git a/docs/superpowers/specs/2026-10-24-tdc-rs-align-v2-design.md b/docs/superpowers/specs/2026-10-24-tdc-rs-align-v2-design.md index 91e437d..eccb8cc 100644 --- a/docs/superpowers/specs/2026-10-24-tdc-rs-align-v2-design.md +++ b/docs/superpowers/specs/2026-10-24-tdc-rs-align-v2-design.md @@ -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:`)拼出这两个 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`), +谓词(判据单点): + +``` +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.`;都没有 ⇒ "未约定" ⇒ **降级(不拦)**。 -**只有 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.`(条款解析)。 + ⚠️ `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 `。 + `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 完成:连接器注册 → 心跳(签名验过)→ 产品上架 → 合约创建/签署 → 交付任务下发 → 权威状态回推闭环。