Files
ssw-jnpf-lite-rust/HOWTO_MODULE.md
T
adminandClaude 7c4ae39664 refactor(skill): 仓根即技能本体 —— 技能资产进版本控制 + 三处软链指向同一仓
影响:此前技能资产(SKILL.md / HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md /
JNPF_SOURCE_AUDIT.md / JNPF_COMPAT_SURFACE.md / references/ / template-boot-jnpf/)
实体住在 ~/.agents/skills/ssw-jnpf-lite-rust/(仓外、不在 git)⇒ 改仓不生效、实体与仓漂移。
现在仓根 = 技能根(对齐 ssw-jnpf-lite-react 的形态),~/.agents · ~/.claude · ~/.workbuddy
(+ ~/.qwenworkcn)四处软链全部解析到同一个仓 ⇒ 改一次仓 = 改一次技能。

改动:
- 新增根级技能文档 6 份:SKILL.md(并补 frontmatter:name/description/type,原文件没有 frontmatter
  只靠目录名兜底)/ HOWTO_MODULE.md / PERMISSION.md / MIGRATION.md / JNPF_SOURCE_AUDIT.md /
  JNPF_COMPAT_SURFACE.md;references/ 与 template-boot-jnpf/ 一并入仓
- 根 README.md 改为技能版(选型/运行/验收门/已知限制),旧项目版 README 移入 docs/README-project.md
- docs/ 下 3 份与根级同源的文档删除(技能版取代),全仓链接改指根级(已修全部相对链接,无坏链)
- docs/ 保留契约真源 contract.md / runbook.md / decisions.md / known-limitations.md / ddl/
- Cargo.toml 取「技能版注释 + 仓版补充」合并;run.sh 用仓版(多旧名兜底 pkill)
- SKILL.md 补 frontmatter + 「技能目录 = 仓根」说明;CLAUDE.md 目录速览同步;HANDOFF.md 技能资产
  描述同步;工作日志补第三段

验证:cargo build --release 0 error · cargo test 195 passed/0 failed · check-module.sh PASS=57
FAIL=0 · 面 A 尺子 PASS=32 FAIL=0 · 面 B 尺子 PASS=18 FAIL=0 SKIP=0(覆盖 18/18)

Co-Authored-By: Claude <[email protected]>
2026-10-26 16:56:58 +08:00

14 KiB
Raw Blame History

加一个业务模块(AI 开发主线)

本文件是 Rust 版的操作手册。参照实现 = 内置的三个模块 (demo/DemoItem · shop/Product · books/Book)——照抄一个最接近的,别从零想。

契约红线见 SKILL.md §「契约红线」。本文件只讲「改哪儿、怎么验证」。

〇.5、一图看完全流程(先看一遍再动)

  1. db/schema.sql        建表(f_ 前缀 + f_id VARCHAR(50) + 软删列)
  2. src/entities.rs      加 spec(列清单 + json_key + numeric 标记 + module_key)
  3. src/crud.rs          加 3 个 handler(List/Save/Delete)—— 复用 handle_list/handle_save/handle_delete
  4. src/routes.rs        注册 3 条路径
  5. src/seed.rs          加内置菜单(id + url_address = Route path)
  6. frontend/src/api/<lc>.ts      3 个函数(list/save/delete)
  7. frontend/src/views/<Ent>.tsx  列表页
  8. frontend/src/App.tsx          <Route path="/<route>">
  9. scripts/check-module.sh      期望表加一行(appCode:Entity)
     ⇒ bash scripts/check-module.sh <appCode> <Entity>   必须全 ✅
    10. scripts/perm-smoke.sh      追加该模块的断言(别新写脚本)

9 个接触点 = 上面的 1–9。第 9 步漏了 ⇒ check-module.sh 直接判「未知 app_code/Entity」退出 2。

〇、命名约定(先想清楚再动)

位置 约定 例(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/entities.rs 加 EntitySpec(含列清单) 端点 404(没注册)
3 src/backend/src/crud.rs 加 3 个 handler 端点 404
4 src/backend/src/routes.rs 注册 3 条路径 端点 404
5 src/backend/src/seed.rs 加内置菜单 菜单不显示(前端侧栏空)
6 src/frontend/src/api/<lc>.ts 3 个函数 页面发请求 404
7 src/frontend/src/views/<Ent>.tsx 列表页 页面空白
8 src/frontend/src/App.tsx <Route path="/<route>"> 页面 404
9 scripts/check-module.sh 期望表加一行 自检退出码 2(闸门形同虚设)

外加一条一致性(不是第 10 个文件): spec.module_key == seed.url_address == App.tsx 的 Route path —— 三处一字不差。 不一致的后果是静默放行(未映射到菜单就放行,不报错)。

二、后端五处改什么

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/entities.rs —— 加 spec

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 },
];

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 标记一致(有单测钉)
};

再把 SHOE_SPEC 加进 ALL_SPECS(否则 find_spec 找不到)。

🔴 json_key 必须等于 db::column_to_json_key(column)(f_title ⇒ title)—— 有单测钉死,不一致会红。 🔴 列顺序 = 响应 JSON 的键序(照抄参照模块,别自作主张排序)。 🔴 default 只在「路径 1(无 id 的新建)」生效——带 id 但库里没这行时,一个默认值都不加。

2.3 src/crud.rs —— 加 3 个 handler

不要重写业务逻辑——handle_list / handle_save / handle_delete 已经把 守卫、SQL 拼装、投影、软删、序列化全包了:

// ---------------------------------------------------------------- shoes(菜单 shoes/Shoe)

/// `GET /api/ssw/shoes/Shoe/List`。
pub async fn shoe_list(State(state): State<AppState>, headers: HeaderMap) -> Json<ActionResult> {
    let spec = shoe_spec();
    handle_list(&state, &headers, spec).await
}

/// `POST /api/ssw/shoes/Shoe/Save`。
pub async fn shoe_save(
    State(state): State<AppState>,
    headers: HeaderMap,
    body: Bytes,
) -> Json<ActionResult> {
    let spec = shoe_spec();
    handle_save(&state, &headers, 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> {
    let spec = shoe_spec();
    handle_delete(&state, &headers, spec, &raw).await
}

fn shoe_spec() -> &'static EntitySpec {
    &crate::entities::SHOE_SPEC
}

🔴 签名不要改:Save 收 body: Bytes(自己解析,不走 Json<T>), Delete 收 raw: RawQuery(?id=)—— handle_save / handle_delete 依赖这个形状。

2.4 src/routes.rs —— 注册路径

.route("/api/ssw/shoes/Shoe/List",   get(crud::shoe_list))
.route("/api/ssw/shoes/Shoe/Save",   post(crud::shoe_save))
.route("/api/ssw/shoes/Shoe/Delete", delete(crud::shoe_delete))

🔴 axum 0.8 逐条注册(matchit 不支持 {a,b})⇒ 三个动作三条 .route()。 🔴 with_state(state) 必须是链条最后一步。 🔴 路由表有钉子测试(routes.rs 的 route_table_is_pinned,照抄面 A 27 条; 面 B 另有 jnpf_route_table_is_pinned,照抄面 B 5 条)⇒ 加完路径要同步改那张表。 🔴 面 B 已落地(src/backend/src/jnpf.rs):新业务模块若要让官方 JNPF 前端也能用, 需另在面 B 补对应官方形状端点(分页信封 PageListVO + f_en_code 点权限)。

2.5 src/seed.rs —— 加内置菜单

在 BUILTIN_MENUS 常量里加一条:

BuiltinMenu {
    id: "m_shoe",
    full_name: "鞋",
    url_address: "shoes/Shoe",     // 🔴 必须 == Route path == spec.module_key
    parent_id: "0",
    menu_type: "2",                 // 1 = 目录,2 = 页面(官方 f_type 是 INTEGER)
    icon: None,
    sort_code: "…",
},

🔴 种子是「幂等 ensure」:启动时按 f_url_address 或 f_id 判存在 ⇒ 改了 url_address 必须重启回灌;软删行不复活、不覆盖已改值。 🔴 改了种子要重启进程才会回灌存量库,不必删库重建。 🔴 种子 INSERT 不写 f_en_code(官方点权限靠它)⇒ 迁官方前要补(见 MIGRATION.md §2.4)。

三、前端三文件改什么

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' ' ' 去换行再匹配。

四、菜单 + 授权

  • 菜单:seed.rs 加一条(见 2.5)。前端侧栏由后端返回的菜单树驱动 ⇒ 不用改前端导航。
  • 授权:默认不授权 ⇒ 非管理员看不到、访问 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 角色:seed.rs 的 ensure_admin_authorizations 会自动补内置菜单的授权 ⇒ 管理员开箱即用,普通角色要手动授权。

五、验证(追加断言,别新写脚本)

5.1 静态自检(改完立刻跑,先于 perm-smoke)

bash scripts/check-module.sh shoes Shoe     # 单模块
bash scripts/check-module.sh                # 全部三个 + 全局红线

🔴 先改 scripts/check-module.sh 的期望表(§一 第 9 步)—— case "${A}:${E}" 分支里补 shoes:Shoe 的表名 / ROUTE / 种子 id / module_key / 有无 api 文件。

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):

# 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                        # 195 条
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 忘了 routes.rs 注册 补 3 条 .route() + 同步改 route_table_is_pinned 钉子表
端点 500 表不存在 / spec 没进 ALL_SPECS 补 schema.sql + 补 ALL_SPECS
页面 404 App.tsx 的 Route path ≠ 菜单 url_address 三处对齐
侧栏没有这个菜单 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 的行)