- HANDOFF §1 现状:端点 376(面 B 346)/ tables 52 / 测试 550 / 官方覆盖 365-372 - HANDOFF 新增 §1「批次 11」小节:表名≠控制器名、enCode 前缀化(create 用 !=0、 update 用 ==1,delete 比对用带前缀的码)、conditionJson 三层结构、方案列表 只需登录、SYS020/SYS021、3 处诚实降级 - HANDOFF 新增「本批踩到并解决的 5 个真 bug」+ §5「批次 11 新增的坑」6 条 - HANDOFF §3 待办:划掉批次 11,补批次 12 指引(缺口 system 55 / permission 26 / systemData 32) - HANDOFF 修正「八道闸门」为「十二道闸门」(旧措辞与 CLAUDE.md 不一致) - PLAN 差距表:面 B 331 → 346,base_* 49 → 52 - CLAUDE.md:cargo test 545 → 550(两处写死值) - memory 日志追加批次 11 段落:结论 / 9 个坑 / 数字(均已复验)
325 lines
26 KiB
Markdown
325 lines
26 KiB
Markdown
# CLAUDE.md — 尚数网 Rust 后端开发框架(ssw-platform)
|
||
|
||
> **本文件是项目级红线 / 当前阶段范围文件。** 代码级「契约唯一真源」在脚手架自带的各项文档里
|
||
> (`docs/contract.md` / `JNPF_COMPAT_SURFACE.md` / `PERMISSION.md` / `MIGRATION.md` 等)。
|
||
>
|
||
> 🔴 **长期架构与路线(定位 / 分层 / 动态加载 / MCP / 迁移 / P0–P5)见 [`PLAN.md`](PLAN.md)。**
|
||
> 本文件只管**当前阶段的红线与范围**,范围表随阶段推进滚动;两者冲突时以 `PLAN.md` 的架构决策为准。
|
||
> 改代码后回头核对两文件是否还成立。
|
||
|
||
---
|
||
|
||
## 0. 一句话定位
|
||
|
||
**尚数网 Rust 后端(ssw-platform)= 用 Rust 重写「尚数网 Java 版后台」,契约与数据库逐字兼容 Java 版(= JNPF v7.0 形状),从而前端 / 移动端 / 库原地不动,只换后端引擎。**
|
||
|
||
- 后端先迁(单二进制、好部署、编译期类型安全)。
|
||
- 前端 / 移动端 / 数据库 **本期不动**,靠「双面契约 + 同一套 `base_*` schema + 同一把 cipher + 同一套 seed」做到兼容。
|
||
- 多租户 / SSO / 微服务 **本期不迁**(见 §2.2)。
|
||
|
||
技术底座 = 已验证的 `ssw-jnpf-lite-rust` 脚手架(axum 0.8 + pglite-rs 0.2 进程内 PostgreSQL,零外部服务)。
|
||
本仓库 = 该脚手架的**实例化项目**;脚手架文档即本项目的契约真源,升级从脚手架同步进来。
|
||
|
||
---
|
||
|
||
## 1. 三个参照物(各司其职,别混)
|
||
|
||
| 参照物 | 路径 | 地位 |
|
||
|---|---|---|
|
||
| **JNPF v7.0 官方源码 + DDL** | git-mirror `jnpf/7.0-jnpf-java-boot` + `jnpf/7.0-jnpf-database`(`PostgreSQL/JNPF-PostgreSQL.sql`) | **数据模型真源**:`base_*` 表名/列名/陷阱以官方 DDL 为准 |
|
||
| **`ssw-jnpf-lite-rust` 脚手架** | `~/Desktop/workspace/skills/ssw-jnpf-lite-rust/`(三处软链同仓) | **契约/工程真源**:本项目的模板与绑定规范 |
|
||
| **尚数网 Java 版(公司 fork)** | 当前生产系统(不在这些 mirror 里) | **兼容目标**:其前端/移动端/库应由本后端无缝接管 |
|
||
|
||
🔴 **关键判断**:mirror 里只有上游 JNPF,没有公司 fork。因此「兼容 Java 版」在工程上
|
||
= **兼容官方 JNPF v7.0 契约(面 B)+ 同一套 `base_*` schema**。Java 版若对官方有定制,
|
||
需要在 Phase 2 拿 Java 版实跑一次面 B diff(见 §8 待确认决策 ③)才能确认覆盖度。
|
||
|
||
---
|
||
|
||
## 2. 范围
|
||
|
||
### 2.1 本期必做(v1,= 脚手架已交付能力)
|
||
|
||
- **后端平台层**:登录 / `CurrentUser` / 5 组 `base_*` 管理 CRUD / 统一授权 / 四源权限合并 / 两段式种子。
|
||
- **双面契约**:面 A(ssw/react 形状,冻结)+ 面 B(官方 JNPF 形状,按 `Vue-Version: 3` 分流)。面 B 让 Java 前端/移动端直连。
|
||
- **3 个示例业务模块**(demo / shop / books)—— 作为「加业务模块」的模板,不进生产。
|
||
- **多应用(app)**:`App-Code` 请求头选定当前应用;`base_system` 注册表 + `f_system_id` 系统级隔离(模块/菜单/授权按系统切分)。**本期只做注册表 + 路由 + 隔离**,不做 `SystemController` CRUD。见 §4.1。
|
||
- **数据库**:复用 JNPF v7.0 官方 `base_*` DDL(8 张表,含多应用注册表 `base_system`)+ 业务表;进程内 pglite-rs(真实 PostgreSQL 语义),后续可换真实 PG。
|
||
|
||
### 2.2 本期不做(明确暂缓,别偷跑)
|
||
|
||
| 项 | 官方对应 | 原因 |
|
||
|---|---|---|
|
||
| 多租户 | `7.0-jnpf-java-tenant` / `f_tenant_id` | 单租户固定 `'0'`,暂不切分 |
|
||
| SSO / OAuth | `jnpf-oauth`(`jnpf-oauth-api/-biz/-controller/-entity`) | 用内部账号密码会话 token,不做第三方登录 |
|
||
| 微服务拆分 | `jnpf-public/jnpf-provider` | 单进程 monolith,不做 RPC/服务注册 |
|
||
| 低代码引擎 | `jnpf-flowable` / visualdev / 代码生成 | **元数据引擎 + 动态 CRUD 已迁**(P2-a/P2-b,见 PLAN.md §P2);**流程引擎(flowable)与代码生成器仍不碰** |
|
||
| 文件 / 消息 / AI / 调度 / 扩展 / 应用中心 | `jnpf-file` / `jnpf-message` / `jnpf-ai` / `jnpf-scheduletask` / `jnpf-extend` / `jnpf-app` | 后续按需,不在 v1;注意 Java 前端可能依赖文件上传等,Phase 2 验证时确认 |
|
||
| 按钮/列/表单/数据范围级授权 | `base_module_button/_column/_form/_data` | 仅做 `item_type='module'`(菜单)一类 |
|
||
|
||
---
|
||
|
||
## 3. JNPF v7.0 模块取舍(java-boot 模块映射)
|
||
|
||
`7.0-jnpf-java-boot` 是 Maven 多模块,顶层模块如下(已逐模块判定):
|
||
|
||
| java-boot 模块 | 决策 | 映射到本后端 |
|
||
|---|---|---|
|
||
| `jnpf-system`(`jnpf-system-biz/-controller/-entity`) | ✅ 移植 | 平台层:`base_user`/`base_role`/`base_organize`/`base_module` 管理及面 B 的 `User`/`Role`/`Organize`/`Menu` |
|
||
| `jnpf-permission` | ✅ 移植 | 平台层:授权写入 + 面 B `Authority/Data`、`Users`、`Role`、`Organize/AsyncList`、`Menu/ModuleBySystem` |
|
||
| `jnpf-admin`(聚合入口 + AOP/filter) | 🟡 部分 | 登录/`CurrentUser`/`AuthFilter` 已映射为面 A/面 B;tenant 过滤、多数据源、sharding 跳过 |
|
||
| `jnpf-public/jnpf-common-all` | 🟡 部分 | `base_*` 实体与 DDL 已对齐;其余 common 工具用 Rust 自有实现 |
|
||
| `jnpf-public/jnpf-generater-base` | ⛔ 跳过 | 代码生成器(低代码),不在 v1 |
|
||
| `jnpf-public/jnpf-provider` | ⛔ 跳过 | RPC/微服务 |
|
||
| `jnpf-oauth` | ⛔ 跳过 | SSO(§2.2) |
|
||
| `7.0-jnpf-java-tenant`(独立仓) | ⛔ 跳过 | 多租户(§2.2) |
|
||
| `jnpf-flowable` | ⛔ 暂不 | 工作流/低代码 |
|
||
| `jnpf-ai`(`jnpf-ai-v2/-v3`) | ⏸ 暂缓 | AI 能力后续按需 |
|
||
| `jnpf-file` | ⏸ 暂缓 | 文件上传/预览;Phase 2 确认 Java 前端是否依赖 |
|
||
| `jnpf-message` / `jnpf-scheduletask` / `jnpf-extend` / `jnpf-app` | ⏸ 暂缓 | 消息/定时/扩展/应用中心 |
|
||
| `jnpf-example` / `jnpf-exception` | ⛔ 不迁 | 示例 / 异常处理(Rust 自有) |
|
||
|
||
**DDL 真源**:`jnpf/7.0-jnpf-database` 仓的 `PostgreSQL/JNPF-PostgreSQL.sql`(经 git-mirror 取)。
|
||
脚手架已带 `docs/ddl/base_ddl_raw.sql` 与对齐后的 `db/schema.sql`(12 表:8 `base_*` + 4 业务)。
|
||
|
||
---
|
||
|
||
## 4. 架构
|
||
|
||
```
|
||
ssw-platform/
|
||
├── Cargo.toml # workspace 根;members = ["src/backend", "crates/*", "packs/*"]
|
||
├── rust-toolchain.toml # 🔴 全仓锁 1.95.0(L3 动态库强依赖,见 PLAN.md §4.5)
|
||
├── crates/ # 【平台侧 crate】业务包不许依赖这里的任何东西
|
||
│ ├── sspf-contract/ # 契约类型:信封 / 码表 / EntitySpec / MenuSpec / UUID / 判别头
|
||
│ │ # 依赖只允许 serde/serde_json/uuid/http(AR4)
|
||
│ ├── sspf-sdk/ # 🔴 业务包唯一依赖:BusinessPack trait + Manifest
|
||
│ │ # 依赖只能是 sspf-contract(AR1)
|
||
│ ├── sspf-store/ # (P0-b)DB 抽象:pglite ⇄ 真实 PG
|
||
│ ├── sspf-lowcode/ # (P2)元数据引擎 + Rhai 沙箱
|
||
│ ├── sspf-plugin/ # (P3)业务包加载器:静态 / dylib / wasm
|
||
│ └── sspf-mcp/ # (P1)MCP 2.0 元工具层
|
||
├── packs/ # 【业务包】整目录可搬(jnpf ⇄ sspf 双向)
|
||
│ └── asset/ # 样板:Cargo.toml + pack.toml + src/lib.rs
|
||
│ # 只依赖 sspf-sdk(AR2)⇒ 可独立 cargo build
|
||
├── src/
|
||
│ ├── backend/ # 内核 crate(package 名仍是 ssw-platform)
|
||
│ │ ├── Cargo.toml
|
||
│ │ ├── src/
|
||
│ │ │ ├── main.rs # 启动装配
|
||
│ │ │ ├── lib.rs # pub mod platform / modules / routes
|
||
│ │ │ ├── platform/ # 【平台层】契约实现,加业务模块一个字都不改
|
||
│ │ │ │ ├── cipher.rs # md5→AES-256-ECB(key=md5("EY8WePvjM5GGwQzn") 的 32 ASCII 字节)→hex
|
||
│ │ │ │ ├── envelope.rs# ActionResult{code,msg,data}
|
||
│ │ │ │ ├── auth.rs # 登录 / CurrentUser / 登录守卫(面 A/面 B 共用)
|
||
│ │ │ │ ├── face_b.rs # 【面 B】基线平台形状:判别头 / PcUserVO / PageListVO / 点权限守卫
|
||
│ │ │ │ │ # (P0 由 jnpf.rs 改名:内部标识必须剥离,前端不依赖)
|
||
│ │ │ │ ├── permission.rs # 四源合并 + 管理员短路 + 菜单树(全部按 f_system_id 隔离)
|
||
│ │ │ │ ├── seed.rs # ensureBase(含 ensure_systems)+ firstSeed
|
||
│ │ │ │ ├── system.rs # 【多应用】App-Code 头 → SystemRef{id,code};base_system 注册表
|
||
│ │ │ │ ├── sys.rs # 5 组 base_* 显式 handler
|
||
│ │ │ │ ├── crud.rs # spec 驱动通用 CRUD 引擎(不含业务表名/app_code)
|
||
│ │ │ │ ├── test_support.rs # 测试用**进程级共享** pglite(pglite 每进程只能开一次)
|
||
│ │ │ │ └── ...(config/db/ids/session/state/entity/menu/guard/mod)
|
||
│ │ │ ├── modules/ # 【业务层】加业务模块只改这里
|
||
│ │ │ │ ├── mod.rs # ALL_SPECS / ALL_MENUS / ALL_ROUTES / router() 汇总
|
||
│ │ │ │ ├── demo.rs / shop.rs / books.rs # 模板模块(不进生产)
|
||
│ │ │ │ ├── asset.rs # 🔴 真实业务:DataResource(数据资源,本体对齐)
|
||
│ │ │ │ └── <app>.rs # 尚数网业务模块(Phase 3 起)
|
||
│ │ │ ├── routes.rs # 路由装配(平台 27 条 + 面 B 14 条 + merge 业务路由)
|
||
│ │ │ └── bootstrap.rs # 【装配根】唯一同时认识两层;把业务菜单注入种子
|
||
│ │ ├── db/schema.sql # 完整 DDL(base_* 8 + 业务 N)
|
||
│ │ └── data/ # 运行期数据(gitignore)
|
||
│ └── frontend/ # 本期暂不动;沿用 Java 版前端/移动端
|
||
├── scripts/ # 六道闸门 + cipher 自证(见 §6)
|
||
└── docs/ # contract / runbook / decisions / known-limitations / ddl
|
||
```
|
||
|
||
**核心不变量**:
|
||
- **平台层 / 业务层分离**:加业务模块只碰 `src/modules/`(新文件 + `mod.rs` 登记),平台层一个字不改。
|
||
两层唯一接头点是 `bootstrap.rs`。
|
||
- **双面契约同一进程**:面 A(ssw 形状,冻结)+ 面 B(官方 JNPF 形状)。判别头 = `Vue-Version: 3`(官方前端必带、本仓前端唯一不发)。
|
||
共用两条路由按头分流:`GET /api/oauth/CurrentUser`、`PUT /api/permission/Authority/Data/{objectId}`。
|
||
- **两套权限判据并存**:面 A 按菜单路径(`f_url_address`);面 B 按点权限编码(`f_en_code`)。两套数据源不同,别混。
|
||
|
||
### 4.1 多应用(app)模型 —— 本期 MVP
|
||
|
||
- **当前应用由 `App-Code` 请求头选定**(官方 JNPF 做法):
|
||
`system::app_code_of(&headers)` → `resolve_system(&db, app_code)` → `SystemRef { id, code }`。
|
||
头缺失 / 未知应用 / 查库失败 **一律回落主系统**(绝不 panic,也不 500)。
|
||
- **注册表 = `base_system`**:`f_en_code` 存 App-Code,`f_id` 即 systemId,`f_full_name` 是显示名,`f_is_main` 标记主系统。
|
||
列定义与官方 `database/PostgreSQL/JNPF-PostgreSQL.sql:4243` **逐字一致**(24 列)。
|
||
种子(`ensure_systems`,幂等):主系统 `mainSystem`(= 官方 `JnpfConst.MAIN_SYSTEM_CODE`,`f_is_main=1`;5 条内置菜单 + 全部业务菜单)+ `app-b`(**故意无菜单**,专门用来验证隔离)。
|
||
- **隔离口径**:所有菜单 / 授权查询都带 `f_system_id`
|
||
(`build_menu_list` / `load_menus` / `has_module` / `has_en_code_permission`)。
|
||
`MenuSpec.system_en_code` 声明菜单归属哪个应用,种子经 `system_id_of()` 解析成 `f_system_id` 落库。
|
||
- **`CurrentUser` / `userInfo` 的系统字段**(`currentSystemId` / `systemId` / `systemCode`)由 `App-Code` 解析,**不再硬编码**;面 A、面 B 同一口径。
|
||
- 🔴 **多应用 ≠ 多租户**:应用(app:`base_system` + `f_system_id`)是「同一租户下的多个子系统」;
|
||
租户(`f_tenant_id`)是数据隔离维度,本期仍固定 `'0'`(§2.2)。
|
||
- 本期**不做**:`SystemController` 增删改查端点、应用级授权包、前端跨应用切换 UI。
|
||
- 钉住它的测试:`platform::system::tests::registry_resolution_and_menu_isolation`
|
||
(默认/未知头 → 主系统;`app-b` → 正确解析;两系统的菜单树互不可见)。
|
||
|
||
---
|
||
|
||
## 5. 契约与数据库「兼容 Java 版」策略(本期核心)
|
||
|
||
兼容不靠"重写一套一样的东西",而靠**三件被刻意锁死、三方共用的契约**(Rust ⇄ NestJS ⇄ 官方 Java):
|
||
|
||
1. **`base_*` 表名/列名逐字对齐官方 DDL**(含两个故意不修正的官方陷阱:
|
||
`base_role_relation` 用户 id 在 `f_object_id`;组织/岗位关系在另一张 `base_user_relation`)。
|
||
2. **口令 cipher**:`md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 32 个 ASCII 字节)→ hex。
|
||
检验向量:`encryptPassword('123456')` ==
|
||
`d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`。
|
||
3. **响应信封 + 主键 + JSON 键名**:`{code,msg,data}`(业务失败也 HTTP 200);主键 36 位 UUID v4 `varchar(50)`;
|
||
JSON 键名 = 列名去 `f_` 前缀后 camelCase。
|
||
|
||
### 5.1 官方 DDL 行号表(`check-citations.sh` 的 CIT3 对账源)
|
||
|
||
官方结构 DDL = `~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql`
|
||
(公司 GitLab `platform/jnpf-platform/7.0` 的 `database/PostgreSQL/`,**13227 行 / 331 张表**)。
|
||
本仓只用到下面 8 张 + 4 张业务表;行号漂移(官方增删表)会被 CIT3 当场抓到:
|
||
|
||
| 表 | 官方 DDL 行 | 用途 |
|
||
|---|---|---|
|
||
| `base_authorize` | 812 | 授权(角色/用户/岗位 × 菜单/按钮) |
|
||
| `base_module` | 2209 | 菜单/模块(`f_system_id` 多应用隔离就在这张表) |
|
||
| `base_organize` | 3178 | 组织机构树 |
|
||
| `base_role` | 3686 | 角色 |
|
||
| `base_role_relation` | 3729 | 角色—用户关系(**用户 id 在 `f_object_id`**) |
|
||
| `base_system` | 4243 | 系统应用(多应用注册表,24 列,`f_is_main` 标主系统) |
|
||
| `base_user` | 4479 | 用户 |
|
||
| `base_user_relation` | 4707 | 用户—组织/岗位关系 |
|
||
|
||
由此得到三条兼容通道:
|
||
|
||
- **数据库兼容**:Rust 后端读写与 Java 版**同一套 `base_*` 表**(同连一个 PG,或 `pg_dump --data-only` 迁移)。列名差一个字符就导不进 —— 所以严禁自创表名/列名。
|
||
- **前端/移动端兼容**:Java 前端发官方形状请求(带 `Vue-Version: 3`)→ 命中**面 B** → 返回官方 `PageListVO`/`PcUserVO` 等形状 → 前端零改。
|
||
- **鉴权兼容**:内部账号密码登录链路(同一把 cipher)→ Java 前端登录/CurrentUser 直连 Rust 后端。
|
||
|
||
🔴 **面 B 未登录返 `code=602`**(不是 600):官方前端只对 `601`/`602` 清 token,返 600 会卡死不跳登录页。面 A 仍是 600(冻结)。
|
||
|
||
---
|
||
|
||
## 6. 验收闸门(十二道,缺一不可)
|
||
|
||
| 类别 | 脚本 | 测什么 | 当前状态 |
|
||
|---|---|---|---|
|
||
| 静态 | `scripts/check-module.sh` | 业务模块 10 接触点齐不齐(**本仓后端-only ⇒ 前端 4 处打 `⏭`,仍计入条数**) | 114/114 已绿 |
|
||
| 静态 | `scripts/check-boundary.sh` | 分层红线 CP1–CP6(平台层不许有业务知识) | 已绿(11/11) |
|
||
| 静态 | `scripts/check-contract.sh` | 契约端点表 ↔ 代码真实路由(CC2–CC10,含官方端点台账 CC10) | 已绿(10/10) |
|
||
| 静态 | `scripts/check-citations.sh` | 文档引文 `路径:行号` 逐条核对 | 4/4 已绿(192 条引文全解析;CIT3 依赖官方 DDL,缺失则 `⏭`) |
|
||
| **静态·架构** | **`scripts/check-arch.sh`** | **crate 依赖纪律 AR1–AR7 + 内存红线 MEM1–MEM2(`--self-test` 反自证)** | **9/9 已绿** |
|
||
| **静态·命名** | **`scripts/check-naming.sh`** | **内部标识剥离 NM1–NM3 阻断 + NM4 注释量化(`--strict` 可升级)** | **3/0 已绿(69 处注释技术债)** |
|
||
| 契约尺子·面 A | `scripts/perm-smoke.sh` | 43 条(面 A 契约闭环 32 + 真实业务模块 asset 9 + 多应用 `App-Code` 路由 2) | 已绿 |
|
||
| 契约尺子·面 B | `scripts/perm-smoke-jnpf.sh` | 23 条(官方形状 18 + 多应用 `App-Code` 路由 1 + 用户 CRUD 4,诚实记 SKIP) | **23/23 已绿** |
|
||
| **契约尺子·MCP** | **`scripts/mcp-smoke.sh`** | **48 条:4 元工具上限 / 分层加载 / 自提示 / 业务失败不误报协议错 / 结构注入防护 / 写工具校验 / 授权闭环 / prompts 模板 / stdout 纯 NDJSON + 阶段 B 低代码动态 CRUD(seed → 默认 dryRun 不落库 → 真写 → 查证 → 子表差集 → 删除 → 建表幂等 / 口令列不外泄)** | **48/48 已绿** |
|
||
| **契约尺子·低代码** | **`scripts/lowcode-smoke.sh`** | **15 条:真实样例解析 / 同构保序 / inline 校验 / 缺参拦截 / 建表 DDL 规则(类型映射·复合主键·逻辑删除列·系统列视图类型)+ 四条反自证** | **15/15 已绿** |
|
||
| **契约尺子·双后端** | **`scripts/baseline-smoke.sh`** | **10 条:基线适配器自动登录 / health 裸对象 / 形状归一化(list→menus、organize→organizeId、裁剪多余键)/ 不支持的 op 发请求前拦下** | **10/10 已绿** |
|
||
| **运行时·内存** | **`scripts/mem-budget.sh`** | **空载物理内存(vmmap `Physical footprint`)是否 ≤ 预算** | **8 MB / 40 MB 预算 已绿** |
|
||
|
||
🔴 期望值只有一处:`docs/contract.md` 附录 A(机器可读 `[ENDPOINT]` / `[OFFICIAL]` 等),由 `scripts/contract_expect.py` 解析。
|
||
每把尺子结尾比对「实际断言数 vs 契约登记数」,对不上即失败 —— 尺子不会被悄悄改弱。
|
||
**加任何业务模块 / 改任何契约 / 加任何 crate 依赖 / 改任何内部标识 / 加任何表,十二道闸门必须全绿才算完成。**
|
||
|
||
🔴 **`cargo test --workspace` 当前 550 条**(内核 + contract 13 + store 17 + sdk 2 + pack-asset 5 + mcp 52 + adapter-baseline 19 + lowcode 112 + 集成测试)——
|
||
拆 crate 后总数会变,**不许把断言数写死**,跑一遍看实际值。
|
||
|
||
cipher 自证(免 node):`./target/release/ssw-platform --enc 123456`。
|
||
|
||
---
|
||
|
||
## 7. 红线(摘要;细则见脚手架文档)
|
||
|
||
1. **契约优先于实现**:端点路径/入参/返回形状/错误码与官方/脚手架逐字一致;不确定先读源码,不凭印象。
|
||
2. **业务失败一律 HTTP 200 + `{code,msg,data}`**;唯一例外:未知路由 HTTP 404(body 仍是信封)。**鉴权失败也是 200**(`600`/`403`)。
|
||
3. **`base_*` 表名/列名逐字对齐官方 DDL**,严禁自创(迁移靠 `--data-only`,差一字导不进)。
|
||
4. **四源权限合并 + 管理员短路 + 未映射放行**:管理员在 SQL 前短路;权限 = 直授+角色+组织+岗位;菜单未映射到 `base_module` ⇒ 放行(静默,必须有测试钉住)。
|
||
5. **口令不得外泄**:库内存 `md5(明文)`;响应手工挑字段(去 `password`);密文只在请求体出现。
|
||
6. **平台层 / 业务层分离**:加模块只碰业务层;接线只在 `bootstrap.rs`。由 `check-boundary.sh` 钉死。
|
||
7. **判别头 `Vue-Version: 3`**:本仓前端禁止发该头(发了面 A 误判成面 B);面 B 必带。
|
||
8. **两套权限判据并存别混**:面 A 按菜单路径,面 B 按 `f_en_code`;同一用户两面可能一通一拒,不是 bug。
|
||
9. **暂缓项不偷跑**:tenant / SSO / 微服务 / 流程引擎 / 代码生成 不在本期(§2.2)。低代码**元数据 + 动态 CRUD** 已落地(P2-a/P2-b),但读 release / 单据号 / 乐观锁仍未做。
|
||
10. **同一文件多 Edit 必须串行 + 改完 grep 复核**。
|
||
11. **低代码表必须「建表即回写」**:`schema.table.create`(或种子)建完表要回写 `f_tables_data`,否则 CRUD 层在模型里找不到 `f_delete_mark` ⇒ 逻辑删除直接报 `LOGICAL_DELETE_UNSUPPORTED`。
|
||
12. **单租户也不省 `f_tenant_id`**:值恒为 `"0"`,但列 `NOT NULL` 且参与复合主键 `(f_id, f_tenant_id)`;建表/写入都必须带这一列。
|
||
13. **写工具默认 `dryRun=true`**:新增写工具不传 `dryRun` 就是演练。这不只是防误写 —— 也是 AI 先看后写的唯一抓手。
|
||
|
||
---
|
||
|
||
## 8. 实施路线图
|
||
|
||
| 阶段 | 目标 | 出口判据 |
|
||
|---|---|---|
|
||
| **Phase 0 — 实例化** | 把脚手架本体(非技能噪音)rsync 进本仓库根的 `src/` + `scripts/` + `Cargo.toml` + `.env.example` + `.gitignore`;`cp .env.example .env` | 目录齐、可 `./run.sh install` |
|
||
| **Phase 1 — 基线门** | 编译 + 跑通六道闸门(默认全绿) | ✅ 已过:`cargo test` 221(lib 98 + 集成 123)、check-module 114/114、check-boundary 11/11、check-contract 10/10、check-citations 4/4、perm-smoke 43/43、perm-smoke-jnpf 23/23 |
|
||
| **Phase 1.5 — 多应用 MVP** | `base_system` 注册表 + `App-Code` 路由 + `f_system_id` 隔离(§4.1) | ✅ 已落地:`registry_resolution_and_menu_isolation` 绿;`app-b` 与主系统菜单互不可见 |
|
||
| **Phase 2 — 兼容验证** | 用尚数网 Java 前端/移动端实连面 B,跑登录/`CurrentUser`/用户/角色/机构/菜单/授权闭环;与 Java 版做一次面 B diff | Java 前端可登录、菜单/授权行为一致 |
|
||
| **Phase 3 — 业务模块** | 按 `HOWTO_MODULE.md` 加尚数网业务模块(只碰 `modules/`) | ✅ 首个已落地:`asset/DataResource`(数据资源,字段对齐公司本体);每模块 check-module + 六闸门全绿 |
|
||
| **Phase 4 —(后续)** | 按需补文件/消息/AI;评估 SSO/租户/微服务;稳定后切真实 PG | 按业务优先级排期 |
|
||
|
||
Phase 0 复制清单(**不要** `cp -R` 整个技能目录,会灌入技能噪音):
|
||
```bash
|
||
SKILL=~/Desktop/workspace/skills/ssw-jnpf-lite-rust
|
||
rsync -a --exclude node_modules --exclude dist --exclude target --exclude data --exclude .DS_Store \
|
||
"$SKILL"/src "$SKILL"/scripts "$SKILL"/run.sh "$SKILL"/Cargo.toml \
|
||
"$SKILL"/.env.example "$SKILL"/.gitignore "$SKILL"/README.md \
|
||
"$SKILL"/HOWTO_MODULE.md "$SKILL"/PERMISSION.md "$SKILL"/MIGRATION.md \
|
||
"$SKILL"/JNPF_COMPAT_SURFACE.md "$SKILL"/JNPF_SOURCE_AUDIT.md \
|
||
"$SKILL"/docs "$PWD"/
|
||
cp .env.example .env && ./run.sh install && ./run.sh dev
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 命令速查
|
||
|
||
```bash
|
||
cargo build --release # 编译(workspace 根,含 crates/* 与 packs/*)
|
||
cargo test --workspace # 单测(当前 550 条)
|
||
bash run.sh dev # 起后端(30010) + 前端(5173)
|
||
bash scripts/perm-smoke.sh # 面 A 43 条
|
||
bash scripts/perm-smoke-jnpf.sh # 面 B 23 条
|
||
bash scripts/check-boundary.sh # 分层红线 CP1–CP6
|
||
bash scripts/check-contract.sh # 契约端点 ↔ 代码路由 对账
|
||
bash scripts/check-module.sh # 业务模块 10 接触点
|
||
bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR7 + 内存红线 MEM1–MEM2
|
||
bash scripts/check-arch.sh --self-test # 反自证:造违规必须被抓到
|
||
bash scripts/check-naming.sh # 内部标识剥离(NM1–NM3 阻断 / NM4 注释量化)
|
||
bash scripts/check-naming.sh --strict # 注释里的原厂名也算红(技术债清零时用)
|
||
bash scripts/mcp-smoke.sh # MCP 工具层契约 48 条(4 元工具 + 分层加载 + 授权闭环 + prompts + 低代码 CRUD)
|
||
bash scripts/lowcode-smoke.sh # 低代码 15 条(表单解析 + 校验 + 建表 DDL 规则 + 4 条反自证)
|
||
bash scripts/baseline-smoke.sh # 双后端契约 10 条(HTTP 适配器 + 形状归一化)
|
||
cargo build -p sspf-adapter-baseline --example probe # baseline-smoke 依赖的探针
|
||
bash scripts/mem-budget.sh # 空载内存实测(P0 出口判据,预算 40 MB)
|
||
cargo test -p sspf-pack-asset # 业务包独立可编(业务包剥离的硬证据)
|
||
./target/release/ssw-platform --mcp # 起 MCP stdio 服务(供 AI 直接驱动,见 docs/mcp.md)
|
||
./target/release/ssw-platform --enc 123456 # cipher 自证
|
||
```
|
||
|
||
> 本机 curl 走系统代理,测 localhost 必须加 `--noproxy '*'`。
|
||
> 🔴 本机沙箱**禁止 `ps` / `top`**(Operation not permitted)⇒ 内存只能用 `vmmap`(`mem-budget.sh` 已处理)。
|
||
> 🔴 本机 rustup 下载受代理限速(~6 MB 卡死)⇒ 不要随手 `rustup update`,工具链以 `rust-toolchain.toml` 为准。
|
||
|
||
---
|
||
|
||
## 10. 待确认决策(开工前或 Phase 2 前定)
|
||
|
||
1. ~~**命名**~~ ✅ **已定**:项目 / crate / bin 一律 `ssw-platform`(`Cargo.toml` + 命令速查已改;脚本里的 `ssw-jnpf-lite-rust` 只剩「脚手架参照物」语义)。
|
||
2. **数据库形态**:MVP 用 pglite-rs 进程内(零服务);稳定期是否切真实 PostgreSQL?数据迁移/双写路径?
|
||
3. **Java 版实际契约差异**:拿尚数网 Java 版实跑一次面 B diff,确认 `18/18` 是否覆盖 Java 前端**全部必需**端点(mirror 只有上游 JNPF,缺公司 fork 定制)。若有缺口,记 `partial`/`absent` 排期补。
|
||
4. **首批业务模块**:尚数网首批要落哪些业务模块?(demo/shop/books 仅作模板,不进生产)
|
||
5. **文件/预览依赖**:Java 前端是否依赖 `jnpf-file` 的文件上传/预览?若依赖,Phase 2 需先补最小文件面 B。
|
||
6. **官方源码位置(`check-citations` 的前置)**:引文校验要读官方源码,默认根 = `~/Desktop/workspace/jnpf`。
|
||
已就位:`jnpf-java-boot` / `jnpf-web-apps-main` / `jnpf-common`(均从内网 Gitea 浅克隆)。
|
||
**缺**:`jnpf-database`(Gitea 上该 mirror 已 404)⇒ CIT3「DDL 行号表」只能 `⏭`。
|
||
拿到 `PostgreSQL/JNPF-PostgreSQL.sql` 后放进 `~/Desktop/workspace/jnpf/jnpf-database/` 即可转真校验。
|
||
|
||
---
|
||
|
||
## 11. 记忆约定
|
||
|
||
- 踩坑与长 traceback → `docs/<子系统>/<topic>.md`。
|
||
- 工作日志 → `.workbuddy/memory/YYYY-MM-DD.md`。
|
||
- 本文件只留「原则 + 决定 + 一句话摘要」;改代码后回头核对是否还成立。
|