mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-09 18:10:30 +08:00

Files

T

huangping 76ff98db87 docs(i1): engineering index, parallel tracks, and product context

Add PARALLEL_ITERATION_INDEX, workspace layout, system architecture,
three-track execution packs, BPM/product references, and planned
service manifests. Supports I1 alignment across backend, web, and SDK.

Made-with: Cursor

2026-04-06 21:04:49 +08:00

5.8 KiB

Raw Blame History

轨道 A：平台 API + License Webhook 后端 — 并行实施包

对齐：BPM 排期 §7 · 工程布局 §5 · 集成平台 §8
约束：Spring Boot 4.0.x；Maven 多模块；仅 *-bootstrap repackage → 各一枚 Fat JAR；服务端禁止 craftlabs-auth-bitanswer；数据层 PostgreSQL 15 + MyBatis-Plus（见 WORKSPACE_ENGINEERING_LAYOUT.md §9.1）。

0. 并行执行总览

维度	说明
两条可部署线	`delivery-platform-api` 与 `license-webhook` 同一日历迭代并行，各产一枚 Fat JAR。
对齐机制	契约 Owner（事件 schema、`Idempotency-Key`、错误码）；共享 OpenAPI / 事件 README；I5 起集成测试门禁。
I1～I4 Webhook	可先验签、幂等、观测、占位路由；生产级持久化 + M5 台账对齐在 I5。

1. 仓库与模块骨架

1.1 双仓库（推荐）

仓库（示例名）	产出
`craftlabs-delivery-platform`	`platform-bootstrap-*.jar`
`craftlabs-license-webhook`	`webhook-bootstrap-*.jar`

1.2 `delivery-platform` 模块示例

delivery-platform/
├── pom.xml
├── platform-domain/
├── platform-application/
├── platform-adapters-web/
├── platform-adapters-persistence/
└── platform-bootstrap/          # 唯一 main + repackage

包名建议：cn.craftlabs.platform.{identity,customer,contract,delivery,licensing,audit,config,...}。

1.3 `license-webhook` 模块示例

license-webhook/
├── pom.xml
├── webhook-domain/
├── webhook-application/
├── webhook-adapters-http/
├── webhook-adapters-integration/
└── webhook-bootstrap/

包名建议：cn.craftlabs.webhook.*。

2. 分迭代后端 Backlog（I1～I6）

迭代	平台：模块	平台：REST/领域	平台：DB	Webhook：范围	集成点	DoD
I1	domain/application/adapters-web/persistence/bootstrap	M11 登录/登出/会话、登录审计、粗 RBAC、OpenAPI 初版	用户、角色、会话、登录审计	脚手架、CI、`/health`、Callback 占位、`Idempotency-Key` 记录	无强依赖	平台 Fat JAR；`dependency:tree` 无 bitanswer；Webhook Fat JAR CI 绿
I2	+M1	客户/项目 CRUD、字典、用户角色分配 API	客户、项目、字典	验签配置、拒绝非法请求指标	字典编码与前端约定	M1 API 与鉴权打通；验签可 curl 演示
I3	加重 persistence	M2 合同+行项、状态机；M10-F01	合同、行、变更日志	事件 DTO 规范化、与平台枚举对齐；可 Mock DB	契约：合同/行 id 供 Callback 关联	状态机单测；事件 schema v0.1 归档
I4		M3 交付；M4 SN 录入/绑定/状态/手工回写	交付、SN、FK	关联键策略、MQ producer 骨架可选	内部 API 或 MQ 方案 ADR	交付+SN 主键链路可追溯
I5		M5 Inbox P0；M6 环境+产品线最小	Inbox 唯一约束、M6 表	验签→幂等落库/入队→平台可见	比特 Dev 联调	E2E：模拟 Callback → 平台 DB 一条 Inbox
I6	bootstrap 横切	加固、Runbook、UAT 缺陷	修复类迁移	Ingress 加固、密钥轮换演练	全链路 BP-01～06、11	UAT 签字；两 JAR 版本可追踪

并行分工小结

迭代	平台关键路径	Webhook 关键路径
I1～I2	身份 + 主数据	Ingress + 验签 + 契约草稿
I3～I4	合同/交付/SN + 审计	事件模型 + 投递骨架
I5～I6	Inbox + M6	真实链路 + 运维

3. Webhook ↔ 平台契约要点

版本：schemaVersion 或 X-Event-Schema-Version。
幂等：Idempotency-Key + 比特稳定 message_id；Inbox 表 (source_system, external_message_id) 唯一。
投递：A) Webhook HTTP POST /internal/v1/callback-events；B) MQ + 平台消费者（MVP 需 I5 定案）。
响应：对比特 2xx 须在持久化或可靠入队之后。
安全：验签用平台侧实现；禁止 JNI SDK。
观测：traceparent / X-Request-Id 贯通。

4. 风险与对前端/SDK

风险	缓解
契约漂移	I3 起 OpenAPI SSOT；fixture 入库
幂等与 UX	DB 唯一约束；前端按业务 id 去重
I5 前 Webhook 空转	I1～I4 以契约+假实现为主
SDK 误用 POM	CI `dependency:tree` grep
前端滞后	I5 起 Postman/Scalar 先行验收

5. CI Jobs 建议

Job	步骤摘要
`platform-build`	`mvn -pl platform-bootstrap -am verify`；可选禁止 `craftlabs-auth-bitanswer`
`webhook-build`	同上 `webhook-bootstrap`
`platform-integration-test`	Testcontainers + Flyway；I5+ Mock Callback 全链路
`cross-service-it`（I5+）	Compose：双 JAR + DB + MQ

6. V1.1（I7～I8）

迭代	平台	Webhook
I7	按钮级权限码、导出脱敏、限流、安全头	速率限制、payload 上限
I8	业务指标 RED、批量导入幂等	Callback 失败率、DLQ 深度

7. Mid（I9～I13）与 V2.0

Mid：M7 设备；M8 待办/通知；M9 报表；M11 SSO/并发/强制下线；M2 变更可选 I13。
V2.0：M10 举证包；MFA、SECURITY_ADMIN、数据范围；CRM、读模型/CQRS 轻量。

8. 修订记录

日期	说明
2026-04-06	由并行 Task 产出并入库；与 Roadmap I1～I6 对齐。

5.8 KiB Raw Blame History Unescape Escape