# 平台前后端 × 客户端 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 + 兼容矩阵** |
| I7 | Webhook **异步投递** + **OPS** 运营权限（Callback） | 路由/菜单与 `@PreAuthorize` 对齐 | 若涉及 Schema 仍走轨道 C |

设计/复盘：[I7_DESIGN.md](./iterations/I7_DESIGN.md)、[I7_IMPLEMENTATION_REVIEW.md](./iterations/I7_IMPLEMENTATION_REVIEW.md)。

---

## 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 示意。 |