docs(CLAUDE): 补 §4.2 发布物与消费方契约(方案 C)+ 命令速查 + 红线 14

- 新增 §4.2:出包/发布(release.sh --publish、target 后缀、Gitea Release)、
  两个自检(path 离线 / rlib 零重编)、Gitea 附件上限 500 的告警,
  以及消费方五条硬约束(rustc 1.95 / --extern 同源 axum / 不声明依赖 / lto=false / 只需 lib)
- §9 命令速查加 release.sh 出包与 --publish
- §7 加红线 14:包的消费契约不许静默破坏(改则同步 §6 文档与技能仓 fetch-platform.sh)
This commit is contained in:
admin committed 2026-11-05 14:05:05 +08:00
1 parent 3f2d56be20
commit 3093ec49fe
1 file changed
+48
+48
View File
@@ -179,6 +179,47 @@ ssw-platform/
- 钉住它的测试:`platform::system::tests::registry_resolution_and_menu_isolation`
(默认/未知头 → 主系统;`app-b` → 正确解析;两系统的菜单树互不可见)。
### 4.2 发布物与消费方契约(方案 C:预编译 rlib,2026-11-05)
> 机制与三条硬约束的完整版见 [`docs/SSPF-PLATFORM-PACKAGE.md`](docs/SSPF-PLATFORM-PACKAGE.md) §6。
> 一句话:**平台每版本打一个自包含包(内含预编译 rlib 闭包),技能/业务仓解包后用 `--extern` 直链,
> 零重编平台 17 个 crate、零重编 axum/tokio 与 serde。**
**出包 / 发布**
```bash
bash scripts/release.sh 0.5.0 # 出 dist/sspf-v0.5.0-<target>.tar.gz(含两个自检)
bash scripts/release.sh 0.5.0 --publish # 再推到 Gitea Release(tag v0.5.0,幂等)
```
- 产物名带**目标平台**(`rustc -vV` 的 host,如 `x86_64-apple-darwin`)—— rlib 与平台/架构绑定,
同版本不同平台是**不同包**。
- `lib/` 是构建产物 `deps/` 的**整目录副本**(`.rlib` + `.rmeta` + proc-macro `.dylib` + 原生 `.a`),
且 **bitcode-free**:出包时先 `cargo clean` 隔离目录,再
`--config profile.release.lto=false --config profile.release.embed-bitcode=false`
(否则 LLVM22 bitcode 让 macOS `ld`/libLTO21 解析失败)。
- 落盘前跑两个自检:**A** 包内 path 依赖 `--offline` 可编译(dev 回退可用);
**B** 最小消费方用 `--extern` + `-L dependency` 直链 rlib、零重编平台(方案 C 可用)。
- `--publish`:默认 `GITEA_URL=http://127.0.0.1:13300`、`GITEA_REPO=ssw/ssw-platform`,
凭据取本机 `git credential` 或 `GITEA_USER/GITEA_PASS`。
- 🔴 **Gitea 附件上限**:默认 100M,本包约 146M ⇒ 本机已把 `[attachment] MAX_SIZE` 调到 500
(`persist/gits/gitea/conf/app.ini`,备份 `app.ini.bak-*`,`docker restart jnpf-gitea` 生效)。
换环境必须同步调大,否则上传 413。
**消费方契约(改这层 = 改外部契约,别静默破坏)**
| 约束 | 原因 |
|---|---|
| 消费方 rustc == 包内 `rust-toolchain.toml`(1.95.0) | rlib ABI 与编译器版本绑定 |
| `.cargo/config.toml` 里 `--extern sspf/axum/tokio/serde/serde_json/http/bytes` + `-L dependency=lib` | sspf 公共 API 带 `axum::Json`/`http::HeaderMap`/`bytes::Bytes`,必须同一份 crate 实例 |
| 消费方 `Cargo.toml` **不声明**这些依赖 | 自己再编一份 = 同名 crate 两实例 → `E0308 mismatched types` |
| 消费方 release `lto = false` | 预编译 rlib 无 bitcode,开 LTO 报 `failed to get bitcode …` |
| 只需 `lib/` + `rust-toolchain.toml` | 源码(`crates/`、`src/`)仅 dev 回退,消费方可不解包 |
消费方取包(技能仓):`bash scripts/fetch-platform.sh <版本>` —— 按 tag + 目标平台从 Gitea Release
下载,本地 `dist/` 与 `SSPF_TAR` 作离线回退;随后生成 `.cargo/config.toml`
(**同时写 `rustflags` 与 `rustdocflags`**,否则 `cargo test` 的 doctest 解析不到 `sspf`)。
---
## 5. 契约与数据库「兼容 Java 版」策略(本期核心)
@@ -263,6 +304,9 @@ cipher 自证(免 node):`./target/release/sspf-admin --enc 123456`。
11. **低代码表必须「建表即回写」**:`schema.table.create`(或种子)建完表要回写 `f_tables_data`,否则 CRUD 层在模型里找不到 `f_delete_mark` ⇒ 逻辑删除直接报 `LOGICAL_DELETE_UNSUPPORTED`。
12. **单租户也不省 `f_tenant_id`**:值恒为 `"0"`,但列 `NOT NULL` 且参与复合主键 `(f_id, f_tenant_id)`;建表/写入都必须带这一列。
13. **写工具默认 `dryRun=true`**:新增写工具不传 `dryRun` 就是演练。这不只是防误写 —— 也是 AI 先看后写的唯一抓手。
14. **包的消费契约不许静默破坏**(方案 C,2026-11-05):`lib/` 必须是 `deps/` 整目录且 bitcode-free、产物名带 target、
消费方 `--extern` 同一份 `axum/tokio/serde/…`、消费方 `lto=false`。改任一项必须同步
`docs/SSPF-PLATFORM-PACKAGE.md` §6 与技能仓 `scripts/fetch-platform.sh`,否则消费方在链接期/类型期炸(§4.2)。
---
@@ -313,6 +357,10 @@ cargo build -p sspf-adapter-baseline --example probe # baseline-smoke 依赖
bash scripts/mem-budget.sh # 空载内存实测(P0 出口判据,预算 40 MB)
./target/release/sspf-admin --mcp # 起 MCP stdio 服务(供 AI 直接驱动,见 docs/mcp.md)
./target/release/sspf-admin --enc 123456 # cipher 自证
# ── 发布(方案 C:预编译 rlib 自包含包,见 §4.2)──
bash scripts/release.sh 0.5.0 # 出包 dist/sspf-v0.5.0-<target>.tar.gz(跑自检 A/B)
bash scripts/release.sh 0.5.0 --publish # 出包 + 推 Gitea Release(tag v0.5.0,幂等)
```
> 本机 curl 走系统代理,测 localhost 必须加 `--noproxy '*'`。