craftlabs-authorization-sdk/docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md

工作区工程划分与仓库边界 — 架构说明

角色：资深架构师对工作区现有资产与 创飞客户商务与交付管理平台 相关文档的对照走查结论。
范围：本 Git 工作区根目录 craftlabs-authorization-sdk 的 物理目录、构建边界、发布物、与外部工程的契约；不在本提交中迁移 java/、native/ 路径（避免破坏既有 CI 与本地脚本）。
关联：系统架构全景（图 + 全量组件） · 功能模块 · BPM 与排期 · 平台与比特对接 · 三轨并行执行索引 · 根目录 engineering/ 清单

---

1. 走查结论（摘要）

维度	现状	架构建议
工作区身份	以 客户端授权 SDK（Java + Native）为核心，配套 Schema、示例配置、产品/平台文档	保持本仓库 「授权 SDK + 契约资产」 为一等公民；商业交付平台（Spring Boot 4.0. + Vue）不宜与 JNI/native 强耦在同一 Maven 树内混建
构建	java/ Maven 多模块；native/ CMake 动态库	CI 双轨：Java 与 Native 可并行；平台后端/前端 独立仓库或独立根级目录 时再挂接新 workflow
文档	docs/ 已覆盖比特规则、Callback、创飞平台 BPM、模块、权限	文档继续集中在 docs/；工程边界以本文 + engineering/ 为 单一事实来源（SSOT）
缺口	根目录无 README；平台 Webhook、管理端未在代码层体现	用 **engineering/planned/** 占位说明 推荐独立仓库名与技术栈；实现阶段按 manifest 开仓

---

2. 工作区逻辑分层（C4-L1）

flowchart TB
  subgraph WS["本工作区 craftlabs-authorization-sdk"]
    S[SDK Java API]
    N[Native craftlabs_auth_bitanswer]
    SCH[schemas/ craftlabs-auth-config]
    EX[examples/]
    DOC[docs/]
  end

  subgraph EXT["规划中的独立工程（见 engineering/planned）"]
    WH[license-webhook-ingress]
    API[delivery-platform-api]
    UI[delivery-platform-ui]
  end

  BA[比特安索云/控制台]
  CLI[现场客户端产品]

  N --> S
  S --> CLI
  SCH --> CLI
  WH -->|POST Callback| BA
  API -->|读写字段| WH
  UI --> API
  DOC -.->|约束| SCH

原则：运行时依赖从平台 API → Webhook → 比特 为一条链；客户端仅依赖 Maven 发布的 SDK 工件 + JSON 配置（校验用 Schema），不依赖平台 UI。

---

3. 物理目录与职责（当前实现）

路径	工程类型	职责	构建命令（摘要）
**java/**	Maven pom 聚合	craftlabs-auth-core（配置模型/校验/桥接）、craftlabs-auth-bitanswer、craftlabs-auth-selfhosted、craftlabs-auth-tests	mvn -f java/pom.xml verify
**native/**	CMake	libcraftlabs_auth_bitanswer、JNI、自研 HTTP 占位	见 native/build 或项目 README
**schemas/**	JSON Schema	craftlabs-auth-config 契约，与 AuthConfigs 对齐	无编译；CI 可 ajv/脚本校验
**examples/**	样例	config/*.json、java/python 烟测	随测试引用
**docs/**	文档	产品、比特对接、工程架构	无构建
**engineering/**	工程元数据	manifest、planned 占位、边界说明	无构建

禁止：在未做迁移方案前，将 Spring Boot 应用 塞进 java/ 下与 craftlabs-auth-* 并列 —— 会导致发布周期、依赖（Boot vs 库消费者）冲突。
平台端正确做法：在 独立仓库 内 多模块开发，由 唯一 bootstrap 模块 执行 spring-boot-maven-plugin repackage，对外只发布 一枚 Fat JAR（见 §5.3）。

---

4. Maven 模块边界（SDK 内部）

craftlabs-auth-parent
├── craftlabs-auth-core      # 无第三方授权运行时；配置、NativeBridge 接口
├── craftlabs-auth-bitanswer # System.loadLibrary + BitAnswerProvider
├── craftlabs-auth-selfhosted
└── craftlabs-auth-tests     # 集成/配置测试

• 对外发布坐标：以 cn.craftlabs:craftlabs-auth-* 为准；版本与 changelog 在发布流水线维护。
• 平台后端若需读取同一配置模型：优先 复制 DTO + 共用 Schema，或将来抽取 **craftlabs-auth-config-model 极小 jar**（另案）；禁止在平台可执行 JAR 中引入 craftlabs-auth-bitanswer（会拉起 JNI/native 期望，属边界错误）。

---

5. 客户端 SDK 与平台端：深入评估与防混淆

5.1 二者不可混为一谈

维度	客户端 SDK（本仓库 java/ + native/）	平台端后端（delivery-platform-api 等独立工程）
运行位置	客户现场业务进程 / 边缘 AI 设备	创飞机房 / 云（VPC）
核心职责	Bit_Login、特征项、本地/云授权运行时	合同、交付、SN 台账、Callback 处置、RBAC、报表
典型依赖	BitAnswer 官方 native + BitAnswerProvider	Spring Boot、DB、MQ；无 BitAnswer 客户端 native
交付形态	多枚 薄 JAR + 各 OS 动态库（与 JAR 同版本）	单枚可执行 Fat JAR（或容器内同等物）每个可部署服务一枚
Spring Boot	不使用（库代码，避免与宿主应用 Boot 版本冲突）	使用（4.0. 线），仅 启动模块 打 Fat JAR
配置	craftlabs-auth-config JSON + Schema	平台自有 application.yml + PostgreSQL 15 数据源；ORM 为 MyBatis-Plus；JSON Schema 仅用于 校验导出的客户端配置（若实现）

硬规则：平台进程 不得 System.loadLibrary("craftlabs_auth_bitanswer")；不得在服务端 classpath 引入 **craftlabs-auth-bitanswer** 模块（除非未来出现「纯 Java、无 native」的只读适配且经架构评审——当前 不存在）。

5.2 命名与仓库层面的识别

• SDK 坐标：cn.craftlabs:craftlabs-auth-*（artifact 前缀固定，文档与 BOM 中一眼可辨）。
• 平台坐标：建议 cn.craftlabs.platform:* 或 cn.craftlabs.delivery:*（禁止复用 craftlabs-auth-* 作为应用模块 artifactId）。
• CI 流水线：SDK 与 platform-* 使用 不同 job，产物上传 不同仓库路径（Maven .../sdk/ vs .../platform/）。

5.3 单 JAR 部署 vs 分模块开发（平台 / Webhook）

诉求：运维只下发 一个 app.jar（或镜像内 java -jar app.jar）；研发仍按 领域拆分模块，边界清晰、编译快、测试可隔离。

推荐 Maven 形态（每个 独立可部署后端 各自一套父 POM，勿与 SDK 父 POM 合并）：

delivery-platform/                    # 或 license-webhook 同理
├── pom.xml                             # packaging=pom，dependencyManagement
├── platform-domain/                    # 实体、领域服务接口、无 Spring Web
├── platform-application-service/       # 用例、事务边界、调用 domain
├── platform-adapters-web/              # REST Controller、DTO 映射
├── platform-adapters-persistence/      # MyBatis-Plus Mapper / XML（PostgreSQL 15）
└── platform-bootstrap/                 # 唯一含 main + spring-boot-maven-plugin
    └── src/main/java/.../Application.java

• 仅 platform-bootstrap 配置 spring-boot-maven-plugin 的 **repackage**（或 executable），依赖其余模块为 普通 jar，打进 Fat JAR / Executable JAR。
• mvn -pl platform-bootstrap -am package → 产出 platform-bootstrap/target/*.jar 一枚，即部署单元。
• 开发体验：IDE 打开 聚合工程，多模块跳转、分模块单测；禁止在多个模块上重复声明 repackage（否则出现多枚「可执行」JAR 或依赖错乱）。

可选变体：

• 分层 jar（Spring Boot 2.3+）：layertools 优化镜像层 —— 仍对应 单次构建的一条启动入口。
• Webhook 与 Core API 分开发布：两个 Maven 工程各产 一枚 Fat JAR（webhook-bootstrap.jar、platform-bootstrap.jar），比强行塞进一个进程更符合 扩容与故障隔离；若强制单进程，可用 同一 bootstrap 模块多 profile（一般 不推荐，耦合过高）。

5.4 SDK 侧构建（对照：不是 Fat JAR）

• craftlabs-auth-core / bitanswer / selfhosted 均为 library jar，不打 spring-boot-maven-plugin。
• 客户端应用（客户自有 Spring Boot 或其它）自行打包 Fat JAR，声明依赖 craftlabs-auth-bitanswer + 携带 匹配版本 native。
• 平台 Fat JAR 与 客户应用 Fat JAR 是 两条完全不同的发布线，不得在平台 POM 里 dependency 整条 SDK 父工程。

5.5 评审检查（单 JAR + 分模块）

• 全仓库是否 只有一个 模块声明 spring-boot-maven-plugin 的 repackage（针对该可部署应用）？
• mvn dependency:tree -pl platform-bootstrap 中是否 无 craftlabs-auth-bitanswer？
• 部署文档是否写清：启动类 FQCN、java -jar 与 JVM 参数、与 SDK 版本无耦合？

---

6. Native 边界

• 产出物：各平台 .so / .dylib / .dll + 头文件。
• 与 Java 契约：NativeBridge 与 jni_bridge.cpp 必须 同版本发布。
• 平台服务：不链接本 native 库；仅 现场 AI/业务进程 链接。

---

7. 规划工程划分（推荐独立 Git 仓库）

下列目录在 **engineering/planned/** 中以 README 描述，默认新开仓库（名称可调整）：

规划 ID	建议仓库名	技术栈（与产品文档对齐）	与本工作区关系
license-webhook-ingress	craftlabs-license-webhook（示例）	Spring Boot 4.0.，仅 Ingress + 验签 + MQ	消费比特 Callback；不依赖 SDK native
delivery-platform-api	craftlabs-delivery-platform	Spring Boot 4.0.，领域 API、PostgreSQL 15、MyBatis-Plus	依赖 schemas 可通过 git submodule 或发布 schema 包
delivery-platform-ui	craftlabs-delivery-platform-ui	Vue 3 + Vite	调用 delivery-platform-api

可选 Monorepo：若公司策略要求单仓，可采用 Bazel / Gradle composite / 多根 pom 父子不包含 SDK 的目录隔离，例如：

mega-repo/
  craftlabs-authorization-sdk/   # 本仓库 subtree 或 submodule
  delivery-platform/
  license-webhook/

迁移成本高于 三仓 + 契约版本化；默认推荐三仓。

---

8. CI/CD 划分建议

组件	触发路径	产物
SDK Java	java/**	Maven deploy（私服/Central）
SDK Native	native/**	各 OS 工件 + 与 Java 同版本 tag
Schema	schemas/**	可与 SDK 同步发 minor；breaking 走 major
平台与 Webhook	独立仓库（或本仓 services/）	Fat JAR + 部署说明（systemd/脚本/docker run）；不强制 容器与 K8s，规模化后再考虑镜像与编排

---

9. 数据与配置契约

• 客户端：craftlabs-auth-config.schema.json + 环境 bitanswer.url 等（见 examples/config）。
• 平台：存储 SN、合同、Callback 等 —— 领域模型独立于 SDK；仅 映射表 与比特特征 ID 与 M6 文档一致。
• Webhook Payload：以比特官方规则文档为准；平台侧 反序列化 DTO 在 license-webhook 仓维护。

9.1 平台数据栈（架构锁定）

项	约定
数据库	PostgreSQL 15（生产、验收、联调基准版本；镜像 postgres:15）
ORM	MyBatis-Plus（Spring Boot 3 使用 mybatis-plus-spring-boot3-starter；升级 Spring Boot 4 时改用官方 mybatis-plus-spring-boot4-starter 并回归）
迁移	Flyway 或 Liquibase（后续迭代引入；与表结构变更门禁对齐）
单测	可不启真实 PG：H2 MODE=PostgreSQL 或 Testcontainers postgres:15，以团队门禁为准

实现参考：services/delivery-platform-api 已接入 MyBatis-Plus + JDBC；本地数据库见 services/docker-compose.yml。

---

10. 安全边界

展开：威胁面、分组件控制、信任边界图与评审清单见 SYSTEM_ARCHITECTURE.md §9。

10.1 密钥与凭据

• Webhook：x-bitanswer-token / 与比特约定的共享密钥 仅 在 部署机环境变量 或 权限受限的本地配置文件（如 chmod 600）；禁止 写入 Git、镜像层与公开 CI 日志。
• 平台数据库：JDBC URL、用户名、密码 仅 注入运行时；docker-compose 与示例 不得 作为生产凭据模板。
• 管理端：演示账号（如 dev/admin）禁止 用于生产；生产至少 强口令。团队尚小时 不强制 上云 KMS / Vault；规模与合规要求上来后再演进。
• SDK 发布防篡改：以 SYSTEM_ARCHITECTURE §9.8 为准（官方渠道、SHA-256、建议 GPG、同 tag 发布 JAR+Native）。

10.2 运行时与数据面

• 传输：对外 仅 HTTPS（Webhook、管理 API、浏览器）；比特 Callback 终端 不接明文 HTTP（除本机健康检查等受控例外）。
• SDK：配置 JSON 不落 平台库表作为默认设计；禁止 在 examples/ 与文档示例中放置真实 bitanswer.url 密钥或生产 SN。
• 服务端 classpath：禁止 craftlabs-auth-bitanswer 与 System.loadLibrary —— 避免将 客户端攻击面 引入机房。
• 日志与排障：Callback 正文、Authorization、数据库 URL 默认脱敏或不打；生产日志外送需合规评估。

10.3 授权与访问控制

• 管理 API：认证（谁） 与 鉴权（能否操作资源） 分层；与 M11 角色矩阵一致，防范 越权（IDOR）。
• Webhook：认证先于重逻辑；幂等 防重放污染；Body 大小限制 防 DoS。

10.4 供应链与构建

• Maven/npm 锁定版本；力所能及时做 依赖漏洞扫描（SCA）。
• SDK 对外发布：每个版本附带 SHA-256 清单，强烈建议 GPG 签名（maven-gpg-plugin 或 GitHub signed releases）；详见 SYSTEM_ARCHITECTURE §9.8。

---

11. 演进检查清单（架构评审用）

• 新代码是否落在正确 仓库/目录（SDK vs 平台 vs Webhook）？
• Schema 变更是否 双向 更新 Java AuthConfigs + 文档？
• Native 与 Java 是否同 tag 发布？
• 平台是否 误引 craftlabs-auth-bitanswer 到服务端 classpath？
• 平台构建是否 仅 bootstrap 模块 产出 Fat JAR，且无重复 repackage？
• 安全：Webhook 生产是否 启用 共享密钥/签名？Actuator 敏感端点是否 已收敛？新接口是否 默认拒否 并完成 鉴权？日志是否 无 明文 Token/Callback？
• 安全：SYSTEM_ARCHITECTURE §9.7 评审项是否逐项可追溯？
• SDK 发布：SYSTEM_ARCHITECTURE §9.8 是否落实 官方渠道 + 校验和（+ 签名）+ JAR/Native 同 tag？

---

12. 修订记录

日期	说明
2026-04-06	初版：工作区走查、目录边界、规划仓库与 CI 划分；落地 engineering/ manifest 与 planned/* 占位。
2026-04-06	增补：§5 客户端 SDK vs 平台端 防混淆表；多模块开发 + 单 Fat JAR 的 Maven 模块划分与 repackage 约束；CI 坐标命名建议。
2026-04-06	关联：PARALLEL_ITERATION_INDEX.md 与 tracks/01–03 三轨并行执行包。
2026-04-06	§9.1 锁定平台 PostgreSQL 15 + MyBatis-Plus；services 工程对齐依赖与本地 docker-compose。
2026-04-06	新增汇总文档 SYSTEM_ARCHITECTURE.md（系统架构图 + 全量组件清单）。
2026-04-06	§10 安全边界扩写（密钥、传输、SDK、鉴权、供应链）；§11 增补安全评审项；与安全专章 SYSTEM_ARCHITECTURE §9 交叉引用。
2026-04-06	小团队假设：凭据以宿主机环境变量/受限文件为主，不强制 K8s/KMS；§10.1/10.4 与 §11 对齐 SDK §9.8 发布完整性。
2026-04-06	§8 CI/CD 表：平台产物以 Fat JAR + 部署说明 为主，不强制 K8s。