Files
ssw-jnpf-lite-rust/HANDOFF.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

30 KiB
Raw Blame History

HANDOFF.md —— tds-lite-rs 交接文档

给下一个会话的你:本文件 + CLAUDE.md 两份读完就能直接开工,不需要重新推导任何设计。 目标:把「JNPF 兼容契约的 Rust 实现」从零写到验收全绿。


0. 当前状态

v1 已完成,验收四门全绿(每一条 ✅ 都有实际执行输出,见 §9 与各任务报告)。

项 状态
目录 ~/Desktop/workspace/tdc-lite-rs/ ✅ 已建并已 commit(main 分支)
CLAUDE.md ✅ 已写;已逐条核对并与代码同步(Task 12)
HANDOFF.md(本文件) ✅ 已写并已同步(§0 状态表 / §9 交接话术,Task 12)
代码 ✅ 后端已实现(src/backend/,Rust 2021 + axum 0.8 + pglite-rs 0.2,10 张表、27 条路由)
前端 ✅ 已逐字复制(src/frontend/;唯一改动 = vite 代理端口 30000 → 30010,其余文件逐字节相同)
脚本 ✅ scripts/perm-smoke.sh(32 条断言)+ scripts/check-module.sh(9 接触点静态自检,55 条 ✅)
工程脚本 ✅ run.sh(install/build/dev/backend/frontend/stop/logs,退出码 0/1/2)
文档 ✅ README.md / docs/runbook.md / .env.example
验收四门 ✅ 全绿(编译 0 error 0 warning · 单测 177 passed / 0 failed · 冒烟 PASS=32 FAIL=0 · 前端浏览器手验全过)

读法:CLAUDE.md(红线与坑位,日常改代码必读)→ §9(怎么起 / 怎么复现验收)。 §3(设计)与 §5(实施顺序 step 0–12)已完结,留作背景与决策记录,不要再照着实施一遍。


1. 决策记录(本轮问答全过程,含被推翻的方案)

保留被推翻的方案,是为了避免下个会话"重新考虑"已经讨论过的问题。

# 问题 决定 理由
1 Rust 版做成什么形态? 先做真实项目,验证后再抽技能 技能是模板;没跑通的模板没有价值
2 v1 做多大? 全量契约对齐(auth + 5 组 base_* + 四源权限 + 两段种子 + 3 业务模块 + 冒烟) 迁移价值全在权限与数据模型这两块,缺一块就不成立
3 落在哪个仓? 独立仓 tds-lite-rs 原方案:tdc-rs 开分支(已被 #4 推翻)
4 运行时拓扑? 先不碰 tdc-rs,独立仓做 tdc-rs 已占 :30000 且已有自己的 /api/oauth/Login(JSON 账号库),两套同路径不同语义会打架
5 目录名? tds-lite-rs(用户指定) 原方案:ssw-jnpf-lite-rust
6 数据库? pglite-rs 0.2(进程内原生 PG) 沿用 tdc-rs 已验证的形态;零服务零 Docker
7 后端端口? :30010(前端 vite :5173) 避开 tdc-rs 的 :30000
8 前端怎么办? 逐字复制 react 技能的前端,零改动 前端零改 = 契约真的对齐了(改了就说明后端在迁就前端)
9 业务实体怎么实现? spec 驱动 CRUD 引擎;5 组 base_* 走显式 handler 业务模块语义简单可声明化;base_* 的语义(一维授权数组 / 用户↔角色 / 机构树防环)塞不进通用引擎
10 冒烟脚本的 node 依赖? Rust 二进制加 --enc <明文> 模式,脚本自证 cipher,不依赖 node 去掉 node 依赖 = 冒烟可在任何装了 Rust 的机器上跑
11 抽技能的时机? 验收门全绿之后再抽 目录结构现在就和 react 技能对齐(src/backend + src/frontend + scripts/ + run.sh),届时 1:1 复制即可

关键约束:tdc-rs 只读。本仓不 import 它的代码、不共享数据目录、不共享端口。 可以读它的 src/cipher.rs / src/db.rs / src/envelope.rs 作工程手法参考。


2. 目标与非目标

目标(v1 做完的样子):

  1. 用 Rust 起一个单二进制、零外部服务的后端,行为与 ssw-jnpf-lite-react(NestJS)逐条一致。
  2. 前端一行不改就能跑通(直接复用 react 技能的 src/frontend)。
  3. base_* 表结构与官方 DDL 逐字一致 ⇒ 迁 JNPF 时导数据即可(--data-only)。
  4. 权限闭环(登录 → 菜单树 → 建用户 → 授权 → 收窄 → 403)有自动化冒烟钉住。
  5. 跑通之后,1:1 复制成技能(ssw-jnpf-lite-rust)。

非目标(明确不做):低代码引擎 / 多租户 / 按钮·列·表单·数据范围级授权 / Redis+Sa-Token / 分页 / secretkey 的官方双层 md5 算法。理由见 CLAUDE.md「明确不在 v1 范围」。


3. 设计(已定稿)

3.1 落点与边界

tds-lite-rs/                      ← 独立 git 仓(已 init,未 commit)
├── Cargo.toml                    ← 【workspace 根】members=["src/backend"] + [profile.release]
├── src/backend/  ← 名字保留是为了将来抽技能时目录与 react 版对齐
│   ├── src/*.rs                  ← 14 个模块(见 §3.3)
│   ├── db/schema.sql             ← 10 张表完整 DDL
│   └── data/                     ← 运行期(gitignore)
├── src/frontend/                 ← react 技能前端逐字复制(零改)
├── scripts/{perm-smoke.sh,check-module.sh}
├── run.sh                        ← install/build/dev/stop/logs
└── .env.example

端口:后端 30010(PORT 可覆盖)· 前端 5173(vite)· vite proxy /api → http://127.0.0.1:30010。

数据库:pglite-rs,默认落盘 src/backend/data/lite.pg;PGLITE_DIR=memory:// ⇒ 纯内存。

3.2 契约逐字对齐表(对着 react 技能源码抄)

契约点 精确口径 react 源码位置
统一返回 {code,msg,data};成功 code=200,msg='成功';失败 data=null src/backend/src/common/action-result.ts
HTTP 状态 业务失败/鉴权失败 HTTP 200;未知路由 HTTP 404(body 仍是 ActionResult) common/action-result.filter.ts
错误码 未登录 600 · 无菜单权限 403 · 业务失败 400(msg 透传) 同上 + 各 controller
登录 POST /api/oauth/Login,form-urlencoded account/password(密文 hex)/grant_type=password auth/auth.controller.ts:19
登录失败文案 缺参 → 400 '缺少 account / password';grant_type 不支持 → 400;口令错 → 400 '账号或密码错误' auth/auth.controller.ts
登录成功体 {token, expiresIn:7200, tokenTypeName:'bearer'} auth/auth.service.ts
CurrentUser GET /api/oauth/CurrentUser → {userInfo:{userId,userAccount,userName,isAdministrator}, menuList} auth/auth.controller.ts:34
cipher md5(明文) → AES-256-ECB-PKCS7(key=md5("EY8WePvjM5GGwQzn") 的 32 ASCII 字节)→ hex common/cipher.ts
检验向量 encryptPassword('123456') = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b common/cipher.ts 注释
口令比对 库内存 md5(明文) 小写 hex;登录解出 md5(明文) ⇒ 大小写不敏感比较 auth/auth.service.ts
权限四源 直授 + 角色 + 组织 + 岗位;管理员短路在 SQL 之前;菜单未映射 ⇒ 放行 sys/permission.service.ts
菜单树 `parentId
授权写入 PUT /api/permission/Authority/Data/{objectId},body {objectType:'role'(小写), module:[...]}(一维) sys/authorize.controller.ts:39
授权读取 GET /api/permission/Authority/RoleModules?roleId= → string[] sys/authorize.controller.ts:52
角色授权写 旧行软删(delete_mark=1)后插新行 sys/sys.service.ts:saveRoleModules
用户↔角色 setUserRoles = 先 delete 旧 base_role_relation 行再插新行 sys/sys.service.ts
用户列表 去掉 password,追加 roleIds / roleNames sys/sys.service.ts:listUsers
账号唯一 应用层保证,只比 delete_mark=0(官方 DDL 无 UNIQUE) sys/sys.service.ts:saveUser
机构删除 有子机构 ⇒ 400 '该机构下还有子机构,先删除子机构' sys/sys.service.ts:deleteOrganize
业务 List 软删过滤 + creatorTime DESC shop/product.service.ts
业务 Save 无 id ⇒ 新 36 位 UUID + creatorUserId='admin' + creatorTime=now + deleteMark=0;有 id ⇒ 覆盖更新 shop/product.service.ts
业务 Delete 软删(f_delete_mark=1) shop/product.service.ts
numeric 列 JSON 字符串("9.90") shop/product.entity.ts + TypeORM numeric→string
int 列 JSON 数字 books/book.entity.ts
端点命名 `/api/ssw/{appCode}/{Entity}/{List Save

种子里必须逐字保留的常量(sys/seed.service.ts 的字面量数组):

  • 角色:role_admin/enCode admin/管理员/sort 1;role_user/enCode user/使用者/sort 2
  • 菜单(f_type:1=目录 2=页面):
    id fullName urlAddress parentId type icon sortCode
    m_sys 系统管理 system 0 1 setting 1
    m_user 用户管理 system/User m_sys 2 — 2
    m_role 角色管理 system/Role m_sys 2 — 3
    m_org 机构管理 system/Organize m_sys 2 — 4
    m_menu 菜单管理 system/Module m_sys 2 — 5
    m_demo Demo 示例 demo-item 0 2 app 6
    m_product 产品管理 shop/Product 0 2 app 7
    m_book 图书超市 books/Book 0 2 app 8

⚠️ perm-smoke.sh 在 react 版里是从 seed.service.ts 的字面量动态算期望菜单树的。 Rust 版没有那个文件 ⇒ 两种做法二选一: (a) 把上表搬进冒烟脚本作为字面量;或 (b) 后端暴露一个只读端点/二进制子命令打印期望树。 推荐 (a):脚本自包含、离线可跑。菜单增删时同步改脚本(这是刻意的耦合,不是缺陷)。

两段式种子(sys/seed.service.ts):

  • ensureBase(每次启动都跑,幂等):按 enCode 补内置角色、按 urlAddress 补内置菜单、 补齐 admin 角色对内置菜单的授权(取库里真实行 id)。 只补缺项:不覆盖已改值;同 urlAddress 已有行(含软删)不复活。
  • firstSeed(仅 users==0 时跑一次):admin/123456(f_is_administrator=1, f_organize_id='0')
    • 一条 base_role_relation(object_type='user', object_id='admin', role_id='role_admin')。 角色/菜单/授权行已由 ensureBase 建出,不重复写。

3.3 后端模块划分

模块 职责 备注
main.rs 启动装配:开库 → 起 schema → seed → 建路由 → 挂中间件 → 监听 with_state 必须是最后一步
config.rs PORT / PGLITE_DIR / 静态目录 / 种子开关 环境变量
db.rs pglite 封装:query_json() / query_rows() / exec() / ensure_schema() / valid_table() 单 backend ⇒ 进程级 db_lock
cipher.rs md5_hex() / encrypt_password() / decrypt_to_md5() 逐字对齐 cipher.ts + 上游向量单测
envelope.rs ActionResult{code,msg,data} + ok/fail/fail_code 业务失败恒 HTTP 200
ids.rs new_uuid() → 36 位 UUID v4 不是 tdc-rs 的雪花
session.rs 内存 token 表(lite- 前缀 + 32 hex) 进程重启即失效
auth.rs 登录 / CurrentUser / require_login() / require_module() 守卫返回 ActionResult(600 / 403)
permission.rs resolve_user_module_ids() 四源合并 / has_module() 管理员短路+未映射放行 / build_menu_list() 四源 + 两条放行路径都要有测试
seed.rs ensure_base() + first_seed() 幂等 + 只补缺项
sys.rs 5 组 base_* 的显式 handler 语义 用户/角色/机构/菜单/授权
crud.rs spec 驱动的通用 CRUD(List/Save/Delete) 业务实体用
entities.rs 业务实体 spec 表(表名 / 列 / 类型 / 数值列 / 守卫菜单 key) 加业务模块 = 加一条 spec
routes.rs 路由装配

3.4 三个关键取舍

  1. 业务实体走 spec 引擎,base_* 走显式 handler。 理由:业务模块语义同构(列表/保存/软删/守卫),声明化后"加一个模块 = 加一条 spec"; 而 base_* 的语义(一维授权数组、用户↔角色关系、机构树防环、账号唯一性)塞不进通用引擎, 硬塞会得到一个既不懂 JNPF 又难懂的框架。
  2. numeric 列在 SQL 投影里就 cast 成 text。 理由:row_to_json 直接给数字 ⇒ serde_json 解析成 f64 ⇒ 回显 9.9 ⇒ 契约破。 在投影层 f_price::text AS price 才是"一次解决、处处一致"。
  3. HTTP 状态语义刻意不同于 tdc-rs(那边是 401/403 裸 body,这边是 200 + code 600/403)。 理由:react 前端的拦截器只认 body.code;两边同时跑时更不能混形状,否则冒烟脚本得写两套。

3.5 前端

  • 逐字复制 ssw-jnpf-lite-react/src/frontend → src/frontend(package.json / vite.config.ts / src/**)。
  • 唯一允许的改动:vite 的 proxy 目标端口 30000 → 30010(以及 baseURL 仍是 /api,不变)。
  • 前端 utils/cipher.ts 保持不变(它是浏览器侧算法;后端 Rust 侧必须与它逐字节等价——由上游向量钉住)。
  • 路由 path(App.tsx):/login /demo-item /shop/Product /books/Book /system/User /system/Role /system/Organize /system/Module ⇒ 去掉前导斜杠就是 base_module.f_url_address ⇒ 也是后端守卫的 module key。三处一字不差。

3.6 目录/文件对照(react 技能 → 本仓)

react 技能 本仓
src/backend/src/common/cipher.ts src/backend/src/cipher.rs
src/backend/src/common/action-result.ts + .filter.ts src/backend/src/envelope.rs
src/backend/src/auth/* src/backend/src/auth.rs
src/backend/src/sys/permission.service.ts src/backend/src/permission.rs
src/backend/src/sys/seed.service.ts src/backend/src/seed.rs
src/backend/src/sys/sys.service.ts src/backend/src/sys.rs
src/backend/src/{demo,shop,books}/* src/backend/src/entities.rs + crud.rs
src/backend/db/schema.sql src/backend/db/schema.sql(本仓要写全 10 张表)
src/frontend/** src/frontend/**(逐字复制)
scripts/perm-smoke.sh scripts/perm-smoke.sh(移植,cipher 改用 --enc)
scripts/check-module.sh scripts/check-module.sh(移植,grep 模式按 Rust 调整)
run.sh run.sh(改成 cargo 版本)

4. 四道验收门("做完"的唯一判据)

门 命令 通过标准
① 编译 cargo build --release 0 error 0 warning;release 配置照 tdc-rs(opt-level=2 / lto="thin" / strip="symbols" / panic="abort" / codegen-units=16)
② 单测 cargo test 覆盖:cipher 上游向量 · 信封形状(200/400/600/403)· 四源合并 · 管理员短路 · 未映射放行 · 种子幂等(跑两次结果一致 + 不复活软删行)· CRUD 往返(36 位 UUID / numeric→"9.90" / int→100)· 账号重复返 400 而非 500
③ 冒烟 bash scripts/perm-smoke.sh 22+ 条断言全绿(FAIL=0),与 react 版断言集逐条对应(见 §5 步骤 11 的清单)
④ 前端手验 cd src/frontend && npm run dev 浏览器 http://127.0.0.1:5173 → admin/123456 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录

外加:scripts/check-module.sh(9 接触点静态自检)的 Rust 版移植,作为"加模块后立刻跑"的前置闸门。


5. 建议实施顺序(step 0–12)

每步都带完成判据。做完一步先跑该步的判据,再进下一步。

step 内容 完成判据
0 建 cargo workspace(根 Cargo.toml:[workspace] members=["src/backend"] + [profile.release])+ 成员 crate(依赖照 tdc-rs:axum 0.8 / tokio / tower-http 0.6 / serde / serde_json / serde_urlencoded 0.7 / rand 0.8 / hex 0.4 / aes 0.8 / ecb 0.1 / md-5 0.10 / uuid v4 / pglite-rs 0.2 / chrono 0.4) 根目录 cargo build 通过(哪怕是空 main)
1 src/cipher.rs + 单测 上游向量逐字节相等;md5_hex 与 decrypt_to_md5 往返一致
2 src/envelope.rs + 单测 业务失败 HTTP 200 + code=400;code=600/403 同形
3 src/db.rs + src/config.rs + db/schema.sql(10 张表) 进程能开库并建表;query_json() 能取回 JSON
4 src/ids.rs + src/session.rs UUID 36 位带连字符;token 登录后可查回
5 src/seed.rs(ensure_base + first_seed) 空库启动 ⇒ admin/123456 + 2 角色 + 8 菜单 + admin 授权;再启动一次库内容不变
6 src/permission.rs + 单测 四源合并各源单独可注入;管理员短路不查 SQL(可用「无授权记录的管理员仍放行」验证);未映射菜单放行
7 src/auth.rs + /api/oauth/* 登录返 {token,expiresIn:7200,tokenTypeName:'bearer'};CurrentUser 返 {userInfo,menuList};无 token ⇒ code=600
8 src/sys.rs + /api/ssw/sys/* + /api/permission/Authority/* 5 组 CRUD 语义对齐;重复账号返 code=400 + msg '账号已存在:xxx'(不是 500);授权写 objectType='role' 小写 + 一维数组
9 src/entities.rs + src/crud.rs + 3 个业务模块端点 demo/shop/books 三个模块端点可用;numeric 往返 "9.90";未授权非管理员访问 shop/books ⇒ code=403
10 src/routes.rs + main.rs 装配 + 404/405 兜底 未知路由 HTTP 404 + code=404;405 返回 JSON;with_state 在链尾
11 scripts/perm-smoke.sh 移植(逐条对应 react 版) 22+ 断言全绿
12 前端复制 + run.sh + .env.example + 文档 门④ 手验全过;run.sh install/build/dev/stop/logs 可用

step 11 的断言清单(照 react 版 scripts/perm-smoke.sh 逐条移植):

  1. 无 token 访问 User/List ⇒ code=600
  2. 加密登录 ⇒ code=200;3. 拿到 token(非空)
  3. CurrentUser ⇒ code=200
  4. 菜单树与种子表逐字相等(推荐做法:把 §3.2 的菜单表搬进脚本作字面量)
  5. 建用户 ⇒ code=200
  6. 重复账号 ⇒ HTTP 200(不是 500)且 code=400 且 msg '账号已存在:smoke_user'
  7. 写授权(一维数组)⇒ code=200;9. 写授权(二维兼容)⇒ code=200
  8. 非管理员登录 ⇒ code=200
  9. 非管理员菜单已收窄(字符串比对)
  10. 非管理员访问 User/List ⇒ code=403
  11. 已授权业务(demo)⇒ code=200
  12. 未知路由 ⇒ HTTP 404(不被吞掉)
  13. admin 短路 ⇒ Product 列表 code=200
  14. Product 新建 ⇒ code=200;17. 主键 36 位;18. numeric 往返 "9.90"
  15. Product 无 token ⇒ code=600;20. 未授权非管理员 ⇒ code=403

(react 版共 22+ 条,上表是主干;移植时以 react 脚本为准逐条对齐,一条不落。)

另外:scripts/check-module.sh(9 接触点静态自检)移植为 Rust 版—— 把「grep TS 文件里的字符串」换成「grep Rust 源 + 检查 spec 注册」,保持同样的 ❌ 判定与退出码约定 (0 全过 / 1 有 ❌ / 2 用法错)。

脚本退出码约定(三个入口一致,照抄 react 技能):

入口 0 1 2
run.sh 执行成功 运行期失败 用法错
scripts/check-module.sh 接触点全过 有 ❌ 项 用法错
scripts/perm-smoke.sh 全绿(FAIL=0) 有断言失败 前置错误(后端不可达)

6. 必读参考文件(绝对路径)

契约真源(react 技能,只读)

~/Desktop/workspace/skills/ssw-jnpf-lite-react/
├── src/backend/src/common/cipher.ts                  ← cipher 算法 + 检验向量
├── src/backend/src/common/action-result.ts           ← {code,msg,data}
├── src/backend/src/common/action-result.filter.ts    ← HTTP 状态映射(200/404 的来源)
├── src/backend/src/auth/auth.controller.ts           ← 登录 / CurrentUser 端点与文案
├── src/backend/src/auth/auth.service.ts              ← 口令比对、token 生成
├── src/backend/src/sys/permission.service.ts         ← 四源合并 + 管理员短路 + 未映射放行 + 菜单树
├── src/backend/src/sys/seed.service.ts               ← roles/menus 字面量 + 两段式种子
├── src/backend/src/sys/sys.service.ts                ← 5 组 base_* CRUD 语义
├── src/backend/src/sys/authorize.controller.ts       ← 授权写/读 + 一维 module 归一化
├── src/backend/src/sys/base-*.entity.ts              ← 7 张表的列 ↔ JSON 键映射
├── src/backend/src/{demo,shop,books}/*               ← 业务模块参照实现
├── src/frontend/src/api/{request,auth,sys,product,book}.ts  ← 前端实际调用的端点
├── src/frontend/src/App.tsx                          ← 前端路由 path(= urlAddress)
├── src/frontend/src/utils/cipher.ts                  ← 浏览器侧 cipher(后端必须等价)
├── scripts/perm-smoke.sh                             ← 断言集(逐条移植)
├── scripts/check-module.sh                           ← 9 接触点静态自检
└── run.sh                                            ← 脚本骨架(改成 cargo 版)

官方 JNPF(数据模型真源,只读)

~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql
  base_authorize        :812
  base_module           :2209
  base_organize         :3178
  base_role             :3686
  base_role_relation    :3729
  base_user             :4479
  base_user_relation    :4707
(另有 base_module_{authorize,button,column,data,form,link,scheme,use_num}、
  base_organize_administrator、base_user_{device,extra,old_password} —— v1 不做)
同目录还有 jnpf_db_init.sql(base_user 的 INSERT 可二次确证列名)等 9 个 init 文件

工程手法参考(tdc-rs,只读、不共享代码)

~/Desktop/workspace/tdc-rs/src/cipher.rs      ← cipher 的 Rust 版逐字实现 + 坑位注释
~/Desktop/workspace/tdc-rs/src/envelope.rs    ← 信封形状
~/Desktop/workspace/tdc-rs/src/db.rs          ← pglite 封装 / query_json / valid_table
~/Desktop/workspace/tdc-rs/src/main.rs        ← resolve_project_dir / 404 兜底 / with_state 收口
~/Desktop/workspace/tdc-rs/src/routes/mw.rs   ← 405 JSON 兜底中间件
~/Desktop/workspace/tdc-rs/Cargo.toml         ← release 配置

7. 风险与坑(开工前先知道)

风险 表现 处置
pglite 单实例独占数据目录 第二个进程起不来(postmaster.pid 锁) 换数据目录/端口;集成测试串行或各用独立目录
pglite 体积 debug 二进制 ~35 MB(内嵌 PG 引擎) 与 tdc-rs 同量级,可接受
cipher 的 ASCII-hex key 坑 一旦当 16 字节摘要用 ⇒ AES-128 ⇒ 登录全挂 单测钉死上游向量(步骤 1)
numeric 变 9.9 前端金额显示错、冒烟第 18 条红 投影层 ::text(步骤 9)
base_role_relation 无 f_user_id 角色授权不生效 建表时逐字照官方 DDL(步骤 3)
npm 装 esbuild 被拦 vite 起不来 / 端口 000 且报错不指根因 npm install-scripts approve esbuild 后在 src/frontend 重跑 npm install
前端端口 macOS 上 localhost:5173 失败 用 127.0.0.1:5173(vite 模板固定 bind IPv4)
冒烟脚本依赖 node 换机器跑不了 Rust 侧 --enc 自证(步骤 11)
权限"看起来生效"其实没测到 返回了数据 ≠ 权限生效(管理员短路/菜单没映射/未清缓存/异常降级放行,四条路径全是放行) 必须以「菜单收窄 + 403 拦截」为判据

8. 开放问题(开工时按需裁决,不阻塞)

  1. git 首个 commit 何时做 —— 目录已 git init 但未 commit。建议步骤 0 结束就 commit 一次骨架。
  2. Cargo workspace 还是单 crate —— ✅ 已定:workspace。 根 Cargo.toml = [workspace] members = ["src/backend"] resolver = "2" + [workspace.dependencies] + [profile.release](release profile 只在 workspace 根生效,别写到成员里); src/backend/Cargo.toml = 成员 crate(crate 名 tds-lite-rs,src/main.rs 在 src/backend/src/main.rs)。 理由:保持目录与 react 版对齐 ⇒ 抽技能时 1:1 复制。
  3. --enc 子命令的参数形式 —— 建议 ./tds-lite-rs --enc 123456(打印 hex 到 stdout,退出码 0); 未知参数按 --help 处理。
  4. 是否需要 /api/health —— react 版没有。建议加({ok, tables, version}),便于冒烟探活,但不是契约。
  5. 抽技能的目标目录名 —— 建议 ssw-jnpf-lite-rust,落在 ~/Desktop/workspace/skills/, 与 ssw-jnpf-lite-react 并列。验收全绿后再做。

9. 交接话术(交付态:这个仓是什么、怎么跑、怎么复现验收)

读 CLAUDE.md + HANDOFF.md(本文件)。设计已定稿且已实现完毕,不要重新设计、不要重写。

一句话

tds-lite-rs = JNPF 兼容契约的 Rust 实现(单二进制、零外部服务:Rust 2021 + axum 0.8 + pglite-rs 0.2 进程内原生 PostgreSQL;10 张表、27 条路由)。 状态:v1 已完成,四道验收门全绿(见 §0)。

怎么起

cd ~/Desktop/workspace/tdc-lite-rs
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)
  • 前端:http://127.0.0.1:5173(vite dev server,/api 代理到后端)
  • 后端:http://127.0.0.1:30010
  • 账号:admin / 123456(首次启动自动种子)
  • bash run.sh logs 看日志(.logs/backend.log、.logs/frontend.log);bash run.sh stop 停(幂等)
  • 🔴 run.sh 的 kill_ports 是 kill -9 ⇒ 只清 30010 / 5173,绝不碰兄弟项目 tdc-rs 的端口
  • 🔴 打 localhost 用 curl 必须加 --noproxy '*'(本机 curl 走系统代理)

怎么复现验收(四门,逐字命令 + 通过标准)

门 命令 通过标准
① 编译 cargo build --release 0 error 0 warning
② 单测 cargo test 177 passed / 0 failed(8 个测试目标:63+6+19+24+3+18+7+37)
③ 冒烟 bash scripts/perm-smoke.sh(后端先起在 :30010) PASS=32 FAIL=0,退出码 0
④ 前端手验 bash run.sh dev ⇒ 浏览器开 http://127.0.0.1:5173 admin/123456 登录 → 菜单树正确 → 5 个管理页可增删改 → 3 个业务页可用 → 退出再登录

外加前置闸门:bash scripts/check-module.sh(9 接触点静态自检,纯静态、零 node 依赖; 期望 PASS=55 FAIL=0;无参 ⇒ 查全部三个业务模块)。

门④ 的浏览器手验清单(逐条):

  1. admin/123456 登录 ⇒ Dashboard 出现「功能菜单」;
  2. 菜单树 = 系统管理(用户管理 / 角色管理 / 机构管理 / 菜单管理)+ Demo 示例 + 产品管理 + 图书超市;
  3. 4 个管理页(用户/角色/机构/菜单)从菜单按钮进入,页面标题正确,且可增删改;
  4. 3 个业务页(DemoItem / Product / Book)可达、可增删;
  5. 退出 ⇒ 回登录页 ⇒ 再登录 ⇒ 仍正常。

⚠️ 已知:react 版 Dashboard 只渲染「目录的子项」(node.children)⇒ Demo 示例 / 产品管理 / 图书超市是顶层页面型菜单(parentId='0',无子项)⇒ Dashboard 里没有按钮,只能按 URL 直达(/demo-item、/shop/Product、/books/Book)。 这是参照物原样行为(前端逐字复制 ⇒ 本仓未改),不是本仓的 bug。

已知限制(分支级)

摘自 ledger(.superpowers/sdd/tds-lite-rs-v1/progress.md)的「分支级已知限制清单」:

  • (k) release 二进制没有 catch-all 的自动化覆盖(触发 panic 的端点是 #[cfg(test)] 专属; catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile 无 panic = "abort" ⇒ 行为等价)。
  • (l) Path<String> 遇畸形百分号编码 ⇒ axum 默认返纯文本 400(非信封)(handler 签名由契约 §S17 定死,改它要动 sys.rs)。
  • (m) 冒烟脚本每次跑会往库里留一行 shop_product + 一行 book_shop_book + 一行 smoke_user (react 同款行为;契约 §13 未要求清理 ⇒ 不改)。
  • (n) 冒烟脚本在「重复账号 curl 超时」场景下 stderr 会多一行 cat: … No such file(观感,判据不受影响)。
  • (o) 冒烟脚本在「空 body 前置失败」时 jq / python 两条路径的前置提示文案不同 (code=无 vs code=ERR),退出码都是 2。

本任务(Task 12)另记两条已观察、未改的观察(留给最终整体评审裁决):

  • react 版 Dashboard 只渲染「目录的子项」 ⇒ 3 个顶层业务页在菜单里没有入口按钮(只能按 URL 直达)。 前端是逐字复制 ⇒ 改它会破「除代理端口外一字不改」的硬约束 ⇒ 不改,只记档。
  • src/frontend/vite.config.ts 的注释仍写着「转发到 NestJS 后端(30010)」—— 本仓后端是 Rust。该注释行属于「代理目标行 + 紧邻注释行」两行允许改动范围, 但 brief 只授权把端口 30000 → 30010 ⇒ 框架名逐字保留,不「顺手修好」(最终评审按 Minor 记)。

下一步(按 plan)

验收四门全绿 ⇒ 下一步是把本仓 1:1 复制成技能 ssw-jnpf-lite-rust, 落在 ~/Desktop/workspace/skills/,与 ssw-jnpf-lite-react 并列 (技能资产形态 = 本仓 1:1 复制;目录结构已刻意与 react 版对齐)。