- 内核只有 lib:启动装配 → crates/sspf-admin(bin sspf-admin);37 个集成测试 → crates/tests(package sspf-tests)。
- demo/shop/books 的 spec/菜单/DDL/面 B 路由搬进 packs/{demo,shop,books};内核 modules/*.rs 只剩「面 A 适配器 + pub use」⇒ 内核零业务知识,示例可整目录搬走。面 A 与前端零改动。
- 示例表 DDL 按平台规则补 f_tenant_id + 复合主键(spec 不加 ⇒ JSON 键与响应逐字不变)。
- 修 is_builtin_table 只认 schema.sql 的漏洞:包表(含 asset_data_resource)此前可被建模页删除/改;现为「平台 DDL ∪ 包表」。
- sspf-compat-online_dev → onlinedev(包名/模块/文件/路由别名同步);6 个 5 行转发壳合并为 forward.rs。
- 新增 AR16 闸门 + lib.rs「30 秒地图」+ src/backend/README.md;pack-sync 补两处判据(module_key=None 的 urlAddress、apiFile 查存在性)。
- 回归:704 tests / 6 道静态闸门全绿;health 181 表;四个包面 A/面 B 运行时全部 200。
25 KiB
加一个业务模块(AI 开发主线)
🔴 2026-11-01 起:一条命令。 本文后半部分的「改哪个文件」清单写于批次 12 之前, 已过时(
db/schema.sql不用改、modules/mod.rs不用改、契约不用手抄)。 以本节为准:bash scripts/new-pack.sh crm Customer --name "客户" \ --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend bash scripts/verify.sh --fast # 纯静态:文件和接线一致 bash scripts/verify.sh --lib # + 单测 + **包冒烟**(真起库、真打 List)🔴 两道都要过:
--fast只证明「该接的地方都接上了」,证明不了「接的活能应答」 —— 表没建出来 / 面 B 路由没 merge /module_key指向不存在的菜单,这三种 静态闸门全绿,只有--lib里的包冒烟(crates/tests/tests/pack_smoke_it.rs)会红。它建
packs/<app>/(真源)+modules/<app>.rs(面 A 适配器), 再把四处生成位置补齐(packs_gen.rs/modules/mod.rs五段 /Cargo.toml依赖段 /docs/contract.md三段)。 生成物手改会在下次pack-sync.py被覆盖,而verify.sh第一步就会红。
参照实现 = 内置的四个模块
(demo/DemoItem · shop/Product · books/Book · asset/DataResource(真实业务))
——要读就抄 packs/asset/,它是完整样板。
契约红线见
SKILL.md§「契约红线」。本文件只讲「改了哪儿、怎么验证」。
〇.5、它内部做了什么(排错时照着看)
1. packs/<app>/src/lib.rs 【真源】EntitySpec + MenuSpec + PackRoute×3 + Pack + DDLS
2. packs/<app>/schema/*.sql 业务表 DDL(include_str! 编进二进制;**不进 db/schema.sql**)
3. packs/<app>/pack.toml 包清单(catalog;内核读的是 pack-sync 生成的 JSON 快照)
4. packs/<app>/Cargo.toml 只依赖 sspf-sdk(AR2:不许 axum / tokio / pglite)
5. src/modules/<app>.rs 面 A 适配器:pub use 包的 spec + 3 个 handler + router()
↓ 以下四处**全部由 scripts/pack-sync.py 从「packs/* + modules/*.rs」生成**
6. src/backend/src/packs_gen.rs 内核包清单(每个包一条 load_static 调用)
7. src/modules/mod.rs 五段:pub mod / ALL_SPECS / ALL_ROUTES / ALL_MENUS / router()
8. src/backend/Cargo.toml >>>GEN:PACK_DEPS 段
9. docs/contract.md 附录 A [MODULE] / [MENU] / [ENDPOINT] 的生成段
10. frontend/src/{api,views}/… + App.tsx 的 <Route>(new-page.sh,--with-frontend)
⇒ bash scripts/verify.sh --fast 必须全 ✅(文件与接线)
⇒ bash scripts/verify.sh --lib 必须全 ✅(+ 包冒烟:List 真应答)
🔴 漏了会怎样(这就是为什么不再让人手抄):
| 漏哪一步 | 现象 | 报错吗 | 谁兜住 |
|---|---|---|---|
6(packs_gen.rs) |
面 B 端点 404,列表永远空 | ❌ 不报 | verify.sh --lib 包冒烟 |
7(ALL_MENUS) |
菜单不种 ⇒ 守卫查不到菜单 ⇒ 越权放行 | ❌ 不报 | 单测 every_pack_loads_with_…(结构性) |
7(router()) |
面 A 404 ⇒ MVP 前端页面空着 | ❌ 不报 | verify.sh --lib 包冒烟 |
| DDL 少一列 | 投影 SQL 报错 ⇒ 列表恒 {"code":400} |
❌ 不报 | verify.sh --lib 包冒烟 |
| 8(Cargo 依赖) | 编译失败 | ✅ 报 | 编译 |
| 9(契约) | check-contract 红 |
✅ 报 | verify.sh --fast |
🔴 平台层(src/platform/)与入口文件(crates/sspf-admin/src/main.rs)一个字都不用改 ——
加业务模块不碰平台层,由尺子 bash scripts/check-boundary.sh(CP1–CP6)钉住:
平台层出现任何业务标识符(表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)⇒ 红。
〇、命名约定(先想清楚再动)
| 位置 | 约定 | 例(books / Book) |
|---|---|---|
app_code |
小写业务名,同时是 URL 段 | books |
entity |
大驼峰,同时是 URL 段 | Book |
| 表名 | 蛇形,官方没有对应表 ⇒ 自己起(推荐 {app}_{entity 小写}) |
book_shop_book |
| 前端 api 文件 | entity 小写 | src/api/book.ts |
| 前端 view 文件 | entity 大驼峰 | src/views/Book.tsx |
| Route path | = 菜单 url_address(去前导斜杠) |
books/Book |
| 菜单种子 id | m_ + entity 小写 |
m_book |
| 列表函数名 | list + 复数(复数规则见 check-module.sh 的 plural()) |
listBooks |
| 单条函数名 | save / delete + entity |
saveBook / deleteBook |
🔴 表名不与官方对齐是刻意的(官方没有低代码业务表)——但两版后端(react 版 / rust 版)之间要同名,
才能开同一个库。demo_item / shop_product / book_shop_book 就是这么定的。
一、要碰的 8 个文件(10 个接触点)
| # | 文件 | 改什么 | 漏了会怎样 |
|---|---|---|---|
| 1 | src/backend/db/schema.sql |
CREATE TABLE {table} |
端点 500(表不存在) |
| 2 | src/backend/src/modules/<app>.rs |
新文件:spec + *_MENU + 3 个 handler + router() |
端点 404(没注册)/ 菜单不显示 |
| 3 | src/backend/src/modules/mod.rs |
ALL_SPECS 加一条 + ALL_MENUS 加一条 + router() merge 一行 + ALL_ROUTES 加 3 条 |
启动自检失败 / 端点 404 / 菜单不被种、admin 少一条授权 |
| 4 | src/frontend/src/api/<lc>.ts |
3 个函数 | 页面发请求 404 |
| 5 | src/frontend/src/views/<Ent>.tsx |
列表页 | 页面空白 |
| 6 | src/frontend/src/App.tsx |
<Route path="/<route>"> |
页面 404 |
| 7 | docs/contract.md |
附录 A:[MODULE] 加一行 + [MENU] 加一行 + [ENDPOINT] 加 3 行(本模块的 3 条端点)+ [FACE] 的 A 条数 +3(期望值真源) |
自检退出码 2(闸门形同虚设)/ check-contract.sh 红 |
| 8 | scripts/perm-smoke.sh |
追加该模块的断言 | 新模块无端到端覆盖 |
外加两条一致性:
spec.module_key==menu.url_address==App.tsx的 Route path —— 三处一字不差。 不一致的后果是静默放行(未映射到菜单就放行,不报错)。- 🔴 入口文件也不碰:
crates/sspf-admin/src/main.rs的BASE_TABLES只列 8 张base_*(8 张全部逐字对齐官方 DDL,含多应用注册表base_system), 业务表由modules::all_specs()派生并与db/schema.sql双向对账 ⇒ 加业务表不用改crates/sspf-admin/src/main.rs。
🔴 分层铁律:后端代码分两层——
| 层 | 目录 | 内容 | 加模块时 |
|---|---|---|---|
| 平台层 | crates/sspf-core/ + crates/sspf-compat-*/ |
契约实现(信封 / cipher / 登录 / 权限 / base_* 管理 / 面 B / CRUD 引擎) |
一个字都不改 |
| 业务层 | src/backend/src/modules/ |
业务 spec + 业务菜单 + handler + 路由 | 只改这里 |
| 装配根 | src/backend/src/bootstrap.rs |
唯一同时认识两层的地方 | 一个字都不改 |
🔴 M7 起平台层路径变了:
src/backend/src/platform/的转发壳已整体删除。 平台能力现在直接从 crate 引:sspf_core::…(平台核心)/crate::compat::<域>::…(契约面)。
(对齐 react 版的 common+auth+sys / demo+shop+books,
以及官方 JNPF 的 jnpf-common+jnpf-system / jnpf-admin。)
二、后端四处改什么
2.1 db/schema.sql —— 建表
照抄 book_shop_book 的形状:
CREATE TABLE {table} (
f_id VARCHAR(50) NOT NULL,
f_title VARCHAR(200),
f_price NUMERIC(12,2),
f_stock INT,
f_creator_user_id VARCHAR(50),
f_creator_time TIMESTAMP,
f_delete_mark INT DEFAULT 0,
CONSTRAINT pk_{table} PRIMARY KEY (f_id)
);
红线:
- 列名全部
f_前缀;主键f_id VARCHAR(50)(不是 32——36 位 UUID 装不下)。 - 软删列
f_delete_mark INT DEFAULT 0(不是物理 DELETE)。 - 🔴 numeric 列(金额) ⇒ spec 里要标
numeric: true(投影::text⇒ JSON 字符串"9.90")。 - 🔴 改了 schema.sql 不生效:schema 只在首次建表时执行 ⇒ 改完要清空
data/重建。
2.2 src/modules/<app>.rs —— 【新文件】spec + handler + 路由
照抄 src/backend/src/modules/shop.rs(最接近的参照实现)。一个文件三块:
//! shoes —— 业务模块:Shoe(物理表 `shoe_item`)。
use axum::body::Bytes;
use axum::extract::{RawQuery, State};
use axum::http::HeaderMap;
use axum::routing::{delete, get, post};
use axum::{Json, Router};
use sspf_core::crud::{handle_delete, handle_list, handle_save};
use sspf_core::entity::{ColumnSpec, EntitySpec};
use sspf_core::envelope::ActionResult;
use sspf_core::state::AppState;
/// ① spec 的列清单(**顺序 = 响应 JSON 的键序**)。
const SHOE_COLUMNS: &[ColumnSpec] = &[
ColumnSpec { column: "f_id", json_key: "id", default: None, numeric: false },
ColumnSpec { column: "f_title", json_key: "title", default: None, numeric: false },
ColumnSpec { column: "f_price", json_key: "price", default: Some("0.00"), numeric: true },
ColumnSpec { column: "f_creator_user_id", json_key: "creatorUserId", default: None, numeric: false },
ColumnSpec { column: "f_creator_time", json_key: "creatorTime", default: None, numeric: false },
ColumnSpec { column: "f_delete_mark", json_key: "deleteMark", default: Some("0"), numeric: false },
];
/// ② spec 本体。
pub const SHOE_SPEC: EntitySpec = EntitySpec {
app_code: "shoes",
entity: "Shoe",
table: "shoe_item",
module_key: Some("shoes/Shoe"), // 🔴 None ⇒ 仅登录(demo 就是 None)
columns: SHOE_COLUMNS,
numeric_columns: &["f_price"], // 🔴 必须与每列的 numeric 标记一致(有单测钉)
// 🔴 `f_creator_user_id` 的写死规则(裁决 S22):
// `Some("admin")` ⇒ 恒写 admin(demo 的规则);`None` ⇒ `body.creatorUserId || 'admin'`。
creator_fixed: None,
};
/// ③ 本模块的 3 条路由(**业务层的路由表**)—— 钉子测试遍历它。
pub const ROUTES: [&str; 3] = [
"/api/ssw/shoes/Shoe/List",
"/api/ssw/shoes/Shoe/Save",
"/api/ssw/shoes/Shoe/Delete",
];
// ---- 3 个 handler:不要重写业务逻辑 ----
// `handle_list` / `handle_save` / `handle_delete`(平台层)已经把
// 守卫、SQL 拼装、投影、软删、序列化全包了。
/// `GET /api/ssw/shoes/Shoe/List`。
pub async fn shoe_list(State(state): State<AppState>, headers: HeaderMap) -> Json<ActionResult> {
handle_list(&state, &headers, &SHOE_SPEC).await
}
/// `POST /api/ssw/shoes/Shoe/Save`。
pub async fn shoe_save(
State(state): State<AppState>,
headers: HeaderMap,
body: Bytes,
) -> Json<ActionResult> {
handle_save(&state, &headers, &SHOE_SPEC, &body).await
}
/// `DELETE /api/ssw/shoes/Shoe/Delete?id=`。
pub async fn shoe_delete(
State(state): State<AppState>,
headers: HeaderMap,
raw: RawQuery,
) -> Json<ActionResult> {
handle_delete(&state, &headers, &SHOE_SPEC, &raw).await
}
/// 本模块的路由(`Router::merge` 进总路由,**对齐 NestJS 的 module 注册**)。
pub fn router() -> Router<AppState> {
Router::new()
.route(ROUTES[0], get(shoe_list))
.route(ROUTES[1], post(shoe_save))
.route(ROUTES[2], delete(shoe_delete))
}
🔴 json_key 必须等于 db::column_to_json_key(column)(f_title ⇒ title)—— 有单测钉死,不一致会红。
🔴 列顺序 = 响应 JSON 的键序(照抄参照模块,别自作主张排序)。
🔴 default 只在「路径 1(无 id 的新建)」生效——带 id 但库里没这行时,一个默认值都不加。
🔴 handler 签名不要改:Save 收 body: Bytes(自己解析,不走 Json<T>),
Delete 收 raw: RawQuery(?id=)—— handle_save / handle_delete 依赖这个形状。
🔴 spec 写成 const(不是 fn find_spec(..).expect(..))—— 非测试代码零 unwrap() / expect() / panic!() 是项目红线。
2.3 src/modules/mod.rs —— 登记这个模块(3 处)
pub mod books;
pub mod demo;
pub mod shop; // 🔴 加这一行
pub const ALL_SPECS: &[EntitySpec] = &[
demo::DEMO_SPEC,
shop::PRODUCT_SPEC,
books::BOOK_SPEC,
shoes::SHOE_SPEC, // 🔴 加这一条
];
pub const ALL_ROUTES: &[&str] = &[
demo::ROUTES[0],
demo::ROUTES[1],
demo::ROUTES[2],
shop::ROUTES[0],
shop::ROUTES[1],
shop::ROUTES[2],
books::ROUTES[0],
books::ROUTES[1],
books::ROUTES[2],
shoes::ROUTES[0], // 🔴 加这三条
shoes::ROUTES[1],
shoes::ROUTES[2],
];
pub fn router() -> Router<AppState> {
demo::router()
.merge(shop::router())
.merge(books::router())
.merge(shoes::router()) // 🔴 加这一行
}
🔴 ALL_SPECS 漏了 ⇒ 启动时的标识符白名单自检会失败(spec 表 … 在 db/schema.sql 里没有 CREATE TABLE)——
记得同时把新表加进 src/backend/db/schema.sql(crates/sspf-admin/src/main.rs 不用改 ⇒ 业务表由 spec 派生)。
🔴 ALL_MENUS 漏了 ⇒ 菜单不会被种、admin 少一条授权 ⇒ 侧栏少一项。
🔴 router() 漏了 merge ⇒ 端点 404。
🔴 ALL_ROUTES 漏了 ⇒ 路由表钉子测试不会报错(它只遍历这张表)⇒ 静默失去覆盖 ⇒ 一定要加。
2.4 src/modules/<app>.rs —— 声明自己的内置菜单
🔴 业务菜单住在业务层(与 EntitySpec 同理:f_url_address 与 f_en_code 都是业务知识)。
在本模块文件里加一条(与 *_SPEC 同级):
use sspf_core::menu::MenuSpec; // 🔴 类型住在平台层,**值**住在业务层
pub const SHOE_MENU: MenuSpec = MenuSpec {
id: "m_shoe",
full_name: "鞋",
en_code: "permission.shoes.shoe", // 🔴 面 B 的点权限编码(官方 @SaCheckPermission 的判据)
url_address: "shoes/Shoe", // 🔴 必须 == Route path == spec.module_key
parent_id: "0",
menu_type: 2, // 1 = 目录,2 = 页面(官方 f_type 是 **INTEGER**)
icon: None,
sort_code: 9,
};
再在 src/backend/src/modules/mod.rs 的 ALL_MENUS 里加一条 shoes::SHOE_MENU,。
🔴 还要在契约里登记(docs/contract.md 附录 A):
[MODULE]加一行:shoes Shoe shoe_item shoes/Shoe shoes/Shoe m_shoe 有 shoes.rs[MENU]加一行:m_shoe 鞋 permission.shoes.shoe shoes/Shoe 0 2 9[ENDPOINT]加三行(本模块的 3 条端点,face一律A,guard=shoes/Shoe(=module_key;仅登录的模块写登录),owner=shoes):A GET /api/ssw/shoes/Shoe/List shoes/Shoe shoes A POST /api/ssw/shoes/Shoe/Save shoes/Shoe shoes A DELETE /api/ssw/shoes/Shoe/Delete shoes/Shoe shoes[FACE]的 A 条数 +3(面 A 专属端点多了 3 条)
⇒ 这几行是尺子的期望值真源(check-module.sh / check-boundary.sh / check-contract.sh
都从那里读)⇒
代码里的 *_MENU 与契约那一行必须逐字一致(check-module.sh 会逐字段比对);
代码里注册的路由与 [ENDPOINT] 那三行必须逐条一致(check-contract.sh 对账)。
🔴 种子是「幂等 ensure」:启动时按 f_url_address 或 f_id 判存在 ⇒
改了 url_address 必须重启回灌;软删行不复活、不覆盖已改值。
🔴 改了种子要重启进程才会回灌存量库,不必删库重建。
🔴 en_code 是面 B 的点权限判据(base_module.f_en_code)—— 面 A 看 f_url_address、
面 B 看 f_en_code,两套并存。迁移前要补(见 MIGRATION.md §2.4)。
🔴 平台层不许出现这条菜单(platform/seed.rs 只自带 5 条系统菜单)⇒
bash scripts/check-boundary.sh 会红。
三、前端三文件改什么
3.1 src/api/<lc>.ts —— 3 个函数
import request from './request';
export const listShoes = () => request.get('/ssw/shoes/Shoe/List');
export const saveShoe = (dto: any) => request.post('/ssw/shoes/Shoe/Save', dto);
export const deleteShoe = (id: string) => request.delete(`/ssw/shoes/Shoe/Delete?id=${id}`);
🔴 request.ts 的 baseURL 是 /api ⇒ 这里不要再写 /api 前缀。
🔴 函数名规则:list + 复数(plural():s/x/ch/sh → +es;辅音 + y → ies;否则 +s),
save/delete + entity。check-module.sh 按这个规则查。
3.2 src/views/<Ent>.tsx —— 列表页
照抄 views/Book.tsx(含 numeric 往返、删除确认、错误提示)。
🔴 金额展示别用 Number() 转——后端给的是字符串 "9.90",转数字会丢尾零。
3.3 src/App.tsx —— 注册路由
import Shoe from './views/Shoe';
…
<Route path="/shoes/Shoe" element={<RequireAuth><Shoe /></RequireAuth>} />
🔴 Route path 必须 == 菜单 url_address(去前导斜杠)—— 不一致 ⇒ 侧栏点了 404。
🔴 JSX 常写成多行(<Route\n path=…>)⇒ check-module.sh 用 tr '\n' ' ' 去换行再匹配。
四、菜单 + 授权
- 菜单:在业务模块里声明(
modules/<app>.rs的*_MENU,见 2.4)⇒ 前端侧栏由 后端返回的菜单树驱动 ⇒ 不用改前端导航。 - 授权:默认不授权 ⇒ 非管理员看不到、访问 403(这是对的)。
要让某个角色看到 ⇒ 写
base_authorize(f_object_type='role'+f_object_id=<roleId>+f_item_type='module'+f_item_id=<menuId>)。 走PUT /api/permission/Authority/Data/{objectId}(objectType小写'role',module传一维数组)。 - admin 角色:
platform/seed.rs的ensure_admin_authorizations会自动补 全部内置菜单(5 条系统菜单 + 业务层声明的那几条)的授权 ⇒ 管理员开箱即用,普通角色要手动授权。
五、验证(追加断言,别新写脚本)
5.1 静态自检(改完立刻跑,先于 perm-smoke)
bash scripts/check-module.sh shoes Shoe # 单模块
bash scripts/check-module.sh # 契约登记的全部模块 + 全局红线
bash scripts/check-contract.sh # 契约端点表 ↔ 代码真实路由(全局)
🔴 先在契约里登记(§一 第 7 步)—— docs/contract.md 附录 A:
[MODULE] 加一行(app / entity / 表名 / urlAddress / moduleKey / 菜单 id / 有无 api 文件 / 模块文件名)、
[MENU] 加一行(菜单 id / 名称 / enCode / urlAddress / parentId / type / icon / sortCode)、
[ENDPOINT] 加三行(本模块的 3 条端点:face / method / path / guard / owner)、
[FACE] 的 A 条数 +3。
🔴 check-module.sh 里不再有期望表(全部从契约读)⇒ 加模块不用改脚本,
但必须改契约,否则脚本判「契约 [MODULE] 里没有这个模块」退出 2。
🔴 check-contract.sh 同理:代码里注册了路由而契约 [ENDPOINT] 没登记 ⇒ 红。
5.2 端到端(scripts/perm-smoke.sh 追加断言)
必选 4 条(每个业务模块都有):
GET /api/ssw/{app}/{Ent}/List无 token ⇒code=600- 无 token ⇒
code=600(同上一条,测的是端点在、守卫在) - 非管理员未授权 ⇒
code=403 - 管理员新建一条 ⇒
code=200+ 回读列表里能看到(长度 +1)
每个业务字段加一条往返断言(防 numeric/text/int 转换 bug):
# numeric ⇒ JSON 字符串(带尾零);int ⇒ JSON 数字
# 例:Shoe 的 f_price 回显必须等于 "9.90"(字符串),f_stock 必须等于 100(数字)
🔴 判据要比原始 JSON 文本——字符串 "9.90" 与数字 9.9 在 jq 里都能取到,
只有比原始文本才分得出来。
🔴 别用 --data-urlencode 配 -G(curl 里两个互斥)——body 用 -d,query 用 -G。
🔴 本机 curl 走系统代理 ⇒ 测 localhost 必须 --noproxy '*'。
5.3 六道闸门全绿才算完
cargo test # 221 条(lib 98 + 集成 123)
bash scripts/check-module.sh # 静态闸门 1:10 接触点(114 条 = 4 模块 × 28 + 全局 2)
bash scripts/check-boundary.sh # 静态闸门 2:分层红线 CP1–CP6(11 条)
bash scripts/check-contract.sh # 静态闸门 3:契约端点表 + 官方端点台账 ↔ 代码真实路由(10 条)
bash scripts/check-citations.sh # 静态闸门 4:文档引文 `路径:行号`(4 条)
bash scripts/perm-smoke.sh # 契约尺子·面 A:43 条(**后端不用先起** ⇒ 不通则自起隔离实例)
bash scripts/perm-smoke-jnpf.sh # 契约尺子·面 B:19 条(面 A 不受影响时也应保持 19/19)
🔴 两把尺子默认自起隔离后端(scripts/smoke_backend.sh):没给 B ⇒ 先探 :30010,
通了就用它、不通就自起隔离实例(空闲端口 + 临时 PGLITE_DIR)⇒ 跑完即删、不留脏数据、
两把尺子互不污染、CI 可跑;显式给了 B ⇒ 不自起(不可达 ⇒ 退出码 2)。
🔴 每道闸门都会自证:跑出来的条数必须等于契约 [RULER] 里登记的条数,
对不上 ⇒ 失败 ⇒ 尺子不会被人悄悄改弱。
🔴 加了断言就得同步契约(docs/contract.md 附录 A 的 [RULER] 那一列),
否则闸门会红(这是故意的:提醒你契约与尺子必须一起改)。
🔴 加业务模块会让 check-module.sh 的条数变多(每模块 20+ 条)⇒
自证那一行会直接告诉你实际条数,照着改契约 [RULER] check-module.sh 即可。
(check-contract.sh 的条数是固定的 10 —— 端点多少条都由契约自己决定,不影响它;
check-citations.sh 的条数是固定的 4 —— 引文多少条都是逐条核对,不影响它。)
六、写之前的自查(5 条)
- 列名全
f_前缀?f_id是VARCHAR(50)不是VARCHAR(32)? json_key= 列名去f_后 camelCase?(f_creator_user_id⇒creatorUserId)- numeric 列标了
numeric: true?numeric_columns数组同步更新? module_key==menu.url_address==App.tsx的 Route path?(三处一字不差)- 改了
schema.sql之后清空data/重建了吗?(schema 只在首次建表时执行)
七、常见坑速查
| 症状 | 根因 | 处理 |
|---|---|---|
| 端点 404 | 忘了在 modules/<app>.rs 里写 router() / 忘了在 modules/mod.rs 里 merge |
补 router() + 补 merge 行 |
| 端点 500 | 表不存在 / spec 没进 ALL_SPECS |
补 schema.sql + 补 ALL_SPECS |
| 启动即退(白名单自检失败) | 新表没进 db/schema.sql(或 spec 拼错表名) |
补 DDL / 改 spec 表名(crates/sspf-admin/src/main.rs 不用改) |
| 页面 404 | App.tsx 的 Route path ≠ 菜单 url_address |
三处对齐 |
| 侧栏没有这个菜单 | modules/<app>.rs 没声明 *_MENU / 没进 ALL_MENUS / 没重启回灌 |
补声明 + 补 ALL_MENUS + 重启进程(不必删库) |
check-boundary.sh 报业务标识符泄漏 |
业务知识写进了平台层(表名 / 菜单 key / 路由前缀) | 挪回业务层;平台层只留类型(EntitySpec / MenuSpec) |
| 非管理员也能看 | module_key 是 None |
改成 Some("app/Entity") |
| 非管理员看不到也访问不了(预期) | 没授权 | 写 base_authorize 或调授权接口 |
金额变成 9.9 |
numeric 列没标 numeric: true |
spec 标上 + numeric_columns 同步 |
| 改了 schema 不生效 | schema 只在首次建表执行 | 清空 data/ 重建 |
check-module.sh 退出码 2 |
契约 [MODULE] 里没加这个 appCode/Entity |
在 docs/contract.md 附录 A 加一行(别改脚本) |
check-contract.sh 报「代码里的 xxx 没被契约登记」 |
契约附录 A 的 [ENDPOINT] 漏了这个模块的 3 条端点 |
补 [ENDPOINT] 三行(face=A / guard = module_key / owner = 模块代号) |
check-contract.sh 报「守卫漂移」 |
契约写的 guard 与代码里的守卫不一致(多半是 module_key 改了) |
两边对齐(要么改 spec.module_key,要么改契约那一行) |
check-contract.sh 报 ⚠️「推不出守卫」 |
代码里守卫的写法变了,扫描器静态推不出来 | 人工核对;确实是新写法 ⇒ 同步改扫描器(check-contract-scan.py 的 guard_of_platform) |
check-contract.sh 报「契约登记了、代码里没有」 |
router() 里用了 ROUTES[0] 而不是字面量路径(扫描器静态解析,认不出数组下标) |
把 router() 的三条 .route("…") 写成字面量(ROUTES 常量仍保留给钉子测试) |
POST …/Save 返 code=400,日志 column "f_xxx_time" is of type timestamp but expression is of type text |
业务表自带的时间列没有 ::timestamp 转换 |
不用改:f_*_time 后缀已被平台层 write_cast 统一识别;其它类型(numeric/integer)才需要逐列登记 |
| 闸门报「尺子被改弱了」 | 加/删了断言但没同步契约 [RULER] |
同步契约里那一列(这是故意的提醒) |
| 建了重复账号 | 官方 f_account 无 UNIQUE |
唯一性应用层保证(只比 delete_mark=0 的行) |