craftlabs-authorization-sdk/docs/engineering/iterations/I7_DESIGN.md

迭代 I7 架构设计 — 可靠投递、运营权限、前端指令

仓库：craftlabs-authorization-sdk（develop）。
前置：I6 收口、I6 实现审核 §3 跟踪项。
角色：迭代功能架构说明；实现以本文件为审查基线。

---

1. 目标与范围

主题	I7 要达成	非目标（后置）
Webhook → 平台	对比特 2xx 后立即返回；平台投递 异步、可重试、落库可观测（状态/次数/最后错误）	MQ、跨地域多活
运营权限	新增 **OPS；Callback Inbox（读/改/挂接）仅 **OPS + SYS_ADMIN；**DEVELOPER** 保留其余业务与 M6 只读	细粒度按钮与数据范围（I8+）
前端	路由 meta.roles 与菜单 **hasAnyRole** 一致；登录页说明 **ops/ops**	Playwright 流水线（I7.1 可选）

---

2. Webhook 侧：平台投递出站队列

2.1 行为

1. **webhook_callback_receipt 首次插入成功** 且配置了 craftlabs.platform.internal.base-url + token 时，写入 **webhook_platform_delivery**，status=PENDING。
2. 不在 Callback HTTP 线程内同步 RestClient 调用平台（避免比特侧拖慢与线程占用）。
3. **@Scheduled** 周期拉取 PENDING / 可重试失败行，POST /internal/v1/callback-events；成功 → SENT；失败 → attempts++，指数退避 **next_retry_at**，超过 **max-attempts** → DEAD（人工/运维处理）。
4. 未配置 base-url 时：不建队列行（与 I5「仅收据」行为一致）。

2.2 表（Flyway V2__webhook_platform_delivery.sql）

列	说明
receipt_id	关联收据
request_body	平台 API JSON 正文
trace_headers_json	traceparent / X-Request-Id 等 JSON
idempotency_key	头 Idempotency-Key 用值
status	PENDING / SENT / DEAD
attempts, last_error, next_retry_at	重试与排障

2.3 配置（示例）

Key	说明
craftlabs.platform.delivery.scheduler-enabled	单测可 false
craftlabs.platform.delivery.max-attempts	默认 8
craftlabs.platform.delivery.batch-size	每.tick 处理条数

---

3. 平台 API：角色与方法安全

3.1 角色

角色	用途
SYS_ADMIN	全量（含 Callback）
OPS	仅 Callback Inbox + 与运营配套能力；不开放合同/交付等业务写路径（由路由与菜单裁剪）
DEVELOPER	业务+M6 只读；不含 Inbox

3.2 安全模型

• **@EnableMethodSecurity** + **@PreAuthorize** 扛后端契约。
• **CallbackInboxController**：hasAnyRole('OPS','SYS_ADMIN')。
• **IntegrationCatalogController**：hasAnyRole('OPS','SYS_ADMIN','DEVELOPER')。
• JWT 仍由 [JwtAuthenticationFilter](../../../services/delivery-platform-api/src/main/java/cn/craftlabs/platform/api/security/JwtAuthenticationFilter.java) 注入 ROLE_*。

3.3 演示账号

用户	密码	角色
admin	admin	SYS_ADMIN
dev	dev	DEVELOPER
ops	ops	OPS

---

4. 前端（delivery-platform-ui）

4.1 路由 meta.roles

区域	meta.roles
首页及以下业务（客户/项目/合同/交付/SN）	SYS_ADMIN, DEVELOPER
/callbacks, /callbacks/:id	SYS_ADMIN, OPS
/integration/*	SYS_ADMIN, DEVELOPER, OPS

4.2 菜单与首页

• Pinia hasAnyRole(roles)，MainLayout / HomeView 按角色显示入口，避免 OPS 误以为可点业务页。

---

5. 测试与 DoD

项	标准
平台	CallbackInboxControllerTest：DEVELOPER 访问 Inbox → 403；SYS_ADMIN/OPS 仍可走通
Webhook	配置 base-url 时 enqueue 产生 PENDING 行；单测关闭 scheduler 避免后台线程
前端	npm run build 通过

---

6. 修订记录

日期	说明
2026-04-06	I7 初版：异步投递表 + OPS + 前端路由/菜单。
2026-04-06	闭环：实现与 I7_IMPLEMENTATION_REVIEW.md 复盘。