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:
1 parent
3f2d56be20
commit
3093ec49fe
1 file changed
+48
@@ -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 '*'`。
|
||||
|
||||
Reference in new issue
Block a user