adminandClaude Code 621e636e76 fix(task12): run.sh 的 PORT 守卫只对 dev/backend 生效 + dev 就绪失败一并收掉前端
- 端口守卫从「case 之前」收进 guard_port() 函数,只在 dev / backend 两个分支里调用
  (这两个才真的会起后端并让后端继承 PORT);--help / 无参 / logs / install / build /
  stop / frontend 完全不受 PORT 影响。守卫仍在 kill_ports 之前 ⇒ 用法错不破坏现场。
  报错三行文案与退出码 2 保持不变;export PORT="${PORT:-30010}" 留在原处。
- dev 的就绪失败分支:用 stop_pid 按 PID 文件把本次刚起的前端一并收掉(不用 pkill),
  输出一行「前端进程已一并收掉」,再照旧打印 backend.log 尾部 20 行并 exit 1
  ⇒ 不再在 5173 上留残进程。
- docs/runbook.md 的端口说明同步收窄,并补「dev 失败时前端一并收掉」。

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 04:20:11 +08:00

tds-lite-rs

JNPF 兼容契约的 Rust 实现 —— 单二进制、零外部服务(进程内原生 PostgreSQL)。

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

  • 📘 契约唯一真源:docs/contract.md —— 与本文件冲突时以契约为准。
  • 🧭 agent 指引:CLAUDE.md(红线 / 踩坑 / 端点全表)· HANDOFF.md(交接)。
  • 🛠 怎么起 / 怎么冒烟 / 常见故障:docs/runbook.md。

快速开始

# 一次性:装依赖(cargo fetch + npm install)+ 构建(cargo build --release + vite build)
bash run.sh install
bash run.sh build

# 日常:后台起后端(30010) + 前端(5173),日志在 .logs/,PID 在 .run/
bash run.sh dev
#   前端 http://127.0.0.1:5173   后端 http://127.0.0.1:30010
#   账号 admin / 123456

bash run.sh stop        # 停(幂等)
bash run.sh logs        # 看日志尾部
端口 谁 说明
30010 后端(Rust) PORT 可覆盖;兄弟项目 tdc-rs 占了 :30000,本仓不碰
5173 前端(vite dev) strictPort: true ⇒ 端口被占直接报错,不自动换端口

目录

tds-lite-rs/
├── Cargo.toml               # cargo workspace 根(成员 = src/backend)+ release profile
├── run.sh                   # install / build / dev / backend / frontend / stop / logs
├── .env.example             # PORT / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://)
├── src/backend/             # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,27 条路由)
├── src/frontend/            # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010)
├── scripts/perm-smoke.sh    # 权限闭环冒烟(32 条断言,零 node 依赖)
├── scripts/check-module.sh  # 业务模块 9 接触点静态自检(纯静态,不起后端)
└── docs/                    # contract.md(契约)· runbook.md(运维)· ddl/

它做了什么(v1 = 全量契约对齐)

  • 登录 / CurrentUser:POST /api/oauth/Login(form-urlencoded,密文 hex)⇒ {token, expiresIn:7200, tokenTypeName:'bearer'}; GET /api/oauth/CurrentUser ⇒ {userInfo, menuList}。
  • 5 组 base_* 管理 CRUD:用户 / 角色 / 机构 / 菜单 / 授权。
  • 统一授权:PUT /api/permission/Authority/Data/{objectId}(body {objectType:'role', module:[...]},小写 + 一维数组)。
  • 四源权限合并:用户直授 + 角色 + 组织 + 岗位;管理员在任何 SQL 之前短路放行;菜单未映射 ⇒ 放行。
  • 两段式种子:ensure_base(每次启动补内置角色/菜单/授权)+ first_seed(仅首次建 admin/123456)。
  • 3 个业务模块(spec 驱动 CRUD 引擎):demo/DemoItem · shop/Product · books/Book。

契约红线(摘要,完整版见 CLAUDE.md)

  1. 业务失败一律 HTTP 200 + {code,msg,data};成败只看 body 的 code。 唯一例外:未知路由 = HTTP 404(body 仍是信封)。鉴权失败也是 200(600 未登录 / 403 无菜单权限)。
  2. base_* 表名/列名逐字对齐官方 JNPF DDL(含两个「故意不修正」的陷阱,见 CLAUDE.md)。
  3. numeric 列必须是 JSON 字符串("9.90",不是 9.9);int 列保持数字。
  4. 口令不得外泄:库里存 md5(明文),对外响应手工挑字段(用户列表去掉 password)。
  5. schema DDL 绝不可从 HTTP 下载。

验收门

门 命令 通过标准
① 编译 cargo build --release 0 error 0 warning
② 单测 cargo test 全绿(当前 177 passed / 0 failed)
③ 冒烟 bash scripts/perm-smoke.sh PASS=32 FAIL=0(需后端已起在 :30010)
④ 前端手验 bash run.sh frontend http://127.0.0.1:5173 → admin/123456 登录 → 菜单树正确 → 5 个管理页可增删改 → DemoItem/Product/Book 三页可用 → 退出再登录

外加:bash scripts/check-module.sh(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。

本机 curl 走系统代理 ⇒ 打 localhost 必须加 --noproxy '*'。


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

参照物 地位
官方 JNPF 源码 + DDL(~/Desktop/workspace/jnpf/) 数据模型真源(base_* 表名/列名)
ssw-jnpf-lite-react 技能(~/Desktop/workspace/skills/ssw-jnpf-lite-react/) 行为真源(NestJS 版把契约跑起来了);本仓前端是它的逐字复制
tdc-rs 兄弟项目(~/Desktop/workspace/tdc-rs/) 只抄工程手法;不共享代码 / 端口 / 数据目录

已知限制(分支级)

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

技术栈

Rust 2021 · axum 0.8 · tokio · pglite-rs 0.2(进程内原生 PostgreSQL,零服务/零 Docker/零 WASM)· aes 0.8 + ecb 0.1 + md-5 0.10 · React 18 + Vite 5(逐字复用)

S
Description
JNPF 兼容契约的 Rust 实现(单二进制、零外部服务,进程内原生 PostgreSQL)
Readme
834 KiB
0 Stars 1 Watchers 0 Forks
Languages
Shell 31.1%
Rust 25.7%
Python 18.5%
TypeScript 15.3%
Java 7.6%
Other 1.8%