docs: 同步批次 12.6 收尾(HANDOFF + HOWTO + CLAUDE + memory)
记下:两档验证的分工(--fast 该接的接上了 / --lib 接上的活真能应答)、 两处反自证结果、以及「不同步 Save/Delete」「不在 new-pack.sh 里跑」两条边界。
This commit is contained in:
1 parent
324e82be0d
commit
21c69ee85d
4 files changed
+121
-10
No files matched your search
@@ -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、插件),都要再补一条**真跑一次**的冒烟。
|
||||
@@ -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`)。两套数据源不同,别混。
|
||||
|
||||
+53
-1
@@ -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 条里挑
|
||||
|
||||
+16
-9
@@ -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/<app>/`(**真源**)+ `modules/<app>.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 的 <Route>(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)钉住:
|
||||
|
||||
Reference in new issue
Block a user