From f6c3ff64eeb6ab1480e2457ae591c6b469d537a9 Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 5 Nov 2026 09:28:47 +0800 Subject: [PATCH] =?UTF-8?q?feat(pkg):=20=E6=AF=8F=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E5=87=BA=E5=8C=85=E6=9B=BF=E4=BB=A3=20git=20=E4=BE=9D=E8=B5=96?= =?UTF-8?q?=EF=BC=88release.sh=20+=20=E6=96=87=E6=A1=A3=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 scripts/release.sh:读 crates/sspf 版本 → 编译预编译 sspf-admin 二进制 → 组装自包含发布包 dist/sspf-vX.Y.Z.tar.gz(预编译二进制 + 平台 crate 闭包 + Cargo.lock + rust-toolchain.toml + 前端源码),并自检验证离线可编。 - docs/SSPF-PLATFORM-PACKAGE.md §6 改为「每版本出包、消费方 path 依赖」模型, 废弃原 git tag 依赖写法;README/HANDOFF/CHANGELOG 同步。 - .gitignore 忽略 dist/ --- .gitignore | 4 + CHANGELOG.md | 3 + HANDOFF.md | 5 +- README.md | 12 +- docs/SSPF-PLATFORM-PACKAGE.md | 75 ++++++++++-- scripts/release.sh | 221 ++++++++++++++++++++++++++++++++++ 6 files changed, 303 insertions(+), 17 deletions(-) create mode 100755 scripts/release.sh diff --git a/.gitignore b/.gitignore index dafa5ce..58d6650 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,10 @@ target/ **/target/ +# 🔴 发布包(2026-11-05 依赖模型变更):release.sh 产出的自包含包是发布物, +# 不入版本库;消费方用 scripts/fetch-platform.sh(技能仓)或等价方式从 dist/ 取。 +dist/ + # 运行期数据(pglite 数据目录) src/backend/data/ src/backend/data.bak-*/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 8eea80c..3a53623 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ - 新增闸门 AR20(raw 不归一 / 共用包裹段 / 公开入口全持同一把锁)+ 反自证 15/15;新增探针 `db_raw_it.rs`(4 条:raw 键不归一、归一路径同时成立、guard 期间 `Db::exec` 被阻塞、`query_rows` 读 `pg_catalog`)。 - `Db::pg()` 文档补「要与平台共用串行域该走哪个入口」的指路表;销掉 v0.3.0 的「双锁」已知局限(`docs/known-limitations.md` 的 (bq))。 - 影响:面 A / 面 B 端点形状、码表、表结构零变化;`Platform` 的公开签名未改(`Finish::default()` 路径逐字等价)。`sspf` 版本 0.5.0。 +- 新增 `scripts/release.sh`:读 `crates/sspf` 版本 → `cargo build --release -p sspf-admin` → 组装自包含发布包 + `dist/sspf-vX.Y.Z.tar.gz`(预编译 `sspf-admin` 二进制 + 平台 crate 源码闭包 17 个 + `src/backend` + `Cargo.lock` + `rust-toolchain.toml` + 前端源码)。 + 消费方(技能仓 / 业务仓)解包到 `vendor/` 用 `path` 依赖接入,**不再直接依赖 git 仓、不再 clone 整个 monorepo、不再每次重编 20+ crate**。详见 `docs/SSPF-PLATFORM-PACKAGE.md` §6。 ## v0.4.0(2026-11-04,平台包零业务清理) diff --git a/HANDOFF.md b/HANDOFF.md index 6c5ac7b..247f2f6 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -199,7 +199,10 @@ **⏭ 业务仓(tdc-rs)P1 必做**(平台侧代劳不了):① 自带 `rust-toolchain.toml` 锁 1.95.0;② **删掉 `[profile.release] panic = "abort"`**(否则 catch-all 失效、契约 §6.5 破);③ `[profile.dev] incremental = false`; -④ 依赖写 `sspf = { path = "../ssw-platform/crates/sspf" }`(发布期换 git tag `v0.2.0`)。 +④ **依赖走发布包**(2026-11-05 变更):平台仓 `bash scripts/release.sh` 打 `dist/sspf-vX.Y.Z.tar.gz`, +业务仓用 `bash scripts/fetch-platform.sh vX.Y.Z`(或等价方式)解包到 `vendor/sspf-vX.Y.Z/`, +`Cargo.toml` 写 `sspf = { path = "vendor/sspf-vX.Y.Z/crates/sspf", version = "0.5" }`。 +**不再直接依赖 git 仓、不再 clone 整个 monorepo、不再每次重编 20+ crate**。详见 `docs/SSPF-PLATFORM-PACKAGE.md` §6。 --- diff --git a/README.md b/README.md index ba5a214..74dc50b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ ## 这是什么 -`sspf` 是 JNPF 契约的 Rust 实现,按 **git tag** 发布给业务仓。一个业务仓、一个进程、 +`sspf` 是 JNPF 契约的 Rust 实现,平台仓**每个版本打一个自包含发布包**(`dist/sspf-vX.Y.Z.tar.gz`, +含预编译 `sspf-admin` 二进制 + 平台 crate 源码 + `Cargo.lock`),消费方解包到 `vendor/` 用 `path` 依赖接入, +**不再需要直接依赖 git 仓**。一个业务仓、一个进程、 一个 PGlite 实例、一个端口,同时提供: | 面 | 内容 | 由谁提供 | @@ -23,8 +25,10 @@ ## 业务仓怎么接 ```toml -[dependencies] -sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.5.0" } +# 消费方:先把平台发布包解包到 vendor/(详见 docs/SSPF-PLATFORM-PACKAGE.md §6) +sspf = { path = "vendor/sspf-v0.5.0/crates/sspf", version = "0.5" } +# (旧写法 git + tag 仍可用,但已不推荐:要求构建时访问 git 且每次重编整个 monorepo) +# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.5.0" } ``` ```rust @@ -55,7 +59,7 @@ ssw-platform/ │ ├── contract.md # 【契约唯一真源】端点 / 返回形状 / 数据模型(附录 A 是尺子期望源) │ ├── SSPF-PLATFORM-PACKAGE.md # P0 需求 + 实施记录(v0.2.0) │ └── SSPF-BUSINESS-COMPOSITION.md # P1 需求 + 实施记录(v0.3.0) -├── scripts/ # 静态闸门(check-*)/ 运行时尺子(*-smoke)/ 生成段同步(pack-sync) +├── scripts/ # 出包(release.sh)/ 静态闸门(check-*)/ 运行时尺子(*-smoke)/ 生成段同步(pack-sync) ├── run.sh # install / build / dev / backend / frontend / stop / logs └── Cargo.toml # cargo workspace 根 ``` diff --git a/docs/SSPF-PLATFORM-PACKAGE.md b/docs/SSPF-PLATFORM-PACKAGE.md index 592aaef..960d26b 100644 --- a/docs/SSPF-PLATFORM-PACKAGE.md +++ b/docs/SSPF-PLATFORM-PACKAGE.md @@ -218,23 +218,64 @@ bash scripts/perm-smoke-jnpf.sh # 面 B 18/18(官方形状没被改坏 --- -## 6. 发布与业务仓依赖写法 +## 6. 发布与消费方依赖写法(每版本出包,不依赖 git 仓) -打 tag **`v0.2.0`**;CHANGELOG 只写「改了什么 / 什么影响」,5–8 行,不写过程与 commit hash。 +> 🔴 **2026-11-05 依赖模型变更**:原 §6 的「发布期用 `git = { tag }` 锁版本」**已废弃** +> (见 §6.5)。改为「平台仓每个版本打一个**自包含发布包**,消费方解包到 `vendor/` 后用 +> `path` 依赖吃进去」——消费方**不再直接依赖 git 仓**、不再每次构建都 clone 整个 monorepo +> 并重新编译 20+ 个本地 crate。 -```toml -# tdc-rs/Cargo.toml —— 开发期 -sspf = { path = "../ssw-platform/crates/sspf" } -# 发布期(换成 git tag 锁版本,路径按内网 Gitea 实际仓库改) -# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" } +### 6.1 为什么「纯预编译 rlib」不可行(务必理解) + +带类型的库 crate(如 `sspf`,消费方要 `use sspf::Platform`)**Cargo 原生不支持当依赖消费 +预编译 rlib**,且 `use sspf::*` 需要接口元数据(`.rmeta`)。⇒ 「消费方完全不编译平台库」在 +Rust 现状下**做不到**。 + +本包的形态是:**「预编译的 `sspf-admin` 二进制(字面)+ 平台 crate 的自包含源码 + `Cargo.lock`」**。 +消费方依赖包内**源码路径**——平台库仍会编译一次(Rust 库常态),但**不再碰 git、不再 clone +monorepo、不再重编 20+ crate**。预编译二进制留给「直接跑平台」运行态模式。 + +### 6.2 平台仓出包 + +打 tag **`vX.Y.Z`**(与 `crates/sspf` 的 `version` 对齐);然后: + +```bash +bash scripts/release.sh # 读 crates/sspf 的 version,出 dist/sspf-vX.Y.Z.tar.gz +bash scripts/release.sh 0.5.1 # 或显式指定版本(覆盖 crates/sspf 的 version) ``` -✅ **git 依赖已实测(2026-11-04 打 tag 当场验的)**:仓外最小项目只写 -`sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }`, -`cargo check` **37.95s 通过** —— cargo 正确解析了本仓 workspace 根,全部依赖都标注 -`?tag=v0.2.0#9083394b`,`sspf 0.2.0` 可 `use`,与 path 依赖等价。 +产物 `dist/sspf-vX.Y.Z/` 含: -业务仓(tdc-rs)侧必须同步配合的 4 件事,**属于 P1,不阻塞 P0**: +| 路径 | 用途 | +|---|---| +| `bin/sspf-admin` | 🔴 预编译二进制(字面,平台侧已 release 编译),可直接跑 | +| `crates/*` | 🔴 平台 crate 自包含源码(sspf 门面 + 其 path 依赖闭包,共 17 个) | +| `src/backend/` | 🔴 内核 lib(`ssw-platform`)—— sspf 的 path 依赖 | +| `Cargo.toml` | 🔴 workspace 根(`version.workspace = true` 继承靠它) | +| `Cargo.lock` | 🔴 锁定整个闭包,消费方 `--offline` 也能编译 | +| `rust-toolchain.toml` | 工具链版本(信息性;消费方需自带同名文件) | +| `docs/SSPF-PLATFORM-PACKAGE.md` | 本文件 | +| `README.md` | 包自述与消费步骤 | +| `frontend/` | 平台前端源码(不含 node_modules/dist,可选随包) | + +脚本最后会**自检验证**:构造最小消费方,`cargo build --offline` 确认包内 path 依赖闭包 +可被离线编译通过,再落盘 tar.gz。 + +### 6.3 消费方怎么接 + +1. 把 `dist/sspf-vX.Y.Z.tar.gz` 解包到消费方仓库的 `vendor/sspf-vX.Y.Z/`。 + (技能仓:`bash scripts/fetch-platform.sh vX.Y.Z` 自动下载/解包。) +2. `Cargo.toml`(建议放 `[workspace.dependencies]`,成员一律 `sspf = { workspace = true }`): + + ```toml + # 升版本 = 改这一行(路径 + version 一起改),不许在任何成员里写第二份 + sspf = { path = "vendor/sspf-vX.Y.Z/crates/sspf", version = "0.5" } + ``` + +3. `.gitignore` 加 `vendor/`。 +4. `cargo build` 即可(`--offline` 也行,包自带 `Cargo.lock`)。 + +### 6.4 业务仓侧必须同步配合的 4 件事(仍适用) 1. 补 `rust-toolchain.toml` 锁 `1.95.0`(rustup 按 cwd 选版本,平台侧代劳不了)。 2. **删掉 `[profile.release] panic = "abort"`**:单进程链接后 release profile 由业务仓根决定, @@ -245,6 +286,16 @@ sspf = { path = "../ssw-platform/crates/sspf" } (`smoke.sh` / `check-boundary.sh` / `check-contract.sh` / `check-entity.sh` / `check-upstream-tests.sh`), 401/403 裸三键与静态 SPA 深链行为一字不改。 +### 6.5 旧写法(已废弃,留作历史) + +```toml +# ❌ 不再推荐:要求消费方构建时访问 git 服务、且每次重编整个 monorepo +# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" } +``` + +git 依赖**仍可用**(cargo 能解析本仓 workspace 根,2026-11-04 实测 `cargo check` 37.95s 通过), +但**不再作为推荐路径**。新消费方一律走 §6.3 的包依赖。 + --- ## 7. 明确不做(P0 边界) diff --git a/scripts/release.sh b/scripts/release.sh new file mode 100755 index 0000000..39dc7d0 --- /dev/null +++ b/scripts/release.sh @@ -0,0 +1,221 @@ +#!/usr/bin/env bash +# +# release.sh —— 给「技能 / 业务」消费方打「自包含发布包」 +# +# 为什么要有它(2026-11-05 定的依赖模型变更): +# 消费方(技能仓 `~/.agents/skills/ssw-jnpf-lite-rust`、未来的业务仓 `tdc-rs`) +# **不再**直接依赖本 git 仓、不再每次构建都 clone 整个 monorepo 并重新编译 20+ 个 +# 本地 crate。改由本脚本每个版本产出一个**自包含包** `dist/sspf-vX.Y.Z.tar.gz`, +# 消费方把它解包到 `vendor/`,用 `path` 依赖指进去即可。 +# +# 包的构成(自包含,消费方 `--offline` 也能编译): +# sspf-vX.Y.Z/ +# ├── bin/sspf-admin # 🔴 预编译二进制(字面,平台侧已 release 编译) +# ├── crates/<17 个 sspf-* 闭包> # 🔴 平台 crate 自包含源码(path 依赖吃这层) +# ├── src/backend/ # 🔴 内核 lib(ssw-platform)—— sspf 的 path 依赖 +# ├── frontend/ # 平台前端源码(不含 node_modules/dist,可选随包) +# ├── Cargo.toml # 🔴 workspace 根(继承 version/edition 靠它) +# ├── Cargo.lock # 🔴 锁定整个闭包,消费方 --offline 才解析得开 +# ├── rust-toolchain.toml # 工具链版本(信息性;消费方需自带同名文件) +# ├── docs/SSPF-PLATFORM-PACKAGE.md # 消费方式说明 +# └── README.md # 本包的自述 +# +# ⚠️ Rust 库硬约束(务必理解,否则会以为「完全不编译平台」能做到): +# 带类型的库 crate(如 sspf,消费方要 `use sspf::Platform`)**没法被「纯预编译 rlib」 +# 当依赖吃**—— Cargo 原生不支持消费预编译 rlib,且 `use sspf::*` 需要接口元数据(.rmeta)。 +# 所以「消费方完全不编译平台库」在 Rust 现状下**做不到**。本包的形态是: +# 「预编译的 sspf-admin 二进制(字面)+ 平台 crate 的自包含源码 + Cargo.lock」, +# 消费方依赖包内**源码路径**——仍会编译一次平台库(Rust 库常态),但**不再碰 git、 +# 不再 clone 整个 monorepo、不再每次重编 20+ crate**。预编译二进制留给「直接跑平台」模式。 +# +# 用法: +# bash scripts/release.sh # 以 crates/sspf 的 version 为版本号出包 +# bash scripts/release.sh 0.5.1 # 显式指定版本(覆盖 crates/sspf 的 version) +# +set -euo pipefail + +# 切到仓库根(无论从哪里调用) +cd "$(dirname "$0")/.." +REPO_ROOT="$(pwd)" + +# ── 1. 决定版本号 ────────────────────────────────────────────── +if [[ $# -ge 1 ]]; then + VERSION="$1" +else + VERSION="$(python3 - <<'PY' +import re,os +p=os.path.join("crates","sspf","Cargo.toml") +t=open(p).read() +m=re.search(r'^version\s*=\s*"([^"]+)"', t, re.M) +print(m.group(1)) +PY +)" +fi +# 🔴 目录/包名带 v 前缀,与 git tag(vX.Y.Z)对齐;crate 自身 version 是无 v 的 X.Y.Z +PKG="sspf-v${VERSION}" +DIST_DIR="dist" +PKG_DIR="${DIST_DIR}/${PKG}" + +echo "==> 出包版本: ${VERSION}" +echo "==> 目标目录: ${PKG_DIR}" + +# ── 2. 编译预编译二进制 sspf-admin(平台侧 release 构建)────────── +echo "==> cargo build --release -p sspf-admin" +cargo build --release -p sspf-admin + +BIN="target/release/sspf-admin" +if [[ ! -x "${BIN}" ]]; then + echo "!! 找不到预编译二进制: ${BIN}" >&2 + exit 1 +fi + +# ── 3. 组装目录 ──────────────────────────────────────────────── +rm -rf "${PKG_DIR}" +mkdir -p "${PKG_DIR}/bin" "${PKG_DIR}/crates" "${PKG_DIR}/src" "${PKG_DIR}/docs" "${PKG_DIR}/frontend" + +# 3.1 预编译二进制 +cp "${BIN}" "${PKG_DIR}/bin/sspf-admin" +BIN_SIZE="$(du -h "${PKG_DIR}/bin/sspf-admin" | cut -f1)" +echo "==> bin/sspf-admin (${BIN_SIZE})" + +# 3.2 计算 sspf 的 path 依赖闭包(纯文件系统 BFS,离线安全;不含 sspf-admin 自身源码) +# 输出每行:源目录包内相对目标 +CLOSURE="$(python3 - <<'PY' +import os, re +root=os.getcwd() +start=os.path.join(root,"crates","sspf") +seen=set() +def resolve(cdir): + ct=os.path.join(cdir,"Cargo.toml") + if not os.path.isfile(ct): return + seen.add(os.path.normpath(cdir)) + txt=open(ct).read() + for m in re.finditer(r'path\s*=\s*"([^"]+)"', txt): + nd=os.path.normpath(os.path.join(cdir, m.group(1))) + if os.path.isdir(nd) and nd not in seen: + resolve(nd) +resolve(start) +for d in sorted(seen): + rel=os.path.relpath(d, root) + if rel=="src/backend": + print(f"{rel}\tsrc/backend") + else: + print(f"{rel}\t{rel}") # crates/xxx -> crates/xxx +PY +)" + +RSYNC_EXCLUDES=( + --exclude target --exclude .git + --exclude __pycache__ --exclude '*.pyc' + --exclude node_modules --exclude .vite --exclude dist +) + +CRATE_N=0 +while IFS=$'\t' read -r src dst; do + [[ -z "${src}" ]] && continue + rsync -a "${RSYNC_EXCLUDES[@]}" "${src}/" "${PKG_DIR}/${dst}/" + if [[ "${dst}" == crates/* ]]; then CRATE_N=$((CRATE_N+1)); fi +done <<< "${CLOSURE}" +echo "==> 复制 ${CRATE_N} 个 crate + src/backend(闭包)" + +# 3.3 workspace 根 + lock + toolchain(消费方 --offline 解析继承字段靠它们) +cp Cargo.toml Cargo.lock rust-toolchain.toml "${PKG_DIR}/" +echo "==> Cargo.toml / Cargo.lock / rust-toolchain.toml" + +# 3.4 消费方式说明 +cp docs/SSPF-PLATFORM-PACKAGE.md "${PKG_DIR}/docs/" + +# 3.5 平台前端源码(不含 node_modules/dist,可选随包;C 用户明确「前端可以留着」) +if [[ -d src/frontend ]]; then + rsync -a "${RSYNC_EXCLUDES[@]}" src/frontend/ "${PKG_DIR}/frontend/" + echo "==> frontend/(源码,已排除 node_modules/dist)" +fi + +# 3.6 生成包内 README +cat > "${PKG_DIR}/README.md" < README.md" + +# ── 4. 打 tar.gz ─────────────────────────────────────────────── +TAR="${DIST_DIR}/${PKG}.tar.gz" +tar -czf "${TAR}" -C "${DIST_DIR}" "${PKG}" +TAR_SIZE="$(du -h "${TAR}" | cut -f1)" +echo "==> 已打包: ${TAR} (${TAR_SIZE})" + +# ── 5. 自检:包内 path 依赖闭包能否被最小消费方离线编译 ──────── +echo "==> 自检验证中(构造最小消费方,--offline 编译)" +TMPCON="$(mktemp -d)" +cat > "${TMPCON}/Cargo.toml" < "${TMPCON}/src/main.rs" <<'EOF' +use sspf::Platform; +fn main() { + println!("sspf VERSION = {}", sspf::VERSION); + let _ = Platform::new(); + println!("OK: path-dep closure resolves & compiles"); +} +EOF +if (cd "${TMPCON}" && cargo build --offline 2>&1 | tail -3); then + echo "==> ✅ 自检通过:${PKG} 可被最小消费方 --offline 编译" +else + echo "!! ❌ 自检失败:包内闭包无法离线编译,请检查 Cargo.lock / workspace 根" >&2 + rm -rf "${TMPCON}" + exit 1 +fi +rm -rf "${TMPCON}" + +echo "" +echo "==================================================" +echo "✅ 出包完成: ${PKG}" +echo " 目录: ${PKG_DIR}" +echo " 压缩包: ${TAR} (${TAR_SIZE})" +echo " 预编译二进制: bin/sspf-admin (${BIN_SIZE})" +echo " crate 闭包: ${CRATE_N} 个 + src/backend" +echo "=================================================="