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(engineering): I8/I9 iteration artifacts and frontend UI specification

Browse Source 
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
This commit is contained in:
huangping
2026-04-07 21:26:51 +08:00
parent d53ddf32c8
commit 650c1caffa
7 changed files with 589 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/engineering/PARALLEL_ITERATION_INDEX.md
+41 -27
View File
@@ -9,11 +9,13 @@
## 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) |
| 轨道 | 仓库/工作区 | 执行包文档 |
| -------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **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) |
---
@@ -21,32 +23,38 @@
三轨 **共用** 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)。
| 迭代 | 后端（双 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)。
| 周次/迭代 | 同步内容 | 参与方 |
| -------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| **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)`。
---
@@ -74,10 +82,16 @@ flowchart LR
JAR --> NAT
```
---
## 5. 修订记录
| 日期 | 说明 |
|------|------|
| 2026-04-06 | 初版：三轨并行索引 + 同步点 + Gantt 示意。 |
| 日期 | 说明 |
| ---------- | ----------------------------------------- |
| 2026-04-06 | 初版：三轨并行索引 + 同步点 + Gantt 示意。 |
| 2026-04-07 | 增加 **I9**：Webhook 出库状态只读（Callback 详情可观测）。 |