docs: 同步批次 12 / 12.5 收尾(HANDOFF + HOWTO + CLAUDE + memory)

HANDOFF 记下加模块的真实成本(一条命令 + 一张产出表)、2 个真 bug、反自证结果;

HOWTO_MODULE 开头两节重写(旧手抄清单已过时);CLAUDE 两条核心不变量改写。
This commit is contained in:
admin committed 2026-11-01 23:04:57 +08:00
1 parent ce30c5b2f6
commit aa2447eec2
4 files changed
+959 -31

No files matched your search

+287
View File
@@ -395,3 +395,290 @@ HANDOFF §0-bis 与 §1 已更正,并补了批次 9/10 的逐批增量。
`fe-gap` 余下:`system` 55 / `permission` 26 / `systemData` 32 —— 从**有官方 `base_*` 表支撑**
的族里挑;`workFlow`(104) / `onlineDev`(101) / `aiCenter`(75) / `extend`(64) / `msgCenter`(50)
基本是「本仓没这个模块」⇒ **先确认产品边界再动手**,做也只是恒空 stub。
---
## 19:00 —— 批次 12 方向决策:「框架固定包 + 业务模块链接就好」
**用户诉求**(原话):「后台一个成熟的框架,然后用极简业务代码 + vue 前端。
能不能先把主要框架打成相对固定包,业务模块链接就好,快速打包/快速验证。放在 HANDOFF 下一轮优先做掉。」
⇒ 本轮**不做端点**,只做**方案 + 写进 HANDOFF**(批次 12),原批次 12 顺延为批次 13。
### 现状体检(实测,非推测)
| 事实 | 证据 |
|---|---|
| `packs/asset` **没被内核装载** | `routes.rs` 只有 1 处 `.merge(`(`modules::router()`);`sspf-sdk` 的 `BusinessPack` 方法只有 manifest/entities/menus/metadata/hooks —— **无 `routes()`** |
| 业务 spec **两份逐字拷贝** | `modules/asset.rs`(178 行)vs `packs/asset/src/lib.rs` |
| 两份拷贝**无比对闸门** | `check-arch.sh` 函数只有 ar1–ar7 + mem1 + mem2,**无 PACK1**(`packs/asset` 注释里写的「P3 加」至今没加) |
| 契约扫描器**只扫 `modules/*.rs`** | `check-contract-scan.py:369` 只遍历 `src/backend/src/modules/`(除 `mod.rs`)⇒ 包搬走 ⇒ 假漂移 |
| 业务表数**写死 52** | `crates/sspf-store/src/db.rs:1226,1233` ⇒ 加表必红(批次 9/10 各踩一次) |
| 业务 DDL **手抄** `schema.sql` | `schema.sql:879/888/897/920` |
| `main.rs::whitelist_self_check` **双向对账** spec↔DDL | 包表会被判「孤儿 DDL」⇒ 启动失败 |
| `src/frontend` **是空的** | 本仓后端-only(CLAUDE.md §2.2);前端在 `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework` |
### 🔴 闸门耗时实测(新增基线,之前没量过)
静态:`check-contract` **66.6s** 🔴最慢 / `check-module` 25.8s / `check-boundary` 7.2s /
`check-citations` 5.2s / `check-naming` 3.6s / `check-arch` 1.6s ⇒ **合计 ~110s**
运行时:`perm-smoke` 6.0s / `perm-smoke-jnpf` 4.8s / `baseline` 3.3s / `mcp` 2.9s(34+14 两段)/
`lowcode` 1.9s ⇒ **合计 ~19s**
⇒ **「快验证」瓶颈在静态闸门,不在起后端** ⇒ 批次 12 的提速目标是「改一个模块后静态 ≤15s」。
### 批次 12 的 4 项交付物
1. `sspf-sdk` 补 `fn routes(&self) -> &'static [PackRoute]`(默认空 ⇒ L0 零改动)
+ 新建 `crates/sspf-plugin`(依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json})。
🔴 **路由「声明」在 sdk(纯数据)、「注册」在内核(唯一认识 axum)** —— 业务包不许依赖 axum(AR2)。
2. `modules/asset.rs` 改 **re-export** `packs/asset` ⇒ 单一真源;补 **PACK1** 闸门
+ 新 **AR9**(平台层不许 `use sspf_pack_*`)。
3. 业务 DDL 跟着包走(`pack.toml` 的 `[[pack.tables]].ddl` 已预留)⇒ 不再手抄 `schema.sql`;
🔴 `sspf-store` 两处表数断言**去写死**;
🔴 `is_builtin_table`(`face_b.rs:12993` 取 `ddl_tables()`)会**把包表当内置表** ⇒ 要重新想。
4. 契约登记**自动生成**(`scripts/pack-sync.py` + BEGIN/END 标记)+ 扫描器**增量缓存**
+ 新增 `scripts/verify.sh`(一条命令跑完 build→静态→单测→尺子,打印耗时 Top3)。
### 明确不做(批次 12)
L3 dylib 动态库(PLAN.md §4.5 六条铁律是另一个量级)/ WASM 执行器 /
`pack export/import --format=baseline` 双向迁移。
🔴 依据 PLAN.md §4.6:「L2 是静态链接,L3 才是运行期 dlopen」「不要对外承诺什么都能热更」。
### 🔴 前端的处理(需产品确认)
本仓**没有前端**。vue 前端那条诉求的正确形态是:
**官方 JNPF monorepo 本身就是那个「固定包」**(业务方只写 `views/` + `api/` + 一行路由)。
若要「页面脚手架」,候选方案 = 仿 `new-pack.sh` 做 `new-page.sh`。
### 产出
`HANDOFF.md`:新增 §0-ter(下一轮做什么)、§0-bis 末尾(优先级改了 + 耗时基线表)、
§3 第 12 项 + 完整「批次 12」小节(4 交付物 / 7 护栏 / 5 验收判据 / 明确不做)、
§1 现状加「业务包目前是死的」。原批次 12 顺延为批次 13,**一字未改**。
---
## 19:40 —— 两阶段路线明确(用户澄清:不是让我去调试)
**用户原话**:「我重新说,不是让你去调试。我的意思是后续基于 官方 /rust 框架做开发,
分为 mvp阶段 和 规范集成开发 阶段,mvp阶段 用 ssw-jnpf-lite-rust 技能 来 开发 AI 怎么快怎么来,
业务框架定型后,迁移在标准jnpf框架集成开发(仅部份终端设备不佳考虑这个做后端)」
⚠️ **上一轮我理解错了**:以为「调试阶段」= 让我去调前端页面。
实际 = **开发流程分两阶段**。⇒ 重写了 §0-ter(上一版的「前端怎么办」已清理)。
### 两阶段路线
```
MVP 阶段(Rust 技能,AI 怎么快怎么来) → 规范集成阶段(迁标准 JNPF Java)
↘ 仅「部分终端设备不佳」的场景保留 Rust 后端
```
### 🔴 关键判断:分界线不是「时间」,是「契约忠实度」
官方端点台账(`docs/contract.md` 附录 A `[OFFICIAL]`,**379 条**)忠实度实测分布:
| status | 条数 | 集成时怎么办 |
|---|---|---|
| `implemented` | **338** | ✅ 直接搬 |
| `partial` | **27** | 🔴 **要还债** |
| `absent` | **7** | 集成时补(官方现成) |
| `oos` | **6** | 集成时按官方做 |
⇒ **27 条 partial 才是 MVP 阶段的债**,分三类:
- **① 临时欠 14 条**(导出/导入/测试连接/打印渲染 —— 恒 400 + 人话,本仓无文件服务/驱动/渲染引擎)
⇒ **删掉本仓实现、换官方的 ⇒ 几乎零成本**(假债)
- **② 形状欠 9 条**(`CurrentUser` 的 `sysConfigInfo` 返 `{}`、按钮级权限恒空、`permissionList` 粒度不同…)
⇒ **要真对齐**(真债)
- **③ 自造 4 条**(`f_en_code` 本仓自定占位、`deleteAllTable` 有意收窄…)⇒ **改成官方编码/语义**(真债)
⇒ **真债 = ②③ 共 13 条**,不是 27 条。**这 13 条就是「快」的精确边界。**
### 🔴 MVP 阶段四条红线(违反 = 集成时返工)
1. 业务表 `base_*` 列名不许自创(官方 DDL 13227 行 / 331 张表,本机 `~/Desktop/workspace/jnpf/jnpf-database/`)
2. 业务表 `f_tenant_id` 不许省(恒 `"0"`,但 `NOT NULL` + 参与复合主键 `(f_id, f_tenant_id)`)
3. 接口路径从第一天就用**官方形状**(面 B);面 A(`/api/ssw/...`)是本仓自造 ⇒ 集成时全作废
4. 返回形状宁可少字段,不许返错形状(官方前端遇缺字段会**静默降级**:按钮恒显、树空)
### ✅ 已到位(集成时直接搬)
`base_*` 逐字对齐 / cipher 逐字节等价(`MIGRATION.md` §7 换算)/ `ActionResult` 零改 /
`EntitySpec` ≈ 一个 Java 实体类 / 面 B 已按 `f_en_code` / **官方前端能零改直连本仓**。
### 🔴 前端(上一轮理解错的地方)
- 本仓 `src/frontend` **是空的**(后端-only);前端**全程**在官方 monorepo
`~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`。
- **官方路由是动态注册**:`router/routes/index.ts` 用
`import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)
⇒ **放文件进 `router/routes/modules/` 即注册,不改配置**。
⇒ 加一个业务页面 = **3 个文件**:`views/<模块>/index.vue` + `api/<模块>.ts` + `router/routes/modules/<模块>.ts`。
- ⚠️ `router/routes/modules/` 目录**官方自己也没建** ⇒ 目前是空的。
- ⚠️ **前端完全没闸门**(`check-module.sh` 的 4 个前端接触点全打 `⏭`)⇒ 批次 12 加 `--fe-root`。
### 批次 12 相应调整(写进 HANDOFF §3)
- 四项交付物不变,但**每项加「集成期友好性」要求**:
① 包路由只许官方形状(面 B);③ 包 DDL 按官方规范(`f_tenant_id` 必带、`baseline_table` 必填);
④ 前端 `new-page.sh` + `check-module.sh --fe-root`。
- 护栏从 7 条加到 **10 条**(新增:路径只许官方 / DDL 不许自造语义 / 前端三处一字不差)。
- 新增 **「集成期 checklist」(8 项)** —— MVP 阶段每加一个包就填一遍,填不完当场还债。
- 🔴 **性价比最高的一件事**:MVP 阶段**把 VO 字段清单抄全** ⇒ 直接消灭「形状欠」9 条的源头。
### 产出
`HANDOFF.md` §0-ter 整节重写为「两阶段开发路线」(含 partial 分布表 / 四条红线 / 已到位表 /
前端两阶段表);§0-bis 追加 19:39 补充;§3「批次 12」加集成期友好性要求 + 10 条护栏 +
集成期 checklist;清理上一轮的错误表述。
---
## 20:10 段 —— 🔴🔴 前端 MVP 方向定案:React 模板,「除了认证其它都留给集成阶段」
**用户指令**(原话):「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
**除了认证,其它都留给集成阶段**」。
⇒ 🔴 **这是对前两版理解的第三次修正**(先写「官方 vue 零改直连面 B」→ 后写「前端全程在官方 monorepo」
→ 现在才是对的)。**下次开工先复核这条再动手。**
### 🔴🔴 头号实测发现:两个技能的 React 前端**逐字节相同**
```bash
$ diff -rq skills/ssw-jnpf-lite-react/src/frontend/src skills/ssw-jnpf-lite-rust/src/frontend/src
# 无输出 ⇒ 完全一致
$ diff react/.../vite.config.ts rust/.../vite.config.ts
# 唯一差异:proxy 端口 30000(NestJS) vs 30010(Rust)
```
⇒ **前端是独立资产,与后端选 Rust 还是 NestJS 无关** ⇒ 换后端栈**前端一个字都不用动**。
⇒ 本仓选择:**MVP 后端 Rust(axum) + 前端用这套 React 模板**(直接从 `ssw-jnpf-lite-rust` 复制 `src/frontend`)。
⇒ React 技能的两把尺子可移植:`scripts/check-module.sh`(11 KB,9 接触点,`--all`/`--live`)、
`scripts/perm-smoke.sh`(22 条基线)。
### 🔴 认证为什么是唯一例外(证据链,逐条实测)
| 环节 | MVP(React) | 官方 | 结论 |
|---|---|---|---|
| 登录端点 | `POST /api/oauth/Login` (form-urlencoded) | `jnpf-web-apps-main/src/api/core/auth.ts`:`Api.Login='/api/oauth/Login'` + `ContentTypeEnum.FORM_URLENCODED` | ✅ 一字不差 |
| 登录参数 | `account`/`password`(hex)/`grant_type=password` | `AuthApi.LoginParams` 同三字段 | ✅ 一字不差 |
| 口令密文 | `cipher.ts` md5→AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")`)→hex | 官方 `DesUtil`+`SecurityProperties` | ✅ 逐字节等价 |
| 返回 | `{token,expiresIn,tokenTypeName}` | 同形 | ✅ |
| 登出码 | 600/601/602 → 清 token 跳 login | 官方 `ResultEnum.TOKEN_ERROR/TOKEN_LOGGED/TOKEN_TIMEOUT` | ✅ 1:1 |
| 信封 | `ActionResult{code,msg,data}` | 官方 `transformResponseHook` 取 `{code,msg}`,`code===ResultEnum.SUCCESS` 才过 | ✅ 1:1 |
| 请求头 | `App-Code` / `Jnpf-Origin: pc` | 官方多 `Vue-Version: 3` + `K1`(RSA 加密的 aesKey) | ⚠️ MVP 少 K1(无 body 级 AES) |
⇒ **认证层 MVP 就照官方契约写 ⇒ 集成时几乎零改**,只需补 `K1` 头 + body 级 `useCipher`。
### 「除了认证」的具体边界
- **MVP 做**:#1~#5(后端 entity/service/controller/module/app.module)+ #6~#7(前端 `api/*.ts` 薄壳 + `views/*.tsx` 原型)
+ **认证全套**(登录页 / 会话 / cipher / 请求层)。
- **集成期做**:#8/#9 的官方等价物(jweb 按菜单自动注册路由、菜单挂载)+ 权限配置 UI + 低代码表单 + 数据建模页 + 官方 Vue 三件套。
- ⇒ 官方 vue **本批完全不碰**。
### 本轮改动
- `HANDOFF.md` §0-ter:ASCII 路线图前端行改为「React 模板(AI 友好薄壳)」+
「🔴 前端在两阶段分别是什么」整节重写(对比表 + 认证证据链表 + 两技能 diff 实测 + 9 接触点对照表)。
- `HANDOFF.md` §3 批次 12 ④:前端交付物校准为 **React 三件套** `new-page.sh` + **移植** React 技能的 `check-module.sh`;
「明确不做」改为「官方 Vue 脚手架是集成期的事」。
- `HANDOFF.md` §3 护栏表第 10 条、§0-bis 20:10 补充段、HANDOFF 顶部「更新于」同步。
- 🔴 **顺手纠正的路径错误**:官方前端实际业务代码在
`~/Desktop/workspace/jnpf/jnpf-web-apps-main`(其 `src/api/request.ts` = `defHttp` 定义处,
164 行,`transformResponseHook` + `addRequestInterceptor` 三个头 + `K1`),
**不是** `~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework`(那是前端框架,无 defHttp)。
⇒ 集成期做 `--fe-root` 时要指对目录。
---
## 2026-11-01 晚:批次 12 收尾(前端三件套 + 计时假数据纠正)
### 🔴 最重要的发现:过去那张「闸门耗时表」大半是**执行环境的错**
沙箱/助手 bash 会把 `grep` `sed` `cat` `wc` 换成**转发壳**
(PATH 指向 `…/shim/brokered-bin/<命令>`,**每次启动 ≈0.19s**),
经 `BASH_ENV` 注入每个 bash 子进程。本仓闸门是「几百次 grep」的形态 ⇒ 被逐条累加。
| 闸门 | 旧数字(壳环境) | 普通终端 | 倍数 |
|---|---|---|---|
| check-contract | 66.6s | **3.2s** | 21× |
| check-module | 25.8s | **1.4s** | 18× |
| check-boundary | 7.2s | **1.5s** | 4.8× |
| check-citations | 5.2s | **4.0s** | 1.3× |
⇒ 教训已落进代码:`verify.sh` 现在先探测 `command -v grep` 是否落在 `*/shim/*`,
命中就打印告警「下面的耗时被放大数倍,别用来判断闸门快不快」。
**耗时不标注环境 = 假数据**。判断真实耗时要 `env -u BASH_ENV PATH=/usr/local/bin:/usr/bin:/bin:…`。
### 真·算法优化(与 shim 无关,换机器也有效)
1. `check-contract-scan.py` 新增 `_fn_positions()`:原来「查一个 handler 就在**整份文件**跑一遍
`re.search`」(362 次,1.4s)⇒ 改成每份文件只扫一遍建 `名字→位置` 表 ⇒ 1.4s → 0.15s。
2. `check-citations-scan.py` 新增 `_lookups()`:原来「每条引文遍历该根下**全部文件**做
`rel.endswith`」⇒ 实测 **1008 万次 endswith**(1.7s)⇒ 改成后缀/基名倒排表,O(1)。
3. `verify.sh` 的 `now()` 从「每步 3 次 python3」改成 `date +%s%N` + bash 整数运算
⇒ 8 步省 ≈2.9s(这 2.9s 不属于任何一步,却计进总耗时 ⇒ 会让人误判闸门慢)。
4. `self_test` 里第一跑 `analyze` 复用 `code_snapshot`(原来白扫一次全仓 0.4s)。
**结果**:`verify.sh --fast` 23.1s → **≈15s**(14.6/14.7/15.2/15.5 四次),`--lib` 23.5s,全绿。
### 前端三件套(批次 12 唯一还没做的一环)
- `src/frontend/` 从 `ssw-jnpf-lite-react` 只复脚手架本体(23 文件,不含技能文档)。
- `scripts/new-page.sh <app> <Entity>` + `scripts/new-page-gen.py`:真源 = 契约 `[MODULE]`
(urlAddress/apiFile/menuId→fullName)+ 表 DDL 列(自动滤平台列)。**不猜**,契约没登记就拒绝。
- 已生成 `asset/DataResource` 三件套(api/dataresource.ts + views/DataResource.tsx + App.tsx 路由)。
- 🔴 **两个坑**:① vite proxy 模板指 NestJS `:30000`,本仓 Rust 后端是 **`:30010`**(否则前端全 502,
表现成 Network Error,最易误判成跨域);② api 文件名 = `lower(Entity)` ⇒ `dataresource.ts`
**全小写**,改约定必须同时改尺子。
- `check-module.sh` 前端接触点从 `⏭` 变真检查 ⇒ 断言 **114 → 123**,契约 `[RULER]` 已同步
(尺子自证会逼你显式登记新条数,这就是它该有的作用)。
- 验证:`npm install`(98 包) + `tsc --noEmit` rc=0 + `vite build` 成功(307KB)。
- **仍未做**:前端没有运行时闸门(刻意不进 `verify.sh`,零 node 依赖是它的定位);
`new-pack.sh` 没做(后端加包仍手写 3 个文件)。
---
## 2026-11-01 夜:批次 12.5 —— 加包变一条命令,漏接变直接报错
### 问题
批次 12 把 spec 搬进包之后,加模块仍要手抄 5 个后端文件 + 改 4 处内核登记。
其中两类漏接**不报错**:漏 `merge` ⇒ 面 B 静默 404;漏 `ALL_MENUS` ⇒ 菜单不种 ⇒ 守卫
查不到菜单 ⇒ **越权放行**。
### 做法:把「内核怎么知道有这个包」从手写改成生成
- 统一包出口约定:每个包导出 `pub struct Pack` + `pub const DDLS: &[(&str,&str)]`
⇒ 生成器只需知道「目录名 + crate 名」。
- `sspf_plugin::load_static()`:manifest 解析 + `PackSource` + `merge` 收进插件层
⇒ `bootstrap.rs::load_packs()` 只剩一行。
- `scripts/pack-sync.py` 现在生成**四处**:`packs_gen.rs`(整文件)、
`modules/mod.rs` 五段(`// >>>GEN:` 标记)、`Cargo.toml` 的 `# >>>GEN:PACK_DEPS`、
`contract.md` 三段。`--check` 覆盖全部四处。
- 🔴 面 A 端点也纳入生成(`[ENDPOINT]`)—— 否则新模块的 3 条面 A 没人登记,
CC2 立刻红「契约 382 / 代码 385」。
- `scripts/new-pack.sh` + `new-pack-gen.py`:一条命令生成 5 个后端文件,
跑 pack-sync,可选 `new-page.sh`;`[RULER]` 条数**实跑 check-module 后自动登记**
(只允许变大,变小=有人删断言 ⇒ 拒绝)。
### 抓到并修掉的 2 个真 bug(都是「加第二个包」才显形)
1. 🔴 `check-contract-scan.py::guard_of_module_with_pack_fallback` 原来
`for pkg in sorted(pack_orig)` 取**第一个包** ⇒ 有 asset+probe 时 probe 的面 A 守卫
被推成 `asset/DataResource` ⇒ **CC6 假飘移 3 条**(人会去改对的契约)。
改成按 `app` 精确匹配,查不到返回「推不出」。
2. 🔴 加包误报 3 个单测(`asset_pack_loads` / `pack_router…` / `health == 52`)——
全是写死计数的**假闸门**。改成结构性断言(每实体:有 DDL + 有菜单 + 3 条路由;
health 表数 = `ddl_tables().len() + packs.ddls.len()`)。
### 验证(在 `/tmp` 仓库副本里跑,避免污染工作区)
`new-pack.sh probe Widget ... --with-frontend` ⇒ 写 5+3 个文件 + 5 处生成位置;
`cargo build` ✅ 3.7s;`cargo test -p sspf-pack-probe` 13 ✅;`ssw-platform --lib` 102 ✅;
`pack-sync --check` 幂等 ✅;`verify.sh --fast` 全绿 **17.2s**。
反自证:删 `packs_gen.rs` 的 probe 块 / 删 `mod.rs` 的 `probe::WIDGET_MENU`
⇒ `--check` 都 rc=1 并指名文件。
### 教训
**「生成物 + `--check`」是治「漏一处就静默」的通用解**:不是靠文档提醒,是让漏接变成红。
前提是生成段有稳定标记、且 `--check` 放在 `verify.sh` 第一步(否则别的闸门会先报一串假飘移)。
+8 -2
View File
@@ -136,8 +136,14 @@ ssw-platform/
```
**核心不变量**:
- **平台层 / 业务层分离**:加业务模块只碰 `src/modules/`(新文件 + `mod.rs` 登记),平台层一个字不改。
两层唯一接头点是 `bootstrap.rs`。
- **平台层 / 业务层分离**:加业务模块**一条命令**
(`bash scripts/new-pack.sh <app> <Entity> --name "…" --columns "a:TYPE"`),平台层一个字不改。
两层唯一接头点是 `bootstrap.rs`,而它读的是**生成**的包清单 `src/backend/src/packs_gen.rs`
(真源是 `packs/*`)。
- **四处内核接线是生成的**(`packs_gen.rs` / `modules/mod.rs` 五段 / `Cargo.toml` 依赖段 /
`contract.md` 三段),由 `scripts/pack-sync.py` 从 `packs/*` + `modules/*.rs` 推出。
**手改会被覆盖**,而 `verify.sh` 第一步 `pack-sync.py --check` 会把「忘了同步」判红
—— 因为漏同步的后果是**静默 404 / 越权放行**,不是编译错误。
- **双面契约同一进程**:面 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`)。两套数据源不同,别混。
+623 -5
View File
@@ -1,6 +1,8 @@
# HANDOFF —— 交给下一个 session 的现场交接
> 更新于 2026-11-01(面 B 批次 11 收尾)。**开工先读这一页**(尤其 §0-bis 缺口全景),再读 `CLAUDE.md`(硬约定),
> 更新于 2026-11-01 19:00(面 B 批次 11 收尾 + **批次 12 方向决策**),
> **20:10 追加「前端 MVP 用 React 模板、除了认证其它都留给集成阶段」**。**开工先读这一页**
> (尤其 **§0-bis 的「下一轮的优先级改了」**),再读 `CLAUDE.md`(硬约定),
> 最后看 `.workbuddy/memory/` 最近一天的日志(踩过的坑)。
> 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。
@@ -15,6 +17,156 @@
---
## 0-ter. 🔴🔴 两阶段开发路线(这是全局路线,先看这条)
**用户定的路线**(2026-11-01 19:39 明确):
```
┌─ MVP 阶段 ─────────────────────────────┐ ┌─ 规范集成阶段 ──────────────────┐
│ 用 ssw-jnpf-lite-rust 技能开发 │ │ 迁到标准 JNPF 框架集成开发 │
│ 「AI 怎么快怎么来」 │ → │ 遵守官方规范 │
│ 后端 = Rust(axum) 单二进制 │ │ 后端 = 标准 JNPF Java │
│ 前端 = React 模板(AI 友好薄壳) │ │ 前端 = 官方 JNPF vue(原生) │
│ └ 只做「认证 + 业务规则原型」 │ │ └ 补齐权限配置/低代码/建模等全套 │
│ └ 其它全部留给集成阶段 │ │ │
│ 目的:把业务快速跑通、把业务规则试出来 │ │ 目的:按官方规范固化、可维护 │
└────────────────────────────────────────┘ └─────────────────────────────────┘
↘ 仅「部分终端设备不佳」的场景保留 Rust 后端
```
🔴 **前端 MVP 用 React、不是 Vue**(2026-11-01 用户纠正):
「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
**除了认证,其它都留给集成阶段**」。
⇒ **官方 vue 是集成阶段的事**;MVP 前端是 **React 薄壳**(两个技能的 React 前端**逐字节相同**)。
详见下面「🔴 前端在两阶段分别是什么」。
🔴 **两阶段的分界线不是「时间」,是「契约忠实度」**:
MVP 阶段允许**形状有偏差**(官方前端能跑、能试业务就行)⇒ 换来速度;
集成阶段要求**逐字对齐官方规范** ⇒ 换来可维护性。
⇒ **MVP 阶段的每一处「快」,都要在集成阶段还债。** 本文件就是那本账。
### 🔴 MVP 阶段「快」的真实代价(2026-11-01 19:40 实测,非推测)
官方端点台账(`docs/contract.md` 附录 A 的 `[OFFICIAL]`,379 条)的忠实度分布:
| status | 条数 | 含义 | 集成阶段怎么办 |
|---|---|---|---|
| `implemented` | **338** | 已落地且**形状对齐** | ✅ 直接搬 |
| `partial` | **27** | 已落地但**形状有偏差** | 🔴 **要还债**(下面逐条列) |
| `absent` | **7** | 未实现 | 集成时补(官方现成) |
| `oos` | **6** | 明确不做 | 集成时按官方做 |
⇒ **MVP 阶段真正的债 = 那 27 条 `partial`**。它们分三类:
| 类 | 条数 | 特征 | 集成时的动作 |
|---|---|---|---|
| **① 临时欠**(本仓没这能力,官方有) | **14** | 导出/导入/测试连接/打印渲染 —— **恒 `400` + 人话**(本仓无文件服务 / 无外部驱动 / 无渲染引擎) | **删掉本仓实现,用官方的** ⇒ 几乎零成本 |
| **② 形状欠**(语义对,VO 不逐字) | **9** | 如 `CurrentUser` 的 `sysConfigInfo` 返 `{}`、按钮级权限恒空、`permissionList` 粒度不同 | 🔴 **要真对齐**(前端依赖这些字段)⇒ 这类是**主要工作量** |
| **③ 自造**(本仓自己发明的) | **4** | 如 `f_en_code` 用本仓自定占位(`permission.demo` 等)、`deleteAllTable` 有意收窄 | 🔴 **改成官方编码 / 官方语义** |
⚠️ **②③ 共 13 条是真债**(要写代码),**① 14 条是假债**(删了换官方的就行)。
⇒ **MVP 阶段真正该盯的是那 13 条**,不是 27 条。这是「快」能快到什么程度的**精确边界**。
### 🔴 MVP 阶段的四条红线(违反了 = 集成时返工)
1. 🔴 **业务表的 `base_*` 列名不许自创** —— 官方 `base_*` DDL 逐字(`JNPF-PostgreSQL.sql` 13227 行 / 331 张表,本机已有)
⇒ 业务表 DDL 从一开始就照官方列名写 ⇒ 集成时**只导数据不导结构**。
2. 🔴 **业务表的 `f_tenant_id` 不许省**(值恒 `"0"`,但列 `NOT NULL` 且参与复合主键 `(f_id, f_tenant_id)`)。
3. 🔴 **接口路径从第一天就用官方形状**(面 B 的 `/api/xxx/...`)⇒ 集成时**前端零改**。
⚠️ 面 A 路径(`/api/ssw/...`)是本仓自造的 ⇒ **集成时全部作废**,只留给 Rust 终端场景。
4. 🔴 **返回形状宁可少字段,不许返错形状** ⇒ 官方前端遇到缺字段会**静默降级**(按钮恒显、树空)。
### ✅ 已经到位的部分(集成时直接搬,别重做)
| 项 | 证据 | 集成时 |
|---|---|---|
| `base_*` 表名/列名逐字对齐官方 | `schema.sql` 48 张 `base_*` | ✅ 只导数据 |
| 口令 cipher 逐字节等价 | `cipher.rs` 检验向量 + 官方 `DesUtil` | ✅ 换算一次(`MIGRATION.md` §7) |
| 响应信封 `ActionResult{code,msg,data}` | `envelope.rs` ↔ `jnpf.base.ActionResult` | ✅ 零改 |
| 实体 spec ↔ Java 实体 | `EntitySpec` 的列清单 ≈ 一个实体类 | ✅ 照 `MIGRATION.md` §2.1 翻译表 |
| 权限判据 | 面 B 已按 `f_en_code`(官方 `@SaCheckPermission` 的判据) | ✅ 零改 |
| 官方前端能直连本仓 | 面 B 契约 + `Vue-Version: 3` 判别头 | ✅ 集成时**前端几乎零改** |
| 官方前端加页面的机制 | `router/routes/index.ts` 用 `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)⇒ **放文件进目录即注册**,不改配置 | ✅ 集成期把打磨期的页面搬进 `modules/` 目录即可 |
### 🔴 前端在两阶段分别是什么(2026-11-01 19:39 修正 + 20:10 按 React 模板重写)
> 🔴 **上一版这里写错了**:当时写「MVP 阶段前端 = 官方 JNPF vue(零改直连面 B)」。
> **用户已纠正**(原话:「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
> **除了认证,其它都留给集成阶段**」):
> **MVP 阶段的前端 = React 技能模板,不是官方 vue**。官方 vue 是**集成阶段**的事。
| | MVP 阶段(AI 怎么快怎么来) | 集成阶段(按官方规范) |
|---|---|---|
| 前端代码 | **React + Vite**(`ssw-jnpf-lite-react` / `ssw-jnpf-lite-rust` 技能里的 `src/frontend`) | **官方 JNPF Vue**(`~/Desktop/workspace/jnpf/jnpf-web-apps-main`) |
| 后端对接 | 面 A `/api/ssw/...`(Rust/NestJS 自造约定)⇒ **前端零改直连** | 面 B `/api/{模块}/{资源}/...`(官方形状)⇒ **前端零改直连** |
| 认证 | ✅ **MVP 就做**(见下「认证为什么例外」) | ✅ 换成官方 `jnpf-oauth`,**路径/返回同形** |
| 业务页面 / 权限配置 UI / 低代码表单 / 数据建模页 | ❌ **不做**(只留最小原型) | ✅ 全做(官方有现成的) |
| 价值 | 业务规则能马上试出来、改一行刷新就看到 | 按官方规范固化、可维护 |
🔴 **一句话**:**MVP 前端 = 「能登录 + 能试业务规则」的薄壳**,
不是「一个 JNPF 前台」。**除了认证,其余全部留给集成阶段**。
#### 🔴🔴 认证为什么是唯一的例外(2026-11-01 20:10 实测,证据链完整)
认证是**唯一不能推迟**的部分——没有它就**连业务都试不了**(登录不进 ⇒ 看不到列表 ⇒ 试不了规则)。
而认证恰好也是**迁移时最不容易出错**的部分,因为它**契约已经完全对齐官方**:
| 环节 | MVP(React 模板) | 官方 | 结论 |
|---|---|---|---|
| 登录端点 | `POST /api/oauth/Login`(`x-www-form-urlencoded`) | `api/core/auth.ts`:`Api.Login = '/api/oauth/Login'` + `ContentTypeEnum.FORM_URLENCODED` | ✅ **一字不差** |
| 登录参数 | `account` / `password`(密文 hex) / `grant_type=password` | `AuthApi.LoginParams`:同样三个字段 | ✅ **一字不差** |
| 口令密文 | `cipher.ts`:`md5(plain)` → AES-256-ECB-PKCS7(key=`md5("EY8WePvjM5GGwQzn")`) → hex | 官方 `DesUtil` + `SecurityProperties` | ✅ **逐字节等价**(检验向量 `encryptPassword('123456')` = `d4958348e...cdc02b`) |
| 登录返回 | `{ token, expiresIn, tokenTypeName }` | 官方同形 | ✅ |
| 登出码 | `600/601/602` → 清 token 跳 `/login` | 官方 `ResultEnum.TOKEN_ERROR / TOKEN_LOGGED / TOKEN_TIMEOUT` 分支 | ✅ **语义 1:1** |
| 响应信封 | `ActionResult{code,msg,data}`,`code!==200` → reject | 官方 `transformResponseHook`:`{code,msg}` + `code===ResultEnum.SUCCESS` 才过 | ✅ **1:1** |
| 请求头 | `App-Code` / `Jnpf-Origin: pc` | 官方 `client.addRequestInterceptor`:三个头 + `K1`(RSA 加密的 aesKey) | ⚠️ MVP 少 `K1`(无 body 级 AES) |
⇒ **认证层在 MVP 阶段就照官方契约写** ⇒ 集成时**认证这块几乎零改**,
只需要把 `K1` 头和 body 级 `useCipher` 补上(官方 `AesEncryption` 走 `requestOptions.useCipher` 开关)。
#### 🔴 关键实测:**两个技能的 React 前端逐字节相同**(2026-11-01 20:05)
```bash
$ diff -rq skills/ssw-jnpf-lite-react/src/frontend/src skills/ssw-jnpf-lite-rust/src/frontend/src
# 无输出 ⇒ 完全一致
$ diff react/src/frontend/vite.config.ts rust/src/frontend/vite.config.ts
# 唯一差异:proxy 端口 30000(NestJS) vs 30010(Rust)
```
⇒ **「React 前端 MVP 模板」是独立资产,与后端选 Rust 还是 NestJS 无关**:
换后端栈**前端一个字都不用动**(契约同形)。
⇒ **这不是巧合,是设计**:两个技能刻意共用同一套前端,
就是为了让「先 NestJS 后 Rust」或「先 Rust 后官方 Java」的迁移路径上,前端永远零改。
⇒ **本仓(ssw-platform)的选择**:**MVP 后端用 Rust(axum),前端用这套 React 模板**
⇒ 直接从 `ssw-jnpf-lite-rust` 复制 `src/frontend` 即可(与 React 技能逐字节相同)。
#### 🔴 认证之外的「9 个接触点」在 React 模板里的位置(集成期要搬到 Vue)
React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO_MODULE.md` §〇.5):
| # | 文件 | React 模板 | 集成期搬到官方 Vue |
|---|---|---|---|
| 1 | `src/backend/src/{app}/xxx.entity.ts` | ✅ MVP 做 | 翻译成 Java 实体(`@TableName` + `SuperEntity`) |
| 2 | `src/backend/src/{app}/xxx.service.ts` | ✅ MVP 做 | 翻译成 `SuperServiceImpl` |
| 3 | `src/backend/src/{app}/xxx.controller.ts` | ✅ MVP 做 | 翻译成 `BaseCrudController`(`references/BaseCrudController.java`) |
| 4 | `src/backend/src/{app}/xxx.module.ts` | ✅ MVP 做 | 换 Maven 多模块 `ssw.{appCode}.xx.xx` |
| 5 | `src/backend/src/app.module.ts`(**两处**) | ✅ MVP 做 | ❌ 集成期删除 |
| 6 | `src/frontend/src/api/xxx.ts` | ✅ MVP 做(3 个 export) | 翻译成 `api/<模块>.ts`(`defHttp.get/post/delete`) |
| 7 | `src/frontend/src/views/Xxx.tsx` | ✅ MVP 做(原型) | 翻译成 `views/<模块>/index.vue` |
| 8 | `src/frontend/src/App.tsx`(+1 `<Route>`) | ✅ MVP 做 | ❌ 集成期删除(官方按菜单自动注册路由) |
| 9 | `src/backend/src/sys/seed.service.ts`(`menus[]` +1 行) | ✅ MVP 做 | 数据 ETL 导进 `base_module` |
⇒ **「除了认证其它都留给集成阶段」的准确含义**:
**MVP 只做 #1~#5(后端)+ #6~#7(前端薄壳)**,
**#8/#9 的官方等价物(路由自动注册、菜单挂载)集成期才做**,
**权限配置 UI / 低代码表单 / 数据建模页这些官方现成能力,MVP 完全不碰**。
⚠️ **注意**:`check-module.sh` 的前端 4 个接触点在本仓**全打 `⏭`** ⇒
**前端目前没有任何闸门保护** ⇒ 集成前必须补(见 §3「批次 12」的 ④)。
---
## 0-bis. 📊 缺口全景(2026-10-31 05:00 全量摸底,看这里决定下一步)
用 `/tmp/fe-scan/scan.py` 扫前端 `src/api/**`(741 条端点定义,先解 `enum Api` 再解析
@@ -102,6 +254,101 @@
`extend`(64) / `msgCenter`(50) —— **基本都属于「本仓没这个模块」**。
(🔴 批次 9 收尾时此处写的 252/28.0% 是**批次 8 的旧数**,实测 291/32.3%,此处已更正。)
### 🔴🔴 下一轮的优先级改了(2026-11-01 19:00 决策,19:39 补充两阶段路线)
**批次 12 不再是「补端点」,改成「把框架打成固定包 + 业务模块链接就好」。**
理由:端点补到 331/900 后,剩下的**大半是「本仓没这个模块」**(做了也是恒空 stub);
而**每加一个业务模块要改 6~8 处、手抄两份 spec、手抄 DDL、手抄契约表** —— 这个成本
才是「成熟框架 + 极简业务代码」的真实瓶颈。
⇒ 详见 §3「批次 12」的完整方案(4 项交付物 + 7 条护栏 + 5 条验收判据)。
🔴 **19:39 补充**:用户明确了**两阶段路线**(MVP 用 Rust 技能「AI 怎么快怎么来」→
业务定型后迁标准 JNPF 集成开发,Rust 只在「部分终端设备不佳」的场景保留)。
⇒ **这改变了批次 12 的优先级排序**:批次 12 的四项交付物**全部服务于 MVP 阶段的速度**,
但**每做一项都要留下「集成时能还债」的痕迹** ⇒ 详见 §0-ter 的「四条红线」与 §3「批次 12」
的「集成期友好性」验收项。**不是「先快后补」,是「快的同时记账」。**
🔴 **20:10 补充(前端方向定案)**:用户指明 **`ssw-jnpf-lite-react` 模板就是前端 MVP 阶段 AI 友好的方向**,
并划定了边界:**「除了认证,其它都留给集成阶段」**。
⇒ **前两版关于前端的表述都是错的**(先写「官方 vue 零改直连面 B」,后写「前端全程在官方 monorepo」)
⇒ 现在定案:**MVP 前端 = React 模板**(**认证做全套**,业务页面只做薄壳原型),
**官方 vue / 权限配置 UI / 低代码 / 数据建模 = 全部留给集成阶段**。
⇒ 🔴 **实测支撑**:两个技能的 `src/frontend` **逐字节相同**(仅 vite proxy 端口不同)
⇒ 前端是**独立资产**,与后端选 Rust 还是 NestJS 无关 ⇒ 换后端栈前端零改。
⇒ 详见 §0-ter 的「🔴 前端在两阶段分别是什么」。
**同时测出「快验证」的成本分布**(2026-11-01 19:00 实测,勿凭印象改):
| 类别 | 闸门 | 耗时 | 备注 |
|---|---|---|---|
| 静态 | `check-contract.sh` | **66.6s** 🔴 最慢 | 静态解析 659 个路由 ⇒ 提速首要目标 |
| 静态 | `check-module.sh` | 25.8s | |
| 静态 | `check-boundary.sh` | 7.2s | |
| 静态 | `check-citations.sh` | 5.2s | |
| 静态 | `check-naming.sh` | 3.6s | |
| 静态 | `check-arch.sh` | 1.6s | |
| 运行时 | `perm-smoke.sh` | 6.0s | 起隔离后端 |
| 运行时 | `perm-smoke-jnpf.sh` | 4.8s | |
| 运行时 | `baseline-smoke.sh` | 3.3s | |
| 运行时 | `mcp-smoke.sh` | 2.9s | 34 + 14 两段 |
| 运行时 | `lowcode-smoke.sh` | 1.9s | |
⇒ **静态闸门合计 ~110s,运行时合计 ~19s** ⇒ 「快速验证」的瓶颈在**静态闸门**,
不在起后端。批次 12 的 ④ 就是治这个(增量扫描 + `scripts/verify.sh` 一条命令)。
### 🔴 2026-11-01 22:00 复核:上面那张表**大半是「转发壳」的错**(结论已修正,别再按它排优先级)
同一套闸门在**普通终端**里只要表里数字的 **1/2 ~ 1/20**。原因不在代码,在**执行环境**:
沙箱 / AI 助手的 bash 会把 `grep` `sed` `cat` `wc` 换成一个**转发壳**
(PATH 指向 `…/shim/brokered-bin/<命令>`,**每次启动 ≈0.19s**)。而本仓闸门正是
「几百次 grep」的形态 ⇒ 0.19s × N 被逐条累加,看起来像「脚本写得慢」。
| 闸门 | 旧表(转发壳环境) | 普通终端实测 | 倍数 |
|---|---|---|---|
| `check-contract.sh` | 66.6s | **3.2s** | 21× |
| `check-module.sh` | 25.8s | **1.4s** | 18× |
| `check-boundary.sh` | 7.2s | **1.5s** | 4.8× |
| `check-citations.sh` | 5.2s | **4.0s** | 1.3× |
| `check-naming.sh` | 3.6s | **2.0s** | 1.8× |
| `check-arch.sh` | 1.6s | **1.7s** | 1× |
⇒ 旧表里「`check-contract` 66.6s→55.0s→8.2s」那几轮优化,**有一半是壳的功劳**,
换台普通终端重跑就没了。**只有纯算法改动才是真的**——2026-11-01 晚做掉的两处:
| 改动 | 真实收益 | 原理 |
|---|---|---|
| `check-contract-scan.py`:**函数体位置索引** `_fn_positions` | 1.4s → 0.15s(单次分析) | 原来「查一个 handler 就在**整份文件**上跑一遍 `re.search`」(362 次)⇒ 改成每份文件只扫一遍、建 `名字 → 位置` 表 |
| `check-citations-scan.py`:**引文后缀倒排表** `_lookups` | 1008 万次 `endswith` → 0 | 原来「每条引文遍历该根下**全部文件**做 `rel.endswith("/"+路径")`」⇒ 建成 `后缀 → 文件` 倒排表,查询 O(1) |
⇒ **教训(已写进 `scripts/verify.sh`)**:`verify.sh` 现在会先探测 `command -v grep`
是否落在 `*/shim/*` / `*/brokered-bin/*`,命中就打印醒目告警——
**「耗时不标注环境 = 假数据」**,假数据会让人去优化根本不存在的问题。
**当前真实数字(普通终端,`bash scripts/verify.sh --fast`)**:
```
契约生成段同步(pack-sync --check) 0.1s
编译(cargo build --offline) 0.3s
静态闸门 check-arch 1.7s
静态闸门 check-boundary 1.5s
静态闸门 check-naming 2.0s
静态闸门 check-module 1.4s
静态闸门 check-contract 3.2s
静态闸门 check-citations 4.0s
──────────────────────────────────────────
总耗时 14.6s(8 个步骤,全 ✅) ⇒ 批次 12 的「≤15s」目标**达成**
```
⚠️ **同一台机上 4 次实测是 14.6 / 14.7 / 15.2 / 15.5s**(机器负载不同,差 1s 量级)
⇒ 引用时说 **≈15s**,别把 14.6 当恒定值;也**别**为了「好看」去砍 `check-citations`
的断言——它 4.0s 里 2.6s 是**沙箱代理的文件读**(`socket.recv`),代码侧只剩 0.6s,
再优化就是跟执行环境较劲,不是跟算法较劲。
`--lib`(外加 `cargo test --workspace --lib`)= **23.5s**(单测 8.8s,103 passed)。
⚠️ 同一个 `verify.sh` 在转发壳环境里仍会打印 36.1s —— 但开头会先警告「本环境的 grep
被转发壳接管」,看到这行就别拿那个数字做判断。
---
## 1. 一句话现状(2026-11-01 批次 11 收尾)
@@ -129,13 +376,22 @@
高级查询方案共 31 条端点 —— 这是「权限」页配权限的后端地基,见 §1「批次 10」小节。
- 🔴 **数据权限三件套落地了**(批次 11):数据权限字段 / 数据权限方案 / 数据连接共 15 条端点
—— 见 §1「批次 11」小节。
- 🔴 **「业务包」目前是死的**(2026-11-01 19:00 实测,下一轮要治):
`packs/asset` **只依赖 sdk、能独立编译**,但**内核根本没装载它** ——
`routes.rs` 只 merge 了 `modules::router()`,且 `sspf-sdk` 的 `BusinessPack`
**没有 `routes()` 方法**(只有 manifest/entities/menus/metadata/hooks)。
⇒ 业务 spec 在 `modules/asset.rs` 与 `packs/asset/src/lib.rs` 里是**两份逐字拷贝**,
且**没有任何闸门比对它们**(`check-arch.sh` 只有 AR1–AR7 + MEM1–MEM2,
`packs/asset` 注释里写的「PACK1 会比对」**至今未实现**)。
⇒ 这就是批次 12 要解决的核心问题(详见 §3「批次 12」)。
**✅ 后端已拆成 workspace 多 crate,业务包可独立编译;十二道闸门全绿;空载内存 8 MB。**
- 新增 `crates/sspf-contract`(契约层,无 axum)、`crates/sspf-sdk`(业务包唯一依赖)、
`packs/asset`(样板业务包,只依赖 sdk,能 `cargo test -p sspf-pack-asset` 独立跑)。
🔴 **但业务包与内核尚未接线**(见上面「业务包目前是死的」)。
- `rust-toolchain.toml` 全仓锁 **1.95.0**(L3 动态库 ABI 一致性强依赖;本机代理限速装不上 1.99)。
- 新增两道闸门:`scripts/check-arch.sh`(AR1–AR5 + MEM1–MEM2,带 `--self-test`)、
- 新增两道闸门:`scripts/check-arch.sh`(AR1–AR7 + MEM1–MEM2,带 `--self-test`)、
`scripts/mem-budget.sh`(空载内存实测,用 `vmmap`,**本机沙箱禁 ps/top**)。
- 内核 `platform/{envelope,entity,menu,ids}.rs` 已改为 re-export 契约层 ⇒ 引用路径零变化。
- `cargo test --workspace` = **240 条**(不是 221/230 了,拆 crate 后数字会变,别写死)。
@@ -748,10 +1004,364 @@ xop run --secret GU=git_local_user --secret GP=git_local_pass -- bash -c '
**create 用 `fieldRule!=0`、update 用 `fieldRule==1`**;delete 比对用**带前缀**的码。
🔴 **方案列表只需登录**(官方没加 `@SaCheckPermission`)。
🔴 `FieldList` / 表字段端点依赖低代码表单与数据库内省 ⇒ **诚实返回空**(不假装)。
12. 🔴🔴 **【批次 12 = 下一轮优先做】框架固定包 + 业务模块链接就好**
—— 不是补端点,是**改「加业务的成本结构」**:加一个业务模块从现在的
**改 6~8 处**(两份 spec 拷贝 + 手抄 DDL + 手抄契约表 + 改 `schema.sql` +
改 `main.rs` BASE_TABLES + 改 `sspf-store/db.rs` 两处表数断言)
降到 **写 1 个包文件 + 改 2 处**。
🔴 **四件事**:① `sspf-sdk` 补 `routes()` + 新建 `crates/sspf-plugin`(L2 静态装载器)
② 打通两份拷贝(`modules/asset.rs` 改 re-export)+ **补 PACK1 闸门**
③ 业务 DDL 跟着包走(不再手抄 `schema.sql`)+ 表数断言去写死
④ 契约登记**自动生成** + 静态闸门**增量提速** + 新增 `scripts/verify.sh` 一条命令。
🔴 **明确不做**:L3 dylib 动态库 / WASM 执行器 / `pack export-import` 双向迁移
(见该节「明确不做」)。完整方案见下方「批次 12」小节。
⚠️ **前端**:本仓 `src/frontend` **是空的**(后端-only)⇒ vue 前端那条诉求
**不在本仓范围**;官方 JNPF monorepo **本身就是那个「固定包」**(前端零改跑在本仓后端上)。
⇒ 若要做前端侧「页面脚手架」,需**先确认产品边界**(候选:仿 `new-pack.sh` 做 `new-page.sh`)。
**下一个(批次 12)**:`fe-gap` 余下最大的 `system` 55 条 / `permission` 26 条 /
`systemData` 32 条里挑**有官方 `base_*` 表支撑**的;`workFlow`(104) / `onlineDev`(101) /
`aiCenter`(75) / `extend`(64) / `msgCenter`(50) 基本都是「本仓没这个模块」⇒
### 🔴🔴 批次 12(下一轮优先做)—— 「框架固定包 + 业务模块链接就好」
> **这一批不是补端点,是改「加业务的成本结构」。** 目标形态:
> **平台层(面 A/B 契约 + 权限 + 低代码 + MCP)打成一块相对固定的底座**,
> **新业务模块只写 spec + 一行注册**,不碰平台层、不重复拷贝、不手抄 DDL、不手抄契约表。
> 完成后「加一个业务模块」从现在的**改 6~8 处**降到**写 1 个文件 + 改 2 处**。
🔴 **本批必须同时满足两个目标(2026-11-01 19:39 追加)**:
**MVP 阶段**(Rust 技能,AI 怎么快怎么来)**要快** ⇒ 上面四项交付物;
**集成阶段**(迁标准 JNPF,规范开发)**不能欠债** ⇒ 每项交付物都要**留下可还债的痕迹**。
⇒ **判据不是「这批做完没」,是「集成时要还的债有没有变少」。**
本批**直接消灭的债**:那 **27 条 `partial`** 里,属于「自造」的 **4 条**会随 ①③ 的重构消失
(`f_en_code` 自定占位 → 改官方编码;`deleteAllTable` 收窄 → 改官方语义)。
#### 现状体检(2026-11-01 19:00 实测,勿凭印象改)
| 事实 | 证据 | 影响 |
|---|---|---|
| 业务 spec **有两份逐字拷贝** | `src/backend/src/modules/asset.rs`(178 行)vs `packs/asset/src/lib.rs` | 改一处忘另一处 ⇒ **静默**不一致 |
| 两份拷贝**没有比对闸门** | `check-arch.sh` 只有 AR1–AR7 + MEM1–MEM2,**没有 PACK1** | `packs/asset/src/lib.rs` 注释里写的「PACK1 会比对(P3 加)」**至今没加** |
| `packs/asset` **根本没被内核装载** | `routes.rs` 只 `merge` 了 `modules::router()`(1 处 merge);`sspf-sdk` 的 `BusinessPack` **没有 `routes()` 方法**(只有 manifest/entities/menus/metadata/hooks) | 业务包是**死的**样板,`PLAN.md` §4.4 写的 `routes()` 未实现 |
| 契约扫描器**只扫 `modules/*.rs`** | `check-contract-scan.py:369` 只遍历 `src/backend/src/modules/`(除 `mod.rs`) | 业务包若搬到 `packs/`,路由**不在扫描范围** ⇒ CC2/CC3 判「契约多 / 代码少」⇒ **假漂移** |
| 静态闸门**最慢 66.6s** | 实测 `check-contract.sh` 66.6s(静态解析 659 个路由);`check-module` 25.8s | 每次改代码都等 ⇒ 「快速验证」体感差 |
| 运行时尺子**都很快** | `perm-smoke` 6.0s / `perm-smoke-jnpf` 4.8s / `lowcode` 1.9s / `baseline` 3.3s / `mcp` 2.9s | **「快验证」的成本在静态闸门,不在运行时** |
| 业务 DDL 要**手抄进 schema.sql** | `schema.sql:879/888/897/920` 四张业务表 | 加一张表要改 schema.sql + `main.rs` BASE_TABLES + `sspf-store/db.rs` **两处**断言(批次 9/10 各踩一次) |
| 业务表数**写死 52** | `crates/sspf-store/src/db.rs:1226,1233` | 加表必红 ⇒ 又一处「记得改」 |
#### 本批交付物(4 件事,按依赖顺序做)
**① `sspf-sdk` 补 `routes()` + `crates/sspf-plugin`(L2 静态装载器)**
- `BusinessPack` 加 `fn routes(&self) -> &'static [PackRoute]`(**默认空** ⇒ 纯元数据包 L0 仍零改动)。
`PackRoute` = `{ method, path, entity }` —— **不是 axum Handler**,只是**声明**。
🔴 **理由**:业务包不许依赖 axum(AR2 钉死)⇒ 路由**声明**在 sdk(纯数据),
**注册**在内核(唯一认识 axum 的地方)。这与 `EntitySpec` 已是同一模式。
- `crates/sspf-plugin`(新 crate,依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json}):
扫 `packs/*/pack.toml` ⇒ 读清单 ⇒ 校验 `kernel_req` 区间 ⇒ 收集 entities/menus/routes。
🔴 **AR8 新增**:本 crate 依赖 ⊆ {sspf-sdk, sspf-contract, serde, serde_json}(不许碰 axum/tokio/pglite)。
- 内核接线:**只改 `bootstrap.rs` 一处** —— 平台层 `crud.rs` 补一个
`crud_router(spec) -> Router<AppState>`(把现有 `handle_list/save/delete` 包成 3 条路由),
业务包给出 `routes()` ⇒ 插件层按 `{method, path, entity}` 查 spec ⇒ 生成路由 ⇒ merge。
⇒ **业务包自带路由,平台层零改动**(这才是「链接就好」的含义)。
- 🔴🔴 **【集成期友好性】包声明的路由路径必须从第一天就用「官方形状」,不许用面 A 的 `/api/ssw/...`**:
- 面 A(`/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`)是**本仓自造**的 ssw 约定
⇒ **集成到官方 JNPF 时全部作废**(官方路径见 `MIGRATION.md` §2.3)。
- 面 B(官方 JNPF 的 `/api/{模块}/{资源}/...`)才是能直接搬的形状。
- ⇒ **业务包默认只声明面 B 形状的路由**;面 A 那套**留给 Rust 终端场景**(保留在 `modules/` 里不动)。
- ⇒ **验收**:新加的包,`pack.toml` 里的路径在官方 `JNPF-PostgreSQL.sql` 对应的 Controller 里
**能一一对上**(用 `MIGRATION.md` §2.1 的逐件翻译表反查)。
**② 打通「两份拷贝」⇒ 单一真源 + `PACK1` 闸门**
- `modules/asset.rs` 的 spec **改为从 `packs/asset` re-export**(`pub use sspf_pack_asset::DATA_RESOURCE_SPEC;`)
⇒ **只留一份**。内核 `Cargo.toml` 加 `sspf-pack-asset = { path = "../../packs/asset" }`。
- 🔴 **AR2 会因此破**(`packs/*` 只能依赖 sdk/serde;内核依赖 packs 是**反向**,不违反 AR2)⇒
需给 `check-arch.sh` 加 **AR9**:内核**只允许**依赖 `packs/<app>` 这类业务包,且**不得**在
平台层(`platform/`)出现 `use sspf_pack_*` ⇒ 业务知识不许漏进平台层。
- **PACK1 闸门**(新增,`check-arch.sh`):`packs/<app>/src/lib.rs` 声明的 entities/menus
与 `modules/<app>.rs` 声明的**逐字一致** ⇒ 不一致就红。有了 re-export,这道闸变成
「**模块文件只允许 re-export,不许自己写 spec**」的形状检查。
**③ 业务 DDL 跟着包走 ⇒ 不再手抄 `schema.sql`**
- 每个包带 `schema/*.sql`(`pack.toml` 的 `[[pack.tables]].ddl` 已预留这个字段);内核启动时
**按包顺序**执行 + 幂等(`CREATE TABLE IF NOT EXISTS`)。
- 🔴 **`sspf-store` 的两处表数断言必须改成「不写死」**(`db.rs:1226,1233`)——
写死 52 是批次 9/10 各踩一次的坑,改成「base 表数写死 + 业务表数 ≥ N」或直接读 `ddl_tables()` 对账。
- 🔴 **`is_builtin_table`(`face_b.rs:12993`)取 `ddl_tables()`** ⇒ 业务包建的表会**自动变成内置表**
⇒ 数据建模页**看不到**用户自己建的表了。这条要**重新想**(本批至少要保证行为不回退)。
- 🔴 `main.rs::whitelist_self_check` 的**双向对账**(孤儿 DDL / 漏建表)要改成
「DDL = base 表 + **所有包**的表」,否则包表会被判成孤儿 DDL ⇒ 启动失败。
- 🔴🔴 **【集成期友好性】包的 DDL 必须按官方规范写,集成时才能「只导数据」**:
- 列名照官方习惯:`f_` 前缀 + `f_id VARCHAR(50)`(36 位 UUID)+ `f_delete_mark INTEGER DEFAULT 0`
+ **`f_tenant_id VARCHAR(50) NOT NULL`**(值恒 `"0"`,**参与复合主键 `(f_id, f_tenant_id)`** ——
单租户也不许省,见 CLAUDE.md 红线 12)。
- **业务表的 `f_` 列不许自创语义**(如把金额叫 `f_money` 而官方叫 `f_price`)⇒ 集成时列名映射是纯人工活。
- 🔴 **包的 `pack.toml` 要补 `baseline_table`**(`[[pack.tables]]` 已有该字段)⇒ 集成时表名不同可自动映射,
不靠人记。
- **验收**:拿一个包,把它的 `schema/*.sql` 对着官方 `JNPF-PostgreSQL.sql` 的同名表逐列比,
差异只允许出现在「官方没有这个业务表」这一项上(业务表本就要新建,但**列的形状**要对齐官方同类表)。
**④ 契约登记自动化 + 让静态闸门变快**
- 契约表 `docs/contract.md` 附录 A 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` 三段,
现在**手写** ⇒ 加包必须手抄三处。⇒ 改成**从包生成**:`scripts/pack-sync.py`
读 `packs/*/pack.toml` + `src/lib.rs` ⇒ 追加到 contract.md 附录 A(幂等)。
🔴 **不要手改生成段**(否则下次同步被覆盖)⇒ 生成段用 `<!-- PACK:BEGIN -->` / `<!-- PACK:END -->` 包起来。
- 🔴 **扫描器要认识 `packs/`**:CC2/CC3 现在只扫 `modules/*.rs` ⇒ 业务包搬走后会判假漂移。
⇒ `check-contract-scan.py` 改成扫 `packs/*/src/lib.rs` + `modules/*.rs` **两处**。
- **提速**(`check-contract.sh` 66.6s 是瓶颈):扫描器目前每次全量解析 659 个路由。
⇒ 加**增量**:按文件 mtime 缓存解析结果(`scripts/.scan-cache.json`)⇒ 改一个文件只重扫一个。
目标:**改一个模块后静态闸门总耗时 ≤ 15s**(现状 ~110s)。
- 🔴 **「快速验证」的新命令**:`bash scripts/verify.sh` —— 一条命令跑完
`build → 静态闸门 → 单测 → 尺子`,末尾打印**总耗时**与**哪道最慢**(Top 3)。
这是「快速打包 / 快速验证」的**用户可见入口**。
- 🔴🔴 **【集成期友好性】前端触点也要进闸门**(现在前端**完全没有保护**,见 §0-ter):
- 🔴 **本批的前端 = React 模板**(`ssw-jnpf-lite-rust` 的 `src/frontend`,与 React 技能**逐字节相同**)
⇒ **本仓要把 `src/frontend` 建起来**(当前是空的,CLAUDE.md §2.2 写的是「后端-only」——
🔴 **这条要改**:新路线下前端在 MVP 阶段就有,且**必须**是 React 模板)。
- ⇒ **本批产出 `scripts/new-page.sh <app> <Entity>`**:生成 **React 三件套**:
`src/frontend/src/api/<lc>.ts`(3 个 export)+ `src/frontend/src/views/<Ent>.tsx`(列表+弹窗表单+删除确认)
+ `src/frontend/src/App.tsx` 的 `<Route path="/<app>/<Entity>" />` 一行
+ 提醒菜单登记(`urlAddress` == Route path 去前导斜杠 == `guardModule` 的 key,**三处一字不差**)。
⇒ 模板直接抄 React 技能的 `views/DemoItem.tsx`(101 行,含弹窗表单)+ `api/product.ts`(7 行)。
- ⇒ **前端闸门**:把 React 技能的 `scripts/check-module.sh`(11 KB,**9 个接触点**,
支持 `--all` 自动探测 / `--live` 实跑后端)**移植**过来 ⇒ 前端 4 个接触点**从 `⏭` 变成真检查**。
🔴 **移植时只改后端路径**(React 技能指 NestJS `src/backend/src/` ⇒ 本仓指 Rust `src/backend/src/`),
**前端路径零改**(`src/frontend/src/...` 两边同名)。
- 🔴 **集成期才做官方 Vue 那一套**:`views/<模块>/index.vue` + `api/<模块>.ts`
+ `router/routes/modules/<模块>.ts`(官方 `import.meta.glob` **放文件即注册,不用改配置**)。
⇒ **本批不做**(明确不做清单里),集成期再写 `new-page.sh --vue` 或另一个脚本。
- ⚠️ **不要现在就把官方 monorepo 的路径写进脚本**:`jnpf-web-monorepo-framework`(7.0 前端框架)
与 `jnpf-web-apps-main`(官方应用)是**两个目录**,实际业务代码在**后者**
(`~/Desktop/workspace/jnpf/jnpf-web-apps-main`,其 `src/api/request.ts` = `defHttp` 定义处)。
⇒ 集成期做 `--fe-root` 时要指对目录。
#### 本批护栏(缺一不可)
| # | 护栏 | 落地位置 |
|---|---|---|
| 1 | 业务包**不许依赖 axum/tokio/pglite** | AR2(已有)+ 新 AR8 |
| 2 | 平台层**不许出现业务包**(业务知识隔离) | 新 AR9 |
| 3 | spec **单一真源**(不许两份拷贝) | PACK1 + re-export 改造 |
| 4 | 路由**声明**在 sdk、**注册**在内核 | `PackRoute` + `bootstrap.rs` |
| 5 | 包表数**不许写死** | `sspf-store/db.rs` 两处断言 |
| 6 | 包 DDL 幂等 + 不许碰 `base_*` | 内核执行时过滤 `base_` 前缀 |
| 7 | 契约登记**生成**而非手写 | `pack-sync.py` + BEGIN/END 标记 |
| 8 | 🔴 **包的路由路径只许官方形状**(面 B),**不许面 A** | `pack-sync.py` 校验 + 评审 |
| 9 | 🔴 **业务表 DDL 列名不许自造语义**,必带 `f_tenant_id` | `new-pack.sh` 模板 + 评审 |
| 10 | 🔴 **前端三处一字不差**(`urlAddress` == `guardModule` key == Route path) | `new-page.sh` + 移植的 `check-module.sh` |
#### 验收判据(做完必须全绿才算完成)
```bash
# 1) 新建一个空业务包,只写 spec,不碰任何平台层文件 ⇒ 全链路自动通
bash scripts/new-pack.sh ledger Ledger # 脚手架:生成 packs/ledger/{Cargo.toml,pack.toml,src/lib.rs,schema/001_init.sql}
# 2) 十二道闸门全绿 + 单测不减少
bash scripts/verify.sh # 新命令:build → 静态闸门 → 单测 → 尺子,打印耗时
# 3) 业务包可独立构建(不依赖内核)
cargo test -p sspf-pack-asset
# 4) 「加包不碰平台层」有钉子测试:git diff --name-only 只应出现 packs/<app>/ + 契约生成段
# 5) 加包后**没有手抄**痕迹:contract.md 的 [MODULE]/[ENDPOINT] 段是生成物
# 6) 🔴【集成期友好性】包的路径/列名能被官方侧对上(详见下面「集成期 checklist」)
```
#### 🔴🔴 集成期 checklist(不是本批做,是**现在就要能回答**的问题)
> 这张表的用途:**MVP 阶段每加一个业务包,就顺手填一遍** ⇒ 集成期不返工。
> 填不完的**当场就还债**(宁可现在多写 20 分钟,别集成时返工一天)。
| 检查项 | 怎么答 | MVP 期成本 | 不做的后果 |
|---|---|---|---|
| 包的端点在官方是**哪个 Controller 哪个方法**? | 用 `MIGRATION.md` §2.1 翻译表反查官方 Java 源码(本机 `~/Desktop/workspace/jnpf/jnpf-java-boot`) | 查 5 分钟 | 🔴 集成时**路径全要改** |
| 业务表的列名官方叫什么? | 对着官方 `JNPF-PostgreSQL.sql` 的同类表比 | 查 10 分钟 | 🔴 集成时**列名映射全靠人工** |
| 这个表的 `baseline_table` 叫什么? | 填进 `pack.toml` 的 `[[pack.tables]]` | 1 分钟 | 🔴 集成时记不住 |
| 业务表的 `f_tenant_id` 带了没? | 看 `schema/*.sql` | 0(模板自带) | 🔴 **复合主键缺列 ⇒ 导不进官方** |
| 这个业务要不要**按钮级/列级权限**? | 官方 `@SaCheckPermission` 的判据是什么 | 想 10 分钟 | 🔴 集成时**权限体系要重做** |
| 返回的 VO 形状官方长什么样? | 对着官方 `XxxListVO` / `XxxInfoVO` 抄字段清单 | 抄 10 分钟 | 🔴 集成时**前端读不到字段 ⇒ 静默降级** |
| 涉及文件上传/导出吗? | 是 ⇒ 记下来(官方走 `jnpf-file` 服务) | 标记 1 分钟 | 🔴 集成时**功能缺失** |
| 前端页面要接的接口清单 | `api/<模块>.ts` 里逐个列 | 已有 | 🔴 集成时**前端要返工** |
🔴 **一条经验**:上面 8 项里,**后 4 项(权限 / VO 形状 / 文件 / 接口清单)就是那 27 条 `partial`
里「形状欠」那 9 条 + 「自造」4 条的来源** ⇒ **在 MVP 阶段就把 VO 字段清单抄全**,
是整个两阶段路线里**性价比最高**的一件事(抄一次,省掉集成期逐条 debug)。
#### 明确不做(本批不碰,别偷跑)
- ❌ **L3 dylib 动态库**(`PLAN.md` §4.5):六条铁律(内存所有权 / catch_unwind / ABI 校验 / 热替换…)
是**另一个量级**的工作力,本批**只做 L2 静态链接**。
🔴 理由:PLAN.md §4.6 写得很清楚 ——「L2 是静态链接(编 30s),L3 才是运行期 dlopen」;
「不要对外承诺什么都能热更」。先把「链接就好」在 **L2** 做到真,再谈 L3。
- ❌ **WASM 执行器**(PLAN.md P3 交付项之一):低代码沙箱已有 Rhai,WASM 是第二实现,不急。
- ❌ **`pack export/import --format=baseline`**(双向迁移):属于 P3 的后一半,本批只做「包内声明 → 内核装载」这一半。
🔴 **但 `pack.toml` 的字段(`baseline_table` / `[[pack.tables]].ddl`)要按最终格式设计好**
⇒ 集成期做 export/import 时**不用改包格式**。
- ❌ **官方 Vue 前端的页面脚手架**(`views/<模块>/index.vue` + `api/<模块>.ts`
+ `router/routes/modules/<模块>.ts`)—— 那是**集成阶段**的事。
⇒ 本批只做 **React 三件套** 的 `new-page.sh` + 移植 React 技能的 `check-module.sh`。
⇒ 🔴 **不改官方 monorepo / 官方应用的任何文件**(`jnpf-web-apps-main`),那是集成期的事。
#### 🔴 前端在两阶段分别怎么办(2026-11-01 19:39 修正 → 20:10 按 React 模板再修正)
> ⚠️ **19:39 这一版仍然写错了**:当时说「前端**全程**都在官方 monorepo 里,两阶段的差别不在有没有前端,
> 而在前端的代码规范等级」。
> **20:10 用户纠正**:「你看看 `ssw-jnpf-lite-react` 的模版,这个就是前端 MVP 阶段 AI 友好的方向,
> **除了认证,其它都留给集成阶段**」。
> ⇒ **MVP 前端 = React 模板**(不是官方 vue);**官方 vue 是集成阶段的事**。
> ⚠️ **两次都写错同一个点** ⇒ 这条在下一轮开工时**先复核再动手**。
| | MVP 阶段(AI 怎么快怎么来) | 集成阶段(按官方规范) |
|---|---|---|
| 前端代码放哪 | **React + Vite**:`src/frontend/src/`(从 `ssw-jnpf-lite-rust` 复制,与 React 技能逐字节相同) | 官方 `~/Desktop/workspace/jnpf/jnpf-web-apps-main/src/`(Vue 3) |
| 认证 | ✅ **MVP 就做**(端点/参数/密文/返回/登出码**全部照官方契约**) | 换官方 `jnpf-oauth`(**同形 ⇒ 零改**) |
| 业务页面 | ✅ **只做薄壳原型**(列表 + 弹窗表单 + 删除)⇒ 够试业务规则 | ✅ 补齐全套(类型、权限控制、国际化、组件用法) |
| 权限配置 UI / 低代码表单 / 数据建模页 | ❌ **不做**(官方有现成的,MVP 不重复造) | ✅ 全做 |
| 加一个业务页面 | React 三件套:`api/<lc>.ts` + `views/<Ent>.tsx` + `App.tsx` 加一行 `<Route>` | Vue 三件套:`api/<模块>.ts` + `views/<模块>/index.vue` + `router/routes/modules/<模块>.ts` |
| 路由注册 | React Router 显式声明(`App.tsx`) | 🔴 **不用改配置** —— 官方 `import.meta.glob('./modules/**/*.ts')` + `mergeRouteModules`(读 `default` 导出)⇒ **放文件即注册** |
| 后端对接 | 面 A `/api/ssw/...` ⇒ **前端零改**直连本仓 Rust | 面 B `/api/{模块}/{资源}/...` ⇒ **前端零改**直连官方 Java |
| ⚠️ 缺口 | **前端完全没闸门**(`check-module.sh` 的 4 个前端接触点全打 `⏭`)⇒ 改错三处不一致**没人拦** | 同 ⇒ 集成前必须补 |
⇒ **本批(批次 12)对前端的动作**(在 ④ 里,已写入):
① `scripts/new-page.sh <app> <Entity>` —— 生成 **React 三件套** + 菜单登记提示;
② **移植** React 技能的 `scripts/check-module.sh`(9 个接触点,`--all` / `--live`)
⇒ 把「三处一字不差」这条从人工检查变成机器检查;
③ 🔴 **不碰官方 Vue 那一套**(集成期的事)。
🔴 **为什么这条值得单独做**:React 侧 `urlAddress` / `guardModule` key / Route path 三处不一致的后果是
**静默放行**(菜单显示了但守卫不命中)⇒ **不报错,只是权限失效** ⇒ 这是最该上闸门的一类。
🔴 **集成期搬 React → Vue 的对应关系**(React 技能 `MIGRATION.md` §「前端:React 原型 → jweb (Vue)」已写明):
- `cipher.ts` ↔ 官方 `defHttp` 拦截器(登出码 / ActionResult 解包)**1:1**;
- `api/<lc>.ts` 的 `request.get('/ssw/...')` ↔ `defHttp.get({ url: '/api/ssw/...' })`(**只差 baseURL 前缀**);
- ⚠️ **React 的 `<Route path>` 在 jweb 不存在** —— jweb 靠菜单挂载(`base_module.f_url_address`)自动注册路由;
- ⚠️ **jweb 请求头要多补 `Vue-Version: 3`**(官方 `addRequestInterceptor` 必发,本仓面 B 也靠它分流)。
#### ✅ 批次 12 完成状态(2026-11-01 22:00 实测)
| 交付物 | 状态 | 落地物 / 证据 |
|---|---|---|
| ① `sspf-sdk` 补 `routes()` + `crates/sspf-plugin` | ✅ | `PackRoute` 纯数据声明(包不依赖 axum);插件层按 `packs/*` 装载 |
| ② 两份拷贝打通 + PACK1 | ✅ | `modules/<app>.rs` 改 re-export;`check-arch` 新增 **PACK1 / AR8 / AR9**,4 例反自证全过 |
| ③ 业务 DDL 跟着包走 | ✅ | `packs/asset/schema/001_init.sql` + `include_str!` 编进二进制 ⇒ **单二进制部署**(运行时无 `packs/`) |
| ④ 契约登记自动生成 + 静态闸门提速 + `verify.sh` | ✅ | `scripts/pack-sync.py`(幂等,两次 md5 一致)+ `scripts/verify.sh`(**≈15s**) |
| ⑤ **前端三件套**(本轮新增) | ✅ | `src/frontend`(React MVP 模板)+ `scripts/new-page.sh` |
**加一个业务模块现在的实际成本(批次 12.5 之后 = 一条命令)**:
```bash
bash scripts/new-pack.sh crm Customer --name "客户" \
--columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend
bash scripts/verify.sh --fast # ≈17s 全绿才继续(含尺子自证)
```
它产出的东西(**全部从「业务决策」推导,不猜**):
| 产出 | 谁生成 |
|---|---|
| `packs/<app>/{Cargo.toml,pack.toml,schema/001_init.sql,src/lib.rs}` | `new-pack-gen.py`(真源:app / 实体名 / 列清单) |
| `src/backend/src/modules/<app>.rs`(面 A 适配器) | 同上(**MVP 前端走面 A**,没有它页面就是空的) |
| `src/backend/src/packs_gen.rs`(内核包清单) | `pack-sync.py`(**生成物**) |
| `modules/mod.rs` 的 5 个登记段 | `pack-sync.py`(**生成物**) |
| `src/backend/Cargo.toml` 的包依赖段 | `pack-sync.py`(**生成物**) |
| `docs/contract.md` 的 `[MODULE]` / `[MENU]` / `[ENDPOINT]` | `pack-sync.py`(**生成物**) |
| `src/frontend/src/{api,views}/…` + `App.tsx` 路由 | `new-page.sh`(`--with-frontend`) |
| `[RULER]` 的断言条数 | 实跑一次 `check-module` 登记(**只允许变大**,见下) |
⇒ 见 §「✅ 批次 12.5 完成状态」。
🔴 **前端接入的两个坑(已修,别再踩)**:
1. **端口**:React 技能模板的 vite proxy 指 NestJS `:30000`,本仓 Rust 后端是 **`:30010`**
(`main.rs` 的 `PORT` 缺省值)⇒ 照抄会在浏览器里表现成 `Network Error`,
最容易误判成「跨域 / 认证」,其实只是端口抄错。
2. **api 文件名**:`check-module.sh` 用 `lower(Entity)` 推文件名 ⇒ `DataResource` 要的是
`api/dataresource.ts`(**全小写**,不是 `dataResource.ts`)。`new-page.sh` 已按此生成。
要改这个约定**必须同时改尺子**,否则尺子会报「缺 export」而文件明明在那儿。
**前端闸门已转真检查**:`check-module.sh` 的前端接触点从 `⏭` 变成真断言 ⇒ 条数
**114 → 123**(契约 `[RULER]` 已同步)。这正是「尺子自证」在起作用——条数对不上就报
「尺子被改弱了(少了/多了断言)」,逼你把新条数**显式**登记,而不是悄悄绿灯。
**未做(明确留下,不是忘了)**:
- 前端**没有运行时闸门**:`npm run build` / `tsc --noEmit` 不在 `verify.sh` 里。
`verify.sh` 的定位是「零 node 依赖的静态闸门」,塞 node 会把它拖慢一个量级;
要验类型请单独跑 `cd src/frontend && npx tsc --noEmit`。
- 官方 **Vue 那一套一行没碰**(集成期的事)。
#### ✅ 批次 12.5 完成状态(2026-11-01 23:40 实测)—— 「加包 = 一条命令,漏接 = 直接报错」
**问题**:批次 12 把 spec 搬进包之后,加一个模块仍要手抄 **5 个后端文件**
(`packs/<app>/` 四个 + `modules/<app>.rs`),再带动 **4 处内核登记**
(`packs_gen` / `Cargo.toml` / `modules/mod.rs` 5 段 / 契约 3 段)。而其中两类漏接
**不报错**:漏 `merge` ⇒ 面 B 静默 404;漏 `ALL_MENUS` ⇒ 菜单不种 ⇒ 守卫查不到菜单
⇒ **越权放行**。
**做法**:把「内核怎么知道有这个包」从**手写**改成**生成** ——
| 派生位置 | 生成器 | 漏了会怎样(改之前) |
|---|---|---|
| `src/backend/src/packs_gen.rs` | `pack-sync.py` | 🔴 面 B 静默 404,无日志 |
| `modules/mod.rs` 的 5 段(`pub mod` / `ALL_SPECS` / `ALL_ROUTES` / `ALL_MENUS` / `router()`) | `pack-sync.py` | 🔴 面 A 静默 404 + 菜单不种 |
| `src/backend/Cargo.toml` 包依赖段 | `pack-sync.py` | 编译报错(响亮) |
| `docs/contract.md` 三段 | `pack-sync.py` | `check-contract` 红(响亮) |
- 新增统一包出口约定:每个包导出 **`pub struct Pack`** + **`pub const DDLS: &[(&str,&str)]`**
⇒ 生成器只要知道「目录名 + crate 名」就能拼出装载调用,**不需要理解每个包的常量命名**。
- `sspf_plugin::load_static()`:把「manifest 解析 + `PackSource` + `merge`」这段样板收进插件层
(**为生成而设计**)⇒ `bootstrap.rs` 的 `load_packs()` 只剩一行。
- **`scripts/new-pack.sh`**(+ `new-pack-gen.py`):一条命令生成 5 个后端文件 + 跑 `pack-sync`
+ 可选 `new-page.sh`。列清单只从 `--columns` 或 `--from-ddl` 来,**没有就拒绝**(不猜类型)。
- **`[RULER]` 条数自动登记**:每加一个模块断言数 **+30**(实测 123 → 153)
⇒ `new-pack-gen.py` 实跑一次 `check-module` 把数字登记掉,**只允许变大**
(变小 = 有人删了断言 ⇒ 拒绝并打印)。
**端到端验证(在 `/tmp` 的仓库副本里做,不污染工作区)**:
```
bash scripts/new-pack.sh probe Widget --name "探针" \
--columns "name:VARCHAR(200),price:DECIMAL(18,2),memo:TEXT" --with-frontend
→ 写 5 个后端文件 + 契约三段的 probe 行 + packs_gen/Cargo/mod.rs + 前端三件套
→ ✅ 已登记 153 条(原 123,+30 来自新模块)
cargo build --offline ✅ 3.7s
cargo test -p sspf-pack-probe ✅ 13 passed
cargo test -p ssw-platform --lib ✅ 102 passed
python3 scripts/pack-sync.py --check ✅ 幂等
bash scripts/verify.sh --fast ✅ 全绿 17.2s
```
**反自证(证明新闸门真的会红,不是「改瞎了还全绿」)**:
| 造的漂移 | 结果 |
|---|---|
| 从 `packs_gen.rs` 删掉 probe 的装载块(模拟「忘了跑 pack-sync」) | `--check` **rc=1**,指名 `packs_gen.rs` |
| 从 `modules/mod.rs` 删掉 `probe::WIDGET_MENU`(模拟「漏登记菜单」) | `--check` **rc=1**,指名 `modules/mod.rs` |
**本轮抓到并修掉的 2 个真 bug**(都是「加第二个包」才显形):
1. 🔴 **`check-contract-scan.py` 的守卫回落取了「排序后第一个包」**
(`for pkg in sorted(pack_orig)`)⇒ 有 `asset` + `probe` 两个包时,probe 的面 A 守卫
被推成 `asset/DataResource` ⇒ **CC6 假飘移 3 条** ⇒ 人会去改**对的**契约。
修法:按 `app` 精确匹配包;查不到就返回「推不出」(人工核对),不再瞎猜。
2. 🔴 **加包会误报 3 个单测**(`asset_pack_loads` / `pack_router…` / `health…==52`)——
全是**写死计数**的假闸门,加包必须先改测试。改成**结构性/推导式**断言:
每个实体必须「有 DDL + 有菜单 + 3 条路由」;health 的表数 =
`ddl_tables().len() + packs.ddls.len()`。
**未做(明确留下)**:
- `new-pack.sh` **不跑 `cargo build`**:它只保证「文件和接线都齐」,编译留给 `verify.sh`
(生成器不该假装自己是编译器;但**编译失败一定是响亮的**)。
- **一个模块文件仍只能有 1 个实体**(`ALL_ROUTES` 与 `ALL_SPECS` 按「每模块 3 条」配对)。
要加第二个实体 ⇒ 另建一个模块文件。放宽它需要引入「模块 → (起点, 条数)」映射表
⇒ 又多一处会漂的结构,暂不做。
- 包**只支持静态链接**(`kind = "static"`);`dylib` 热插拔仍未做。
- 官方 **Vue 那一套一行没碰**(集成期)。
#### 批次 12 顺延为批次 13(原计划,一字不改)
`fe-gap` 余下最大的 `system` 55 条 / `permission` 26 条 / `systemData` 32 条里挑
**有官方 `base_*` 表支撑**的;`workFlow`(104) / `onlineDev`(101) / `aiCenter`(75) /
`extend`(64) / `msgCenter`(50) 基本都是「本仓没这个模块」⇒
**先确认产品边界再动手**,做也只是恒空 stub。
**实现模板(照抄就行)**:`ORGANIZE_WRITE_FIELDS` / `POSITION_WRITE_FIELDS` 那一套
@@ -854,3 +1464,11 @@ ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh
1. 追加 `.workbuddy/memory/YYYY-MM-DD.md`:结论 / 坑 / 数字(闸门通过数)
2. 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的)
3. 若还有未完成项,**确认下一次定时任务存在**(`automation_update` list 可查),没有就新建
**当前挂着的定时任务**(2026-11-01 19:23 实查):
| 任务 | id | 触发 | 覆盖范围 |
|---|---|---|---|
| **ssw-platform 批次 12:框架固定包 + 业务模块链接就好** | `68997e3d-b08a-4f12-b0d1-003733b381c1` | **2026-11-02 09:00 一次性** | 批次 12 全部 4 项交付物 + 护栏 + 验收判据(prompt 已写全,自包含) |
| ssw-platform P2-b 收尾 | `1dcb55af-…` | 已过期(一次性,未删) | P2-b 已完成 ⇒ **可删** |
| 每日积分 | `82c41449-…` | 每日 08:00 | 与本仓无关 |
+41 -24
View File
@@ -1,38 +1,55 @@
# 加一个业务模块(AI 开发主线)
本文件是 **Rust 版**的操作手册。参照实现 = 内置的四个模块
> 🔴 **2026-11-01 起:一条命令。** 本文后半部分的「改哪个文件」清单写于批次 12 之前,
> **已过时**(`db/schema.sql` 不用改、`modules/mod.rs` 不用改、契约不用手抄)。
> 以本节为准:
>
> ```bash
> bash scripts/new-pack.sh crm Customer --name "客户" \
> --columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend
> bash scripts/verify.sh --fast # ≈17s 全绿才继续
> ```
>
> 它建 `packs/<app>/`(**真源**)+ `modules/<app>.rs`(面 A 适配器),
> 再把**四处生成位置**补齐(`packs_gen.rs` / `modules/mod.rs` 五段 /
> `Cargo.toml` 依赖段 / `docs/contract.md` 三段)。
> 生成物手改会在下次 `pack-sync.py` 被覆盖,而 `verify.sh` 第一步就会红。
参照实现 = 内置的四个模块
(`demo/DemoItem` · `shop/Product` · `books/Book` · **`asset/DataResource`(真实业务)**)
——**照抄一个最接近的,别从零想**;要加真实业务模块就抄 `asset.rs`。
——要读就抄 `packs/asset/`,它是完整样板。
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改哪儿、怎么验证」。**
> 契约红线见 [`SKILL.md`](SKILL.md) §「契约红线」。**本文件只讲「改了哪儿、怎么验证」。**
## 〇.5、一图看完全流程(先看一遍再动)
## 〇.5、它内部做了什么(排错时照着看)
```
1. db/schema.sql 建表(f_ 前缀 + f_id VARCHAR(50) + 软删列)
2. src/modules/<app>.rs 【新文件】spec + *MENU + 3 个 handler + 自己的 router()
3. src/modules/mod.rs 加 spec 进 ALL_SPECS + 加菜单进 ALL_MENUS + 加 router() 进 merge + 加路由进 ALL_ROUTES
4. frontend/src/api/<lc>.ts 3 个函数(list/save/delete)
5. frontend/src/views/<Ent>.tsx 列表页
6. frontend/src/App.tsx <Route path="/<route>">
7. docs/contract.md 附录 A 加五行:[MODULE] 一行 + [MENU] 一行 + [ENDPOINT] 三行
(本模块的 3 条端点)+ [FACE] 的 A 条数 +3
★ 期望值真源
⇒ bash scripts/check-module.sh <appCode> <Entity> 必须全 ✅
⇒ bash scripts/check-contract.sh 必须全 ✅(端点表 ↔ 代码)
8. scripts/perm-smoke.sh 追加该模块的断言(别新写脚本)
1. packs/<app>/src/lib.rs 【真源】EntitySpec + MenuSpec + PackRoute×3 + Pack + DDLS
2. packs/<app>/schema/*.sql 业务表 DDL(include_str! 编进二进制;**不进 db/schema.sql**)
3. packs/<app>/pack.toml 包清单(catalog;内核读的是 pack-sync 生成的 JSON 快照)
4. packs/<app>/Cargo.toml 只依赖 sspf-sdk(AR2:不许 axum / tokio / pglite)
5. src/modules/<app>.rs 面 A 适配器:pub use 包的 spec + 3 个 handler + router()
↓ 以下四处**全部由 scripts/pack-sync.py 从「packs/* + modules/*.rs」生成**
6. src/backend/src/packs_gen.rs 内核包清单(每个包一条 load_static 调用)
7. src/modules/mod.rs 五段:pub mod / ALL_SPECS / ALL_ROUTES / ALL_MENUS / router()
8. src/backend/Cargo.toml >>>GEN:PACK_DEPS 段
9. docs/contract.md 附录 A [MODULE] / [MENU] / [ENDPOINT] 的生成段
10. frontend/src/{api,views}/… + App.tsx 的 <Route>(new-page.sh,--with-frontend)
⇒ bash scripts/verify.sh --fast 必须全 ✅
```
**8 个文件 = 上面的 1–8**(其中 `modules/<app>.rs` 与 `modules/mod.rs` 是**业务层**)。
第 7 步漏了 ⇒ `check-module.sh` 直接判「契约 [MODULE] 里没有这个模块」退出 2;
`[ENDPOINT]` 漏了 ⇒ `check-contract.sh` 判「代码里的路由没被契约登记」红。
🔴 **漏了会怎样**(这就是为什么不再让人手抄):
| 漏哪一步 | 现象 | 报错吗 |
|---|---|---|
| 6(`packs_gen.rs`) | 面 B 端点 404,列表永远空 | ❌ **不报** |
| 7(`ALL_MENUS`) | 菜单不种 ⇒ 守卫查不到菜单 ⇒ **越权放行** | ❌ **不报** |
| 7(`router()`) | 面 A 404 ⇒ MVP 前端页面空着 | ❌ **不报** |
| 8(Cargo 依赖) | 编译失败 | ✅ 报 |
| 9(契约) | `check-contract` 红 | ✅ 报 |
🔴 **平台层(`src/platform/`)与入口文件(`src/backend/src/main.rs`)一个字都不用改** ——
加业务模块**不碰平台层**。
(对比 react 版要动 4 个后端文件;本仓**只动 `src/modules/` 下的 2 个文件** + `db/schema.sql`。)
🔴 **内置菜单也住在业务层**(`modules/<app>.rs` 的 `*_MENU: MenuSpec`)⇒ 由装配根
`bootstrap.rs` 注入平台层的种子 ⇒ 平台层只自带 5 条**系统**菜单。
🔴 这条分层由尺子钉住:`bash scripts/check-boundary.sh`(CP1–CP6)——
加业务模块**不碰平台层**,由尺子 `bash scripts/check-boundary.sh`(CP1–CP6)钉住:
平台层出现任何业务标识符(表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code)⇒ 红。
## 〇、命名约定(先想清楚再动)