mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
docs(i1): engineering index, parallel tracks, and product context
Add PARALLEL_ITERATION_INDEX, workspace layout, system architecture, three-track execution packs, BPM/product references, and planned service manifests. Supports I1 alignment across backend, web, and SDK. Made-with: Cursor
This commit is contained in:
@@ -0,0 +1,276 @@
|
||||
# 工作区工程划分与仓库边界 — 架构说明
|
||||
|
||||
> **角色**：资深架构师对工作区现有资产与 **创飞客户商务与交付管理平台** 相关文档的对照走查结论。
|
||||
> **范围**：本 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。 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user