Files
ssw-jnpf-lite-rust/HOWTO_MODULE.md
T
adminandClaude Code ab8833af28 refactor(backend): 平台层 / 业务层分离 —— 加业务模块只碰 modules/
后端从平铺(src/{config,db,cipher,…,entities}.rs)改两层,对齐 react 版的
common+auth+sys / demo+shop+books 与官方 JNPF 的 jnpf-common+jnpf-system / jnpf-admin。

- 平台层 src/platform/:契约实现(config·db·cipher·envelope·ids·session·state·
  auth·permission·seed·sys·jnpf·entity·crud)—— 加业务模块不动
- 业务层 src/modules/:mod.rs + demo/shop/books,各自带 spec + 3 条路由 + 自己的 router()
- routes.rs 变成「平台路由 + 一次 merge(modules::router())」,业务路由不再登记在平台层
- 业务路由清单也搬到业务层(modules::ALL_ROUTES),平台层钉子测试遍历它
  ⇒ 原来「每加一模块要改 routes.rs 路由表」的口子被堵死
- 清掉平台层最后一个业务知识泄漏:S22 的 f_creator_user_id 规则原在引擎里写死
  app_code == "demo",改为业务 spec 自己声明(EntitySpec.creator_fixed)
- check-module.sh 新增反向断言(平台层不得注册业务路由)+ 正向断言(业务层须登记)
  ⇒ 断言 57 → 69
- 文档同步(SKILL/CLAUDE/README/HANDOFF/PERMISSION/MIGRATION/HOWTO_MODULE/contract),
  新增红线「平台层不许出现业务表名 / app_code」;decisions.md 补 P81

验证:cargo build --release 0 error 0 warning · cargo test 197 passed / 0 failed ·
check-module.sh PASS=69 FAIL=0 · 面 A PASS=32 FAIL=0 · 面 B PASS=18 FAIL=0 SKIP=0

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 17:26:21 +08:00

362 lines
17 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 开发主线)
本文件是 **Rust 版**的操作手册。参照实现 = 内置的三个模块
(`demo/DemoItem` · `shop/Product` · `books/Book`)——**照抄一个最接近的,别从零想**。
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。**
## 〇.5、一图看完全流程(先看一遍再动)
```
1. db/schema.sql 建表(f_ 前缀 + f_id VARCHAR(50) + 软删列)
2. src/modules/<app>.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/<lc>.ts 3 个函数(list/save/delete)
6. frontend/src/views/<Ent>.tsx 列表页
7. frontend/src/App.tsx <Route path="/<route>">
8. scripts/check-module.sh 期望表加一行(appCode:Entity)
⇒ bash scripts/check-module.sh <appCode> <Entity> 必须全 ✅
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/<app>.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/<lc>.ts` | 3 个函数 | 页面发请求 404 |
| 6 | `src/frontend/src/views/<Ent>.tsx` | 列表页 | 页面空白 |
| 7 | `src/frontend/src/App.tsx` | `<Route path="/<route>">` | **页面 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/<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 表名 … 不在本仓的 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/<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' ' '` 去换行再匹配。
## 四、菜单 + 授权
- **菜单**:`platform/seed.rs` 加一条(见 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.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/<app>.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` 的行) |