docs: 同步批次 12 / 12.5 收尾(HANDOFF + HOWTO + CLAUDE + memory)

HANDOFF 记下加模块的真实成本(一条命令 + 一张产出表)、2 个真 bug、反自证结果;

HOWTO_MODULE 开头两节重写(旧手抄清单已过时);CLAUDE 两条核心不变量改写。
This commit is contained in:
admin committed 2026-11-01 23:04:57 +08:00
1 parent ce30c5b2f6
commit aa2447eec2
4 files changed
+959 -31

No files matched your search

+41 -24
View File
@@ -1,38 +1,55 @@
# 加一个业务模块(AI 开发主线)
本文件是 **Rust 版**的操作手册。参照实现 = 内置的四个模块
> 🔴 **2026-11-01 起:一条命令。** 本文后半部分的「改哪个文件」清单写于批次 12 之前,
> **已过时**(`db/schema.sql` 不用改、`modules/mod.rs` 不用改、契约不用手抄)。
> 以本节为准:
>
> ```bash
> bash scripts/new-pack.sh crm Customer --name "客户" \
> --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend
> bash scripts/verify.sh --fast # ≈17s 全绿才继续
> ```
>
> 它建 `packs/<app>/`(**真源**)+ `modules/<app>.rs`(面 A 适配器),
> 再把**四处生成位置**补齐(`packs_gen.rs` / `modules/mod.rs` 五段 /
> `Cargo.toml` 依赖段 / `docs/contract.md` 三段)。
> 生成物手改会在下次 `pack-sync.py` 被覆盖,而 `verify.sh` 第一步就会红。
参照实现 = 内置的四个模块
(`demo/DemoItem` · `shop/Product` · `books/Book` · **`asset/DataResource`(真实业务)**)
——**照抄一个最接近的,别从零想**;要加真实业务模块就抄 `asset.rs`。
——要读就抄 `packs/asset/`,它是完整样板。
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。**
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改了哪儿、怎么验证」。**
## 〇.5、一图看完全流程(先看一遍再动)
## 〇.5、它内部做了什么(排错时照着看)
```
1. db/schema.sql 建表(f_ 前缀 + f_id VARCHAR(50) + 软删列)
2. src/modules/<app>.rs 【新文件】spec + *MENU + 3 个 handler + 自己的 router()
3. src/modules/mod.rs 加 spec 进 ALL_SPECS + 加菜单进 ALL_MENUS + 加 router() 进 merge + 加路由进 ALL_ROUTES
4. frontend/src/api/<lc>.ts 3 个函数(list/save/delete)
5. frontend/src/views/<Ent>.tsx 列表页
6. frontend/src/App.tsx <Route path="/<route>">
7. docs/contract.md 附录 A 加五行:[MODULE] 一行 + [MENU] 一行 + [ENDPOINT] 三行
(本模块的 3 条端点)+ [FACE] 的 A 条数 +3
★ 期望值真源
⇒ bash scripts/check-module.sh <appCode> <Entity> 必须全 ✅
⇒ bash scripts/check-contract.sh 必须全 ✅(端点表 ↔ 代码)
8. scripts/perm-smoke.sh 追加该模块的断言(别新写脚本)
1. packs/<app>/src/lib.rs 【真源】EntitySpec + MenuSpec + PackRoute×3 + Pack + DDLS
2. packs/<app>/schema/*.sql 业务表 DDL(include_str! 编进二进制;**不进 db/schema.sql**)
3. packs/<app>/pack.toml 包清单(catalog;内核读的是 pack-sync 生成的 JSON 快照)
4. packs/<app>/Cargo.toml 只依赖 sspf-sdk(AR2:不许 axum / tokio / pglite)
5. src/modules/<app>.rs 面 A 适配器:pub use 包的 spec + 3 个 handler + router()
↓ 以下四处**全部由 scripts/pack-sync.py 从「packs/* + modules/*.rs」生成**
6. src/backend/src/packs_gen.rs 内核包清单(每个包一条 load_static 调用)
7. src/modules/mod.rs 五段:pub mod / ALL_SPECS / ALL_ROUTES / ALL_MENUS / router()
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 必须全 ✅
```
**8 个文件 = 上面的 1–8**(其中 `modules/<app>.rs` 与 `modules/mod.rs` 是**业务层**)。
第 7 步漏了 ⇒ `check-module.sh` 直接判「契约 [MODULE] 里没有这个模块」退出 2;
`[ENDPOINT]` 漏了 ⇒ `check-contract.sh` 判「代码里的路由没被契约登记」红。
🔴 **漏了会怎样**(这就是为什么不再让人手抄):
| 漏哪一步 | 现象 | 报错吗 |
|---|---|---|
| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** |
| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** |
| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** |
| 8(Cargo 依赖) | 编译失败 | ✅ 报 |
| 9(契约) | `check-contract` 红 | ✅ 报 |
🔴 **平台层(`src/platform/`)与入口文件(`src/backend/src/main.rs`)一个字都不用改** ——
加业务模块**不碰平台层**。
(对比 react 版要动 4 个后端文件;本仓**只动 `src/modules/` 下的 2 个文件** + `db/schema.sql`。)
🔴 **内置菜单也住在业务层**(`modules/<app>.rs` 的 `*_MENU: MenuSpec`)⇒ 由装配根
`bootstrap.rs` 注入平台层的种子 ⇒ 平台层只自带 5 条**系统**菜单。
🔴 这条分层由尺子钉住:`bash scripts/check-boundary.sh`(CP1–CP6)——
加业务模块**不碰平台层**,由尺子 `bash scripts/check-boundary.sh`(CP1–CP6)钉住:
平台层出现任何业务标识符(表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)⇒ 红。
## 〇、命名约定(先想清楚再动)