craftlabs-authorization-sdk/docs/engineering/tracks/03-client-sdk.md

轨道 C：craftlabs-authorization-sdk（客户端）— 并行实施包

对齐：BPM §7 BP-10 · 工程布局 §5
事实：craftlabs-auth-core / bitanswer / selfhosted；schemas/；examples/；平台 不嵌入 Native。

---

1. SDK 版本线与 Native 标签

原则	说明
独立 SemVer	SDK 不与平台 Fat JAR 版本号绑定；对外话术分两条线。
MAJOR	Schema 不兼容、公共 API 破坏、JNI 契约不兼容。
MINOR	向后兼容扩展：可选 Schema 字段、新 API、新示例。
PATCH	Bugfix、文档；无契约变化。
预发布	-rc.N 与平台 UAT/比特联调对齐；不用平台版本代替 SDK 版本。
Native	每次发行 JAR + 各 OS native 同版本；Git 单 tag（如 v1.4.2）；禁止只升其一。

---

2. 平台迭代 × SDK 工作对照

迭代	平台焦点	SDK 必需	SDK 非阻塞
I1	M11 脚手架	无	文档：与平台产物区分
I2	M1	无	文档
I3	M2、M10-F01	无	文档
I4	M3、M4、激活回写	烟测路径下 推荐 PATCH 修缺陷	文档/示例与 BP-10 口径
I5	M5、M6、Webhook、BP-10	Schema + AuthConfigs + examples 同步	Native 与 Webhook 无关
I6	UAT	冻结 SDK 版本、CHANGELOG、BitAnswer 兼容矩阵	禁止 UAT 周做 MAJOR Schema

小结：I1～I4 以文档/示例为主；I5 起 Schema/Java/示例为硬交付；I6 冻结与清单。

---

3. BP-10：何时 bump Schema / Java / 文档 / 示例

变更类型	Schema	Java AuthConfigs	docs	examples
新增可选字段	MINOR（或 PATCH）	同交付对齐	字段说明	可选示例
新增必填/收紧/改名	MAJOR 或 breaking 策略	必须同步	迁移说明	必须更新模板
仅 description	PATCH	通常无	可选	可选
M6 仅改发布流程、JSON 形态不变	无	无	手册可选	无

硬规则：影响「平台导出 → Schema → 客户端」任一环的变更，同一发布列车 更新 Schema + Java（若有）+ 示例。

---

4. SDK 发布检查清单（非平台 Fat JAR）

1. mvn -f java/pom.xml clean verify；Native 各 OS 构建通过。
2. mvn deploy：craftlabs-auth-* 版本一致；无 spring-boot-maven-plugin repackage。
3. Native 与 JAR 同版本 发布。
4. Schema + examples CI 校验。
5. CHANGELOG：破坏性变更、BitAnswer 版本区间、已知平台导出版本（若可公开）。
6. 兼容矩阵：SDK 版本、厂商库、OS/JDK；与平台应用版本 分列。
7. Git tag；不含 java -jar platform.jar 说明。

---

5. V1.1+ SDK 增强（规划）

主题	说明
更严校验	CI 对 examples 与 Schema 双向校验；平台脱敏 fixture
Fixtures	最小/完整/非法 JSON 绑定 Schema 版本
可选 config-model 薄模块	供平台后端复用 POJO 无 native；另案评审

---

6. 防混淆话术

SDK = craftlabs-auth-* 库 + Native + Schema/示例；平台 = 独立仓 bootstrap Fat JAR，无 BitAnswer Native，版本号线独立。并行以 I5（BP-10） 为契约首要对齐点，I6 为 SDK 冻结点。

---

7. 修订记录

日期	说明
2026-04-06	由并行 Task 产出并入库。