# 加一个业务模块(AI 开发主线) > 🔴 **2026-11-04 起流程变了**:平台不在本仓(在已发布的 `sspf` 包里), > 「加模块」= **写一个业务包 + 一个面 A 适配器**,其余四处派生位置**由脚本生成**。 > 上一版的「8 个文件 / 10 个接触点 / 手改 `db/schema.sql`」已经作废 —— > 那些位置现在都是 `// >>>GEN:xxx` 生成段,手改会被覆盖且 `--check` 会红。 > > 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。** ## 〇、一张图 ``` packs// ← 业务真源(你写的) Cargo.toml 只依赖 sspf 门面 pack.toml 清单:app_code / 表 / 契约版本区间 schema/001_init.sql 建表(跟着包走,include_str! 进二进制) src/lib.rs 列 + spec + 菜单 + 面 B 路由 + Pack 实现 src/backend/src/modules/.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///… ← 前端在用 面 B /api// ← 官方 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`); 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//` 目录名**逐字一致** | `blog` | | 实体 | UpperCamelCase | `Post` | | 表名 | `_` | `blog_post` | | 列 | `f_` 前缀 + snake_case | `f_title` | | JSON 键 | 去 `f_` 前缀后 camelCase | `title` | | 菜单 `id` | `m_` | `m_blog` | | 菜单 `url_address` | `/` | `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_::Pack` 拼路径。 🔴 **每条实体恰好 3 条路由**(List / Save / Delete)—— 装载自检钉住这个数。 🔴 **面 B 是声明不是 handler**:`PackRoute` 里没有 axum 类型 ⇒ 包不依赖 axum, 内核按声明 + spec 生成 handler。 ### 3.4 `src/backend/src/modules/.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//src/lib.rs` 的 `*_COLUMNS` + `schema/001_init.sql` | 新库直接生效;**老库要自己 `ALTER TABLE`**(DDL 是 `IF NOT EXISTS`,不会改已有表) | | 改菜单名 / 排序 | `packs//src/lib.rs` 的 `*_MENU` | 重启;种子幂等(按 `f_id`) | | 加面 B 路由 | `*_ROUTES`(**每条实体恒 3 条**,别加第 4 条) | 重启 | | 加面 A 路由 | `modules/.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/.ts` —— 3 个函数(`list` / `save` / `del`),照 `api/product.ts`; 2. `src/frontend/src/views/.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()` 没返回它 | 补 `&[_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` 了吗**?