- 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 断言)。
9.4 KiB
加一个业务模块(AI 开发主线)
🔴 2026-11-04 起流程变了:平台不在本仓(在已发布的
sspf包里), 「加模块」= 写一个业务包 + 一个面 A 适配器,其余四处派生位置由脚本生成。 上一版的「8 个文件 / 10 个接触点 / 手改db/schema.sql」已经作废 —— 那些位置现在都是// >>>GEN:xxx生成段,手改会被覆盖且--check会红。契约红线见
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 scripts/new-pack.sh blog Post --name "文章" \
--columns "title:VARCHAR(255),body:TEXT,pv:INTEGER"
它会:
- 建
packs/blog/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}(表名blog_post;Cargo.toml的[dependencies]留空); - 建
src/backend/src/modules/blog.rs(面 A 适配器,3 条路由); - 跑
pack-sync.py把四处生成位置补齐。
然后:
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
[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
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
四样东西,顺序固定:
DDLS: &[(&str, &str)]——表名 → include_str!的 DDL;*_SPEC: EntitySpec——app_code/entity/table/module_key/columns/numeric_columns;*_MENU: MenuSpec—— 内置菜单(url_address必须 ==module_key);*_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)
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 会红 |
五、验证
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 的段落抄):
# 新建 → 断言主键 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):
src/frontend/src/api/<app>.ts—— 3 个函数(list/save/del),照api/product.ts;src/frontend/src/views/<Entity>.tsx—— 列表页,照views/Product.tsx;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 存在 |
七、写之前的自查
- 表名 / 列名对不对齐基线?(迁 JNPF 时靠列名导数据)
module_key==url_address== 前端 Route path?(三处一字不差)- 有金额列吗?有 ⇒ 必须
NUMERIC且进numeric_columns(JSON 字符串"9.90")。 - DDL 幂等吗?
IF NOT EXISTS+f_tenant_id+ 复合主键。 - 改了
pack.toml跑pack-sync.py了吗?