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

9.4 KiB
Raw Blame History

加一个业务模块(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"

它会:

  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 把四处生成位置补齐。

然后:

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

四样东西,顺序固定:

  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)

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):

  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 了吗?