diff --git a/CLAUDE.md b/CLAUDE.md index cdba4b2..fe5c1eb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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-.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-.tar.gz(跑自检 A/B) +bash scripts/release.sh 0.5.0 --publish # 出包 + 推 Gitea Release(tag v0.5.0,幂等) ``` > 本机 curl 走系统代理,测 localhost 必须加 `--noproxy '*'`。