Files
ssw-jnpf-lite-rust/HOWTO_MODULE.md
T
admin d8a8165dd7 fix(skill): 自检/文档同步到方案 C(SC3/SC4/SC5 + rustdocflags + description)
- check-scaffold.py: 三条判据从旧模型(sspf 必须声明为 Cargo 依赖)改为方案 C:
  SC3 应用不声明平台/框架件;SC4 业务包不声明外部依赖;
  SC5 Cargo.toml 不出现 sspf(平台由 .cargo/config.toml 的 --extern 提供)。
  _base_tree 与 VIOLATIONS 同步,反自证仍 6/6。
- fetch-platform.sh: 生成的 .cargo/config.toml 同时写 rustdocflags
  (cargo test 的 doctest 走 rustdoc,不吃 build.rustflags,之前 E0432)。
- SKILL.md frontmatter description 改为「预编译 rlib / Gitea Release 按 tag+平台取包 / 零重编」。
- Cargo.toml 头部、HOWTO_MODULE、docs/runbook、new-pack/pack-sync 注释同步。

验证:verify.sh 全量 7/7(静态 3 步 + cargo test + release 构建 + 面 A/面 B 各 18 断言)。
2026-11-05 13:54:52 +08:00

212 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 加一个业务模块(AI 开发主线)
> 🔴 **2026-11-04 起流程变了**:平台不在本仓(在已发布的 `sspf` 包里),
> 「加模块」= **写一个业务包 + 一个面 A 适配器**,其余四处派生位置**由脚本生成**。
> 上一版的「8 个文件 / 10 个接触点 / 手改 `db/schema.sql`」已经作废 ——
> 那些位置现在都是 `// >>>GEN:xxx` 生成段,手改会被覆盖且 `--check` 会红。
>
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。**
## 〇、一张图
```
packs/<app>/ ← 业务真源(你写的)
Cargo.toml 不声明外部依赖(sspf 走 .cargo/config.toml 的 --extern)
pack.toml 清单:app_code / 表 / 契约版本区间
schema/001_init.sql 建表(跟着包走,include_str! 进二进制)
src/lib.rs 列 + spec + 菜单 + 面 B 路由 + Pack 实现
src/backend/src/modules/<app>.rs ← 面 A 适配器(你写的,或脚本生成后微调)
3 个 handler + ROUTES + router()
spec / 菜单只 pub use 转发(不许重写第二份)
↓ python3 scripts/pack-sync.py(生成,别手改)
src/backend/src/packs_gen.rs ← 装载调用 + pack.toml 的 JSON 快照
src/backend/src/modules/mod.rs ← MODS / SPECS / ROUTES / MENUS / ROUTER 五段
src/backend/Cargo.toml ← # >>>GEN:PACK_DEPS(包的 path 依赖)
↓ ssfp::Platform::new().packs(reg).router(modules::router()).serve()
面 A /api/ssw/<app>/<Entity>/… ← 前端在用
面 B /api/<app>/<Entity> ← 官方 JNPF 形状
```
## 一、生成一个包(一条命令)
```bash
bash scripts/new-pack.sh blog Post --name "文章" \
--columns "title:VARCHAR(255),body:TEXT,pv:INTEGER"
```
它会:
1. 建 `packs/blog/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}`(表名 `blog_post`;`Cargo.toml` 的 `[dependencies]` **留空**);
2. 建 `src/backend/src/modules/blog.rs`(面 A 适配器,3 条路由);
3. 跑 `pack-sync.py` 把四处生成位置补齐。
然后:
```bash
cargo check # 编译
bash scripts/verify.sh # 静态判据 + 全量测试 + 两把运行时尺子
```
> 🔴 **不写 `--columns` 也能跑**:只生成 `f_id` + 创建人/时间四列,之后手工补。
> 🔴 **列类型**用 SQL 类型(`VARCHAR(255)` / `NUMERIC(12,2)` / `INTEGER` / `TIMESTAMP(0)`);
> `NUMERIC` / `DECIMAL` 会自动进 `numeric_columns`(响应序列化成 JSON **字符串** `"9.90"`)。
## 二、命名约定(先想清楚)
| 东西 | 约定 | 例 |
|---|---|---|
| `app_code` | 小写、与 `packs/<app>/` 目录名**逐字一致** | `blog` |
| 实体 | UpperCamelCase | `Post` |
| 表名 | `<app>_<entity_snake>` | `blog_post` |
| 列 | `f_` 前缀 + snake_case | `f_title` |
| JSON 键 | 去 `f_` 前缀后 camelCase | `title` |
| 菜单 `id` | `m_<app>` | `m_blog` |
| 菜单 `url_address` | `<app>/<Entity>` | `blog/Post` |
| spec 的 `module_key` | **必须等于** `url_address`(也等于前端 Route path) | `blog/Post` |
🔴 `module_key != url_address` 的后果是**静默放行**(菜单查不到 ⇒ 权限守卫直接放行)。
## 三、包里的四个文件
### 3.1 `pack.toml`
```toml
[pack]
app_code = "blog"
name = "文章"
version = "1.0.0"
kernel = ">=0.4,<0.5" # 契约版本区间(业务包要求的平台契约版本)
migratable = true
[[pack.tables]]
name = "blog_post"
ddl = "schema/001_init.sql"
baseline_table = "blog_post"
```
🔴 `kernel` 不是 cargo 版本,是 `sspf::kernel::bootstrap::kernel_version()` 那个**契约版本**
(当前 `0.4.0`);写错区间 ⇒ 装载直接报 `LoadError::KernelMismatch`。
### 3.2 `schema/001_init.sql`
```sql
CREATE TABLE IF NOT EXISTS blog_post (
f_id VARCHAR(50) NOT NULL,
f_title VARCHAR(255),
f_creator_user_id VARCHAR(50),
f_creator_time TIMESTAMP(0) WITHOUT TIME ZONE,
f_delete_mark INTEGER DEFAULT 0,
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
PRIMARY KEY (f_id, f_tenant_id)
);
```
🔴 **必须幂等**(`IF NOT EXISTS`):启动时每次都会跑一遍。
🔴 **必须带 `f_tenant_id` 并进复合主键**:装载器有硬闸门(`pack_ddls_carry_tenant_id_and_composite_key`)。
🔴 **不许建 `base_*`**:平台表归 `sspf` 管,装载器会拒载。
🔴 **spec 的列清单里不要写 `f_tenant_id`** ⇒ 面 A / 面 B 的 JSON 形状不受它影响。
### 3.3 `src/lib.rs`
四样东西,顺序固定:
1. `DDLS: &[(&str, &str)]` —— `表名 → include_str!` 的 DDL;
2. `*_SPEC: EntitySpec` —— `app_code` / `entity` / `table` / `module_key` / `columns` / `numeric_columns`;
3. `*_MENU: MenuSpec` —— 内置菜单(`url_address` 必须 == `module_key`);
4. `*_ROUTES: &[PackRoute]`(**面 B**,官方 RESTful 形状)+ `impl BusinessPack for Pack`。
🔴 **类型名固定 `Pack`**:`packs_gen.rs` 按 `sspf_pack_<app>::Pack` 拼路径。
🔴 **每条实体恰好 3 条路由**(List / Save / Delete)—— 装载自检钉住这个数。
🔴 **面 B 是声明不是 handler**:`PackRoute` 里没有 axum 类型 ⇒ 包不依赖 axum,
内核按声明 + spec 生成 handler。
### 3.4 `src/backend/src/modules/<app>.rs`(面 A)
```rust
pub use sspf_pack_blog::POST_MENU;
pub use sspf_pack_blog::POST_SPEC;
pub const ROUTES: [&str; 3] = [
"/api/ssw/blog/Post/List",
"/api/ssw/blog/Post/Save",
"/api/ssw/blog/Post/Delete",
];
```
三个 handler 都是三行(`handle_list` / `handle_save` / `handle_delete`),
模板见 `new-pack.sh` 生成的那份。
🔴 **只准 `pub use` 转发 spec**:两份 spec 拷贝迟早分叉;`pack-sync.py`
在没有 `pub use ..._SPEC` 时直接报错。
## 四、改已有包(加列 / 改菜单 / 加路由)
| 改什么 | 改哪里 | 之后 |
|---|---|---|
| 加一列 | `packs/<app>/src/lib.rs` 的 `*_COLUMNS` + `schema/001_init.sql` | 新库直接生效;**老库要自己 `ALTER TABLE`**(DDL 是 `IF NOT EXISTS`,不会改已有表) |
| 改菜单名 / 排序 | `packs/<app>/src/lib.rs` 的 `*_MENU` | 重启;种子幂等(按 `f_id`) |
| 加面 B 路由 | `*_ROUTES`(**每条实体恒 3 条**,别加第 4 条) | 重启 |
| 加面 A 路由 | `modules/<app>.rs` 的 `ROUTES` + handler + `router()` | 重启 |
| 改 `pack.toml` | 改了就跑 `python3 scripts/pack-sync.py` | 忘了 `--check` 会红 |
## 五、验证
```bash
python3 scripts/pack-sync.py --check # 生成物不漂移
python3 scripts/check-scaffold.py # 本仓只准有业务(6 条)
cargo test --workspace # 包自检 + 应用装配
bash scripts/perm-smoke.sh # 面 A 32 条(默认自起隔离后端)
bash scripts/perm-smoke-jnpf.sh # 面 B 18 条
bash scripts/verify.sh # 上面全部,一条命令
```
### 5.1 追加断言(别新写脚本)
新模块要证明「真的能用」,加到 `scripts/perm-smoke.sh` 里(照 demo / shop / books 的段落抄):
```bash
# 新建 → 断言主键 36 位 → 断言 numeric 往返是 JSON 字符串 → 无 token 600 → 未授权 403
```
🔴 **加了断言必须同步契约**:`docs/contract.md` 附录 A 的 `[RULER]` 里
`perm-smoke.sh` 的条数要改成实际值,否则尺子自证失败(**这是故意的**:防止有人把尺子改弱)。
同理 `[MENU_TREE]`(菜单树字符串)、`[MENU]` / `[MODULE]` / `[ENDPOINT]` 三张表也要同步。
### 5.2 前端(可选)
前端是 `src/frontend/`(React + Vite):
1. `src/frontend/src/api/<app>.ts` —— 3 个函数(`list` / `save` / `del`),照 `api/product.ts`;
2. `src/frontend/src/views/<Entity>.tsx` —— 列表页,照 `views/Product.tsx`;
3. `src/frontend/src/App.tsx` —— 注册路由(**path 必须等于菜单 `url_address`**)。
改完 `cd src/frontend && npm run build` ⇒ 产物落 `src/frontend/dist/`,后端直接托管。
## 六、常见坑
| 现象 | 原因 | 修法 |
|---|---|---|
| 面 A 全部 404 | 包没被装载 | 看 `packs_gen.rs` 的 `>>>GEN:PACKS` 段;跑 `pack-sync.py` |
| 面 B 全部 404 | `PackRoute` 路径不是官方形状 | `/api/{app}/{Entity}` + `/api/{app}/{Entity}/{id}` 才对 |
| 装包报 `KernelMismatch` | `kernel` 区间不含当前契约版本 | 改区间(当前 `>=0.4,<0.5`) |
| 装包报 `AppCodeMismatch` | `pack.toml` 的 `app_code` ≠ 目录名 | 改成一致 |
| 启动报「DDL 试图建 base_*」 | 包 DDL 里写了平台表 | 删掉;平台表归 `sspf` |
| 启动报「缺 f_tenant_id / 复合主键」 | 包 DDL 少了租户列 | 按 §3.2 补 |
| 菜单树里没有新模块 | `BusinessPack::menus()` 没返回它 | 补 `&[<X>_MENU]` |
| 非管理员访问新模块 403 | 没给该用户授权 | 正常行为(管理员短路) |
| 非管理员访问新模块 200(本该 403) | `module_key` ≠ `url_address` ⇒ 查不到菜单 ⇒ **放行** | 两处改成一致 |
| `cargo check` 报找不到 `sspf` | 没网 / Gitea 不通 | 见 `~/.cargo/git` 缓存;确认 tag 存在 |
## 七、写之前的自查
1. **表名 / 列名对不对齐基线**?(迁 JNPF 时靠列名导数据)
2. **`module_key` == `url_address` == 前端 Route path**?(三处一字不差)
3. **有金额列吗**?有 ⇒ 必须 `NUMERIC` 且进 `numeric_columns`(JSON 字符串 `"9.90"`)。
4. **DDL 幂等吗**?`IF NOT EXISTS` + `f_tenant_id` + 复合主键。
5. **改了 `pack.toml` 跑 `pack-sync.py` 了吗**?