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

# 架构师审核：I1～I6 实现对照（本工作区 `develop`）

> **方法**：以 [并行索引](../PARALLEL_ITERATION_INDEX.md)、各迭代设计稿（如 [I5_I6_DESIGN.md](./I5_I6_DESIGN.md)）、三轨道文档（[01](../tracks/01-backend-platform-webhook.md) / [02](../tracks/02-frontend-platform-ui.md) / [03](../tracks/03-client-sdk.md)）为预期，对照仓库 **当前实现** 做收口审计。  
> **范围**：`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](./I6_CLOSEOUT.md) | 过程性文档；**不替代**自动化 E2E |
| Runbook：内部 Token、连通性、轮换 | [RUNBOOK.md §10](../../../services/RUNBOOK.md) | 无 |
| 安全响应头与依赖门禁 | `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 前跟踪项

1. **Webhook 投递**：评估异步队列或 Outbox，补 **DLQ 指标**（设计 A.5、M5-F08）。  
2. **内部认证**：mTLS 或请求签名；Token 多版本滚动。  
3. **Playwright/Cypress**：将 I6_CLOSEOUT §2 固化为流水线冒烟。  
4. **权限细化**：M5 运营接口由 SYS_ADMIN/DEVELOPER 收口为 Ops 角色（设计 A.3 已注明 I7+）。  

---

## 4. 修订记录

| 日期 | 说明 |
|------|------|
| 2026-04-06 | 初版：I6 架构师审核，对照 I5_I6_DESIGN 与三轨道文档。 |