记下:两档验证的分工(--fast 该接的接上了 / --lib 接上的活真能应答)、 两处反自证结果、以及「不同步 Save/Delete」「不在 new-pack.sh 里跑」两条边界。
116 KiB
HANDOFF —— 交给下一个 session 的现场交接
更新于 2026-11-01 19:00(面 B 批次 11 收尾 + 批次 12 方向决策), 20:10 追加「前端 MVP 用 React 模板、除了认证其它都留给集成阶段」。开工先读这一页 (尤其 §0-bis 的「下一轮的优先级改了」),再读
CLAUDE.md(硬约定), 最后看.workbuddy/memory/最近一天的日志(踩过的坑)。 无人值守时不要问用户,选最保守可行的方案继续,并把决策写回本文件。
0. ⚠️ 修正上一版口径(很重要)
上一版说「跑 pnpm 必须 dangerouslyDisableSandbox」。这条不完整:真正拦住 fs 的是
NODE_OPTIONS 里注入的 node-language-shim.cjs(brokered-fs),退沙箱它仍在,末尾报
CODEBUDDY_BROKER_OUTCOME_UNKNOWN — Broker request timed out。正确做法见 §2,用
env -u NODE_OPTIONS pnpm ... —— 实测 2169 包 46.5s 装完。
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 阶段的四条红线(违反了 = 集成时返工)
- 🔴 业务表的
base_*列名不许自创 —— 官方base_*DDL 逐字(JNPF-PostgreSQL.sql13227 行 / 331 张表,本机已有) ⇒ 业务表 DDL 从一开始就照官方列名写 ⇒ 集成时只导数据不导结构。 - 🔴 业务表的
f_tenant_id不许省(值恒"0",但列NOT NULL且参与复合主键(f_id, f_tenant_id))。 - 🔴 接口路径从第一天就用官方形状(面 B 的
/api/xxx/...)⇒ 集成时前端零改。 ⚠️ 面 A 路径(/api/ssw/...)是本仓自造的 ⇒ 集成时全部作废,只留给 Rust 终端场景。 - 🔴 返回形状宁可少字段,不许返错形状 ⇒ 官方前端遇到缺字段会静默降级(按钮恒显、树空)。
✅ 已经到位的部分(集成时直接搬,别重做)
| 项 | 证据 | 集成时 |
|---|---|---|
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)
$ 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 再解析
模板串),跟后端 routes.rs 做差集。只看本仓该有的 6 个前缀:
| 前缀 | 已覆盖 | 缺口 | 缺口主要是什么 |
|---|---|---|---|
permission |
54 | 62 | 个人设置 Users/Current/*(14)、Standing(6)、PermissionGroup(6)、Action(3)、导入导出 |
system |
29 | 208 | 大半是本仓没这个模块:printDev(15)/Dataset(16)/DataModel(11)/DataInterface(10)/InterfaceOauth(9)/DataSource(5)/PortalManage(4)/BusinessCategory(5)/Area(6)/BillRule(6)… |
oauth |
3 | 11 | 扫码登录、锁屏、验证码证书 |
message |
0 | 53 | 消息中心(本仓无表) |
file |
0 | 32 | 文件/网盘(本仓无表) |
extend |
0 | 53 | 示例模块 + 邮件 + 甘特图(本仓无表) |
| 合计 | 86 | 419 |
🔴 判断:419 里约 250 条属于「本仓没这个模块」,真做也只是恒空 stub。
剩下的真价值集中在 permission 那 62 条。所以下一轮按这个顺序做:
permission/Users/Current/*个人设置(14 条,个人中心要用)—— ✅ 批次 1(实际 23 条)permission/Standing/PermissionGroup/Action(15 条)—— ✅ 批次 2(实际 21 条)—— ✅ 批次 3(实际 25 条)system/System+system/SysConfig(17 条,系统配置页)✅ 批次 4 做完(实际 19 条)——新表message(53) / 低代码模块 ⇒ 批量恒空 stubbase_business_category/base_message/base_notice;业务分类(官方 38 行种子)+ 站内消息(列表/已读/回执/删除)+ 公告(增删改查 + 发布即逐收件人落消息)。 ⚠️ 只做了api/system/message.ts那 14 条(消息记录页 / 公告管理页用的),api/msgCenter/*(发送配置/账号配置/供应商/模板/监控/敏感词 —— 共 36 条) 是「消息中心运维后台」,本仓没这个产品 ⇒ 仍待定(见下条)。
被最多页面共用的接口(python3 scripts/fe-page-deps.py 的实测排序,按这个做收益最高):
DataModel/{}/Tables(12 页) / visualdev/OnlineDev/{}/Config(10) / ai/AiSupplier/Selector(10) /
BusinessCategory/treeList(9 ✅批次4) / Log(9) / workflow/operator/List(9) /
Dataset/{}/Actions/InfoByIds(9) / BasicDataType(9) / extend/TableExample 四个(9) / Tag/selector(8 ✅批次3)。
下一个(批次 5)建议:
✅ 批次 5 做完(实际 21 条)——新表 system/Log(5) + system/CommonWords(6) + system/BillRule(8)base_sys_log / base_common_words / base_bill_rule;
登录即落日志(Log 页与个人中心「登录日志」同一份数据)、审批常用语 CRUD + 使用计数、
单据规则 CRUD + 单号生成器(时间/随机/UUID 三分支 + 跨天归零 + 回写流水)。
顺手把 DictionaryData/All 从「恒空」改成真读字典 + 灌 businessType 13 行种子。
详见 §1「批次 5」小节。
~~下一个(批次 7)建议:数据建模的写面(POST/PUT/DELETE /DataModel/{linkId}/Table…
addFields+Copy+Export/Import,共 8 条)—— 这批要动真 DDL (CREATE TABLE/ALTER TABLE/DROP TABLE),必须先立两条护栏: ①base_*平台表禁止 ALTER/DROP(只允许看);② 表名/列名一律过白名单再拼 SQL。~~ ✅ 批次 7 做完(实际 8 条)——两条护栏都立了,且判据取 DDL 真源:
- ①
db_ident白名单([A-Za-z_][A-Za-z0-9_]*+ 双引号包裹)—— 唯一能拼字符串进 DDL 的入口; - ②
is_builtin_table=sspf_store::db::ddl_tables()⇒schema.sql里定义过的 35 张全部只给看 (不写死清单,加表自动受保护,不会「加了表忘了加护栏」)。 - 官方
checkTab的两道闸照抄:内置表DB101/DB102、表里有数据DB201/DB202。 - 🔴
update是重建表(官方也是),所以「有数据就拒」这条闸不能省 —— 省了就是「改个注释,数据全没」。 - 🔴
addFields不要求主键(主键早在表上):要求了会让「加一列」永远失败; 且只ADD COLUMN IF NOT EXISTS,新列一律可空(给非空表加NOT NULL列必失败)。 - 🔴
Copy用LIKE … INCLUDING ALL(官方按字段清单重建会丢自增);type=1的数据搬运写成显式列清单 ——INSERT … SELECT *会被check-archMEM1 判成整表载入。 deleteAllTable有意收窄:只删「不在schema.sql里」的表(官方全删,含系统表 ⇒ 在这仓等于自杀)。Export/Import恒400+ 人话(没有文件服务 / 没启 multipart),不返假下载地址。
做完这三页(/dataCenter/dataModel、/dataCenter/dataSource、/dataCenter/basicField)
就真正可用了。再往后是 systemData 的 Dataset/DataInterface 其余族。
~~批次 8 候选:systemData 的 Dataset(16) / DataInterface(10) / InterfaceOauth(9)
system/printDev(15)。~~ ✅ 批次 8 做完Dataset(实际 18 条)——见 §1「批次 8」小节。
- 它是全仓唯一执行用户手写 SQL 的地方 ⇒ 三道护栏(只
select/with、不许分号、 按词边界扫危险动词)+ 变量全走$N绑定。 Dataset是AutoComplete/PopupSelect/InputTable/SelectModal/ 报表 / 打印 / 大屏的共同底座(fe-page-deps里Actions/InfoByIds被 9 个页面共用)⇒ 收益比条数大。- ⚠️ 只做
sqlType=1(手写 SQL);图形化配置式(sqlType=2)/ HTTP / 静态数据一律400+ 人话。 - 下一个(批次 9):
DataInterface(12) +InterfaceOauth(11) +system/printDev(17)。printDev是本仓没有打印设计器 ⇒ 多半只能恒空 stub(先看onlineDev/printDev/Form.vue再定)。✅ 批次 9 做完(实际 39 条)——见 §1「批次 9」小节。 - 批次 10 候选:从「本仓确有官方
base_*表支撑」的候选族里挑,选了权限配置族:Signature(7) +ModuleButton(7) +ModuleColumn(6) +ModuleForm(6) +AdvancedQuery(5)。✅ 批次 10 做完(实际 31 条)——见 §1「批次 10」小节。 - 批次 11 候选:继续沿权限族往下挑,选了数据权限三件套:
ModuleDataAuthorize(6) +ModuleDataAuthorizeScheme(5) +ModuleDataAuthorizeLink(4)。✅ 批次 11 做完(实际 15 条)——见 §1「批次 11」小节。
2026-11-01 实测(python3 scripts/fe-gap.py):合计 331 / 900(36.8%);
permission 111/137(81.0%)、system 141/196(71.9%,批次 4 47→66、批次 5 66→84、
批次 9 84→101、批次 10 101→132、批次 11 132→141)、
systemData 74/106(69.8%,批次 6 从 0 起、批次 7 29→35、批次 8 35→52、批次 9 52→74);
剩下体量最大的仍是 workFlow(104) / onlineDev(101) / aiCenter(75) /
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 收尾)
📌 当前数字(以此为准,下面各批的「当时数字」仅存档):
- 契约端点 376 条(面 A 28 + 面 B 346 + 两面共用 2);
tables→ 52。 cargo test --offline --workspace= 550 passed / 0 failed。- 十二道闸门全绿;
check-contractPASS=10 FAIL=0,官方端点覆盖 365/372 (implemented 338 / partial 27 / absent 7;oos 6 单列)。 python3 scripts/fe-gap.py:合计 331 / 900(36.8%),permission111/137(81.0%)、system141/196(71.9%)、systemData74/106(69.8%)。 (批次 9 收尾时此处写的 252/28.0% 是批次 8 的旧数,批次 9 实测 291/32.3%,此处已更正。)- 🔴 数据建模三页(
/dataCenter/dataModel/dataSource/basicField)现在真能用了: 建表 / 改表 / 加字段 / 删表 / 复制 / 预览 / 导出(明说不支持)全通, 平台表(schema.sql里的 52 张)与「有数据的表」一律禁改禁删。 - 🔴 数据集(
/dataCenter/dataset)真能跑 SQL 了:这是全仓唯一执行用户手写 SQL 的地方, 三道护栏 + 变量全走$N绑定。它是AutoComplete/PopupSelect/InputTable/SelectModal/ 报表 / 打印 / 大屏的共同底座 —— 这一批之后那批通用组件不再是空壳。 - 🔴 数据接口(
/dataCenter/dataService)真能取数了:复用数据集那套执行面(SQL 只读 +$N绑定),Export明说不支持。接口认证(/integrationCenter/openApi)与 打印模板(/onlineDev/printDev)也落地了;打印模板只存设计 JSON、不渲染 (本仓无渲染引擎 ⇒Export/BatchData恒400+ 人话)。 - 🔴 权限配置族落地了(批次 10):电子签章、按钮权限、列表权限、表单权限、 高级查询方案共 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–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 后数字会变,别写死)。- 长期架构与路线看
PLAN.md(尤其判断 ⑥ 内存约束、判断 ⑦ 执行器、§4.5 动态库 ABI)。
前端侧(未变):✅ 浏览器里真跑起来了,用户管理页可渲染、列表/新增/编辑/删除全部可用。
-
登录
admin/123456→ 进/home→/permission/user正常渲染,左侧分组树 + 右侧表格有数据, 整页零非 200 请求(fetch/XHR 双钩子实测[])。 -
机构管理
/permission/organize也正常渲染(空状态,零报错)。 第二波(04:00–05:00)当时的数字(已过期,仅存档): -
契约端点 207 条(面 B 177 条);
tables→ 26(新增base_group、base_position、base_dictionary_type、base_dictionary_data、base_user_extra、base_sign_img、base_standing、base_permission_group、base_action)。 -
六闸全绿:
check-module 114/check-boundary 11/check-contract 10/check-citations 4/perm-smoke 43/perm-smoke-jnpf 23,cargo test230 全过。 -
官方端点台账覆盖 165/172(implemented 160 / partial 5 / absent 7)。
-
浏览器实测 5 个页面零非 200:用户管理、机构管理、角色管理、菜单管理、岗位。 菜单管理页能正常显示树(系统管理 → 用户/角色/机构/菜单管理)。
批次 2(2026-10-31 08:00–09:00)做了什么
permission/Standing(8) + permission/PermissionGroup(8) + permission/Action(5) = 21 条面 B 端点,
新增官方表 base_standing(15 列) / base_permission_group(16 列) / base_action(15 列)。
官方 DDL 逐字对齐(行号已核对 JNPF-PostgreSQL.sql):
base_action:1 / base_permission_group:3278 / base_standing:4071。
🔴 官方陷阱已照抄:base_action.f_enabled_mark 是 VARCHAR(11)(不是 INTEGER)⇒
投影用 COALESCE(f_enabled_mark,'0'),不加 integer CAST。
🔴 官方语义已对齐:
base_standing.f_is_system:1=系统身份 / 2=自定义 ⇒ 新建默认写 2,投影归一化成isSystem0/1。base_action.f_type:1=自定义 ⇒ 新建强制写 1(前端record.type == 1 ? '自定义' : '系统')。PermissionGroupController.list会用userService.getFullNameByIds把f_permission_member的 id 串换成用户名串 ⇒ 本仓用子查询string_agg(...)做同样的替换。
🔴 本轮踩到并解决的 4 个真 bug(都有回归测试 + 反自证)
| # | 症状 | 根因 | 修法 |
|---|---|---|---|
| ① | GET /PermissionGroup/PermissionMember/{id} → 500 / data:null |
f_id = ANY($1::text[]) ⇒ pglite-rs 把 $1::text[] 当成 PG 数组类型 _text |
改 ANY(string_to_array($1::text, ','))(函数在 SQL 里做 ⇒ 参数仍是 text) |
| ② | DELETE /PermissionGroup/{id} → 500 42P18 |
软删 base_authorize 的 SQL 带了 $1 但 WHERE/赋值里没用到 ⇒ PG 拒「无法确定 $1 类型」 |
把 f_delete_user_id = $1::text 写进 SET(既是审计列,也用掉参数) |
| ③ | DELETE /Standing/{id} 后关联残留(静默) |
软删关联的占位符与参数顺序错位(SQL $1=item_type、$2=item_id,参数传 [account, id]) |
rel = [item_type, id, account] + SQL 改 $1/$2/$3 对齐 |
| ④ | 权限组列表 permissionMember 返uuid 串 |
漏了官方的 getFullNameByIds 替换 |
子查询 string_agg 换成人名串 |
回归测试:src/backend/tests/batch2_it.rs(4 条,每个钉一个 bug)。
反自证全部做过:逐个把修复回退 ⇒ 测试精确复现原始报错(cannot convert between String and _text /
42P18 / 关联残留 n=1 / uuid 串)⇒ 恢复后 4 条全过。
批次 3(2026-10-31 21:40–22:10)—— 应用中心 + 系统配置
31 条面 B 端点:/api/system/System(13:列表/详情/新建/改/删/复制/置顶/偏好/开发者授权×3/Selector/userAuthList)
/api/system/SysConfig(8:参数读写/第三方配置读写/管理员列表/设置/企业微信·钉钉连通性测试)/api/system/SynThirdInfo(4:同步/统计/清空/失败清单)/api/system/Tag(6:列表/详情/新建/改/删/selector —— 应用中心页一进来就拉selector?enCode=AppTags)。
- 新表三张(官方 DDL 逐字):
base_system_top(置顶按f_user_id + f_type记账)、base_sys_config(f_category + f_key → f_value的键值表)、base_tag(标签)。 - 🔴 老库补表:
Db::ensure_schema原先见到base_user就早退 ⇒ 后加的表在老库上 永远不存在。现在会按schema.sql逐表探to_regclass,缺哪张补哪张 (DDL 仍以schema.sql为唯一真源,不另写迁移脚本);单独测试见tests/schema_upgrade_it.rs。 - 🔴 尺子自身的 bug 修了:
check-contract-scan.py判面 B 守卫时只认模块名jnpf与函数require_login_jnpf—— 文件早已改名face_b.rs/require_login_face_b⇒ 整片面 B 的 CC6 守卫检查静默失效(只打 warning)。两个名字都认之后恢复生效。 - 复制应用只复制应用行(菜单/表单资源不复制)⇒
[OFFICIAL]记partial; 应用授权的devUsers存f_user_id逗号串、不写base_authorize⇒ 也记partial。 - 企业微信/钉钉连通性测试恒业务失败(未接 SDK)—— 刻意不假装成功。
批次 4(2026-10-31)—— 消息业务分类 + 站内消息 + 公告
19 条面 B 端点:/api/system/BusinessCategory(7:树/详/增/改/删/treeList/selector)
/api/message(5:列表/全部已读/读消息/删记录/回执)/api/message/Notice(7:列表/增/详/改/删/发布/回执人列表)。
- 新表三张(官方 DDL 逐字):
base_business_category/base_message/base_notice; tables 26 → 29。 - 🔴 业务分类是平台字典,不是用户数据:官方初始库灌 89 行(一级 + 二级 + 三级)。
本仓在
platform/seed.rs::BUSINESS_CATEGORIES灌 38 行(5 个一级 + 33 个二级), id 沿用官方雪花 id(f_category存的就是这些 id 串,改 id 官方历史消息就错位)。 三级是「消息事件」粒度(flow_todo_remind之类),没有消息行时展示不到 ⇒ 暂不灌。 - 🔴
base_message一行 = 一个收件人(f_user_id是收件人,发件人在f_creator_user_id) ⇒ 所有查询必须带f_user_id = 当前用户,漏了就是串号。 - 🔴 公告发布是全链路的唯一消息来源:
PUT /Notice/{id}/Actions/Release置f_enabled_mark=1后逐收件人插base_message(收件人为空 ⇒ 全体启用用户),f_category拼「公告一级 id,公告提醒二级 id」⇒ 消息记录页按二级页签过滤、 按一级enCode显示类型名,两者同时成立。不落这一步,消息记录页永远是空的。 - 🔴
ReadInfo会写库(f_is_read0⇒1),且f_is_read=2(已回执)时不回退 —— 前端「点开就变已读」全靠它,别当纯查询。 - 🔴 用户标签要按
f_id与f_account双键查:本仓写f_creator_user_id存的是账号 (seed.rs的ADMIN_ACCOUNT),官方历史数据里是 id ⇒ 只查一种另一种永远显示空。 - 已知
partial:POST /message/Notice/List的时间区间过滤未做 (releaseTime/creatorTime/expirationTime三个区间参数接受但忽略); 分类删除是软删(官方物理删,本仓偏保守)。 - 回归测试
tests/batch4_it.rs(3 条):分类树/裁剪/两段式 selector/判重、 发布扩散、读+回执+删除(含「已回执不回退」与「只删自己的」)。
批次 5(2026-11-01)—— 系统日志 + 审批常用语 + 单据规则
21 条面 B 端点:/api/system/Log(6:列表/详情/删一条/按类型清空/清登录日志/模块名)
/api/system/CommonWords(7:列表/selector/详/增/改/删/使用计数)/api/system/BillRule(10:列表/selector/详/增/改/启停/删/导出/导入/生成单号)。
- 新表三张(官方 DDL 逐字):
base_sys_log(30 列)/base_common_words/base_bill_rule;tables 29 → 32。 - 🔴 登录日志此前根本不存在:
self_system_log(个人中心「登录日志」)是手写的恒空分页。 本轮在auth.rs::login_handler里落一行f_type=1(成功f_login_mark=1、失败=0且f_description存失败原因), 失败只打 stderr 绝不冒泡(日志写坏了不能把登录搞挂)⇒Log?category=1与Users/Current/SystemLog共用同一个log_page(.., 1, Some(uid)),两处同时变真。 - 🔴
DELETE /Log/{type}的{type}是分类号不是 id(官方deleteLoginLog就是删f_type=1全部)。 实现成「删某一条」的话,管理员点「一键清空」会静默什么都不做。路由上/Log/{id}的 GET(详情)与 DELETE(清空) 共用同一段名{id}(matchit 不允许同位置两个参数名),handler 内部按分类号解析。 - 🔴
to_char的占位符不能照搬官方:PG 的HH是 12 小时制、毫秒叫MS不叫SSS⇒ 单独写to_char_pattern()把小写官方格式映射成 PG 格式,否则会生成「下午 03 点」的错号。 - 🔴 改单据规则时只有四个条件变了才清流水(前缀/后缀长度、位数、日期格式)——
照抄官方这段判断,不然「改个描述」也会把
f_this_number清掉,已发出的号就重号了。 - 🔴
f_this_number/f_output_number只由BillNumber回写,不在*_WRITE_FIELDS里(14 列不含这两个); 规则被发过号(f_output_number非空)就禁删(400 单据已经被使用,不允许被删除)。 - 🔴 常用语判重按
文本 + 类型同档(公共/个人各一套),且CommonWordsController官方一个@SaCheckPermission都没有 ⇒ 故意不挂guard(),只做require_login_face_b。 - 已知
partial:DELETE /Log/{id}的dataInterfaceId收窄未做;BillRule的Export/Import恒业务失败(本仓没有文件服务,刻意不假装成功)。 - 顺手修:
GET /api/system/DictionaryData/All原先恒空(businessType之类下拉全空且不报错) ⇒ 改为真读两张字典表 +seed.rs灌businessType13 行(isTree=0)。 - 回归测试
tests/batch5_it.rs(6 条):登录落日志双读者一致、三条删除路径语义不同、 常用语 CRUD + 计数、单号时间格式 + 跨天归零、规则守卫、随机/UUID 分支。
批次 6(2026-11-01)—— 数据连接 + 数据建模只读面
16 条面 B 端点:/api/system/DataSource(8:列表/分组/下拉树/详/增/改/删/测试连接)
/api/system/BasicDataType(1:基准类型列表)+/api/system/CommonFields(1:常用字段列表)/api/system/DataModel/**(6:表清单 / 表+视图 / 表信息 / 字段 / 字段下拉 / 数据预览)。
- 新表三张(官方 DDL 逐字):
base_db_link(22 列)/base_data_type/base_common_fields;tables 32 → 35。 - 两张平台字典照官方初始库逐字灌(
seed.rs):DATA_TYPES7 行 +COMMON_FIELDS10 行。 🔴 前者是数据建模表单的类型下拉唯一数据源,空了表单虽能开但建不出表(不报错)。 - 🔴
DataSource/Selector的第一组第一项必须是合成的「默认数据库」(id="0"):dataCenter/dataModel/index.vue:158-166取list[0].children[0]当默认连接, 少了它dbType是undefined⇒ 建表表单判不出库类型。本仓只有一个库 ⇒linkId一律忽略。 - 🔴
Preview绝对不能写SELECT *:query_json_params会把f_*列名归一成 camelCase (f_en_code⇒enCode),而Preview.vue:62取的是record[column.field.toLowerCase()](原样列名)⇒ 整张表会空白且不报错。必须逐列"col" AS "col"(双引号别名是权威名)。 - 🔴
hasTableData必须真探测(EXISTS(SELECT 1 …)):前端据此把已有字段锁成不可改 (Form.vue:113-115),给false会让用户在有数据的表上删列 ⇒ 直接丢数据。 - 🔴 详情不回明文密码(
password恒空串);update传空串 = 不改密码(前端编辑时密码框本来就空)。Actions/Test恒业务失败(本仓没有外部驱动层)—— 刻意不假装连上了。 - 表名/列名收窄成
[A-Za-z_][A-Za-z0-9_]*([db_ident],比valid_table宽一点:官方允许_开头), 只有Preview会把表名拼进 SQL ⇒ 这段白名单 + 双引号是唯二的注入防线。 - 已知
partial:dbType保持编码原样(官方换字典中文名,本仓没灌「系统数据连接」字典);CommonFields只校验登录(官方要dataCenter.dataModel|dataCenter.basicField任一, 本仓后者还没登记成点权限);tableName/fieldName取 PG 注释,本仓 schema.sql 没写COMMENT ON⇒ 全是空串(数据建模页「说明」列会空,想改就补COMMENT ON)。 - 🔴 尺子也改了一处:
check-contract-scan.py原先只认guard(&state,&headers,CONST), 新增guard_any(&state,&headers,&[A,B])的推导(契约里写A|B,顺序即代码里的顺序) —— 官方@SaCheckPermission(..., mode=OR)那几处就靠它,否则整条只能打「推不出」警告。 - 回归测试
tests/batch6_it.rs(5 条):连接的增删改查 + 默认库契约 + 软删三处一致、 两张字典的 7/10 行与dataTypeName联查、表清单分页/关键词/字段归一/hasTableData、 预览分页与单字段模糊、未登录 602。
批次 7(2026-11-01)—— 数据建模写面(真 DDL)
8 条面 B 端点:POST/PUT /DataModel/{linkId}/Table(建表 / 改表)
PUT …/addFields(加字段)+DELETE …/Table/{tableName}(删表)DELETE …/deleteAllTable+POST …/Table/{t}/Actions/Copy+GET …/Actions/Export+POST …/Actions/Import。
- 🔴 两条护栏,缺一不可:
① [
db_ident] 白名单([A-Za-z_][A-Za-z0-9_]*+ 双引号)—— 全仓唯一能把字符串拼进 DDL 的入口; ② [is_builtin_table] =sspf_store::db::ddl_tables()⇒schema.sql里定义过的 35 张全部只给看。 🔴 判据取 DDL 真源而不是在 handler 里再抄一份清单 —— 抄一份的后果是「加了表忘了加护栏」, 新表能被用户在建模页一键删掉。 - 🔴
update是重建表(官方creTable→dropTable→reTableName)⇒「表里有数据就拒」(DB202) 这条闸不能省:省了就是「改个表注释,数据全没」。本仓实现成DROP TABLE old; CREATE TABLE new …同一批交给Db::exec(simple protocol ⇒ 隐式事务), 比官方那三步少一个「删了旧表但新表没建起来」的中间态。 - 🔴
addFields不要求主键:主键早在表上,还要求「必须选一个主键」会让**「加一列」永远失败**。 这条是实测踩到的(第一版照抄 create 的校验 ⇒ 400「请选择一个字段作为主键」)。 且只ADD COLUMN IF NOT EXISTS、新列一律可空(给非空表加NOT NULL列必失败)。 - 🔴
Copy用CREATE TABLE … (LIKE … INCLUDING ALL):主键 /NOT NULL/DEFAULT/IDENTITY一起带过去。官方是「读字段清单再重建」⇒ 复制出来的表丢自增。type=1的数据搬运写显式列清单(INSERT INTO dst (c1,c2) SELECT c1,c2 FROM src)—— 写SELECT *会被check-arch的 MEM1 判成「整表载入内存」。 - 🔴
deleteAllTable有意收窄:官方删getTableList的全部表(含系统表, 在这仓等于把平台自己拆了 ——base_user一没就再也登不回来,种子只在空库上跑) ⇒ 本仓只删「不在schema.sql里」的表,也就是用户自己从建模页建的。 - 🔴
dataLength对decimal必须带小数位(18,4而不是18):只给精度的话, 前端编辑一次表就把numeric(18,4)改成numeric(18,0),静默丢精度。 改的是db_field_rows的numeric_precision || ',' || numeric_scale。 Export/Import恒400+ 人话(没有文件服务 / 没启axum/multipart), 不返假下载地址(前端会拿它去location.href,得到一个 404 页面)。- 回归测试
tests/batch7_it.rs(8 条):建表往返 + 重名、五类非法 schema、 内置表禁改禁删、改表重建 + 改名、加字段只追加、有数据的表冻结、 复制守卫 + 清空只删非内置、导出导入诚实失败。
批次 8(2026-11-01)—— 数据集(真执行 SQL)
18 条面 B 端点:/Dataset 的 GET/POST/PUT/DELETE + getList + previewSql
fields+GetParam/{id}+{id}/get+{id}/save+{id}/Actions/{Export,Copy,Preview,List,InfoByIds,getRes}Actions/Import。新表base_data_set(26 列)/base_data_set_relation(13 列),tables35 → 37。
- 🔴 这是全仓唯一执行用户手写 SQL 的地方(数据连接那条只是存配置)。三道护栏见
[
dataset_sql_guard]:① 去尾分号后必须select/with开头;② 全文不许再有;(pglite 的exec走 simple protocol,多语句会一起跑);③ 按词边界扫危险动词 (insert/update/delete/drop/truncate/alter/create/grant/revoke/copy/vacuum/merge)与 文件/延时函数(pg_read_file/pg_ls_dir/lo_import/pg_sleep/dblink…)。 - 🔴 按词边界而不是子串:
update_time/create_id这种别名必须放行 —— 子串匹配会把 一批正常的业务 SQL 全拒掉(测试里专门钉了这一条)。 - 🔴 变量只走绑定:
${xxx}/@xxx一律转成$N+ 参数数组,绝不拼进文本。 与官方两处有意不同:官方找不到值时原样保留变量名(结果是一条非法 SQL,用户看到 PG 的语法错);本仓直接400 缺少参数 xxx。官方空集合替换成一个空格(in ( )语法错); 本仓替换成NULL。 - 🔴
getRes用的是 body 里的dataConfigJson,不是库里的 —— 设计器边改边试跑, 读库永远是上一次保存的 SQL。 - ⚠️ 列名靠「执行 1 行」反推:
row_to_json没有行就没有键 ⇒ 空结果集拿不到列名,fields返回空数组(官方走 JDBC 元数据,本仓做不到)。写进[OFFICIAL]的implemented备注里。 - 🔴 列表与详情的形状不同:列表
DataSetListVO的type/returnType是中文名 (SQL语句/列表数据),详情DataSetForm里是数字。同一份投影,两个整形函数。 - 🔴
{id}/save的variateJson收下不落库(本仓没有base_data_interface_variate表),{id}/get恒回"[]"—— 形状对上,内容为空,不假装存了。 - 🔴
SELECT *会被check-archMEM1 判红(终端内存预算 120MB)。而这里列名由用户 SQL 决定、拿不到清单 ⇒ 写成jnpfs.*(带表别名,语义等价,且每句都自带LIMIT)。 InfoByIds的propsValue过db_ident白名单 —— 它要拼进 SQL 的列名位, 不过白名单就是一个注入口(测试里用code" ; drop table base_user --钉住了)。previewSql只支持sqlType=1(原样回 SQL);图形化配置式 / HTTP / 静态数据一律400+ 人话。- 回归测试
tests/batch8_it.rs(6 条):形状与 CRUD(含「只改名称不误判重」)、getList剔isSystem参数、绑定执行(含引号注入串 ⇒ 0 行)、护栏五拦一放、 设计器往返 +getRes用 body、InfoByIds顺序对齐 + 导出导入诚实失败。
批次 9(2026-11-01)—— 数据接口 + 接口认证 + 打印模板
39 条面 B 端点:DataInterface(12) + InterfaceOauth(10) + printDev(17)。
新表 6 张:base_data_interface / base_data_interface_oauth / base_data_interface_user /
base_data_interface_log / base_print_template / base_print_version,tables 37 → 43。
🔴 DDL 名 ≠ 实体名(照抄官方时踩的坑):PrintDevEntity → base_print_template
(不是 base_print_dev);PrintVersionEntity → base_print_version;
InterfaceOauthEntity → base_data_interface_oauth。
- 🔴 点权限编码三套并存(判据都是
base_module.f_en_code):dataCenter.dataService(数据接口)/integrationCenter.openApi(接口认证)/onlineDev.printDev(打印模板)。官方没加@SaCheckPermission的那几条 (getList/GetParam/Preview/Selector/WorkSelector/getListOptions/BatchData)在本仓只要求登录(require_login_face_b)—— 与官方一致。 - 🔴 数据接口的
Preview复用数据集那套执行面(SQL 只读 +$N绑定 + 三道护栏), 官方另有 API / 静态数据两种类型 ⇒ 本仓400+ 人话(不假装支持)。 - 🔴
GetParam是裸数组(官方ActionResult<List<DynamicForm>>)—— 不是{list:[…]}。 - 🔴 接口认证的
SaveUserList是本仓拆出来的独立端点:官方是在create/update里内联保存用户清单(InterfaceOauthController.java:125),本仓为了让前端saveUserList能单独调用而拆开(等价语义,[OFFICIAL]备注里写明了)。 - 🔴 打印模板没有渲染引擎 ⇒
Export/BatchData恒400+ 人话 (不返假下载地址、不返空数据);Save/Version/*只存设计 JSON。 - 🔴 打印版本的发布语义:
Save的type=1即发布 ⇒ 旧的已发布版本归档(state=2)、 新版本state=1、模板state=1;type=0只存 JSON 不发布。 - 🔴 版本删除的三道闸,顺序照抄官方(
PrintDevController.java:332): ① 只剩一个 ⇒至少保留一个版本(官方 SYS043); ②state=1⇒已发布版本不可删除(SYS044); ③state=2⇒已归档版本不可删除(SYS045)。 ⇒ 顺序不能换:只剩 1 个时先命中①,测不到②③(测试里专门复制出第二个版本再测)。 - 🔴
Selector是「分类节点 + 模板叶子」的树(官方PrintDevTreeModel), 且只含state=1(已发布)的模板 ⇒ 草稿模板不该出现在下拉里。 - 🔴 版本列表
fullName=打印版本V{n}(官方versionList逐字), 返回裸数组(官方ActionResult<List<PrintVersionListVO>>)。 - 🔴 复制模板要连版本一起复制(官方
copyPrintdev也复制版本); 副本名加「副本」+ 5 位 uuid 前缀,编码也换掉(撞名/撞码靠 uuid 天然避开)。 - 回归测试
tests/batch9_it.rs(9 条):数据接口双判重 + 只改名称不误判重 + 软删、GetParam裸数组 + 导出诚实失败、接口真取数 + 禁用后拒绝、接口认证判重 +getAppIdUUID +interfaceSelector两棵树、打印建模板带首版本、Save发布归档、版本删除三闸、Selector树只含已发布 +Export/BatchData诚实失败、复制带版本。
🔴 本批踩到并解决的 2 个真 bug
interface_oauth_create的 INSERT 报42701 column "f_app_id" specified more than once—— 种子列里放了f_app_id,而io_write_fields又把 body 的appId映射到同一列 ⇒ 列出现两次。修法:appId只走写字段路径(body 没给才补 uuid),不再单独塞列。 (这类「种子列 + 写字段表撞车」的坑,data_interface_create/print_dev_create也有同款结构, 写新表时要一起检查。)sspf-store的表数断言停在 37 ⇒cargo test --workspace直接红 2 条 (schema_sql_has_expected_table_count/ddl_tables_parses_every_create_table)。 🔴 加表必须同时改三处:schema.sql、main.rs的BASE_TABLES、crates/sspf-store/src/db.rs的两处断言(后者容易漏 —— 它在另一个 crate 里)。
批次 10(2026-11-01)—— 权限配置族(电子签章 / 按钮 / 列表 / 表单 / 高级查询)
31 条面 B 端点:Signature(7) + ModuleButton(7) + ModuleColumn(6) +
ModuleForm(6) + AdvancedQuery(5)。
新表 6 张:base_signature / base_signature_user / base_module_button /
base_module_column / base_module_form / base_advanced_query_scheme,
tables 43 → 49。
🔴 点权限有两种形态,判据都是 base_module.f_en_code(管理员在 SQL 前短路):
- OR 两码(
guard_any):ModuleButton/ModuleColumn/ModuleForm三族官方是@SaCheckPermission(value={"permission.resource","appConfig.appResource"}, mode=OR)⇒ 满足其一即可。 - 无点权限、只需登录(
require_login_face_b):Signature与AdvancedQuery官方控制器根本没加@SaCheckPermission⇒ 与官方一致,不要自作主张加权限。
🔴 enCode 有「写时前缀化 / 读时剥除」的对称语义(官方 ModuleColumnController.java:184-195):
fieldRule == 1⇒ 落库值 =jnpf_+bindTable+_jnpf_+enCodefieldRule == 2⇒ 落库值 =childTableKey+-+enCode- 单条路径只在「菜单存在」时套前缀(官方判据
moduleService.getInfo(moduleId) != null); 批量路径无条件套前缀(官方批量不看菜单是否存在)—— 两条路径行为不一样,别统一。 - 读回时剥掉前缀还原成原始
enCode(-取其后;再去jnpf_<bindTable>_jnpf_)。
🔴 官方常量(JnpfConst.java:170,175):SIDE_MARK_PRE = "jnpf_"、
SIDE_MARK = "_jnpf_" —— 就是上面那个前缀的来源。
🔴 「批量落库要么全成要么全败」是两族共有的语义:
ModuleButton/selectActions:逐条判重,任一撞 ⇒ 整体失败且一条都不落库; 落库时parentId = "-1"(官方selectActions把 parentId 置"-1"表示根)、enabledMark = 1、新 id。ModuleColumn/ModuleForm批量创建:批内撞码也失败(HashSet 去重),同样一条都不落库。
🔴 形状差异容易踩:
Signature列表的userIds是字符串(多个授权人用;连接,官方StringJoiner), 详情的userIds是数组 —— 同一字段两种形状,别写混。Signature的名称与编码是两次独立判重 ⇒ 分别报「名称不能重复」「编码不能重复」。Signature的userIds变化 ⇒ 先全删后全插(官方signatureUserMapper.delete(id)后重建)。AdvancedQuery的列表是ListVO({list:[…]})不是PageListVO; 且getList/getInfo/delete都按f_creator_user_id = 当前用户过滤 ⇒ 别人的方案看到的是「数据不存在」/「删除失败,数据不存在」。 但官方update是updateById(不校验归属)⇒ 本仓同样「存在即可改」。
🔴 官方消息码(MsgCode.java)本批直接采用:
EXIST001="名称不能重复" / EXIST002="编码不能重复" / FA001="数据不存在" /
FA002="更新失败,数据不存在" / FA003="删除失败,数据不存在" /
SYS050="只能输入字母、数字、点、横线和下划线,且以字母开头"。
- 回归测试
tests/batch10_it.rs(9 条):签章判重 +userIds形状、改签章重建授权人、 Selector/ListByIds/软删、按钮判重 +selectActions原子性、enCode前缀与剥除、 批量撞码整体失败、表单前缀与默认值、高级查询归属隔离 + ListVO、高级查询必填校验。
🔴 本批踩到并解决的坑
- 🔴 契约扫描器只认
face_b这一个 mod 名(scripts/check-contract-scan.py:252:if mod in ("jnpf", "face_b"))⇒ 守卫的静态推导只对内联在face_b.rs里的 handler 生效。 本批一度想拆独立文件face_b_batch10.rs,会直接让 CC6 守卫静默失效 —— 拆文件前先读扫描器,别让「守卫没跑」变成绿灯。 ⇒ 解法:临时文件 → Python 脚本插入face_b.rs的 PRINT DEV 段之后 → 删临时文件。 - 🔴
LIMIT/OFFSET也必须::text::integer(本仓参数一律按 text 绑定):LIMIT $N OFFSET $M会报protocol error: cannot convert between ... Option<String> and the Postgres type int8⇒ 写成LIMIT ${}::text::integer OFFSET ${}::text::integer。 - 🔴
base_module_form.f_sort_code是BIGINT—— 抄 DDL 时手误写成BIGIG会被 PG 直接拒。 - 🔴 加表仍然是三处(批次 9 已经踩过一次,这里再确认):
schema.sql+main.rs的BASE_TABLES+crates/sspf-store/src/db.rs的两处断言。 本批 43 → 49,另加src/backend/tests/batch6_it.rs与routes.rshealth 测试里的表数断言。
批次 11(2026-11-01)—— 数据权限三件套(字段 / 方案 / 数据连接)
15 条面 B 端点:ModuleDataAuthorize(6) + ModuleDataAuthorizeScheme(5) +
ModuleDataAuthorizeLink(4)。
新表 3 张:base_module_authorize / base_module_scheme / base_module_link,
tables 49 → 52。
🔴 表名 ≠ 控制器名 ≠ 实体名(抄官方时最容易错的一处):
控制器叫 ModuleDataAuthorize*,但实体 @TableName 是 base_module_authorize /
base_module_scheme / base_module_link —— 不是 base_module_data_authorize_*。
🔴 点权限:除「方案列表」外全部 OR 两码 {"permission.resource","appConfig.appResource"}
(guard_any);方案列表只需登录(官方 ModuleDataAuthorizeSchemeController.java:62
那个 list 没加 @SaCheckPermission)。
🔴 enCode 前缀化是「写时加、读时剥」(与批次 10 的 ModuleColumn 是两套不同前缀):
| 动作 | 判据 | 落库值 | 读回 |
|---|---|---|---|
| create | module.type==3 && fieldRule != 0 && bindTable 非空 |
bindTable + "." + enCode |
剥掉 bindTable. 前缀 |
| update | module.type==3 && fieldRule == 1 && bindTable 非空 |
bindTable + "." + enCode |
同上 |
- 🔴 create 是
!=0、update 是==1—— 官方两处判据不一样,别统一成!=0。 - 🔴 delete 的方案引用比对用「原始带前缀」的 enCode(官方
ModuleDataAuthorizeController.java:297比的是entity.getEnCode(),库里那个值带前缀) ⇒ 拿剥过的码去比会失配 ⇒ 永远拦不住。
🔴 conditionJson 结构是「数组 → groups 数组 → item.field」(三层):
[ { "groups": [ { "field": "demo_item.f_name" } ] } ]
🔴 官方消息码(MsgCode.java):EXIST001="名称不能重复" / EXIST002="编码不能重复" /
FA002="更新失败,数据不存在" / FA003="删除失败,数据不存在" /
SYS020="该字段在方案{0}中已被使用" / SYS021="修改失败,该方案不允许编辑"。
🔴 两处「诚实降级」(本仓无对应能力,不假装成功):
-
GET /ModuleDataAuthorize/{moduleId}/FieldList⇒ 官方靠visualdevServiceImpl解析 低代码表单字段 ⇒ 本仓返回空数组(不是 404、不是假数据)。 -
GET /ModuleDataAuthorizeLink/{linkId}/Tables/{tableName}/Fields/{menuType}/{dataType}⇒ 官方靠dbTableService.getFieldList做数据库内省 ⇒ 本仓返回空 PageListVO。 -
另:
getVisualTables对低代码菜单(type 3/9/11)官方走表单解析 ⇒ 本仓返回{linkId:"", linkTables:[]};其余 type 按menuId + type查base_module_link。 -
回归测试
tests/batch11_it.rs(5 条):字段 enCode 前缀化 + 剥除 + FieldList 空数组 + condition 解码、update 前缀化 + 「更新失败,数据不存在」、delete 的 SYS020 拦截 + 软删 + 「删除失败,数据不存在」、方案双判重 + PageListVO + SYS021 + 软删、连接新建/更新 + getVisualTables 低代码空/非低代码查表 + getInfo 命中/未命中 + 表字段空 PageListVO。
🔴 本批踩到并解决的 5 个真 bug(跨批次,顺手修掉的)
- 🔴
b10_insert把None当now()绑定 ⇒ 整型列直接类型错 (column "f_all_data" is of type integer but expression is of type timestamp)。 触发点:可选整型字段缺省时传了None。本批改了f_all_data/f_type, 顺手发现批次 10 的f_field_rule有两处同样的雷(列表权限批量 / 表单权限批量) ⇒ 一并改成「缺省按官方默认 0」。以后写b10_insert整型列一律不许传None。 - 🔴 查
int4列必须写$N::text::integer—— 本仓参数一律按 text 绑定 (params_of统一Option<String>)⇒f_type = $2报cannot convert between ... Option<String> and the Postgres type int4。 同批的LIMIT/OFFSET已在批次 10 踩过同一个坑(那时是 int8)。 - 🔴 写路径要「只 SET body 里出现的键」 —— 官方是
updateById(entity), Mybatis 只 SET 实体里非 null 的字段 ⇒ body 没带的键保持原值。 本批补齐了ModuleDataAuthorize的enCode与ModuleDataAuthorizeLink的linkId/linkTables/dataType(之前一律 SET ⇒ 会把没传的字段清空)。 - 🔴 批次 10 有个「跨用例污染」的假绿/假红:
module_column_batch_rejects_duplicate_in_batch断言列表权限「一条都不许落库 ⇒ count == 0」,但同一文件共用一个 pglite 临时库、any_menu_id()对每个测试都返回同一个菜单 ⇒ 别的测试已建过 2 行 ⇒ 必然红。 已改成基线相对(before→before + 2)。教训:共用库的测试不要写死绝对条数。 - 🔴 裸
exec_params绑整型会炸 —— pglite-rs 按&str推断参数类型, 绑int4列要写成$N::text::integer;测试里插行优先走端点(顺带覆盖了端点)。
🔴 上一批(第一批)踩到并解决的 4 个真 bug
CurrentUser的preferenceJson必须是字符串"{}"—— 给对象会让前端handleUpdatePreferences抛异常 ⇒ 登录后立刻跳 Logout(表现为「登录无效原地打转」)。- 菜单
urlAddress走的是面 B 路径permission/user,不是面 A 的system/User⇒ 之前直接访问/system/User必然 404。 Users列表的keyword压根没进 SQL(搜索框形同虚设)⇒ 已补三列 ILIKE。- 空关键词时把
like塞进参数数组 ⇒ PG 报「bind supplies 1 params, statement requires 0」 ⇒ 必须if keyword.is_empty() { Vec::new() }。
2. 运行中的现场(断了就按这里重启)
后端(端口 30000)
cd ~/Desktop/workspace/ssw-platform
RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml # 改代码后
# 🔴 **尺子跑的是 release 产物** ⇒ 跑尺子前必须 `cargo build --release`
RUSTC_WRAPPER=sccache cargo build --release --manifest-path src/backend/Cargo.toml
nohup env PORT=30000 ./target/debug/ssw-platform > /tmp/ssw-backend.log 2>&1 & # 后台起
curl -s http://127.0.0.1:30000/api/health # 期望 {"ok":true,"tables":43,...}
拿 token(面 B):
ENC=$(./target/debug/ssw-platform --enc 123456)
curl -s -X POST http://127.0.0.1:30000/api/oauth/Login \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Vue-Version: 3' -H 'App-Code: mainSystem' \
--data-urlencode account=admin --data-urlencode "password=$ENC"
# → data.token(lite- 前缀)。Authorization 头是**裸 token,没有 bearer 前缀**
前端(~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework)
🔴 必须 env -u NODE_OPTIONS:否则被 brokered-fs shim 逐次拦截(0.15 包/s,末尾
ERR_PNPM_CODEBUDDY_BROKER_DENY / CODEBUDDY_BROKER_OUTCOME_UNKNOWN)。依赖已经装好,
下面第 1 步只在坏了时重跑。
cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework
env -u NODE_OPTIONS pnpm install --prefer-offline --reporter=append-only # 断了才需要重跑,约 47s
pnpm -r run stub --if-present # 已由 postinstall 跑过
env -u NODE_OPTIONS nohup pnpm dev:main > /tmp/vite-main.log 2>&1 & # vite, 3000, /dev → 30000
- 成功标志:
node_modules/.modules.yaml存在(✅ 已存在)、vite 打印ready in ~7s - 打开
http://localhost:3000/(根路径 App-Code 为空 ⇒ 后端回退主系统,已支持) - 登录:
admin/123456(登录框自己加密,不要手填密文)
⚠️ 后台进程会随 turn 结束被回收(run_in_background 起的东西在回复完就没了)。
🔴 2026-10-31 实测修正:run_in_background 不可靠(上下文压缩那一轮 vite 就被回收了,
日志里明明 ready in 5188ms)。用 nohup ... & 起,实测能跨 turn 存活:
# 前端
cd ~/Desktop/workspace/jnpf/7.0/frontend/web/jnpf-web-monorepo-framework
env -u NODE_OPTIONS nohup pnpm dev:main > /tmp/vite-main.log 2>&1 &
# 后端
cd ~/Desktop/workspace/ssw-platform
nohup env PORT=30000 ./target/debug/ssw-platform > /tmp/ssw-backend.log 2>&1 &
两个都起好后,浏览器会话 aix --session ssw 可以直接复用(登录态在 localStorage)。
⚠️ 后端一重启,token 就失效(session 是进程内内存表)⇒ 每轮开工必须重新登录拿 token。
代码仓库(本机 Gitea)
cd ~/Desktop/workspace/ssw-platform
git status -sb # main...origin/main,工作区应干净
# 推送(凭据只在 xop 注入的环境里存在,脚本不落盘)
xop run --secret GU=git_local_user --secret GP=git_local_pass -- bash -c '
export GIT_ASKPASS=/tmp/askpass-ssw.sh GIT_TERMINAL_PROMPT=0
git -c http.proxy= -c https.proxy= push origin main' < /dev/null
- 远端:
http://127.0.0.1:13300/ssw/ssw-platform.git(Gitea 1.26.1,私有,默认分支 main) ssw是用户命名空间不是组织(/api/v1/orgs/ssw返 404),建仓用POST /api/v1/user/repos/tmp/askpass-ssw.sh若不存在,重建:case "$1" in *[Uu]sername*) echo "$GU";; *) echo "$GP";; esac- 🔴 xop 会把输出里等于密钥值的串打码(
ssw→ss****【xop禁止将密钥泄漏】),日志别扭但无害 - 每批做完建议
git add -A && git commit(一晚上至少留一个可回滚点)
3. 待办(按优先级,做完一条划一条)
P0 —— 用户管理页剩余接口 ✅ 2026-10-31 全部做完
| 端点 | 状态 |
|---|---|
GET /api/permission/Group |
✅ 左侧分组树(ListVO)。表是官方 base_group(不是 base_user_group,官方 DDL JNPF-PostgreSQL.sql:1758 只有 base_group) |
GET/POST/PUT/DELETE /api/permission/Group/{id} |
✅ CRUD 全通,端到端实测(建→详情→改→加成员→移出→删) |
POST /api/permission/Group/{id}/Actions/AddUser / DeleteUser |
✅ 走 base_user_relation(f_object_type='Group'),幂等插 |
POST /api/permission/Users/{id}/SetPosition + /SetPositionBatch |
✅ 405 已修(单独注册 /Users/SetPositionBatch) |
GET /api/permission/Users/{id}/SelectorByUserPosId |
✅ |
GET /api/system/System/getDevUser |
✅ |
DELETE /api/permission/socials/{id} |
✅ 本仓无 base_socials_users ⇒ 恒成功 |
POST /api/permission/Users/workHandover |
✅ 置 f_handover_mark=1 |
另外顺手补了 5 条页面级 404(都是「不补就弹红条」的):
GET /api/system/DictionaryData/All(恒 {list:[]},不能是裸数组)、
GET /api/system/HomeData(恒 [],前端读 res.data.length)、
POST /api/system/MenuData/useModuleNum/{id}(恒成功)、
GET /api/oauth/getLoginConfig + getConfig/{account}(登录前调用 ⇒ 无守卫,恒 {})。
P1 —— 让页面真跑起来 ✅ 2026-10-31 达成
可复现步骤(实测有效):
nohup起后端 + vite(命令见 §2)aix open "http://localhost:3000/login" --session ssw→aix snapshot拿@eN→ fill 账号/密码 → click 登录 → 约 9s 后落到/homeaix open "http://localhost:3000/permission/user"⇒ 期望:左侧「全部用户」+ 分组节点, 右侧表格有 admin 行,零报错- 零非 200 的查法(比看控制台准):进页面前先注入 fetch/XHR 双钩子收集
window.__net, 再 filterx[0]!==200。控制台看不到 404 的 details 时就用这招
P2 —— 机构管理 Organize CRUD + Selector ✅ 2026-10-31 做完
Organize CRUD + SelectorGET/POST /api/permission/Organize、GET/PUT/DELETE /api/permission/Organize/{id}、
GET /api/permission/Organize/Selector 共 6 条。
端到端实测:建父 → 建子(organizeIdTree = 父树+自己,orgNameTree 同理)→ 详情 →
改(只发 fullName,enCode 不动)→ Selector 2 行 → 删 → 剩 0 行。
⚠️ 删机构不级联(只软删本行)⇒ 已记为已知限制 (ak)。
P3 —— 菜单管理 / 角色授权 ✅ 2026-10-31 05:00 做完
| 批次 | 端点 | 备注 |
|---|---|---|
岗位 Position |
12 条 | 新表 base_position(官方 23 列逐字)。CRUD + Selector/SelectorTree/Condition/SelectedList/DutyPosition/DutyUser |
角色 Role |
6 条 | base_role 已有。CRUD + Selector + RoleCondition |
菜单 Menu |
13 条 | base_module 已有。CRUD + 四种 Selector + Export/权限组 |
字典 DictionaryType/Data |
14 条 | 新表 2 张。分类 CRUD + 数据 CRUD + 两种下拉 |
| 用户选人 / 授权 / 关系 | 16 条 | Users/Selector、getUserList、getSelected*、getAllPermission、Authorize、Authority/{kind}/{id}、RoleRelation/*、UserRelation/* |
P4 —— 剩下的(按 §0-bis 的全景表,从上往下做)
✅ 批次 1 做完(实际 23 条)——新表permission/Users/Current/*个人设置 14 条(BaseInfo/改密码/主题/语言/头像/签名/saas)base_user_extra/base_sign_img✅ 批次 2 做完(实际 21 条)——新表permission/Standing(6) /PermissionGroup(6) /Action(3)base_standing/base_permission_group/base_action← 下一个 ✅ 批次 3 做完(实际 31 条,含 Tag)——新表system/System(11) +system/SysConfig(6) 系统配置页base_system_top/base_sys_config; 应用中心 CRUD + 置顶 + 应用授权 + 系统参数/第三方配置键值表 + 管理员设置 + 同步统计。✅ 批次 4 做完(实际 19 条,含 BusinessCategory)——新表message(53) 里的api/system/message.ts那 14 条base_business_category/base_message/base_notice。api/msgCenter/*(36 条运维后台)仍未定。✅ 批次 5 做完(实际 21 条)——新表system/Log(5) +system/CommonWords(6) +system/BillRule(8)base_sys_log/base_common_words/base_bill_rule; 登录落日志 + 常用语 CRUD + 单据规则与单号生成器。✅ 批次 6 做完(实际 16 条)——新表DataModel/{}/Tables(12 页共用) +DataSource+BasicDataType+CommonFieldsbase_db_link/base_data_type/base_common_fields; 数据建模只读面(表清单/字段/预览)+ 数据连接 CRUD。写面(真 DDL)留给批次 7。✅ 批次 7 做完(实际 8 条)——真 DDL + 两道护栏(DataModel写面 8 条(CREATE/ALTER/DROP TABLE+addFields+Copy+Export/Import)db_ident+ddl_tables内置表清单)- 官方
checkTab的「内置表 / 有数据」双闸。数据建模三页现在真能用。
- 官方
✅ 批次 8 做完(实际 18 条)——新表systemData的Dataset(16)base_data_set/base_data_set_relation;CRUD + 设计器get/save+ 六条取数 (Preview/List/InfoByIds/getRes/previewSql/fields)+ 下拉 + 恒失败的导出导入。 真执行 SQL,三道护栏 +${xxx}/@xxx全绑定。✅ 批次 9 做完(实际 39 条)——新表 6 张(DataInterface(12) +InterfaceOauth(11) +system/printDev(17)base_data_interface/base_data_interface_oauth/base_data_interface_user/base_data_interface_log/base_print_template/base_print_version);数据接口复用数据集执行面真取数、 接口认证 CRUD + 用户清单、打印模板模板/版本两套 CRUD + 发布归档语义。 🔴 打印无渲染引擎 ⇒Export/BatchData恒400+ 人话。权限配置族✅ 批次 10 做完(实际 31 条)——新表 6 张(Signature(7) +ModuleButton(7) +ModuleColumn(6) +ModuleForm(6) +AdvancedQuery(5)base_signature/base_signature_user/base_module_button/base_module_column/base_module_form/base_advanced_query_scheme);电子签章 + 按钮/列表/表单权限 + 高级查询方案。 🔴 OR 两码点权限(permission.resource|appConfig.appResource);Signature/AdvancedQuery官方无点权限 ⇒ 只需登录。 🔴enCode写时前缀化 / 读时剥除(单条按「菜单存在」,批量无条件)。数据权限三件套✅ 批次 11 做完(实际 15 条)——新表 3 张(ModuleDataAuthorize(6) +ModuleDataAuthorizeScheme(5) +ModuleDataAuthorizeLink(4)base_module_authorize/base_module_scheme/base_module_link);数据权限字段 + 方案(双判重 / SYS021 / 引用校验 SYS020)+ 数据连接。 🔴 表名 ≠ 控制器名(ModuleDataAuthorize*⇒base_module_authorize等)。 🔴enCode前缀化用bindTable + "."(与批次 10 的jnpf_<bind>_jnpf_是两套); create 用fieldRule!=0、update 用fieldRule==1;delete 比对用带前缀的码。 🔴 方案列表只需登录(官方没加@SaCheckPermission)。 🔴FieldList/ 表字段端点依赖低代码表单与数据库内省 ⇒ 诚实返回空(不假装)。- 🔴🔴 【批次 12 = 下一轮优先做】框架固定包 + 业务模块链接就好
—— 不是补端点,是改「加业务的成本结构」:加一个业务模块从现在的
改 6~8 处(两份 spec 拷贝 + 手抄 DDL + 手抄契约表 + 改
schema.sql+ 改main.rsBASE_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(下一轮优先做)—— 「框架固定包 + 业务模块链接就好」
这一批不是补端点,是改「加业务的成本结构」。 目标形态: 平台层(面 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 的逐件翻译表反查)。
- 面 A(
② 打通「两份拷贝」⇒ 单一真源 + PACK1 闸门
modules/asset.rs的 spec 改为从packs/assetre-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 0f_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.sh66.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 技能指 NestJSsrc/backend/src/⇒ 本仓指 Rustsrc/backend/src/), 前端路径零改(src/frontend/src/...两边同名)。 - 🔴 集成期才做官方 Vue 那一套:
views/<模块>/index.vue+api/<模块>.tsrouter/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时要指对目录。
- 🔴 本批的前端 = React 模板(
本批护栏(缺一不可)
| # | 护栏 | 落地位置 |
|---|---|---|
| 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 |
验收判据(做完必须全绿才算完成)
# 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/<模块>.tsrouter/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 scripts/new-pack.sh crm Customer --name "客户" \
--columns "name:VARCHAR(200),level:VARCHAR(50)" --with-frontend
bash scripts/verify.sh --fast # 纯静态:文件与接线一致(含尺子自证)
bash scripts/verify.sh --lib # + 单测 + **包冒烟**(真起库、真打 List)
⚠️ 不在这里写耗时:verify.sh 每次运行自己打印总耗时 + Top 3 最慢
(判据是「耗时必须可见」,写在文档里的数字一定会烂)。
它产出的东西(全部从「业务决策」推导,不猜):
| 产出 | 谁生成 |
|---|---|
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 完成状态」。
🔴 前端接入的两个坑(已修,别再踩):
- 端口:React 技能模板的 vite proxy 指 NestJS
:30000,本仓 Rust 后端是:30010(main.rs的PORT缺省值)⇒ 照抄会在浏览器里表现成Network Error, 最容易误判成「跨域 / 认证」,其实只是端口抄错。 - 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(都是「加第二个包」才显形):
- 🔴
check-contract-scan.py的守卫回落取了「排序后第一个包」 (for pkg in sorted(pack_orig))⇒ 有asset+probe两个包时,probe 的面 A 守卫 被推成asset/DataResource⇒ CC6 假飘移 3 条 ⇒ 人会去改对的契约。 修法:按app精确匹配包;查不到就返回「推不出」(人工核对),不再瞎猜。 - 🔴 加包会误报 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.6 完成状态(2026-11-01 23:15 实测)—— 「接上了」≠「接的活能应答」
问题:12.5 之后,漏接会红(pack-sync --check),但接错了仍然全绿。
routes.rs::route_table_is_pinned 只用「错方法 ⇒ 405」证明路径注册了,
它证明不了 handler 跑得通。中间那段是静默失败的重灾区:
| 造的错 | 静态闸门 | 用户看到 |
|---|---|---|
| spec 有列、DDL 缺列(投影 SQL 报错) | 全绿 | 列表恒 {"code":400},页面空着 |
module_key 指向不存在的菜单 |
全绿 | 403,页面空着 |
| 面 B 路由没 merge 进总路由 | 全绿 | 404,页面空着 |
做法:src/backend/tests/pack_smoke_it.rs —— 一个测试、遍历全部包
(ALL_SPECS / ALL_ROUTES / 包注册表,一个条目都不写死):
登录拿 token ⇒ 面 A 每个 List ⇒ 断言 code==200 且 data 是裸数组;
面 B 每条 List 路由 ⇒ 断言 code==200 且 data.list 是数组、pagination.total 非空。
失败时一次列出全部坏条目(加包场景常一坏一片,逐条重跑才能看全 = 浪费)。
verify.sh新增这一步,挂在--lib(full/smoke已由--workspace覆盖,不重复跑): 实测 +2.4s(起 pglite + 起 HTTP 服务 + 4 个包 × 2 面)。- 🔴 不放进
--fast:内环的定位是「零 node、零起库的纯静态」,塞进去会把 20s 变成 25s 且多一个 flaky 面(端口 / 起库)。--fast与--lib的分工现在很清楚:--fast= 该接的接上了;--lib= 接上的活真能应答。
反自证(两处,实测):
| 造的漂移 | 结果 |
|---|---|
packs/asset/schema/001_init.sql 删掉 f_category(spec 还有这一列) |
FAILED,一次列出两条:面 A .../DataResource/List 信封 code=400、面 B /api/asset/DataResource 信封 code=400(附 column "f_category" does not exist 的服务端日志) |
bootstrap::pack_router_or_empty 改成恒 Router::new() |
FAILED,指名 面 B /api/asset/DataResource 状态 404 ≠ 200 |
顺手修的两处文档失真:
verify.sh头部写「45 个测试二进制」,实测(cargo test --workspace --no-run的Executable行数)= 37 ⇒ 改成 37。这类数字没人核就一定是错的。--lib的描述写「不起库」也是错的(--lib里的routes.rs测试早就起 pglite 了) ⇒ 改成「lib 单测 + 包冒烟(起库)」。
边界(有意不做):
- 不冒烟 Save / Delete:Save 需要合法 body,而
ColumnSpec有意不带类型 (只有numeric: bool+default)⇒VARCHAR与TIMESTAMP在 spec 里长得一样 ⇒ 造不出对所有包都合法的 body。退一步用{}又要求「业务列全部可空」—— 那是业务决策(--columns允许写NOT NULL),平台不该替包规定。 写 / 删留给各包自己的集成测试(crud_it.rs/batch*_it.rs)。 - 不在
new-pack.sh里跑:与「生成器不该假装自己是编译器」同一条边界 —— 它只管「文件和接线都齐」,能不能应答交给verify.sh。
批次 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 那一套
—— 列白名单 + now() 不占参数位 + 只 SET body 里出现的键 + 读回不选 f_password。
docs/contract.md 三处登记必须同步,否则 CC10 / CIT2 会红。
4. 每批实现的固定动作(缺一不可)
cd ~/Desktop/workspace/ssw-platform
# 1) 实现 → 编译
RUSTC_WRAPPER=sccache cargo build --manifest-path src/backend/Cargo.toml
# 2) 重启后端(老进程先 kill)
PORT=30000 ./target/debug/ssw-platform &
# 3) 运行时验证(比静态比对权威)
python3 scripts/probe-page.py docs/fe/page-user.tsv
# 4) 单测 + 六闸
RUSTC_WRAPPER=sccache cargo test --manifest-path src/backend/Cargo.toml
# 🔴 **尺子跑的是 release 产物** ⇒ 跑尺子前必须先 build --release
RUSTC_WRAPPER=sccache cargo build --release --manifest-path src/backend/Cargo.toml
for s in check-module check-boundary check-contract check-citations; do bash scripts/$s.sh; done
bash scripts/perm-smoke.sh
ENC_BIN="$PWD/target/debug/ssw-platform" bash scripts/perm-smoke-jnpf.sh
新增/变更端点必须同步三处,否则闸门必红:
docs/contract.md的[ENDPOINT](面 B 行首列写B)与[OFFICIAL](absent → implemented)docs/contract.md的[FACE]计数 +[RULER]里perm-smoke-jnpf.sh的断言数src/backend/src/routes.rs测试里的JNPF_REGISTERED(按路径列,同路径多方法算一条)
5. 必踩的坑(都已踩过一次,别再踩)
- 🔴 一条
.route()只挂一个方法:check-contract-scan.py只解析每个.route()的第一个方法,get(a).post(b)会被判成「契约写 POST、代码是 GET」。同路径多次.route()在 axum 里是合并,不冲突。 - 🔴 驼峰 ≠ 下划线机械转换:
ranks↔f_rank、certificatesType↔f_certificates_type。 列名只来自白名单常量(如USER_WRITE_FIELDS),别用snake_case()猜。 - 🔴
f_creator_time写 SQLnow()时不占参数位:marks.push("now()")而非placeholder(), 否则$n序号和columns错位(报column is of type timestamp but expression is of type text)。 - 🔴 写路径只
SETbody 里出现过的键,未出现的列必须保持原值(有断言钉住)。 - 🔴 读回不选
f_password/f_secretkey(有断言钉住「详情无 password 键」)。 - 🔴
{id}会吞掉Users/下未注册的静态 GET 子路径;matchit 静态段优先,所以那些路由 一旦注册就自动优先匹配,不需要改详情。 - 🔴 测试共用
platform/test_support.rs的单例 pglite(进程内只能开一个实例), 别在测试里open_temp。 - 🔴
python脚本里递归取同目录.vue时用if seen is None:,不能写seen = seen or set()(空 set 是 falsy ⇒ 每层新建 ⇒ 环形 import OOM 被 SIGKILL)。 - 🔴 jq 里
$d|has(a) or $d|has(b)会被|抢结合 ⇒ 用[keys[]|select(.=="a" or .=="b")]|length。 - 🔴 端口:前端 dev 3000,代理
/dev→ 30000,后端绝不能起在 3000。 - 🔴 npm/pnpm 类命令一律
env -u NODE_OPTIONS(见 §0);cargo 不受影响,不用加。 - 🔴 后台进程随 turn 结束被回收:起服务与验证必须同一 turn 内完成。
- 🔴 git 推送别把密码塞 remote URL:用
GIT_ASKPASS+xop run --secret,并加-c http.proxy=。 - 🔴
.gitignore已挡target/(1.7G) 与src/backend/data/(38M);git add -A前先git diff --cached --name-only | wc -l确认没暴涨。
批次 2 新增的坑
- 🔴 PG 数组参数一律不能写
$N::text[]:pglite-rs 0.2.7 会把它当成 PG 数组类型_text, 而本仓参数一律按 text 绑定(Option<String>)⇒ 协议错cannot convert between the Rust type String and the Postgres type _text。 ⇒ 改成= ANY(string_to_array($N::text, ','))(函数在 SQL 里做)。 - 🔴 PG 会拒「SQL 里有 $N 但没用它」:
42P18: could not determine data type of parameter $1。 ⇒ 凡是留了$N的软删 SQL,都要把对应列写进 SET(f_delete_user_id = $N::text)。 - 🔴 占位符顺序必须与参数追加顺序逐字对齐(不是「大致对上」)⇒ 写完对着读一遍。
- 🔴
base_action.f_enabled_mark是 VARCHAR(11)(官方 DDL 陷阱)⇒ 别按整数 CAST。 - 🔴
base_standing.f_is_system是 1=系统 / 2=自定义 ⇒ 新建写 2,不是 1。 - 🔴 官方
list端点常有「id 串换人名串」的后处理(getFullNameByIds)⇒ 抄控制器别只抄模型。 - 🔴 Bash 里写多层嵌套引号的 curl + python 验证脚本很容易引号不闭合(
bash -n报unexpected EOF但定位不到行)⇒ 直接用 Python 写验证器(urllib+ProxyHandler({})绕过本机代理),别跟 bash 引号较劲。 - 🔴 尺子用的是
target/release/ssw-platform,不是 debug 产物 ⇒ 改完代码跑尺子前 必须cargo build --release,否则尺子跑的是旧二进制(表现为「刚修好的端点还是 405」)。
批次 11 新增的坑
- 🔴
b10_insert的None不是「不写这列」,是「写now()」 ⇒ 整型列直接类型错 (column "f_all_data" is of type integer but expression is of type timestamp)。 ⇒ 写整型列一律给具体值(缺省按官方默认补0),不要传None。 (这条已把批次 10 的f_field_rule×2 也炸出来了 —— 同一个雷,隔一批才被踩到。) - 🔴 查
int4列必须$N::text::integer(本仓参数一律按 text 绑定)。f_type = $2⇒cannot convert between ... Option<String> and the Postgres type int4。 - 🔴
updateById语义 = 只 SET body 里出现的键:官方 Mybatis 只 SET 实体里非 null 的字段 ⇒ body 没带的键保持原值。⇒ 自己拼 SET 列表时别把没传的键也 SET 上去(会清空数据)。 - 🔴 共用 pglite 的测试不要写死绝对条数:同一测试文件里
any_menu_id()对每个测试返回 同一个菜单 ⇒ 别的测试先建过行 ⇒ 「count == 0」必红。⇒ 一律基线相对(before/before + n)。 - 🔴
async fn忘了.await会静默不执行(编译器只给unused_must_use警告)⇒ 测试里「插了行却查不到」先查这个。 - 🔴 官方
ActionResult.success(String msg)是「msg 带提示、data 为 null」, 与本仓ok(json!({...}))(msg="成功"、data 透传)不是同一个形状。 本仓沿用既有约定(create 回{id})—— 改的时候要连前端消费点一起看。
6. 收工前(每一轮都要做)
- 追加
.workbuddy/memory/YYYY-MM-DD.md:结论 / 坑 / 数字(闸门通过数) - 更新本文件 §1 现状、§2 现场、§3 待办(划掉做完的)
- 若还有未完成项,确认下一次定时任务存在(
automation_updatelist 可查),没有就新建
当前挂着的定时任务(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 | 与本仓无关 |