admin/craftlabs-authorization-sdk
1
0
Fork 0
mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-09 10:00:30 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(i1): engineering index, parallel tracks, and product context

Browse Source 
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:
huangping
2026-04-06 21:04:49 +08:00
parent 3894315759
commit 76ff98db87
19 changed files with 2878 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/engineering/PARALLEL_ITERATION_INDEX.md
+80
View File
@@ -0,0 +1,80 @@
# 平台前后端 × 客户端 SDK — 并行迭代执行索引
> **目的**：在 [BPM 与版本排期](../chuangfei-platform-bpm-and-roadmap.md) 的 **I1～I6 / V1.1 / Mid / V2.0** 框架下，**三条工程线并行**落地时的 **入口文档、同步点与职责**。
> **基准**：与 [WORKSPACE_ENGINEERING_LAYOUT.md](./WORKSPACE_ENGINEERING_LAYOUT.md)（Fat JAR、禁止服务端 `craftlabs-auth-bitanswer`）一致。
> **全景**：系统上下文、容器、组件与时序见 [SYSTEM_ARCHITECTURE.md](./SYSTEM_ARCHITECTURE.md)。
> **安全**：信任边界、威胁缓解与分组件控制见 [SYSTEM_ARCHITECTURE.md §9](./SYSTEM_ARCHITECTURE.md)。
---
## 1. 三条轨道与文档
| 轨道 | 仓库/工作区 | 执行包文档 |
|------|-------------|------------|
| **A. 平台后端** | `craftlabs-delivery-platform` + `craftlabs-license-webhook`（规划） | [tracks/01-backend-platform-webhook.md](./tracks/01-backend-platform-webhook.md) |
| **B. 平台前端** | `craftlabs-delivery-platform-ui`（规划） | [tracks/02-frontend-platform-ui.md](./tracks/02-frontend-platform-ui.md) |
| **C. 客户端 SDK** | 本工作区 `craftlabs-authorization-sdk` | [tracks/03-client-sdk.md](./tracks/03-client-sdk.md) |
---
## 2. 并行模型（同迭代日历）
三轨 **共用** Roadmap 的 **I1～I6**（各约 **2 周**），同一迭代内并行开工；**硬耦合**集中在 **I5（Callback + Schema）** 与 **I6（UAT）**。
| 迭代 | 后端（双 JAR） | 前端（Vue） | 客户端 SDK（本仓） |
|------|----------------|-------------|---------------------|
| I1 | 身份 + Webhook 脚手架 | 登录 + 布局壳 + RBAC 路由 | 文档/边界说明，无阻塞发布 |
| I2 | M1 主数据 + 字典 | 客户/项目页 | 同上 |
| I3 | M2 合同 + M10-F01 | 合同向导与行项 | 同上 |
| I4 | M3 交付 + M4 SN | 交付 + SN 页 | 文档与示例与 BP-10 口径一致 |
| I5 | M5 Inbox + M6 + Webhook 生产链 | Callback + 集成只读页 | **Schema + AuthConfigs + examples 对齐 BP-10** |
| I6 | 加固 + UAT | E2E + 缺陷 | **冻结 SDK 版本 + CHANGELOG + 兼容矩阵** |
---
## 3. 跨轨同步点（必须对齐）
| 周次/迭代 | 同步内容 | 参与方 |
|-----------|----------|--------|
| **I1 末** | 认证方式（JWT vs Session）、OpenAPI `auth` tag、错误码与 401 行为 | 后端 + 前端 |
| **I2 末** | 客户/项目 DTO 冻结；字典编码 | 后端 + 前端 |
| **I3 末** | 合同状态枚举与非法迁移码；M10-F01 字段 | 后端 + 前端 |
| **I4 末** | SN 绑定与「孤儿 SN」规则；交付门禁参数（M11-F20） | 后端 + 前端 + SDK（文档） |
| **I5 起** | Callback payload 与 inbox DTO；**Idempotency-Key**；Webhook→平台投递方式（HTTP/MQ） | 后端 Webhook + 后端平台 + 前端 + **SDK（Schema/示例）** |
| **I6** | UAT 场景、冻结 **SDK 版本**、两枚 Fat JAR 与前端 `VITE_API_BASE` | 全员 |
**契约 Owner（建议角色）**：架构或 Tech Lead 兼任；**OpenAPI 单一事实来源** 为本仓库 [`contracts/openapi/delivery-platform-api.json`](../../contracts/openapi/delivery-platform-api.json)（与运行时 `/v3/api-docs` 由 `OpenApiContractSnapshotTest` 对齐），说明见 [`contracts/README.md`](../../contracts/README.md)。
---
## 4. 依赖关系简图
```mermaid
flowchart LR
subgraph FE[前端 UI]
UI[Vue 3]
end
subgraph BE[平台 API]
API[platform-bootstrap.jar]
end
subgraph WH[Webhook]
WB[webhook-bootstrap.jar]
end
subgraph SDK[本仓库 SDK]
JAR[craftlabs-auth-*]
NAT[native]
end
UI --> API
WB -->|内部调用或 MQ| API
SDK -.->|不依赖平台运行时| API
JAR --> NAT
```
---
## 5. 修订记录
| 日期 | 说明 |
|------|------|
| 2026-04-06 | 初版：三轨并行索引 + 同步点 + Gantt 示意。 |
docs/engineering/SYSTEM_ARCHITECTURE.md
+562
View File
@@ -0,0 +1,562 @@
# 系统架构设计 — 全景图与组件清单
> **角色**：资深架构师视角的 **系统上下文、容器划分、逻辑组件、数据流与部署边界** 的单一汇总页。
> **读者**：研发、测试、运维、产品与集成方。
> **关联**：[工作区工程划分](./WORKSPACE_ENGINEERING_LAYOUT.md) · [并行迭代索引](./PARALLEL_ITERATION_INDEX.md) · [功能模块 M1–M11](../chuangfei-platform-product-modules.md) · [比特对接总览](../chuangfei-bitanswer-integration-platform.md) · [`engineering/workspace-manifest.json`](../../engineering/workspace-manifest.json)
> **安全专章**：本章 **§9**（含 **§9.0** 小团队阶段、**§9.8** SDK 发布完整性）；与工作区 [WORKSPACE §10 安全边界](./WORKSPACE_ENGINEERING_LAYOUT.md) 互补。
---
## 1. 架构目标与原则
| 原则 | 说明 |
|------|------|
| **边界清晰** | **客户端授权运行时**（SDK + Native + 现场进程）与 **商业交付平台**（Web + 双后端 + 数据持久化）在 **依赖、发布周期、classpath** 上严格分离。 |
| **契约先行** | 客户端配置以 **`schemas/craftlabs-auth-config.schema.json`** 为契约；Callback / OpenAPI 以 **文档与版本化契约** 对齐多轨迭代（见 [PARALLEL_ITERATION_INDEX](./PARALLEL_ITERATION_INDEX.md)）。 |
| **可运维** | 每个可独立扩缩的后端服务 **一枚 Fat JAR**（`spring-boot-maven-plugin` **repackage** 仅挂在启动模块）；密钥与连接串 **不进** SDK 与示例仓库。 |
| **数据栈锁定** | 平台持久化：**PostgreSQL 15** + **MyBatis-Plus**（详见 [WORKSPACE_ENGINEERING_LAYOUT §9.1](./WORKSPACE_ENGINEERING_LAYOUT.md)）。 |
| **安全默认** | **最小权限**、**纵深防御**、**可审计**；对外入口 **TLS**；敏感面（Webhook、管理 API、SN/许可数据）**单独威胁建模**与门禁。 |
| **阶段目标（创飞当前）** | **小团队**：优先 **功能与需求闭环**；并发与规模 **不高**。平台侧 **单/双 Fat JAR + 单机或少量 VM** 上 `java -jar` 即可；**不将 K8s、云 KMS、服务网格** 作为现阶段必选项，待业务量与合规要求上升再演进。 **安全重心** 放在 **已发布 SDK 的完整性**（不易被 **替换、假冒**），见 **§9.0 / §9.8**。 |
---
## 2. 系统上下文（C4 Level 1）
展示本体系与 **外部环境** 的关系：谁使用谁、谁回调谁。
```mermaid
flowchart TB
subgraph Actors["参与者"]
OPS[运维/管理员]
BIZ[商务/交付/License Ops]
DEV[客户侧研发]
end
subgraph CraftLabs["创飞侧系统（本方案范围）"]
UI[交付管理平台 Web UI]
API[交付平台 API]
WH[License Webhook Ingress]
DB[(PostgreSQL 15)]
end
subgraph ClientSite["客户现场 / 边缘环境"]
APP[客户业务应用]
SDK[CraftLabs 授权 SDK]
NAT[BitAnswer Native 库]
end
subgraph External["外部系统"]
BA[比特安索云 / 控制台]
end
OPS --> UI
BIZ --> UI
UI --> API
API --> DB
WH --> DB
WH -->|内部 HTTP / MQ 异步| API
BA -->|规则 Callback HTTPS POST| WH
SDK -->|Bit_Login / 许可 API| BA
APP --> SDK
SDK --> NAT
DEV -->|依赖 Maven 工件 + JSON 配置| SDK
DEV -.->|阅读 Schema/文档| CraftLabs
```
**读图要点**：
- **比特** 只与 **Webhook**（服务端入站）和 **SDK**（客户端出站授权）发生 **不同方向** 的交互；平台 UI **不** 替代 SDK 完成现场授权。
- **SDK 不依赖** 平台 API 运行时；二者仅通过 **契约（Schema、文档、可选 OpenAPI 导出配置）** 弱耦合。
---
## 3. 容器架构（C4 Level 2）
本工作区与规划仓库中的 **可构建、可部署或可分发单元**。
```mermaid
flowchart TB
subgraph Browser["用户浏览器"]
SPA[Vue 3 SPA<br/>delivery-platform-ui]
end
subgraph DMZ["接入层（可选 Gateway）"]
GW[API Gateway / 反向代理<br/>规划]
end
subgraph SimpleHost["机房或云主机（单机为主）"]
JAR_API[delivery-platform-api<br/>Fat JAR :8080]
JAR_WH[license-webhook-ingress<br/>Fat JAR :8081]
PG[(PostgreSQL 15)]
MQ[[消息队列<br/>可选·低并发可省]]
end
subgraph ArtifactRepo["制品与契约"]
MVN[Maven：cn.craftlabs / cn.craftlabs.platform]
SCH[JSON Schema + examples]
NATIVE[各 OS Native 动态库]
end
subgraph CI["持续集成"]
WF_SDK[ci-java.yml]
WF_PLAT[ci-platform.yml]
end
SPA -->|HTTPS /api| JAR_API
GW -.-> JAR_API
GW -.-> JAR_WH
JAR_API --> PG
JAR_WH --> PG
JAR_WH -.-> MQ
MQ -.-> JAR_API
MVN --> APPX[客户应用构建]
SCH --> APPX
NATIVE --> APPX
WF_SDK --> MVN
WF_PLAT --> JAR_API
WF_PLAT --> JAR_WH
WF_PLAT --> SPA
```
**阶段说明（创飞当前）**：并发不高时 **可不部署 MQ**（Webhook 直写库或由 API 轮询即可）；后端以 **一台或两台云主机** 各跑 `java -jar …` 为主，**无需 K8s**。
| 容器 | 技术 / 形态 | 默认端口或产出 | 职责摘要 |
|------|-------------|----------------|----------|
| **delivery-platform-ui** | Vue 3 + Vite + Pinia + Element Plus | 静态资源 / dev server | 管理端 SPA：登录、领域页面、调用平台 REST。 |
| **delivery-platform-api** | Spring Boot 3.4.x（目标 4.0.x）、Security、Actuator、MyBatis-Plus | **8080**、Fat JAR | 领域 API、认证、M1–M11 业务能力、读写字段库。 |
| **license-webhook-ingress** | Spring Boot、Actuator | **8081**、Fat JAR | 比特 Callback 入站、验签/Token、快速 2xx、异步投递（表/MQ）。 |
| **PostgreSQL** | 15.x | 5432 | 平台主库；与 SDK **无** 直连。 |
| **SDK Java 模块** | 多模块 Maven，**非** Spring Boot | 多枚 `craftlabs-auth-*.jar` | 配置模型、BitAnswer 桥接、自托管占位等。 |
| **Native** | CMake | `.so` / `.dylib` / `.dll` | 比特官方运行时绑定，随 SDK 版本发布。 |
| **schemas + examples** | JSON Schema、样例 JSON | 无进程 | 配置契约与集成样例。 |
---
## 4. 平台后端逻辑组件（领域视图）
与产品模块 **M1–M11** 对齐的 **逻辑分包**（实现可跨多 Maven 模块，但边界应一致）。
```mermaid
flowchart LR
subgraph API["delivery-platform-api（逻辑）"]
M11[identity / platform M11]
M1[customer-project M1]
M2[contract M2]
M3[delivery M3]
M4[licensing SN M4]
M5[inbox callback M5]
M6[integration mapping M6]
M7[device M7]
M8[notification M8]
M9[reporting M9]
M10[audit M10]
PERS[persistence MyBatis-Plus]
end
M11 --> M1
M1 --> M2
M2 --> M3
M2 --> M4
M3 --> M4
M6 --> M4
M5 --> M4
M4 --> M7
M5 --> M8
M4 --> M9
M1 & M2 & M3 & M4 & M5 --> M10
M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 & M9 & M10 & M11 --> PERS
```
**Webhook 侧（license-webhook-ingress）逻辑组件**（精简）：
| 组件 | 职责 |
|------|------|
| **Ingress Controller** | 接收 POST、限流与尺寸约束（规划加固）。 |
| **Token / 签名验证** | `x-bitanswer-token` 或约定头；与 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 等环境变量对齐。 |
| **幂等与投递** | `Idempotency-Key` 或 payload 内事件 ID；写入 **inbox** 或 **MQ**（I5+），由平台 API 消费。 |
| **观测** | Actuator、结构化日志、指标（与平台统一约定）。 |
---
## 5. 客户端 SDK 组件（本仓库 `java/` + `native/`）
```mermaid
flowchart TB
subgraph SDK["CraftLabs Authorization SDK"]
CORE[craftlabs-auth-core<br/>配置 / NativeBridge / 校验]
BIT[craftlabs-auth-bitanswer<br/>Provider + loadLibrary]
SH[craftlabs-auth-selfhosted<br/>占位实现]
TST[craftlabs-auth-tests]
end
SCH2[schemas + examples]
JNI[libcraftlabs_auth_bitanswer]
CORE --> BIT
CORE --> SH
BIT --> JNI
TST --> CORE
SCH2 -.-> CORE
```
**硬约束**：平台服务端 **禁止** 依赖 `craftlabs-auth-bitanswer` 与 **禁止** `System.loadLibrary("craftlabs_auth_bitanswer")`（见 [WORKSPACE §5](./WORKSPACE_ENGINEERING_LAYOUT.md)）。
---
## 6. 关键运行时序
### 6.1 比特 Callback → 平台
```mermaid
sequenceDiagram
participant BA as 比特安索云
participant WH as license-webhook-ingress
participant Store as PG / MQ
participant API as delivery-platform-api
participant UI as 管理端 UI
BA->>WH: POST /webhook/bitanswer/callback
WH->>WH: 校验 Token / 幂等键
WH->>Store: 持久化或入队（异步）
WH-->>BA: 2xx 快速响应
API->>Store: 拉取 / 消费事件
UI->>API: 查询 Inbox / 处置状态
```
### 6.2 管理员使用平台
```mermaid
sequenceDiagram
participant U as 用户
participant UI as delivery-platform-ui
participant API as delivery-platform-api
participant DB as PostgreSQL 15
U->>UI: 登录 / 操作业务页
UI->>API: REST（Session / JWT 由迭代约定）
API->>DB: MyBatis-Plus 读写
API-->>UI: DTO / 错误码
```
### 6.3 客户现场授权（与平台解耦）
```mermaid
sequenceDiagram
participant APP as 客户应用
participant SDK as craftlabs-auth-*
participant NAT as Native
participant BA as 比特安索云
APP->>SDK: 初始化 + 加载配置 JSON
SDK->>SDK: Schema/规则校验（可选）
SDK->>NAT: JNI 调用
NAT->>BA: 许可 / 登录协议
BA-->>NAT: 授权结果
NAT-->>SDK: 回调结果
SDK-->>APP: 授权状态 / 特征项
```
---
## 7. 全量组件清单（Master Inventory）
下表覆盖 **本工作区已实现或已占位** 的组件；规划项标注为 **（规划）**。
| ID | 组件名称 | 类型 | 路径 / 坐标 / 产物 | 技术栈 | 主要职责 |
|----|----------|------|-------------------|--------|----------|
| C01 | **craftlabs-auth-parent** | Maven 聚合 | `java/pom.xml` | Java 17 | SDK 父工程、依赖与模块编排。 |
| C02 | **craftlabs-auth-core** | Library JAR | `java/craftlabs-auth-core` | Java | 配置模型、`NativeBridge`、与 Schema 对齐的校验入口。 |
| C03 | **craftlabs-auth-bitanswer** | Library JAR | `java/craftlabs-auth-bitanswer` | Java + JNI | `BitAnswerProvider`、`System.loadLibrary`、**仅客户端**。 |
| C04 | **craftlabs-auth-selfhosted** | Library JAR | `java/craftlabs-auth-selfhosted` | Java | 自托管授权占位 / 扩展点。 |
| C05 | **craftlabs-auth-tests** | 测试模块 | `java/craftlabs-auth-tests` | JUnit 等 | SDK 侧集成与回归测试。 |
| C06 | **libcraftlabs_auth_bitanswer** | Native | `native/` | CMake | 各平台动态库，与 C02/C03 **同版本发布**。 |
| C07 | **craftlabs-auth-config Schema** | 契约 | `schemas/craftlabs-auth-config.schema.json` | JSON Schema Draft 2020-12 | 客户端配置 **单一契约**；CI 与 SDK 测试可对齐校验。 |
| C08 | **examples** | 样例 | `examples/` | JSON / 脚本 | 配置样例与烟测引用。 |
| C09 | **documentation** | 文档 | `docs/` | Markdown | 产品、对接、工程、架构。 |
| C10 | **engineering-meta** | 元数据 | `engineering/` | JSON / MD | `workspace-manifest.json`、planned 占位、README 索引。 |
| C11 | **craftlabs-platform-services-parent** | Maven 聚合 | `services/pom.xml` | Java 17 + Spring Boot 3.4.x | 平台后端父 POM；**与 C01 分构建线**。 |
| C12 | **delivery-platform-api** | 可执行 Fat JAR | `services/delivery-platform-api` | Spring Web/Security/Actuator、MyBatis-Plus、PostgreSQL 驱动 | 平台 REST、领域逻辑（迭代扩展）、**8080**。 |
| C13 | **license-webhook-ingress** | 可执行 Fat JAR | `services/license-webhook-ingress` | Spring Web/Actuator | Callback 入站、Token、**8081**。 |
| C14 | **PostgreSQL** | 基础设施 | 部署环境 / `services/docker-compose.yml` | 15.x | 平台主数据存储。 |
| C15 | **delivery-platform-ui** | SPA | `web/delivery-platform-ui` | Vue 3、Vite、Pinia、vue-router、axios、Element Plus | 管理端界面；dev 代理 `/api` → API。 |
| C16 | **CI：SDK Java** | 流水线 | `.github/workflows/ci-java.yml` | GitHub Actions | `java/` 构建与测试（JDK 版本以 workflow 为准）。 |
| C17 | **CI：Platform + Web** | 流水线 | `.github/workflows/ci-platform.yml` | GitHub Actions | `services/` Maven verify + `web/` npm build。 |
| C18 | **API Gateway** | 接入（规划） | 未在本仓 | 待定 | 统一 TLS、路由、限流（可选）。 |
| C19 | **Message Queue** | 中间件（规划） | 未在本仓 | 待定 | Webhook 与 API 解耦、削峰（I5+ 常见形态）。 |
| C20 | **企业 IdP** | 身份（规划） | 未在本仓 | OIDC/SAML 等 | 与 M11 企业登录集成（若需）。 |
| C21 | **密钥与凭据** | 运维配置 | 部署机 | **环境变量**、**chmod 600 配置文件** | 注入 Webhook Token、DB 密码；**禁止** 进 Git；**不强制** 云 KMS。 |
| C22 | **WAF / 边缘限流** | 安全（可选） | 边界 | 云 WAF 或 Nginx 限流模块 | 低并发阶段可省；对外暴露或合同要求时再上。 |
---
## 8. 技术栈总览
| 分层 | 选型 | 备注 |
|------|------|------|
| 管理端 | Vue 3、Vite、Pinia、vue-router、axios、Element Plus | 构建产物静态托管或 CDN。 |
| 平台 API | Spring Boot 3.4.x（路线图 4.0.x）、Spring Security、Actuator | Fat JAR 部署。 |
| Webhook | 同上（独立进程） | 与 API **进程隔离**，失败域分离。 |
| ORM | MyBatis-Plus（`mybatis-plus-spring-boot3-starter`） | Boot 4 时切换 `boot4-starter`。 |
| 数据库 | PostgreSQL 15 | 测试可用 H2 PG 模式或 Testcontainers。 |
| 客户端 SDK | Java 17、多模块薄 JAR | 不打 Spring Boot repackage。 |
| 客户端 Native | CMake、比特官方 API | 与 Java **同版本 tag**。 |
| 契约 | JSON Schema 2020-12 | `schemas/` 与 `examples/`。 |
---
## 9. 安全架构（授权与平台）
授权与许可数据直接影响 **商业履约与合规**，安全需求高于一般内部后台。本节给出 **信任边界、威胁面、控制措施与演进要求**，供架构评审与渗透测试对齐。
### 9.0 阶段与重心（广州创飞 · 小团队）
| 维度 | 当前立场 |
|------|----------|
| **部署** | **单 Fat JAR / 进程** 部署在云主机或内网服务器；PostgreSQL 可与应用 **同机或同 VPC 内另一台**；**不强制** 容器编排与云 KMS。 |
| **密钥** | Webhook Token、数据库密码等放在 **宿主机环境变量** 或 **权限受限的配置文件**（`chmod 600`、仅运行用户可读），**绝不** 提交 Git。 |
| **优先级** | 先保证 **功能与需求闭环**；平台侧 **基础 TLS + 认证 + 日志脱敏** 即可满足多数早期场景。 |
| **安全重心** | **对外发布的 SDK（JAR + Native）**：防范 **供应链篡改与假冒制品**；**破解/逆向** 的硬防线主要在 **比特安索 Native 与许可密码学**，Java 层需 **诚实评估**（见 **§9.8**）。 |
### 9.1 安全目标（CIA + 授权特有）
| 目标 | 含义 | 在本体系的落点 |
|------|------|----------------|
| **机密性** | 许可状态、SN、合同金额、Callback 原文、密钥不外泄 | TLS、日志脱敏、DB 访问控制、前端不持久化敏感令牌到不安全存储 |
| **完整性** | Callback 与台账不被篡改；配置与制品未被替换 | Webhook 验签/共享密钥、幂等键、审计日志（M10）、依赖与镜像签名（供应链） |
| **可用性** | 授权链路与管理端在约定 SLA 内可服务 | Webhook 快速 2xx + 异步处理；低并发阶段 **单机 + 健康检查** 即可，**不必** 预设 K8s 弹性扩容 |
| **不可否认性**（按需） | 关键操作可追溯 | 审计表、WORM 或日志外送（合规场景） |
### 9.2 信任边界
```mermaid
flowchart TB
subgraph Untrusted["不可信或半可信"]
Internet((Internet))
BA[比特云]
CustomerNet[客户现场网络]
Dev[集成方研发环境]
end
subgraph TrustHigh["高信任 — 创飞数据面"]
PG[(PostgreSQL)]
Secrets[(凭据：宿主机环境变量<br/>或受限配置文件)]
end
subgraph TrustMed["中信任 — 应用进程"]
API[delivery-platform-api]
WH[license-webhook-ingress]
end
subgraph TrustUser["用户终端"]
Browser[管理员浏览器]
ClientApp[客户业务进程 + SDK]
end
Internet -->|TLS 仅| WH
Internet -->|TLS 仅| API
Internet --> Browser
BA -->|HTTPS Callback| WH
CustomerNet --> ClientApp
Dev -.->|Maven/文档| ClientApp
Browser -->|HTTPS + 会话/JWT| API
ClientApp -->|TLS 至比特/自托管| BA
WH --> PG
API --> PG
API --> Secrets
WH --> Secrets
```
**边界规则**：
- **Webhook URL** 暴露在公网或 DMZ：视为 **持续被扫描**；必须 **TLS + 强认证 + 限流 + 最小响应体**。
- **管理端 API**：仅对 **已认证主体** 开放业务写能力；**禁止** 将平台账号用于客户现场 SDK。
- **SDK 配置 JSON**：含 `bitanswer.url`、`applicationData`、特征映射等，属 **客户环境机密**；**不得** 回传至创飞平台作为默认遥测（除非单独签署数据处理协议并做脱敏设计）。
### 9.3 威胁面与缓解（摘要）
| 威胁 | 示例 | 架构层缓解 |
|------|------|------------|
| **伪造 Callback** | 攻击者 POST 恶意 payload | **共享密钥**（如 `x-bitanswer-token` 与 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 常量时间比较）；**比特官方 IP/证书钉扎**（若文档支持）；**payload 大小与 JSON 深度限制** |
| **重放** | 重复投递同一事件污染台账 | **幂等键**（`Idempotency-Key` / 事件 ID）+ 唯一约束；重复返回成功语义 |
| **撞库 / 会话窃取** | 管理端弱口令、Token 泄露 | **密码策略 / MFA（规划）**、**HttpOnly + Secure Cookie** 或 **短期 JWT + 刷新**、**CORS 严格白名单** |
| **越权** | 用户访问他人合同或 SN | **RBAC（M11）**、**行级授权**（组织/客户维度）、API **资源级鉴权** |
| **注入** | SQL / 反序列化 | **参数化查询**（MyBatis `#{}`）、**禁用不安全的反序列化 gadget**、DTO 白名单 |
| **SSRF**（若存在出站拉取） | 服务端替用户请求内网 | **出站 URL 白名单**、**禁用 file://**、独立网络分区 |
| **供应链 / 假冒 SDK** | 第三方镜像站替换 JAR、客户误下「绿色版」 | **官方唯一分发渠道** + **GPG/SHA-256 校验**（§9.8）；Maven 依赖 **锁定版本**；CI **依赖漏洞扫描**（力所能及） |
| **日志泄露** | Callback 原文、Token 打日志 | **结构化日志字段脱敏**、**禁止 debug 打印完整 Authorization** |
### 9.4 分组件控制要求
#### 9.4.1 `license-webhook-ingress`
| 控制项 | 要求 |
|--------|------|
| 传输 | **仅 HTTPS**；HTTP 仅允许本机健康检查（若必须）且不得承载业务 |
| 认证 | 配置 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 时 **强制校验** `x-bitanswer-token`（或比特约定头）；生产 **禁止** 长期关闭校验 |
| 处理 | **先校验后解析大对象**；限制 body 大小；超时快速失败仍返回约定错误码（避免资源耗尽） |
| 观测 | 日志记录 **事件 ID、幂等键、结果码**；**不** 记录完整密钥与完整 payload（或脱敏后） |
| 网络 | 云厂商 **安全组** 仅开放 443/业务端口；数据库 **不对公网**；单机阶段 **本机回环或内网 IP** 连库即可 |
#### 9.4.2 `delivery-platform-api`
| 控制项 | 要求 |
|--------|------|
| 认证 | I1 演示账号 **不得用于生产**；生产至少 **强口令**；团队具备条件时再上 **MFA / 企业 IdP（C20）** |
| 授权 | 每个 mutating 接口 **显式角色/权限**；与 M11 角色矩阵一致 |
| 数据 | DB 账号 **最小权限**（读写分离账号可选）；连接串来自 **环境变量或宿主机配置**，禁止提交仓库 |
| Actuator | **生产关闭或仅本机访问** `env`、`heapdump`；`health` 可给 **本机监控脚本或 Nginx 探活** |
| CORS | **显式允许源**，禁用 `*` 携带凭证 |
#### 9.4.3 `delivery-platform-ui`
| 控制项 | 要求 |
|--------|------|
| 存储 | **不** 将 refresh token 写入 `localStorage`（优先 HttpOnly Cookie 或安全内存策略） |
| CSP | 生产启用 **Content-Security-Policy**，限制内联脚本与未知域 |
| 依赖 | `npm audit` 纳入 CI；锁定 lockfile |
#### 9.4.4 客户端 SDK 与 Native
| 控制项 | 要求 |
|--------|------|
| 配置 | `craftlabs-auth-config` 由 **宿主应用** 安全加载（文件权限、必要时磁盘加密）；**禁止** 将含敏感字段的示例提交到客户代码库模板 |
| 完整性 | Native **与 JAR 同版本** 分发；**正式发布** 必须带 **校验与/或签名**（见 **§9.8**） |
| 运行时 | **不信任** 客户进程内存防护；敏感字符串尽量 **缩短生命周期**（比特 SDK 能力范围内） |
#### 9.4.5 PostgreSQL
| 控制项 | 要求 |
|--------|------|
| 网络 | DB **不暴露公网**；仅应用子网可达 |
| 加密 | 云盘默认加密或宿主机全盘加密即可；敏感列 **应用层加密** 为可选增强 |
| 审计 | 高危 DML/DDL 与 **管理员账号** 变更记入 M10 或 DB 审计扩展 |
### 9.5 与时序对齐的安全步骤（示意）
**Callback（补充安全步骤）**：
```mermaid
sequenceDiagram
participant BA as 比特安索云
participant WH as Webhook
participant Store as PG/MQ
BA->>WH: TLS + POST
WH->>WH: TLS 终结校验（mTLS 仅在高合规客户场景考虑）
WH->>WH: 校验 Token（常量时间）
WH->>WH: 限制 body 大小 + 解析
WH->>WH: 幂等键去重
WH->>Store: 写入 inbox（脱敏日志）
WH-->>BA: 2xx
```
**管理端（补充安全步骤）**：
```mermaid
sequenceDiagram
participant U as 用户
participant UI as SPA
participant API as Platform API
U->>UI: 登录
UI->>API: HTTPS + CSRF 防护（Cookie 模式）
API->>API: 认证 + 颁发会话/JWT
UI->>API: 业务请求 + 凭证
API->>API: 鉴权（角色 + 资源）
API-->>UI: 最小必要 DTO
```
### 9.6 合规与审计衔接
- **M10 审计与合规**：登录、合同变更、SN 绑定/解绑、Callback 处置、权限变更等 **必须** 产生不可抵赖审计记录（谁、何时、对象 ID、前后摘要）。
- **数据出境**：若 Callback 或日志含个人信息，需对齐 **个人信息保护法** 与客户 DPA。
- **渗透测试**：有对外暴露或合同要求时，对 **Webhook** 与 **管理 API** 做专项测试（认证绕过、IDOR、批量枚举）；小团队可 **采购外包渗透** 或分阶段补做。
### 9.7 架构评审安全清单（节选）
- [ ] Webhook 生产环境 **已启用** 共享密钥或更强机制（签名/HMAC 以比特文档为准）。
- [ ] 管理 API **无** 默认弱口令路径；Actuator 敏感端点 **已收敛**。
- [ ] 平台与 Webhook **未引入** `craftlabs-auth-bitanswer`。
- [ ] 日志与异常栈 **无** 明文数据库密码、Token、完整 Callback。
- [ ] OpenAPI 中 **错误码** 不泄露内部堆栈或枚举用户存在性（登录接口需谨慎）。
- [ ] `examples/config/*.json` **无** 真实生产 URL/密钥（仅占位）。
- [ ] **SDK 发布**：每个对外版本具备 **SHA-256 清单**；**强烈建议** GPG 签名与 **唯一官方下载说明**。
- [ ] **SDK 发布**：`java` 与 `native` **同 tag**，CHANGELOG 与交付说明 **可追溯**。
### 9.8 SDK 发布完整性（当前安全重心）
客户侧 **Java 字节码可被反编译**，单靠混淆无法对抗动机足够的攻击者。**真正承担许可与密码学校验的**，应是 **比特安索 Native 与云端许可体系**。创飞 SDK 的安全目标应定位为：
1. **防篡改、防假冒**：客户拿到的是 **官方构建** 的 JAR/Native，未被中间人替换。
2. **防版本错配**：JAR 与 `.so/.dylib/.dll` **同一次发布**（同 Git tag / 同一 Release 页），避免「新 JAR + 旧库」导致异常或绕过路径。
3. **可追溯**：出问题能对照 **确切版本与校验和** 复现。
| 措施 | 说明 | 小团队可执行性 |
|------|------|------------------|
| **官方唯一渠道** | 仅通过 **公司控制的 Maven 私服 / GitHub Release / 合同交付包** 分发；**禁止** 引导客户从匿名网盘、论坛下载「整合包」。 | 必做 |
| **SHA-256 清单** | 每个 Release 发布 `SHA256SUMS`；仓库内 **`scripts/sdk-release-checksums.sh`** 已落地，说明见 **`java/RELEASING.md`**；客户用 `sha256sum -c` / `shasum -a 256 -c` 校验。 | 必做 |
| **GPG 签名** | Maven：**`mvn -f java/pom.xml -Prelease-sign verify`**（`maven-gpg-plugin`，各 JAR 旁生成 `.asc`）；清单文件：`SIGN=1` 跑上述脚本生成 `SHA256SUMS.asc`。公布 **公钥指纹** 固定页。 | 强烈建议 |
| **Git Tag = 发布单元** | `java/` 与 `native/` **同一 tag** 打发布；CHANGELOG 写清 **兼容的比特 SDK 版本**。 | 必做 |
| **依赖锁定** | 客户工程使用 **明确版本号** 或 BOM；避免「浮动版本」被投毒依赖间接替换。 | 建议 |
| **ProGuard 等混淆** | 仅增加逆向成本，**不能**替代 Native 侧安全；若上，只作 **非关键路径** 的辅助手段。 | 可选 |
| **法务条款** | 许可协议中约定 **禁止反编译、再分发**（民事约束，与技术防护互补）。 | 建议 |
**客户集成检查清单（可印在交付文档）**：
- [ ] JAR/Native 均来自 **创飞官方渠道**，并已核对 **SHA-256**（或验签）。
- [ ] 各工件版本号 **一致**，与发布说明中的 **比特依赖版本** 一致。
- [ ] 未混入第三方「破解补丁」或修改版 `libcraftlabs_auth_bitanswer`。
---
## 10. 部署与网络（简图）
```mermaid
flowchart TB
subgraph Public["公网 / 比特侧可达"]
BA[比特 Callback 出口 IP]
end
subgraph Perimeter["边界（常为一台 Nginx/Caddy）"]
LB[TLS 终结 + 反代]
end
subgraph AppTier["应用层（单机或双机 java -jar）"]
WH_P[Webhook Fat JAR]
API_P[Platform API Fat JAR]
UI_S[静态 UI 或同机 Nginx 托管]
end
subgraph DataTier["数据层"]
PG_P[PostgreSQL 15<br/>单实例或云托管]
end
BA --> LB --> WH_P
Users((管理员浏览器)) --> LB --> UI_S
Users --> LB --> API_P
WH_P --> PG_P
API_P --> PG_P
```
**阶段注记（创飞当前）**：**不依赖 K8s**；扩容以 **加机器 + 多实例反代** 即可。**安全注记**：云安全组 **收紧**；PG **仅内网**；WAF/mTLS **按合同与预算** 选装，非 MVP 必选。
---
## 11. 修订记录
| 日期 | 说明 |
|------|------|
| 2026-04-06 | 初版：系统上下文、容器、领域与 SDK 组件图、时序、全量组件表、技术栈与部署简图。 |
| 2026-04-06 | **§9 安全架构**：信任边界、威胁与缓解、分组件控制、安全时序、合规与评审清单；原则表增加 **安全默认**；部署节增加安全注记。 |
| 2026-04-06 | **对齐小团队**：§1 **阶段目标**、§3 单机部署说明、§9.0、凭据改为宿主机配置、部署图改为 `java -jar` + Nginx；新增 **§9.8 SDK 发布完整性**（防篡改/假冒重心）。 |
---
**下一步**：领域表结构、OpenAPI 与事件 Schema 建议单独维护为 **版本化契约仓库** 或 `contracts/` 子模块，并在 [PARALLEL_ITERATION_INDEX](./PARALLEL_ITERATION_INDEX.md) 的同步点更新版本号。
docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md
+276
View File
@@ -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。 |
docs/engineering/tracks/01-backend-platform-webhook.md
+132
View File
@@ -0,0 +1,132 @@
# 轨道 A：平台 API + License Webhook 后端 — 并行实施包
> **对齐**：[BPM 排期 §7](../chuangfei-platform-bpm-and-roadmap.md) · [工程布局 §5](../WORKSPACE_ENGINEERING_LAYOUT.md) · [集成平台 §8](../../chuangfei-bitanswer-integration-platform.md)
> **约束**：Spring Boot **4.0.x**；Maven **多模块**；**仅 `*-bootstrap`** `repackage` → **各一枚 Fat JAR**；服务端 **禁止** `craftlabs-auth-bitanswer`；数据层 **PostgreSQL 15** + **MyBatis-Plus**（见 [WORKSPACE_ENGINEERING_LAYOUT.md §9.1](../WORKSPACE_ENGINEERING_LAYOUT.md)）。
---
## 0. 并行执行总览
| 维度 | 说明 |
|------|------|
| **两条可部署线** | `delivery-platform-api` 与 `license-webhook` **同一日历迭代并行**，各产 **一枚 Fat JAR**。 |
| **对齐机制** | **契约 Owner**（事件 schema、`Idempotency-Key`、错误码）；共享 **OpenAPI / 事件 README**；**I5 起** 集成测试门禁。 |
| **I1～I4 Webhook** | 可先 **验签、幂等、观测、占位路由**；生产级持久化 + M5 台账对齐在 **I5**。 |
---
## 1. 仓库与模块骨架
### 1.1 双仓库（推荐）
| 仓库（示例名） | 产出 |
|----------------|------|
| `craftlabs-delivery-platform` | `platform-bootstrap-*.jar` |
| `craftlabs-license-webhook` | `webhook-bootstrap-*.jar` |
### 1.2 `delivery-platform` 模块示例
```
delivery-platform/
├── pom.xml
├── platform-domain/
├── platform-application/
├── platform-adapters-web/
├── platform-adapters-persistence/
└── platform-bootstrap/ # 唯一 main + repackage
```
包名建议：`cn.craftlabs.platform.{identity,customer,contract,delivery,licensing,audit,config,...}`。
### 1.3 `license-webhook` 模块示例
```
license-webhook/
├── pom.xml
├── webhook-domain/
├── webhook-application/
├── webhook-adapters-http/
├── webhook-adapters-integration/
└── webhook-bootstrap/
```
包名建议：`cn.craftlabs.webhook.*`。
---
## 2. 分迭代后端 Backlog（I1～I6）
| 迭代 | 平台：模块 | 平台：REST/领域 | 平台：DB | Webhook：范围 | 集成点 | DoD |
|------|------------|-----------------|----------|---------------|--------|-----|
| **I1** | domain/application/adapters-web/persistence/bootstrap | M11 登录/登出/会话、登录审计、粗 RBAC、OpenAPI 初版 | 用户、角色、会话、登录审计 | 脚手架、CI、`/health`、Callback 占位、`Idempotency-Key` 记录 | 无强依赖 | 平台 Fat JAR；`dependency:tree` 无 bitanswer；Webhook Fat JAR CI 绿 |
| **I2** | +M1 | 客户/项目 CRUD、字典、用户角色分配 API | 客户、项目、字典 | 验签配置、拒绝非法请求指标 | 字典编码与前端约定 | M1 API 与鉴权打通；验签可 curl 演示 |
| **I3** | 加重 persistence | M2 合同+行项、状态机；M10-F01 | 合同、行、变更日志 | 事件 DTO 规范化、与平台枚举对齐；可 Mock DB | 契约：合同/行 id 供 Callback 关联 | 状态机单测；事件 schema v0.1 归档 |
| **I4** | | M3 交付；M4 SN 录入/绑定/状态/手工回写 | 交付、SN、FK | 关联键策略、MQ producer 骨架可选 | 内部 API 或 MQ 方案 ADR | 交付+SN 主键链路可追溯 |
| **I5** | | M5 Inbox P0；M6 环境+产品线最小 | Inbox 唯一约束、M6 表 | 验签→幂等落库/入队→平台可见 | 比特 Dev 联调 | E2E：模拟 Callback → 平台 DB 一条 Inbox |
| **I6** | bootstrap 横切 | 加固、Runbook、UAT 缺陷 | 修复类迁移 | Ingress 加固、密钥轮换演练 | 全链路 BP-01～06、11 | UAT 签字；两 JAR 版本可追踪 |
### 并行分工小结
| 迭代 | 平台关键路径 | Webhook 关键路径 |
|------|--------------|------------------|
| I1～I2 | 身份 + 主数据 | Ingress + 验签 + 契约草稿 |
| I3～I4 | 合同/交付/SN + 审计 | 事件模型 + 投递骨架 |
| I5～I6 | Inbox + M6 | 真实链路 + 运维 |
---
## 3. Webhook ↔ 平台契约要点
- **版本**：`schemaVersion` 或 `X-Event-Schema-Version`。
- **幂等**：`Idempotency-Key` + 比特稳定 `message_id`；Inbox 表 `(source_system, external_message_id)` 唯一。
- **投递**：A) Webhook **HTTP** `POST /internal/v1/callback-events`；B) **MQ** + 平台消费者（MVP 需 I5 定案）。
- **响应**：对比特 **2xx** 须在持久化或可靠入队**之后**。
- **安全**：验签用平台侧实现；**禁止** JNI SDK。
- **观测**：`traceparent` / `X-Request-Id` 贯通。
---
## 4. 风险与对前端/SDK
| 风险 | 缓解 |
|------|------|
| 契约漂移 | I3 起 OpenAPI SSOT；fixture 入库 |
| 幂等与 UX | DB 唯一约束；前端按业务 id 去重 |
| I5 前 Webhook 空转 | I1～I4 以契约+假实现为主 |
| SDK 误用 POM | CI `dependency:tree` grep |
| 前端滞后 | I5 起 Postman/Scalar 先行验收 |
---
## 5. CI Jobs 建议
| Job | 步骤摘要 |
|-----|----------|
| `platform-build` | `mvn -pl platform-bootstrap -am verify`；可选禁止 `craftlabs-auth-bitanswer` |
| `webhook-build` | 同上 `webhook-bootstrap` |
| `platform-integration-test` | Testcontainers + Flyway；I5+ Mock Callback 全链路 |
| `cross-service-it`（I5+） | Compose：双 JAR + DB + MQ |
---
## 6. V1.1（I7～I8）
| 迭代 | 平台 | Webhook |
|------|------|---------|
| I7 | 按钮级权限码、导出脱敏、限流、安全头 | 速率限制、payload 上限 |
| I8 | 业务指标 RED、批量导入幂等 | Callback 失败率、DLQ 深度 |
---
## 7. Mid（I9～I13）与 V2.0
- **Mid**：M7 设备；M8 待办/通知；M9 报表；M11 SSO/并发/强制下线；M2 变更可选 I13。
- **V2.0**：M10 举证包；MFA、SECURITY_ADMIN、数据范围；CRM、读模型/CQRS 轻量。
---
## 8. 修订记录
| 日期 | 说明 |
|------|------|
| 2026-04-06 | 由并行 Task 产出并入库；与 Roadmap I1～I6 对齐。 |
docs/engineering/tracks/02-frontend-platform-ui.md
+85
View File
@@ -0,0 +1,85 @@
# 轨道 B：delivery-platform-ui（Vue 3）— 并行实施包
> **对齐**：[BPM 排期 §7](../chuangfei-platform-bpm-and-roadmap.md) · [功能模块 M1–M11](../../chuangfei-platform-product-modules.md) · [并行索引](../PARALLEL_ITERATION_INDEX.md)
---
## 1. 技术基线
| 项 | 选型 |
|----|------|
| 运行时 | **Vue 3** + **Vite**，Composition API + `<script setup>` |
| 状态 | **Pinia** |
| 路由 | **vue-router**（懒加载、meta：权限码、`title`） |
| HTTP | **axios**（拦截器：JWT Bearer 或 Session Cookie） |
| UI | **Element Plus** |
| 契约（可选） | OpenAPI → TS 类型，与后端 **contract-first** |
认证：环境切换 `withCredentials` 与 `Authorization`；登录后写入 Pinia。
---
## 2. I1～I6 前端 Backlog
| 迭代 | 路由/页面 | 关键组件 | API/状态 | E2E | DoD |
|------|-----------|----------|----------|-----|-----|
| **I1** | `/login`、`/` 布局、`/403`/`/404` | `AppLayout`、`LoginForm`、`IdleTimeout` | auth/user store；401 统一处理 | P0 登录与回跳 | RBAC 路由守卫；菜单按权限过滤 |
| **I2** | `/customers`、`/projects` 及详情；`/admin/dictionaries` | `DataTable`、`CustomerForm`、`ProjectForm` | CRUD + 字典缓存 | P0 客户→项目 | 与 M1 P0 字段一致 |
| **I3** | `/contracts`、新建向导、`/contracts/:id` | `ContractWizard`、`ContractLineEditor`、`StatusTag` | 状态机由后端校验，前端禁用非法操作 | P0 草稿→生效 | M2 P0；M10-F01 入口 |
| **I4** | `/deliveries`、`/licenses/sn`、导入 | `DeliveryBatchForm`、`SnBindDialog`、`SnStatusTimeline` | 交付与合同行；孤儿 SN 警告 | P0 交付→SN→回写 | M3/M4 P0 |
| **I5** | `/callbacks`、`/integration/environments`、`product-lines` | `CallbackInboxTable`、`CallbackPayloadViewer`（脱敏） | Inbox 处置；M6 只读/受限写 | P0 列表→详情→状态 | 与 Webhook 联调或 staging |
| **I6** | 全链路导航与修缺陷 | 可选 `GlobalSearch` | 错误与空态统一 | P0 **BP-01～06+11** 全链路 E2E | UAT 无 P0；手册截图一致 |
---
## 3. 页面 ↔ 模块（摘要）
| 模块 | 典型路由 | MVP 迭代 |
|------|----------|----------|
| M11 | 登录、用户/角色（I2）、Mid SSO | I1、Mid |
| M1 | 客户、项目 | I2 |
| M2 | 合同 | I3 |
| M3/M4 | 交付、SN | I4 |
| M5/M6 | Callback、集成配置 | I5 |
| M7～M9 | 设备、待办、报表 | Mid |
| M10 | 审计展示/导出 | I3+ / Mid / V2 |
---
## 4. Mock 与契约先行
| 工作包 | 可先 mock？ | 建议 |
|--------|-------------|------|
| I1 壳层 + RBAC | ✅ | MSW / vite-plugin-mock |
| M1 CRUD | ✅ | I3 前客户/项目 DTO 冻结 |
| M2 合同 | ⚠️ | 状态迁移 **OpenAPI 冻结**（I2 末） |
| M3/M4 | ⚠️ | 门禁与 M11-F20 契约先行 |
| M5/M6 | ⚠️ | Payload 以 Webhook/API DTO 为准 |
**契约顺序**：Auth → Customer/Project → Contract → Delivery/SN → Callback/Integration。
---
## 5. V1.1 / Mid / V2.0（摘要）
- **I7～I8**：按钮级 `v-permission`；导出脱敏；运维只读仪表盘；批量导入进度。
- **Mid I9～I13**：设备/换机；待办与通知配置；对账与 Callback 报表；**SSO**（`/oauth/callback` 等）；合同变更对比可选。
- **V2.0**：M10 导出包、MFA、SECURITY_ADMIN、数据范围、CRM 同步状态页。
---
## 6. E2E 建议
| 层级 | 工具向 |
|------|--------|
| Smoke | Playwright / Cypress：登录 + 各迭代主路由 |
| P0 业务 | I6 全链路 + V1.1 导入导出 |
| Mid | SSO、待办、报表（staging IdP 或 mock OIDC） |
---
## 7. 修订记录
| 日期 | 说明 |
|------|------|
| 2026-04-06 | 由并行 Task 产出并入库。 |
docs/engineering/tracks/03-client-sdk.md
+92
View File
@@ -0,0 +1,92 @@
# 轨道 C：craftlabs-authorization-sdk（客户端）— 并行实施包
> **对齐**：[BPM §7 BP-10](../chuangfei-platform-bpm-and-roadmap.md) · [工程布局 §5](../WORKSPACE_ENGINEERING_LAYOUT.md)
> **事实**：`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 产出并入库。 |