From 21c69ee85d805fbd82a514f44923045dcfaef78d Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 1 Nov 2026 23:13:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=89=B9=E6=AC=A1=20?= =?UTF-8?q?12.6=20=E6=94=B6=E5=B0=BE=EF=BC=88HANDOFF=20+=20HOWTO=20+=20CLA?= =?UTF-8?q?UDE=20+=20memory=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记下:两档验证的分工(--fast 该接的接上了 / --lib 接上的活真能应答)、 两处反自证结果、以及「不同步 Save/Delete」「不在 new-pack.sh 里跑」两条边界。 --- .workbuddy/memory/2026-11-01.md | 48 +++++++++++++++++++++++++++++ CLAUDE.md | 4 +++ HANDOFF.md | 54 ++++++++++++++++++++++++++++++++- HOWTO_MODULE.md | 25 +++++++++------ 4 files changed, 121 insertions(+), 10 deletions(-) diff --git a/.workbuddy/memory/2026-11-01.md b/.workbuddy/memory/2026-11-01.md index 7e33b7e..54ec410 100644 --- a/.workbuddy/memory/2026-11-01.md +++ b/.workbuddy/memory/2026-11-01.md @@ -682,3 +682,51 @@ $ diff react/.../vite.config.ts rust/.../vite.config.ts ### 教训 **「生成物 + `--check`」是治「漏一处就静默」的通用解**:不是靠文档提醒,是让漏接变成红。 前提是生成段有稳定标记、且 `--check` 放在 `verify.sh` 第一步(否则别的闸门会先报一串假飘移)。 + +--- + +## 批次 12.6 —— 「接上了」≠「接的活能应答」(2026-11-01 23:15) + +### 先补的事:批次 12 / 12.5 从来没提交 +88 个文件 / 10795 行躺在工作区里(上一轮「收尾」只写了文档,没 commit)。 +按项目惯例补了两个 commit:`ce30c5b feat(pack): …` + `aa2447e docs: …`。 +⇒ 教训:**「收尾」清单里必须包含 commit**,否则下一轮开工时 `git diff` 已经失真。 + +### 问题:漏接会红了,接错还是全绿 +`routes.rs::route_table_is_pinned` 用「错方法 ⇒ 405」只证明**路径注册了**。 +中间那段(handler 跑不通)没有任何闸门: +- spec 有列 / DDL 缺列 ⇒ 投影 SQL 报错 ⇒ 列表恒 `{"code":400}`,页面空着 +- `module_key` 指向不存在的菜单 ⇒ 403 +- 面 B 路由没 merge ⇒ 404 +三者**静态闸门全绿**。 + +### 做法:`tests/pack_smoke_it.rs`(一个测试,遍历全部包) +登录拿 token ⇒ 面 A 每模块 `List`(`code==200` + `data` 是裸数组); +面 B 每条 List 路由(`code==200` + `data.list` 数组 + `pagination.total` 非空)。 +**一个条目都不写死**(`ALL_SPECS` / `ALL_ROUTES` / 注册表遍历)⇒ 加包自动覆盖。 +失败时**一次列全部坏条目**(加包常一坏一片)。 + +### 挂在哪档:`--lib`,不是 `--fast` +`--fast` = 纯静态(该接的接上了);`--lib` = + 单测 + 包冒烟(接上的活真能应答)。 +`full` / `smoke` 已由 `--workspace` 覆盖 ⇒ 不重复跑。实测 **+2.4s**(`--lib` 54.9s)。 + +### 反自证(两处,都实测红过再还原) +| 造的漂移 | 结果 | +|---|---| +| DDL 删掉 `f_category`(spec 还有) | FAILED,一次列出面 A 400 + 面 B 400 | +| `pack_router_or_empty` 恒空 | FAILED,指名 `面 B /api/asset/DataResource 404` | + +### 顺手修的文档失真 +- `verify.sh` 写「45 个测试二进制」,实测 `cargo test --workspace --no-run` 的 + `Executable` 行数 = **37** ⇒ 改成 37。(这类数字没人核就一定是错的。) +- `--lib` 描述「不起库」也是错的(`routes.rs` 测试早就在起 pglite)⇒ 改成「起库」。 + +### 边界(有意不做) +- **不冒烟 Save/Delete**:`ColumnSpec` 有意不带类型(只有 `numeric` + `default`) + ⇒ 造不出对所有包都合法的 body;用 `{}` 又等于替包规定「业务列必须可空」 + ⇒ 那是业务决策。写/删留给各包自己的集成测试。 +- **不在 `new-pack.sh` 里跑**:与「生成器不该假装自己是编译器」同一条边界。 + +### 教训 +**「注册了」和「跑得通」是两个断言,必须分开钉。** 静态闸门只能看前者; +凡是有「注册/装配」这一步的地方(路由、菜单、DDL、插件),都要再补一条**真跑一次**的冒烟。 diff --git a/CLAUDE.md b/CLAUDE.md index a6924f5..631c46d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,6 +144,10 @@ ssw-platform/ `contract.md` 三段),由 `scripts/pack-sync.py` 从 `packs/*` + `modules/*.rs` 推出。 **手改会被覆盖**,而 `verify.sh` 第一步 `pack-sync.py --check` 会把「忘了同步」判红 —— 因为漏同步的后果是**静默 404 / 越权放行**,不是编译错误。 +- **两档验证,分工别混**:`verify.sh --fast`(纯静态)证明「**该接的地方接上了**」; + `verify.sh --lib`(+ 单测 + 包冒烟 `tests/pack_smoke_it.rs`)证明「**接上的活真能应答**」。 + 后者遍历全部包真打 `List`(面 A + 面 B)—— 表没建出来 / 路由没 merge / 守卫指错菜单 + 这三种**静态闸门全绿**、页面空着,只有它会红。**加包后两档都要跑。** - **双面契约同一进程**:面 A(ssw 形状,冻结)+ 面 B(官方 JNPF 形状)。判别头 = `Vue-Version: 3`(官方前端必带、本仓前端唯一不发)。 共用两条路由按头分流:`GET /api/oauth/CurrentUser`、`PUT /api/permission/Authority/Data/{objectId}`。 - **两套权限判据并存**:面 A 按菜单路径(`f_url_address`);面 B 按点权限编码(`f_en_code`)。两套数据源不同,别混。 diff --git a/HANDOFF.md b/HANDOFF.md index 5a200a7..1782cf4 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1249,9 +1249,13 @@ cargo test -p sspf-pack-asset ```bash bash scripts/new-pack.sh crm Customer --name "客户" \ --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend -bash scripts/verify.sh --fast # ≈17s 全绿才继续(含尺子自证) +bash scripts/verify.sh --fast # 纯静态:文件与接线一致(含尺子自证) +bash scripts/verify.sh --lib # + 单测 + **包冒烟**(真起库、真打 List) ``` +⚠️ **不在这里写耗时**:`verify.sh` 每次运行自己打印总耗时 + Top 3 最慢 +(判据是「耗时必须可见」,写在文档里的数字一定会烂)。 + 它产出的东西(**全部从「业务决策」推导,不猜**): | 产出 | 谁生成 | @@ -1357,6 +1361,54 @@ bash scripts/verify.sh --fast ✅ 全绿 17.2s - 包**只支持静态链接**(`kind = "static"`);`dylib` 热插拔仍未做。 - 官方 **Vue 那一套一行没碰**(集成期)。 +#### ✅ 批次 12.6 完成状态(2026-11-01 23:15 实测)—— 「接上了」≠「接的活能应答」 + +**问题**:12.5 之后,漏接会红(`pack-sync --check`),但**接错了仍然全绿**。 +`routes.rs::route_table_is_pinned` 只用「错方法 ⇒ 405」证明**路径注册了**, +它证明不了 **handler 跑得通**。中间那段是静默失败的重灾区: + +| 造的错 | 静态闸门 | 用户看到 | +|---|---|---| +| spec 有列、DDL 缺列(投影 SQL 报错) | 全绿 | 列表恒 `{"code":400}`,页面空着 | +| `module_key` 指向不存在的菜单 | 全绿 | 403,页面空着 | +| 面 B 路由没 merge 进总路由 | 全绿 | 404,页面空着 | + +**做法**:`src/backend/tests/pack_smoke_it.rs` —— **一个测试、遍历全部包** +(`ALL_SPECS` / `ALL_ROUTES` / 包注册表,**一个条目都不写死**): +登录拿 token ⇒ 面 A 每个 `List` ⇒ 断言 `code==200` 且 `data` 是裸数组; +面 B 每条 List 路由 ⇒ 断言 `code==200` 且 `data.list` 是数组、`pagination.total` 非空。 +失败时**一次列出全部坏条目**(加包场景常一坏一片,逐条重跑才能看全 = 浪费)。 + +- `verify.sh` 新增这一步,挂在 **`--lib`**(`full`/`smoke` 已由 `--workspace` 覆盖,不重复跑): + 实测 **+2.4s**(起 pglite + 起 HTTP 服务 + 4 个包 × 2 面)。 +- 🔴 **不放进 `--fast`**:内环的定位是「零 node、零起库的纯静态」,塞进去会把 20s 变成 25s + 且多一个 flaky 面(端口 / 起库)。`--fast` 与 `--lib` 的分工现在很清楚: + **`--fast` = 该接的接上了;`--lib` = 接上的活真能应答**。 + +**反自证(两处,实测)**: + +| 造的漂移 | 结果 | +|---|---| +| `packs/asset/schema/001_init.sql` 删掉 `f_category`(spec 还有这一列) | **FAILED**,一次列出两条:面 A `.../DataResource/List` 信封 code=400、面 B `/api/asset/DataResource` 信封 code=400(附 `column "f_category" does not exist` 的服务端日志) | +| `bootstrap::pack_router_or_empty` 改成恒 `Router::new()` | **FAILED**,指名 `面 B /api/asset/DataResource 状态 404 ≠ 200` | + +**顺手修的两处文档失真**: + +- `verify.sh` 头部写「45 个测试二进制」,实测(`cargo test --workspace --no-run` 的 + `Executable` 行数)= **37** ⇒ 改成 37。这类数字没人核就一定是错的。 +- `--lib` 的描述写「不起库」也是错的(`--lib` 里的 `routes.rs` 测试早就起 pglite 了) + ⇒ 改成「lib 单测 + 包冒烟(起库)」。 + +**边界(有意不做)**: + +- **不冒烟 Save / Delete**:Save 需要合法 body,而 `ColumnSpec` **有意不带类型** + (只有 `numeric: bool` + `default`)⇒ `VARCHAR` 与 `TIMESTAMP` 在 spec 里长得一样 + ⇒ 造不出对所有包都合法的 body。退一步用 `{}` 又要求「业务列全部可空」—— + 那是**业务决策**(`--columns` 允许写 `NOT NULL`),平台不该替包规定。 + 写 / 删留给各包自己的集成测试(`crud_it.rs` / `batch*_it.rs`)。 +- **不在 `new-pack.sh` 里跑**:与「生成器不该假装自己是编译器」同一条边界 + —— 它只管「文件和接线都齐」,能不能应答交给 `verify.sh`。 + #### 批次 12 顺延为批次 13(原计划,一字不改) `fe-gap` 余下最大的 `system` 55 条 / `permission` 26 条 / `systemData` 32 条里挑 diff --git a/HOWTO_MODULE.md b/HOWTO_MODULE.md index 8b9b443..d9250af 100644 --- a/HOWTO_MODULE.md +++ b/HOWTO_MODULE.md @@ -7,9 +7,14 @@ > ```bash > bash scripts/new-pack.sh crm Customer --name "客户" \ > --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend -> bash scripts/verify.sh --fast # ≈17s 全绿才继续 +> bash scripts/verify.sh --fast # 纯静态:文件和接线一致 +> bash scripts/verify.sh --lib # + 单测 + **包冒烟**(真起库、真打 List) > ``` > +> 🔴 **两道都要过**:`--fast` 只证明「该接的地方都接上了」,**证明不了「接的活能应答」** +> —— 表没建出来 / 面 B 路由没 merge / `module_key` 指向不存在的菜单,这三种 +> **静态闸门全绿**,只有 `--lib` 里的包冒烟(`tests/pack_smoke_it.rs`)会红。 +> > 它建 `packs//`(**真源**)+ `modules/.rs`(面 A 适配器), > 再把**四处生成位置**补齐(`packs_gen.rs` / `modules/mod.rs` 五段 / > `Cargo.toml` 依赖段 / `docs/contract.md` 三段)。 @@ -35,18 +40,20 @@ 8. src/backend/Cargo.toml >>>GEN:PACK_DEPS 段 9. docs/contract.md 附录 A [MODULE] / [MENU] / [ENDPOINT] 的生成段 10. frontend/src/{api,views}/… + App.tsx 的 (new-page.sh,--with-frontend) - ⇒ bash scripts/verify.sh --fast 必须全 ✅ + ⇒ bash scripts/verify.sh --fast 必须全 ✅(文件与接线) + ⇒ bash scripts/verify.sh --lib 必须全 ✅(+ 包冒烟:List 真应答) ``` 🔴 **漏了会怎样**(这就是为什么不再让人手抄): -| 漏哪一步 | 现象 | 报错吗 | -|---|---|---| -| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** | -| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** | -| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** | -| 8(Cargo 依赖) | 编译失败 | ✅ 报 | -| 9(契约) | `check-contract` 红 | ✅ 报 | +| 漏哪一步 | 现象 | 报错吗 | 谁兜住 | +|---|---|---|---| +| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** | `verify.sh --lib` 包冒烟 | +| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** | 单测 `every_pack_loads_with_…`(结构性) | +| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** | `verify.sh --lib` 包冒烟 | +| DDL 少一列 | 投影 SQL 报错 ⇒ 列表恒 `{"code":400}` | ❌ **不报** | `verify.sh --lib` 包冒烟 | +| 8(Cargo 依赖) | 编译失败 | ✅ 报 | 编译 | +| 9(契约) | `check-contract` 红 | ✅ 报 | `verify.sh --fast` | 🔴 **平台层(`src/platform/`)与入口文件(`src/backend/src/main.rs`)一个字都不用改** —— 加业务模块**不碰平台层**,由尺子 `bash scripts/check-boundary.sh`(CP1–CP6)钉住: