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

# 系统架构设计 — 全景图与组件清单

> **角色**：资深架构师视角的 **系统上下文、容器划分、逻辑组件、数据流与部署边界** 的单一汇总页。  
> **读者**：研发、测试、运维、产品与集成方。  
> **关联**：[工作区工程划分](./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) 的同步点更新版本号。