HANDOFF 记下加模块的真实成本(一条命令 + 一张产出表)、2 个真 bug、反自证结果; HOWTO_MODULE 开头两节重写(旧手抄清单已过时);CLAUDE 两条核心不变量改写。
450 lines
24 KiB
Markdown
450 lines
24 KiB
Markdown
# 加一个业务模块(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 # ≈17s 全绿才继续
|
||
> ```
|
||
>
|
||
> 它建 `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 必须全 ✅
|
||
```
|
||
|
||
🔴 **漏了会怎样**(这就是为什么不再让人手抄):
|
||
|
||
| 漏哪一步 | 现象 | 报错吗 |
|
||
|---|---|---|
|
||
| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** |
|
||
| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** |
|
||
| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** |
|
||
| 8(Cargo 依赖) | 编译失败 | ✅ 报 |
|
||
| 9(契约) | `check-contract` 红 | ✅ 报 |
|
||
|
||
🔴 **平台层(`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` 的行) |
|