mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
huangping
5fe7181b35
- Architect: I7_DESIGN.md, I7_IMPLEMENTATION_REVIEW.md; parallel index + track B - Backend: @EnableMethodSecurity; OPS login; CallbackInbox PreAuthorize; IntegrationCatalog triple role - Webhook: V2 webhook_platform_delivery; planner + scheduler + single-shot forwarder; tests - Frontend: Pinia hasAnyRole; MainLayout/HomeView/router for OPS vs dev - Runbook §10.5 delivery config Made-with: Cursor
5.1 KiB
5.1 KiB
架构师审核：I1～I6 实现对照（本工作区 develop）
方法：以 并行索引、各迭代设计稿（如 I5_I6_DESIGN.md）、三轨道文档（01 / 02 / 03）为预期，对照仓库 当前实现 做收口审计。
范围：services/delivery-platform-api、services/license-webhook-ingress、web/delivery-platform-ui、contracts/openapi、schemas/及 CI/Enforcer 门禁；不评价未在本仓的独立 Fat JAR 发布物。
1. 总评
| 维度 | 结论 |
|---|---|
| 迭代完整性 | I1～I5 主路径已在前后端与 Webhook 贯通；I6 以 UAT 文档、Runbook、安全头、前端生产基址与导航 收口，符合 Part B「无大块新功能」原则。 |
| 契约 | 公开 API 以 contracts/openapi/delivery-platform-api.json 为 SSOT，OpenApiContractSnapshotTest 守门；/internal/** 排除默认 springdoc 分组，与设计一致。 |
| 风险 | 内部 Token 为 MVP 共享密钥；生产应规划 mTLS/签名（设计已提示）。Webhook 转发失败仅日志重试次数用尽，无持久化 DLQ，适合 I6 后需求排期。 |
2. 分项审核
2.1 I1 — 身份、JWT、壳层
| 预期 | 实现 | 偏差 |
|---|---|---|
| Bearer JWT、401 入口、路由 RBAC | JwtAuthenticationFilter、SecurityConfig JWT 链、router meta.roles |
无 |
| 登录与 ping | AuthController、/api/v1/ping、前端 LoginView |
无 |
2.2 I2 — M1 主数据
| 预期 | 实现 | 偏差 |
|---|---|---|
| 客户/项目 CRUD + 字典 | Controllers + CustomersView / ProjectsView |
无结构性偏差（字段级以 OpenAPI 为准） |
2.3 I3 — M2 合同 + M10-F01
| 预期 | 实现 | 偏差 |
|---|---|---|
| 合同与行项、状态机服务端校验 | Contract API + 前端向导/详情 | 历史曾出现前后端动词不一致，当前以 PATCH status 等与后端对齐（需在 UAT 再点检） |
| 审计 | AuditService、AuditEntityTypes / AuditActions |
已扩展 Callback 相关常量（I5） |
2.4 I4 — M3/M4 交付与 SN
| 预期 | 实现 | 偏差 |
|---|---|---|
| 交付批次、行、许可 SN | 对应 API + DeliveriesView / SN 向导与列表 |
与设计 P0 一致 |
2.5 I5 — M5 Inbox、M6 只读、Webhook 链
| 预期（见 I5_I6_DESIGN Part A） | 实现 | 偏差 / 备注 |
|---|---|---|
platform_callback_inbox + M6 表 + Flyway V5 |
已落地 | 无 |
公开 GET/PATCH callback-inbox、integration GET |
已落地 | 无 |
POST /internal/v1/callback-events + 内部 Token |
CallbackInternalController、InternalTokenAuthenticationFilter |
无 |
幂等 (sourceSystem, externalMessageId) + 重复返回 duplicate |
CallbackEventIngestService |
无 |
schemaVersion major 校验 |
SUPPORTED_SCHEMA_MAJOR = 1 |
与设计「拒绝无法识别的 major」一致 |
| Webhook：收据后转发、trace 头、有限重试 | PlatformCallbackForwarder |
MVP：同步线程内 3 次退避；与设计「异步重试」相比属简化，Runbook 已说明可配置性 |
前端 /callbacks、脱敏 |
redactPayload.js、Inbox 视图 |
建议 UAT 确认敏感字段字典与产品一致 |
| OpenAPI 仅公开路由 | 内部 @Hidden + paths-to-exclude |
无 |
2.6 I6 — UAT、冻结、加固
| 预期（Part B + I6_CLOSEOUT） | 实现 | 偏差 |
|---|---|---|
| UAT 检查表 | I6_CLOSEOUT.md | 过程性文档；不替代自动化 E2E |
| Runbook：内部 Token、连通性、轮换 | RUNBOOK.md §10 | 无 |
| 安全响应头与依赖门禁 | SecurityConfig.apiHeaders：X-Content-Type-Options、frame deny、Referrer-Policy；ci-security（Trivy + npm audit）与 Dependabot |
HSTS 依设计交由边缘层 |
前端生产 VITE_API_BASE |
main.js + README + CLOSEOUT §4 |
无 |
| 首页全链路导航 | HomeView 模块链接 |
满足轨道 B I6「全链路导航」最低要求 |
2.7 轨道 C（SDK / Schema）
| 预期 | 实现 | 偏差 |
|---|---|---|
| I5 硬交付 Schema/示例/AuthConfigs | 以本仓 schemas/、java/、CI 为准（参见轨道 C 文档） |
I6 冻结需在发布周由发布 Owner 执行 tag/CHANGELOG/矩阵，非本审计单次提交所能证明 |
3. 建议进入 I7 / V1.1 前跟踪项
- Webhook 投递：评估异步队列或 Outbox，补 DLQ 指标（设计 A.5、M5-F08）。
- 内部认证：mTLS 或请求签名；Token 多版本滚动。
- Playwright/Cypress：将 I6_CLOSEOUT §2 固化为流水线冒烟。
- 权限细化：M5 运营接口由 SYS_ADMIN/DEVELOPER 收口为 Ops 角色（设计 A.3 已注明 I7+）。
4. 修订记录
| 日期 | 说明 |
|---|---|
| 2026-04-06 | 初版：I6 架构师审核，对照 I5_I6_DESIGN 与三轨道文档。 |
| 2026-04-06 | I6 表：补充 CI 依赖/CVE 与 Dependabot。 |