- 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 断言)。
212 lines
9.4 KiB
Markdown
212 lines
9.4 KiB
Markdown
# 加一个业务模块(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` 了吗**?
|