mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-10 02:20:28 +08:00

Files

T

huangping 650c1caffa docs(engineering): I8/I9 iteration artifacts and frontend UI specification

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

2026-04-07 21:26:51 +08:00

6.5 KiB

Raw Blame History

平台前后端 × 客户端 SDK — 并行迭代执行索引

目的：在 BPM 与版本排期的 I1～I6 / V1.1 / Mid / V2.0 框架下，三条工程线并行落地时的 入口文档、同步点与职责。
基准：与 WORKSPACE_ENGINEERING_LAYOUT.md（Fat JAR、禁止服务端 craftlabs-auth-bitanswer）一致。
全景：系统上下文、容器、组件与时序见 SYSTEM_ARCHITECTURE.md。
安全：信任边界、威胁缓解与分组件控制见 SYSTEM_ARCHITECTURE.md §9。

1. 三条轨道与文档

轨道	仓库/工作区	执行包文档
A. 平台后端	`craftlabs-delivery-platform` + `craftlabs-license-webhook`（规划）	tracks/01-backend-platform-webhook.md
B. 平台前端	`craftlabs-delivery-platform-ui`（规划）	tracks/02-frontend-platform-ui.md
C. 客户端 SDK	本工作区 `craftlabs-authorization-sdk`	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、I7_IMPLEMENTATION_REVIEW.md；I8：I8_WEBHOOK_DELIVERY_REPLAY_DESIGN.md、I8_IMPLEMENTATION_REVIEW.md；I9：I9_WEBHOOK_DELIVERY_VISIBILITY_DESIGN.md、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. 依赖关系简图

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 详情可观测）。

6.5 KiB Raw Blame History Unescape Escape