Files
ssw-platform/HOWTO_MODULE.md
T
admin 21c69ee85d docs: 同步批次 12.6 收尾(HANDOFF + HOWTO + CLAUDE + memory)
记下:两档验证的分工(--fast 该接的接上了 / --lib 接上的活真能应答)、

两处反自证结果、以及「不同步 Save/Delete」「不在 new-pack.sh 里跑」两条边界。
2026-11-01 23:13:42 +08:00

457 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 加一个业务模块(AI 开发主线)
> 🔴 **2026-11-01 起:一条命令。** 本文后半部分的「改哪个文件」清单写于批次 12 之前,
> **已过时**(`db/schema.sql` 不用改、`modules/mod.rs` 不用改、契约不用手抄)。
> 以本节为准:
>
> ```bash
> 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` 里的包冒烟(`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`](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/`)与入口文件(`src/backend/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` | 追加该模块的断言 | 新模块无端到端覆盖 |
**外加两条一致性**:
1. `spec.module_key` == `menu.url_address` == `App.tsx` 的 Route path —— **三处一字不差**。
不一致的后果是**静默放行**(未映射到菜单就放行,不报错)。
2. 🔴 **入口文件也不碰**:`main.rs` 的 `BASE_TABLES` 只列 8 张 `base_*`(8 张全部逐字对齐官方 DDL,含多应用注册表 `base_system`),
业务表由 `modules::all_specs()` 派生并与 `db/schema.sql` 双向对账
⇒ 加业务表**不用**改 `main.rs`。
🔴 **分层铁律**:后端代码分两层——
| 层 | 目录 | 内容 | 加模块时 |
|---|---|---|---|
| **平台层** | `src/backend/src/platform/` | 契约实现(信封 / cipher / 登录 / 权限 / `base_*` 管理 / 面 B / CRUD 引擎) | **一个字都不改** |
| **业务层** | `src/backend/src/modules/` | 业务 spec + **业务菜单** + handler + 路由 | **只改这里** |
| **装配根** | `src/backend/src/bootstrap.rs` | 唯一同时认识两层的地方 | **一个字都不改** |
(对齐 react 版的 `common`+`auth`+`sys` / `demo`+`shop`+`books`,
以及官方 JNPF 的 `jnpf-common`+`jnpf-system` / `jnpf-admin`。)
## 二、后端四处改什么
### 2.1 `db/schema.sql` —— 建表
照抄 `book_shop_book` 的形状:
```sql
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`**(最接近的参照实现)。一个文件三块:
```rust
//! 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 crate::platform::crud::{handle_delete, handle_list, handle_save};
use crate::platform::entity::{ColumnSpec, EntitySpec};
use crate::platform::envelope::ActionResult;
use crate::platform::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 处)
```rust
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`(**`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` 同级):
```rust
use crate::platform::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 个函数
```ts
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` —— 注册路由
```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
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 条**(每个业务模块都有):
1. `GET /api/ssw/{app}/{Ent}/List` 无 token ⇒ `code=600`
2. 无 token ⇒ `code=600`(同上一条,测的是**端点在、守卫在**)
3. 非管理员未授权 ⇒ `code=403`
4. 管理员新建一条 ⇒ `code=200` + 回读列表里能看到(长度 +1)
**每个业务字段加一条往返断言**(防 numeric/text/int 转换 bug):
```bash
# 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 六道闸门全绿才算完
```bash
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 条)
1. **列名全 `f_` 前缀?** `f_id` 是 `VARCHAR(50)` 不是 `VARCHAR(32)`?
2. **`json_key` = 列名去 `f_` 后 camelCase?**(`f_creator_user_id` ⇒ `creatorUserId`)
3. **numeric 列标了 `numeric: true`?** `numeric_columns` 数组同步更新?
4. **`module_key` == `menu.url_address` == `App.tsx` 的 Route path?**(三处一字不差)
5. **改了 `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 表名(`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` 的行) |