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

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

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

---

## 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）

```mermaid
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](./SYSTEM_ARCHITECTURE.md)。

### 10.1 密钥与凭据

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

---

## 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](./SYSTEM_ARCHITECTURE.md) 评审项是否逐项可追溯？  
- **SDK 发布**：[SYSTEM_ARCHITECTURE §9.8](./SYSTEM_ARCHITECTURE.md) 是否落实 **官方渠道 + 校验和（+ 签名）+ 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](./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](./SYSTEM_ARCHITECTURE.md)（系统架构图 + 全量组件清单）。 |
| 2026-04-06 | **§10** 安全边界扩写（密钥、传输、SDK、鉴权、供应链）；**§11** 增补安全评审项；与安全专章 [SYSTEM_ARCHITECTURE §9](./SYSTEM_ARCHITECTURE.md) 交叉引用。 |
| 2026-04-06 | **小团队假设**：凭据以宿主机环境变量/受限文件为主，**不强制** K8s/KMS；**§10.1/10.4** 与 **§11** 对齐 **SDK §9.8** 发布完整性。 |
| 2026-04-06 | **§8** CI/CD 表：平台产物以 **Fat JAR + 部署说明** 为主，**不强制** K8s。 |