# 轨道 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 对齐。 |