diff --git a/docs/superpowers/2026-10-26-tdc-rs-v3-execution-prompt.md b/docs/superpowers/2026-10-26-tdc-rs-v3-execution-prompt.md new file mode 100644 index 0000000..2b965c8 --- /dev/null +++ b/docs/superpowers/2026-10-26-tdc-rs-v3-execution-prompt.md @@ -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 | diff --git a/docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md b/docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md index 37d6cdd..3c2c08e 100644 --- a/docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md +++ b/docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md @@ -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 |