# 加一个业务模块(AI 开发主线) 本文件是 **Rust 版**的操作手册。参照实现 = 内置的三个模块 (`demo/DemoItem` · `shop/Product` · `books/Book`)——**照抄一个最接近的,别从零想**。 > 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。** ## 〇.5、一图看完全流程(先看一遍再动) ``` 1. db/schema.sql 建表(f_ 前缀 + f_id VARCHAR(50) + 软删列) 2. src/modules/.rs 【新文件】spec + 3 个 handler + 自己的 router() 3. src/modules/mod.rs 加 spec 进 ALL_SPECS + 加 router() 进 merge + 加路由进 ALL_ROUTES 4. src/platform/seed.rs 加内置菜单(id + url_address = Route path) 5. frontend/src/api/.ts 3 个函数(list/save/delete) 6. frontend/src/views/.tsx 列表页 7. frontend/src/App.tsx 8. scripts/check-module.sh 期望表加一行(appCode:Entity) ⇒ bash scripts/check-module.sh 必须全 ✅ 9. scripts/perm-smoke.sh 追加该模块的断言(别新写脚本) ``` **9 个接触点 = 上面的 1–9**。第 8 步漏了 ⇒ `check-module.sh` 直接判「未知 app_code/Entity」退出 2。 🔴 **平台层(`src/platform/`)一个字都不用改** —— 加业务模块**不碰平台层**。 (对比 react 版要动 4 个后端文件;本仓**只动 `src/modules/` 下的 2 个文件** + `db/schema.sql` + `platform/seed.rs` 的菜单一条。) ## 〇、命名约定(先想清楚再动) | 位置 | 约定 | 例(`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` 就是这么定的。 ## 一、要碰的 9 个接触点 | # | 文件 | 改什么 | 漏了会怎样 | |---|---|---|---| | 1 | `src/backend/db/schema.sql` | `CREATE TABLE {table}` | 端点 500(表不存在) | | 2 | `src/backend/src/modules/.rs` | **新文件**:spec + 3 个 handler + `router()` | 端点 404(没注册) | | 3 | `src/backend/src/modules/mod.rs` | `ALL_SPECS` 加一条 + `router()` merge 一行 + `ALL_ROUTES` 加 3 条 | 启动自检失败 / 端点 404 | | 4 | `src/backend/src/platform/seed.rs` | 加内置菜单 | **菜单不显示**(前端侧栏空) | | 5 | `src/frontend/src/api/.ts` | 3 个函数 | 页面发请求 404 | | 6 | `src/frontend/src/views/.tsx` | 列表页 | 页面空白 | | 7 | `src/frontend/src/App.tsx` | `` | **页面 404** | | 8 | `scripts/check-module.sh` | 期望表加一行 | 自检退出码 2(闸门形同虚设) | | 9 | `scripts/perm-smoke.sh` | 追加该模块的断言 | 新模块无端到端覆盖 | **外加一条一致性(不是第 10 个文件)**: `spec.module_key` == `seed.url_address` == `App.tsx` 的 Route path —— **三处一字不差**。 不一致的后果是**静默放行**(未映射到菜单就放行,不报错)。 🔴 **分层铁律**:后端代码分两层—— | 层 | 目录 | 内容 | 加模块时 | |---|---|---|---| | **平台层** | `src/backend/src/platform/` | 契约实现(信封 / cipher / 登录 / 权限 / `base_*` 管理 / 面 B / CRUD 引擎) | **一个字都不改** | | **业务层** | `src/backend/src/modules/` | 业务 spec + handler + 路由 | **只改这里** | (对齐 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/.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, headers: HeaderMap) -> Json { handle_list(&state, &headers, &SHOE_SPEC).await } /// `POST /api/ssw/shoes/Shoe/Save`。 pub async fn shoe_save( State(state): State, headers: HeaderMap, body: Bytes, ) -> Json { handle_save(&state, &headers, &SHOE_SPEC, &body).await } /// `DELETE /api/ssw/shoes/Shoe/Delete?id=`。 pub async fn shoe_delete( State(state): State, headers: HeaderMap, raw: RawQuery, ) -> Json { handle_delete(&state, &headers, &SHOE_SPEC, &raw).await } /// 本模块的路由(`Router::merge` 进总路由,**对齐 NestJS 的 module 注册**)。 pub fn router() -> Router { 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`), `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 { demo::router() .merge(shop::router()) .merge(books::router()) .merge(shoes::router()) // 🔴 加这一行 } ``` 🔴 **`ALL_SPECS` 漏了** ⇒ 启动时的标识符白名单自检会失败(`spec 表名 … 不在本仓的 10 张表清单里`)—— 记得同时把新表名加进 `src/backend/src/main.rs` 的 `EXPECTED_TABLES`。 🔴 **`router()` 漏了 merge** ⇒ 端点 404。 🔴 **`ALL_ROUTES` 漏了** ⇒ 路由表钉子测试**不会报错**(它只遍历这张表)⇒ 静默失去覆盖 ⇒ 一定要加。 ### 2.4 `src/platform/seed.rs` —— 加内置菜单 在 `BUILTIN_MENUS` 常量里加一条: ```rust BuiltinMenu { 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, }, ``` 🔴 **种子是「幂等 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)。 ## 三、前端三文件改什么 ### 3.1 `src/api/.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/.tsx` —— 列表页 照抄 `views/Book.tsx`(含 numeric 往返、删除确认、错误提示)。 🔴 **金额展示别用 `Number()` 转**——后端给的是字符串 `"9.90"`,转数字会丢尾零。 ### 3.3 `src/App.tsx` —— 注册路由 ```tsx import Shoe from './views/Shoe'; … } /> ``` 🔴 **Route path 必须 == 菜单 `url_address`**(去前导斜杠)—— 不一致 ⇒ 侧栏点了 404。 🔴 JSX 常写成多行(``)⇒ `check-module.sh` 用 `tr '\n' ' '` 去换行再匹配。 ## 四、菜单 + 授权 - **菜单**:`platform/seed.rs` 加一条(见 2.4)。前端侧栏由**后端返回的菜单树**驱动 ⇒ 不用改前端导航。 - **授权**:**默认不授权 ⇒ 非管理员看不到、访问 403**(这是对的)。 要让某个角色看到 ⇒ 写 `base_authorize` (`f_object_type='role'` + `f_object_id=` + `f_item_type='module'` + `f_item_id=`)。 走 `PUT /api/permission/Authority/Data/{objectId}`(`objectType` **小写** `'role'`, `module` 传**一维数组**)。 - **admin 角色**:`platform/seed.rs` 的 `ensure_admin_authorizations` 会**自动**补内置菜单的授权 ⇒ 管理员开箱即用,普通角色要手动授权。 ## 五、验证(追加断言,别新写脚本) ### 5.1 静态自检(改完立刻跑,**先于** perm-smoke) ```bash bash scripts/check-module.sh shoes Shoe # 单模块 bash scripts/check-module.sh # 全部三个 + 全局红线 ``` 🔴 **先改 `scripts/check-module.sh` 的期望表**(§一 第 8 步)—— `case "${A}:${E}"` 分支里补 `shoes:Shoe` 的表名 / ROUTE / 种子 id / module_key / 有无 api 文件 / **模块文件名**(`T_FILE`)。 ### 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 # 197 条 bash scripts/check-module.sh # 静态自检 bash scripts/perm-smoke.sh # 面 A 32 条 bash scripts/perm-smoke-jnpf.sh # 面 B 18 条(面 A 不受影响时也应保持 18/18) ``` ## 六、写之前的自查(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` == `seed.url_address` == `App.tsx` 的 Route path?**(三处一字不差) 5. **改了 `schema.sql` 之后清空 `data/` 重建了吗?**(schema 只在首次建表时执行) ## 七、常见坑速查 | 症状 | 根因 | 处理 | |---|---|---| | 端点 404 | 忘了在 `modules/.rs` 里写 `router()` / 忘了在 `modules/mod.rs` 里 merge | 补 `router()` + 补 merge 行 | | 端点 500 | 表不存在 / spec 没进 `ALL_SPECS` | 补 `schema.sql` + 补 `ALL_SPECS` + 补 `EXPECTED_TABLES` | | 启动即退(白名单自检失败) | 新表名没进 `main.rs` 的 `EXPECTED_TABLES` | 加表名 | | 页面 404 | `App.tsx` 的 Route path ≠ 菜单 `url_address` | 三处对齐 | | 侧栏没有这个菜单 | `platform/seed.rs` 没加 / 没重启回灌 | 加种子 + **重启进程**(不必删库) | | 非管理员也能看 | `module_key` 是 `None` | 改成 `Some("app/Entity")` | | 非管理员看不到也访问不了(预期) | 没授权 | 写 `base_authorize` 或调授权接口 | | 金额变成 `9.9` | numeric 列没标 `numeric: true` | spec 标上 + `numeric_columns` 同步 | | 改了 schema 不生效 | schema 只在首次建表执行 | 清空 `data/` 重建 | | `check-module.sh` 退出码 2 | 期望表没加这个 appCode/Entity | 改 `scripts/check-module.sh` 的 `case` | | 建了重复账号 | 官方 `f_account` **无 UNIQUE** | 唯一性**应用层**保证(只比 `delete_mark=0` 的行) |