Files
ssw-jnpf-lite-rust/CLAUDE.md
T
adminandClaude 0aed12a102 docs: 契约规格 + 实施计划 + 官方 base_* DDL 原文
- docs/contract.md: 唯一规格来源(信封/cipher/端点/权限/种子/验收门)
- docs/ddl/base_ddl_raw.sql: 从官方 JNPF dump 逐字提取的 7 张 base_* DDL
- CLAUDE.md / HANDOFF.md: 项目级 agent 指引与交接文档

Co-Authored-By: Claude <[email protected]>
2026-10-25 17:05:00 +08:00

18 KiB
Raw Blame History

AGENTS.md

本文件是 tds-lite-rs 的项目级 agent 指引。内容必须与代码同步;改代码后回头核对本文件是否还成立。

详细设计、决策记录、实施顺序、验收门 ⇒ 见 HANDOFF.md。

项目定位

tds-lite-rs = JNPF 兼容契约的 Rust 实现(单二进制、零外部服务)。

它的存在意义只有一条:让"用 Rust 写业务"和"迁回官方 JNPF(Java)"之间是机械翻译,而不是重写。 为此本仓的数据模型(表名/列名/语义)与 HTTP 契约从第一天就锁死成官方 JNPF 的形状。

命名沿用用户指定的 tds-lite-rs(与 ssw-jnpf-lite / ssw-jnpf-lite-react 同族的轻量垫片), 不要把它理解成 tdc-rs 那个「数据接入连接器」——两者无继承关系。

三个参照物(各司其职,别混)

参照物 路径 地位
官方 JNPF 源码 + DDL ~/Desktop/workspace/jnpf/ 数据模型真源:base_* 表名/列名/陷阱以官方 DDL 为准
ssw-jnpf-lite-react 技能 ~/Desktop/workspace/skills/ssw-jnpf-lite-react/ 行为真源:NestJS 版把契约"跑起来了",本仓逐条对齐它
tdc-rs 兄弟项目 ~/Desktop/workspace/tdc-rs/ 只抄工程手法(pglite 单实例、row_to_json 投影、axum 0.8 坑位)。不共享代码、不共享端口、不共享数据目录

🔴 tdc-rs 与本仓无依赖关系。别 import 它的代码、别改它、别把两边的数据目录指到同一处。 它已经占了 :30000,本仓后端默认 :30010。

交付形态

v1 = 全量契约对齐:登录 / CurrentUser / 5 组 base_* 管理 CRUD / 统一授权 / 四源权限合并 / 两段式种子 / 3 个业务模块(demo · shop · books)/ 权限闭环冒烟。 先做真实项目,跑通验收门之后再抽成技能(技能资产形态 = 本仓 1:1 复制)。

技术栈

层 选型 说明
后端 Rust 2021 + axum 0.8 + tokio 单二进制
数据库 pglite-rs 0.2(进程内原生 PostgreSQL) 零服务/零 Docker/零 WASM;数据落盘 src/backend/data/lite.pg
前端 react 技能的前端产物,逐字复用(React + Vite) 零改前端;vite 代理 /api → 后端
密码学 aes 0.8 + ecb 0.1 + md-5 0.10 与 react 技能 cipher.ts 逐字节等价
其它 serde / serde_json / serde_urlencoded 0.7 / uuid v4 / rand 0.8

🔴 pglite-rs ≠ 浏览器 PGlite。crate 名 pglite-rs、import 名 pglite; 它把 postgres-pglite 编译成原生静态库链进二进制 ⇒ 真实 PostgreSQL 语义(类型/MVCC/事务/扩展/线协议), 进程内单 backend。不是 @electric-sql/pglite(那是 WASM + IndexedDB,本仓禁止引入)。

目录速览(目标形态)

tds-lite-rs/
├── Cargo.toml               # 【workspace 根】members = ["src/backend"];release profile 写在这里
├── CLAUDE.md / HANDOFF.md   # 本文件 / 交接文档
├── src/
│   ├── backend/             # Rust 后端(workspace 唯一成员,crate 名 tds-lite-rs)
│   │   ├── Cargo.toml
│   │   ├── src/
│   │   │   ├── main.rs      # 启动装配
│   │   │   ├── config.rs    # 环境变量
│   │   │   ├── db.rs        # pglite 封装 + schema 初始化
│   │   │   ├── cipher.rs    # md5 + AES-256-ECB(对齐 cipher.ts)
│   │   │   ├── envelope.rs  # ActionResult{code,msg,data}
│   │   │   ├── ids.rs       # 36 位 UUID v4
│   │   │   ├── session.rs   # 内存 token 表
│   │   │   ├── auth.rs      # 登录 / CurrentUser / 鉴权守卫
│   │   │   ├── permission.rs# 四源合并 + 管理员短路 + 菜单树
│   │   │   ├── seed.rs      # ensureBase + firstSeed
│   │   │   ├── sys.rs       # 5 组 base_* 显式 handler
│   │   │   ├── crud.rs      # 业务实体 spec 驱动 CRUD 引擎
│   │   │   ├── entities.rs  # 业务实体 spec 表
│   │   │   └── routes.rs    # 路由装配
│   │   ├── db/schema.sql    # 完整 DDL(base_* 7 张 + 3 业务表)
│   │   └── data/            # 运行期数据(gitignore)
│   └── frontend/            # react 技能前端逐字复制(不改)
├── scripts/
│   ├── perm-smoke.sh        # 权限闭环冒烟(22+ 断言)
│   └── check-module.sh      # 业务模块 9 接触点静态自检
├── run.sh                   # install / build / dev / stop / logs
└── .env.example

架构红线

  1. 🔴 契约优先于实现。 任何端点的路径、入参、返回形状、错误码,必须与 ssw-jnpf-lite-react 逐字一致。不确定时先读 react 技能源码,别凭印象。
  2. 🔴 业务失败一律 HTTP 200 + {code,msg,data}。 成败只看 body 的 code。 例外只有一个:未知路由保留 HTTP 404(body 仍是 ActionResult 形状)。 🔴 鉴权失败也是 HTTP 200(code=600 未登录 / code=403 无菜单权限)—— 与 tdc-rs 的 401/403 裸 body 相反,别把 tdc-rs 的形状抄过来。
  3. 🔴 base_* 表名与列名逐字对齐官方 DDL(含两个官方陷阱,见下)。 不允许自创表名/列名——迁移期靠 --data-only 导数据,列名差一个字符就导不进去。
  4. 🔴 四源权限合并 + 管理员短路 + 未映射放行。
    • 管理员(f_is_administrator=1)在任何 SQL 之前短路放行;
    • 权限 = 用户直授 + 角色 + 组织 + 岗位,只查角色会漏授权;
    • 菜单未映射到 base_module ⇒ 放行(对齐 SswPermissionGuard 的 warn 路径), 不是拒绝。这条最容易写反,且静默(不报错),所以必须有测试钉住。
  5. 🔴 口令不得外泄。 库内存 md5(明文);对外响应手工挑字段(用户列表要去掉 password)。 密文只在请求体里出现,永不回显。
  6. 🔴 前端不直接持有数据库。 一切访问经 /api/**。
  7. 🔴 schema DDL 绝不可从 HTTP 下载。 db/schema.sql 不在 web root, 且要有兜底守卫(/api/** 之外的静态托管只放前端产物)。
  8. 🔴 同一文件的多个 Edit 必须串行(并行 Edit = last-writer-wins 静默覆盖)。 改完必须 grep 复核全部改动点。

官方 DDL 的两个"故意不修正"的陷阱

陷阱 事实 后果
base_role_relation 用户 id 存在 f_object_id(配 f_object_type='user'),没有 f_user_id 写错列 ⇒ 角色授权永远不生效
base_user_relation 组织/岗位关系在另一张表,那里才有 f_user_id 写错表 ⇒ 组织/岗位授权永远不生效

另:base_module.f_type 是 INTEGER(1-目录 2-页面),f_category 是 VARCHAR(分类)—— 早期 MVP 曾写反,本仓以官方 DDL 为准。

关键实现细节(改代码前必读)

  1. cipher 的 key 是"hex 串当 ASCII 用": md5_hex("EY8WePvjM5GGwQzn") 得到 32 个 hex 字符 ⇒ 把这 32 个 ASCII 字节当 key ⇒ AES-256(不是 AES-128)。src 同理 = md5_hex(明文) 的 32 个 ASCII 字节。 输出 hex。上游检验向量:encryptPassword('123456') == d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b。 tdc-rs/src/cipher.rs 有逐字对齐的 Rust 实现可读作参考(但不共享代码)。
  2. 口令比对:base_user.f_password 存 md5(明文) 的小写 hex; 登录时 decrypt(密文) 得到 md5(明文) ⇒ 大小写不敏感比较。
  3. numeric 列必须序列化成 JSON 字符串("9.90",不是 9.9)。 手段:在 SQL 投影里就 cast 成 text(f_price::text AS price)—— row_to_json 直接给数字会被 serde_json 变成 f64 再输出 9.9 ⇒ 契约破。 int 列(f_delete_mark / f_stock / f_is_administrator)保持数字。
  4. 主键是 36 位 UUID v4(带连字符),列 varchar(50) 装得下。不是 tdc-rs 的雪花十进制。
  5. JSON 键名 = 列名去 f_ 前缀后 camelCase:f_id→id、f_real_name→realName、 f_url_address→urlAddress、f_is_administrator→isAdministrator、f_delete_mark→deleteMark、 f_creator_time→creatorTime。请求体去前缀名(title 不是 fTitle)。
  6. pglite 单 backend 串行化:所有 DB 访问必须持进程级 db_lock (OnceLock<Arc<tokio::Mutex<()>>>)。同时一个数据目录只能被一个进程打开 ⇒ 集成测试要么串行、要么各自用独立数据目录。
  7. 查询结果序列化:沿用 tdc-rs 的手法 SELECT row_to_json(q)::text AS _row FROM (<sql>) q ⇒ 取单列文本 ⇒ serde_json::from_str。 不要另起逐列类型映射分支。
  8. 标识符白名单:任何拼进 SQL 的表名/列名都要过白名单 ([A-Za-z][A-Za-z0-9_]*),并在启动时自检全部拼接点,不过白名单 ⇒ 秒退。
  9. include_str! 路径相对 src/db.rs:写 ../db/schema.sql。
  10. axum 0.8 语义:Router<S> 的 S 是"还缺什么状态" ⇒ with_state 必须是链条最后一步。
  11. Form<T> 在 axum 0.8.9 只实现 FromRequest(没有 OptionalFromRequest) ⇒ Option<Form<T>> 编译不过 ⇒ 需要"解析失败也走业务信封"的表单端点, 取原始 body 自己用 serde_urlencoded::from_bytes 解析。 (/api/oauth/Login 正是这种端点,且 grant_type 不能加 camelCase。)
  12. 405 的 JSON 兜底用响应改写中间件(挂在链尾),不要用 axum 的 method_not_allowed_fallback(后者只对调用那一刻已注册的路由生效,且丢 Allow 头)。
  13. schema 初始化:启动时探测 base_user 是否存在,不存在才按 ; 拆分执行 schema.sql (拆分要字面量感知,别把字符串里的 ; 当语句边界)。
  14. 路径与 cwd 解耦:resolve_project_dir() 从可执行文件向上找锚点文件, static/ 与 data/ 都基于它 —— 后台启动时 cwd 会漂移,改成相对 cwd ⇒ 500。
  15. 未知路由 = HTTP 404(body 仍是 {code:404,msg:'接口不存在',data:null})。 不要用"全局 404 兜底"把它变成 200。

数据模型

src/backend/db/schema.sql —— 10 张表。

base_* 7 张(官方 DDL 逐字,复合主键 (f_id, f_tenant_id),单租户固定 '0')

表 官方 DDL 行号 用途
base_authorize 812 授权(f_object_type/f_object_id/f_item_type/f_item_id)
base_module 2209 菜单(f_url_address = 前端 Route path 去前导斜杠)
base_organize 3178 机构(f_parent_id 树)
base_role 3686 角色(f_en_code 唯一性应用层保证)
base_role_relation 3729 用户↔角色(⚠️ 用户 id 在 f_object_id)
base_user 4479 用户(f_password=md5,f_is_administrator,f_account 无 UNIQUE)
base_user_relation 4707 用户↔组织/岗位(⚠️ 这里才有 f_user_id)

行号出处:~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql (同目录还有 jnpf_db_init.sql 等 9 个 init 文件,只读)。

业务表 3 张(与 react 技能同名 ⇒ 两版后端可开同一个库)

表 实体 列
demo_item DemoItem f_id / f_title / f_status / f_creator_user_id / f_creator_time / f_delete_mark
shop_product Product f_id / f_title / f_price numeric(12,2) / f_creator_user_id / f_creator_time / f_delete_mark
book_shop_book Book f_id / f_title / f_author / f_isbn / f_category / f_price numeric(12,2) / f_stock int / f_creator_user_id / f_creator_time / f_delete_mark

🔴 只有 base_* 的表名/列名是契约;业务表名只是为了数据模型可移植(两版后端能开同一个库)才故意对齐。

端点全表

方法 路径 守卫 说明
POST /api/oauth/Login 无 form-urlencoded:account / password(密文 hex) / grant_type=password;成功返回 {token, expiresIn:7200, tokenTypeName:'bearer'}
GET /api/oauth/CurrentUser 登录 {userInfo:{userId,userAccount,userName,isAdministrator}, menuList};未登录 code=600
GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=} 登录 + 菜单 system/User 列表去掉 password,附 roleIds/roleNames
GET/POST/DELETE /api/ssw/sys/Role/{List,Save,Delete?id=} 登录 + 菜单 system/Role
GET /api/ssw/sys/Role/Modules?roleId= 登录 返 string[](菜单 id)
GET/POST/DELETE /api/ssw/sys/Organize/{List,Save,Delete?id=} 登录 + 菜单 system/Organize 有子机构时拒删(code=400)
GET/POST/DELETE /api/ssw/sys/Module/{List,Save,Delete?id=} 登录 + 菜单 system/Module
PUT /api/permission/Authority/Data/{objectId} 登录 body {objectType:'role', module:['m1','m2']} —— objectType 必须小写、module 是一维数组
GET /api/permission/Authority/RoleModules?roleId= 登录 返 string[]
GET/POST/DELETE /api/ssw/demo/DemoItem/{List,Save,Delete?id=} 仅登录 业务模块模板
GET/POST/DELETE /api/ssw/shop/Product/{List,Save,Delete?id=} 登录 + 菜单 shop/Product
GET/POST/DELETE /api/ssw/books/Book/{List,Save,Delete?id=} 登录 + 菜单 books/Book

其它:未知路由 → HTTP 404 + {code:404,msg:'接口不存在',data:null}。

命令速查

# 编译(仓库根是 cargo workspace,成员 = src/backend)
cargo build                      # debug
cargo build --release            # 发布版(release profile 写在根 Cargo.toml)
cargo test                       # 单测

# 运行(后端)
PORT=30010 ./target/release/tds-lite-rs
PGLITE_DIR=memory:// PORT=30010 ./target/release/tds-lite-rs   # 纯内存

# 冒烟
bash scripts/perm-smoke.sh                       # 默认打 127.0.0.1:30010
B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh
./target/release/tds-lite-rs --enc 123456         # cipher 自证(免 node 依赖)

本机 curl 走系统代理,测 localhost 必须加 --noproxy '*'。 后台常驻进程用 Bash 工具的 run_in_background 托管;nohup … & 在工具返回后会被回收。 起服务时 stdout 不要指向 /dev/null(进程会以 100 退出)。

已知踩坑清单

症状 根因 处理
登录必失败(400 账号或密码错误) cipher key 当成了 16 字节原始摘要 ⇒ AES-128 key = md5_hex 的 32 个 ASCII 字节 ⇒ AES-256
f_price 回显 9.9 而不是 "9.90" row_to_json 把 numeric 给了数字 投影里 f_price::text AS price
角色授权写了不生效 写进 base_role_relation.f_user_id(不存在此列) 用户 id 写 f_object_id + f_object_type='user'
组织/岗位授权不生效 写进 base_role_relation 写 base_user_relation(有 f_user_id)
授权接口返 200 但一行没写 objectType 传了 'Role'(大写) 必须小写 'role';module 传一维数组
非管理员拿到了全部菜单 只查了角色授权 四源合并(直授+角色+组织+岗位)
菜单授权没生效但接口放行 菜单 f_url_address ≠ 前端 Route path 三处(urlAddress / Route path / 守卫 key)必须一字不差
Option<Form<T>> 编译不过 axum 0.8.9 的 Form 无 OptionalFromRequest 取原始 body 自己 serde_urlencoded 解析
405 返回 HTML / 丢 Allow 头 用了 axum 的 method_not_allowed_fallback 用响应改写中间件(链尾)
DDL 能从 HTTP 下载 DDL 落在 web root 移到 db/ + 兜底守卫
第二个实例起不来 pglite 单实例独占数据目录 换数据目录/端口
集成测试互相撞车 pglite 独占 + 种子账号唯一 串行跑 或 各用独立数据目录
账号能建重复 官方 f_account 无 UNIQUE(故意的) 唯一性应用层保证;只比 delete_mark=0 的行
data/ 里的库改了不生效 schema 只在首次建表时执行 改 schema ⇒ 清空 data/ 重建

明确不在 v1 范围

  • 低代码引擎(JNPF 的表单/流程/代码生成)—— 官方能力,本仓不碰。
  • 多租户(jnpf-tenant*)—— 单租户固定 f_tenant_id='0'。
  • 按钮/列/表单/数据范围级授权(base_module_button / _column / _form / _data)—— 官方 DDL 里都有,但 v1 只做 item_type='module'(菜单)一类。
  • Redis / Sa-Token —— 内存 token 表即可(进程重启即失效,与 JNPF 的 Sa-Token 内存模式同代)。
  • 分页 —— 契约里的 List 就是全量(前端不分页)。要分页是 JNPF 稳定期的 SuperServiceImpl.page。
  • base_user.secretkey / f_role_id 的 JNPF 真实算法(官方是 md5(md5(raw)+secretkey))—— 本仓留位待迁移补;本仓用 md5(明文) 即可(登录比的是同一个值)。

记忆约定

  • 踩坑清单与长 traceback → docs/<子系统>/<topic>.md(本文件表格即其索引)。
  • 工作日志 → .workbuddy/memory/YYYY-MM-DD.md。
  • 本文件只留「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。