把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。
新增文档:
- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。
新增尺子(第四把 + 两把专项):
- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。
影响:
- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
(`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
**不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。
实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。
⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。
Co-Authored-By: Claude Code <[email protected]>
16 KiB
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) |
2. 数据 ETL
2.1 表结构:不用搬
schema/migrate.sql 是上游 tdc_* schema 的生成产物(B0 逐列对账,零差异)
⇒ 表结构不需要 ETL,只要把数据搬过去。
# 重建一个空库(表全按 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 级别的事)
-- 在**本仓**的库里跑(把上游的 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 一致性自证
# 本仓的公式(两个独立向量,用系统 md5 算出来的)
cargo test --lib official_password_hash
# ⇒ 两个向量的期望值是外部算的 ⇒ 不是自证自洽
3.5 🔴 换算后必做的确认
- 用旧口令登录一次(
POST /api/oauth/Login,密码走上游同款加密)⇒ 应当code=200。 - 确认管理员位没丢:
SELECT f_account, f_is_administrator FROM base_user WHERE f_is_administrator = 1; - 🔴 默认口令
admin/admin是公开已知的 ⇒ 上线前改掉 (TDC_STRICT_SECRETS=1会在「管理员仍用默认口令」时拒绝启动)。
4. 迁移检查清单
# ① 结构对账
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