Files
tdc-rs/MIGRATION.md
T
admin 3271732e8b feat(engine): 接入执行层与三入向端点,打通 Exec/Start 链路
- 新增 engine 模块(状态机/配置/SHA256摘要/进程拉起/状态):ACCEPTED→控制面→ET→Ray→MPC→终态
- 新增 controller/exec.rs:SelfCheckStatus/Dev/Artifact/Exec/Start + Exec/Status,handler 内复核内部令牌与协议版本
- 新增 client/mpc_control_plane.rs:GET /nodes /sessions /report 与 POST /desired,Bearer 鉴权
- 平台 nax 语义落地(rayHead 当 GCS、mpc 为算子执行体),密钥不落状态/回执/日志
- 海光控制面地址 192.168.1.102 → .23(运行态配置)
- tests/exec_endpoints.rs 6 条契约用例;MIGRATION.md §1.7.1 记录范围
2026-11-13 19:38:48 +08:00

268 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MIGRATION —— Java TDC ⇄ Rust `tdc-rs` 逐件翻译表
> 🔴 本文件回答两个问题:
> ① **上游那个类 / 那个方法,在本仓对应哪个文件哪一行?**
> ② **从上游 Java 版迁到本仓,数据与口令怎么搬?**
>
> **上游真源**(只读克隆):`/tmp/sswtdc-probe/boot/ssw-tdc/`
> (更早的 `~/Desktop/workspace/ssw-mvp/boot/ssw-tdc` **已过时**,别引用)。
>
> **写法范式**:每条结论带 `文件:行号` + 一致/偏差 + 偏差是否刻意
> (与本仓既有的上游核对报告 `docs/superpowers/2026-10-26-tdc-rs-upstream-diff.md` 同款,**不另立格式**)。
**图例**:✅ 一致 · ⚠️ **刻意偏差** · ❌ **未实现**(在「明确不在范围」里)
---
## 1. 逐件翻译表
### 1.1 通用 CRUD 引擎(18 个实体共用)
| 上游 | 本仓 | 结论 |
|---|---|---|
| `ssw-tdc-controller/…/controller/TdcCrudController.java:57` | `src/tdc/entity/mod.rs`(`TableSpec` 注册表)+ `src/tdc/service/crud.rs` | ✅ **不是逐类抄**,是**声明式注册表**:18 个实体各自声明元数据,引擎**零 `match api_name`** |
| `TdcCrudController.java:83` `keywordColumns()` | `src/tdc/entity/*.rs` 的 `keyword_columns` | ✅ 逐实体抄(2026-10-24 全量脚本核对,零差异) |
| `TdcCrudController.java:88` `filterColumns()` | `src/tdc/entity/*.rs` 的 `filter_columns` | ✅ 同上 |
| `TdcCrudController.java:96` `tenantColumn()` | `TableSpec::tenant_column` | ✅ |
| `TdcCrudController.java:101` `defaultOrderColumn()` | `TableSpec::default_order_column` | ✅ |
| `TdcCrudController.java:133` `requireMenuPermission()` | `src/platform/auth.rs:243`(`require_menu_permission`) | ✅ 同构:内部令牌 **或** 有登录态(上游 `permissionGuard == null` 时也只校验这两样) |
| `TdcCrudController.java:174/190/199/210/231/252`(六个动作都先 `requireMenuPermission()`) | `src/tdc/service/crud.rs:213/282/467/524/672/772/831` | ✅ **读四个 + 写三个**共用**同一个**闸门 |
| `TdcCrudController.java:274` 租户列过滤 | `src/tdc/mapper.rs` | ✅ |
| `TdcCrudController.java:284` 过滤列拼装 | `src/tdc/mapper.rs` | ⚠️ **刻意偏差**:本仓一律 `CAST(col AS TEXT) = $1`(上游把 varchar 绑给 smallint 列会 PG 报错) |
| `TdcCrudController.java:292` 关键字列拼装 | `src/tdc/mapper.rs` | ✅ |
| `TdcCrudController.java:304` 默认排序 | `src/tdc/mapper.rs` | ✅ |
| 上游 `ssw.tdc.entity.*Entity`(26 个类) | `src/tdc/entity/*.rs`(18 个 spec) | ⚠️ 18 个实体有控制器;其余 8 个是**子表 / 示例表 / 排除范围** |
### 1.2 实体与表(逐名对账)
| 上游实体类 | 表 | 本仓 spec | 结论 |
|---|---|---|---|
| `entity/IdentityEntity.java:26` | `tdc_identity` | `src/tdc/entity/identity.rs` | ⚠️ **双读写路径**:引擎路径 `SELECT *` + 领域路径只 SELECT 明确列(`src/tdc/service/identity.rs`)⇒ 记 `docs/known-limitations.md` **L1** |
| `entity/IdentityEntity.java:111`(`@JsonIgnore` 的 SK) | `tdc_identity.f_secret_key` | `src/tdc/entity/identity.rs` 的 `hidden_fields` | ✅ 出参**整条删键**(不是置 null),入参静默忽略 |
| `entity/ProductEntity.java:88`(`BigDecimal f_price`) | `tdc_product.f_price` | `src/tdc/entity/product.rs` | ✅ 输出 **JSON 数字**(D16:上游无 `@JsonSerialize` ⇒ Jackson 默认 ⇒ 数字) |
| `entity/CredentialEntity.java` 的 `secretKey` | `tdc_credential` | `src/tdc/entity/credential.rs` | ⚠️ **本仓比上游更严**:多去敏一个字段(`check-entity.sh` 的 E4 认这个) |
| `entity/DeliveryTaskEntity.java` 的 `devUrl` / `devToken` | `tdc_delivery_task` | `src/tdc/entity/delivery_task.rs` | ✅ 照抄上游 `@JsonIgnore` |
| `entity/DemoCarInsuranceEntity.java` | `tdc_demo_car_insurance` | — | ❌ **无父外键** ⇒ 挂不上任何聚合体 ⇒ 记 **L3** |
### 1.3 子表挂载(B3)
| 上游 | 本仓 | 结论 |
|---|---|---|
| `service/ResourceServiceImpl#withChildren`(`fieldRules` + `maskRules`) | `src/tdc/entity/resource.rs` 的 `child_tables` | ✅ **只挂 `GET /Resource/{id}/Detail`**(普通详情**不带**) |
| `service/DataInterfaceServiceImpl#withChildren`(`params` + `fields`) | `src/tdc/entity/data_interface.rs` | ✅ **只挂普通 `GET /DataInterface/{id}`**(上游**没有** `/Detail` 路由) |
| `controller/DeliveryTaskController#decorate`(参与方) | `src/tdc/entity/delivery_task.rs` | ✅ 挂**详情与列表**(列表走批量查,避 N+1) |
| — | `src/tdc/entity/delivery_task.rs` 的 `outbox` | ⚠️ **本仓扩展**:上游**不挂** `tdc_delivery_outbox`(它只被 `DeliveryOutboxRetryTicker` 消费)⇒ 记 `docs/contract.md` §子表聚合 §偏离 |
### 1.4 身份 / 账号
| 上游 | 本仓 | 结论 |
|---|---|---|
| `controller/AuthController.java:96` `@PostMapping("/Login")` | `src/tdc/controller/auth.rs:11` | ✅ 连接器身份登录(软 PKI)**不动** |
| `controller/AuthController.java:138` `@GetMapping("/Me")` | `src/tdc/service/identity.rs:311` | ✅ |
| `controller/AuthController.java:152`(角色 SQL) | `src/tdc/service/account.rs:320` | ✅ **逐字照抄**(`IN ('tdcProvider','tdcConsumer','tdsReadOnly')`) |
| `controller/AuthController.java:207` `data.put("roles", roles)` | `src/tdc/service/identity.rs:360` | ✅ `/Auth/Me` 带 `roles` 键(**只对账号会话算**) |
| `controller/AuthController.java:213`(账号查询 SQL) | `src/tdc/service/account.rs:270` | ✅ |
| `controller/AuthController.java:74` `@GetMapping("/SsoConfig")` | `src/tdc/controller/auth.rs:14` | ✅ 本仓恒 `enabled:false`(不实现 MaxKey SSO) |
| `controller/AuthController.java:241` `@GetMapping("/Spaces")` | `src/tdc/controller/auth.rs:13` | ✅ |
| j7 `PasswordTokenGranter`(jar 内) | `src/tdc/service/account.rs:124` | ✅ `md5(lower(md5(明文)) + lower(f_secretkey))`(见 §3) |
| `config/TdcJ7SeedBootstrap.java:43` | `src/tdc/service/account.rs:621`(`bootstrap_account_layer`) | ✅ 种三个角色 + 引导管理员;⚠️ **租户列取值 `0`**(上游 seed 是空串)⇒ **无功能影响**(该表查询不带租户过滤) |
| `boot/db/j7/V1.0.1__connector_seed.sql:17-25` | `src/tdc/service/account.rs:56`(`SEED_ROLES`) | ✅ **逐字照抄**(id / 中文名 / `f_en_code` / `f_type='user'` 全同) |
| j7 登录端点(`/api/oauth/Login`) | `src/tdc/controller/account.rs:42` | ✅ form-urlencoded,字段名 `grant_type` 原样 |
| j7 `base_user` 表 | `schema/migrate.sql`(`base_user`) | ✅ 逐字搬运(主键内联,见 `CLAUDE.md`) |
### 1.5 出向 TDS(P4)
| 上游 | 本仓 | 结论 |
|---|---|---|
| `client/TdsReportClient.java:42` | `src/tdc/client/tds.rs` | ✅ 只实现 **9 个** internal 通道方法 |
| `client/TdsReportClient.java:63`(`X-Internal-Token`) | `src/tdc/client/tds.rs` 的 `internal_headers()` | ✅ 出向**固定 6 个头**,**绝不**带 `Authorization` / cookie |
| `controller/ServiceCatalogController.java:44/81/124` | `src/tdc/controller/tds_biz.rs:36/37/38` | ✅ 目录 / 下单 / 批量下单 |
| `controller/BillingController.java:108/123/144/166/235/254/269` | `src/tdc/controller/tds_biz.rs:43-52` | ✅ 账单 7 个端点 |
| `controller/BillingController.java:254` `LocalCompare` | `src/tdc/controller/tds_biz.rs` | ✅ 读**本地** `tdc_api_consume_log`,**零出向** |
| `controller/TdsReportClient` 的 `login` / `ensureToken` 通道 | — | ❌ **不做**(P4 只做 internal 通道) |
| `controller/TradeOrderBridgeController` | — | ❌ **不做**(旧的 `/api/ssw/tdc/tds/*` 代理网关**已永久下线** ⇒ 404) |
### 1.6 平台层(Rust 侧新增 / 上游无对应)
| 本仓 | 上游对照 | 结论 |
|---|---|---|
| `src/platform/cipher.rs` | `frontend/web/src/utils/cipher.ts:17`(`encryptPassword`) | ✅ **逐字对齐**:key = `md5_hex(CIPHER_KEY)` 的 32 个 ASCII 字节;src = `md5_hex(plain)` 的 32 个 ASCII 字节;Pkcs7 补 `16×0x10` ⇒ 48 字节 / 96 hex |
| `src/platform/envelope.rs` | j7 `ActionResult` | ✅ HTTP 200 + `{code,msg,data}` |
| `src/platform/auth.rs:132`(`reject`) | 上游 `InternalTokenSupport`(`ssw-common-biz/…/security/InternalTokenSupport.java`) | ✅ 裸 `{success:false,code,msg}`(**无 `data`**) |
| `src/platform/fallback.rs`(DDL 两层守卫) | 上游**无**(本仓加固) | ⚠️ **本仓更严**:上游把 DDL 放 web root 是可下载的 |
| `src/platform/mw.rs:59`(405 JSON 改写) | 上游用 Spring 默认 | ⚠️ **本仓更严**:上游 405 返回 HTML |
| `src/platform/compare.rs` | 上游无 | ⚠️ **本仓更严**:常量时间比较(C11,两份实现合一) |
### 1.7 明确**不做**(❌)
| 上游 | 为什么不做 |
|---|---|
| `client/NaxClient.java` / `client/K8sSandboxClient.java` | 依赖 **Nax 隐私计算引擎** + **scard 安全平面**(软 PKI + 软 TPM)⇒ 本地不可行 |
| `engine/NaxEngineRunner.java` / `engine/NaxPodSupport.java` | 同上 |
| `policy/*`(`PolicyEngine` / `PolicyRuleRegistry` / `ExecutionPolicyGate` …) | 策略执行引擎(依赖 Nax) |
| `schedule/*`(14 个 Ticker) | 后台调度(`DeliveryOutboxRetryTicker` / `AuditReportTicker` / …)⇒ 本仓**不实现交付执行** |
| `heartbeat/IdentityHeartbeatTicker.java` | 心跳上报(依赖 TDS 出站 + 私钥签名) |
| `controller/SandboxSessionController.java` / `P2PChannelController.java` / `EngineJobController.java` | 隐私计算 / P2P / 引擎作业 |
| `controller/ApiGatewayController.java` / `ApiDocController.java` / `FileController.java` / `PortalController.java` | 网关 / 文档 / 文件 / 门户 |
| j7 的 `base_module` / `base_authorize` / `base_organize` 等 120 张 `base_*` | 上游 `ssw.jnpf-permission.enabled=false` ⇒ 菜单授权行是死的(记 **L2**) |
#### 1.7.1 2026-11-13 追加:执行链路(用户口径变更,覆盖上表相关两条)
> 用户 2026-11-13 明确「不用 Java 版,用 tdc-rs 连接器;**不起 Pod**;平台下发 →
> EasyTier + Ray 组网 → MPC 跑通」。上表 `engine/NaxEngineRunner` / `NaxPodSupport` /
> `EngineJobController` / `schedule/*` 的「本仓**不实现交付执行**」是**当时能力的事实陈述**,
> 不是产品约束,现已被推翻。**保留原表作为历史**,本节只记本批新增范围。
> 完整研判见 `../ssw-tds-test/docs/tdc-rs-exec-chain-decision-2026-11-13.md`。
| 新增 | 位置 | 边界 |
|---|---|---|
| 三入向端点 | `controller/exec.rs` | `Internal/SelfCheckStatus` / `Dev/Artifact` / `Exec/Start`,外加验收用 `Exec/Status`;产物摘要自算(纯 Rust SHA-256) |
| MPC 控制面出向 | `client/mpc_control_plane.rs` | `GET /nodes\|/sessions\|/report`、`POST /desired`;Bearer + 裸 JSON/204,**不复用 TDS 的 internal 头** |
| 执行层状态机 | `engine/{mod,config,digest,process,state}.rs` | 控制面对账 → ET 组网 → Ray 计算层 → MPC 点火;异步落 `data_dir/exec/*.json`,不碰 18 实体注册表 |
| 契约回归 | `tests/exec_endpoints.rs` | ⑦ PROBE 404→200、handler 内 fail-closed 复核、产物 List+hash、幂等、dry-run=`PLANNED` |
🔴 **口径内仍不做**:起 K8s Pod、Java 版 Nax 运行时、Python 函数级 `ray.put/ray.get`
分布式计算、平台侧数据产品动态分片、在 ZYNQ(armv7/无 python3) 上跑 Ray、跨 netns 自动化。
🔴 **不起 Pod** 时 `clusterConfig.parties[].address` 是 K8s Service DNS 死地址 ⇒ 真实端点
必须由 `TDC_EXEC_SITE_ENDPOINTS` 显式给出,缺了 fail-closed,**不猜、不回落**。
🔴 `Exec/Start` 的 `_code=200, ok=true` 只表示**已受理**;真实成败查 `Exec/Status`,
`dry_run` 收口是 `PLANNED`,绝不算 `SUCCEEDED`。
---
## 2. 数据 ETL
### 2.1 表结构:不用搬
`schema/migrate.sql` 是**上游 `tdc_*` schema 的生成产物**(B0 逐列对账,零差异)
⇒ **表结构不需要 ETL**,只要把数据搬过去。
```bash
# 重建一个空库(表全按 migrate.sql 建好)
bash scripts/reset-data.sh
PORT=30000 ./target/debug/tdc-connector
```
🔴 探针只在**首次建表**时跑 ⇒ **改了 `migrate.sql` 必须先 `reset-data.sh`**。
### 2.2 数据搬运(`tdc_*` 业务表)
| 步骤 | 做什么 | 注意 |
|---|---|---|
| ① | 从上游 MySQL `dump` 出 30 张 `tdc_*` 表 | 只导这 30 张;`base_*` 见 §2.4 |
| ② | 按 **列名**(`f_` 前缀)逐列 `INSERT` | ⚠️ **不要按列序** —— 上游 `CREATE TABLE` 的列序与本仓**可能不同** |
| ③ | `f_tenant_id` 保持原值 | 本仓的租户过滤读 `f_tenant_id`(`TableSpec::tenant_column`) |
| ④ | `f_delete_mark` 原样搬 | 本仓存活谓词 = `(f_delete_mark IS NULL OR f_delete_mark = 0)` ⇒ **NULL 与 0 都算存活** |
| ⑤ | 审计列(`f_creator_time` / `f_last_modify_time` …)原样搬 | 🔴 **时区**:上游 MySQL 与本仓都用**服务器本地时区**(D18)⇒ 不用换算 |
🔴 **列名 vs JSON 键**:本仓对外是 camelCase,但**表里的列名是 `f_snake_case`**
⇒ ETL 按**列名**搬,不要按 JSON 键。
### 2.3 实体 → 表的**多对一**(易踩)
`Dataset` **没有自己的表** —— 它是 `tdc_resource` 的**只读视图**
(`src/tdc/entity/dataset.rs` 的 `table = "tdc_resource"`)。
⇒ 搬数据时:`tdc_resource` 搬一次即可;**不要**为 Dataset 再搬一份。
### 2.4 `base_*` 三表(账号层)
| 表 | 搬什么 | 注意 |
|---|---|---|
| `base_user` | 账号行 | 🔴 **口径变了**(见 §3):上游 j7 存 `md5(明文)`,本仓存**官方双 md5** ⇒ **必须重算**,不能直接搬 `f_password` |
| `base_role` | 角色行 | 建议直接用本仓引导种的三行(`tdcProvider` / `tdcConsumer` / `user`)⇒ **上游其余 j7 角色不必搬**(菜单体系已排除) |
| `base_role_relation` | 用户 ↔ 角色 | 角色 id 要与 `base_role` 对得上 ⇒ 若用本仓引导的角色,**关系行要重写**(角色 id 换成种子的固定 id) |
🔴 **`base_user` 的行 id 要用 j7 形状**(UUID v4 大写,36 字符)——
本仓 `src/tdc/service/account.rs:137` 的 `new_j7_id()` 就是照上游
`UUID.randomUUID().toString().toUpperCase()` 生成的 ⇒ 同一张表里**别混两种 id 风格**。
### 2.5 不搬的
| 不搬 | 原因 |
|---|---|
| `data/accounts.json` | B4 之后**后端不再读取**(决策 D8:存量账号**不导入**) |
| 上游 120 张 `base_*` | 菜单/授权体系已排除(**L2**) |
| 隐私计算相关表的**数据** | Nax / Sandbox 不实现(但表**建了**,因为要跟上游 schema 对齐) |
---
## 3. 口令换算
### 3.1 两种存储口径
| | 上游 j7 | 本仓 |
|---|---|---|
| 存什么 | `f_password = md5(明文)` | `f_password = md5(lower(md5(明文)) + lower(f_secretkey))` |
| 有 secretkey 吗 | ❌ 没有 | ✅ 有(`f_secretkey` 列,**每账号随机**) |
| 改密时 | 重算 `md5(明文)` | **只重算 `f_password`**(**secretkey 不换**) |
### 3.2 换算公式(从上游 → 本仓)
已知上游的 `f_password_old = md5(明文)` ⇒ 需要**明文**或**明文的 md5**:
```
md5_明文hex = f_password_old (上游存的就是它)
f_password_new = md5( lower(md5_明文hex) + lower(f_secretkey) )
```
⚠️ **方向不可逆**:只有 `f_password_old`(= `md5(明文)`)**不够**吗?——
**够**!因为 `md5(明文)` 本身就是公式的第一段 ⇒
`f_password_new = md5( lower(f_password_old) + lower(f_secretkey) )`。
🔴 **但前提是 `f_secretkey` 已知**:
- 若该账号在上游**已经有** `f_secretkey`(上游 j7 表有这一列)⇒ 直接用它,**口令不用变**;
- 若没有 ⇒ **随机生成一个**(`new_j7_id()` 形状)⇒ 该账号的口令**仍然不变**
(因为公式只用 `md5(明文)`,不依赖 secretkey 的来源)。
⇒ **结论:口令不需要用户重新设置**,只需用旧 `f_password` + 新旧任一 `secretkey` 重算。
### 3.3 换算脚本(照抄公式,一行 SQL 级别的事)
```sql
-- 在**本仓**的库里跑(把上游的 f_password 灌进一列再回写)
UPDATE base_user
SET f_password = md5( lower(f_password) || lower(f_secretkey) ),
f_secretkey = '<若为空则生成的 UUID v4 大写>'
WHERE f_secretkey IS NULL OR f_secretkey = '';
```
> PostgreSQL 的 `md5(text)` 返回 32 个小写 hex ⇒ 与本仓 `official_password_hash` 的输出**逐字一致**
> (本仓两侧都 `to_lowercase()`)。
### 3.4 一致性自证
```bash
# 本仓的公式(两个独立向量,用系统 md5 算出来的)
cargo test --lib official_password_hash
# ⇒ 两个向量的期望值是外部算的 ⇒ 不是自证自洽
```
### 3.5 🔴 换算后**必做**的确认
1. 用**旧口令**登录一次(`POST /api/oauth/Login`,密码走上游同款加密)⇒ 应当 `code=200`。
2. 确认管理员位没丢:`SELECT f_account, f_is_administrator FROM base_user WHERE f_is_administrator = 1;`
3. 🔴 **默认口令 `admin` / `admin` 是公开已知的** ⇒ 上线前改掉
(`TDC_STRICT_SECRETS=1` 会在「管理员仍用默认口令」时**拒绝启动**)。
---
## 4. 迁移检查清单
```bash
# ① 结构对账
grep -cE '^CREATE TABLE public\.tdc_' schema/migrate.sql # 30
grep -cE '^CREATE TABLE public\.base_' schema/migrate.sql # 3
curl -s --noproxy '*' http://127.0.0.1:30000/api/health # tables=30 baseTables=3
# ② 尺子全绿
cargo test && bash scripts/smoke.sh && bash scripts/check-boundary.sh \
&& bash scripts/check-entity.sh && bash scripts/check-contract.sh
# ③ 契约一致(端点数 == 实际注册路由数)
bash scripts/check-contract.sh # ⇒ 132 条端点一致
# ④ 上游差异表(B0 产物)
less docs/superpowers/2026-10-26-tdc-rs-upstream-diff.md
```