mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 18:10:30 +08:00
huangping
650c1caffa
Add I8/I9 design and implementation review markdown, update parallel iteration index and I7 review cross-links, and add FRONTEND_UI_SPECIFICATION for design handoff (Figma Make). Made-with: Cursor
98 lines
6.5 KiB
Markdown
98 lines
6.5 KiB
Markdown
# 平台前后端 × 客户端 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 |
|
||
| I8 | `**DEAD` 出库重放**：Webhook 内部 API + 平台代理 + UI / Runbook | Callback 详情「重新入队」 | 不涉及 SDK Schema |
|
||
| I9 | **出库状态只读**：Webhook `GET by-receipt` + 平台代理 + 详情展示 | Callback 详情「出库状态」 | 不涉及 SDK Schema |
|
||
|
||
|
||
设计/复盘：[I7_DESIGN.md](./iterations/I7_DESIGN.md)、[I7_IMPLEMENTATION_REVIEW.md](./iterations/I7_IMPLEMENTATION_REVIEW.md)；I8：[I8_WEBHOOK_DELIVERY_REPLAY_DESIGN.md](./iterations/I8_WEBHOOK_DELIVERY_REPLAY_DESIGN.md)、[I8_IMPLEMENTATION_REVIEW.md](./iterations/I8_IMPLEMENTATION_REVIEW.md)；I9：[I9_WEBHOOK_DELIVERY_VISIBILITY_DESIGN.md](./iterations/I9_WEBHOOK_DELIVERY_VISIBILITY_DESIGN.md)、[I9_IMPLEMENTATION_REVIEW.md](./iterations/I9_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 示意。 |
|
||
| 2026-04-07 | 增加 **I9**：Webhook 出库状态只读（Callback 详情可观测）。 |
|
||
|
||
|