Files
ssw-jnpf-lite-rust/CLAUDE.md
T
adminandClaude Code 8edcd3507d feat: 前端逐字复制(仅代理端口改 30010)+ run.sh + check-module.sh + 文档
前端:从 ssw-jnpf-lite-react/src/frontend 逐字复制(package-lock.json 一并复制),
唯一改动 = vite.config.ts 的代理目标 30000 → 30010(含紧邻注释行的端口);
src/api/request.ts 的注释与 axios timeout: 30000 逐字节保留。

脚本:run.sh(install/build/dev/backend/frontend/stop/logs,退出码 0/1/2,
kill_ports 只清 30010 与 5173);scripts/check-module.sh(9 接触点静态自检,
纯静态零 node 依赖)。

文档:README.md、docs/runbook.md、.env.example;CLAUDE.md 逐条核对并与代码同步,
HANDOFF.md §0 状态表与 §9 交接话术改为交付态。

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

20 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 代理端口 30000 → 30010;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   # 本文件 / 交接文档
├── README.md                # 项目定位 / 启动方式 / 验收门
├── run.sh                   # install / build / dev / backend / frontend / stop / logs
├── .env.example             # PORT / PGLITE_DIR(后者只能写绝对路径或 memory://)
├── docs/
│   ├── contract.md          # 【契约唯一真源】端点 / 返回形状 / 数据模型
│   ├── runbook.md           # 怎么起 / 怎么冒烟 / 常见故障
│   └── ddl/                 # 官方 DDL 摘录
├── 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 技能前端逐字复制(**只改** vite.config.ts 的代理端口 30000→30010)
├── scripts/
│   ├── perm-smoke.sh        # 权限闭环冒烟(32 条断言,零 node 依赖)
│   └── check-module.sh      # 业务模块 9 接触点静态自检(纯静态,不起后端)
└── .gitignore

架构红线

  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_* 的表名/列名是契约;业务表名只是为了数据模型可移植(两版后端能开同一个库)才故意对齐。

端点全表

🔴 src/backend/src/routes.rs 里逐条注册 27 条路径(axum 0.8.9 用 matchit 0.8.4, 不支持 {a,b} 这种「一段里多个参数」的写法 ⇒ 必须逐条注册)。

方法 路径 守卫 说明
GET /api/health 无 非契约探活 ⇒ {ok, tables, version};永远有响应(查不到表也返 200)
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}。 (routes.rs 的「路由表钉子测试」用「错方法 ⇒ 405」逐条证明这 27 条都注册了。)

命令速查

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

# 工程脚本(仓库根 run.sh;退出码 0 成功 / 1 运行期失败 / 2 用法错)
bash run.sh install              # cargo fetch + npm --prefix src/frontend install
bash run.sh build                # cargo build --release + vite build
bash run.sh dev                  # 后台起后端(30010) + 前端(5173),日志 .logs/、PID .run/
bash run.sh backend              # 前台起后端
bash run.sh frontend             # 前台起前端
bash run.sh stop                 # 停后台进程(幂等)
bash run.sh logs                 # tail .logs/{backend,frontend}.log
bash run.sh                      # 无参 ⇒ 用法错 ⇒ 退出码 2

# 运行(后端)
PORT=30010 ./target/release/tds-lite-rs
PGLITE_DIR=memory:// PORT=30010 ./target/release/tds-lite-rs   # 临时库(系统临时目录的一次性数据目录,进程退出即销毁;pglite-rs 0.2.7 没有真内存模式)

# 前端
npm --prefix src/frontend install        # 或 npm ci(严格按 package-lock.json 装)
npm --prefix src/frontend run build      # 产出 src/frontend/dist
npm --prefix src/frontend run dev        # http://127.0.0.1:5173(vite 代理 /api → 30010)

# 冒烟 / 自检
bash scripts/perm-smoke.sh                       # 默认打 127.0.0.1:30010(32 条断言)
B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh
bash scripts/check-module.sh                    # 9 接触点静态自检(纯静态,不起后端)
./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 ✅本仓已修(cipher.rs 按此实现,上游检验向量单测钉死)
f_price 回显 9.9 而不是 "9.90" row_to_json 把 numeric 给了数字 投影里 f_price::text AS price ✅本仓已修(冒烟断言比的是原始 JSON 文本,字符串与数字能分出来)
角色授权写了不生效 写进 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 传一维数组 ✅本仓已修(冒烟断言覆盖一维/二维两种写法)
非管理员拿到了全部菜单 只查了角色授权 四源合并(直授+角色+组织+岗位) ✅本仓已修(冒烟断言「菜单已按授权收窄」+「访问 User/List ⇒ 403」)
菜单授权没生效但接口放行 菜单 f_url_address ≠ 前端 Route path 三处(urlAddress / Route path / 守卫 key)必须一字不差 ✅本仓已修(scripts/check-module.sh 的第 9 条接触点逐模块钉住)
Option<Form<T>> 编译不过 axum 0.8.9 的 Form 无 OptionalFromRequest 取原始 body 自己 serde_urlencoded 解析 ✅本仓已修(登录端点即此写法)
405 返回 HTML / 丢 Allow 头 用了 axum 的 method_not_allowed_fallback 用响应改写中间件(链尾) ✅本仓已修(routes.rs 测试断言 405 + 保留 Allow 头)
DDL 能从 HTTP 下载 DDL 落在 web root 移到 db/ + 兜底守卫 ✅本仓已修(测试断言两条 DDL 路径都返 404)
第二个实例起不来 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。
  • 本文件只留「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。