- 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]>
18 KiB
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
架构红线
- 🔴 契约优先于实现。 任何端点的路径、入参、返回形状、错误码,必须与
ssw-jnpf-lite-react逐字一致。不确定时先读 react 技能源码,别凭印象。 - 🔴 业务失败一律 HTTP 200 +
{code,msg,data}。 成败只看 body 的code。 例外只有一个:未知路由保留 HTTP 404(body 仍是ActionResult形状)。 🔴 鉴权失败也是 HTTP 200(code=600未登录 /code=403无菜单权限)—— 与tdc-rs的 401/403 裸 body 相反,别把 tdc-rs 的形状抄过来。 - 🔴
base_*表名与列名逐字对齐官方 DDL(含两个官方陷阱,见下)。 不允许自创表名/列名——迁移期靠--data-only导数据,列名差一个字符就导不进去。 - 🔴 四源权限合并 + 管理员短路 + 未映射放行。
- 管理员(
f_is_administrator=1)在任何 SQL 之前短路放行; - 权限 = 用户直授 + 角色 + 组织 + 岗位,只查角色会漏授权;
- 菜单未映射到
base_module⇒ 放行(对齐SswPermissionGuard的 warn 路径), 不是拒绝。这条最容易写反,且静默(不报错),所以必须有测试钉住。
- 管理员(
- 🔴 口令不得外泄。 库内存
md5(明文);对外响应手工挑字段(用户列表要去掉password)。 密文只在请求体里出现,永不回显。 - 🔴 前端不直接持有数据库。 一切访问经
/api/**。 - 🔴 schema DDL 绝不可从 HTTP 下载。
db/schema.sql不在 web root, 且要有兜底守卫(/api/**之外的静态托管只放前端产物)。 - 🔴 同一文件的多个 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 为准。
关键实现细节(改代码前必读)
- 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 实现可读作参考(但不共享代码)。 - 口令比对:
base_user.f_password存md5(明文)的小写 hex; 登录时decrypt(密文)得到md5(明文)⇒ 大小写不敏感比较。 - 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)保持数字。 - 主键是 36 位 UUID v4(带连字符),列
varchar(50)装得下。不是tdc-rs的雪花十进制。 - 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)。 - pglite 单 backend 串行化:所有 DB 访问必须持进程级
db_lock(OnceLock<Arc<tokio::Mutex<()>>>)。同时一个数据目录只能被一个进程打开 ⇒ 集成测试要么串行、要么各自用独立数据目录。 - 查询结果序列化:沿用
tdc-rs的手法SELECT row_to_json(q)::text AS _row FROM (<sql>) q⇒ 取单列文本 ⇒serde_json::from_str。 不要另起逐列类型映射分支。 - 标识符白名单:任何拼进 SQL 的表名/列名都要过白名单
(
[A-Za-z][A-Za-z0-9_]*),并在启动时自检全部拼接点,不过白名单 ⇒ 秒退。 include_str!路径相对src/db.rs:写../db/schema.sql。- axum 0.8 语义:
Router<S>的S是"还缺什么状态" ⇒with_state必须是链条最后一步。 Form<T>在 axum 0.8.9 只实现FromRequest(没有OptionalFromRequest) ⇒Option<Form<T>>编译不过 ⇒ 需要"解析失败也走业务信封"的表单端点, 取原始 body 自己用serde_urlencoded::from_bytes解析。 (/api/oauth/Login正是这种端点,且grant_type不能加 camelCase。)- 405 的 JSON 兜底用响应改写中间件(挂在链尾),不要用 axum 的
method_not_allowed_fallback(后者只对调用那一刻已注册的路由生效,且丢Allow头)。 - schema 初始化:启动时探测
base_user是否存在,不存在才按;拆分执行schema.sql(拆分要字面量感知,别把字符串里的;当语句边界)。 - 路径与 cwd 解耦:
resolve_project_dir()从可执行文件向上找锚点文件,static/与data/都基于它 —— 后台启动时 cwd 会漂移,改成相对 cwd ⇒ 500。 - 未知路由 = 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。 - 本文件只留「原则 + 决定 + 一句话摘要」。改代码后回头核对本文件是否还成立。