docs(spec): v3 追加对标技能修订 + 落执行提示词

- v3 spec:补 D10–D15 / §0.5 借什么不借什么 / §2.3 边界规约 + C1–C12 /
  §2.4 三把尺子 / §5.4 权限现状盘点(五条放行路径)
- 新增 docs/superpowers/2026-10-26-tdc-rs-v3-execution-prompt.md(执行提示词)

回退点:06f5a79(B1b 搬家的 revert 基准)
This commit is contained in:
admin committed 2026-10-26 18:56:04 +08:00
1 parent 06f5a798fb
commit 17a16ec930
2 files changed
+405 -33

No files matched your search

@@ -0,0 +1,178 @@
# 执行提示词:按 v3 设计改造 tdc-rs(B0 → B5)
> 这份文件是**给人/agent 复制粘贴用**的提示词,不是设计书。
> 设计真源 = `docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md`(下称「**v3 spec**」)。
> 🔴 提示词与 v3 spec 冲突时,**以 v3 spec 为准**;发现提示词写错就改提示词,别改 spec 的决定。
---
## 提示词正文(从这里开始复制)
你要在仓库 `/Users/xs/Desktop/workspace/tdc-rs` 上执行一次**已经设计好、已经评审过**的改造。
### 0. 先读这些(不要凭印象动手)
1. **v3 spec(唯一执行依据)**:
`docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md`
全文读一遍,特别是 **§0.5(借什么/不借什么 + P1/P2/P3 三个真问题)**、
**§2.1(目标目录树 + 平移映射表)**、**§2.3(平台层/业务层边界规约 + C1–C12 收敛清单 + 4 个静态接触点)**、
**§2.4(三把尺子)**、**§5.4(权限现状盘点)**、**§8(分批实施与验收)**、**§10(风险与回滚)**、**§12(决策记录 D1–D15)**。
配套继承文档:`docs/superpowers/specs/2026-10-24-tdc-rs-align-v2-design.md`(v2 未被 v3 改写的章节继续有效)。
2. **对标技能(只读借鉴,不抄代码)**:`~/.agents/skills/ssw-jnpf-lite-rust/`
—— 它的仓根就是技能本体。看三样东西就够:
`SKILL.md`(工程化外壳长什么样)、`scripts/perm-smoke.sh` + `scripts/check-module.sh`(尺子怎么写)、
`docs/contract.md` + `docs/decisions.md`(契约真源 / 裁决台账的写法)。
🔴 **只借「工程化外壳」,不借「契约层」**(见 v3 spec §0.5 / D10)。
3. **上游真源(只读)**:`/tmp/sswtdc-probe`(上游 Java TDC 快照)—— 业务表/实体/端点语义以上游为准。
### 1. 本次要干的活(严格按批序,一批做完验收再进下一批)
```
B0 → B1a → B1b → B2 → B3 → B4 → B5 → B6+(可选)
只读核查 尺子先行 搬家+收敛 schema 子表聚合 账号层 文档 上游动作端点
```
🔴 **B1 内部顺序不可换**:**B1a(写尺子、锁基线)必须先于 B1b(搬 9810 行代码)**。
理由:`cargo test` 是进程内 `oneshot`,**不经过 HTTP 层** ⇒ 没有尺子就搬家 = 裸奔。
#### B0 · 只读核查(不动代码)
- 重放上游迁移(`scripts/gen-migrate.sh`)→ 算出上游「建过 / 活 / 已删」的表集;
与 tdc-rs 现有 **30 张** `tdc_*` 表逐名对账;列上游 **27 实体 / 33 控制器** 的覆盖差。
- 产物:`docs/superpowers/2026-10-26-tdc-rs-upstream-diff.md`(差异表)。
- **不改任何代码**。
#### B1a · 尺子先行(只加脚本,不改业务代码)
写三把尺子到 `scripts/`,**在【旧目录结构上】先跑一遍,锁住现状基线**:
| 脚本 | 形态 | 必须覆盖 | 退出码 |
|---|---|---|---|
| `scripts/smoke.sh` | **真进程真 HTTP**(零 node 依赖;cipher 用后端 `--enc` 之类的自证手段) | ① 业务信封 200 + `code` ② 鉴权 **401/403 裸三键**(**无 `data`**)③ `/api/**` 未命中 = **404 JSON**(不是 SPA HTML)④ 405 = `{code,msg,data:null}` 且**保留 `Allow` 头** ⑤ `hidden_fields`(`secretKey` / `devUrl` / `devToken`)**不在出参** ⑥ numeric 列是 **JSON 字符串** ⑦ 列表分页信封 `{pagination,list}` ⑧ `/api/health` 的 `tables`/`baseTables` 真查库 | 0 全绿 / 1 有失败 / 2 前置错 |
| `scripts/check-boundary.sh` | **纯静态**,不起后端 | v3 spec **§2.3.2 的 4 个接触点**逐条钉 | 0 / 1 / 2 |
| `scripts/check-entity.sh` | **纯静态**,不起后端 | 加一个实体时:表在 `migrate.sql` · spec 在 `entity/` · 6 条路由已注册 · `hidden_fields` 覆盖上游 `@JsonIgnore` · 编码前缀不重复 · 权限键不重复 · `f_`↔camelCase 双向映射闭合 | 0 / 1 / 2 |
- **验收**:`smoke.sh` 全绿 + **记录基线断言数 N**(写进 `.workbuddy/memory/2026-10-26.md` 和 v3 spec §8 B1b 那一行的 N 值)。
- 🔴 **N 是后续所有批次的硬判据:断言数只许增不许减,且 B1b 搬家前后必须 == N**(搬家不改契约)。
- ⚠️ 本机 curl 走系统代理 ⇒ 打 localhost **必须加 `--noproxy '*'`**。
#### B1b · 包结构重组 + 边界收敛(**行为零变化**)
按 v3 spec §2.1 的平移映射表搬:
- `src/registry.rs` → `src/tdc/entity/*.rs`(18 个实体一文件)+ `entity/mod.rs`(`ALL_SPECS` + 启动自检)
- `src/crud.rs`(1246 行)→ **三切**:`src/tdc/mapper.rs`(SQL/投影/序列化)+ `src/tdc/service/crud.rs`(分档/写路径规则)+ `src/tdc/controller/crud.rs`(HTTP handler + 路由表)
- `src/routes/*.rs` → `src/tdc/controller/*.rs`;其中 **`mw.rs` / `fallback.rs` / `body.rs` 归 `src/platform/`**(通用响应改写与兜底)
- `src/routes/health.rs` → `src/tdc/controller/health.rs`(`tables` 是业务表数 ⇒ 业务语义)
- `src/db.rs` `session.rs` `envelope.rs` `cipher.rs` `ids.rs` `protocol.rs` `state.rs` `config.rs` → `src/platform/*`(同名)
- `src/codec.rs` → `src/tdc/util/code.rs`(**业务编码生成器**;`ids.rs` 主键生成**留平台层**)
- `src/tds/mod.rs` → `src/tdc/client/tds.rs`;`src/domain/identity.rs` → `src/tdc/service/identity.rs` + `tdc/controller/auth.rs`;`src/account.rs` → `src/tdc/service/account.rs`
- **同时完成 v3 spec §2.3.1 的 C1–C12 全部 12 条收敛**(不是可选,是本批验收项之一):
- C1/C2/C3 = 引擎里的 `match api_name` 全删,改成**读 `TableSpec` 字段**
(新增 `child_tables` / `not_found_msg` / `aggregate_detail` 三个 spec 字段);
- C4 = `db.rs` 的 schema 探针改通用(查 `pg_catalog.pg_tables`);
- C5 = `auth.rs` 的 `WHITE_URL` 清单归业务层 `tdc/support/public_paths.rs`,**顺手剪掉 7 条死路径**;
- C7 = health 的 `tdc\_%` 归业务层;C8/C9 = `Config`/`TdcConfig`、`AppState` 拆两半;
- C10 = `tdc_identity` 领域 SQL 收口到 `tdc/service/identity.rs`,**只 SELECT 明确列,永不 `SELECT *`**;
- C11 = `constant_time_eq` 两份实现合一,上收到平台层;C12 = 删手写日历算法,统一用 `chrono`(口径 **UTC**)。
- **验收**:`cargo test` **223 条全绿** + `smoke.sh` 断言数 **== N** + `check-boundary.sh` 全绿
+ `docs/CONSOLE-ACCEPTANCE.md` 的浏览器验收**重跑一遍**。
- 🔴 **每条 C 项单独提交**(便于二分定位);回退点 = `06f5a79`。
#### B2 · schema 追平上游
`scripts/gen-migrate.sh` 重放到上游最新(迁移号已到 `V2.94.0`)⇒ `schema/migrate.sql` 补 `base_user` / `base_role` / `base_role_relation`。
- **验收**:migrate.sql 可重放;表集与上游逐名对齐;`data/` 清空重建后 `/api/health` 的 `tables`/`baseTables` 符合预期。
- 🔴 **改 schema 必须清空 `data/` 重建**(`CREATE TABLE IF NOT EXISTS` 不改已有表)——用 `scripts/reset-data.sh`。
#### B3 · 子表聚合补齐
聚合详情扩到上游口径,覆盖 **7 个子表**:`ResourceField` / `ResourceMaskRule` / `DataInterfaceField` / `DataInterfaceParam` / `DeliveryTaskParticipant` / `DeliveryOutbox` / `DemoCarInsurance`。
(上游也**没给它们独立控制器**,走父实体聚合 ⇒ **不新增端点**。)
- **验收**:聚合详情字段齐全断言 + 父子表一致(建子行 → 父详情可见)。
#### B4 · 账号层切 `base_user`(D5)+ 删 18 权限键(D6)
- `data/accounts.json` 的**读取路径删掉**(**文件保留不删**——个人/运行期数据不擅自删);账号落 `base_user`。
- 口令改**官方双 md5 公式**:`f_password = md5(lower(md5(明文)) + lower(f_secretkey))`,`f_secretkey` 每账号随机 UUID。
- 前端 cipher **一字不改**(`src/cipher.rs` 与上游同算法,只改**存储公式**);
- 存量账号**不导入**(一次性换算单向不可逆)。
- 管理员位 = `base_user.f_is_administrator = 1`,**查询异常 ⇒ false(fail-closed)**,守住 `/api/permission/Users*`。
- 角色码三件套:`tdcProvider` / `tdcConsumer` / `tdsReadOnly`(照上游的悬空角色码照抄,只种 3 个角色)。
- **删除** 18 个实体级权限键 + `capabilities()` + 引擎里那整条「写操作按权限键二次校验」分支。
🔴 **但不要把权限收紧成 fail-closed**(理由见 v3 spec §5.2 / §5.4 / D11)。
- **验收**:登录 / 用户管理 / 管理员位 / 角色码四组断言 + 存量导入**不做**的确认
+ 上游公式自证(`md5(md5(plain)+secretkey)` 往返)+ **部署退出门槛:确认账号发放只给受信人**。
#### B5 · 工程化外壳(文档层,只写文档不改代码)
按 v3 spec §11.2 逐份产出,每份**带指向代码的 `文件:行号` 引用**:
| 文档 | 内容 | 验收 |
|---|---|---|
| `docs/contract.md` | **契约唯一真源**:132 端点全表(1 health + 4 auth + 7 account + 110 crud + 10 tds_biz)· 4 种响应形状 · 分页信封 · `f_`↔camelCase 命名契约 · 权限章节(**含 §5.4 敞开事实**)· 数据模型(30 + 3 张表) | 端点数 **== 实际注册路由数**(用脚本对账) |
| `docs/decisions.md` | 逐条裁决「什么—为什么—代价」(含 D1–D15 的落账) | 每条指向代码 `文件:行号` |
| `docs/known-limitations.md` | 实体级写权限敞开 · `tdc_identity` 双读写路径 · 动作端点未实现 · 分发形态缺陷 | — |
| `docs/runbook.md` | 怎么起 / 怎么冒烟(`cargo test` + `smoke.sh` + `check-boundary.sh`)/ 常见故障 | 照着跑一遍能通 |
| `docs/ACCOUNT-LAYER.md` | `base_user` 契约 + 官方双 md5 公式 + 管理员位 fail-closed | 公式往返断言 |
| `MIGRATION.md` | **Java TDC ⇄ Rust 逐件翻译表**(每条标上游 `文件:行号`)+ 数据 ETL + 口令换算 | 抽查 5 条属实 |
| `HOWTO_ENTITY.md` | **加一个实体**的操作手册(比技能的 `HOWTO_MODULE.md` 更短:只碰 `entity/` 一处) | 照着加一个试跑 |
- 每份文档写完**抽查 5 条引用属实**。
- 同时同步 `CLAUDE.md`(目录树 / 红线 / 表清单 / 坑表)与 `.workbuddy/memory/2026-10-26.md`(每批一段)。
### 2. 硬红线(违反即返工)
1. 🔴 **契约零变化(B1b 尤其)**:端点路径 / 方法 / 请求体 / 响应体**一律不动**。
4 种响应形状(业务信封 200 / 鉴权 401·403 裸三键 / 404 JSON / 405 `{code,msg,data:null}` 保留 `Allow` 头)
一个都不许改。**判据 = `smoke.sh` 断言数守恒。**
2. 🔴 **不要借技能的契约层**(v3 spec §0.5 / D10):**不做**面 A/面 B 双面、**不做** `200 + 600/602` 鉴权信封
(TDC 是 **401/403 裸 body**,追平上游)、**不建** `base_module` 菜单体系、**不改**成复合主键 `(f_id,f_tenant_id)`。
→ `perm-smoke-jnpf.sh` **不做**(D1 已排除面 B)。
3. 🔴 **不要收紧权限成 fail-closed**(D11):现状**本来就敞开**(5 条放行路径,§5.4)⇒ D6 是**拆掉一层假权限**,
不是收权。处置 = **显式记账**(`known-limitations.md` + `contract.md` 权限章节 + 部署约束),不是加门禁。
若将来要收紧,回退点 = 恢复 18 键分支 + 补 `base_module`(**上游不建 ⇒ 接受与上游不一致**)。
4. 🔴 **不要技能化**(D12):本轮**不写** `SKILL.md`、**不做** `~/.agents|~/.claude|~/.workbuddy` 三处软链、
**不做**「仓根即技能」。阻塞在分发形态(`static/` 靠 `resolve_project_dir()` 从 `current_exe()` 向上找
⇒ `cargo install` 装出的二进制找不到前端;`/tmp/sswtdc-probe`、`PREBUILT_DIST` 均 gitignore ⇒ 第三方 clone 装不起来)。
只**记账**(S10),等分发形态定了单独立项。
5. 🔴 **平台层 / 业务层边界**:`src/platform/` 里**不许出现业务知识**——业务表名(`tdc_`)、实体名
(`Product` / `Resource` / `DeliveryTask` …)、业务端点路径(`/api/ssw/tdc/`)、业务表数量、业务配置。
`src/tdc/` 里**不许出现平台能力的第二份实现**。
⚠️ **通用 CRUD 引擎住在业务层**(`tdc/mapper.rs` / `tdc/service/crud.rs` / `tdc/controller/crud.rs`)——
这是为了对位上游 `TdcCrudController`(D3);但它的**逻辑必须实体无关**(零 `match api_name`)。
6. 🔴 **同一文件的多个 Edit 必须串行**(并行 = last-writer-wins 静默覆盖);改完**必须 grep 复核全部改动点**。
7. 🔴 **删个人文件必须真进回收站**(`~/.Trash`),**禁止 `rm`**;本轮**不删** `data/accounts.json`(只停用读取路径)。
8. 🔴 **密钥零明文**:agent 环境用 `xop run --secret ENV=VAULTNAME -- CMD < /dev/null`
(**`< /dev/null` 必须有**,否则 xop 一直等 Touch ID);**严禁**读取明文进上下文;
**严禁**读 `~/.git-credentials` 明文;**严禁**把口令写进 remote URL。
9. 🔴 **不要 `git push`**,除非用户明确要求。本轮只提交到本地分支。
10. 🔴 **本机 curl 打 localhost 必须 `--noproxy '*'`**;**pglite 一个数据目录只能被一个进程打开** ⇒ 集成测试串行跑或各用独立数据目录。
### 3. 交付节奏与汇报
- **一批一提交**(C 项再细分为「一条 C 一提交」),提交信息写清批次与影响。
- 每批结束立刻更新:`CLAUDE.md`(若该批改了代码/目录/红线)+ `.workbuddy/memory/2026-10-26.md`(一段)。
- 每批验收跑全这四条,**全部绿才进下一批**:
`cargo test` · `scripts/smoke.sh`(断言数 == N 或更多)· `scripts/check-boundary.sh` · `scripts/check-entity.sh`
- 遇到与 v3 spec 冲突的判断:**停下来问用户**,别自行改 spec;确认后**回写 spec** 再动手。
- 最终汇报给出:各批验收结果表(实测数字,不许写「应该没问题」)+ 剩余偏差清单 + 已知限制。
### 4. 开工前先做两件事
1. **提交当前未提交的 v3 spec 修订**(工作区里 `docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md` 已改,尚未 commit)
—— 先把它落成一个 commit,这样 B1b 的回退点才清晰。
2. `git status` 确认工作区干净、`git branch` 确认在 `feat/mvc-align-v3`(**不要**在 `main` 上直接改)。
---
## 提示词正文结束(到这里结束复制)
---
## 附:给用户看的速览(不必复制给执行方)
| 项 | 值 |
|---|---|
| 仓库 | `/Users/xs/Desktop/workspace/tdc-rs` |
| 分支 | `feat/mvc-align-v3`(HEAD `06f5a79` = v3 spec 落点 / B1b 回退点) |
| 设计真源 | `docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md`(498 行,本次已改 **D10–D15 / §0.5 / §2.3 / §2.4 / §5.4**) |
| 本提示词 | `docs/superpowers/2026-10-26-tdc-rs-v3-execution-prompt.md`(本文件) |
| 对标技能(只读) | `~/.agents/skills/ssw-jnpf-lite-rust/`(仓根 = 技能本体) |
| 上游真源(只读) | `/tmp/sswtdc-probe` |
| 批序 | B0 → **B1a(尺子先行)** → **B1b(搬家+收敛)** → B2 → B3 → B4 → B5 → B6+ |
| 硬判据 | `cargo test` 223 条全绿 · `smoke.sh` 断言数 **== N** · `check-boundary.sh` 全绿 |
| 三条不做 | 面 A/面 B · `600/602` 信封 · `base_module` 菜单 · 技能化 · 收紧成 fail-closed |
@@ -1,8 +1,12 @@
# tdc-rs 对齐上游 Java TDC · v3(业务包 MVC + 账号层同源 + 单库)
# tdc-rs 对齐上游 Java TDC · v3(业务包 MVC + 账号层同源 + 单库 + 工程化外壳)
> 版本:v3(2026-10-26) 继承:`2026-10-24-tdc-rs-align-v2-design.md`(v2 的对齐面总览、状态机、协议类、TDS 契约继续有效)
> 版本:v3(2026-10-26,含**对标技能追加修订**:D10–D15 / §0.5 / §2.3 / §2.4 / §5.4)
> 继承:`2026-10-24-tdc-rs-align-v2-design.md`(v2 的对齐面总览、状态机、协议类、TDS 契约继续有效)
> 本文只写 **v3 相对 v2 的增量与改写**;v2 未被本文改写的章节继续有效。
> 配套:`2026-10-25-tdc-rs-p4-tds-outbound-design.md`(P4 TDS 出向,本次不改)。
>
> 🔴 **本次修订的一句话**:借技能 `ssw-jnpf-lite-rust` 的**工程化外壳**(分层边界 + 可执行尺子 + 文档四件套 + 迁移/加实体手册),
> **不借它的契约层**(面 A/面 B · 600/602 信封 · `base_module` 菜单 · 复合主键)——见 §0.5 / D10。
---
@@ -21,18 +25,50 @@
| **D3** | **核心是业务包 MVC** | Rust 侧目录对位上游 `ssw.tdc.*`(entity/mapper/service/controller/support/…),**保留通用 CRUD 引擎**(不退回「每实体四件套」) |
| **D4** | **单库** | `base_*` 与 `tdc_*` 共处**一个 pglite 实例、一个 `public` schema**,靠表前缀分区(上游两库里的表也都在 `public` ⇒ DDL 逐字一致、导数据零改写) |
### 0.3 附带决定(本轮问询)
### 0.3 附带决定
> **D5 / D6 = 用户拍板,不可自行推翻**;**D10–D15 = 2026-10-26 对标技能后新增**(实施前可推翻,推翻需回写本文)。
| # | 决定 | 说明 |
|---|---|---|
| **D5** | 账号层**一步切到 `base_user`** | 官方双 md5 口令公式 + 自动生成 `secretkey`;`data/accounts.json` 一次性导入后停用 |
| **D6** | 权限模型**按上游** | 登录态 + 角色码(`tdcProvider`/`tdcConsumer`/`tdsReadOnly`)+ 管理员位(`base_user.f_is_administrator`)三件套;**删除** tdc-rs 现有的 18 个实体级权限键与能力集判定 |
| **D10** | **借技能的「工程化外壳」,不借它的「契约层」** | 借四件:① 平台层/业务层分离(`src/platform/` + `src/tdc/`)② 三把可执行尺子(HTTP 契约冒烟 + 边界静态自检 + 实体静态自检)③ 文档四件套(契约真源 / 逐条裁决 / 已知限制 / runbook)④ 迁移手册 + 加实体手册。**契约层一律不借**:面 A/面 B 双面(D1/D7 已排除)、`200+600/602` 鉴权信封(上游是 401/403 裸 body,§5.3)、`base_module` 菜单 + 四源权限合并(上游 `jnpf-permission.enabled=false`)、`f_tenant_id='0'` 单租户与复合主键。**理由**:技能的价值在「怎么保证契约不被改坏」,不在「契约本身是什么」 |
| **D11** | 权限宽严**维持追平上游 = 显式敞开 + 显式记账** | 对标盘点发现 tdc-rs 现状**已有 5 条放行路径**(§5.4),净效果已是「任何登录用户可写全部 18 实体」⇒ D6 的删除**不是收权也不是放权,是拆掉一层「看起来在管、实际没管」的假权限**,且删掉后与上游**完全同构**。⇒ **不**收紧为 fail-closed(会造出与上游不一致的新偏差);改为**把「实体级无隔离」写成显式条款**(§9 S1 升级 + `docs/known-limitations.md` + 部署退出门槛) |
| **D12** | **技能化(`SKILL.md` + 三处软链 + 仓根即技能)本批不做** | 阻塞在**分发形态**:`static/` 靠 `resolve_project_dir()` 从 `current_exe()` 向上找 ⇒ `cargo install` 装出的二进制找不到前端;`/tmp/sswtdc-probe`、`PREBUILT_DIST` 均 gitignore ⇒ 第三方 clone 下来装不起来。⇒ 本批只补**文档与尺子**,技能化等分发形态定了再单独立项 |
### 0.4 非目标(显式不做)
- ❌ 官方 JNPF 前端 / 面 B 官方形状端点 / `base_module` 菜单体系 / `f_en_code` 点权限(D1 + 上游 `ssw.jnpf-permission.enabled=false`)。
- ❌ Nax 隐私计算作业(`Sandbox`/`Privacy`/`Notebook`/`Tee` 等依赖 Nax 引擎与 scard 软 PKI/软 TPM,本地不可行)——**注意**:`tdc_sandbox_exec_run` / `tdc_privacy_exec_run` 只是**作业记录表**,本仓照常提供 CRUD;不可行的是「跑作业」这件事。
- ❌ 上游动作端点全量(~30–40 个,见 §6.3)——**下一批**按控制器分批做。
- ❌ **技能化**(`SKILL.md` + `~/.agents|~/.claude|~/.workbuddy` 三处软链 + 仓根即技能)——D12:先解决分发形态。
---
### 0.5 本轮对标技能的结论摘要(2026-10-26 追加)
**一句话**:tdc-rs **不是** JNPF 实现,是上游 Java TDC 的 Rust 重实现 ⇒ 「按技能改造」**不是**「改成 JNPF 后台」,
而是**借技能用来「保证契约不被改坏」的那套工程外壳**(D10)。
#### 借什么 / 不借什么
| 层 | 借 | 不借 | 理由 |
|---|---|---|---|
| 契约层 | — | 面 A/面 B 双面 · `200+600/602` 鉴权信封 · `base_module` 菜单 + 四源合并 | D1/D7 已排除面 B;上游鉴权是 401/403 裸 body(§5.3);上游 `jnpf-permission.enabled=false` |
| 数据层 | 上游 j7 的 `base_user`/`base_role`/`base_role_relation` **逐列 DDL**(§3.3 已列) | `base_*` 全家桶 · 复合主键 `(f_id,f_tenant_id)` · `f_tenant_id='0'` 单租户 | 本仓 30 张表是**单列主键**、租户列可空;换主键会炸掉全部存量数据 |
| 工程层 | **四件全借**(D10):平台/业务分层 · 三把尺子 · 文档四件套 · 迁移与加实体手册 | — | 这才是技能真正的资产 |
#### 对标盘点暴露的三个真问题(本次改造的真正标的)
| # | 问题 | 处置 |
|---|---|---|
| **P1** | **平台层 / 业务层没有边界**:共 **12 条收敛项**(C1–C12),其中 **7 条是业务知识硬编码在共享/平台代码里**(引擎 2 处按实体名分叉 + schema 探针 + 鉴权白名单 + health 表计数 + 业务配置 2 处)+ 1 处**平台→业务反向依赖** + 业务绕过引擎(`tdc_identity` 双读写路径) | §2.3 边界规约 + C1–C12 收敛清单,**B1b 一次做完** |
| **P2** | **尺子只有 `cargo test`**(进程内 `oneshot`,**不经过 HTTP 层**)⇒ HTTP 状态码 / 响应头 / body 原始 JSON 文本 / 404·405 真实形状 / 隐藏字段是否真不在出参 —— **全都没有被测到** | §2.4 三把尺子,**B1a 先行**(D13) |
| **P3** | **权限是「假权限」**:**5 条放行路径**(§5.4)使净效果已是「除管理员端点外,任何登录用户可写全部 18 实体」 | D11:删假层 + **显式记账**(**不收紧**,见 §5.2 / §5.4) |
> 另有一条**不在本次改造范围**但必须记账的分发缺陷(D12):`static/` 靠 `resolve_project_dir()` 从
> `current_exe()` 向上找 ⇒ `cargo install` 装出的二进制**找不到前端** ⇒ 控制台白屏。
---
@@ -60,10 +96,17 @@ Rust 侧目标(单 crate,`tdc-rs`):
```
src/
├── main.rs lib.rs state.rs config.rs ← 启动装配(对应 ssw-tdc-admin)
├── db.rs session.rs envelope.rs cipher.rs ids.rs
│ protocol.rs codec.rs ← 平台壳层(对应 jnpf base/oauth)
└── tdc/ ← 业务包(对位 ssw.tdc.*)
├── main.rs lib.rs ← 启动装配(对应 ssw-tdc-admin)
├── platform/ ← 【平台层】加业务实体/端点**一个字都不改**
│ ├── state.rs config.rs ← 状态容器 / 环境变量
│ ├── db.rs ← pglite 封装 + SQL 切分 + f_↔camelCase 映射契约
│ ├── session.rs envelope.rs ← 内存会话 / ActionResult 信封
│ ├── cipher.rs ids.rs ← 口令协议 / 主键生成
│ ├── protocol.rs ← 协议版本闸门 + 日志净化
│ ├── auth.rs ← 三道门 + Principal
│ ├── body.rs mw.rs fallback.rs ← 宽松 JSON 体 / 405 改写 / 404+DDL 守卫
│ └── mod.rs ← 平台层模块清单 + 边界规约(§2.3)
└── tdc/ ← 【业务层】对位 ssw.tdc.*
├── entity/ 每个实体一文件:列清单 / json_key / numeric /
│ hidden_fields / frozen_columns / 分档 / filter / keyword
│ mod.rs ALL_SPECS 汇总 + 启动自检(迁自 registry::validate)
@@ -79,22 +122,32 @@ src/
├── schedule/ 定时任务占位(上游 ssw.tdc.schedule)
├── client/ TDS 出向客户端(现 `src/tds/`,整体平移)
├── notify/ heartbeat/ sso/ ← 占位,后续批
├── util/ **业务**工具(上游 ssw.tdc.util 对位);平台级通用件(ids / codec)留在 `src/` 平台层,**一份实现不复制**
├── util/ **业务**工具(上游 ssw.tdc.util 对位)
│ mod.rs code.rs ← 业务编码生成器(原 `src/codec.rs`,见下)
├── config.rs constant.rs
```
> 🔴 **原 `src/codec.rs` 归位到业务层**(`tdc/util/code.rs`):它是**业务编码生成器**
> (`PRO`/`RES`/`API`/`DS` 前缀 + 两条上游生成器),不是序列化 codec,也不是平台件。
> `ids.rs`(主键生成)留在平台层。**一份实现不复制。**
**平移映射(v2 → v3)**
| v2 位置 | v3 位置 | 备注 |
|---|---|---|
| `src/registry.rs`(1159 行) | `src/tdc/entity/*.rs` + `entity/mod.rs` | 18 条 `TableSpec` 拆成 18 个实体文件;`ALL_SPECS` 汇总;`validate()` 迁 `entity/mod.rs` |
| `src/crud.rs`(1246 行) | `src/tdc/mapper.rs`(SQL/投影/序列化)+ `src/tdc/service/crud.rs`(分档/写路径规则)+ `src/tdc/controller/crud.rs`(HTTP handler + 路由表) | 三切,**行为零变化** |
| `src/routes/*.rs` | `src/tdc/controller/*.rs` | `routes/` 消失;`mw.rs`(405/413 改写)与 `fallback.rs`(404 + DDL 守卫)留在 `src/` 平台层 |
| `src/crud.rs`(1246 行) | `src/tdc/mapper.rs`(SQL/投影/序列化)+ `src/tdc/service/crud.rs`(分档/写路径规则)+ `src/tdc/controller/crud.rs`(HTTP handler + 路由表) | 三切,**行为零变化**;引擎内 2 处 `match api_name` 改为**读 spec 字段**(§2.3.1 C1/C2) |
| `src/routes/*.rs` | `src/tdc/controller/*.rs` | `routes/` 目录消失;**但** `mw.rs` / `fallback.rs` / `body.rs` 归**平台层**(见下两行)——它们是通用响应改写与兜底,不是业务 |
| `src/routes/mw.rs` `fallback.rs` `body.rs` | `src/platform/{mw,fallback,body}.rs` | 405 改写 / 404 + DDL 守卫 / 宽松 JSON 体 = 平台能力 |
| `src/routes/health.rs` | `src/tdc/controller/health.rs` | 🔴 `tables` 计数是**业务表数**(W5:30 + 3 = 33)⇒ 平台层不该知道「业务表」是什么 ⇒ 归业务层;平台层只提供 db 连通性探测 helper |
| `src/db.rs` `session.rs` `envelope.rs` `cipher.rs` `ids.rs` `protocol.rs` `state.rs` `config.rs` | `src/platform/*`(同名) | 整体平移,**零行为变化**;`db.rs` 的 schema 探针改**通用化**(§2.3.1 C4) |
| `src/codec.rs` | `src/tdc/util/code.rs` | 业务编码生成器 ⇒ 业务层(`ids.rs` 主键生成留平台层) |
| `src/domain/identity.rs` | `src/tdc/service/identity.rs` + `tdc/controller/auth.rs` | 身份登录(`/api/ssw/tdc/Auth/*`) |
| `src/account.rs` | `src/tdc/service/account.rs`(存储换 `base_user`,见 §4) | 登录与用户管理 |
| `src/tds/mod.rs` | `src/tdc/client/tds.rs` | 出向客户端 |
| `src/auth.rs` | `src/` 平台层(保留原位) | 三道门 + `Principal`;仅 `Principal::Account` 语义随 §4 调整 |
| `src/registry.rs` 的 `PERMISSION_KEYS` | **删除** | D6:改由 §5 的角色码/管理员位判定 |
| `src/auth.rs` | `src/platform/auth.rs` | 三道门 + `Principal`;**白名单路径清单归业务层**(§2.3.1 C5);仅 `Principal::Account` 语义随 §4 调整 |
| `src/registry.rs` 的 `PERMISSION_KEYS` | **删除** | D6:改由 §5 的角色码/管理员位判定。**副作用**:引擎对 `domain::identity::capabilities` 的反向依赖**随之消失**(§2.3.1 C6) |
### 2.2 通用引擎**保留**(D3 的另一半)
@@ -104,6 +157,59 @@ src/
- `frozen_columns` / `create_codes` / `filter_columns` / `keyword_columns` / `tenant_column` / `default_order_column`。
- `no_create` / `no_update` / `no_delete` **业务分档**(照上游控制器的可写性差异)——⚠️ 这是**业务规则**,不是权限机制,**不随 D6 删除**。
### 2.3 平台层 / 业务层边界规约(D10 · 对标技能的「加业务模块只碰业务层」)
**规约一句话**:`src/platform/` 里**不许出现业务知识**——业务表名、实体名、app 名、具体端点路径、业务表数量。
`src/tdc/` 里**不许出现平台能力的第二份实现**。
> 这条规约的价值不在目录好看,而在**它可被静态检查**(§2.4 的 `check-boundary.sh`)
> ⇒ 「业务又漏进平台了」会**当场红**,而不是靠人读 9810 行代码发现。
#### 2.3.1 收敛清单(B1b 必须一次做完,逐条给出改造方式)
| # | 现状位置 | 泄漏内容 | 改造方式 |
|---|---|---|---|
| **C1** | `src/crud.rs` `child_tables()` | `match api_name { "Resource" \| "Dataset" => … }` + **硬编码两个不在 REGISTRY 里的表名** `tdc_resource_field` / `tdc_resource_mask_rule` | `TableSpec` 增字段 `child_tables: &'static [(&'static str, &'static str)]` ⇒ **引擎零 `match api_name`**,子表由业务 spec 声明(与技能 `EntitySpec.creator_fixed` 同一手法) |
| **C2** | `src/crud.rs` `detail_not_found_msg()` | `match api_name { "Dataset" => "数据集不存在或资源已删除", … }` | `TableSpec` 增字段 `not_found_msg: &'static str`(默认 "记录不存在或已删除") |
| **C3** | `src/routes/crud.rs` 聚合详情注册 | 按名 `registry::find("Resource")` / `find("Dataset")` + `expect` | `TableSpec` 增 `aggregate_detail: bool` ⇒ 控制器**遍历 spec** 注册 `/api/ssw/tdc/{Entity}/{id}/Detail` ⇒ **零硬编码实体名** |
| **C4** | `src/db.rs` `ensure_schema()` | 探针写死 `SELECT 1 FROM tdc_identity LIMIT 1` | 探针改**通用**:`SELECT count(*) FROM pg_catalog.pg_tables WHERE schemaname='public'` ⇒ 为 0 才执行 `migrate.sql`(单 schema 布局下成立:base_* 与 tdc_* 同处 `public`) |
| **C5** | `src/auth.rs` `WHITE_URL` | 硬编码 12 条**业务端点路径**,其中 **7 条(Gateway×2 / P2P×4 / Portal / Topology)本仓已无对应路由** | 白名单**清单**归业务层(`tdc/support/public_paths.rs`),平台层 `auth.rs` 只保留「按清单放行」的机制;**顺带剪掉 7 条死路径** |
| **C6** | `src/crud.rs` → `domain::identity::capabilities()` | **平台引擎 → 业务域**反向依赖 | **D6 删除整条权限键分支时自动消失**(无需 `PermissionProvider` trait)——本项**零额外成本**,记此以免实施时漏删 |
| **C7** | `src/routes/health.rs` | `table_name LIKE 'tdc\_%'` + `tables: 30` 是 P0 验收口径 | 归业务层 `tdc/controller/health.rs`(W5 契约已规定 `tables` = 业务表数、新增 `baseTables` ⇒ 本就属业务语义) |
| **C8** | `src/config.rs` | `identity_code` / `identity_name` / `identity_secret` / `bootstrap_admin_*` 五个**业务配置**混在平台配置 struct | 拆 `Config`(平台:port/data_dir/tokens)与 `TdcConfig`(业务:身份与引导)⇒ `AppState` 相应拆两半 |
| **C9** | `src/state.rs` | `AppState` 含 `bootstrap: BootstrapIdentity` / `accounts: AccountStore` 两个业务字段 | 同 C8 |
| **C10** | `src/domain/identity.rs` 8 条手写 SQL + `src/routes/tds_biz.rs` 2 处手写 SELECT | **业务绕过引擎**:同一张 `tdc_identity` 有两条读写路径(通用 CRUD + 领域专用 SQL)⇒ 隐藏字段/冻结列/权限语义在两条路径上**不一致** | **显式承认 + 收口**(不追求「全收进引擎」——上游无此概念,成本高):① 领域 SQL 全部收进 `tdc/service/identity.rs` 一处;② 领域查询**只 SELECT 明确列、永不 `SELECT *`**;③ 在 `docs/known-limitations.md` 记「`tdc_identity` 双读写路径」 |
| **C11** | `src/account.rs` `constant_time_eq` 与 `src/domain/identity.rs` `constant_time_eq` | **两份几乎相同的实现** | 上收到 `src/platform/`(平台件:常量时间比较);业务侧复用,**一份实现** |
| **C12** | `src/account.rs` `civil_from_days` / `now_iso` | 手写 UTC 日历算法,而仓里**已依赖 `chrono`**(`codec.rs` 用过)⇒ 重复造轮子,且与 `codec` 的本地时区口径**不一致** | 删手写实现,统一用 `chrono`(注意口径统一为 **UTC**,并写进 `docs/contract.md`) |
#### 2.3.2 「可被静态检查」的四个接触点(`check-boundary.sh` 逐条钉)
1. `src/platform/**` 内**不得出现**字符串 `tdc_`(表名前缀)与 `/api/ssw/tdc/`(业务端点前缀)。
2. `src/platform/**` 内**不得出现**具体实体名(`Product` / `Resource` / `DeliveryTask` / …)作为标识符。
3. **通用 CRUD 引擎**(`src/tdc/mapper.rs` / `src/tdc/service/crud.rs` / `src/tdc/controller/crud.rs`,
对位上游 `TdcCrudController`)内**不得出现** `match api_name` 或任何按实体名的分支
⇒ 分支只能读 `TableSpec` 字段。
⚠️ 引擎**住在业务层**(D3:镜像上游 `ssw.tdc.controller` 的落位),但**逻辑必须实体无关**——
这与技能把引擎放 `platform/crud.rs` 是**同一手法**(引擎不认识任何具体实体),
只是**落位不同**(tdc-rs 只有一个业务域 `tdc_`,没有第二个业务包可放)。
4. `src/platform/auth.rs` 内**不得出现**字面量端点路径 ⇒ 只能引用业务层提供的清单。
### 2.4 三把尺子(D10 · 对标技能的 `perm-smoke.sh` / `check-module.sh`)
**现状缺口(P2)**:唯一尺子是 `cargo test`(进程内 `tower::ServiceExt::oneshot`)⇒ **不经过 HTTP 层**,
因此 **测不到**:HTTP 状态码、响应头、`Allow` 头、body 的**原始 JSON 文本**、404/405 的真实形状、
隐藏字段是否真的不在出参里。而这些恰恰是 tdc-rs 的契约红线(§5.3 的 4 种响应形状、
§2.2 的 `hidden_fields` 整条删键语义)。
| 尺子 | 形态 | 断言面 | 退出码 |
|---|---|---|---|
| `scripts/smoke.sh` | 打**真进程真 HTTP**(零 node 依赖;cipher 用后端自证) | ① 业务信封 200 + `code` ② 鉴权 401/403 裸三键(**无 `data`**)③ `/api/**` 未命中 = **404 JSON**(不是 SPA HTML)④ 405 = `{code,msg,data:null}` 且**保留 `Allow` 头** ⑤ `hidden_fields`(`secretKey` / `devUrl` / `devToken`)**不在出参** ⑥ numeric 列是 **JSON 字符串** ⑦ 列表分页信封 `{pagination,list}` ⑧ `/api/health` 的 `tables`/`baseTables` 真查库 | 0 全绿 / 1 有失败 / 2 前置错 |
| `scripts/check-boundary.sh` | **纯静态**,不起后端 | §2.3.2 的 4 条接触点 | 0 / 1 / 2 |
| `scripts/check-entity.sh` | **纯静态**,不起后端 | 加一个实体时:表在 `migrate.sql` · spec 在 `entity/` · 6 条路由已注册 · `hidden_fields` 覆盖上游 `@JsonIgnore` · 编码前缀不重复 · 权限键不重复 · `f_`↔camelCase 双向映射闭合 | 0 / 1 / 2 |
🔴 **尺子必须先于重构存在**:`smoke.sh` 属 **B1a**,**排在 B1b(搬家)之前** ⇒ 否则搬家期间没有 HTTP 层回归网。
⇒ **B1 内部顺序固定**:先补 `smoke.sh`(在旧目录结构上跑,锁住现状基线 N)⇒ 再做搬家 ⇒ 再跑一次,**前后断言数必须相同**。
---
## 3. 数据层:单库 + 追平上游最新
@@ -193,12 +299,44 @@ src/
**为何不保留细粒度**:上游 `ssw.jnpf-permission.enabled=false` 是**架构决定**(连接器不读 j7 菜单、前端路由静态 + 角色分流),Rust 侧若单方面加实体级门禁 ⇒ 两边行为不一致,且需为 18 键补 `base_module` 菜单(上游明确不建)⇒ 反而制造「看似对齐实则不同」的偏差。**记为「刻意分歧」= 无分歧,本次是追平。**
> 🔴 **诚实记账(D11)**:对标盘点发现 tdc-rs **现状已有 5 条放行路径**(§5.4),
> 净效果**已经是**「除管理员端点外,任何登录用户可写全部 18 实体」。
> ⇒ **D6 的删除既不是收权、也不是放权**,而是**拆掉一层「看起来在管、实际没管」的假权限**;
> 删除后与上游**完全同构**(上游也只校验「有登录态或内部令牌」)。
> ⇒ **不收紧为 fail-closed**(会造出与上游不一致的新偏差);改为**把「实体级无隔离」写成显式条款**:
> §9 S1 升级为**部署约束** + `docs/known-limitations.md` 独立条目 + `docs/contract.md` 权限章节
> + 部署退出门槛(§8 B4 验收第 5 条:账号发放只给受信人)。
> ⚠️ 风险表里「权限放宽后暴露越权写入 = 高」的表述**同步修正**:真实风险不是「放宽」,
> 而是「**没人知道它本来就是敞开的**」⇒ 处置从「收紧」改为「记账 + 部署约束」。
### 5.3 鉴权失败形状:**不变**(已是上游口径)
- 上游 `TdcAuthFilter`(`boot/ssw-tdc-admin/.../TdcAuthFilter.java:129-141`)= **HTTP 401/403 + 裸 `{"success":false,"code":401,"msg":"…"}`**(**无 `data` 键**)。
- tdc-rs 现状相同 ⇒ **不动**。(技能框架那套「HTTP 200 + `code` 600/602」是 **JNPF 平台**形状,不是 TDC 的;D1 已排除面 B。)
- 三道门顺序与文案照上游:协议版本闸门(`X-Protocol-Version`)→ 内部令牌(`X-Internal-Token`)→ 会话令牌。
### 5.4 权限现状盘点(D11 的依据 · 2026-10-26 对标新增)
tdc-rs 看似有「18 条实体级权限键 + 写权限二次校验」,但**实际判定链上有 5 条放行路径**:
| # | 路径 | 现状位置 | 结果 |
|---|---|---|---|
| ① | 内部令牌 `Principal::Internal` | `crud.rs:629` | **直接放行**(全域管理员) |
| ② | 本地账号 `Principal::Account` | `crud.rs:634` | **直接放行**(本地账号无 `f_capability` 来源) |
| ③ | 身份会话,但 `f_capability` **解析不出** | `crud.rs:638-640` | **fail-open 放行**(注释:「本地单机模式不该把写操作全锁死」) |
| ④ | 权限键**查不到** | `crud.rs:637` | 回退到**实体名**当键 |
| ⑤ | 菜单权限检查 | `auth.rs:252-255` | fail-open(j7 框架库被排除 ⇒ 有主体即放行) |
**净效果**:除管理员端点外,**任何登录用户可写全部 18 个实体**。
**两处管理员短路**(记账,不改):
- 连接器身份会话 = 隐式管理员(`routes/account.rs:120`)⇒ 拿到身份令牌即可管所有账号;
- 内部令牌 = 全域管理员(`crud.rs:629`)。
**⇒ 结论**:D6 删除权限键链路后,**有效访问面不变**(本来就敞着),但
① 与上游**完全同构**;② 不再有「文档说有权限、实际没管」的**误导**。
这正是 D11「显式敞开 + 显式记账」而非「收紧」的理由。
---
## 6. 业务层
@@ -207,7 +345,7 @@ src/
- 现有 18 个注册表实体 → `tdc/entity/` 下 18 个文件(列清单 / json_key / numeric / hidden / frozen / 分档)。
- 上游 27 个 Java 实体中,**tdc-rs 未暴露的 9 个**里 **7 个是子表**(`ResourceField` / `ResourceMaskRule` / `DataInterfaceField` / `DataInterfaceParam` / `DeliveryTaskParticipant` / `DeliveryOutbox` / `DemoCarInsurance`)——上游也**没有**给它们独立控制器,走父实体聚合 ⇒ **不新增端点**,改为在父实体的聚合详情里覆盖(对齐上游口径)。
- 真正缺独立端点的上游控制器(**全部属下一批 B5+**,本批不做):`ApiDoc` / `ApiGateway` / `EngineJob` / `File` / `P2PChannel` / `Portal` / `SandboxSession` / `Topology` / `TradeOrderBridge` / `UsageMetricReport` / `Instance`(约 30–40 端点)。
- 真正缺独立端点的上游控制器(**全部属下一批 B6+**,本批不做):`ApiDoc` / `ApiGateway` / `EngineJob` / `File` / `P2PChannel` / `Portal` / `SandboxSession` / `Topology` / `TradeOrderBridge` / `UsageMetricReport` / `Instance`(约 30–40 端点)。
- 表集**不动**(30 张 → 追平上游后可能变,见 §3.2)——**B0 出差异表后再定**。
### 6.2 聚合详情
@@ -217,21 +355,26 @@ src/
### 6.3 动作端点(**本批不做**)
- 上游「~130 个动词」的实测量级 ≈ 11 个未覆盖控制器 ⇒ 约 30–40 端点(`Resource/{id}/Sync`、`Product/{id}/OnShelf`、`DeliveryTask/{id}/Policy`、`Contract/{id}/Negotiate`、`SandboxSession/*`、`File/*`、`P2P/*`、`TradeOrderBridge/*`…)。
- 分批规则:**按控制器一批一份 spec**,每批端到端可验收;B5 起。
- 分批规则:**按控制器一批一份 spec**,每批端到端可验收;**B6 起**(原写「B5 起」——
因 B5 已被工程化外壳批次占用,见 §8)。
---
## 7. 对外契约变化清单(对上游 SPA 的影响)
> 编号 **W1–W9**(契约变化)。⚠️ **勿与 §2.3.1 的收敛项 C1–C12 混淆**(那批是内部收敛项,不是对外契约变化)。
| # | 契约 | 变化 | 上游 SPA 是否受影响 |
|---|---|---|---|
| C1 | `/api/oauth/Login` | 请求体**不变**(`account`/`password`密文 hex/`grant_type=password`);**响应语义不变**(`{token, expiresIn}`)⇒ 浏览器侧 cipher 一字不改 | ❌ 无感 |
| C2 | 口令校验 | 存储公式变了(裸 md5 → 官方双 md5);**旧账号全部失效**(不导入存量)⇒ 用户须用引导账号或重建账号 | ⚠️ 需告知 |
| C3 | `/api/permission/Users*` | 存储换 `base_user`;出参形状**不变**(`account_view` 手工挑字段) | ❌ 无感 |
| C4 | 实体级写权限 | **取消**(D6)⇒ 非管理员也能写实体(只读分档仍在) | ⚠️ 行为变宽 |
| C5 | `/api/health` | `tables` 语义**改为业务表数**(`tdc_*`),新增 `baseTables`;总计 30 + 3 = 33 | ❌ 上游 SPA 不读 |
| C6 | 业务端点 | 形状**不变**(18 实体的 6 条 CRUD 路由 + 聚合详情 + 10 个 TDS 端点全部保留) | ❌ 无感 |
| C7 | 鉴权失败 | **不变**(401/403 裸 body) | ❌ 无感 |
| W1 | `/api/oauth/Login` | 请求体**不变**(`account`/`password`密文 hex/`grant_type=password`);**响应语义不变**(`{token, expiresIn}`)⇒ 浏览器侧 cipher 一字不改 | ❌ 无感 |
| W2 | 口令校验 | 存储公式变了(裸 md5 → 官方双 md5);**旧账号全部失效**(不导入存量)⇒ 用户须用引导账号或重建账号 | ⚠️ 需告知 |
| W3 | `/api/permission/Users*` | 存储换 `base_user`;出参形状**不变**(`account_view` 手工挑字段) | ❌ 无感 |
| W4 | 实体级写权限 | **取消假层**(D6/D11)⇒ 非管理员也能写实体(只读分档仍在)。⚠️ **不是「变宽」**:现状已敞开(§5.4 五条放行路径)⇒ **有效访问面不变**,只是不再有一层「看起来在管」的假权限 | ⚠️ 行为不变、**表述变**(从「有权限键」变「无实体级隔离」) |
| W5 | `/api/health` | `tables` 语义**改为业务表数**(`tdc_*`),新增 `baseTables`;总计 30 + 3 = 33 | ❌ 上游 SPA 不读 |
| W6 | 业务端点 | 形状**不变**(18 实体的 6 条 CRUD 路由 + 聚合详情 + 10 个 TDS 端点全部保留) | ❌ 无感 |
| W7 | 鉴权失败 | **不变**(401/403 裸 body) | ❌ 无感 |
| W8 | **平台层 / 业务层分层 + 12 条边界收敛**(B1b) | **对外契约零变化**(端点路径/方法/请求体/响应体全部不变)⇒ 断言数守恒是硬判据(§8 B1b) | ❌ 无感 |
| W9 | **`tdc_identity` 领域 SQL 收口**(D15) | 对外契约零变化;仅内部 SQL 位置与列选择收紧(只 SELECT 明确列) | ❌ 无感 |
---
@@ -240,16 +383,29 @@ src/
| 批 | 内容 | 动代码? | 验收 |
|---|---|---|---|
| **B0** | **只读核查**:重放上游迁移 → 算出「建过/活/删」表集;与 tdc-rs 的 30 张逐名对账;列 27 实体 / 33 控制器的覆盖差 | ❌ | 差异表落 `docs/superpowers/2026-10-26-tdc-rs-upstream-diff.md` |
| **B1** | **包结构重组**(行为零变化):`registry.rs`→`entity/`、`crud.rs`→`mapper+service+controller`、`routes/`→`controller/`、`tds/`→`client/` | ✅(纯搬家) | `cargo test` **223 条全绿**(改完 grep 复核全部改动点)+ `docs/CONSOLE-ACCEPTANCE.md` 的浏览器验收重跑 |
| **B1a** | **尺子先行**(D10/P2):写 `scripts/smoke.sh`(HTTP 契约,真进程真 HTTP)+ `scripts/check-boundary.sh` + `scripts/check-entity.sh`,**在旧目录结构上先跑一遍** ⇒ 锁住现状基线 | ✅(只加脚本) | `smoke.sh` 全绿 + 记录**基线断言数 N**(后续每批**不得下降**) |
| **B1b** | **包结构重组 + 边界收敛**(行为零变化):`registry.rs`→`tdc/entity/`、`crud.rs`→`tdc/mapper+service+controller`、`routes/`→`tdc/controller/`(`mw`/`fallback`/`body`→`platform/`)、`tds/`→`tdc/client/`、`codec.rs`→`tdc/util/code.rs`、平台件→`src/platform/`;**并完成 §2.3.1 的 C1–C12 全部 12 条收敛** | ✅(搬家 + 收敛) | `cargo test` **223 条全绿**(改完 grep 复核全部改动点)+ `smoke.sh` 断言数 **== N**(不增不减,搬家不改契约)+ `check-boundary.sh` 全绿 + `docs/CONSOLE-ACCEPTANCE.md` 的浏览器验收重跑 |
| **B2** | **schema 追平**:`scripts/gen-migrate.sh` 重放到上游最新;`base_user`/`base_role`/`base_role_relation` 入 `migrate.sql` | ✅ | migrate.sql 可重放;表集与上游逐名对齐;`data/` 清空重建后 `/api/health` 的 `tables`/`baseTables` 符合预期 |
| **B3** | **子表聚合补齐**:聚合详情扩到上游口径(覆盖 7 个子表:`ResourceField` / `ResourceMaskRule` / `DataInterfaceField` / `DataInterfaceParam` / `DeliveryTaskParticipant` / `DeliveryOutbox` / `DemoCarInsurance`) | ✅ | 聚合详情字段齐全断言 + 父子表一致(建子行 → 父详情可见) |
| **B4** | **账号层切换**:删 `accounts.json` 读取路径;`base_user` 落库;官方双 md5 公式;管理员位 fail-closed;角色码三件套;`/api/permission/Users*` 改读写 `base_user`;**删除 18 权限键链路**(D6) | ✅ | 登录 / 用户管理 / 管理员位 / 角色码四组断言 + 存量导入**不做**的确认 + 上游公式自证(`md5(md5(plain)+secretkey)` 往返) |
| **B4** | **账号层切换**:删 `accounts.json` 读取路径;`base_user` 落库;官方双 md5 公式;管理员位 fail-closed;角色码三件套;`/api/permission/Users*` 改读写 `base_user`;**删除 18 权限键链路 + `capabilities()`**(D6/D11) | ✅ | 登录 / 用户管理 / 管理员位 / 角色码四组断言 + 存量导入**不做**的确认 + 上游公式自证(`md5(md5(plain)+secretkey)` 往返)+ **部署退出门槛:确认账号发放只给受信人**(D11) |
| **B5** | **工程化外壳(文档层)**(D10/D12):`docs/contract.md`(**132 端点全表** + 4 种响应形状 + 数据模型,唯一真源)· `docs/decisions.md`(逐条裁决)· `docs/known-limitations.md`(含 §5.4 权限敞开的显式条目)· `docs/runbook.md`(怎么起/怎么冒烟/常见故障)· `MIGRATION.md`(Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL)· `HOWTO_ENTITY.md`(加一个实体)· `CLAUDE.md` 目录树与红线同步 | ❌(只写文档) | 每份文档**有指向代码的 `文件:行号` 引用**且抽查 5 条属实;`docs/contract.md` 的端点数 **== 实际注册路由数**(用脚本对账) |
| **B6+** | **上游动作端点**(原「B5 起」,因 B5 被工程化外壳占用而顺延):按控制器一批一份 spec | ✅ | 每批端到端可验收 |
**尺子**:`cargo test`(B1 后应仍 223 条,B3/B4 增新断言)+ `docs/CONSOLE-ACCEPTANCE.md` 浏览器验收 + **新增两条跨端断言**:
> 🔴 **B1 内部顺序不可换**:先有 HTTP 尺子(B1a)再有搬家(B1b)——否则 9810 行搬家期间**没有回归网**。
**尺子**(三层,缺一不可):
| 层 | 工具 | 覆盖面 |
|---|---|---|
| 单元/集成 | `cargo test` | 进程内逻辑(**不覆盖 HTTP 层**)——B1 后仍 223 条,B2/B3/B4 增新断言 |
| **HTTP 契约** | `scripts/smoke.sh`(**新增**,B1a) | 状态码 / 响应头 / 原始 JSON 文本 / 4 种响应形状 / 隐藏字段 / numeric 字符串化 / 分页信封 |
| **静态边界** | `scripts/check-boundary.sh` `check-entity.sh`(**新增**,B1a) | 平台层不含业务知识 / 加实体的接触点完整性 |
另加:`docs/CONSOLE-ACCEPTANCE.md` 浏览器验收(人工)+ **两条跨端断言**:
1. 账号口令按官方公式存储且可登录(跨 Java/Rust 可通);
2. 非管理员/管理员的 `base_user.f_is_administrator` 判定与上游 `TdcConnectorAdminGuard` 同义。
**不做**:`perm-smoke-jnpf.sh`(面 B 作废,D1)。
**不做**:`perm-smoke-jnpf.sh`(面 B 作废,D1);**不做**技能化(D12,等分发形态)。
---
@@ -257,13 +413,19 @@ src/
| # | 分歧 | 理由 |
|---|---|---|
| S1 | 权限**无**实体级隔离(D6) | 追平上游(`jnpf-permission.enabled=false`)⇒ 不是分歧,是追平;记此以免后人误加 |
| S2 | 鉴权失败用 **401/403 裸 body**(非 200+600/602) | 上游 `TdcAuthFilter` 就是这样 ⇒ 追平 |
| S1 | 权限**无**实体级隔离 | **不是「D6 造成的放宽」,而是「现状本来就是这样」**(§5.4 五条放行路径)⇒ D6 只拆掉假层 ⇒ 与上游同构。**部署约束**:账号发放只给受信人(D11 / B4 验收第 5 条) |
| S2 | 鉴权失败用 **401/403 裸 body**(非 200+600/602) | 上游 `TdcAuthFilter` 就是这样 ⇒ 追平。**技能那套 600/602 是 JNPF 平台形状,不是 TDC 的**(D1/D7/D10) |
| S3 | `base_*` 只建 3 张(上游 j7 有 123 张) | 上游只用账号/角色链路 ⇒ 功能等价,少 120 张空表 |
| S4 | 单库单 schema(上游两库) | D4;表名逐字一致 ⇒ 导数据零改写 |
| S5 | 无 `base_module` 菜单、无 `f_en_code` 点权限 | 上游明确不建 |
| S6 | 不跑 Nax 隐私计算作业 | 依赖 Nax 引擎 + scard 软 PKI/软 TPM,本地不可行(`tdc_*_exec_run` 表仍提供 CRUD) |
| S7 | `tdsReadOnly` 判据在、种子不种 | 照抄上游自身的不一致(§4.1) |
| S8 | `tdc_identity` **双读写路径**(领域 SQL 绕过 CRUD 引擎) | 上游无「通用引擎」概念,硬收进引擎成本高且会失真 ⇒ **显式承认 + 收口 + 记账**(§2.3.1 C10) |
| S9 | 实体级写权限**不设门禁**(显式敞开) | D11:与上游同构;**代价已知**,靠部署约束而非代码门禁兜底(§5.2 / §5.4) |
| S10 | **不技能化**(无 `SKILL.md`、不在三处技能目录) | D12:分发形态未定(`static/` 定位依赖 `current_exe()` 向上找 ⇒ `cargo install` 装出的二进制找不到前端);先做文档层(B5) |
> **内部规约**(不对外的分歧,只对本仓生效):`src/platform/` 不含业务知识(表名 / 实体名 / 端点路径 / 业务表计数),
> 由 `scripts/check-boundary.sh` 静态钉住(§2.3.2)。
---
@@ -272,21 +434,47 @@ src/
| 风险 | 等级 | 处置 |
|---|---|---|
| B1 搬家动 223 条测试与浏览器验收 | 中 | 纯搬家不改行为;**同文件多 Edit 必须串行**;每步 `cargo test` + grep 复核 |
| **B1b 边界收敛(C1–C12)误改引擎写路径** | **中高** | C1–C3 改的是**引擎判定**,最易出静默偏差 ⇒ ① **B1a 尺子先行**(先在旧结构上锁基线 N)② 改完 `smoke.sh` 断言数**必须 == N** ③ 每条 C 项**单独提交**(便于二分定位)④ 回退点 = `06f5a79`(v3 spec 落点) |
| **无 HTTP 尺子就搬 9810 行** | **高** | B1a/B1b 顺序**不可换**;`cargo test` 不覆盖 HTTP 层(§2.4) |
| B2 schema 追平引发**存量数据不可用** | 中 | 全新 `data/` 重建(B2 本就要求清空);`scripts/reset-data.sh` |
| B4 换口令公式 ⇒ **旧账号全失效** | 中 | 已知且为 D5 的一部分(C2);引导账号兜底;`data/accounts.json` 保留可查 |
| B4 换口令公式 ⇒ **旧账号全失效** | 中 | 已知且为 D5 的一部分(W2);引导账号兜底;`data/accounts.json` 保留可查 |
| 上游仍在动(迁移号已到 V2.94.0) | 中 | B0 差异表 + `gen-migrate.sh` 可重放;**快照式**对齐,不追上游 git 历史 |
| 权限放宽后暴露越权写入 | **高** | 知情决策(D6/§5.2);上线前确认账号发放只给受信人;如需收紧,回退点是「保留 18 键分支」 |
| **实体级写权限敞开 ⇒ 越权写入** | **高** | ⚠️ 表述修正:**不是「放宽」**(现状已敞开,§5.4),而是「**没人知道它本来就敞开**」⇒ 处置从「收紧」改为 **① 显式记账**(S1/S9 + `known-limitations.md` + `contract.md` 权限章节)**② 部署约束**(账号发放只给受信人,B4 验收第 5 条)。**若将来要收紧**,回退点 = 恢复 18 键分支 + 补 `base_module`(上游不建 ⇒ 需接受与上游不一致) |
| **B5 文档写了但代码没跟上**(漂移) | 中 | 每份文档带 `文件:行号` 引用 + **抽查 5 条属实**;`docs/contract.md` 的端点数用脚本与实际注册路由**对账** |
| **分发形态**(`static/` 靠 `current_exe()` 向上找 ⇒ `cargo install` 装的二进制找不到前端) | 中 | D12:**本批不修**,明确记账(S10);技能化与分发形态一起单独立项 |
| `/api/health` 契约变动 | 低 | `tables` 语义改为业务表数 + 新增 `baseTables`;同步测试与文档 |
---
## 11. 文档与记忆同步清单(B1–B4 完成后)
## 11. 文档与记忆同步清单
- `CLAUDE.md`:目录树(`src/tdc/**`)、红线(**删**「权限键 + 能力集」那条,**加**「权限按上游三件套」)、表清单(30 + 3)、坑表补 3 条(账号层换表 / 口令公式 / 权限无实体级)。
- `docs/`:新增 `docs/ACCOUNT-LAYER.md`(`base_user` 契约 + 官方公式 + 管理员位);`docs/CONSOLE-ACCEPTANCE.md` 重跑;`docs/known-limitations.md` 记 D6 的安全后果。
- `.workbuddy/memory/2026-10-26.md`:工作日志(每批一段)。
### 11.1 随代码改(每批结束即刻)
- `CLAUDE.md`:目录树(`src/platform/**` + `src/tdc/**`)、红线(**删**「权限键 + 能力集」那条,**加**「权限按上游三件套」+ **加**「平台层不含业务知识」)、表清单(30 + 3)、坑表补 3 条(账号层换表 / 口令公式 / 权限无实体级)+ 补 2 条(`codec.rs` 归位业务层 / `tdc_identity` 双读写路径)。
- `.workbuddy/memory/2026-10-26.md`(每批一段;B0–B4 + B5 各一段)。
- 记忆(本机):**旧口径「tdc-rs 用 accounts.json 不建 base_* 表」已作废** ⇒ 需更新项目级记忆条目。
### 11.2 B5 文档四件套 + 两本手册(D10 · 对标技能)
| 文档 | 内容 | 验收 |
|---|---|---|
| `docs/contract.md` | **契约唯一真源**:132 端点全表(1 health + 4 auth + 7 account + 110 crud + 10 tds_biz)· 4 种响应形状 · 分页信封 · `f_`↔camelCase 命名契约 · 权限章节(**含 §5.4 敞开事实**)· 数据模型(30 + 3 张表) | 端点数 **== 实际注册路由数**(脚本对账) |
| `docs/decisions.md` | 逐条裁决「什么—为什么—代价」(含本设计书 D1–D15 的落账) | 每条指向代码 `文件:行号` |
| `docs/known-limitations.md` | 分支级已知限制:实体级写权限敞开 · `tdc_identity` 双读写路径 · 动作端点未实现 · 分发形态缺陷(D12) | — |
| `docs/runbook.md` | 怎么起 / 怎么冒烟(`cargo test` + `smoke.sh` + `check-boundary.sh`)/ 常见故障 | 照着跑一遍能通 |
| `docs/ACCOUNT-LAYER.md` | `base_user` 契约 + 官方双 md5 公式 + 管理员位 fail-closed | 公式往返断言 |
| `MIGRATION.md` | **Java TDC ⇄ Rust 逐件翻译表**(每条标上游 `文件:行号`)+ 数据 ETL + 口令换算 | 抽查 5 条属实 |
| `HOWTO_ENTITY.md` | **加一个实体**的操作手册(比技能的 `HOWTO_MODULE.md` 更短:只碰 `entity/` 一处) | 照着加一个试跑 |
> **范式照抄技能**:`JNPF_SOURCE_AUDIT.md` 的写法(每条结论带 `文件:行号` + 一致/偏差 + 偏差是否刻意)
> 是本仓上游核对报告的既有范式 ⇒ `MIGRATION.md` 沿用,**不另立格式**。
### 11.3 明确不做(D12)
- ❌ `SKILL.md` + `~/.agents|~/.claude|~/.workbuddy` 三处软链 + 「仓根即技能」——
阻塞在分发形态(`static/` 定位 + gitignore 的上游快照/`PREBUILT_DIST`)⇒ 技能化与分发形态**一起单独立项**。
- ❌ `references/` / `template-*` 目录(技能有,但 tdc-rs 无对应资产)。
---
## 12. 决策记录
@@ -302,3 +490,9 @@ src/
| D7 | 面 B / `perm-smoke-jnpf.sh` | **不做** | 由 D1 推导 |
| D8 | 存量 `accounts.json` 账号 | **不导入**(D5 推导;文件保留不删) | 由 D5 推导 |
| D9 | `tdsReadOnly` | 判据在、种子不种(照抄上游不一致) | §4.1 |
| D10 | **借技能的工程化外壳,不借契约层** | 四件全借(分层 / 尺子 / 文档 / 手册);契约层一律不借(面 A·面 B · 600/602 信封 · `base_module` 菜单 · 复合主键) | 2026-10-26 对标技能 `ssw-jnpf-lite-rust` |
| D11 | 权限宽严**维持追平上游 = 显式敞开 + 显式记账** | 现状已敞开(§5.4 五条放行路径)⇒ D6 是拆假层不是收权;**不**收紧为 fail-closed(会造出与上游不一致的新偏差) | §5.2 / §5.4 |
| D12 | **技能化本批不做** | 阻塞在分发形态(`static/` 定位依赖 `current_exe()` 向上找)⇒ 先做文档层(B5),技能化单独立项 | §0.4 / §11.3 |
| D13 | **B1 拆成 B1a(尺子先行)+ B1b(搬家 + 边界收敛)** | `cargo test` 不覆盖 HTTP 层 ⇒ 无尺子不搬家;B1a 先在旧结构上锁基线断言数 N,B1b 后断言数必须 == N | §2.4 / §8 |
| D14 | `codec.rs` 归**业务层** `tdc/util/code.rs` | 它是**业务编码生成器**(`PRO`/`RES`/`API`/`DS`),不是序列化 codec;`ids.rs`(主键生成)留平台层 | §2.1 |
| D15 | `tdc_identity` **双读写路径显式承认 + 收口 + 记账** | 不硬收进引擎(上游无「通用引擎」概念,成本高且失真)⇒ 领域 SQL 收进 `tdc/service/identity.rs`、只 SELECT 明确列、记进 `known-limitations.md` | §2.3.1 C10 / S8 |