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

docs/engineering/tracks/01-backend-platform-webhook.md

@@ -0,0 +1,132 @@
+# 轨道 A：平台 API + License Webhook 后端 — 并行实施包
+
+> **对齐**：[BPM 排期 §7](../chuangfei-platform-bpm-and-roadmap.md) · [工程布局 §5](../WORKSPACE_ENGINEERING_LAYOUT.md) · [集成平台 §8](../../chuangfei-bitanswer-integration-platform.md)  
+> **约束**：Spring Boot **4.0.x**；Maven **多模块**；**仅 `*-bootstrap`** `repackage` → **各一枚 Fat JAR**；服务端 **禁止** `craftlabs-auth-bitanswer`；数据层 **PostgreSQL 15** + **MyBatis-Plus**（见 [WORKSPACE_ENGINEERING_LAYOUT.md §9.1](../WORKSPACE_ENGINEERING_LAYOUT.md)）。
+
+---
+
+## 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 对齐。 |

docs/engineering/tracks/02-frontend-platform-ui.md

@@ -0,0 +1,85 @@
+# 轨道 B：delivery-platform-ui（Vue 3）— 并行实施包
+
+> **对齐**：[BPM 排期 §7](../chuangfei-platform-bpm-and-roadmap.md) · [功能模块 M1–M11](../../chuangfei-platform-product-modules.md) · [并行索引](../PARALLEL_ITERATION_INDEX.md)
+
+---
+
+## 1. 技术基线
+
+| 项 | 选型 |
+|----|------|
+| 运行时 | **Vue 3** + **Vite**，Composition API + `<script setup>` |
+| 状态 | **Pinia** |
+| 路由 | **vue-router**（懒加载、meta：权限码、`title`） |
+| HTTP | **axios**（拦截器：JWT Bearer 或 Session Cookie） |
+| UI | **Element Plus** |
+| 契约（可选） | OpenAPI → TS 类型，与后端 **contract-first** |
+
+认证：环境切换 `withCredentials` 与 `Authorization`；登录后写入 Pinia。
+
+---
+
+## 2. I1～I6 前端 Backlog
+
+| 迭代 | 路由/页面 | 关键组件 | API/状态 | E2E | DoD |
+|------|-----------|----------|----------|-----|-----|
+| **I1** | `/login`、`/` 布局、`/403`/`/404` | `AppLayout`、`LoginForm`、`IdleTimeout` | auth/user store；401 统一处理 | P0 登录与回跳 | RBAC 路由守卫；菜单按权限过滤 |
+| **I2** | `/customers`、`/projects` 及详情；`/admin/dictionaries` | `DataTable`、`CustomerForm`、`ProjectForm` | CRUD + 字典缓存 | P0 客户→项目 | 与 M1 P0 字段一致 |
+| **I3** | `/contracts`、新建向导、`/contracts/:id` | `ContractWizard`、`ContractLineEditor`、`StatusTag` | 状态机由后端校验，前端禁用非法操作 | P0 草稿→生效 | M2 P0；M10-F01 入口 |
+| **I4** | `/deliveries`、`/licenses/sn`、导入 | `DeliveryBatchForm`、`SnBindDialog`、`SnStatusTimeline` | 交付与合同行；孤儿 SN 警告 | P0 交付→SN→回写 | M3/M4 P0 |
+| **I5** | `/callbacks`、`/integration/environments`、`product-lines` | `CallbackInboxTable`、`CallbackPayloadViewer`（脱敏） | Inbox 处置；M6 只读/受限写 | P0 列表→详情→状态 | 与 Webhook 联调或 staging |
+| **I6** | 全链路导航与修缺陷 | 可选 `GlobalSearch` | 错误与空态统一 | P0 **BP-01～06+11** 全链路 E2E | UAT 无 P0；手册截图一致 |
+
+---
+
+## 3. 页面 ↔ 模块（摘要）
+
+| 模块 | 典型路由 | MVP 迭代 |
+|------|----------|----------|
+| M11 | 登录、用户/角色（I2）、Mid SSO | I1、Mid |
+| M1 | 客户、项目 | I2 |
+| M2 | 合同 | I3 |
+| M3/M4 | 交付、SN | I4 |
+| M5/M6 | Callback、集成配置 | I5 |
+| M7～M9 | 设备、待办、报表 | Mid |
+| M10 | 审计展示/导出 | I3+ / Mid / V2 |
+
+---
+
+## 4. Mock 与契约先行
+
+| 工作包 | 可先 mock？ | 建议 |
+|--------|-------------|------|
+| I1 壳层 + RBAC | ✅ | MSW / vite-plugin-mock |
+| M1 CRUD | ✅ | I3 前客户/项目 DTO 冻结 |
+| M2 合同 | ⚠️ | 状态迁移 **OpenAPI 冻结**（I2 末） |
+| M3/M4 | ⚠️ | 门禁与 M11-F20 契约先行 |
+| M5/M6 | ⚠️ | Payload 以 Webhook/API DTO 为准 |
+
+**契约顺序**：Auth → Customer/Project → Contract → Delivery/SN → Callback/Integration。
+
+---
+
+## 5. V1.1 / Mid / V2.0（摘要）
+
+- **I7～I8**：按钮级 `v-permission`；导出脱敏；运维只读仪表盘；批量导入进度。
+- **Mid I9～I13**：设备/换机；待办与通知配置；对账与 Callback 报表；**SSO**（`/oauth/callback` 等）；合同变更对比可选。
+- **V2.0**：M10 导出包、MFA、SECURITY_ADMIN、数据范围、CRM 同步状态页。
+
+---
+
+## 6. E2E 建议
+
+| 层级 | 工具向 |
+|------|--------|
+| Smoke | Playwright / Cypress：登录 + 各迭代主路由 |
+| P0 业务 | I6 全链路 + V1.1 导入导出 |
+| Mid | SSO、待办、报表（staging IdP 或 mock OIDC） |
+
+---
+
+## 7. 修订记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-04-06 | 由并行 Task 产出并入库。 |

docs/engineering/tracks/03-client-sdk.md

@@ -0,0 +1,92 @@
+# 轨道 C：craftlabs-authorization-sdk（客户端）— 并行实施包
+
+> **对齐**：[BPM §7 BP-10](../chuangfei-platform-bpm-and-roadmap.md) · [工程布局 §5](../WORKSPACE_ENGINEERING_LAYOUT.md)  
+> **事实**：`craftlabs-auth-core` / `bitanswer` / `selfhosted`；`schemas/`；`examples/`；平台 **不嵌入** Native。
+
+---
+
+## 1. SDK 版本线与 Native 标签
+
+
+| 原则            | 说明                                                               |
+| ------------- | ---------------------------------------------------------------- |
+| **独立 SemVer** | SDK **不与**平台 Fat JAR 版本号绑定；对外话术分两条线。                             |
+| **MAJOR**     | Schema 不兼容、公共 API 破坏、JNI 契约不兼容。                                  |
+| **MINOR**     | 向后兼容扩展：可选 Schema 字段、新 API、新示例。                                   |
+| **PATCH**     | Bugfix、文档；无契约变化。                                                 |
+| **预发布**       | `-rc.N` 与平台 UAT/比特联调对齐；**不用**平台版本代替 SDK 版本。                      |
+| **Native**    | 每次发行 **JAR + 各 OS native** 同版本；Git **单 tag**（如 `v1.4.2`）；禁止只升其一。 |
+
+
+---
+
+## 2. 平台迭代 × SDK 工作对照
+
+
+| 迭代     | 平台焦点                | SDK **必需**                                 | SDK **非阻塞**            |
+| ------ | ------------------- | ------------------------------------------ | ---------------------- |
+| **I1** | M11 脚手架             | 无                                          | 文档：与平台产物区分             |
+| **I2** | M1                  | 无                                          | 文档                     |
+| **I3** | M2、M10-F01          | 无                                          | 文档                     |
+| **I4** | M3、M4、激活回写          | 烟测路径下 **推荐 PATCH** 修缺陷                     | 文档/示例与 BP-10 口径        |
+| **I5** | M5、M6、Webhook、BP-10 | **Schema + `AuthConfigs` + examples 同步**   | Native 与 Webhook 无关    |
+| **I6** | UAT                 | **冻结 SDK 版本**、CHANGELOG、**BitAnswer 兼容矩阵** | 禁止 UAT 周做 MAJOR Schema |
+
+
+**小结**：I1～I4 以文档/示例为主；**I5 起** Schema/Java/示例为硬交付；**I6** 冻结与清单。
+
+---
+
+## 3. BP-10：何时 bump Schema / Java / 文档 / 示例
+
+
+| 变更类型                | Schema              | Java AuthConfigs | docs | examples |
+| ------------------- | ------------------- | ---------------- | ---- | -------- |
+| 新增可选字段              | MINOR（或 PATCH）      | 同交付对齐            | 字段说明 | 可选示例     |
+| 新增必填/收紧/改名          | MAJOR 或 breaking 策略 | 必须同步             | 迁移说明 | 必须更新模板   |
+| 仅 description       | PATCH               | 通常无              | 可选   | 可选       |
+| M6 仅改发布流程、JSON 形态不变 | 无                   | 无                | 手册可选 | 无        |
+
+
+**硬规则**：影响「平台导出 → Schema → 客户端」任一环的变更，**同一发布列车** 更新 Schema + Java（若有）+ 示例。
+
+---
+
+## 4. SDK 发布检查清单（非平台 Fat JAR）
+
+1. `mvn -f java/pom.xml clean verify`；Native 各 OS 构建通过。
+2. `mvn deploy`：`craftlabs-auth-*` **版本一致**；**无** `spring-boot-maven-plugin` repackage。
+3. Native 与 JAR **同版本** 发布。
+4. Schema + examples CI 校验。
+5. CHANGELOG：破坏性变更、BitAnswer 版本区间、已知平台导出版本（若可公开）。
+6. **兼容矩阵**：SDK 版本、厂商库、OS/JDK；与平台应用版本 **分列**。
+7. Git tag；**不含** `java -jar platform.jar` 说明。
+
+---
+
+## 5. V1.1+ SDK 增强（规划）
+
+
+| 主题                    | 说明                                       |
+| --------------------- | ---------------------------------------- |
+| 更严校验                  | CI 对 examples 与 Schema 双向校验；平台脱敏 fixture |
+| Fixtures              | 最小/完整/非法 JSON 绑定 Schema 版本               |
+| 可选 `config-model` 薄模块 | 供平台后端复用 POJO **无 native**；另案评审           |
+
+
+---
+
+## 6. 防混淆话术
+
+**SDK** = `craftlabs-auth-*` **库** + **Native** + Schema/示例；**平台** = 独立仓 **bootstrap Fat JAR**，无 BitAnswer Native，**版本号线独立**。并行以 **I5（BP-10）** 为契约首要对齐点，**I6** 为 SDK 冻结点。
+
+---
+
+## 7. 修订记录
+
+
+| 日期         | 说明              |
+| ---------- | --------------- |
+| 2026-04-06 | 由并行 Task 产出并入库。 |
+
+