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-06-09 10:00:30 +08:00 · 2026-04-06 21:04:49 +08:00
parent 3894315759
commit 76ff98db87
19 changed files with 2878 additions and 0 deletions
@@ -0,0 +1,19 @@
+# 工程元数据（Engineering）
+
+本目录存放 **工作区边界说明** 与 **规划中的独立工程占位**，不引入额外构建步骤。
+
+
+| 文件/路径                                                | 说明                                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `[workspace-manifest.json](workspace-manifest.json)` | 机器可读：当前组件路径、建议独立仓库列表                                                                                         |
+| `[planned/](planned/)`                               | 规划工程 README 占位（Webhook、平台 API、平台 UI）                                                                         |
+| **系统架构全景（C4、时序、全量组件表、§9 安全架构）**               | `[../docs/engineering/SYSTEM_ARCHITECTURE.md](../docs/engineering/SYSTEM_ARCHITECTURE.md)` |
+| **OpenAPI 契约（SSOT）**                                  | `[../contracts/README.md](../contracts/README.md)` · `openapi/delivery-platform-api.json` |
+| **平台部署 Runbook**                                     | `[../services/RUNBOOK.md](../services/RUNBOOK.md)` |
+| 详细架构走查                                               | `[../docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md](../docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md)` |
+| 三轨并行迭代（后端 / 前端 / SDK）                              | `[../docs/engineering/PARALLEL_ITERATION_INDEX.md](../docs/engineering/PARALLEL_ITERATION_INDEX.md)` · `[../docs/engineering/tracks/](../docs/engineering/tracks/)` |
+
+
+**原则**：**授权 SDK**（`java/`、`native/`）与 **商业交付平台**（Spring + Vue）**分仓或分流水线**，避免服务端依赖 JNI/native 与客户端库混用。
+
+**部署形态**：平台/Webhook 后端采用 **多模块开发 + 单 Fat JAR**（仅 bootstrap 模块 `repackage`）；SDK 侧为 **多枚 library jar + native**，**不打** Spring Boot 可执行包 —— 详见 [WORKSPACE_ENGINEERING_LAYOUT.md §5](../docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md)。
@@ -0,0 +1,10 @@
+# 规划中的工程（占位）
+
+以下目录 **仅含 README**，用于对齐 [工作区工程划分文档](../../docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md)。  
+**实现时**：建议在独立 Git 仓库中创建项目，并将本仓库 **`schemas/`** 以 submodule、复制或 Maven/Gradle 资源依赖方式对齐。
+
+| 子目录 | 规划职责 |
+|--------|----------|
+| [`license-webhook-ingress`](license-webhook-ingress) | 比特规则 Callback 接入 |
+| [`delivery-platform-api`](delivery-platform-api) | 客户商务与交付管理平台后端 |
+| [`delivery-platform-ui`](delivery-platform-ui) | 管理端前端 |
@@ -0,0 +1,35 @@
+# delivery-platform-api（规划）
+
+## 职责
+
+实现 [客户商务与交付管理平台](../../../docs/chuangfei-platform-product-modules.md) 中 **M1–M11** 领域 API（客户、项目、合同、交付、SN、Callback 处置、集成配置、设备、待办、报表、审计、身份与权限等）。
+
+## 建议技术栈
+
+- **Spring Boot 4.0.\***、Spring Security、**PostgreSQL 15**、**MyBatis-Plus**、Flyway/Liquibase。
+- OpenAPI（springdoc）；与 `license-webhook-ingress` 通过 **MQ/内部 API** 协作。
+
+## 构建与部署：多模块开发 + 单 JAR 运维
+
+与 **客户端 SDK** 严格区分（详见 [WORKSPACE_ENGINEERING_LAYOUT.md §5](../../../docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md)）：
+
+| 模式 | 做法 |
+|------|------|
+| **开发** | Maven **多模块**：`domain`、`application-service`、`adapters-web`、`adapters-persistence`、**`bootstrap`（唯一 main）** |
+| **部署** | 仅 **`bootstrap`** 模块启用 `spring-boot-maven-plugin` **`repackage`**，产出 **一枚** 可执行 Fat JAR（`java -jar platform-bootstrap.jar`） |
+| **构建命令示例** | `mvn -pl platform-bootstrap -am clean package` |
+
+**禁止**：多个模块同时 `repackage`；在平台任意模块依赖 **`cn.craftlabs:craftlabs-auth-bitanswer`**（客户端 JNI SDK）。
+
+## 与本工作区关系
+
+- **可选**：将 [`schemas/craftlabs-auth-config.schema.json`](../../../schemas/craftlabs-auth-config.schema.json) 作为 **校验导出给现场的 JSON** 的资源（拷贝或构建时嵌入）；**不**为引入 SDK 而把 `craftlabs-auth-parent` 作为父 POM。
+- 若需共享纯配置 POJO：单独 **`craftlabs-auth-config-model`** 薄模块（无 native、无 `System.loadLibrary`），由 SDK 与平台 **分别** 以 **compileOnly/optional** 或复制方式对齐 —— 须经架构评审。
+
+## 仓库建议名
+
+`craftlabs-delivery-platform`
+
+## Maven 坐标建议
+
+- GroupId：如 `cn.craftlabs.platform`（与 `cn.craftlabs:craftlabs-auth-*` **区分**）
@@ -0,0 +1,13 @@
+# delivery-platform-ui（规划）
+
+## 职责
+
+客户商务与交付管理平台 **SPA**：Vue 3 + Vite；对接 `delivery-platform-api` 的 OpenAPI；实现 [产品模块文档](../../../docs/chuangfei-platform-product-modules.md) 所列界面与权限（路由 meta + 后端 RBAC）。
+
+## 与本工作区关系
+
+- 无代码依赖；**文档与排期**见 [BPM 与 Roadmap](../../../docs/chuangfei-platform-bpm-and-roadmap.md)。
+
+## 仓库建议名
+
+`craftlabs-delivery-platform-ui`
@@ -0,0 +1,26 @@
+# license-webhook-ingress（规划）
+
+## 职责
+
+- 接收比特授权云 **规则 Callback**（HTTPS POST + JSON）。
+- 校验 `x-bitanswer-token`（或约定头）；**快速返回 2xx**；正文异步处理。
+- 将事件写入 **消息队列** 或 **inbox 表**（与平台一致：**PostgreSQL 15** + **MyBatis-Plus**），由 `delivery-platform-api` 消费（或同仓 Worker 模块）。
+
+## 建议技术栈
+
+- **Java 21+**（与团队 JDK LTS 一致）、**Spring Boot 4.0.\***。
+- 无 UI；可选 Spring Cloud Gateway 前置，或裸 Tomcat/Jetty + Actuator。
+
+## 与本工作区关系
+
+- **不依赖** `craftlabs-auth-bitanswer` native。
+- 事件 Schema 对齐 [比特规则文档](../../../docs/bitanswer-licensing-design-and-rules.md) §5 与 [Callback 评估](../../../docs/bitanswer-callbacks-endpoints-assessment.md)。
+
+## 构建与部署
+
+- 与平台 API 相同策略：**Maven 多模块** + **唯一 `bootstrap` 模块** `spring-boot-maven-plugin` **repackage** → **单枚** `webhook-bootstrap.jar` 部署。  
+- **不依赖** `craftlabs-auth-bitanswer`。
+
+## 仓库建议名
+
+`craftlabs-license-webhook`（可改名；与 `workspace-manifest.json` 中 `plannedRepositories` 保持一致即可）。
@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://craftlabs.cn/engineering/workspace-manifest.json",
+  "title": "craftlabs-authorization-sdk workspace manifest",
+  "workspace": "craftlabs-authorization-sdk",
+  "description": "客户端授权 SDK 与契约资产；商业交付平台与 Webhook 建议独立仓库，见 engineering/planned/",
+  "components": [
+    {
+      "id": "sdk-java",
+      "path": "java",
+      "type": "maven-multi-module",
+      "artifactId": "craftlabs-auth-parent",
+      "build": "mvn -f java/pom.xml verify"
+    },
+    {
+      "id": "sdk-native",
+      "path": "native",
+      "type": "cmake",
+      "primaryTarget": "craftlabs_auth_bitanswer"
+    },
+    {
+      "id": "auth-config-schema",
+      "path": "schemas",
+      "type": "json-schema",
+      "mainFile": "schemas/craftlabs-auth-config.schema.json"
+    },
+    {
+      "id": "examples",
+      "path": "examples",
+      "type": "samples"
+    },
+    {
+      "id": "documentation",
+      "path": "docs",
+      "type": "markdown"
+    },
+    {
+      "id": "engineering-meta",
+      "path": "engineering",
+      "type": "workspace-metadata"
+    }
+  ],
+  "deploymentPrinciples": {
+    "clientSdk": "多枚 library JAR + native 动态库；不使用 spring-boot-maven-plugin repackage",
+    "platformBackend": "Maven 多模块开发；仅 bootstrap 模块 spring-boot-maven-plugin repackage 产出单枚可执行 Fat JAR；classpath 禁止 craftlabs-auth-bitanswer"
+  },
+  "plannedRepositories": [
+    {
+      "id": "license-webhook-ingress",
+      "suggestedName": "craftlabs-license-webhook",
+      "stack": "Spring Boot 4.0.x",
+      "role": "BitAnswer rules Callback HTTPS ingress, token verify, MQ enqueue",
+      "stubPath": "engineering/planned/license-webhook-ingress",
+      "deployArtifact": "单 Fat JAR（webhook-bootstrap 唯一 repackage）"
+    },
+    {
+      "id": "delivery-platform-api",
+      "suggestedName": "craftlabs-delivery-platform",
+      "stack": "Spring Boot 4.0.x",
+      "role": "Customer, contract, delivery, SN, M5–M11 domains",
+      "stubPath": "engineering/planned/delivery-platform-api",
+      "deployArtifact": "单 Fat JAR（platform-bootstrap 唯一 repackage）"
+    },
+    {
+      "id": "delivery-platform-ui",
+      "suggestedName": "craftlabs-delivery-platform-ui",
+      "stack": "Vue 3 + Vite",
+      "role": "Management console SPA",
+      "stubPath": "engineering/planned/delivery-platform-ui"
+    }
+  ]
+}