Files
ssw-platform/PLAN.md
T
admin e0c1904a0e docs: 同步面 B 批次 11 收尾(HANDOFF/PLAN/CLAUDE + memory 日志)
- HANDOFF §1 现状:端点 376(面 B 346)/ tables 52 / 测试 550 / 官方覆盖 365-372
- HANDOFF 新增 §1「批次 11」小节:表名≠控制器名、enCode 前缀化(create 用 !=0、
  update 用 ==1,delete 比对用带前缀的码)、conditionJson 三层结构、方案列表
  只需登录、SYS020/SYS021、3 处诚实降级
- HANDOFF 新增「本批踩到并解决的 5 个真 bug」+ §5「批次 11 新增的坑」6 条
- HANDOFF §3 待办:划掉批次 11,补批次 12 指引(缺口 system 55 / permission 26 / systemData 32)
- HANDOFF 修正「八道闸门」为「十二道闸门」(旧措辞与 CLAUDE.md 不一致)
- PLAN 差距表:面 B 331 → 346,base_* 49 → 52
- CLAUDE.md:cargo test 545 → 550(两处写死值)
- memory 日志追加批次 11 段落:结论 / 9 个坑 / 数字(均已复验)
2026-11-01 19:18:17 +08:00

1001 lines
54 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PLAN —— 尚数网统一开发平台(SSPF)总体架构与路线
> 本文件回答 **「做成什么、为什么这么做、怎么算做完」**。
> `CLAUDE.md` 是红线与当前范围(随阶段滚动更新),本文件是**长期架构基线**,阶段推进时只改 §9 的勾。
> 术语:**基线平台** = 兼容目标(现称 JNPF v7 的那套 Java 平台,代码/文档内统一叫 `baseline`,不再出现原厂名)。
---
## 0. 一句话定位
**SSPF = 尚数网企业统一开发平台**:以「元数据驱动 + 契约兼容 + AI 原生接口」三层能力,
让业务系统从「写代码」变成「声明 + 验证」,并保证存量前端/移动端/数据库零改动平滑接管。
三层价值,缺一不可:
| 层 | 是什么 | 为什么必须有 |
|---|---|---|
| **兼容层** | 逐字对齐基线平台的 HTTP 契约、`base_*` DDL、口令算法、响应信封 | 前端/移动端/存量库不动,才有「切换」而不是「重做」 |
| **元数据层** | 表/模型/表单/菜单/流程/权限全部是**库里的数据**,引擎解释执行 | 这才是「低代码」;也是「后续开发不用编译」的唯一干净实现 |
| **AI 接口层** | MCP 2.0 元工具 + 自提示 + 分层加载 | 让 AI 成为第一开发者,而不是让人去点 20 个页面 |
---
## 1. 目标分解(三条时间线,别混)
| 时间线 | 目标 | 可验收的判据 | 依赖 |
|---|---|---|---|
| **N(现在–Q1)** | 提高基线平台开发速度 / 降低环境要求 | ① 同一需求 AI 交付耗时 ↓50% ② 部署从「Java+Redis+Nacos+DB」降到「单二进制 + 内嵌 PG」 | 轨道 A + B 并行 |
| **M(Q1–Q2)** | 完全稳定 / 行为一致后切换 Rust 版 | 影子对账 P0 差异 = 0;同一前端在两个后端跑同一套 E2E 全绿 | 轨道 B |
| **L(Q2+)** | 人 + AI 高效协作开发 | 业务需求从「提给开发」变成「对话产出 + 自动验证 + 可回滚」 | 轨道 A 成熟 |
### 1.1 🔴 关键:拆成两条轨道并行,不要串行
```
轨道 A(AI 工具面) ── 架在【现有 Java 后端】上,立刻可用 ──▶ 提速
│
│ 同一套 MCP 工具契约,后端实现可替换
▼
轨道 B(Rust 内核) ── 逐条迁契约,影子对账 ──▶ 降环境、去 Java ──▶ 切换
```
**理由**:基线平台的开发速度瓶颈**不在 Java 运行时**,而在「人/ AI 要理解平台、记住 50 个坑、点 20 个页面」。
dacli 的 4.7 万行 TypeScript 全部在解决这件事 —— 这证明「工具面」是可以独立于「后端实现」交付的价值。
反过来,如果先做 Rust 内核再想工具面,提速目标会被内核进度绑死半年。
**架构保证**:MCP 层只依赖 `PlatformAdapter` trait,不认具体后端。
```rust
// crates/sspf-mcp/src/adapter.rs
#[async_trait]
pub trait PlatformAdapter: Send + Sync {
async fn call(&self, op: &str, args: Value) -> Result<Value, ApiError>;
async fn describe_env(&self) -> EnvInfo; // app_code / system / db / 版本
}
// 两个实现:
// JnpfHttpAdapter —— 打现有 Java 后端(HTTP),P1 就能用
// SspfNativeAdapter —— 进程内直调 kernel,P4 切换
// 工具契约、自提示、返回形状,两边完全一致。
```
---
## 2. 五条核心判断(都会影响后续所有设计)
### 判断 ①:不改前端 ⇒ 「低代码引擎」在后端只是「元数据服务 + 动态数据路由」
基线平台的低代码渲染器在**前端**(Vue 的 FormGenerator 解释表单 JSON)。既然不迁前端,
Rust 侧**不需要重写渲染器**,只需要三件事:
1. **存取**:`visualdev` 那套 JSON 原样存、原样取(同构,不改一个字段)
2. **动态 CRUD**:给定 `modelId` → 查元数据 → 解析出物理表/字段/权限 → 拼 SQL(**零编译**)
3. **发布/版本**:表单草稿 → 发布 → 版本快照
⇒ 低代码引擎的工作量比直觉小一个量级,**且天然满足「不编译」**。这是第 8 条需求的落地点。
### 判断 ②:「不编译」有四级;**动态库是必须项,不是可选项**
Rust 没有稳定 ABI,`cdylib` 跨编译器版本会段错误。按「稳定性 × 成本」排序:
| 级 | 机制 | 编译 | 适用 | 风险 |
|---|---|---|---|---|
| **L0 元数据** | 表单/模型/菜单/流程/权限 = 库里的 JSON | **零** | 80% 的业务 | 无 |
| **L1 表达式** | Rhai 求值(受限宿主 API + 资源上限) | **零** | 15% 的业务(业务规则) | 低(沙箱化) |
| **L2 静态 crate** | `packs/<app>/src` 编成 rlib,链进内核 | 只编业务 crate(~30s) | 4% 的业务(外部集成、复杂算法) | 无 |
| **L3 动态库** | `cdylib` + `libloading`,`plugins/*.dylib` 启动扫描 | 独立编、热替换 | **必须支持**(见 §4.5) | 🟡 中(靠 ABI 契约 + 工具链锁定压住) |
**L3 是硬需求**,理由是终端产品形态:客户现场要能单独替换/升级某个业务能力,不能等整包发版。
代价必须用工程手段压住,而不是回避:
1. **工具链锁死 `1.95.0`**(`rust-toolchain.toml` + `pack.toml` 的 `[pack.build].toolchain`,CI 双向校验)
2. **ABI 只暴露 4 个 C 函数**,其余全部走 JSON(见 §4.5)
3. **装载失败不能拖垮内核**:版本不匹配直接拒载;`catch_unwind` + 独立线程兜底
4. **热替换必须显式**:`sspf plugin reload <name>`,不做自动监控(自动热更 = 状态迁移地狱)
WASM 保留为 L3 的**并行**选项(不是替代):沙箱隔离更彻底,适合「AI 生成的业务逻辑先试跑」。
### 判断 ③:双向迁移的本质是「业务包格式」,不是「转换工具」
要做 `jnpf ⇄ sspf` 无缝,靠的不是写两个转换器,而是**一个两边都能读的中间格式**(见 §5)。
格式定得早,迁移就是打包/解包;定得晚,就是重写。
### 判断 ④:MCP 2.0 的胜负手是 token 预算,不是工具数量
200 个工具全量注册 ⇒ 光 schema 约 6 万 token,AI 直接被淹。
必须做 **L0 常驻 4 个元工具 + L1 分类索引 + L2 按需 describe**(见 §6)。
这与当前主流 agent 的「工具搜索 / 延迟加载」范式一致。
> 注:**「MCP 2.0」是本项目的工具层架构代号,不是协议版本号**。
> 协议侧按官方最新 spec 实现(`2025-06-18` / `2025-11-25`:`outputSchema`、`structuredContent`、
> `resources`、`prompts`、`elicitation`、tool annotations、Streamable HTTP)。
### 判断 ⑤:以「前端是否依赖」划界,不依赖的全改
「去掉原厂字眼」与「契约一致」的冲突,用一条判据解决:
**前端 / 移动端 / 存量数据库会读到的字符串,一个字不改;读不到的,全改。**(细化见 §7)
**改错层的后果是前端全挂**。
### 判断 ⑥:内存是一级设计约束,不是优化项 🔴
**产品形态**:尚数网的连接器是**终端产品**(客户现场 / 一体机 / 边缘节点),不是机房里的中台。
完整 Java 版基线平台在目标硬件上**跑不动**;勉强起来之后,也没有余量再跑业务、跑沙箱、跑计算。
这一条把 Rust 版的性质改了:
| 原来的假设 | 修正后 |
|---|---|
| Rust 版是「稳定后切换」的**优化项** | Rust 版是**唯一可部署形态**,是产品可行性的前置条件 |
| 轨道 B 可以慢慢来 | 轨道 B 的**内存指标**从 P0 就要进闸门,不能等 P5 |
| 沙箱/计算是后期增强 | 沙箱/计算是**终端产品的卖点**,架构必须从 P0 预留执行器位置 |
**内存预算(进 P0 出口判据,`scripts/mem-budget.sh` 可执行)**:
| 场景 | 目标常驻 | 实测(2026-10-31) | 说明 |
|---|---|---|---|
| 空载(内核 + 空库 21 表) | ≤ 40 MB | **7 MB** ✅ | 单二进制,strip 后静态链接;vmmap Physical footprint |
| 典型(20 表 / 1 万行 / 10 并发) | ≤ 120 MB | 待压测 | pglite 共享缓冲 + 会话表 |
| 峰值(导入导出 / 报表) | ≤ 256 MB | 待压测 | **必须流式**,禁止整表载入 |
| 沙箱单实例 | ≤ 64 MB(可配) | 待 P3 | 超限即杀,不拖累主进程 |
| 对照:Java 全套 | 2–4 GB | — | JVM + Spring + Redis + Nacos |
🔴 **7 MB 这个数字是终端产品可行性的第一份硬证据** —— 同一个业务契约,
Java 栈要 2–4 GB,Rust 栈空载 7 MB。它同时说明:内存预算的风险不在「做不到」,
而在「后续不加约束地长胖」(无界缓存、整表载入、每请求 clone 大对象)。所以 MEM1/MEM2 进闸门。
**四条内存红线**(写进 `check-arch.sh`):
1. 禁止 `SELECT *` 全表读进 `Vec` —— 导出/报表一律游标流式
2. 禁止无界缓存(所有缓存必须有 `max_entries` + LRU 淘汰)
3. 每个限额必须有默认值 + 可配,不许「不配就无限」
4. 沙箱/计算必须能独立限额并强杀,不影响主进程存活
### 判断 ⑦:执行器(沙箱 + 计算)从 P0 预留位置,P3 落地
终端产品要跑的不只是 CRUD。架构上预留三个执行层,共享同一套资源限额:
| 执行器 | 用途 | 隔离级别 | 落地阶段 |
|---|---|---|---|
| **表达式**(Rhai) | 字段校验/计算/联动 | 同进程,操作数上限 + 深度上限 | P2 |
| **WASM 沙箱** | AI 生成的业务逻辑、第三方脚本 | 同进程独立内存,fuel 计量 | P3 |
| **进程沙箱** | 重计算 / 不可信代码 / 调用外部 CLI | 独立进程,cgroup/Job 限额,可强杀 | P4 |
🔴 三者共用 `Executor` trait,**不许各写一套限额逻辑**。
---
## 3. 架构
### 3.1 总图
```
┌──────────────────────────────────────────────────────────────────────┐
│ AI 客户端:Claude Code / Cursor / WorkBuddy / 自研 Agent │
└──────────────────────────┬───────────────────────────────────────────┘
│ MCP(stdio 本地 / Streamable HTTP 团队共享)
┌──────────────────────────▼───────────────────────────────────────────┐
│ sspf-mcp ── 元工具层(常驻 4 个,schema < 2K token) │
│ sspf_context 环境与工程上下文 │
│ sspf_discover 意图 → 工具/资源索引(L1 分类) │
│ sspf_describe 工具 → 完整 schema + 自提示(L2,含 pitfalls) │
│ sspf_call 统一执行(结构化返回 + next_actions) │
│ │
│ 唯一知识源 registry ──▶ 派生 tool schema / 文档 / 校验器 / CI 用例 │
└──────────────────────────┬───────────────────────────────────────────┘
│ trait PlatformAdapter(后端可替换)
┌────────────────┴─────────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────────────────────────┐
│ JnpfHttpAdapter │ │ SspfNativeAdapter │
│ 打现有 Java 后端 │ │ 进程内直调 │
└────────┬─────────┘ └──────────────┬───────────────────────┘
│ │
┌────────▼─────────┐ ┌──────────────▼───────────────────────┐
│ 基线平台(Java) │ │ sspf-kernel(单二进制) │
│ 现状,存量资产 │ │ ├ contract 信封/错误码/契约类型 │
└──────────────────┘ │ ├ auth cipher/session/guard │
│ ├ permission 四源合并 │
│ ├ lowcode 元数据引擎(解释型) │
│ ├ store pglite ⇄ 真实 PG │
│ └ plugin 业务包加载器(L0–L3) │
└──────────────┬───────────────────────┘
│
┌──────────────▼───────────────────────┐
│ packs/<app>/ ── 业务包(整目录可搬) │
│ ├ pack.toml 清单/兼容区间 │
│ ├ schema/*.sql DDL(f_ 前缀) │
│ ├ meta/*.json 表单/模型/菜单/流程 │
│ ├ src/ 可选:Rust 业务逻辑 │
│ └ tests/ 契约测试(两边都能跑) │
└──────────────────────────────────────┘
```
### 3.2 目录重构(从单 crate → workspace 多 crate)
现状是 `src/backend` 单 crate(1.6 万行)。要满足「内核不编译、业务可搬」,必须拆:
```
ssw-platform/
├── crates/
│ ├── sspf-contract/ # 契约类型:ActionResult / EntitySpec / MenuSpec / 错误码 / 码表
│ ├── sspf-sdk/ # 🔴 业务包唯一依赖。只含 trait + 数据类型,依赖仅 serde
│ ├── sspf-store/ # DB 抽象:pglite 后端 + 真实 PG 后端
│ ├── sspf-auth/ # cipher / session / guard
│ ├── sspf-permission/ # 四源合并 + 管理员短路 + 菜单树
│ ├── sspf-lowcode/ # 元数据引擎:form/model/menu/flow + 动态 CRUD
│ ├── sspf-plugin/ # 业务包加载器:静态注册 / dylib / wasm(后两者可选 feature)
│ ├── sspf-kernel/ # 启动装配 + 路由挂载(bin 目标)
│ └── sspf-mcp/ # MCP 服务 + registry + 4 元工具 + adapter
├── packs/ # 🔴 业务包,只依赖 sspf-sdk
│ ├── asset/
│ └── ...
├── tools/
│ ├── diff-harness/ # 影子对账(§8)
│ ├── pack-cli/ # pack 导入导出
│ └── gates/ # 六道闸门(从 scripts/ 迁入,保持可独立跑)
├── web/ # 复用基线平台前端(不改)
└── docs/
```
**拆分纪律**(已实现为 `scripts/check-arch.sh`,`--self-test` 会造违规反自证):
| 规则 | 内容 | 违反后果 |
|---|---|---|
| AR1 | `sspf-sdk` 依赖**只能**是 `sspf-contract` | 业务包被框架绑架,不可搬 |
| AR2 | `packs/*` 依赖 ⊆ {`sspf-sdk`, `serde`} | 同上 |
| AR3 | `sspf-contract` 不许 `use axum/tokio/pglite/sqlx` | 契约层有 IO ⇒ 业务包再也不「轻」 |
| AR4 | `sspf-contract` 依赖 ⊆ {`serde`, `serde_json`, `uuid`, `http`} | 同上 |
| AR5 | `sspf-mcp` 依赖 ⊆ {`sspf-contract`, `serde`, `serde_json`} | 无法同时接「进程内内核」与「远端 Java 后端」 |
| MEM1 | 非注释代码不许 `SELECT *` | 整表读进 Vec ⇒ 直接超内存预算 |
| MEM2 | 缓存必须有 `MAX_*` / `CAPACITY_*` 上限常量 | 无界缓存 = 慢性内存泄漏 |
### 3.3 现状 vs 目标(差距表)
| 能力 | 现状 | 目标 | 差距 |
|---|---|---|---|
| 面 B 契约端点 | ✅ **346 条**(2026-11-01 批次 11 收尾) | 全量(含 lowcode/flow/file/message) | 官方端点覆盖 365/372;余下多为「本仓没这个模块」 |
| `base_*` DDL | ✅ **52 张**逐字对齐 | 全量 331 张中的必需集 | 按域补 |
| 平台/业务分层 | ✅ `check-boundary.sh` 钉住 | 升级为 crate 级隔离 | **P0 已拆 contract / store / sdk;asset 包可独立编译;`jnpf.rs`→`face_b.rs`** |
| 低代码元数据引擎 | ✅ **P2-b 完成**:解析 + 校验 + 建表 + 动态 CRUD(6 个工具) | visualdev 同构 + 动态 CRUD + 发布 | 读 release / 单据号 / 乐观锁 → P2-c |
| 业务包格式 | 🟡 `pack.toml` 已定稿、`packs/asset` 已有样板 | 导入导出工具 | **P3** |
| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 26 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model/workflow/release) | P1 收尾 |
| 影子对账 | ❌ 无 | 语料库 + 归一化比对 | **全新,P4** |
| 部署形态 | 🟡 pglite 单二进制 | 单二进制 + 可选真实 PG | P5 收口 |
---
## 4. 动态加载机制(第 8 条落地)
### 4.1 业务实现四级(先判级,再动手)
写业务前先回答一个问题:**这件事能不能只用数据描述?**
```
需要新的业务能力
│
├─ 只是增删改查 + 表单 + 菜单 + 权限? ──────────▶ L0 元数据(零代码、零编译)
│
├─ 有校验/计算/联动/显隐等规则? ────────────────▶ L1 表达式(零编译)
│
├─ 要调外部系统 / 复杂算法 / 事务编排? ─────────▶ L2 业务 crate(编 30s)
│
└─ 需要独立发版、热替换、多团队并行? ───────────▶ L3 动态库(编 + 装载)
```
**比例目标**:L0+L1 ≥ 90%,L2 ≤ 9%,L3 ≤ 1%。达不到说明元数据层设计不足,而不是业务太复杂。
### 4.2 L0:元数据(真正的「不编译」)
引擎能力清单(`sspf-lowcode`):
| 能力 | 输入 | 行为 |
|---|---|---|
| 实体/表 | `EntitySpec`(列 + 类型 + 索引) | 建表 / 迁移(幂等) |
| 模型 | 模型 JSON(字段 + 关联 + 数据源) | 注册 + 动态解析 |
| 表单 | 表单 JSON(与基线平台同构) | 存取 + 发布 + 版本 |
| 菜单 | 菜单声明 | upsert 到 `base_module` + 授权 |
| 流程 | 流程 JSON(BPMN 子集) | 存取 + 节点绑定表单 |
| 数据 | `modelId` + 查询条件 | 动态拼 SQL(列白名单,非字符串拼接) |
🔴 **动态 CRUD 的安全铁律**:所有列名/表名**只能来自元数据白名单**,绝不接受请求体里的标识符。
这条比「参数化查询」更严 —— 参数化防值注入,白名单防**结构**注入。
### 4.3 L1:表达式 —— 用 Rhai,但必须沙箱化
**选型:Rhai**(成熟、纯 Rust、无 GC、可完全禁用危险能力)。
**不自研求值器** —— 类型系统、字符串、正则、闭包这些特性自己写会变成长期负债;
业务方要的表达式能力一定会超出最初设想。
Rhai 的能力**默认全关**,只开白名单:
| 配置项 | 值 | 理由 |
|---|---|---|
| `eval` | **禁用** | Rhai 的 `eval` 是元编程入口,等于开后门 |
| IO / 文件 / 网络 | **禁用** | 一律不注册 |
| `import` / 模块加载 | **禁用** | 防跨脚本注入 |
| 时钟 | 只读 + 固定时区 | 可复现;不许拿来做限流 |
| 宿主函数 | 白名单注册 | 只有 `lookup() / len() / matches() / hasRole() / now() / today() / coalesce()` |
资源限额(缺一不可,全部可配 + 有默认):
| 限额 | 默认 | 作用 |
|---|---|---|
| `max_operations` | 10,000 | 防长计算 / 死循环 |
| `max_expr_depths` | 32 | 防深度炸弹 |
| `max_call_levels` | 16 | 防递归 |
| 执行超时 | 50 ms | 兜底(`operations` 之外的阻塞) |
| 返回 / 中间值大小 | 64 KB | 防内存炸 |
四条实现约定:
1. **编译一次,缓存 AST**:`Engine::compile` → `AST`,按表达式源 + 版本哈希缓存(有上限,LRU)
2. **表达式存元数据表** ⇒ 改规则 = 改数据 = **零编译**
3. **错误必须可读**:`EvalAltResult` 要映射成「哪个字段 / 哪一行 / 期望什么」,不能把 Rhai 原始错误直接抛给业务
4. **每次求值独立 `Scope`**,不许跨请求共享变量(防串数据与越权读)
示例(业务方写的就是这个):
```
len(fullName) <= 50 && matches(code, "^[A-Z]{2}\\d{4}$")
amount * (1 + taxRate)
status == "draft" && hasRole("finance")
lookup("customer", customerId, "creditLimit") >= amount
```
### 4.4 L2:业务 crate(默认的「写代码」形态)
```rust
// packs/asset/src/lib.rs
//! 业务包唯一入口。依赖只有 sspf-sdk(+ serde)。
use sspf_sdk::{BusinessPack, Manifest, EntitySpec, MenuSpec, MetadataDoc, Result};
pub struct AssetPack;
impl BusinessPack for AssetPack {
fn manifest(&self) -> &Manifest {
&Manifest { app_code: "asset", name: "数据资源", version: "1.0.0" }
}
fn entities(&self) -> &[EntitySpec] { &[DATA_RESOURCE] }
fn menus(&self) -> &[MenuSpec] { &[DATA_RESOURCE_MENU] }
// 需要时再实现 routes() / hooks();L0 包一个都不用实现
}
// 注册(唯一接线点,不进内核)
sspf_sdk::register!(AssetPack);
```
内核侧:
```rust
// crates/sspf-kernel/src/main.rs —— 内核里唯一的「业务知识」
let packs: Vec<Box<dyn BusinessPack>> = vec![
Box::new(asset::AssetPack), // ← 加业务包只改这一行
];
```
🔴 这一行是**唯一**允许出现业务名的地方,由 `check-arch.sh` 白名单钉住。
### 4.5 L3:动态库(**必做**,feature `dylib`)
#### 为什么手写 C ABI,而不用 `abi_stable`
业务插件的交互本来就是「收一个 JSON、返回一个 JSON」,**不需要跨 ABI 传复杂类型**。
C ABI + JSON 的调试成本最低(`ctypes` / `dlopen` 直接能测),而 `abi_stable` 要求业务方
把所有类型标注 `StableAbi`,学习成本与耦合度都更高。
⇒ **边界只有 JSON 字符串 + 6 个函数**。
#### ABI 契约(v1,改动即升版本)
```rust
// 插件侧(每个业务 cdylib 必须导出,符号名固定)
#[no_mangle] pub extern "C" fn sspf_abi_version() -> u32; // 必须返回 1
#[no_mangle] pub extern "C" fn sspf_build_info() -> *mut c_char; // JSON: {rustc, profile, pack}
#[no_mangle] pub extern "C" fn sspf_init(ctx: *const c_char) -> *mut c_char; // 入参 JSON,返 handle 或 err
#[no_mangle] pub extern "C" fn sspf_invoke(handle: *const c_char, op: *const c_char,
args: *const c_char) -> *mut c_char;
#[no_mangle] pub extern "C" fn sspf_shutdown(handle: *const c_char) -> *mut c_char;
#[no_mangle] pub extern "C" fn sspf_free(ptr: *mut c_char); // 🔴 谁分配谁释放
```
#### 六条铁律
| # | 铁律 | 不做的后果 |
|---|---|---|
| 1 | **内存所有权单向**:插件分配的字符串必须由插件的 `sspf_free` 释放,内核只用不 free | 跨 allocator free ⇒ 堆破坏 / 随机崩溃 |
| 2 | **所有调用 `catch_unwind`**:插件 panic 转成 `{ok:false,error}` JSON | panic 跨 FFI 是 UB ⇒ 主进程直接死 |
| 3 | **ABI 版本不匹配直接拒载**,不尝试兼容 | 静默错位读写 ⇒ 最难查的一类 bug |
| 4 | **构建信息必须校验**:`ABI 版本 + rustc 版本 + panic 策略` 三者全对才加载 | 换工具链重编的插件混进来 ⇒ 段错误 |
| 5 | **热替换前先排空**:引用计数归零才 `dlclose`;`dlclose` 后**复制到新路径再 `dlopen`** | 同 inode 重载会拿到旧句柄 ⇒ "改了没生效" |
| 6 | **插件崩溃不能拖垮内核**:可选 `--plugin-isolation=process`(子进程 + IPC) | 一个坏插件等于整站宕机 |
#### 工具链锁定
```toml
# rust-toolchain.toml(仓库根,全仓生效)
[toolchain]
channel = "1.95.0"
components = ["rustfmt", "clippy"]
profile = "minimal"
```
`pack.toml` 的 `[pack.build]` 必须写同一版本,CI 双向校验:
```bash
ACTUAL=$(rustc --version | awk '{print $2}')
[ "$ACTUAL" = "1.95.0" ] || { echo "工具链漂移: $ACTUAL != 1.95.0"; exit 1; }
# 插件侧:读 build_info 里的 rustc 字段,与 manifest 声明比对
```
> **为什么是 1.95.0 而不是最新 stable**:锁版本的意义是**全仓可复现 + 插件 ABI 一致**,
> 不是追新。1.95.0 是本机既有版本,立即可用;1.99.1 下载受本机代理限速(6 MB 卡死)。
> 要升级时按 §4.5 的四步走(改文件 → 全仓重编 → 插件全部重发 → 同步 pack.toml)。
🔴 **`panic = "abort"` 绝对禁止**(workspace 根 `Cargo.toml` 已有此注记):
abort 下 `catch_unwind` 抓不到 panic,铁律 2 直接失效。
#### 装载流程
```
启动扫描 plugins/*/manifest.toml
│
├─ 读 build_info → 校验 ABI / rustc / profile ──✗──▶ 拒载 + 记 ERROR(不退出)
├─ dlopen(RTLD_NOW | RTLD_LOCAL) ──✗──▶ 拒载 + 记 ERROR
├─ sspf_init(ctx) → handle 或 err ──✗──▶ sspf_shutdown + 拒载
└─ 注册到 plugin registry(op → handler)
```
**降级原则**:插件加载失败 ⇒ 该插件提供的 op 返回 `PLUGIN_UNAVAILABLE`,
其余功能照常。**内核绝不因为插件问题拒绝启动。**
### 4.6 「链接就好」的准确含义(这段是给未来的自己看的)
| 说法 | 准确含义 |
|---|---|
| 「低代码不用编译」 | ✅ 真的。元数据在库里,改数据即生效 |
| 「内核不用编译」 | ✅ 加业务包时不用。加**平台能力**(新契约面/新存储)时仍要编,但频率极低 |
| 「业务链接就好」 | 🟡 L2 是**静态链接**(`cargo build` 30s,增量更快),L3 才是运行期 `dlopen` |
| 「热更新」 | ⚠️ 只有 L0/L1 是热的;L2 要重启进程;L3 要 `dlopen` + 状态迁移 |
不要对外承诺「什么都能热更」—— 会被 L2 打脸。
---
## 5. 业务包与双向迁移(第 8 条后半)
### 5.1 `pack.toml`
```toml
[pack]
app_code = "asset"
name = "数据资源"
version = "1.0.0"
kernel = ">=0.4,<0.5" # 内核兼容区间(不匹配则拒载)
migratable = true # 允许导出到基线平台
[pack.compat]
baseline = "v7" # 兼容基线版本
frontend = "vue3" # 前端族(决定表单 JSON 方言)
tenant = false # 本期单租户
[[pack.tables]]
name = "asset_data_resource"
ddl = "schema/001_init.sql"
baseline_table = "asset_data_resource" # 基线平台上的表名(允许不同,导出时映射)
[pack.metadata]
forms = ["meta/forms/data_resource.json"]
models = ["meta/models/data_resource.json"]
menus = ["meta/menus.json"]
flows = []
[pack.build] # 仅 L2/L3 需要
kind = "static" # static | dylib | wasm
toolchain = "1.85" # L3 必填,用于 ABI 校验
```
### 5.2 迁移 = 打包 / 解包,不是重写
```bash
sspf pack export asset --format=baseline --out=/tmp/asset.jnpfpack
# 产出:DDL(转基线方言) + visualdev JSON(字段名对齐) + 菜单/授权 SQL + 导入脚本
sspf pack import /tmp/asset.jnpfpack --format=baseline
# 读基线平台导出的包 → 归一化成 sspf pack → 落库 + 注册
```
对齐点(**这四条对了,迁移就是搬箱子**):
| 对齐项 | 规则 |
|---|---|
| 物理表 | 列名 `f_` 前缀 + `f_id VARCHAR(50)` + 软删列;导出时若基线侧表名不同,用 `baseline_table` 映射 |
| 表单 JSON | 与基线平台 `visualdev` **同构**,一个字段都不改(前端要靠它渲染) |
| 菜单 | `f_url_address` / `f_en_code` / `f_system_id` 三列语义一致 |
| 权限 | `base_authorize` 的 `f_object_type` + `f_item_type` 取值一致 |
🔴 **反向迁移的坑**:基线平台的口令是 `md5(lower(md5(pwd)) + lower(secretkey))`,
SSPF 侧若用简化式,导出时必须做一次换算(`MIGRATION.md` §7 已记录,**单向、先备份**)。
### 5.3 业务包的可搬性验收
一个包算合格,必须能过这条:
```bash
# 1) 独立构建(不依赖内核源码)
cd packs/asset && cargo build --target-dir /tmp/asset-build
# 2) 依赖审计:只能有 sspf-sdk + serde
cargo tree -p asset --depth 1 | grep -v "sspf-sdk\|serde" && exit 1
# 3) 导出 → 导入往返(幂等)
sspf pack export asset --format=baseline --out=/tmp/a.pack
sspf pack import /tmp/a.pack --target=/tmp/fresh-db
sspf verify contract --db=/tmp/fresh-db # 必须全绿
```
---
## 6. MCP 2.0:自提示 + 分层加载(第 6 条落地)
### 6.1 为什么不能「一个能力一个工具」
| 方案 | 常驻 token | 问题 |
|---|---|---|
| 全量注册 60 个工具 | ~18K | 还没干活就烧掉 1/6 上下文 |
| 全量注册 200 个工具 | ~60K | 直接废掉 |
| **L0 + L1 + L2 按需** | **~1.8K 常驻,峰值 ~5K** | 需要多一次 discover/describe 往返 |
### 6.2 L0:常驻四件套(协议层只注册这四个)
| 工具 | 入参 | 返回 | 作用 |
|---|---|---|---|
| `sspf_context` | `scope: project\|user\|db\|env` | `{app, system, user, db, version, entities[], capabilities[]}` | 会话第一步;后续工具的默认上下文 |
| `sspf_discover` | `query?, category?, limit=10` | `[{id, title, one_liner, category, mutates, cost}]` | 意图 → 工具索引;不带 query 返回分类树 |
| `sspf_describe` | `tool_id, level=brief\|full\|pitfalls` | `{schema, hints{...}, examples[], related[]}` | 取完整 schema + 自提示 |
| `sspf_call` | `tool_id, args, dry_run?` | `{ok, data, effects[], next_actions[], hints[]}` | 统一执行 |
**为什么 `describe` 和 `call` 要分开**:AI 可以先 `dry_run` + 看 pitfalls 再决定要不要真跑;
也允许「describe 一次、call 多次」,省掉重复 schema 成本。
### 6.3 L1/L2:工具分类(约 55 个,分 12 域)
| 域 | 工具(id) | 说明 |
|---|---|---|
| `context` | `context.get` `context.set_app` | 应用/系统切换 |
| `schema` | `schema.table.create` `schema.table.list` `schema.table.describe` `schema.table.migrate` | 物理表 |
| `model` | `model.create` `model.update` `model.list` `model.describe` | 数据模型 |
| `form` | `form.create` `form.update` `form.release` `form.preview` `form.list` `form.export` `form.import` | 低代码表单 |
| `menu` | `menu.create` `menu.tree` `menu.update` `menu.delete` | 菜单 |
| `permission` | `perm.authorize` `perm.role.create` `perm.user.create` `perm.check` `perm.group.*` | 权限 |
| `dict` | `dict.type.upsert` `dict.data.upsert` `dict.list` `dict.resolve` | 字典 |
| `data` | `data.query` `data.insert` `data.update` `data.delete` `data.import` | 通用数据 |
| `workflow` | `flow.create` `flow.bind` `flow.publish` `flow.start` `flow.status` | 流程 |
| `verify` | `verify.gates` `verify.contract` `verify.smoke` `verify.diff` | 验证(🔴 只读) |
| `release` | `release.build` `release.deploy` `release.rollback` | 发布 |
| `ops` | `ops.health` `ops.logs` `ops.db.dump` `ops.db.restore` | 运维 |
### 6.4 自提示:工具自带「坑」,不靠文档
每个工具必须提供五段(缺一段 CI 红):
```rust
pub struct Hints {
when_to_use: &'static [&'static str], // 什么场景用
when_not_to_use: &'static [&'static str], // 什么场景别用(防误用)
preconditions: &'static [&'static str], // 前置(如「先 context 拿 dbLinkId」)
pitfalls: &'static [Pitfall], // ❌ wrong / ✅ right / 为什么 / P0-P2
examples: &'static [Example], // 🔴 必须能被 CI dry_run 跑通
}
```
实际渲染效果(`sspf_describe("form.create", level="pitfalls")`):
```json
{
"tool_id": "form.create",
"hints": {
"preconditions": ["先调 sspf_context 取 dbLinkId;为空会导致表单挂在默认库"],
"pitfalls": [
{
"severity": "P0",
"wrong": "字段名用 f_user_id 且 jnpfKey=inputNumber",
"right": "jnpfKey=relationForm + modelId=关联表单 id",
"rationale": "关联字段若用 inputNumber,前端渲染不报错但保存时外键为空,列表页显示空白。"
},
{
"severity": "P1",
"wrong": "enCode 带连字符 registration-form",
"right": "registration_form(自动 strip,但会多一条修正记录)",
"rationale": "物理列名不支持连字符;strip 后与前端路由不一致会导致菜单 404。"
}
],
"examples": [
{ "args": { "enCode": "asset_ledger", "fields": [] }, "note": "最小可用调用" }
]
}
}
```
**自提示的三条铁律**:
1. **单一真值源**:`registry` 里写一次,派生 tool schema / `describe` 输出 / 静态文档 / CI 用例
2. **examples 必须可执行**:CI 对每个 example 跑 `dry_run`,跑不通 = 构建失败(防文档腐烂)
3. **失败即教学**:错误返回必须带 `hints[] + next_actions[] + doc_ref`,让 AI 一次就能自纠
### 6.5 失败返回的形状(比成功更重要)
```json
{
"ok": false,
"error": {
"code": "FORM_ENCODE_EXISTS",
"message": "enCode 已存在:asset_ledger",
"field": "enCode",
"retryable": false
},
"hints": [
{ "level": "fix", "text": "换一个 enCode,或对已有表单调用 form.update", "auto_fixable": false }
],
"next_actions": [
{ "tool": "form.list", "args": { "keyword": "asset_ledger" }, "why": "先确认是否同一个表单" }
],
"doc": "sspf://errors#FORM_ENCODE_EXISTS"
}
```
### 6.6 Resources / Prompts / 协议特性
**Resources**(按需 `resources/read`,不占常驻上下文):
| URI | 内容 |
|---|---|
| `sspf://contract/endpoints` | 契约端点表(机器可读) |
| `sspf://ddl/base` | `base_*` DDL |
| `sspf://docs/module-howto` | 加业务模块指南 |
| `sspf://registry/tools` | 全量工具索引(离线用) |
| `sspf://pack/{app}` | 业务包清单与迁移状态 |
| `sspf://errors` | 错误码字典 |
**Prompts**(把多步流程固化成可复用模板):
| prompt | 作用 |
|---|---|
| `new_business_module` | 加业务模块(含 5 个 elicitation 追问) |
| `migrate_from_baseline` | 从基线平台导入 |
| `verify_all` | 跑全部闸门 + 出报告 |
| `diagnose_500` | 按错误码定位 |
**协议特性使用**:
- `outputSchema` + `structuredContent`:返回强类型,AI 不用解析文本
- `annotations`:`readOnlyHint`(verify/context 全只读)、`destructiveHint`(delete/restore)、`idempotentHint`(upsert)
- `elicitation`:缺关键信息时反向问用户(**不要瞎猜**)
- `Streamable HTTP`:团队共享一个 MCP 实例;本地 stdio 给单人
### 6.7 验收判据
一个「AI 能独立完成」的闭环,必须全绿:
```
自然语言需求
→ sspf_context(拿 app/db)
→ sspf_discover("建一个带审批的报销单")
→ sspf_describe("form.create", pitfalls)
→ sspf_call("schema.table.create") ← dry_run 先看 DDL
→ sspf_call("form.create")
→ sspf_call("menu.create")
→ sspf_call("perm.authorize")
→ sspf_call("form.release")
→ sspf_call("verify.gates") ← 必须全绿
→ 前端页面可打开、可增删改查
```
**任一步失败,AI 必须能靠 `hints + next_actions` 自纠,不需要人介入。** 这是 MCP 层的唯一 KPI。
---
## 7. 契约与命名(第 7 条落地)
### 7.1 唯一判据:**前端 / 移动端 / 存量库是否「依赖」它**
「依赖」的严格定义:**拿它做判断、查找、拼路径、解析、判分支**。
只是「显示给人看」的不算依赖。
| 类别 | 举例 | 处理 |
|---|---|---|
| **结构性字符串**(前端用它做逻辑) | HTTP 路径 `/api/permission/Users`、响应键名 `data.list`、请求头 `Vue-Version: 3`/`App-Code`/`Jnpf-Origin`、错误码 `602`、枚举值(`f_type` 的 1/2、`f_is_system` 的 1/2)、菜单 `urlAddress`/`enCode`、表单 JSON 的 `jnpfKey`、cipher key 字面量 | ❌ **一个字都不改** |
| **数据库标识**(存量库迁移依赖) | 表名 `base_user`、列名 `f_id`/`f_en_code` | ❌ **一个字都不改** |
| **展示性文案**(前端只渲染,不判断) | `msg` 里的中文提示、日志、注释、README | ✅ **全改**(语义一致即可) |
| **内部标识**(前端完全读不到) | crate 名、模块名、类型名、函数名、变量名、文件名 | ✅ **全改** |
🔴 这条判据解释了两个容易吵的点:
1. **`jnpfKey` 必须保留** —— 它出现在表单 JSON 里,前端 `componentMap.ts` 靠它选组件。
改了就白屏。名字难看也得留。
2. **`msg` 可以改** —— 前端只是 `message.error(res.msg)`,不解析内容。
但**语义不能变**("用户名已存在" 不能改成 "操作失败")。
**统一用词**(仅用于「非结构性」位置):
| 场合 | 用词 |
|---|---|
| 代码标识符 | `baseline`(`BaselineCompat`、`baseline_probe`、`crate::baseline`) |
| 文档 | **基线平台**(首次出现注明"兼容目标 v7") |
| 禁止 | `jnpf` / `引迈` / `JNPF` 出现在**新增**文件的标识符与文案里 |
### 7.2 `check-naming.sh` 的实现口径
不能简单 grep 关键词(会把契约字符串一起拦掉,改了就崩)。三层过滤:
```
第 1 层:豁免区(直接跳过,不检查)
docs/contract.md、db/schema.sql、src/**/routes.rs 里的路径字面量、
tests/**(断言要写真实路径)、任何 "..." 里被前端消费的常量白名单
第 2 层:必改区(出现即红)
*.rs / *.toml 里的 标识符(fn/struct/enum/mod/const/变量)、crate 名、注释
*.md 里的叙述文字(排除引用块与代码块中的契约示例)
第 3 层:人工复核区(黄灯,不阻断)
msg 文案、错误提示
```
实现建议:Rust 侧用 `syn` 解析取标识符(比正则可靠),文档侧用正则可接受。
🔴 **白名单必须是「显式文件 + 行号」而非「关键词豁免」** —— 否则会漏。
### 7.3 规范一致的落地方式
「规范保持一致」不等于「代码长得一样」。真正要一致的是**语义**:
| 规范项 | 一致性要求 |
|---|---|
| 命名规范(`f_` 前缀 / camelCase 键名 / 36 位 UUID) | 逐字一致 |
| 错误码语义 | 逐字一致(含 600/601/602 的用途区分) |
| 权限判据 | 两套并存(面 A 按菜单路径、面 B 按 `f_en_code`),语义各自一致 |
| 分层规范 | 一致,但用 Rust 的方式表达(crate 边界 + trait) |
| 提交/评审规范 | 沿用公司规范(`dacli/docs/尚数网基本开发规范v3.0.md`) |
---
## 8. 验证体系(「完全稳定/一致」怎么证明)
### 8.1 六道闸门 → 升级为八道
现状六道(静态 4 + 契约尺子 2)保留,新增两道:
| # | 闸门 | 测什么 | 何时跑 |
|---|---|---|---|
| 7 | `check-arch.sh` | crate 边界 AR1–AR5 + 业务包依赖审计 | 每次提交 |
| 8 | `diff-harness` | 同一语料打两个后端,归一化比对 | 每日 + 发版前 |
### 8.2 影子对账(diff harness)
```
tools/diff-harness/
├── corpus/ # JSONL 语料,一条一个请求
│ ├── auth.jsonl # 登录/CurrentUser/过期/无权限
│ ├── crud.jsonl # 5 组 base_* 的增删改查 + 分页 + 搜索
│ ├── menu.jsonl # 菜单树/多应用隔离
│ ├── permission.jsonl # 授权写入/读取/四源合并
│ └── errors.jsonl # 错误码矩阵(400/403/500/600/602)
├── run.sh # 双打 + 落盘
├── normalize.py # 归一化(见下)
└── report.html # 按端点分组的差异报告
```
**归一化规则(必须写死,否则天天误报)**:
| 类型 | 处理 |
|---|---|
| UUID / 主键 | → `<id>` |
| 时间戳 | → `<ts>`(保留"是否为空") |
| 列表顺序 | 按主键排序后再比 |
| 浮点/金额 | 转字符串比(防 `9.9` vs `9.90`) |
| 分页 total | 数据不同步时允许差,单独标 `DATA_DRIFT` 不算 P0 |
| 字段增删 | 基线有、SSPF 无 ⇒ **P0**;SSPF 多 ⇒ P2(前端不读就无害) |
**分级与出口**:
| 级别 | 定义 | 出口要求 |
|---|---|---|
| P0 | 字段缺失 / 类型不同 / 错误码不同 / 权限判定相反 | **= 0** |
| P1 | 值不同(非 ID/时间)/ 排序不同 | ≤ 3 且每条有豁免记录 |
| P2 | 多返回字段 / 文案差异 | 不限 |
### 8.3 切换的三道门(缺一不可)
1. **契约门**:八道闸门全绿 + diff P0=0
2. **体验门**:同一前端 E2E(登录→菜单→5 个核心页 CRUD)在两个后端全绿
3. **回滚门**:切流开关能 30 秒内切回;数据双写/单向同步有对账脚本
---
## 9. 路线图
> 阶段出口判据 = 硬条件,不达标不进下一阶段。周期是量级参考,不是承诺。
> 🔴 **P0 起每个阶段都要过内存门**(§2 判断 ⑥ 的预算表)—— 终端产品形态下,内存超标等于不可交付。
### P0 · 锁工具链、拆 crate(约 2 周)
| 项 | 内容 |
|---|---|
| 交付 | `rust-toolchain.toml` 锁 **1.95.0**;workspace 拆分(**contract / store / sdk 已落地**,kernel 原地待搬);`sspf-sdk` trait 定稿;`pack.toml` 定稿;`check-arch.sh`(AR1–AR5 + MEM1–MEM2);`check-naming.sh`(NM1–NM4);`mem-budget.sh` |
| 约束 | 行为零变化(九道闸门必须仍全绿) |
| 出口 | `cargo build` 通过;九闸绿;`packs/asset` 能独立构建;**空载常驻 ≤ 40 MB 实测(已达 7 MB)**;内部标识零原厂名(NM1–NM3) |
| 风险 | 拆 crate 引入循环依赖(已定位:`auth → jnpf` 只有 `is_jnpf` + `current_user` 3 处,`is_jnpf` 下沉 contract、分流上移到路由层即可解开) |
### P1 · MCP 2.0 骨架 + 基线适配器(约 4 周)
| 项 | 内容 |
|---|---|
| 交付 | `sspf-mcp`(4 元工具 + registry + discover/describe);`BaselineHttpAdapter`;首批 20 工具(context/form/menu/dict/permission/data);`sspf://` resources |
| 价值 | **立刻可用**:AI 通过 MCP 操作现有 Java 后端,开发速度提升先落地;同时充当 P4 对账的「参照侧」 |
| 出口 | §6.7 闭环全绿;单会话 token 峰值 < 8K;`examples` CI 全通过 |
| 风险 | 工具粒度设计反复 ⇒ 先按「一次调用 = 一个业务意图」定,别按 API 一一映射 |
**P1 已完成(2026-10-31)**:
- `crates/sspf-mcp`:协议(stdio NDJSON)+ registry + 4 元工具 + 五段自提示 + resources
- `NativeAdapter`(进程内,共用 `AppState`)+ `--mcp` 子命令 + `--mcp --with-http` 双形态
- 业务工具 **19 个**:context(1) / schema(3) / menu(3) / permission(6) / dict(3) / data(2)
- **授权闭环**:`authorize.grant` / `authorize.revoke` / `effective`(四源并集 + 应用过滤两组数)
+ `user.create`(建非管理员账号,让「授权是否真的生效」可验证)
- **多步模板 3 个**:`new_business_module` / `diagnose_menu_not_visible` / `verify_all`;
测试会核对模板里引用的工具 id 是否真实存在(防腐烂)
- **`BaselineHttpAdapter`**(`crates/sspf-adapter-baseline`):5 个只读 op 的端点映射
+ **形状归一化**(`{code,msg,data:{list}}` → native 形状),P4 对账的前置件
- 两道尺子:`mcp-smoke.sh` 32 条、`baseline-smoke.sh` 10 条
- 接入说明见 `docs/mcp.md`
**P1 待做**:业务工具补到约 55 个(缺 form / model / workflow 三大域)、
基线适配器按对账需要扩展 op。
> ⚠️ 轨道 A 的定位要摆正:它是**过渡期的开发加速器 + 对账基准**,不是终态。
> 终端产品交付形态只有 Rust 版(判断 ⑥)。
### P2 · 低代码元数据引擎 + Rhai 沙箱(约 6 周)
| 项 | 内容 |
|---|---|
| 交付 | `sspf-lowcode`:模型/表单/菜单/流程元数据 + 动态 CRUD + 发布版本;visualdev JSON 同构导入;`sspf-expr`(Rhai 沙箱,§4.3 全部限额);`Executor` trait 首版 |
| 出口 | 基线平台导出的表单 JSON,不改一个字段能在 SSPF 上渲染 + 存取;动态 CRUD 通过列白名单安全测试;Rhai 逃逸测试(`eval`/IO/递归/超深表达式)全部被拒 |
| 风险 | 表单 JSON 方言多(不同控件)⇒ 先覆盖 top 10 控件,其余降级 input |
**P2 已完成(2026-10-31,第一波 P2-a)**:
- `crates/sspf-lowcode`:`form`(控件树解析)/ `model`(表结构解析)/ `widget`(54 种 jnpfKey 分类)
/ `validate`(9 类诊断码),**纯计算**,38 个测试毫秒级跑完(AR7 钉住不许依赖 DB)
- DDL:`base_visual_dev` / `base_visual_release` 进 `schema.sql`,列与官方逐字一致(21 → 23 张表)
- 真实样例落地为 fixture:官方初始化数据里的「应收费用」表单(主表 6 字段 / 子表 8 字段)
- MCP 工具 3 个(只读):`form.list` / `form.describe` / `form.validate`;后两个支持 **inline JSON**
(不用入库就能校验草稿)
- `scripts/lowcode-smoke.sh` 8 条,含**两条反自证**:改坏 `__vModel__` 必须被抓、未知控件必须只 warn
**第一波刻意没做的**:动态 CRUD(写数据)、写表单定义。原因:写的前置是「解析 + 校验被真实数据验证透」,
否则等于让 AI 生成前端画不出来的 JSON。**动态 CRUD 已在第二波补上,写表单定义仍未做。**
**P2-b 已完成(2026-10-31,第二波)—— 动态 CRUD 闭环**:
- `sspf-lowcode::ddl`:**纯计算**建表 DDL(类型映射 / 复合主键 `(f_id, f_tenant_id)` /
系统列 / 逻辑删除列)+ `rewrite_model`(把真实列回写成 `f_tables_data` 的形态)
- 内核 `lowcode_ddl::create_and_sync`:建表 → 回写 `f_tables_data`(**幂等**;表已存在则跳过,
列不同报 `TABLE_EXISTS_DIFFERENT`,不自动 ALTER)
- 内核 `lowcode_crud` / `lowcode_check`:真实事务执行、子表差集对账、
**落库前三重校验**(单行唯一 `UNIQUE_CONSTRAINT_VIOLATED` / 业务主键组合唯一
`BUSINESS_KEY_VIOLATED` / 必填,失败一条 SQL 都不执行)
- MCP 工具 4 个(写):`schema.table.create` + `data.record.insert/update/delete`;
写工具**默认 `dryRun=true`**(不传就是演练)
- 开发期通道 `--seed-lowcode-demo [--dry-run]`:用官方 fixture 造一份可用的低代码功能
(固定 `enCode=receivableDemo`,幂等;prod 档开库前拒绝;dry-run 连库都不开)
- `scripts/mcp-smoke.sh` 扩到 **48 条**(M1–M47,其中阶段 B 用 python 动态驱动,
覆盖「演练不落库 → 真写 → 查证 → 子表差集 → 删除」)
- `scripts/lowcode-smoke.sh` 扩到 **15 条**(L9–L14:类型映射 / 复合主键 / 逻辑删除列 /
系统列视图类型,含两条反自证)
**P2-b 的关键判断(后续别改坏)**:
1. **建表后必须回写** `f_tables_data`:不回写 ⇒ CRUD 层在模型里找不到 `f_delete_mark`,
逻辑删除直接报 `LOGICAL_DELETE_UNSUPPORTED`(已真实踩到)。
2. 建表列来源 = **模型**(不是表单控件):官方 `f_tables_data` 本身就是建表后的回写产物,
列序与官方 DDL 逐列一致;模型驱动少一层「控件类型 ↔ DDL 类型」的多对一映射。
3. `f_delete_mark` 是 **INTEGER**,不是 boolean(官方 `TableFeildsEnum` 也是 `"int"`)。
4. **单租户**:`f_tenant_id` 固定 `"0"`,但列 `NOT NULL` 且**参与复合主键** —— 不能省。
5. 子表更新是**差集对账**(不是整条替换):入参没有的旧行会被删;主表则是部分更新。
**P2-b 刻意没做的**(留给 P2-c):读 `base_visual_release`(运行时读发布版)、
单据号生成器(需序号表)、真正的乐观锁(现在只写 `f_version=0`,不校验)。
**P2-b 的前置件**:`docs/visualdev-mechanism.md` —— 从 jnpf Java 源码逐条读出的运行时机制
(接口契约 15 个端点 / 列名规则 / 系统字段 / 自动填充 / 主子表),每条结论标了源码位置。
读这份文档时纠正了两个已实现代码里的错误判断(列名归因反了、`calculate` 不是只读)。
**实测发现的三条方言**(都已写进代码注释与测试):
1. `f_tables_data` 的 `columnName` **全是 null** ⇒ 只能从 `field` 推导,而推导**不等于**真实列名
(`F_CreatorTime` → `f_creatortime`,实际列是 `f_creator_time`)
⇒ 本 crate 只保证「表单 ↔ 模型设计稿」自洽;与真实库的一致性由 P2-b 的写工具在落库前比对
`information_schema`(对不上报 `COLUMN_MISMATCH`,拒绝写)
2. 子表内字段的 `tableName` 指向**主表**,不是子表 ⇒ 子表归属只能看父节点
3. `formRef` / `formModel` 是 Vue 变量名,不是固定常量(见过 `elForm`/`formData`,也见过 `formRef`/`dataForm`)
### P3 · 业务包 + 动态库 + 双向迁移(约 5 周)
| 项 | 内容 |
|---|---|
| 交付 | `sspf-plugin`(L2 静态 + **L3 dylib 完整实现**,§4.5 六条铁律全覆盖);`pack export/import --format=baseline`;`packs/asset` 样板;WASM 执行器(`Executor` 第二实现) |
| 出口 | §5.3 三条验收全过;asset 包往返幂等;**ABI 三个反自证**:版本不符拒载、插件 panic 不拖垮内核、热替换生效;插件内存超限被强杀 |
| 风险 | 表名/字段映射不一致 ⇒ 用 `baseline_table` 显式声明,禁止猜;`dlclose` 后重载拿到旧句柄 ⇒ 复制到新路径再 `dlopen` |
### P4 · 影子对账 + 切换准备(约 4 周)
| 项 | 内容 |
|---|---|
| 交付 | diff-harness + 语料库(≥300 条);切换开关(按 app_code / 菜单 / 用户组分流);回滚脚本;进程沙箱执行器 |
| 出口 | P0=0、P1≤3;体验门全绿;回滚演练成功一次;**整套峰值内存 ≤ 256 MB** |
| 风险 | 语料覆盖不足 ⇒ 用前端真实流量采样补语料(脱敏) |
### P5 · 切换与增强(持续)
| 项 | 内容 |
|---|---|
| 交付 | 真实 PG 支持收口;AI 协作流(需求 → 包 → 验证 → 发布);MCP 工具面全量化 |
| 出口 | 单二进制替代 Java 栈;部署步骤 ≤ 3 条命令;**目标硬件实测跑通业务 + 沙箱 + 计算三件套** |
---
## 10. 风险与待决策
### 10.1 已识别风险
| # | 风险 | 影响 | 缓解 |
|---|---|---|---|
| R1 | 拆 crate 破坏现有 147 端点行为 | 高 | P0 只搬不改;六闸 + diff 基线先跑一次存档 |
| R2 | 表单 JSON 方言覆盖不全 | 中 | 先 top 10 控件;缺失控件降级 + 明确报「不支持」而非静默 |
| R3 | Rust 动态库 ABI 崩 | 中 | 默认关 feature;只给明确需要的团队;强制版本校验 |
| R4 | MCP 工具粒度过细 → token 反弹 | 中 | 按业务意图设计;CI 统计 describe 后平均 token,超阈值报警 |
| R5 | 影子对账语料不足 → 假绿 | 高 | 语料必须来自真实流量采样 + 每条差异人工过一遍 |
| R6 | 「去原厂字眼」误改契约字符串 | 🔴 极高 | `check-naming.sh` 白名单 + 契约文件只读保护 |
| R7 | 业务包依赖偷偷膨胀 | 中 | `cargo tree` 审计进 CI;`sspf-sdk` 依赖锁死 serde |
### 10.2 待决策(开工前定,不定就按推荐走)
### 10.2 决策台账
**已定(2026-10-31)**:
| # | 决策 | 结论 | 约束 |
|---|---|---|---|
| D0 | 工具链 | **Rust 1.95.0**(`rust-toolchain.toml` 全仓锁定,本机既有版本) | L3 动态库强依赖;插件 `build_info` 必须匹配;升级走 §4.5 四步 |
| D3 | L3 动态加载 | **必做**(不是可选 feature 开关就不给降级余地) | §4.5 六条铁律;装载失败降级不退出 |
| D4 | 表达式引擎 | **Rhai**(沙箱化,能力全关 + 白名单) | §4.3 五项限额 + 四项约定 |
| D7 | 命名剥离判据 | **前端/移动端/存量库是否依赖**(§7.1) | 结构性字符串一字不改;展示性文案可改 |
| D8 | 部署形态 | **终端产品**(客户现场 / 一体机 / 边缘) | 内存预算进每阶段出口 |
**仍待定(不定就按推荐走)**:
| # | 决策 | 推荐 | 备选 |
|---|---|---|---|
| D1 | 数据库形态 | P0–P4 用 pglite(零依赖);P5 提供真实 PG 后端(同一 SQL 方言) | 直接上 PG(部署要求变高,违背终端形态) |
| D2 | MCP 传输 | 本地 stdio + 团队 Streamable HTTP 双支持 | 只 stdio |
| D5 | 工具命名 | MCP 层 `sspf_*`(4 个元工具)+ `域.动作`(tool_id) | 扁平命名 |
| D6 | 业务包目录 | `packs/<app_code>/`,与 `app_code` 同名 | 按团队分目录 |
| D9 | 插件隔离默认值 | `in-process`(快);客户端可切 `process`(稳) | 直接默认进程隔离(性能损失大) |
| D10 | 沙箱运行时 | WASM(wasmtime + 组件模型) | 独立进程 + 容器(重,但可跑任意语言) |
---
## 11. 与现有文档的关系
| 文档 | 职责 | 本文件与它的关系 |
|---|---|---|
| `CLAUDE.md` | 当前阶段红线 + 范围 | 本文件定长期架构;CLAUDE.md 的 §2 范围随阶段滚动 |
| `HANDOFF.md` | 现场交接 | 不变 |
| `MIGRATION.md` | Rust ⇄ 基线平台逐件映射 | 本文件 §5 是其上位设计 |
| `JNPF_COMPAT_SURFACE.md` | 面 B 规格 | 契约真源,不改 |
| `PERMISSION.md` | 权限与 `base_*` 红线 | 不改 |
| `HOWTO_MODULE.md` | 加模块操作手册 | P3 后改为「加业务包」手册 |
| 本文件 | **架构基线 + 路线图** | 阶段推进只改 §9 的勾 |
---
## 12. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-31 | 首版:三层定位、双轨并行、五条核心判断、crate 拆分、L0–L3 动态加载、MCP 2.0 元工具设计、业务包双向迁移、影子对账、P0–P5 路线 |