From 76ff98db876cd9e699da47216bb24a63bac8ccf4 Mon Sep 17 00:00:00 2001 From: huangping Date: Mon, 6 Apr 2026 21:04:49 +0800 Subject: [PATCH] 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 --- .gitignore | 7 + README.md | 43 ++ ...itanswer-callbacks-endpoints-assessment.md | 88 +++ docs/bitanswer-licensing-design-and-rules.md | 188 ++++++ ...huangfei-bitanswer-integration-platform.md | 391 ++++++++++++ docs/chuangfei-platform-bpm-and-roadmap.md | 359 +++++++++++ docs/chuangfei-platform-product-modules.md | 400 +++++++++++++ docs/engineering/PARALLEL_ITERATION_INDEX.md | 80 +++ docs/engineering/SYSTEM_ARCHITECTURE.md | 562 ++++++++++++++++++ .../WORKSPACE_ENGINEERING_LAYOUT.md | 276 +++++++++ .../tracks/01-backend-platform-webhook.md | 132 ++++ .../tracks/02-frontend-platform-ui.md | 85 +++ docs/engineering/tracks/03-client-sdk.md | 92 +++ engineering/README.md | 19 + engineering/planned/README.md | 10 + .../planned/delivery-platform-api/README.md | 35 ++ .../planned/delivery-platform-ui/README.md | 13 + .../planned/license-webhook-ingress/README.md | 26 + engineering/workspace-manifest.json | 72 +++ 19 files changed, 2878 insertions(+) create mode 100644 README.md create mode 100644 docs/bitanswer-callbacks-endpoints-assessment.md create mode 100644 docs/bitanswer-licensing-design-and-rules.md create mode 100644 docs/chuangfei-bitanswer-integration-platform.md create mode 100644 docs/chuangfei-platform-bpm-and-roadmap.md create mode 100644 docs/chuangfei-platform-product-modules.md create mode 100644 docs/engineering/PARALLEL_ITERATION_INDEX.md create mode 100644 docs/engineering/SYSTEM_ARCHITECTURE.md create mode 100644 docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md create mode 100644 docs/engineering/tracks/01-backend-platform-webhook.md create mode 100644 docs/engineering/tracks/02-frontend-platform-ui.md create mode 100644 docs/engineering/tracks/03-client-sdk.md create mode 100644 engineering/README.md create mode 100644 engineering/planned/README.md create mode 100644 engineering/planned/delivery-platform-api/README.md create mode 100644 engineering/planned/delivery-platform-ui/README.md create mode 100644 engineering/planned/license-webhook-ingress/README.md create mode 100644 engineering/workspace-manifest.json diff --git a/.gitignore b/.gitignore index 9741d22..150ad6b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# SDK 发布产物（校验和脚本生成，不上库） +dist/ + # Build **/build/ **/target/ @@ -34,6 +37,10 @@ cmake-build-*/ # Maven dependency-reduced-pom.xml +# Node (平台前端) +node_modules/ +web/**/dist/ + # Python __pycache__/ *.py[cod] diff --git a/README.md b/README.md new file mode 100644 index 0000000..eceb767 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# CraftLabs Authorization SDK + +创飞 **客户端授权 SDK** 工作区：Java API + Native 动态库 + **授权配置 JSON Schema** + 示例与文档。 +**商业交付管理平台**（合同/交付/SN/Webhook 运营后台）按架构设计为 **独立仓库**，见 [`engineering/planned/`](engineering/planned/) 与 [`docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md`](docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md)。 +平台后端 **运维部署** 为 **单枚可执行 Fat JAR**（多模块源码、`bootstrap` 唯一 `repackage`）；**切勿**与下方 **客户端 SDK** 工件混用或把 SDK 打进平台 JAR。 + +## 仓库结构 + +| 目录 | 说明 | +|------|------| +| [`java/`](java/) | Maven 多模块：`craftlabs-auth-core`、`craftlabs-auth-bitanswer`、`craftlabs-auth-selfhosted`、`craftlabs-auth-tests` | +| [`native/`](native/) | CMake：`libcraftlabs_auth_bitanswer`（JNI + 比特/自研适配占位） | +| [`schemas/`](schemas/) | `craftlabs-auth-config` JSON Schema | +| [`examples/`](examples/) | 示例配置与烟测脚本 | +| [`docs/`](docs/) | 比特对接、创飞平台产品/流程/工程架构文档 | +| [`engineering/`](engineering/) | 工作区 manifest、**规划工程占位** | + +## 构建 + +```bash +# Java（需 JDK 17+） +mvn -f java/pom.xml verify + +# Native（需 CMake、C++、可选 JDK 用于 JNI） +cmake -S native -B native/build -DCRAFTLABS_BUILD_JNI=ON +cmake --build native/build +``` + +## 发布与完整性（SHA-256 / GPG） + +对外发版前生成 **`SHA256SUMS`**、可选 **GPG 签 JAR** 与 **`SHA256SUMS.asc`**，见 **[`java/RELEASING.md`](java/RELEASING.md)**（脚本：`scripts/sdk-release-checksums.sh`）。 + +## 文档索引 + +- 工程划分与边界（架构）：[`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/chuangfei-platform-product-modules.md`](docs/chuangfei-platform-product-modules.md) +- 业务流程与版本排期：[`docs/chuangfei-platform-bpm-and-roadmap.md`](docs/chuangfei-platform-bpm-and-roadmap.md) +- 比特授权与规则纲要：[`docs/bitanswer-licensing-design-and-rules.md`](docs/bitanswer-licensing-design-and-rules.md) + +## 许可证 + +版权所有 © 广州创飞人工智能技术有限公司（以项目实际声明为准）。 diff --git a/docs/bitanswer-callbacks-endpoints-assessment.md b/docs/bitanswer-callbacks-endpoints-assessment.md new file mode 100644 index 0000000..7ba81eb --- /dev/null +++ b/docs/bitanswer-callbacks-endpoints-assessment.md @@ -0,0 +1,88 @@ +# 比特安索方案：工作区走查 — 地址与「回调」评估 + +> **范围**：本仓库内与比特安索（Bitanswer）相关的 URL、回调概念及受影响系统能力。 +> **日期**：2026-04-06 +> **关联**：[授权制度与规则](bitanswer-licensing-design-and-rules.md) · [客户端 API 纲要](bitanswer-client-api-overview.md) · [创飞侧平台与对接能力评估](chuangfei-bitanswer-integration-platform.md) + +--- + +## 1. 结论摘要 + +| 类别 | 是否在本仓库配置 | 典型形态 | 涉及系统功能 | +|------|------------------|----------|--------------| +| **`bitanswer.url`（授权服务地址）** | 是（JSON 配置 + Schema） | `https://…` 云/E3、`bit://ip:port` 集团、`lic://…` 本地等 | 登录、在线激活/升级、会话与心跳、特征项校验等与 **Bitanswer 运行时** 直连的能力 | +| **控制台「规则」HTTP Callback** | 否（官方控制台配置） | 业务系统提供的 `https://…` Webhook + `x-bitanswer-token` | **订单/资产/审计**：激活前后、设备绑定、云保保会话失效等事件的异步通知与集成 | +| **SDK 属性里的函数指针回调** | 未在本 SDK 封装层暴露 | C 侧 `SetAttr` + `ATTR_HB_*_CALLBACK` 等 | **进程内**心跳失败/停止、集团排队等待等 **UI 或重连策略**，非 HTTP | +| **`selfhosted.baseUrl`** | 是（另一 provider） | 自研授权 HTTP 根地址 | 与比特方案并行；本仓库仅 `selfhosted_http_ping` 等占位，非 Bitanswer 官方回调 | + +本 SDK 当前 **`BitAnswerProvider` 仅委托 native，未实现规则 Webhook 接收端**；若产品要在比特控制台配规则回调，需在 **独立后端服务** 实现 POST 接口与鉴权。 + +--- + +## 2. 本仓库中出现的「地址」清单 + +### 2.1 配置项：`bitanswer.url` + +- **定义**：[`BitanswerConfigSection`](../java/craftlabs-auth-core/src/main/java/cn/craftlabs/auth/config/BitanswerConfigSection.java) 字段 `url`。 +- **校验**：[`AuthConfigs`](../java/craftlabs-auth-core/src/main/java/cn/craftlabs/auth/config/AuthConfigs.java) 在 `provider=bitanswer` 时要求非空。 +- **Schema**：[`schemas/craftlabs-auth-config.schema.json`](../schemas/craftlabs-auth-config.schema.json) 描述为 **Bit_Login `szURL`**（云 `http(s)://`、集团 `bit://`、本地 `lic://` 等）。 +- **示例**： + - [`examples/config/floating.bitanswer.json`](../examples/config/floating.bitanswer.json)、[`school.bitanswer.json`](../examples/config/school.bitanswer.json)：`https://cloud.bitanswer.example/e3`（占位云地址）。 + - [`examples/config/wharf.bitanswer.json`](../examples/config/wharf.bitanswer.json)：`bit://license.example.com:8273`（集团服务）。 + +**功能映射（客户端 → 比特侧）**： + +- **登录与会话**：`Bit_Login` / `Bit_LoginEx` 连到该 URL 所指云中心或集团服务；决定云/集团/混合行为还与 `loginMode`、环境变量等有关（见 `docs/bitanswer-client-api-overview.md` §2–3）。 +- **在线激活与升级**：同类 URL 会传给 `Bit_UpdateOnline`、`Bit_GetUpdateInfo` 等（官方 API 表见 `docs/bitanswer-client-api-overview.md` §5）。 +- **可选 `rootPath`**：配置项中有 `rootPath`，对应 `Bit_SetRootPath`，影响本地授权文件查找根目录（与 URL 形态 `root://` 语义相关，见 `docs/c.md`）。 + +### 2.2 文档中的规则 Callback URL（非本仓库代码配置） + +- **出处**：[`docs/bitanswer-licensing-design-and-rules.md`](bitanswer-licensing-design-and-rules.md) §5.5，对应官方 [规则](https://doc.bitanswer.cn/docs/function/rule/) 文档。 +- **形态**：JSON 动作数组中的 `callback.url`，请求头可含 `x-bitanswer-token`。 +- **触发事件**（与业务系统相关）：`sn:pre_activate` / `sn:post_activate`、`device:pre_activate` / `device:post_activate`、`yunbaobao:session_logout` 等。 + +**功能映射（贵司后端若承接回调）**： + +| 事件 | 建议评估的系统能力 | +|------|---------------------| +| `sn:pre_activate` | 激活前风控：黑名单、订单状态、SN 与合同是否一致；可配合异步拒绝策略（以实现为准） | +| `sn:post_activate` | 开通交付、CRM 状态更新、用量计费起点、通知客户 | +| `device:pre_activate` / `post_activate` | 设备台账、换机策略、终端数/浮动策略与内部资产系统对账 | +| `yunbaobao:session_logout` | 会话吊销联动：踢下线、清理服务端会话、安全审计 | + +**注意**：官方说明回调为 **异步 POST**，**响应体可被忽略**；接收方应 **幂等**、校验 `x-bitanswer-token`、限流与防重放。 + +### 2.3 SDK 文档中的「回调」= C 函数指针（非 URL） + +- **出处**：[`docs/c.md`](c.md) 中 `Bit_SetAttr` 相关常量，例如： + - `ATTR_HB_STOPED_CALLBACK` / `ATTR_HB_STOPED_CALLBACK_EX`：心跳停止 + - `ATTR_HB_RETRY_FAILED_CALLBACK` / `ATTR_HB_RETRY_CALLBACK_EX` / `EX2`：心跳重试失败/重试 + - `ATTR_HB_RETRY_SUCCESS_CALLBACK`：心跳重试成功 + - `ATTR_QUEUE_WAIT_CALLBACK`：集团排队等待（与 `BIT_QUERY_WAIT` 等配合） + +**功能映射**：在 **同一进程内** 由 Bitanswer 客户端库调用开发商注册的函数，用于 **监控与授权服务的连接质量、排队 UX、自动重连**。 +**本仓库**：[`BitAnswerProvider`](../java/craftlabs-auth-bitanswer/src/main/java/cn/craftlabs/auth/bitanswer/BitAnswerProvider.java) 未暴露 `setAttr`/这些回调；若需使用，要在 **native 层或后续 JNI** 扩展。 + +### 2.4 其它：`selfhosted.baseUrl` + +- **定义**：[`SelfhostedConfigSection`](../java/craftlabs-auth-core/src/main/java/cn/craftlabs/auth/config/SelfhostedConfigSection.java)。 +- **代码**：[`native/src/selfhosted/http_client.h`](../native/src/selfhosted/http_client.h) 中 `selfhosted_http_ping(base_url)`。 +- **说明**：属于 **自研授权 provider**，与比特控制台规则 Callback **无直接对应**；评估部署时不要与 `bitanswer.url` 混淆。 + +--- + +## 3. 对实现与运维的检查项建议 + +1. **`bitanswer.url`**：区分环境（云/E3 生产、测试集团 `bit://`、纯本地 `lic://`）；与 **产品识别码 `applicationData`**、**SN** 一并纳入密钥与配置管理。 +2. **规则 Callback URL**：在架构图中单独标注为 **比特云 → 贵司公网/内网穿透 HTTPS**；明确 **谁生成 `x-bitanswer-token`**、轮换与日志脱敏（含 `sn`、`mid`、IP）。 +3. **函数指针回调**：若未来在 native 启用，明确线程模型与 **不得在回调中执行阻塞 IO** 等约束（以官方 `bitanswer.h` 为准）。 +4. **文档与代码一致性**：当前 [`native/src/bitanswer/bitanswer_adapter.h`](../native/src/bitanswer/bitanswer_adapter.h) 仍为占位；真正接入 `Bit_Login` 等后，应同步更新本文 §2.1 的实现引用。 + +--- + +## 4. 修订记录 + +| 日期 | 说明 | +|------|------| +| 2026-04-06 | 初版：基于工作区 grep 与核心配置/Java/native 文件走查。 | diff --git a/docs/bitanswer-licensing-design-and-rules.md b/docs/bitanswer-licensing-design-and-rules.md new file mode 100644 index 0000000..8b3e14b --- /dev/null +++ b/docs/bitanswer-licensing-design-and-rules.md @@ -0,0 +1,188 @@ +# 比特授权云：授权制度设计与规则机制（实现依据） + +> **文档来源**（官方）： +> +> - [授权设计与创建](https://doc.bitanswer.cn/docs/function/licensing-design-creation/) +> - [规则](https://doc.bitanswer.cn/docs/function/rule/) +> +> **用途**：作为本仓库及相关功能**设计、实现、联调**时的领域依据；与更宽范围的机制总览见 `[bitanswer-authorization-overview.md](./bitanswer-authorization-overview.md)`。 +> **整理日期**：2026-04-06 +> **对接落地**：创飞侧平台、交付物与能力评估见 [chuangfei-bitanswer-integration-platform.md](./chuangfei-bitanswer-integration-platform.md)。 + +--- + +## 1. 授权制度：四层对象 + +授权由四层对象叠加定义「卖什么、怎么卖、发什么」。 + + +| 层级 | 作用 | +| -------------------- | ------------------------------------------------------------------------------- | +| **产品 (Product)** | 定义被授权对象：一套软件或组合；承载**授权功能模块的集合**。含唯一产品名、**特征项**（功能/加密点）、**配置项**（应用与用户小数据）。 | +| **模版 (Template)** | 产品特征项的**子集**，限定某次授权里**可用模块及版本**，常对应一个**发行版本**。 | +| **业务 (Business)** | 定义**销售/授权商业模式**：云授权、集团授权、单机授权等；在此配置各类**授权属性组合**。 | +| **授权 (Entitlement)** | 实际发给用户的授权：**从模版继承模块**；**从业务继承授权类型**，但可**改写**业务允许的授权属性。由全球唯一 **16 位字母数字 SN** 标识。 | + + +### 1.1 授权内容更新与同步 + +- 授权内容更新后，客户端可用对应 **SN** 升级授权内容。 +- **云授权**：更新可较快反映到客户端，应用**无需重启**。 +- **集团授权、单机授权**：更新在客户端**下次连接服务器**时同步。 +- **单机**：带**智能连接**的会在联网时自动同步；带**强制认证**的需定期连服务器；其它情况多在授权失效时才尝试连服务器。 +- 开发商也可选择**手动**更新客户端本地授权内容。 + +--- + +## 2. 业务侧授权属性（约束维度） + +在业务中可配置的约束项（不同授权类型下可用组合不同），官方文档列出的包括： + + +| 属性 | 说明 | +| --------------- | ----------------------------------- | +| **连接类型**（单机） | 离线，或可自动进行后台验证的**智能连接**。 | +| **强制认证** | 客户端**最大离线时间**；超过后须与服务器再次验证才能继续使用。 | +| **安装限制** | 客户端允许**激活次数**；单机授权下由**所有客户端共享**该次数。 | +| **有效期** | 从激活起算的最长使用时间。 | +| **用户数** | 集团授权：集团服务器可支持的**最大并发访问用户数**。 | +| **起始日期 / 结束日期** | 授权生效、失效的**绝对时间**。 | +| **使用次数** | 客户端能成功执行 **Login** 的次数上限。 | +| **终端限制** | 单机授权允许在多少台客户端上被激活。 | + + +通过不同业务（例如演示业务、永久有效单机正式版业务）组合上述属性，对齐销售与交付形态。 + +--- + +## 3. 特征项 (Feature)：授权在代码中的语义 + +- **标识**：特征 **ID**（整数，API 调用用）+ **名称**（界面展示）；在产品内唯一。 +- **产品级**：数量、名称、类型、是否**可覆盖**、特征组等**仅能在产品特征项界面**完成。 +- **模版 / 授权码级**：只能**选择**特征项、设置特征项的**授权属性**，或修改带「可覆盖」的特征项**值**。 + +### 3.1 特征项在产品上的基本属性 + +- **ID**：系统分配，用于客户端 API 指定特征项。 +- **名称**：用途说明；在集团授权管理界面等对用户可见。 +- **类型**：决定可进行的操作（见下表）。 +- **可覆盖**：是否允许在模版或授权码中**重写该特征项的值**（不同用户/模版需要不同特征值时应开启）。 +- **值**：影响特征项 API 行为。 + +### 3.2 授权码上的特征项授权属性 + +在授权码中可设置/修改（且同时受**整条授权**的授权属性约束）： + +- **有效期**：自所在授权码激活起算，单位**天**。 +- **结束日期**：可用到结束日当天 24 点。 +- **用户数**：仅**集团授权**类型 SN 可设，为该特征项的可用用户数。 + +### 3.3 特征项类型与 API + + +| 类型 | 含义 | 主要 API | +| ------ | ----------- | --------------------------------- | +| **只读** | 只读数据，客户端不可写 | `ReadFeature` | +| **读写** | 可读可写 | `ReadFeature`、`WriteFeature` | +| **算法** | 算法因子，不可直接读写 | `ConvertFeature`（单向转换） | +| **密钥** | AES 密钥因子 | `EncryptFeature`、`DecryptFeature` | + + +所有类型均支持 `**QueryFeature`**、`**ReleaseFeature**`：检查是否存在及是否有效。 +**集团授权**：`QueryFeature` 会占用模块用户数，`ReleaseFeature` 释放；文档要求二者在代码中**成对**出现。 + +### 3.4 特征组 + +- 用于管理与勾选；默认有 **「所有」** 组包含全部特征项。 +- 可新建组并向组内添加特征项；**新特征项默认不会**进入除「所有」外的组，需手工维护。 + +### 3.5 实现与安全注意 + +- 典型用法：每需单独授权的模块分配**主特征项**做 `QueryFeature` / `ReleaseFeature`；辅以加密类特征项；模块退出前释放占用（集团场景尤其重要）。 +- 避免**过于频繁**调用特征项 API，以免影响性能。 +- **DRM 产品**：特征项类型不可设置，且不可选「可覆盖」（用于内容加密密钥）。 +- **密钥 / 算法**类型：操作员仅读权限时特征值不可见，显示为 `**`**。 + +--- + +## 4. 配置项 (Data)：非安全存储 + +- **用途**：`Name` / `Value` 字符串对，存应用配置或少量运行时数据；**不应**代替特征项做安全控制。 +- **与特征项区别**：特征项侧重功能点/加密点；配置项侧重应用与用户数据。 +- **覆盖**：模版或授权码中可创建**产品中未预先定义**的配置项名；若与产品配置项同名则运行时取得**覆盖后**的值。 +- **删除**：可删除授权码中的配置项；**删除产品或模版中定义的配置项会返回错误**。 +- **枚举**：`GetDataNum`、`GetDataName` 等。 +- **可靠性**：客户端库可能**缓存**配置项；异常断电等情况下**近期更新可能丢失**，应用需容错。存储为 **UTF-8**，含中文时客户端需注意编码处理。 + +--- + +## 5. 规则 (Rule)：云端可编程扩展 + +与静态「产品—模版—业务—授权」模型并列，**规则**用于在特定**事件**上注入 **JavaScript 判断 + 动作**，扩展业务逻辑。 + +### 5.1 结构 + + +| 组成部分 | 说明 | +| ------- | ------------------------------------------- | +| **事件** | 规则入口；向触发器提供 `event` 对象（不同事件字段不同）。 | +| **触发器** | JavaScript 编写的条件；返回 **布尔**；`true` 时执行动作。 | +| **动作** | 触发后执行的操作（如回调）；一条规则可有多个动作，**执行顺序不严格保证**；可为空。 | + + +**约束**：一条规则**仅对应一个事件**；创建后需在列表中**启动**方会在下次事件发生时生效。 + +### 5.2 已定义事件（文档列表） + + +| ID | 代码 | 名称 | +| ------ | -------------------------- | -------------------------- | +| 0x0001 | `yunbaobao:session_logout` | 云保保客户端会话失效（登出、踢出、过期） | +| 0x0101 | `sn:pre_activate` | 授权码**首次**激活**前** | +| 0x0102 | `sn:post_activate` | 授权码**首次**激活**后** | +| 0x0301 | `device:pre_activate` | 设备激活**前**（设备**重新激活**时也会执行） | +| 0x0302 | `device:post_activate` | 设备激活**后** | + + +### 5.3 事件载荷要点（实现联调参考） + +- 多类事件含 `**snInfo`**：`sn`、`type`（如 FLOAT）、`volumeNumber`（终端限制）、`activeDate`、`startDate`、`endDate`（文档说明为与 `expirationDays` 合计相关）、`expirationDays`、`userNumber`、`transferVolume`、`transferNumber`、`status`、`customInfo`、`ip` 等。 +- `**sn:post_activate**`、`**device:post_activate**` 等还含 `**device**`：`regDate`、`mid`（设备指纹）、`status`、`deviceCount`（已激活设备总数）等。 +- `**yunbaobao:session_logout**`：`sn`、`sid`、`type`（LOGOUT / EXPIRED / CLEAR / OTHER）、`logout_time` 等。 + +详细字段以官方文档各事件小节为准。 + +### 5.4 触发器运行环境 + +- 语言：**ECMAScript 5.1**；**禁止使用 `const`、`let`**。 +- **无**任意 IO；**无** `console.log`；**无** `window`、`document`、`location` 等。 +- 保存前应用控制台**调试功能**验证脚本。 + +### 5.5 动作：回调 (Callback) + +- 配置为 **JSON 数组**；元素示例形态包含 `callback.url`、`callback.headers`（如 `x-bitanswer-token` 用于认证）。 +- **异步**执行；服务端响应**可被忽略**。 +- 使用 **POST**，**JSON** body；内容包含 `event`、`rule`、`data`（含对应事件的 `snInfo` / `device` / `ip` 等）。 + +--- + +## 6. 与实现工作的对应关系（摘要） + + +| 领域概念 | 实现侧通常对应 | +| ----------------- | ------------------------------------------ | +| 产品 / 模版 / 业务 / SN | 控制台配置与发放流程；SDK 登录对象与产品绑定 | +| 业务授权属性 | 期限、终端、离线、次数、用户并发等策略的建模与校验 | +| 特征项类型与 API | 功能开关、加密点、集团用户数占用与释放 | +| 配置项 | 非敏感 K/V 同步；注意缓存与持久化边界 | +| 规则 | Webhook/内部服务对接激活与设备生命周期；ES5.1 脚本与回调幂等、安全校验 | + + +--- + +## 7. 修订记录 + + +| 日期 | 说明 | +| ---------- | ------------------------- | +| 2026-04-06 | 初版：依据「授权设计与创建」「规则」两篇整理入库。 | diff --git a/docs/chuangfei-bitanswer-integration-platform.md b/docs/chuangfei-bitanswer-integration-platform.md new file mode 100644 index 0000000..48280f2 --- /dev/null +++ b/docs/chuangfei-bitanswer-integration-platform.md @@ -0,0 +1,391 @@ +# 广州创飞人工智能技术有限公司 — 与比特安索对接：平台与交付物能力评估 + +> **平台定义**：**广州创飞人工智能技术有限公司客户商务与交付管理平台** —— 收口 **客户与项目、合同、交付产品、具体授权（含比特安索集成）** 等功能模块，支撑规模化商务履约与许可运营。 +> **目的**：在 [回调与地址走查](bitanswer-callbacks-endpoints-assessment.md)、[授权制度与规则](bitanswer-licensing-design-and-rules.md) 等结论基础上，明确 **创飞侧需建设或提供的平台形态**、**具体交付软件**，以及 **应具备的能力**，用于立项、架构评审与验收。 +> **日期**：2026-04-06 +> **说明**：比特安索侧能力以官方文档与控制台为准；本文聚焦 **创飞作为软件开发商 + 集成方** 的交付范围。 +> **双视角分析**：§6 为 **产品经理** 维度，§7 为 **技术架构（与比特对接的抽象）** 维度。 +> **功能清单**：模块划分与详细功能点见 [chuangfei-platform-product-modules.md](./chuangfei-platform-product-modules.md)。 +> **业务流程与排期**：全业务 BPM、版本与迭代计划见 [chuangfei-platform-bpm-and-roadmap.md](./chuangfei-platform-bpm-and-roadmap.md)。 +> **工程划分**：工作区目录边界与规划仓库见 [engineering/WORKSPACE_ENGINEERING_LAYOUT.md](./engineering/WORKSPACE_ENGINEERING_LAYOUT.md) · [根目录 engineering/](../engineering/README.md)。 +> **实现与使用分档**：§8 为 **前端 + 后端**（**Java Spring Boot 4.0.\* 长期稳定线 + Vue 3 + Vite**）分阶段开发评估；§9 为 **产品使用**（MVP / Mid / Full）分阶段评估。后端 **固定主版本线为 Spring Boot 4.0.\***（补丁随官方 **4.0.x** 升级，**不用里程碑版**），以便与 **Spring 生态后续 AI 相关扩展**（如 Spring AI、统一配置与可观测性栈）同代演进，降低后续集成改造成本。 + +--- + +## 1. 对接边界（谁负责什么） + +| 边界 | 比特安索（授权云 / 集团服务 / 控制台） | 创飞（本公司） | +|------|----------------------------------------|----------------| +| 授权模型 | 产品、模版、业务、SN、特征项、配置项、规则引擎 | 按产品线映射业务 SKU → 控制台配置；不在比特控制台外「再造一套许可模型」除非有自研 `selfhosted` | +| 客户端运行时 | 官方 Bitanswer SDK（C/Java 等）、与产品绑定的库 | 集成 **craftlabs-authorization-sdk**（及随产品 native 库）、应用内调用与配置下发 | +| 出站 HTTP（比特 → 创飞） | 规则动作 **Callback**：向创飞 URL POST JSON | 提供 **公网可达、可鉴权** 的 HTTPS 端点；解析 `event` / `data` 并驱动内部流程 | +| 入站连接（创飞客户端 → 比特） | 云/E3 `https://…`、集团 `bit://…` 等 | 为每环境、每产品线配置正确 **`bitanswer.url`**；管理 SN、`applicationData`、证书与网络策略 | + +--- + +## 2. 创飞建议提供的「平台」形态（逻辑分层） + +不必一开始做成单一巨石系统，但建议在架构上区分以下 **逻辑平台**，便于分工与演进。 + +### 2.1 授权集成与配置平台（对内 DevOps / 架构） + +- **能力**：统一维护「产品线 ↔ 比特产品/模版/业务/特征 ID」映射；生成与校验 [`craftlabs-auth-config`](../schemas/craftlabs-auth-config.schema.json) 类配置；管理多环境 `bitanswer.url`、SN 样例与联调账号。 +- **交付形态**：可先从 **Git 仓库 + Schema CI 校验 + 文档** 起步，再演进为内部配置服务或门户。 + +### 2.2 许可事件与集成平台（对接规则 Callback） + +- **能力**：接收比特控制台配置的 **规则 Callback**（异步 POST）；校验 **`x-bitanswer-token`**（或双方约定头）；按 `event` 类型路由到订单、资产、计费、通知等系统；**幂等**与**重试友好**（官方不依赖响应体）。 +- **交付形态**：独立 **BFF/API 网关后的 Webhook 服务**（建议与核心业务库解耦，用消息队列削峰）。 + +### 2.3 客户与订单主数据（CRM / ERP / 自研商务系统） + +- **能力**：SN 与合同/订单/客户绑定；激活前校验（对应 `sn:pre_activate` 场景）；激活后状态推进（对应 `sn:post_activate`）。 +- **说明**：可复用现有系统；若无，至少需 **最小订单-SN 台账** 才能用好规则回调。 + +### 2.4 设备与终端治理（可选但强烈建议） + +- **能力**：存储 `mid`（设备指纹）与 SN、客户、场站关系；支持换机、终端数对账（对应 `device:pre_activate` / `post_activate`）。 +- **适用**：单机浮动、多终端限制、现场交付类产品（如码头、校园场景示例配置所暗示的部署形态）。 + +### 2.5 可观测性与支持 + +- **能力**：客户端授权失败日志脱敏上报；区分「网络 / SN 无效 / 特征未授权 / 集团满并发」等；与比特控制台告警协同。 +- **交付形态**：日志规范、仪表盘、客服查询 SN 状态的手册（只读控制台或内部工具）。 + +--- + +## 3. 具体交付软件与工件（建议清单） + +下列项可与当前仓库及产品线对齐，按项目裁剪。 + +| 交付物 | 说明 | 与现有仓库关系 | +|--------|------|----------------| +| **craftlabs-authorization-sdk**（及绑定 native） | 统一 Java/Native 授权门面，`provider=bitanswer` 时消费 `bitanswer.url` 等 | 本仓库已有核心模块与示例配置 | +| **产品线授权配置文件** | 每产品/场景的 JSON（含 `features.*.bitanswerFeatureId` 等） | 见 `examples/config/*.bitanswer.json` 模式 | +| **规则 Callback 接收服务** | HTTPS 端点 + 鉴权 + 事件分发；可选管理后台查看原始 payload（脱敏） | **本仓库未包含**，需单独工程 | +| **配置与安全交付流程** | SN、`applicationData`、环境 URL 的分发与轮换；禁止硬编码进镜像 | 流程 + 密钥管理（Vault/KMS/CI Secret） | +| **集成与联调文档** | 环境矩阵、比特控制台截图级操作说明、错误码对照 | 可延续 `docs/bitanswer-*.md` 体系 | +| **（选用）集团授权服务器侧运维** | 若使用 `bit://` 自建集团服务：高可用、备份、与比特版本兼容矩阵 | 与 `wharf.bitanswer.json` 类场景相关 | + +--- + +## 4. 应具备的能力清单（功能与非功能） + +### 4.1 功能能力 + +| 能力域 | 应具备要点 | +|--------|------------| +| **运行时接入** | 能使用官方 SDK + 本 SDK 完成 Login、激活、特征项 Query/Release（集团场景成对释放）、心跳策略与产品识别码一致 | +| **配置治理** | Schema 级校验、环境隔离、特征 ID 与逻辑功能键映射可追溯 | +| **规则 Callback** | 支持文档所列事件的 JSON 解析；与订单/资产状态机衔接；可选拒绝或标记风险（视比特侧是否支持同步阻断，以官方为准） | +| **会话与吊销联动** | 若使用云保保相关能力：能消费 `yunbaobao:session_logout` 或与客户端登出联动，避免「业务已关、许可仍显示占用」类体验问题 | +| **多授权模式共存** | 云 / 集团 / 单机（含智能连接、强制认证）在架构上可区分部署与运维责任，避免混用 URL 与 loginMode | + +### 4.2 非功能能力 + +| 能力域 | 应具备要点 | +|--------|------------| +| **安全** | Callback URL 仅 HTTPS；token 轮换；payload 脱敏日志；防重放与 IP 允许列表（若比特出口 IP 可约定） | +| **可靠性** | Webhook 快速 `2xx`、内部异步处理；队列重试；死信与人工补偿 | +| **合规与审计** | 激活、换机、会话失效留痕；满足客户与内部审计查询 | +| **版本与兼容** | 比特 SDK 与集团服务版本矩阵；升级窗口与客户通知 | + +--- + +## 5. 与比特控制台的操作分工（落地检查表） + +- **创飞运营/产品**：维护产品、模版、业务、特征项；配置规则与 **Callback URL**、**x-bitanswer-token**。 +- **创飞研发**：实现客户端集成、Webhook 服务、内部状态机与对账。 +- **创飞运维**：`bitanswer.url` 网络可达性、证书、集团服务（若自建）SLA。 +- **双方联调**：`sn:pre_activate` / `post_activate` 各至少一轮全链路；含异常 SN、重复激活、设备重激活。 + +--- + +## 6. 产品经理维度：分析与评估 + +### 6.1 平台定位与价值主张 + +将 **客户项目、合同、交付物与授权** 收口为一条可追溯的业务链，并与比特安索在 SN、激活、规则回调、功能开关等能力上打通。对内减少「合同已签但授权未配、交付与许可不一致、规则回调无人跟进」等断层；对外使 **交付可预期、授权可运营、问题可定位**，支撑多产品线、多客户的规模化商务与交付，而非仅依赖人工台账与零散工具。 + +### 6.2 目标用户与人设（内部） + +| 人设 | 典型职责 | 与平台关系 | +|------|----------|------------| +| 商务 / 客户经理 | 商机、报价、合同推进、客户沟通 | 维护客户与项目主数据，触发交付与授权需求 | +| 交付 / 实施 | 交付清单、环境、上线节奏 | 登记交付产品、核对交付与合同范围 | +| 授权运营 / License Ops | SN 策略、激活规则、BitAnswer 配置与异常处理 | 配置授权、处理回调与规则事件、与 SDK/回调服务协同 | +| 订单 / 运营支持（可与 CRM 合并） | 订单、SKU、开票与履约对齐 | 保证「卖什么」与「授什么」一致 | +| 研发 / 平台工程 | SDK、Webhook 服务、可观测性 | 保障集成稳定、排障与版本演进 | +| 管理层 / 财务合规 | 收入确认、审计、风险 | 审计轨迹与报表，非日常操作主用户 | + +### 6.3 核心模块地图（与四大域 + 支撑域） + +- **客户 / 项目**：客户档案、项目/阶段、干系人，与合同/交付关联。 +- **合同**：主数据、标的（产品/模块/席位数/期限）、状态（草稿→生效→变更→终止）。 +- **交付产品**：交付批次与清单、与合同行项/SKU 映射、交付完成标记。 +- **授权**：BitAnswer 集成配置、SN 分配与生命周期、激活记录、功能与产品配置对应（如 per-product JSON）、规则 Webhook 入站与处置状态。 +- **支撑（必要）**：集成与运维（回调地址、配置发布、Webhook 健康度）；事件与规则编排（回调→业务动作/工单）；设备/资产治理（可选）；审计与合规；可观测性（激活与回调指标）。 + +### 6.4 关键用户旅程 + +1. **合同签订 → SN 分配 → 交付 → 激活**：合同生效后生成授权需求 → License Ops 完成（或同步）比特侧 SN/许可包 → 交付标记已交付 → 客户端经 SDK 激活 → 平台记录结果与原因码。 +2. **规则触发 → Webhook → 运营处置**：比特规则满足 → HTTPS 接收回调 → 落库并关联客户/合同/SN → 运营认领、续期/冻结/升级等，写回状态并通知。 +3. **合同变更 → 授权差异对齐**：变更后对比「合同授权视图」与当前比特/缓存状态 → 待办清单 → 批量调整并审计。 +4. **交付争议 / 对账举证**：拉取合同条款 + 交付记录 + SN 发放与激活时间线 + 回调摘要，一条链查到底。 +5. **新产品接入**：平台注册 SKU/功能矩阵 → 维护授权 JSON → 联调 SDK 与测试环境比特 → 上线检查清单（回调可达、监控就绪）→ 商务可报价签约。 + +### 6.5 MVP 与分阶段路线图（P0 / P1 / P2） + +| 阶段 | 范围与理由 | +|------|------------| +| **P0（MVP）** | 客户/项目、合同、交付产品最小主数据与关联；SN 分配与激活结果回写；Webhook 入站 + 事件列表 + 与客户/合同/SN 的基础关联（挂不上先保留原始载荷）；SDK 配置来源与环境区分。**理由**：先跑通主链与排障、审计雏形。 | +| **P1** | 合同行项与授权/SKU 规则化映射、变更 diff；回调处置工作流（认领、状态机、通知）；设备治理（若适用）与审计报表；可观测仪表盘。**理由**：降本增效、减人为错误。 | +| **P2** | 与 CRM/订单深度同步、审批流、多法人；规则/策略可配置编排；到期续费与异常聚类等。**理由**：客户与产品线规模化后的必然需求。 | + +### 6.6 成功指标（KPI） + +- **产品**：主链覆盖率（新签合同在平台内完成合同→交付→授权记录）；SN/激活/回调与客户或合同关联成功率；合同生效到「许可就绪」中位时长；配置模板复用率。 +- **运营**：回调队列处理 SLA、激活成功率与 Top 失败原因、合同与授权不一致类工单占比、关键字段变更可追溯比例（目标趋近 100%）。 + +### 6.7 风险与待决策问题（干系人澄清） + +- 主数据权威（CRM/电子签/本平台）与冲突合并策略。 +- BitAnswer 控制台与平台内闭环的边界、是否双写及对账。 +- Webhook 安全（签名/幂等/重放）、SLA 与灾备是否与商务承诺一致。 +- 多产品 JSON 与客户端/SDK 发版节奏、最低 SDK 版本策略。 +- 日志与 PII 留存、数据跨境（若涉及）。 +- License Ops 编制与工单机制是否在 P0 明确。 +- 管理层优先指标：交付周期 vs 授权类客诉下降，影响功能取舍。 + +--- + +## 7. 技术架构维度：分析与评估 + +### 7.1 系统语境（Context） + +| 参与者 | 角色 | +|--------|------| +| **客户商务与交付管理平台** | 客户、项目、合同、交付项、产品/SKU、SN/设备台账、授权策略与比特 ID 映射；**不提供** BitAnswer 运行时。 | +| **比特安索** | 许可模型、规则、SN/设备生命周期；**出站 Callback** 至创飞 HTTPS。 | +| **客户现场客户端** | **craftlabs-authorization-sdk**（`BitAnswerProvider` → native）+ JSON 配置（含 `bitanswer.url` 等）。 | + +```mermaid +flowchart LR + subgraph CF["创飞平台"] + P["商务与交付域\n项目/合同/交付/SN"] + I["授权集成层\n映射/配置/事件编排"] + W["Webhook 接入\nCallback 接收"] + end + + subgraph BA["比特安索"] + C["控制台 / 规则引擎"] + CL["授权云 / 集团服务"] + end + + subgraph EDGE["客户现场"] + APP["现场客户端\nSDK + Native"] + end + + P --> I + W --> I + I --> P + + C -->|"规则 Callback\nHTTPS POST + Token"| W + APP -->|"Login/激活/特征/心跳"| CL + CL -.->|"策略与许可结果"| APP + I -->|"配置与 SN 交付\n(流程+工件)"| EDGE +``` + +**要点**：Callback 为 **比特 → 创飞**；客户端为 **现场 → 比特**；主数据与状态机在创飞平台闭环；**Webhook 须独立服务**（与本仓库 SDK 分离）。 + +### 7.2 逻辑架构：建议服务与模块 + +| 逻辑组件 | 职责 | +|----------|------| +| **商务与交付核心 API** | 客户、项目、合同、交付项、产品/SKU、SN/设备 CRUD 与状态机；为授权事件提供业务锚点。 | +| **授权集成服务** | 产品线 ↔ 比特产品/模版/业务/特征 ID；`craftlabs-auth-config` 生成/校验；多环境 `bitanswer.url`。可先 Git + Schema CI，再演进配置 API。 | +| **Webhook Ingress** | 公网 HTTPS、Token 鉴权、快速 `2xx`；置于网关/WAF 后；与核心库解耦，异步投递下游。 | +| **事件与工作流编排** | 按 `event` 路由；幂等键；补偿与工单；建议 MQ + DLQ。 | +| **配置与密钥分发** | 脱敏配置模板、环境参数、轮换策略进入发布流水线或配置中心；禁止密钥进镜像。 | +| **可观测与支持** | trace、脱敏审计日志、客户端错误分类上报。 | + +### 7.3 数据域模型（高层） + +```text +客户 ──* 项目 +客户 ──* 合同 + +合同 ──* 交付项 +交付项 *──* 产品/SKU + +产品/SKU ──* 授权策略映射（比特 product/template/business/featureIds、策略版本、环境） + +合同/交付项 ──* SN +SN *──* 设备（mid、换机历史） + +授权事件流水（Callback + 可选客户端上报摘要）── 关联 SN、设备、合同/交付项、event、幂等键、处理状态 +``` + +**要点**：SN 是连接比特控制台与创飞商务数据的键；`LicensePolicyMapping` 将销售 SKU 映射为比特特征与规则；设备域对齐 `device:*` 类事件。 + +### 7.4 集成模式摘要 + +- **规则 Callback**：Ingress 尽快 `2xx`；校验 `x-bitanswer-token` 并支持轮换；幂等键与乱序容忍（按状态机合法性判定）。 +- **边缘配置**：符合 Schema 的 JSON、环境 `bitanswer.url`；SN 与 `applicationData` 经安全通道交付，与镜像构建分离。 +- **密钥**：KMS/Secret Manager；日志脱敏（token 不落库、不落日志）。 + +### 7.5 非功能需求（NFR）与技术风险 + +**NFR**：HTTPS 全链路、WAF/限流、Webhook 多实例无状态、队列多 AZ、RTO/RPO 与降级；结构化日志与按 `event` 的指标；比特 SDK/集团服务 **兼容矩阵** 与发版联动。 + +**风险与缓解**：Callback 洪峰 → MQ 与限流；幂等缺失 → 唯一约束/幂等表；SN 与合同不一致 → `sn:pre_activate` 校验 + 对账任务；SDK 升级破坏现场 → 预发演练与灰度、保留稳定 native 包。 + +### 7.6 分阶段技术交付（与 PM 阶段对齐） + +| PM 阶段 | 技术验收要点 | +|---------|----------------| +| 需求与方案 | 语境图与逻辑架构评审；数据域 v1；事件清单与幂等策略；安全与密钥方案。 | +| 设计 | API/事件契约；Ingress 与队列拓扑；`LicensePolicyMapping` 模型与 Schema 对齐。 | +| 迭代 1（MVP） | 联调环境 SDK 跑通；Webhook 最小实现（鉴权 + 入队 + 2xx）；至少一类核心事件（如 `sn:post_activate`）打通台账。 | +| 迭代 2 | 设备域与 `device:*`；`pre_activate` 风控；DLQ 与补偿；配置 CI 校验。 | +| UAT / 上线 | 全事件抽样、异常与换机场景；监控告警；token 轮换与回滚手册。 | + +--- + +## 8. 前端与后端实现维度：Spring Boot 4.0.\* + Vue 分阶段开发评估 + +### 8.1 技术栈与版本假设 + +| 层级 | 选型 | 说明 | +|------|------|------| +| 后端 | Java + **Spring Boot 4.0.\*** | **主版本线锁定 4.0**，采用官方 **4.0.x** 补丁（GA，非里程碑）；**Jakarta** 命名空间；**Java 基线以 Boot 4 官方 System Requirements 为准**（当前一代为 **Java 17+**，生产 JDK 建议与团队统一为 **LTS，如 21**）。**选型理由**：4.0 线为后续 **AI 能力扩展**（Spring AI、工具调用、向量检索与观测组件等）预留同代生态位，避免在 3.x 与 4.x 之间二次迁移。 | +| 前端 | **Vue 3**（Composition API）+ **Vite** | Vue 3.x + Vite 稳定版；**锁版本**（lockfile）避免构建漂移。 | + +**AI 扩展（规划约束，非 MVP 必做）**：在 Spring Boot **4.0.\*** 上按需引入 **Spring AI**（或官方推荐组合）、统一 **Observability**（Micrometer / OTel）与 **API 契约**（springdoc），使对话、RAG、MCP/工具类集成与现有 REST、安全、配置模型一致；具体模块与版本在立项时按 Spring 官方 BOM 与兼容性矩阵选定。 + +### 8.2 三档总览（最小版 → 完整版） + +| 档位 | 业务目标（一句话） | 前端重心 | 后端重心 | 风险量级 | +|------|-------------------|----------|----------|----------| +| **MVP** | 内部可用：主数据 + 合同/交付最小闭环 + 许可可查 + Callback 不断链 | 少页面、列表+表单、基础鉴权 | 粗粒度模块、REST 为主、Webhook 打通一条链、基础审计 | 中 | +| **Mid** | 流程与协作：状态机、报表雏形、异步与队列可观测 | 复杂表格/表单、按钮级权限、简单仪表盘 | Ingress 与 Worker 分离趋势、Outbox/MQ、幂等固化、OpenAPI 稳定 | 中高 | +| **Full** | 可运营、可审计、可扩展：治理、对账、多集成 | i18n/a11y、高级报表、动态权限/租户 | 限界上下文清晰、读模型/报表分离、SLO、审计独立管道 | 高 | + +### 8.3 MVP（最小版本） + +**目标**：客户/项目、合同、交付项 CRUD；SN 录入/绑定；Webhook 接收 → 校验 → 入队或直写 + **幂等**；关键写操作审计。 + +**前端（Vue）**：布局 + 客户/项目/合同/交付/SN 列表与详情编辑；Callback 投递记录只读页；Pinia + 路由守卫 + axios 封装；表格分页排序；可选导出 CSV；少量单测 + 1～2 条 E2E。 + +**后端（Spring）**：分包域：`identity`、`customer-project`、`contract`、`delivery`、`licensing`、`webhook-ingest`、`audit`；REST `/api/v1/...`；**Spring Security**（JWT 或 Session）+ 粗角色；**PostgreSQL 15** + **MyBatis-Plus** + Flyway/Liquibase；Webhook **inbox 或 MQ**；幂等键 `(source, message_id)` 或 `event_id`；**springdoc-openapi**；Micrometer + 结构化日志 + `/actuator/health`。 + +**前后端依赖**：认证契约、分页/错误码、许可与合同关联模型、Webhook **schemaVersion** 约定。 + +**本档风险**：比特字段枚举与内部模型不一致；Webhook ACK 与落库事务边界；权限过粗导致 Mid 期大改。 + +**工作量（定性）**：**M～L**（联调与 Webhook 占大头）。 + +### 8.4 Mid（增强版） + +**目标**：合同/交付状态机与操作轨迹；许可映射与批量 SN；**MQ 为主路径**；失败重试与 Ops 入口；基础监控指标。 + +**前端**：状态时间轴；Webhook 失败列表与详情（脱敏）；映射配置页；简单 KPI 卡片；可编辑表格、动态表单；**按钮级权限**；ECharts 可选；OpenAPI 客户端进 CI；`Idempotency-Key` 与后端对齐。 + +**后端**：Ingress **独立部署** 倾向；**Outbox** + DLQ；**@PreAuthorize** 细粒度；乐观锁；领域事件；**OpenAPI v1 冻结**；分布式 Trace + 业务指标（Webhook lag、激活成功率）。 + +**风险**：异步与 UI「已受理」反馈不一致；报表与 OLTP 同库压力；映射与比特控制台不同步。 + +**工作量（定性）**：**L**。 + +### 8.5 Full（完整版） + +**目标**：数据范围/多租户（若需要）、审计与合规导出、SLA 看板、对账与异常工单、配置模板化、BitAnswer 全生命周期与对账任务。 + +**前端**：模板/字典/集成配置后台；多维报表与订阅；审计检索；任务中心（长耗时对账）；字段级权限与动态路由；虚拟滚动 + 游标分页；i18n 与 WCAG 目标；契约测试与性能脚本。 + +**后端**：模块化单体或拆服务；**CQRS 轻量**读模型；OAuth2/OIDC/SSO；ABAC/数据范围；读写分离或报表库；事件版本化与回放；OpenAPI 多受众与兼容 CI；SLO 与审计独立存储。 + +**风险**：拆分过早/过晚；审计写放大；业务规则与比特长期分叉（需防腐层与定期对齐）。 + +**工作量（定性）**：**L～XL**。 + +### 8.6 横切能力递进 + +| 能力 | MVP | Mid | Full | +|------|-----|-----|------| +| OpenAPI | 开发态 | CI + v1 冻结 | 多受众 + 兼容检查 | +| 安全 | JWT/Session + 粗角色 | 细权限 + ingress 加固 | SSO + 数据范围 + 密钥轮换 | +| 异步 | 可选 MQ | Outbox + DLQ | 事件版本 + 回放 | +| 观测 | 日志 + health | Metrics + Trace | SLO + 审计管道 | +| 测试 | 手工为主 | E2E + 核心单测 | 契约 + 性能 + a11y | + +--- + +## 9. 产品使用维度：MVP / Mid / Full 分阶段评估 + +> 本节从 **谁在用、要完成什么、界面呈现什么事实、如何运营** 描述，不展开 Spring/Vue 实现细节（见 §8）。 + +### 9.1 三档定位 + +| 档位 | 一句话目标 | +|------|------------| +| **MVP** | **卖—授—激活** 闭环可追溯，Callback 不丢，SN 可关联合同 | +| **Mid** | 规模化：**设备/换机、队列与补偿、对账与报表、通知** | +| **Full** | **变更治理、财务/审计级追溯、深度集成** 与多模式许可运营 | + +### 9.2 MVP + +**角色与任务**：商务建客户/项目/合同；交付登记交付物；License Ops 管 SN 与激活核对；订单支持维护合同行与 SKU 对应；研发保障 Callback 可查。 + +**必备界面**：客户档案；项目工作台；合同台账；合同行/订单行；交付登记；**SN/授权台账**；**Callback 收件箱**；比特侧状态摘要（只读/链接，不替代控制台）。 + +**用户要看到的「事实」**：客户与项目；合同标的；交付是否完成；SN 绑谁、状态；Callback 是否到达与处理结果；**客户→项目→合同→交付→SN** 端到端链路。 + +**运营流**：Callback 入站落库与状态更新或待办；SN 发放与激活核对；失败可重试或人工跟进。 + +**不做**：完整 CRM/电子签、精细设备治理、财务闭环、替代比特控制台全能力、客户自助门户。 + +**验收**：一条真实或模拟链路跑通；合法 Callback 100% 可检索；SN 可追溯到合同；权限与审计字段满足；无「孤儿 SN」至少可警告/筛选。 + +**依赖**：License Ops、比特控制台规则与 token、现场交付节点、研发 Callback 端点。 + +### 9.3 Mid + +**增量角色与任务**：交付管设备/场站与换机；Ops 队列 SLA 与批量 SN；客服按 SN 诊断；管理层看健康度。 + +**增量界面**：设备台账；换机/重激活；Callback 运营台（过滤、批量处理、死信）；**对账视图**（标的 vs 已发 vs 已激活）；待办/通知；产品线与环境映射只读或受控编辑。 + +**增量事实**：多设备历史；Callback 耗时与 TOP 原因；履约缺口；即将到期列表。 + +**不做**：完整 ERP 收入确认、全功能客户自助、经销商分润、自建对等规则引擎。 + +**验收**：换机场景台账完整；对账抽样一致；峰值 Callback 不丢；至少一类通知通道可测。 + +### 9.4 Full + +**增量重点**：财务/合规审计与导出；管理层经营视图；产品/架构的变更与版本治理。 + +**增量界面**：合同变更与版本；授权策略库（映射版本、生效区间）；客户健康度/续费；审计导出；可选客户只读门户；CRM/ERP 同步状态。 + +**验收**：变更闭环 T+X 与控制台一致；审计抽样可追溯；集成成功率与失败清单可处理。 + +### 9.5 与 P0 / P1 / P2 路线对齐 + +| 路线 | 含义 | 与本三档 | +|------|------|----------| +| **P0** | 能接单、交付、授权，Callback 不断链 | ≈ **MVP** 主体 | +| **P1** | 运营效率：队列、对账、设备、通知 | ≈ **Mid** | +| **P2** | 治理与增长：变更、经营分析、深度集成 | ≈ **Full** | + +P0/P1/P2 为**优先级语言**；MVP/Mid/Full 为**产品包边界**；排期可交错，但**验收边界**建议按档固化，避免 MVP 膨胀。 + +--- + +## 10. 修订记录 + +| 日期 | 说明 | +|------|------| +| 2026-04-06 | 初版：基于工作区走查与比特文档推导创飞侧平台与交付物。 | +| 2026-04-06 | 增补：平台正式命名；§6 产品维度、§7 技术架构双 Task 分析并入本文。 | +| 2026-04-06 | 增补：§8 前端+后端（Spring Boot GA + Vue 3 + Vite）分档；§9 产品使用分档；与 P0–P2 对齐说明。 | +| 2026-04-06 | §8 后端基线明确为 **Spring Boot 4.0.\*** 长期线，并补充与 **AI 扩展**（Spring AI 等）同代演进说明。 | diff --git a/docs/chuangfei-platform-bpm-and-roadmap.md b/docs/chuangfei-platform-bpm-and-roadmap.md new file mode 100644 index 0000000..5829e5e --- /dev/null +++ b/docs/chuangfei-platform-bpm-and-roadmap.md @@ -0,0 +1,359 @@ +# 客户商务与交付管理平台 — 业务流程设计与版本迭代排期 + +> **文档角色**：资深产品经理视角的 **全业务 BPM 走查**、**版本迭代计划** 与 **排期框架**（可与研发 Sprint 对齐后填入具体日历）。 +> **计划基准日**：2026-04-06（相对排期以 **T0** 表示立项/开工周）。 +> **关联文档**：[功能模块与功能点](chuangfei-platform-product-modules.md) · [平台与比特对接总览](chuangfei-bitanswer-integration-platform.md) · [回调与地址评估](bitanswer-callbacks-endpoints-assessment.md) · [授权制度与规则](bitanswer-licensing-design-and-rules.md) · [工作区工程划分](engineering/WORKSPACE_ENGINEERING_LAYOUT.md) + +--- + +## 1. 工作区文档走查结论（摘要） + + +| 文档 | 已覆盖内容 | 本文补足内容 | +| -------------------------------------------------- | ----------------------------------------------------- | -------------------------------------- | +| `chuangfei-platform-product-modules.md` | M1–M11 模块、功能点 ID、P0/P1/P2、角色权限矩阵 | **跨模块泳道流程**、**状态机与异常分支**、**发布列车与周次排期** | +| `chuangfei-bitanswer-integration-platform.md` | 对接边界、技术架构、Spring Boot 4.0. + Vue 分档、产品使用 MVP/Mid/Full | 将上述档位 **映射为可发布版本号与迭代切片** | +| `bitanswer-licensing-design-and-rules.md` | 产品/模版/业务/授权、特征项、规则 Callback 事件 | Callback 在 BPM 中的 **触发点与系统边界** | +| `bitanswer-callbacks-endpoints-assessment.md` | URL 类型、Webhook 与 SDK 分工 | 在排期中固定 **Webhook 工程与联调节点** | +| `craftlabs-auth-config` Schema / `examples/config` | 客户端配置形态 | 在 **BP-10** 与 **V1.0** 中体现配置发布依赖 | + + +**排期假设（可调整）**：每迭代 **2 周**；团队为 **1 个全栈小队**（可并行时压缩总周数）；**UAT 每大版本末预留 1 迭代**。 + +--- + +## 2. 业务流程总览索引 + + +| 流程编号 | 流程名称 | 主价值 | 涉及模块 | 主责角色 | +| --------- | ------------------- | ---------- | ----------- | ----------- | +| **BP-01** | 客户与项目准入 | 主数据干净、可挂合同 | M1、M11 | 商务、管理员 | +| **BP-02** | 合同起草、审批与生效 | 「卖什么」入台账 | M2、M10 | 商务、订单支持 | +| **BP-03** | 交付计划与交付完成 | 「可激活」前置 | M3、M2 | 交付 | +| **BP-04** | 授权需求与 SN 发放 | 合同→许可载体 | M4、M2、M3、M6 | License Ops | +| **BP-05** | 现场激活与状态回写 | 闭环到台账 | M4、比特、现场客户端 | 交付、Ops | +| **BP-06** | 许可事件（Callback）入站与处置 | 不断链、可审计 | M5、M4、M8 | Ops、研发支撑 | +| **BP-07** | 合同变更与授权差异对齐 | 卖授一致 | M2、M4、M6、M9 | 商务、Ops | +| **BP-08** | 设备登记、换机与重激活 | 终端合规 | M7、M5、M4 | 交付、Ops | +| **BP-09** | 对账、异常工单与举证 | 管理降险 | M9、M8、M10 | 管理层、财务、合规 | +| **BP-10** | 授权集成配置发布 | 客户端可连比特 | M6、研发 | 架构、Ops | +| **BP-11** | 账户开通、登录与权限变更 | 安全访问 | M11、M10 | 管理员、安全 | + + +--- + +## 3. 业务流程设计（详述） + +### 3.1 BP-01 客户与项目准入 + +**目标**：任何合同必须挂在已存在且已校验的客户/项目下。 + +**步骤**：① 管理员维护字典（行业、区域等）→ ② 商务创建客户档案（必填项校验）→ ③ 创建项目并关联客户、干系人 → ④（可选）客户/项目冻结策略生效。 + +**输出物**：客户 ID、项目 ID；审计记录（M10-F01）。 + +**异常**：重复客户 → P2 合并流程（M1-F08）；权限不足 → M11 拦截。 + +--- + +### 3.2 BP-02 合同起草、审批与生效 + +**目标**：合同状态合法迁移，行项可支撑后续交付与 SN 绑定。 + +**状态机（逻辑）**：`草稿` → `待生效` → `生效`；`生效` → `变更中` → `生效（新版本）`；`生效` → `终止/到期`。 + +**步骤**：① 选客户与项目 → ② 录入合同头与 **合同行项**（SKU/数量/期限）→ ③（P1）附件上传 → ④ 商务/订单支持核对订单号关联（M2-F06）→ ⑤ 状态置为生效。 + +**输出物**：合同 ID、行项 ID；变更时版本号（M2-F07）。 + +**异常**：行项为空或金额/数量口径冲突 → 阻断生效；越权编辑 → 审计告警。 + +--- + +### 3.3 BP-03 交付计划与交付完成 + +**目标**：交付批次与清单与 **合同行** 对齐，标记「已交付」作为 SN 发放门禁（可配置）。 + +**步骤**：① 基于项目/合同创建交付批次 → ② 维护交付清单（产品实例、环境说明 P1）→ ③ 关联合同行项 → ④ 交付工程师确认完成（M3-F05）→ ⑤ 状态变为已交付。 + +**输出物**：交付批次 ID、完成时间。 + +**异常**：未关联合同行的交付项 → 警告或阻断（系统参数 M11-F20）。 + +--- + +### 3.4 BP-04 授权需求与 SN 发放 + +**目标**：从「生效合同 +（建议）已交付」生成许可需求，SN 绑定合同行/项目/客户。 + +**步骤**：① License Ops 查看授权需求清单（M4-F08，可与合同行汇总）→ ② 在比特控制台完成 SN/许可包操作（系统外）→ ③ 平台 **录入或导入 SN**（M4-F01）→ ④ **绑定** 合同行与客户/项目（M4-F02）→ ⑤ 状态：已发放 → 通知客户/交付（可手工，Mid 接 M8）。 + +**输出物**：SN 记录、绑定关系、发放时间。 + +**异常**：孤儿 SN（无绑定）→ 警告列表；与合同数量超额 → 规则校验（P1 增强）。 + +--- + +### 3.5 BP-05 现场激活与状态回写 + +**目标**：客户端经 **craftlabs-authorization-sdk** 与比特交互后，平台侧可见激活结果。 + +**步骤**：① 交付将 SN 与环境说明交付客户 → ② 现场部署并配置 `bitanswer.url` 等（BP-10 已发布配置）→ ③ 客户端激活 → ④ Ops **回写** 激活成功/失败及原因码（M4-F05）或接口同步（若建设）→ ⑤ 更新 SN 状态。 + +**输出物**：激活时间、状态、备注。 + +**异常**：长期未激活 → Mid 纳入报表 M9-F02；失败原因字典维护（M11-F19）。 + +--- + +### 3.6 BP-06 许可事件（Callback）入站与处置 + +**目标**：比特规则触发后 **HTTPS Callback** 不丢、可关联、可关闭。 + +**步骤**：① Webhook Ingress 验签/token → 快速 2xx → ② 落库事件（M5-F01～F04）→ ③ 解析 `sn` 尝试关联 SN/合同 → ④ Ops 处置（认领、备注、更新业务状态或建待办 M8）→ ⑤ 失败进重试/DLQ（Mid）。 + +**事件类型对齐**（参见 [bitanswer-licensing-design-and-rules.md](./bitanswer-licensing-design-and-rules.md)）：`sn:pre_activate` / `post_activate`、`device:pre_activate` / `post_activate`、`yunbaobao:session_logout` 等。 + +**异常**：无法解析关联 → 人工挂接；重复投递 → 幂等不重复改状态。 + +--- + +### 3.7 BP-07 合同变更与授权差异对齐 + +**目标**：合同变更后，**应授 vs 实授** 可对比、可出待办。 + +**步骤**：① 发起合同变更（M2-F07）→ ② 系统生成 **授权差异提示**（行项增减/延期）→ ③ Ops 在比特控制台调整并更新平台 SN/状态 → ④ 关闭变更单。 + +**输出物**：变更版本、操作记录（M10）。 + +**依赖**：Mid 报表 M9、映射 M2-F08 / M6。 + +--- + +### 3.8 BP-08 设备登记、换机与重激活 + +**目标**：`mid` 与 SN 关系清晰，换机与 `device:`* Callback 一致。 + +**步骤（Mid+）**：① 登记设备（M7-F01）→ ② 绑定 SN 历史（M7-F02）→ ③ 换机申请与记录（M7-F03）→ ④ 重激活后 Callback 更新台账。 + +**异常**：终端数超限 → 提示对齐比特策略（不替代控制台规则）。 + +--- + +### 3.9 BP-09 对账、异常工单与举证 + +**目标**：管理层/财务/合规可拉通 **合同—交付—SN—激活—Callback**。 + +**步骤（Mid+）**：① 打开对账视图（M9-F01～F03）→ ② 导出（权限控制 M9-F04）→ ③ 异常项生成待办（M8）→ ④ 合规按 M10 导出审计包（Full）。 + +--- + +### 3.10 BP-10 授权集成配置发布 + +**目标**：产品线、环境、`bitanswer.url`、特征映射与 JSON 模板 **版本化发布** 到现场可安装包或配置中心。 + +**步骤**：① M6 维护映射与模板 → ② Schema 校验（可与 CI 联动）→ ③ 发布记录（M6-F06）→ ④ 随产品发版或运维下发。 + +**依赖**：本仓库 `[schemas/craftlabs-auth-config.schema.json](../schemas/craftlabs-auth-config.schema.json)`。 + +--- + +### 3.11 BP-11 账户开通、登录与权限变更 + +**目标**：最小权限、会话可追溯、敏感操作可审计。 + +**步骤**：① 管理员创建用户并分配角色（M11-F14～F16）→ ② 用户登录/改密/登出（§12.1）→ ③ 角色变更写 M10/M11-F21。 + +**异常**：暴力破解 → 锁定（M11-F05）；人员离职 → 禁用与会话失效（M11-F12）。 + +--- + +## 4. 端到端泳道流程（主链路） + +```mermaid +flowchart TB + subgraph SALES[商务 / 订单支持] + A1[BP-01 客户/项目] + A2[BP-02 合同与行项] + end + + subgraph DEL[交付] + B1[BP-03 交付完成] + end + + subgraph OPS[License Ops] + C1[BP-04 SN 发放与绑定] + C2[BP-06 Callback 处置] + C3[BP-05 激活回写] + end + + subgraph DEVOPS[架构 / 研发] + D1[BP-10 配置发布] + D2[Webhook 服务运维] + end + + subgraph EDGE[客户现场 + 比特] + E1[客户端 SDK 激活] + E2[比特控制台 / 规则] + end + + A1 --> A2 --> B1 --> C1 + D1 --> E1 + C1 --> E1 + E1 --> E2 + E2 -->|Callback| C2 + C2 --> C3 + B1 -.->|门禁| C1 +``` + + + +--- + +## 5. 关键状态机汇总（产品规则） + + +| 对象 | 状态（节选） | 允许迁移（示例） | +| ----------- | ------------------------- | ----------------------- | +| 合同 | 草稿 / 待生效 / 生效 / 变更中 / 终止 | 草稿→待生效→生效；生效→变更中→生效（新版） | +| 交付批次 | 未交付 / 部分 / 已交付 | 未交付→已交付（或经部分） | +| SN | 未发放 / 已发放 / 已激活 / 冻结 / 异常 | 未发放→已发放→已激活；任意→冻结（授权） | +| Callback 事件 | 待处理 / 已处理 / 失败 / 忽略 | 待处理→已处理或失败→（重试）已处理 | +| 用户账号 | 启用 / 禁用 | 启用↔禁用；禁用强制会话失效 | + + +详细字段级规则在 PRD/配置表（M11-F20）中展开。 + +--- + +## 6. 版本迭代总体规划（Roadmap） + + +| 版本 | 定位 | 对应产品包 | 目标上线（相对 T0） | 核心验收 | +| -------- | ------- | ------ | ---------------- | ---------------------------- | +| **V1.0** | MVP 可投产 | MVP | **T0 + 10～12 周** | 主链路 BP-01～06、11 + 一条真实项目 UAT | +| **V1.1** | MVP 加固 | MVP+ | T0 + 14～16 周 | 性能、权限细项、生产监控 | +| **V1.5** | Mid 第一波 | Mid 核心 | T0 + 18～22 周 | M7、M8、M9 主干 + BP-08 雏形 | +| **V1.6** | Mid 完成 | Mid | T0 + 24～28 周 | 对账报表、Callback 运营台、SSO | +| **V2.0** | Full 基线 | Full | T0 + 34～42 周 | 变更治理、审计导出、MFA/数据范围等 P2 | + + +**说明**：若 **双迭代并行**（后端 Webhook 与业务 API 分队），V1.0 可压至 **8～10 周**，但需明确接口契约负责人。 + +--- + +## 7. 分迭代排期（Release Backlog） + +> **三轨并行执行包**（后端双 JAR + 前端 Vue + 本仓 SDK）：见 [engineering/PARALLEL_ITERATION_INDEX.md](./engineering/PARALLEL_ITERATION_INDEX.md) 与 [tracks/01](./engineering/tracks/01-backend-platform-webhook.md)、[02](./engineering/tracks/02-frontend-platform-ui.md)、[03](./engineering/tracks/03-client-sdk.md)。 + +### 7.1 V1.0 MVP（建议 5～6 个迭代 × 2 周） + + +| 迭代 | 周期（相对） | 目标产出 | 覆盖流程/模块 | +| ------ | --------- | ------------------------------------------------ | ----------------------- | +| **I1** | T0～T0+2W | 工程脚手架、CI、环境；M11 登录/登出/会话/审计登录；用户角色粗矩阵 | BP-11 | +| **I2** | +2W～+4W | M1 客户/项目全 P0；M11 字典、用户角色分配 | BP-01 | +| **I3** | +4W～+6W | M2 合同与行项 P0 + 状态机；M10-F01 | BP-02 | +| **I4** | +6W～+8W | M3 交付 P0；M4 SN P0（录入/绑定/状态/回写） | BP-03、BP-04、BP-05（手工回写） | +| **I5** | +8W～+10W | M5 Callback 收件箱 P0；M6 环境与产品线 P0；**Webhook 服务联调** | BP-06、BP-10 最小 | +| **I6** | +10W～+12W | E2E 缺陷收敛；**UAT**；操作手册 v1；生产配置检查清单 | BP-01～06、11 全链路 | + + +**V1.0 必须验收用例**：任选 1 条真实或准生产项目，完成 **客户→合同→交付→SN→（模拟）激活→Callback 可见→台账一致**。 + +--- + +### 7.2 V1.1 加固（建议 2 迭代） + + +| 迭代 | 目标 | +| ------ | --------------------------- | +| **I7** | 权限码拆到按钮级；导出与脱敏；接口限流与安全头 | +| **I8** | 生产观测仪表盘；备份恢复演练；SN/合同批量导入稳定性 | + + +--- + +### 7.3 V1.5～V1.6 Mid（建议 4～5 迭代） + + +| 迭代 | 目标产出 | 覆盖 | +| ----------- | -------------------------------------- | ----------------- | +| **I9** | M7 设备与换机 P1；M5 失败标注与重试入口 | BP-08 | +| **I10** | M8 待办 + 一种通知通道 | BP-06、BP-09 | +| **I11** | M9 对账与 Callback 统计 + 导出 | BP-09 | +| **I12** | M11 SSO、并发会话、强制下线、密码重置；M2/M4/M6 P1 增强项 | BP-02、BP-04、BP-10 | +| **I13（可选）** | M2 变更版本与差异提示；UAT Mid | BP-07 | + + +--- + +### 7.4 V2.0 Full（建议 5～7 迭代） + + +| 主题 | 包含功能域 | +| ------ | ----------------------------------- | +| 合规与审计 | M10-F03/F04；举证包；留存策略 | +| 安全 | M11 MFA、SECURITY_ADMIN、数据范围 M11-F17 | +| 集成与规模化 | M1 CRM 同步 P2；M6 影响分析；M9 订阅与经营看板 | +| 体验 | M8 模板与静默规则；可选客户只读门户（单独立项时移出） | + + +--- + +## 8. 功能点 × 版本映射矩阵（摘要） + +> 完整清单见 [chuangfei-platform-product-modules.md](./chuangfei-platform-product-modules.md) 各表 **优先级** 列；下表按 **版本** 聚合。 + + +| 版本 | P0 全量 | P1 主要增量 | P2 主要增量 | +| ------------- | --------------------------------------------------- | ------------------------------ | ----------------------------- | +| **V1.0** | 各模块标注 P0 的功能点 + M11 §12.1 F01～F07、§12.2 F14～F16、F19 | 不强制 | 不含 | +| **V1.1** | — | 稳定性与权限细化、批量导入 | — | +| **V1.5～V1.6** | — | 全部模块 P1 为主（M7、M8、M9、M11 SSO 等） | 少量 P2 可提前（按商务压力） | +| **V2.0** | — | 收尾 Mid 缺口 | P2：MFA、安全管理员、数据范围、CRM、M10 导出等 | + + +--- + +## 9. 里程碑与依赖 + + +| 里程碑 | 时间点（相对） | 依赖 | +| ------------------ | --------- | -------------------------- | +| M0 立项与范围冻结 | T0 | 本 Roadmap + 模块文档签字 | +| M1 α：可登录 + 主数据 | T0+4W | 身份设计、测试环境 | +| M2 β：合同+交付+SN | T0+8W | 法务字段定稿 | +| M3 γ：Callback 联调通过 | T0+10W | **比特控制台规则 URL**、公网 Ingress | +| M4 UAT 完成 | T0+12W | 种子用户、脱敏数据 | +| M5 生产首上 | T0+12～14W | 运维 SLA、密钥 KMS | +| Mid GA | T0+24～28W | SSO IdP、通知渠道账号 | +| Full GA | T0+34～42W | 法务审计字段、财务口径 | + + +**外部强依赖**：比特安索控制台权限、Callback 出口网络、现场客户端发版窗口（与 BP-10 同步）。 + +--- + +## 10. 假设、风险与待办 + + +| 类型 | 内容 | +| ------ | ---------------------------------------------------------------- | +| **假设** | 单团队 2 周迭代；需求变更每周冻结；比特 API/控制台能力不降级 | +| **风险** | Webhook 延期则 V1.0 砍为「仅收件箱+人工」，激活仍走 BP-05 | +| **风险** | 合同字段反复 → I3 膨胀；建议首期 **法务一次评审** | +| **待办** | 将本文迭代 **I1～I6** 导入 Jira/飞书 **Epic/Story**；为每条 BP 指定 **流程 Owner** | + + +--- + +## 11. 修订记录 + + +| 日期 | 说明 | +| ---------- | ---------------------------------------------- | +| 2026-04-06 | 初版：工作区文档走查；BP-01～11 流程；泳道图；V1.0～V2.0 路线图与迭代排期。 | +| 2026-04-06 | §7 增加指向三轨并行执行文档（后端/前端/SDK）。 | + + diff --git a/docs/chuangfei-platform-product-modules.md b/docs/chuangfei-platform-product-modules.md new file mode 100644 index 0000000..19f2425 --- /dev/null +++ b/docs/chuangfei-platform-product-modules.md @@ -0,0 +1,400 @@ +# 客户商务与交付管理平台 — 功能模块划分与功能点（产品视角） + +> **平台全称**：广州创飞人工智能技术有限公司客户商务与交付管理平台。 +> **文档性质**：产品经理视角的 **模块划分** 与 **功能点清单**，用于需求评审、版本切片与验收对齐。 +> **关联文档**：[平台与比特对接总览](chuangfei-bitanswer-integration-platform.md)（定位、架构、分阶段路线） · [**业务流程与版本排期**](chuangfei-platform-bpm-and-roadmap.md)（BPM、迭代计划） · [工作区工程划分](engineering/WORKSPACE_ENGINEERING_LAYOUT.md)。 +> **优先级约定**：**P0** = MVP 必含；**P1** = 增强运营效率；**P2** = 治理与规模化。同一功能可在多期迭代交付，表中标注为「首期目标优先级」。 + +--- + +## 1. 模块总览 + + +| 序号 | 模块名称 | 一句话职责 | 典型主要用户 | +| --- | -------------------- | ---------------------------------- | ---------------- | +| M1 | **客户与项目中心** | 客户主数据、项目与干系人，作为合同与交付的上游 | 商务、客户经理 | +| M2 | **合同与履约行** | 合同全生命周期、标的与行项，对齐「卖什么」 | 商务、订单支持 | +| M3 | **交付管理** | 交付批次、交付清单与完成状态，衔接「可激活」前提 | 交付/实施 | +| M4 | **授权与许可运营** | SN 台账、与合同/交付绑定、激活状态、与比特侧映射 | License Ops | +| M5 | **许可事件（Callback）运营** | 比特规则 Webhook 入站记录、关联、处置与补偿 | License Ops、研发支撑 | +| M6 | **授权集成与配置** | 产品线↔比特 ID 映射、环境 URL、客户端授权 JSON 治理 | 架构、License Ops | +| M7 | **设备与终端治理** | 设备标识、换机与激活历史（与 `device:`* 事件对齐） | 交付、License Ops | +| M8 | **通知与待办** | 关键事件触达、任务队列与 SLA 提示 | 全员（按角色） | +| M9 | **报表与对账** | 履约与授权一致性视图、缺口与到期 | 管理层、Ops、财务（只读） | +| M10 | **审计与合规** | 关键操作留痕、导出与留存策略 | 合规、管理层 | +| M11 | **身份、访问与平台管理** | **登录/登出与会话**、用户组织、**角色权限**、字典与系统参数 | 全员登录；管理员维护账号与权限 | + + +```mermaid +flowchart TB + M1[客户与项目 M1] + M2[合同与履约行 M2] + M3[交付管理 M3] + M4[授权与许可运营 M4] + M5[许可事件 Callback M5] + M6[授权集成与配置 M6] + M7[设备与终端 M7] + M8[通知与待办 M8] + M9[报表与对账 M9] + M10[审计与合规 M10] + M11[身份与平台管理 M11] + + M1 --> M2 + M2 --> M3 + M2 --> M4 + M3 --> M4 + M6 --> M4 + M5 --> M4 + M4 --> M7 + M5 --> M8 + M4 --> M9 + M3 --> M9 + M2 --> M9 + M1 --> M10 + M2 --> M10 + M3 --> M10 + M4 --> M10 + M5 --> M10 + M11 --> M1 +``` + + + +--- + +## 2. M1 客户与项目中心 + +**定位**：统一客户与项目上下文，避免合同、交付、SN 挂在「无名客户」或重复档案上。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ------------- | -------------------------------------------- | --- | +| M1-F01 | 客户档案创建/编辑 | 客户名称、统一社会信用代码/客户编码、行业、地址、开票信息等（字段以法务/财务为准裁剪） | P0 | +| M1-F02 | 客户列表与检索 | 多条件筛选、分页、关键字搜索 | P0 | +| M1-F03 | 客户详情聚合视图 | 关联项目数、在履约合同数、在途 SN 数等摘要（只读统计） | P0 | +| M1-F04 | 项目创建/编辑 | 项目名称、所属客户、阶段、计划起止、项目经理 | P0 | +| M1-F05 | 项目列表与筛选 | 按客户、阶段、时间筛选 | P0 | +| M1-F06 | 项目干系人 | 客户侧联系人、内部负责人、角色标签 | P0 | +| M1-F07 | 客户/项目冻结与解冻 | 禁止新业务挂载或仅允许只读（规则可配置） | P1 | +| M1-F08 | 客户合并与去重 | 疑似重复客户识别、合并流程与审计 | P2 | +| M1-F09 | 与外部 CRM 主数据同步 | 以外部 ID 关联、增量同步状态展示（不替代 CRM 全能力） | P2 | + + +--- + +## 3. M2 合同与履约行 + +**定位**：合同是「卖什么」的权威来源之一；履约行/合同行是 SN 与交付的锚点。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | --------------- | ------------------------------- | --- | +| M2-F01 | 合同登记与编辑 | 合同编号、客户、关联项目、签订日、生效日、终止条件 | P0 | +| M2-F02 | 合同状态机 | 草稿、待生效、生效、变更中、终止/到期等；非法跳转拦截 | P0 | +| M2-F03 | 合同标的摘要 | 产品/模块/数量/期限/席位等业务口径展示（可与行项汇总一致） | P0 | +| M2-F04 | 合同行项（履约行） | 多行：SKU 或产品包、数量、单价（可选）、交付与授权口径 | P0 | +| M2-F05 | 合同附件 | 上传扫描件/电子签输出（存储与权限受控） | P1 | +| M2-F06 | 合同与订单关联 | 外部订单号、内部订单记录 ID（若存在订单系统） | P1 | +| M2-F07 | 合同变更与版本 | 变更单、版本号、影响授权差异提示（与 M4 联动） | P1 | +| M2-F08 | 合同行与授权 SKU 规则映射 | 行项默认映射到许可 SKU/特征包（与 M6 联动） | P1 | +| M2-F09 | 合同到期与续费提醒 | 基于生效/结束日期的列表与订阅（与 M8 联动） | P2 | + + +--- + +## 4. M3 交付管理 + +**定位**：记录「交了什么、何时可激活」，是 License Ops 发放 SN 的前置依据之一。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ----------- | ------------------------------- | --- | +| M3-F01 | 交付批次创建 | 关联项目/合同，批次号、计划交付日 | P0 | +| M3-F02 | 交付清单 | 交付物条目：产品实例、数量、环境说明、备注 | P0 | +| M3-F03 | 交付与合同行关联 | 每条交付行可关联合同行项，支撑对账 | P0 | +| M3-F04 | 交付状态 | 未交付、已交付、部分交付；关键状态变更留痕 | P0 | +| M3-F05 | 交付完成确认 | 责任人、完成时间、可选客户签收记录 | P0 | +| M3-F06 | 现场环境信息 | 部署地址、网络要求、联系人（敏感字段权限控制） | P1 | +| M3-F07 | 交付与 SN 发放门禁 | 规则：仅「已交付」合同范围可生成/绑定 SN（可配置为强/弱） | P1 | +| M3-F08 | 交付模板 | 按产品线预置交付清单模板 | P2 | + + +--- + +## 5. M4 授权与许可运营 + +**定位**：SN 与激活事实的台账中心；不替代比特控制台，但与比特状态 **摘要对齐、可追溯**。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | -------------- | ---------------------------- | --- | +| M4-F01 | SN 手工录入/导入 | 单条新增、批量导入（模板校验、重复提示） | P0 | +| M4-F02 | SN 与合同/项目/客户绑定 | 必选关联路径之一（合同行或项目），禁止裸 SN 或仅警告 | P0 | +| M4-F03 | SN 生命周期状态 | 未发放、已发放、已激活、已冻结、已回收、异常等 | P0 | +| M4-F04 | SN 详情页 | 展示绑定关系、发放记录、激活时间、最近事件摘要 | P0 | +| M4-F05 | 激活结果回写 | 人工录入或接口同步：成功/失败及原因码分类 | P0 | +| M4-F06 | 比特控制台状态摘要 | 同一 SN 的关键字段摘要或控制台链接（只读，权限控制） | P0 | +| M4-F07 | 批量 SN 操作 | 批量绑定、批量状态变更（审批可选） | P1 | +| M4-F08 | 授权需求单 | 由合同/交付生成的「待发放 SN」清单，供 Ops 执行 | P1 | +| M4-F09 | 试用/正式/续期标签 | 与业务口径一致的标签，便于筛选与报表 | P1 | +| M4-F10 | SN 与设备关联视图 | 展示绑定 `mid` 列表与历史（依赖 M7） | P1 | +| M4-F11 | 授权策略生效视图 | 展示当前映射版本、环境（与 M6 联动） | P2 | + + +--- + +## 6. M5 许可事件（Callback）运营 + +**定位**：承接比特规则 **HTTPS Callback**，保证 **不断链、可关联、可处置**。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ----------- | -------------------------------------------------------------------------------------------------------------------- | --- | +| M5-F01 | 事件收件箱列表 | 按时间、事件类型、`sn`、处理状态筛选 | P0 | +| M5-F02 | 事件详情 | 展示解析后字段 + 脱敏后的原始 payload；关联 SN/合同 | P0 | +| M5-F03 | 处理状态 | 待处理、已处理、失败、忽略；处理人与时间 | P0 | +| M5-F04 | 关联解析失败兜底 | 无法关联主数据时保留事件并支持人工挂接 | P0 | +| M5-F05 | 事件类型字典 | `sn:pre_activate`、`sn:post_activate`、`device:pre_activate`、`device:post_activate`、`yunbaobao:session_logout` 等展示名与说明 | P0 | +| M5-F06 | 失败原因标注 | Ops 可选分类，便于报表 | P1 | +| M5-F07 | 批量重处理/重试入口 | 在业务允许范围内触发补偿（与后端幂等策略一致） | P1 | +| M5-F08 | 死信与积压监控视图 | 队列深度、最久未处理 TOP（与可观测联动） | P1 | +| M5-F09 | 事件驱动待办 | 自动生成待办卡片（与 M8 联动） | P1 | +| M5-F10 | 模拟投递（仅测试环境） | 联调验收工具 | P2 | + + +--- + +## 7. M6 授权集成与配置 + +**定位**：把「产品线—比特产品/模版/业务/特征 ID—环境 URL」管起来，支撑客户端 JSON 与联调。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ----------------- | -------------------------------------------------------------- | --- | +| M6-F01 | 产品线定义 | 产品线编码、名称、说明 | P0 | +| M6-F02 | 环境维度 | 开发/测试/预发/生产及对应 `bitanswer.url` 登记 | P0 | +| M6-F03 | 比特侧 ID 映射 | 产品、模版、业务 ID 与产品线+环境绑定（与控制台一致） | P1 | +| M6-F04 | 逻辑功能键 ↔ 特征项映射 | 对齐 `craftlabs-auth-config` 中 `features.*.bitanswerFeatureId` 等 | P1 | +| M6-F05 | 授权 JSON 模板管理 | 模板版本、变更说明、与 Schema 校验结果（可接 CI） | P1 | +| M6-F06 | 配置发布记录 | 谁、何时、发布了哪一版到哪一环境 | P1 | +| M6-F07 | 控制台链接与说明 | 规则 Callback URL、token 轮换登记（非密钥明文展示） | P1 | +| M6-F08 | SDK / native 版本矩阵 | 与现场客户端兼容范围说明 | P2 | +| M6-F09 | 变更影响分析 | 映射变更影响哪些在服 SN/合同（只读分析） | P2 | + + +--- + +## 8. M7 设备与终端治理 + +**定位**：支撑浮动、换机、终端限制类场景，与比特 `device:`* 事件及 `mid` 对齐。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ----------------- | ----------------------- | --- | +| M7-F01 | 设备登记 | `mid`、别名、场站、关联客户/项目 | P1 | +| M7-F02 | 设备与 SN 绑定历史 | 时间线：首次激活、换机、解绑 | P1 | +| M7-F03 | 换机申请与处理记录 | 轻量审批可选；处理结果与备注 | P1 | +| M7-F04 | 设备列表与检索 | 按 SN、客户、场站筛选 | P1 | +| M7-F05 | 与 Callback 设备事件联动 | 从事件跳转设备详情 | P1 | +| M7-F06 | 终端数/并发策略展示 | 只读展示合同或比特策略摘要（不重复造规则引擎） | P2 | + + +--- + +## 9. M8 通知与待办 + +**定位**：把「该谁处理」说清楚，降低 Callback 与 SN 异常堆积。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ------------ | ------------------------------- | --- | +| M8-F01 | 站内待办列表 | 按角色过滤：待处理 Callback、待发放 SN、待核对激活 | P1 | +| M8-F02 | 待办认领与完成 | 状态流转与备注 | P1 | +| M8-F03 | 邮件/企业微信等一种通道 | 关键事件必达一种（可配置订阅） | P1 | +| M8-F04 | 通知模板 | 事件类型 → 模板变量 | P2 | +| M8-F05 | 静默规则 | 重复事件聚合、防骚扰 | P2 | + + +--- + +## 10. M9 报表与对账 + +**定位**：给管理层与 Ops **履约 vs 授权** 的一致性视图。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------ | ---------------- | ------------------- | --- | +| M9-F01 | 合同标的 vs 已发 SN 视图 | 按合同/行项汇总应发、实发 | P1 | +| M9-F02 | 已发 vs 已激活视图 | 未激活占比、超期未激活列表 | P1 | +| M9-F03 | Callback 统计 | 按类型、状态、时间段的成功率与耗时分布 | P1 | +| M9-F04 | 导出 CSV/Excel | 权限与脱敏策略受控 | P1 | +| M9-F05 | 项目健康度看板 | 多项目并行时的红黄绿（规则可配置） | P2 | +| M9-F06 | 订阅报表 | 定期邮件推送 | P2 | + + +--- + +## 11. M10 审计与合规 + +**定位**：满足内审与客户抽样举证，**关键操作不可抵赖**。 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------- | -------- | --------------------------- | --- | +| M10-F01 | 关键字段变更日志 | 客户、合同、SN 绑定、状态变更：旧值/新值/人/时间 | P0 | +| M10-F02 | 审计检索 | 按对象 ID、用户、时间范围查询 | P1 | +| M10-F03 | 导出审计包 | 范围可选（项目/合同/时间窗），水印与权限 | P2 | +| M10-F04 | 留存策略配置 | 与法务对齐的保留周期说明（技术实现另见架构） | P2 | + + +--- + +## 12. M11 身份、访问与平台管理 + +**定位**：**账户如何安全进入与退出系统**；进入后**能看能改什么**由角色与数据范围控制；以下为 **认证与会话**、**授权模型落地**、**平台配置** 三部分。 + +### 12.1 账户登录、登出与会话 + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------- | ------------- | ----------------------------------------------- | --- | +| M11-F01 | 登录页 | 账号（工号/邮箱/登录名可配置一种为主）+ 密码登录入口；错误提示不暴露用户是否存在（防枚举） | P0 | +| M11-F02 | 登出 | 主动登出：清除服务端会话或作废令牌、前端清理本地凭证 | P0 | +| M11-F03 | 登录态保持与超时 | **空闲超时**自动登出并提示；可选「记住本次会话」策略（与安全基线平衡，默认保守） | P0 | +| M11-F04 | 未登录访问拦截 | 访问受保护路由时跳转登录页，登录成功后回跳原目标 URL（或安全白名单内路径） | P0 | +| M11-F05 | 登录失败与锁定 | 连续失败次数阈值触发**临时锁定**或验证码；解锁策略（时长/管理员解锁）可配置 | P0 | +| M11-F06 | 登录/登出审计 | 记录成功/失败登出、时间、来源 IP、客户端类型（脱敏与留存策略另定） | P0 | +| M11-F07 | 密码修改 | 已登录用户修改本人密码；校验旧密码强度与新密码策略 | P0 | +| M11-F08 | 密码重置 | 管理员重置密码或邮件/短信重置链接（通道选一种即可）；重置后可选强制首次登录改密 | P1 | +| M11-F09 | 企业 SSO / OIDC | 与企业身份源单点登录；登出可与 IdP **单点登出**联动（若 IdP 支持） | P1 | +| M11-F10 | 双因素认证 MFA | TOTP/短信/企业令牌等一种；可配置为全员或高敏角色必选 | P2 | +| M11-F11 | 并发会话策略 | 同一账号是否允许多端同时在线；超出策略时踢旧会话或拒绝新登录（可配置） | P1 | +| M11-F12 | 管理员强制下线 | 安全或人事场景下终止指定用户本会话或全会话 | P1 | +| M11-F13 | 服务时间窗提示（可选） | 维护窗口登录页公告 | P2 | + + +### 12.2 用户、角色与权限配置（管理侧） + + +| 功能点 ID | 功能点名称 | 说明 | 优先级 | +| ------- | ---------------- | --------------------------------------------- | --- | +| M11-F14 | 用户与账号生命周期 | 创建、启用/禁用、离职归档；与 SSO 时同步外部主键 | P0 | +| M11-F15 | 角色定义与分配 | 预置角色（见 §13）+ 可选自定义角色；用户可挂多角色 | P0 | +| M11-F16 | 功能权限（RBAC） | 菜单、按钮、API 操作与 **§13 权限码** 对齐；支持按环境预览「某用户看见什么」 | P0 | +| M11-F17 | 数据范围（Data Scope） | 按事业部/区域/客户组限制列表可见行（与 M11-F18 二选一或组合） | P2 | +| M11-F18 | 数据属主/团队 | 如「仅本人负责客户」「本团队项目」（字段：负责人、协作人） | P1 | +| M11-F19 | 业务字典 | 合同类型、交付类型、SN 异常原因分类等 | P0 | +| M11-F20 | 系统参数 | 「孤儿 SN」强校验、交付门禁、会话超时分钟数、密码策略等 | P1 | +| M11-F21 | 管理员敏感操作留痕 | 改角色、改权限、强制下线、重置密码等单独记审计 | P1 | + + +> **说明**：原 M11-F01～F06 已拆并至 **12.1 / 12.2**；实现时功能点 ID 以研发 backlog 为准，本文 ID 供需求追溯。 + +--- + +## 13. 角色与权限体系 + +### 13.1 模型说明 + +- **认证（Authentication）**：谁登录、会话是否有效 —— 对应 **§12.1**。 +- **授权（Authorization）**：登录后能做什么 —— **RBAC**（角色 → 权限码）为主，**数据范围**（事业部 / 团队 / 属主）为增强（P1/P2）。 +- **权限码**：建议与前后端统一枚举，例如 `module:resource:action`（如 `contract:order:export`），便于接口与按钮同源校验。 + +### 13.2 预置角色定义 + + +| 角色代码 | 角色名称 | 定位 | 典型职责 | +| ---------------- | --------- | --------- | ---------------------------------------- | +| `SYS_ADMIN` | 系统管理员 | 平台配置与账号治理 | 用户/角色/字典/系统参数；**不默认拥有业务全量数据**时可配置为「仅管理」 | +| `SECURITY_ADMIN` | 安全管理员（可选） | 账号与登录安全 | 锁定策略、强制下线、审计检索；与 `SYS_ADMIN` 分离（职责分离，P2） | +| `SALES` | 商务经理 | 客户与签约侧 | 客户、项目、合同维护；发起交付与授权需求 | +| `ORDER_SUPPORT` | 订单/运营支持 | 履约对齐 | 合同行与 SKU、订单号关联；协助商务核对「卖授一致」 | +| `DELIVERY` | 交付工程师 | 现场交付 | 交付批次与清单、环境信息、交付完成确认 | +| `LICENSE_OPS` | 授权运营 | 许可台账与比特协同 | SN 全生命周期、Callback 处置、与控制台操作配合 | +| `DEV_SUPPORT` | 研发/集成支撑 | 技术排障 | Callback 技术字段、集成配置**只读或受限编辑**；无业务合同删除权 | +| `FINANCE_VIEW` | 财务只读 | 对账与收入支撑 | 报表与合同/SN **只读**；无改密权外的写权限 | +| `COMPLIANCE` | 合规/审计 | 抽查与导出 | 审计日志、导出包；业务数据多为 **只读** | +| `EXEC_VIEW` | 管理层只读 | 经营视图 | 报表与健康度看板 **只读** | +| `READONLY_ALL` | 业务只读（可选） | 跨模块浏览 | 全业务 **只读**，用于培训或二线；敏感字段仍脱敏 | + + +**多角色**：用户可同时拥有 `SALES` + `DELIVERY` 等，权限取**并集**；互斥规则（如 `SYS_ADMIN` 与业务高敏导出）由企业策略在实现时约束。 + +### 13.3 模块级权限矩阵（摘要） + +约定：**—** 无访问；**R** 查看；**W** 新建与编辑；**D** 删除；**X** 导出；**A** 审批/处置类（认领、重试、状态变更）；**M** 模块管理配置（映射、字典、系统参数）。 + + +| 模块 | SYS_ADMIN | SALES | ORDER_SUPPORT | DELIVERY | LICENSE_OPS | DEV_SUPPORT | FINANCE_VIEW | COMPLIANCE | EXEC_VIEW | +| ----------- | --------- | ---------- | ------------- | -------- | ----------- | ----------- | ------------ | ---------- | --------- | +| M1 客户与项目 | M / RWD | RWD | R | R | R | R | R | R | R | +| M2 合同 | M / RWDX | RWDX | RWD | R | R | R | RX | RX | R | +| M3 交付 | M / RWD | R | R | RWD | R | R | R | R | R | +| M4 授权/SN | M / RWDA | R | R | R | RWDA | R | RX | R | R | +| M5 Callback | M / RA | — | — | — | RA | R | R | R | R | +| M6 集成配置 | M | — | — | — | RW | R（只读为主） | — | R | — | +| M7 设备 | M / RW | R | R | RW | RW | R | R | R | R | +| M8 待办 | M | R | R | R | R | R | R | R | R | +| M9 报表 | M | R | R | R | R | R | RX | RX | R | +| M10 审计 | M | — | — | — | — | R | R | RX | — | +| M11 身份与平台 | M（全量） | 仅 F07 本人改密 | 同左 | 同左 | 同左 | 同左 | 同左 | R（审计检索） | — | + + +**说明**： + +- `SYS_ADMIN` 列中 **M / RWD** 表示：至少能 **M**（用户角色字典参数）；是否开放业务 **RWD** 由企业决定 —— 建议生产环境 **默认关闭** 业务写权限，仅保留 M11 管理面。 +- `SECURITY_ADMIN`（若启用）：建议拥有 M11 中 F05～F12、F21 及 M10 审计检索 **RX**，**不**默认拥有 M4 SN 发放。 +- `DEV_SUPPORT`：M6 建议 **仅 R**；若需改测试环境映射可走 **变更工单 + 临时提权**。 +- 细粒度需在实现阶段将矩阵展开为 **权限码清单**（每个菜单、按钮、导出、删除各一条）。 + +### 13.4 权限码命名建议（示例） + + +| 权限码 | 含义 | +| ------------------------------- | -------------- | +| `auth:session:logout` | 本人登出（全员） | +| `auth:user:password:change` | 本人改密 | +| `admin:user:manage` | 用户 CRUD | +| `admin:role:manage` | 角色与权限绑定 | +| `customer:project:rw` | M1 读写 | +| `contract:order:rw` | M2 合同读写 | +| `contract:order:export` | M2 导出 | +| `delivery:batch:rw` | M3 交付读写 | +| `license:sn:rw` | M4 SN 读写 | +| `license:sn:export` | M4 导出 | +| `license:callback:process` | M5 处置 Callback | +| `integration:config:rw` | M6 配置写 | +| `integration:config:read` | M6 只读 | +| `report:view` / `report:export` | M9 | +| `audit:search` / `audit:export` | M10 | + + +### 13.5 与版本包的关系（对应 §14） + +- **MVP（P0）**：§12.1 的 F01～F07 + §12.2 的 F14～F16 + F19；§13.2 至少落地 `SYS_ADMIN`、`SALES`、`DELIVERY`、`LICENSE_OPS`、`ORDER_SUPPORT`、`EXEC_VIEW`（或合并只读角色）；§13.3 矩阵可先 **粗粒度**（模块级），Mid 再拆按钮级权限码。 +- **Mid（P1）**：SSO、会话并发、强制下线、密码重置、数据属主/团队；`DEV_SUPPORT`、`FINANCE_VIEW`；权限码全量挂菜单/接口。 +- **Full（P2）**：MFA、`SECURITY_ADMIN`、事业部数据范围、细粒度互斥策略。 + +--- + +## 14. 按版本包的功能边界（与 P0 / P1 / P2 对齐） + + +| 版本包 | 包含模块与要点 | +| -------- | ------------------------------------------------------------------------------------------------------------------------- | +| **MVP** | M1、M2、M3、M4 核心功能点 + M5 收件箱与基础处置 + M6 环境与产品线最小集 + **M11 §12.1（登录/登出/会话/审计）+ §12.2 用户角色权限与字典** + M10-F01；角色矩阵 **§13.3 粗粒度** | +| **Mid** | MVP + M7 + M8 + M9 主体 + M2/M4/M5/M6 增强项 + M10-F02 + **M11 SSO/并发/强制下线/重置密码/数据属主** + **权限码细拆** | +| **Full** | Mid + M2/M6/M9/M10/M11 的 P2 项 + M1/M8 集成与智能化类增强 + **MFA、安全管理员、数据范围** | + + +--- + +## 15. 修订记录 + + +| 日期 | 说明 | +| ---------- | ---------------------------------------------------------------------------------- | +| 2026-04-06 | 初版：产品视角模块划分与功能点表。 | +| 2026-04-06 | 增补：M11 扩展为身份/访问/平台管理；**登录/登出/会话**功能点；**§13 角色与权限体系**（预置角色、模块矩阵、权限码示例）；版本包与 §14 对齐。 | + + diff --git a/docs/engineering/PARALLEL_ITERATION_INDEX.md b/docs/engineering/PARALLEL_ITERATION_INDEX.md new file mode 100644 index 0000000..e70f61e --- /dev/null +++ b/docs/engineering/PARALLEL_ITERATION_INDEX.md @@ -0,0 +1,80 @@ +# 平台前后端 × 客户端 SDK — 并行迭代执行索引 + +> **目的**：在 [BPM 与版本排期](../chuangfei-platform-bpm-and-roadmap.md) 的 **I1～I6 / V1.1 / Mid / V2.0** 框架下，**三条工程线并行**落地时的 **入口文档、同步点与职责**。 +> **基准**：与 [WORKSPACE_ENGINEERING_LAYOUT.md](./WORKSPACE_ENGINEERING_LAYOUT.md)（Fat JAR、禁止服务端 `craftlabs-auth-bitanswer`）一致。 +> **全景**：系统上下文、容器、组件与时序见 [SYSTEM_ARCHITECTURE.md](./SYSTEM_ARCHITECTURE.md)。 +> **安全**：信任边界、威胁缓解与分组件控制见 [SYSTEM_ARCHITECTURE.md §9](./SYSTEM_ARCHITECTURE.md)。 + +--- + +## 1. 三条轨道与文档 + +| 轨道 | 仓库/工作区 | 执行包文档 | +|------|-------------|------------| +| **A. 平台后端** | `craftlabs-delivery-platform` + `craftlabs-license-webhook`（规划） | [tracks/01-backend-platform-webhook.md](./tracks/01-backend-platform-webhook.md) | +| **B. 平台前端** | `craftlabs-delivery-platform-ui`（规划） | [tracks/02-frontend-platform-ui.md](./tracks/02-frontend-platform-ui.md) | +| **C. 客户端 SDK** | 本工作区 `craftlabs-authorization-sdk` | [tracks/03-client-sdk.md](./tracks/03-client-sdk.md) | + +--- + +## 2. 并行模型（同迭代日历） + +三轨 **共用** Roadmap 的 **I1～I6**（各约 **2 周**），同一迭代内并行开工；**硬耦合**集中在 **I5（Callback + Schema）** 与 **I6（UAT）**。 + +| 迭代 | 后端（双 JAR） | 前端（Vue） | 客户端 SDK（本仓） | +|------|----------------|-------------|---------------------| +| I1 | 身份 + Webhook 脚手架 | 登录 + 布局壳 + RBAC 路由 | 文档/边界说明，无阻塞发布 | +| I2 | M1 主数据 + 字典 | 客户/项目页 | 同上 | +| I3 | M2 合同 + M10-F01 | 合同向导与行项 | 同上 | +| I4 | M3 交付 + M4 SN | 交付 + SN 页 | 文档与示例与 BP-10 口径一致 | +| I5 | M5 Inbox + M6 + Webhook 生产链 | Callback + 集成只读页 | **Schema + AuthConfigs + examples 对齐 BP-10** | +| I6 | 加固 + UAT | E2E + 缺陷 | **冻结 SDK 版本 + CHANGELOG + 兼容矩阵** | + +--- + +## 3. 跨轨同步点（必须对齐） + +| 周次/迭代 | 同步内容 | 参与方 | +|-----------|----------|--------| +| **I1 末** | 认证方式（JWT vs Session）、OpenAPI `auth` tag、错误码与 401 行为 | 后端 + 前端 | +| **I2 末** | 客户/项目 DTO 冻结；字典编码 | 后端 + 前端 | +| **I3 末** | 合同状态枚举与非法迁移码；M10-F01 字段 | 后端 + 前端 | +| **I4 末** | SN 绑定与「孤儿 SN」规则；交付门禁参数（M11-F20） | 后端 + 前端 + SDK（文档） | +| **I5 起** | Callback payload 与 inbox DTO；**Idempotency-Key**；Webhook→平台投递方式（HTTP/MQ） | 后端 Webhook + 后端平台 + 前端 + **SDK（Schema/示例）** | +| **I6** | UAT 场景、冻结 **SDK 版本**、两枚 Fat JAR 与前端 `VITE_API_BASE` | 全员 | + +**契约 Owner（建议角色）**：架构或 Tech Lead 兼任；**OpenAPI 单一事实来源** 为本仓库 [`contracts/openapi/delivery-platform-api.json`](../../contracts/openapi/delivery-platform-api.json)（与运行时 `/v3/api-docs` 由 `OpenApiContractSnapshotTest` 对齐），说明见 [`contracts/README.md`](../../contracts/README.md)。 + +--- + +## 4. 依赖关系简图 + +```mermaid +flowchart LR + subgraph FE[前端 UI] + UI[Vue 3] + end + subgraph BE[平台 API] + API[platform-bootstrap.jar] + end + subgraph WH[Webhook] + WB[webhook-bootstrap.jar] + end + subgraph SDK[本仓库 SDK] + JAR[craftlabs-auth-*] + NAT[native] + end + + UI --> API + WB -->|内部调用或 MQ| API + SDK -.->|不依赖平台运行时| API + JAR --> NAT +``` + +--- + +## 5. 修订记录 + +| 日期 | 说明 | +|------|------| +| 2026-04-06 | 初版：三轨并行索引 + 同步点 + Gantt 示意。 | diff --git a/docs/engineering/SYSTEM_ARCHITECTURE.md b/docs/engineering/SYSTEM_ARCHITECTURE.md new file mode 100644 index 0000000..04ca30b --- /dev/null +++ b/docs/engineering/SYSTEM_ARCHITECTURE.md @@ -0,0 +1,562 @@ +# 系统架构设计 — 全景图与组件清单 + +> **角色**：资深架构师视角的 **系统上下文、容器划分、逻辑组件、数据流与部署边界** 的单一汇总页。 +> **读者**：研发、测试、运维、产品与集成方。 +> **关联**：[工作区工程划分](./WORKSPACE_ENGINEERING_LAYOUT.md) · [并行迭代索引](./PARALLEL_ITERATION_INDEX.md) · [功能模块 M1–M11](../chuangfei-platform-product-modules.md) · [比特对接总览](../chuangfei-bitanswer-integration-platform.md) · [`engineering/workspace-manifest.json`](../../engineering/workspace-manifest.json) +> **安全专章**：本章 **§9**（含 **§9.0** 小团队阶段、**§9.8** SDK 发布完整性）；与工作区 [WORKSPACE §10 安全边界](./WORKSPACE_ENGINEERING_LAYOUT.md) 互补。 + +--- + +## 1. 架构目标与原则 + +| 原则 | 说明 | +|------|------| +| **边界清晰** | **客户端授权运行时**（SDK + Native + 现场进程）与 **商业交付平台**（Web + 双后端 + 数据持久化）在 **依赖、发布周期、classpath** 上严格分离。 | +| **契约先行** | 客户端配置以 **`schemas/craftlabs-auth-config.schema.json`** 为契约；Callback / OpenAPI 以 **文档与版本化契约** 对齐多轨迭代（见 [PARALLEL_ITERATION_INDEX](./PARALLEL_ITERATION_INDEX.md)）。 | +| **可运维** | 每个可独立扩缩的后端服务 **一枚 Fat JAR**（`spring-boot-maven-plugin` **repackage** 仅挂在启动模块）；密钥与连接串 **不进** SDK 与示例仓库。 | +| **数据栈锁定** | 平台持久化：**PostgreSQL 15** + **MyBatis-Plus**（详见 [WORKSPACE_ENGINEERING_LAYOUT §9.1](./WORKSPACE_ENGINEERING_LAYOUT.md)）。 | +| **安全默认** | **最小权限**、**纵深防御**、**可审计**；对外入口 **TLS**；敏感面（Webhook、管理 API、SN/许可数据）**单独威胁建模**与门禁。 | +| **阶段目标（创飞当前）** | **小团队**：优先 **功能与需求闭环**；并发与规模 **不高**。平台侧 **单/双 Fat JAR + 单机或少量 VM** 上 `java -jar` 即可；**不将 K8s、云 KMS、服务网格** 作为现阶段必选项，待业务量与合规要求上升再演进。 **安全重心** 放在 **已发布 SDK 的完整性**（不易被 **替换、假冒**），见 **§9.0 / §9.8**。 | + +--- + +## 2. 系统上下文（C4 Level 1） + +展示本体系与 **外部环境** 的关系：谁使用谁、谁回调谁。 + +```mermaid +flowchart TB + subgraph Actors["参与者"] + OPS[运维/管理员] + BIZ[商务/交付/License Ops] + DEV[客户侧研发] + end + + subgraph CraftLabs["创飞侧系统（本方案范围）"] + UI[交付管理平台 Web UI] + API[交付平台 API] + WH[License Webhook Ingress] + DB[(PostgreSQL 15)] + end + + subgraph ClientSite["客户现场 / 边缘环境"] + APP[客户业务应用] + SDK[CraftLabs 授权 SDK] + NAT[BitAnswer Native 库] + end + + subgraph External["外部系统"] + BA[比特安索云 / 控制台] + end + + OPS --> UI + BIZ --> UI + UI --> API + API --> DB + WH --> DB + WH -->|内部 HTTP / MQ 异步| API + + BA -->|规则 Callback HTTPS POST| WH + SDK -->|Bit_Login / 许可 API| BA + APP --> SDK + SDK --> NAT + + DEV -->|依赖 Maven 工件 + JSON 配置| SDK + DEV -.->|阅读 Schema/文档| CraftLabs +``` + +**读图要点**： + +- **比特** 只与 **Webhook**（服务端入站）和 **SDK**（客户端出站授权）发生 **不同方向** 的交互；平台 UI **不** 替代 SDK 完成现场授权。 +- **SDK 不依赖** 平台 API 运行时；二者仅通过 **契约（Schema、文档、可选 OpenAPI 导出配置）** 弱耦合。 + +--- + +## 3. 容器架构（C4 Level 2） + +本工作区与规划仓库中的 **可构建、可部署或可分发单元**。 + +```mermaid +flowchart TB + subgraph Browser["用户浏览器"] + SPA[Vue 3 SPA
delivery-platform-ui] + end + + subgraph DMZ["接入层（可选 Gateway）"] + GW[API Gateway / 反向代理
规划] + end + + subgraph SimpleHost["机房或云主机（单机为主）"] + JAR_API[delivery-platform-api
Fat JAR :8080] + JAR_WH[license-webhook-ingress
Fat JAR :8081] + PG[(PostgreSQL 15)] + MQ[[消息队列
可选·低并发可省]] + end + + subgraph ArtifactRepo["制品与契约"] + MVN[Maven：cn.craftlabs / cn.craftlabs.platform] + SCH[JSON Schema + examples] + NATIVE[各 OS Native 动态库] + end + + subgraph CI["持续集成"] + WF_SDK[ci-java.yml] + WF_PLAT[ci-platform.yml] + end + + SPA -->|HTTPS /api| JAR_API + GW -.-> JAR_API + GW -.-> JAR_WH + JAR_API --> PG + JAR_WH --> PG + JAR_WH -.-> MQ + MQ -.-> JAR_API + + MVN --> APPX[客户应用构建] + SCH --> APPX + NATIVE --> APPX + + WF_SDK --> MVN + WF_PLAT --> JAR_API + WF_PLAT --> JAR_WH + WF_PLAT --> SPA +``` + +**阶段说明（创飞当前）**：并发不高时 **可不部署 MQ**（Webhook 直写库或由 API 轮询即可）；后端以 **一台或两台云主机** 各跑 `java -jar …` 为主，**无需 K8s**。 + +| 容器 | 技术 / 形态 | 默认端口或产出 | 职责摘要 | +|------|-------------|----------------|----------| +| **delivery-platform-ui** | Vue 3 + Vite + Pinia + Element Plus | 静态资源 / dev server | 管理端 SPA：登录、领域页面、调用平台 REST。 | +| **delivery-platform-api** | Spring Boot 3.4.x（目标 4.0.x）、Security、Actuator、MyBatis-Plus | **8080**、Fat JAR | 领域 API、认证、M1–M11 业务能力、读写字段库。 | +| **license-webhook-ingress** | Spring Boot、Actuator | **8081**、Fat JAR | 比特 Callback 入站、验签/Token、快速 2xx、异步投递（表/MQ）。 | +| **PostgreSQL** | 15.x | 5432 | 平台主库；与 SDK **无** 直连。 | +| **SDK Java 模块** | 多模块 Maven，**非** Spring Boot | 多枚 `craftlabs-auth-*.jar` | 配置模型、BitAnswer 桥接、自托管占位等。 | +| **Native** | CMake | `.so` / `.dylib` / `.dll` | 比特官方运行时绑定，随 SDK 版本发布。 | +| **schemas + examples** | JSON Schema、样例 JSON | 无进程 | 配置契约与集成样例。 | + +--- + +## 4. 平台后端逻辑组件（领域视图） + +与产品模块 **M1–M11** 对齐的 **逻辑分包**（实现可跨多 Maven 模块，但边界应一致）。 + +```mermaid +flowchart LR + subgraph API["delivery-platform-api（逻辑）"] + M11[identity / platform M11] + M1[customer-project M1] + M2[contract M2] + M3[delivery M3] + M4[licensing SN M4] + M5[inbox callback M5] + M6[integration mapping M6] + M7[device M7] + M8[notification M8] + M9[reporting M9] + M10[audit M10] + PERS[persistence MyBatis-Plus] + end + + M11 --> M1 + M1 --> M2 + M2 --> M3 + M2 --> M4 + M3 --> M4 + M6 --> M4 + M5 --> M4 + M4 --> M7 + M5 --> M8 + M4 --> M9 + M1 & M2 & M3 & M4 & M5 --> M10 + + M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 & M9 & M10 & M11 --> PERS +``` + +**Webhook 侧（license-webhook-ingress）逻辑组件**（精简）： + +| 组件 | 职责 | +|------|------| +| **Ingress Controller** | 接收 POST、限流与尺寸约束（规划加固）。 | +| **Token / 签名验证** | `x-bitanswer-token` 或约定头；与 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 等环境变量对齐。 | +| **幂等与投递** | `Idempotency-Key` 或 payload 内事件 ID；写入 **inbox** 或 **MQ**（I5+），由平台 API 消费。 | +| **观测** | Actuator、结构化日志、指标（与平台统一约定）。 | + +--- + +## 5. 客户端 SDK 组件（本仓库 `java/` + `native/`） + +```mermaid +flowchart TB + subgraph SDK["CraftLabs Authorization SDK"] + CORE[craftlabs-auth-core
配置 / NativeBridge / 校验] + BIT[craftlabs-auth-bitanswer
Provider + loadLibrary] + SH[craftlabs-auth-selfhosted
占位实现] + TST[craftlabs-auth-tests] + end + + SCH2[schemas + examples] + JNI[libcraftlabs_auth_bitanswer] + + CORE --> BIT + CORE --> SH + BIT --> JNI + TST --> CORE + SCH2 -.-> CORE +``` + +**硬约束**：平台服务端 **禁止** 依赖 `craftlabs-auth-bitanswer` 与 **禁止** `System.loadLibrary("craftlabs_auth_bitanswer")`（见 [WORKSPACE §5](./WORKSPACE_ENGINEERING_LAYOUT.md)）。 + +--- + +## 6. 关键运行时序 + +### 6.1 比特 Callback → 平台 + +```mermaid +sequenceDiagram + participant BA as 比特安索云 + participant WH as license-webhook-ingress + participant Store as PG / MQ + participant API as delivery-platform-api + participant UI as 管理端 UI + + BA->>WH: POST /webhook/bitanswer/callback + WH->>WH: 校验 Token / 幂等键 + WH->>Store: 持久化或入队（异步） + WH-->>BA: 2xx 快速响应 + API->>Store: 拉取 / 消费事件 + UI->>API: 查询 Inbox / 处置状态 +``` + +### 6.2 管理员使用平台 + +```mermaid +sequenceDiagram + participant U as 用户 + participant UI as delivery-platform-ui + participant API as delivery-platform-api + participant DB as PostgreSQL 15 + + U->>UI: 登录 / 操作业务页 + UI->>API: REST（Session / JWT 由迭代约定） + API->>DB: MyBatis-Plus 读写 + API-->>UI: DTO / 错误码 +``` + +### 6.3 客户现场授权（与平台解耦） + +```mermaid +sequenceDiagram + participant APP as 客户应用 + participant SDK as craftlabs-auth-* + participant NAT as Native + participant BA as 比特安索云 + + APP->>SDK: 初始化 + 加载配置 JSON + SDK->>SDK: Schema/规则校验（可选） + SDK->>NAT: JNI 调用 + NAT->>BA: 许可 / 登录协议 + BA-->>NAT: 授权结果 + NAT-->>SDK: 回调结果 + SDK-->>APP: 授权状态 / 特征项 +``` + +--- + +## 7. 全量组件清单（Master Inventory） + +下表覆盖 **本工作区已实现或已占位** 的组件；规划项标注为 **（规划）**。 + +| ID | 组件名称 | 类型 | 路径 / 坐标 / 产物 | 技术栈 | 主要职责 | +|----|----------|------|-------------------|--------|----------| +| C01 | **craftlabs-auth-parent** | Maven 聚合 | `java/pom.xml` | Java 17 | SDK 父工程、依赖与模块编排。 | +| C02 | **craftlabs-auth-core** | Library JAR | `java/craftlabs-auth-core` | Java | 配置模型、`NativeBridge`、与 Schema 对齐的校验入口。 | +| C03 | **craftlabs-auth-bitanswer** | Library JAR | `java/craftlabs-auth-bitanswer` | Java + JNI | `BitAnswerProvider`、`System.loadLibrary`、**仅客户端**。 | +| C04 | **craftlabs-auth-selfhosted** | Library JAR | `java/craftlabs-auth-selfhosted` | Java | 自托管授权占位 / 扩展点。 | +| C05 | **craftlabs-auth-tests** | 测试模块 | `java/craftlabs-auth-tests` | JUnit 等 | SDK 侧集成与回归测试。 | +| C06 | **libcraftlabs_auth_bitanswer** | Native | `native/` | CMake | 各平台动态库，与 C02/C03 **同版本发布**。 | +| C07 | **craftlabs-auth-config Schema** | 契约 | `schemas/craftlabs-auth-config.schema.json` | JSON Schema Draft 2020-12 | 客户端配置 **单一契约**；CI 与 SDK 测试可对齐校验。 | +| C08 | **examples** | 样例 | `examples/` | JSON / 脚本 | 配置样例与烟测引用。 | +| C09 | **documentation** | 文档 | `docs/` | Markdown | 产品、对接、工程、架构。 | +| C10 | **engineering-meta** | 元数据 | `engineering/` | JSON / MD | `workspace-manifest.json`、planned 占位、README 索引。 | +| C11 | **craftlabs-platform-services-parent** | Maven 聚合 | `services/pom.xml` | Java 17 + Spring Boot 3.4.x | 平台后端父 POM；**与 C01 分构建线**。 | +| C12 | **delivery-platform-api** | 可执行 Fat JAR | `services/delivery-platform-api` | Spring Web/Security/Actuator、MyBatis-Plus、PostgreSQL 驱动 | 平台 REST、领域逻辑（迭代扩展）、**8080**。 | +| C13 | **license-webhook-ingress** | 可执行 Fat JAR | `services/license-webhook-ingress` | Spring Web/Actuator | Callback 入站、Token、**8081**。 | +| C14 | **PostgreSQL** | 基础设施 | 部署环境 / `services/docker-compose.yml` | 15.x | 平台主数据存储。 | +| C15 | **delivery-platform-ui** | SPA | `web/delivery-platform-ui` | Vue 3、Vite、Pinia、vue-router、axios、Element Plus | 管理端界面；dev 代理 `/api` → API。 | +| C16 | **CI：SDK Java** | 流水线 | `.github/workflows/ci-java.yml` | GitHub Actions | `java/` 构建与测试（JDK 版本以 workflow 为准）。 | +| C17 | **CI：Platform + Web** | 流水线 | `.github/workflows/ci-platform.yml` | GitHub Actions | `services/` Maven verify + `web/` npm build。 | +| C18 | **API Gateway** | 接入（规划） | 未在本仓 | 待定 | 统一 TLS、路由、限流（可选）。 | +| C19 | **Message Queue** | 中间件（规划） | 未在本仓 | 待定 | Webhook 与 API 解耦、削峰（I5+ 常见形态）。 | +| C20 | **企业 IdP** | 身份（规划） | 未在本仓 | OIDC/SAML 等 | 与 M11 企业登录集成（若需）。 | +| C21 | **密钥与凭据** | 运维配置 | 部署机 | **环境变量**、**chmod 600 配置文件** | 注入 Webhook Token、DB 密码；**禁止** 进 Git；**不强制** 云 KMS。 | +| C22 | **WAF / 边缘限流** | 安全（可选） | 边界 | 云 WAF 或 Nginx 限流模块 | 低并发阶段可省；对外暴露或合同要求时再上。 | + +--- + +## 8. 技术栈总览 + +| 分层 | 选型 | 备注 | +|------|------|------| +| 管理端 | Vue 3、Vite、Pinia、vue-router、axios、Element Plus | 构建产物静态托管或 CDN。 | +| 平台 API | Spring Boot 3.4.x（路线图 4.0.x）、Spring Security、Actuator | Fat JAR 部署。 | +| Webhook | 同上（独立进程） | 与 API **进程隔离**，失败域分离。 | +| ORM | MyBatis-Plus（`mybatis-plus-spring-boot3-starter`） | Boot 4 时切换 `boot4-starter`。 | +| 数据库 | PostgreSQL 15 | 测试可用 H2 PG 模式或 Testcontainers。 | +| 客户端 SDK | Java 17、多模块薄 JAR | 不打 Spring Boot repackage。 | +| 客户端 Native | CMake、比特官方 API | 与 Java **同版本 tag**。 | +| 契约 | JSON Schema 2020-12 | `schemas/` 与 `examples/`。 | + +--- + +## 9. 安全架构（授权与平台） + +授权与许可数据直接影响 **商业履约与合规**，安全需求高于一般内部后台。本节给出 **信任边界、威胁面、控制措施与演进要求**，供架构评审与渗透测试对齐。 + +### 9.0 阶段与重心（广州创飞 · 小团队） + +| 维度 | 当前立场 | +|------|----------| +| **部署** | **单 Fat JAR / 进程** 部署在云主机或内网服务器；PostgreSQL 可与应用 **同机或同 VPC 内另一台**；**不强制** 容器编排与云 KMS。 | +| **密钥** | Webhook Token、数据库密码等放在 **宿主机环境变量** 或 **权限受限的配置文件**（`chmod 600`、仅运行用户可读），**绝不** 提交 Git。 | +| **优先级** | 先保证 **功能与需求闭环**；平台侧 **基础 TLS + 认证 + 日志脱敏** 即可满足多数早期场景。 | +| **安全重心** | **对外发布的 SDK（JAR + Native）**：防范 **供应链篡改与假冒制品**；**破解/逆向** 的硬防线主要在 **比特安索 Native 与许可密码学**，Java 层需 **诚实评估**（见 **§9.8**）。 | + +### 9.1 安全目标（CIA + 授权特有） + +| 目标 | 含义 | 在本体系的落点 | +|------|------|----------------| +| **机密性** | 许可状态、SN、合同金额、Callback 原文、密钥不外泄 | TLS、日志脱敏、DB 访问控制、前端不持久化敏感令牌到不安全存储 | +| **完整性** | Callback 与台账不被篡改；配置与制品未被替换 | Webhook 验签/共享密钥、幂等键、审计日志（M10）、依赖与镜像签名（供应链） | +| **可用性** | 授权链路与管理端在约定 SLA 内可服务 | Webhook 快速 2xx + 异步处理；低并发阶段 **单机 + 健康检查** 即可，**不必** 预设 K8s 弹性扩容 | +| **不可否认性**（按需） | 关键操作可追溯 | 审计表、WORM 或日志外送（合规场景） | + +### 9.2 信任边界 + +```mermaid +flowchart TB + subgraph Untrusted["不可信或半可信"] + Internet((Internet)) + BA[比特云] + CustomerNet[客户现场网络] + Dev[集成方研发环境] + end + + subgraph TrustHigh["高信任 — 创飞数据面"] + PG[(PostgreSQL)] + Secrets[(凭据：宿主机环境变量
或受限配置文件)] + end + + subgraph TrustMed["中信任 — 应用进程"] + API[delivery-platform-api] + WH[license-webhook-ingress] + end + + subgraph TrustUser["用户终端"] + Browser[管理员浏览器] + ClientApp[客户业务进程 + SDK] + end + + Internet -->|TLS 仅| WH + Internet -->|TLS 仅| API + Internet --> Browser + BA -->|HTTPS Callback| WH + CustomerNet --> ClientApp + Dev -.->|Maven/文档| ClientApp + + Browser -->|HTTPS + 会话/JWT| API + ClientApp -->|TLS 至比特/自托管| BA + + WH --> PG + API --> PG + API --> Secrets + WH --> Secrets +``` + +**边界规则**： + +- **Webhook URL** 暴露在公网或 DMZ：视为 **持续被扫描**；必须 **TLS + 强认证 + 限流 + 最小响应体**。 +- **管理端 API**：仅对 **已认证主体** 开放业务写能力；**禁止** 将平台账号用于客户现场 SDK。 +- **SDK 配置 JSON**：含 `bitanswer.url`、`applicationData`、特征映射等，属 **客户环境机密**；**不得** 回传至创飞平台作为默认遥测（除非单独签署数据处理协议并做脱敏设计）。 + +### 9.3 威胁面与缓解（摘要） + +| 威胁 | 示例 | 架构层缓解 | +|------|------|------------| +| **伪造 Callback** | 攻击者 POST 恶意 payload | **共享密钥**（如 `x-bitanswer-token` 与 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 常量时间比较）；**比特官方 IP/证书钉扎**（若文档支持）；**payload 大小与 JSON 深度限制** | +| **重放** | 重复投递同一事件污染台账 | **幂等键**（`Idempotency-Key` / 事件 ID）+ 唯一约束；重复返回成功语义 | +| **撞库 / 会话窃取** | 管理端弱口令、Token 泄露 | **密码策略 / MFA（规划）**、**HttpOnly + Secure Cookie** 或 **短期 JWT + 刷新**、**CORS 严格白名单** | +| **越权** | 用户访问他人合同或 SN | **RBAC（M11）**、**行级授权**（组织/客户维度）、API **资源级鉴权** | +| **注入** | SQL / 反序列化 | **参数化查询**（MyBatis `#{}`）、**禁用不安全的反序列化 gadget**、DTO 白名单 | +| **SSRF**（若存在出站拉取） | 服务端替用户请求内网 | **出站 URL 白名单**、**禁用 file://**、独立网络分区 | +| **供应链 / 假冒 SDK** | 第三方镜像站替换 JAR、客户误下「绿色版」 | **官方唯一分发渠道** + **GPG/SHA-256 校验**（§9.8）；Maven 依赖 **锁定版本**；CI **依赖漏洞扫描**（力所能及） | +| **日志泄露** | Callback 原文、Token 打日志 | **结构化日志字段脱敏**、**禁止 debug 打印完整 Authorization** | + +### 9.4 分组件控制要求 + +#### 9.4.1 `license-webhook-ingress` + +| 控制项 | 要求 | +|--------|------| +| 传输 | **仅 HTTPS**；HTTP 仅允许本机健康检查（若必须）且不得承载业务 | +| 认证 | 配置 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 时 **强制校验** `x-bitanswer-token`（或比特约定头）；生产 **禁止** 长期关闭校验 | +| 处理 | **先校验后解析大对象**；限制 body 大小；超时快速失败仍返回约定错误码（避免资源耗尽） | +| 观测 | 日志记录 **事件 ID、幂等键、结果码**；**不** 记录完整密钥与完整 payload（或脱敏后） | +| 网络 | 云厂商 **安全组** 仅开放 443/业务端口；数据库 **不对公网**；单机阶段 **本机回环或内网 IP** 连库即可 | + +#### 9.4.2 `delivery-platform-api` + +| 控制项 | 要求 | +|--------|------| +| 认证 | I1 演示账号 **不得用于生产**；生产至少 **强口令**；团队具备条件时再上 **MFA / 企业 IdP（C20）** | +| 授权 | 每个 mutating 接口 **显式角色/权限**；与 M11 角色矩阵一致 | +| 数据 | DB 账号 **最小权限**（读写分离账号可选）；连接串来自 **环境变量或宿主机配置**，禁止提交仓库 | +| Actuator | **生产关闭或仅本机访问** `env`、`heapdump`；`health` 可给 **本机监控脚本或 Nginx 探活** | +| CORS | **显式允许源**，禁用 `*` 携带凭证 | + +#### 9.4.3 `delivery-platform-ui` + +| 控制项 | 要求 | +|--------|------| +| 存储 | **不** 将 refresh token 写入 `localStorage`（优先 HttpOnly Cookie 或安全内存策略） | +| CSP | 生产启用 **Content-Security-Policy**，限制内联脚本与未知域 | +| 依赖 | `npm audit` 纳入 CI；锁定 lockfile | + +#### 9.4.4 客户端 SDK 与 Native + +| 控制项 | 要求 | +|--------|------| +| 配置 | `craftlabs-auth-config` 由 **宿主应用** 安全加载（文件权限、必要时磁盘加密）；**禁止** 将含敏感字段的示例提交到客户代码库模板 | +| 完整性 | Native **与 JAR 同版本** 分发；**正式发布** 必须带 **校验与/或签名**（见 **§9.8**） | +| 运行时 | **不信任** 客户进程内存防护；敏感字符串尽量 **缩短生命周期**（比特 SDK 能力范围内） | + +#### 9.4.5 PostgreSQL + +| 控制项 | 要求 | +|--------|------| +| 网络 | DB **不暴露公网**；仅应用子网可达 | +| 加密 | 云盘默认加密或宿主机全盘加密即可；敏感列 **应用层加密** 为可选增强 | +| 审计 | 高危 DML/DDL 与 **管理员账号** 变更记入 M10 或 DB 审计扩展 | + +### 9.5 与时序对齐的安全步骤（示意） + +**Callback（补充安全步骤）**： + +```mermaid +sequenceDiagram + participant BA as 比特安索云 + participant WH as Webhook + participant Store as PG/MQ + + BA->>WH: TLS + POST + WH->>WH: TLS 终结校验（mTLS 仅在高合规客户场景考虑） + WH->>WH: 校验 Token（常量时间） + WH->>WH: 限制 body 大小 + 解析 + WH->>WH: 幂等键去重 + WH->>Store: 写入 inbox（脱敏日志） + WH-->>BA: 2xx +``` + +**管理端（补充安全步骤）**： + +```mermaid +sequenceDiagram + participant U as 用户 + participant UI as SPA + participant API as Platform API + + U->>UI: 登录 + UI->>API: HTTPS + CSRF 防护（Cookie 模式） + API->>API: 认证 + 颁发会话/JWT + UI->>API: 业务请求 + 凭证 + API->>API: 鉴权（角色 + 资源） + API-->>UI: 最小必要 DTO +``` + +### 9.6 合规与审计衔接 + +- **M10 审计与合规**：登录、合同变更、SN 绑定/解绑、Callback 处置、权限变更等 **必须** 产生不可抵赖审计记录（谁、何时、对象 ID、前后摘要）。 +- **数据出境**：若 Callback 或日志含个人信息，需对齐 **个人信息保护法** 与客户 DPA。 +- **渗透测试**：有对外暴露或合同要求时，对 **Webhook** 与 **管理 API** 做专项测试（认证绕过、IDOR、批量枚举）；小团队可 **采购外包渗透** 或分阶段补做。 + +### 9.7 架构评审安全清单（节选） + +- [ ] Webhook 生产环境 **已启用** 共享密钥或更强机制（签名/HMAC 以比特文档为准）。 +- [ ] 管理 API **无** 默认弱口令路径；Actuator 敏感端点 **已收敛**。 +- [ ] 平台与 Webhook **未引入** `craftlabs-auth-bitanswer`。 +- [ ] 日志与异常栈 **无** 明文数据库密码、Token、完整 Callback。 +- [ ] OpenAPI 中 **错误码** 不泄露内部堆栈或枚举用户存在性（登录接口需谨慎）。 +- [ ] `examples/config/*.json` **无** 真实生产 URL/密钥（仅占位）。 +- [ ] **SDK 发布**：每个对外版本具备 **SHA-256 清单**；**强烈建议** GPG 签名与 **唯一官方下载说明**。 +- [ ] **SDK 发布**：`java` 与 `native` **同 tag**，CHANGELOG 与交付说明 **可追溯**。 + +### 9.8 SDK 发布完整性（当前安全重心） + +客户侧 **Java 字节码可被反编译**，单靠混淆无法对抗动机足够的攻击者。**真正承担许可与密码学校验的**，应是 **比特安索 Native 与云端许可体系**。创飞 SDK 的安全目标应定位为： + +1. **防篡改、防假冒**：客户拿到的是 **官方构建** 的 JAR/Native，未被中间人替换。 +2. **防版本错配**：JAR 与 `.so/.dylib/.dll` **同一次发布**（同 Git tag / 同一 Release 页），避免「新 JAR + 旧库」导致异常或绕过路径。 +3. **可追溯**：出问题能对照 **确切版本与校验和** 复现。 + +| 措施 | 说明 | 小团队可执行性 | +|------|------|------------------| +| **官方唯一渠道** | 仅通过 **公司控制的 Maven 私服 / GitHub Release / 合同交付包** 分发；**禁止** 引导客户从匿名网盘、论坛下载「整合包」。 | 必做 | +| **SHA-256 清单** | 每个 Release 发布 `SHA256SUMS`；仓库内 **`scripts/sdk-release-checksums.sh`** 已落地，说明见 **`java/RELEASING.md`**；客户用 `sha256sum -c` / `shasum -a 256 -c` 校验。 | 必做 | +| **GPG 签名** | Maven：**`mvn -f java/pom.xml -Prelease-sign verify`**（`maven-gpg-plugin`，各 JAR 旁生成 `.asc`）；清单文件：`SIGN=1` 跑上述脚本生成 `SHA256SUMS.asc`。公布 **公钥指纹** 固定页。 | 强烈建议 | +| **Git Tag = 发布单元** | `java/` 与 `native/` **同一 tag** 打发布；CHANGELOG 写清 **兼容的比特 SDK 版本**。 | 必做 | +| **依赖锁定** | 客户工程使用 **明确版本号** 或 BOM；避免「浮动版本」被投毒依赖间接替换。 | 建议 | +| **ProGuard 等混淆** | 仅增加逆向成本，**不能**替代 Native 侧安全；若上，只作 **非关键路径** 的辅助手段。 | 可选 | +| **法务条款** | 许可协议中约定 **禁止反编译、再分发**（民事约束，与技术防护互补）。 | 建议 | + +**客户集成检查清单（可印在交付文档）**： + +- [ ] JAR/Native 均来自 **创飞官方渠道**，并已核对 **SHA-256**（或验签）。 +- [ ] 各工件版本号 **一致**，与发布说明中的 **比特依赖版本** 一致。 +- [ ] 未混入第三方「破解补丁」或修改版 `libcraftlabs_auth_bitanswer`。 + +--- + +## 10. 部署与网络（简图） + +```mermaid +flowchart TB + subgraph Public["公网 / 比特侧可达"] + BA[比特 Callback 出口 IP] + end + + subgraph Perimeter["边界（常为一台 Nginx/Caddy）"] + LB[TLS 终结 + 反代] + end + + subgraph AppTier["应用层（单机或双机 java -jar）"] + WH_P[Webhook Fat JAR] + API_P[Platform API Fat JAR] + UI_S[静态 UI 或同机 Nginx 托管] + end + + subgraph DataTier["数据层"] + PG_P[PostgreSQL 15
单实例或云托管] + end + + BA --> LB --> WH_P + Users((管理员浏览器)) --> LB --> UI_S + Users --> LB --> API_P + WH_P --> PG_P + API_P --> PG_P +``` + +**阶段注记（创飞当前）**：**不依赖 K8s**；扩容以 **加机器 + 多实例反代** 即可。**安全注记**：云安全组 **收紧**；PG **仅内网**；WAF/mTLS **按合同与预算** 选装，非 MVP 必选。 + +--- + +## 11. 修订记录 + +| 日期 | 说明 | +|------|------| +| 2026-04-06 | 初版：系统上下文、容器、领域与 SDK 组件图、时序、全量组件表、技术栈与部署简图。 | +| 2026-04-06 | **§9 安全架构**：信任边界、威胁与缓解、分组件控制、安全时序、合规与评审清单；原则表增加 **安全默认**；部署节增加安全注记。 | +| 2026-04-06 | **对齐小团队**：§1 **阶段目标**、§3 单机部署说明、§9.0、凭据改为宿主机配置、部署图改为 `java -jar` + Nginx；新增 **§9.8 SDK 发布完整性**（防篡改/假冒重心）。 | + +--- + +**下一步**：领域表结构、OpenAPI 与事件 Schema 建议单独维护为 **版本化契约仓库** 或 `contracts/` 子模块，并在 [PARALLEL_ITERATION_INDEX](./PARALLEL_ITERATION_INDEX.md) 的同步点更新版本号。 diff --git a/docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md b/docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md new file mode 100644 index 0000000..39a9ff3 --- /dev/null +++ b/docs/engineering/WORKSPACE_ENGINEERING_LAYOUT.md @@ -0,0 +1,276 @@ +# 工作区工程划分与仓库边界 — 架构说明 + +> **角色**：资深架构师对工作区现有资产与 **创飞客户商务与交付管理平台** 相关文档的对照走查结论。 +> **范围**：本 Git 工作区根目录 `craftlabs-authorization-sdk` 的 **物理目录、构建边界、发布物、与外部工程的契约**；**不**在本提交中迁移 `java/`、`native/` 路径（避免破坏既有 CI 与本地脚本）。 +> **关联**：[**系统架构全景（图 + 全量组件）**](./SYSTEM_ARCHITECTURE.md) · [功能模块](chuangfei-platform-product-modules.md) · [BPM 与排期](chuangfei-platform-bpm-and-roadmap.md) · [平台与比特对接](chuangfei-bitanswer-integration-platform.md) · [三轨并行执行索引](./PARALLEL_ITERATION_INDEX.md) · [根目录 `engineering/` 清单](../../engineering/workspace-manifest.json) + +--- + +## 1. 走查结论（摘要） + + +| 维度 | 现状 | 架构建议 | +| --------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | +| **工作区身份** | 以 **客户端授权 SDK**（Java + Native）为核心，配套 **Schema、示例配置、产品/平台文档** | 保持本仓库 **「授权 SDK + 契约资产」** 为一等公民；**商业交付平台**（Spring Boot 4.0. + Vue）**不宜**与 JNI/native 强耦在同一 Maven 树内混建 | +| **构建** | `java/` Maven 多模块；`native/` CMake 动态库 | CI **双轨**：Java 与 Native 可并行；平台后端/前端 **独立仓库或独立根级目录** 时再挂接新 workflow | +| **文档** | `docs/` 已覆盖比特规则、Callback、创飞平台 BPM、模块、权限 | 文档继续集中在 `docs/`；**工程边界**以本文 + `engineering/` 为 **单一事实来源（SSOT）** | +| **缺口** | 根目录无 README；平台 Webhook、管理端未在代码层体现 | 用 `**engineering/planned/`** 占位说明 **推荐独立仓库名与技术栈**；实现阶段按 manifest 开仓 | + + +--- + +## 2. 工作区逻辑分层（C4-L1） + +```mermaid +flowchart TB + subgraph WS["本工作区 craftlabs-authorization-sdk"] + S[SDK Java API] + N[Native craftlabs_auth_bitanswer] + SCH[schemas/ craftlabs-auth-config] + EX[examples/] + DOC[docs/] + end + + subgraph EXT["规划中的独立工程（见 engineering/planned）"] + WH[license-webhook-ingress] + API[delivery-platform-api] + UI[delivery-platform-ui] + end + + BA[比特安索云/控制台] + CLI[现场客户端产品] + + N --> S + S --> CLI + SCH --> CLI + WH -->|POST Callback| BA + API -->|读写字段| WH + UI --> API + DOC -.->|约束| SCH +``` + + + +**原则**：**运行时依赖**从平台 API → Webhook → 比特 为一条链；**客户端**仅依赖 **Maven 发布的 SDK 工件** + **JSON 配置**（校验用 Schema），不依赖平台 UI。 + +--- + +## 3. 物理目录与职责（当前实现） + + +| 路径 | 工程类型 | 职责 | 构建命令（摘要） | +| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| `**java/`** | Maven `pom` 聚合 | `craftlabs-auth-core`（配置模型/校验/桥接）、`craftlabs-auth-bitanswer`、`craftlabs-auth-selfhosted`、`craftlabs-auth-tests` | `mvn -f java/pom.xml verify` | +| `**native/**` | CMake | `libcraftlabs_auth_bitanswer`、JNI、自研 HTTP 占位 | 见 `native/build` 或项目 README | +| `**schemas/**` | JSON Schema | `craftlabs-auth-config` 契约，与 `AuthConfigs` 对齐 | 无编译；CI 可 `ajv`/脚本校验 | +| `**examples/**` | 样例 | `config/*.json`、`java`/`python` 烟测 | 随测试引用 | +| `**docs/**` | 文档 | 产品、比特对接、工程架构 | 无构建 | +| `**engineering/**` | **工程元数据** | manifest、**planned** 占位、边界说明 | 无构建 | + + +**禁止**：在未做迁移方案前，将 **Spring Boot 应用** 塞进 `java/` 下与 `craftlabs-auth-`* 并列 —— 会导致发布周期、依赖（Boot vs 库消费者）冲突。 +**平台端正确做法**：在 **独立仓库** 内 **多模块开发**，由 **唯一 `bootstrap` 模块** 执行 `spring-boot-maven-plugin` **repackage**，对外只发布 **一枚 Fat JAR**（见 **§5.3**）。 + +--- + +## 4. Maven 模块边界（SDK 内部） + +``` +craftlabs-auth-parent +├── craftlabs-auth-core # 无第三方授权运行时；配置、NativeBridge 接口 +├── craftlabs-auth-bitanswer # System.loadLibrary + BitAnswerProvider +├── craftlabs-auth-selfhosted +└── craftlabs-auth-tests # 集成/配置测试 +``` + +- **对外发布坐标**：以 `cn.craftlabs:craftlabs-auth-*` 为准；版本与 **changelog** 在发布流水线维护。 +- **平台后端**若需读取同一配置模型：优先 **复制 DTO + 共用 Schema**，或将来抽取 `**craftlabs-auth-config-model` 极小 jar**（另案）；**禁止**在平台可执行 JAR 中引入 `craftlabs-auth-bitanswer`（会拉起 JNI/native 期望，属边界错误）。 + +--- + +## 5. 客户端 SDK 与平台端：深入评估与防混淆 + +### 5.1 二者不可混为一谈 + + +| 维度 | **客户端 SDK**（本仓库 `java/` + `native/`） | **平台端后端**（`delivery-platform-api` 等独立工程） | +| --------------- | ----------------------------------------- | ---------------------------------------------------------------- | +| **运行位置** | 客户现场业务进程 / 边缘 AI 设备 | 创飞机房 / 云（VPC） | +| **核心职责** | `Bit_Login`、特征项、本地/云授权运行时 | 合同、交付、SN 台账、Callback 处置、RBAC、报表 | +| **典型依赖** | BitAnswer 官方 native + `BitAnswerProvider` | Spring Boot、DB、MQ；**无** BitAnswer 客户端 native | +| **交付形态** | 多枚 **薄 JAR** + 各 OS **动态库**（与 JAR 同版本） | **单枚可执行 Fat JAR**（或容器内同等物）**每个可部署服务一枚** | +| **Spring Boot** | **不使用**（库代码，避免与宿主应用 Boot 版本冲突） | **使用**（4.0. 线），仅 **启动模块** 打 Fat JAR | +| **配置** | `craftlabs-auth-config` JSON + Schema | 平台自有 `application.yml` + **PostgreSQL 15** 数据源；ORM 为 **MyBatis-Plus**；JSON Schema 仅用于 **校验导出的客户端配置**（若实现） | + + +**硬规则**：平台进程 **不得** `System.loadLibrary("craftlabs_auth_bitanswer")`；不得在服务端 classpath 引入 `**craftlabs-auth-bitanswer`** 模块（除非未来出现「纯 Java、无 native」的只读适配且经架构评审——当前 **不存在**）。 + +### 5.2 命名与仓库层面的识别 + +- **SDK 坐标**：`cn.craftlabs:craftlabs-auth-*`（artifact 前缀固定，文档与 BOM 中一眼可辨）。 +- **平台坐标**：建议 `cn.craftlabs.platform:*` 或 `cn.craftlabs.delivery:*`（**禁止**复用 `craftlabs-auth-*` 作为应用模块 artifactId）。 +- **CI 流水线**：SDK 与 **platform-*** 使用 **不同 job**，产物上传 **不同仓库路径**（Maven `.../sdk/` vs `.../platform/`）。 + +### 5.3 单 JAR 部署 vs 分模块开发（平台 / Webhook） + +**诉求**：运维只下发 **一个 `app.jar`**（或镜像内 `java -jar app.jar`）；研发仍按 **领域拆分模块**，边界清晰、编译快、测试可隔离。 + +**推荐 Maven 形态**（每个 **独立可部署后端** 各自一套父 POM，勿与 SDK 父 POM 合并）： + +``` +delivery-platform/ # 或 license-webhook 同理 +├── pom.xml # packaging=pom，dependencyManagement +├── platform-domain/ # 实体、领域服务接口、无 Spring Web +├── platform-application-service/ # 用例、事务边界、调用 domain +├── platform-adapters-web/ # REST Controller、DTO 映射 +├── platform-adapters-persistence/ # MyBatis-Plus Mapper / XML（PostgreSQL 15） +└── platform-bootstrap/ # 唯一含 main + spring-boot-maven-plugin + └── src/main/java/.../Application.java +``` + +- **仅 `platform-bootstrap`** 配置 `spring-boot-maven-plugin` 的 `**repackage**`（或 `executable`），依赖其余模块为 **普通 jar**，打进 **Fat JAR / Executable JAR**。 +- `mvn -pl platform-bootstrap -am package` → 产出 `platform-bootstrap/target/*.jar` **一枚**，即部署单元。 +- **开发体验**：IDE 打开 **聚合工程**，多模块跳转、分模块单测；**禁止**在多个模块上重复声明 `repackage`（否则出现多枚「可执行」JAR 或依赖错乱）。 + +**可选变体**： + +- **分层 jar（Spring Boot 2.3+）**：`layertools` 优化镜像层 —— 仍对应 **单次构建的一条启动入口**。 +- **Webhook 与 Core API 分开发布**：两个 Maven 工程各产 **一枚** Fat JAR（`webhook-bootstrap.jar`、`platform-bootstrap.jar`），比强行塞进一个进程更符合 **扩容与故障隔离**；若强制单进程，可用 **同一 `bootstrap` 模块多 profile**（一般 **不推荐**，耦合过高）。 + +### 5.4 SDK 侧构建（对照：不是 Fat JAR） + +- `craftlabs-auth-core` / `bitanswer` / `selfhosted` 均为 **library jar**，**不打** `spring-boot-maven-plugin`。 +- 客户端应用（客户自有 Spring Boot 或其它）自行打包 Fat JAR，**声明依赖** `craftlabs-auth-bitanswer` + 携带 **匹配版本 native**。 +- **平台 Fat JAR** 与 **客户应用 Fat JAR** 是 **两条完全不同的发布线**，不得在平台 POM 里 `dependency` 整条 SDK 父工程。 + +### 5.5 评审检查（单 JAR + 分模块） + +- 全仓库是否 **只有一个** 模块声明 `spring-boot-maven-plugin` 的 `repackage`（针对该可部署应用）？ +- `mvn dependency:tree -pl platform-bootstrap` 中是否 **无** `craftlabs-auth-bitanswer`？ +- 部署文档是否写清：启动类 FQCN、`java -jar` 与 JVM 参数、**与 SDK 版本无耦合**？ + +--- + +## 6. Native 边界 + +- **产出物**：各平台 `.so` / `.dylib` / `.dll` + 头文件。 +- **与 Java 契约**：`NativeBridge` 与 `jni_bridge.cpp` 必须 **同版本发布**。 +- **平台服务**：**不**链接本 native 库；仅 **现场 AI/业务进程** 链接。 + +--- + +## 7. 规划工程划分（推荐独立 Git 仓库） + +下列目录在 `**engineering/planned/`** 中以 README 描述，**默认新开仓库**（名称可调整）： + + +| 规划 ID | 建议仓库名 | 技术栈（与产品文档对齐） | 与本工作区关系 | +| ------------------------- | -------------------------------- | ---------------------------------------- | ------------------------------------------------- | +| `license-webhook-ingress` | `craftlabs-license-webhook`（示例） | Spring Boot **4.0.**，仅 Ingress + 验签 + MQ | **消费**比特 Callback；**不**依赖 SDK native | +| `delivery-platform-api` | `craftlabs-delivery-platform` | Spring Boot **4.0.**，领域 API、**PostgreSQL 15**、**MyBatis-Plus** | 依赖 **schemas** 可通过 git submodule 或发布 **schema 包** | +| `delivery-platform-ui` | `craftlabs-delivery-platform-ui` | Vue 3 + Vite | 调用 `delivery-platform-api` | + + +**可选 Monorepo**：若公司策略要求单仓，可采用 **Bazel / Gradle composite / 多根 `pom` 父子不包含 SDK** 的目录隔离，例如： + +``` +mega-repo/ + craftlabs-authorization-sdk/ # 本仓库 subtree 或 submodule + delivery-platform/ + license-webhook/ +``` + +迁移成本高于 **三仓 + 契约版本化**；**默认推荐三仓**。 + +--- + +## 8. CI/CD 划分建议 + + +| 组件 | 触发路径 | 产物 | +| ----------- | ------------ | ------------------------------------- | +| SDK Java | `java/`** | Maven deploy（私服/Central） | +| SDK Native | `native/**` | 各 OS 工件 + 与 Java **同版本 tag** | +| Schema | `schemas/`** | 可与 SDK 同步发 **minor**；breaking 走 major | +| 平台与 Webhook | **独立仓库**（或本仓 `services/`） | **Fat JAR** + 部署说明（`systemd`/脚本/`docker run`）；**不强制** 容器与 K8s，规模化后再考虑镜像与编排 | + + +--- + +## 9. 数据与配置契约 + +- **客户端**：`craftlabs-auth-config.schema.json` + 环境 `bitanswer.url` 等（见 `examples/config`）。 +- **平台**：存储 SN、合同、Callback 等 —— **领域模型独立于 SDK**；仅 **映射表** 与比特特征 ID 与 M6 文档一致。 +- **Webhook Payload**：以比特官方规则文档为准；平台侧 **反序列化 DTO** 在 `license-webhook` 仓维护。 + +### 9.1 平台数据栈（架构锁定） + +| 项 | 约定 | +|----|------| +| **数据库** | **PostgreSQL 15**（生产、验收、联调基准版本；镜像 `postgres:15`） | +| **ORM** | **MyBatis-Plus**（Spring Boot 3 使用 `mybatis-plus-spring-boot3-starter`；升级 Spring Boot 4 时改用官方 `mybatis-plus-spring-boot4-starter` 并回归） | +| **迁移** | Flyway 或 Liquibase（后续迭代引入；与表结构变更门禁对齐） | +| **单测** | 可不启真实 PG：H2 `MODE=PostgreSQL` 或 Testcontainers `postgres:15`，以团队门禁为准 | + +实现参考：`services/delivery-platform-api` 已接入 MyBatis-Plus + JDBC；本地数据库见 `services/docker-compose.yml`。 + +--- + +## 10. 安全边界 + +> **展开**：威胁面、分组件控制、信任边界图与评审清单见 [SYSTEM_ARCHITECTURE.md §9](./SYSTEM_ARCHITECTURE.md)。 + +### 10.1 密钥与凭据 + +- **Webhook**：`x-bitanswer-token` / 与比特约定的共享密钥 **仅** 在 **部署机环境变量** 或 **权限受限的本地配置文件**（如 `chmod 600`）；**禁止** 写入 Git、镜像层与公开 CI 日志。 +- **平台数据库**：JDBC URL、用户名、密码 **仅** 注入运行时；`docker-compose` 与示例 **不得** 作为生产凭据模板。 +- **管理端**：演示账号（如 `dev`/`admin`）**禁止** 用于生产；生产至少 **强口令**。团队尚小时 **不强制** 上云 KMS / Vault；规模与合规要求上来后再演进。 +- **SDK 发布防篡改**：以 [SYSTEM_ARCHITECTURE §9.8](./SYSTEM_ARCHITECTURE.md) 为准（官方渠道、SHA-256、建议 GPG、同 tag 发布 JAR+Native）。 + +### 10.2 运行时与数据面 + +- **传输**：对外 **仅 HTTPS**（Webhook、管理 API、浏览器）；比特 Callback 终端 **不接明文 HTTP**（除本机健康检查等受控例外）。 +- **SDK**：配置 JSON **不落** 平台库表作为默认设计；**禁止** 在 `examples/` 与文档示例中放置真实 `bitanswer.url` 密钥或生产 SN。 +- **服务端 classpath**：**禁止** `craftlabs-auth-bitanswer` 与 `System.loadLibrary` —— 避免将 **客户端攻击面** 引入机房。 +- **日志与排障**：Callback 正文、Authorization、数据库 URL **默认脱敏或不打**；生产日志外送需合规评估。 + +### 10.3 授权与访问控制 + +- 管理 API：**认证（谁）** 与 **鉴权（能否操作资源）** 分层；与 **M11** 角色矩阵一致，防范 **越权（IDOR）**。 +- Webhook：**认证先于重逻辑**；**幂等** 防重放污染；**Body 大小限制** 防 DoS。 + +### 10.4 供应链与构建 + +- Maven/npm **锁定版本**；力所能及时做 **依赖漏洞扫描**（SCA）。 +- **SDK 对外发布**：每个版本附带 **SHA-256 清单**，**强烈建议** **GPG 签名**（`maven-gpg-plugin` 或 GitHub signed releases）；详见 [SYSTEM_ARCHITECTURE §9.8](./SYSTEM_ARCHITECTURE.md)。 + +--- + +## 11. 演进检查清单（架构评审用） + +- 新代码是否落在正确 **仓库/目录**（SDK vs 平台 vs Webhook）？ +- Schema 变更是否 **双向** 更新 Java `AuthConfigs` + 文档？ +- Native 与 Java **是否同 tag 发布**？ +- 平台是否 **误引** `craftlabs-auth-bitanswer` 到服务端 classpath？ +- 平台构建是否 **仅 bootstrap 模块** 产出 Fat JAR，且无重复 `repackage`？ +- **安全**：Webhook 生产是否 **启用** 共享密钥/签名？Actuator 敏感端点是否 **已收敛**？新接口是否 **默认拒否** 并完成 **鉴权**？日志是否 **无** 明文 Token/Callback？ +- **安全**：[SYSTEM_ARCHITECTURE §9.7](./SYSTEM_ARCHITECTURE.md) 评审项是否逐项可追溯？ +- **SDK 发布**：[SYSTEM_ARCHITECTURE §9.8](./SYSTEM_ARCHITECTURE.md) 是否落实 **官方渠道 + 校验和（+ 签名）+ JAR/Native 同 tag**？ + +--- + +## 12. 修订记录 + + +| 日期 | 说明 | +| ---------- | ------------------------------------------------------------------------------------------- | +| 2026-04-06 | 初版：工作区走查、目录边界、规划仓库与 CI 划分；落地 `engineering/` manifest 与 `planned/`* 占位。 | +| 2026-04-06 | 增补：**§5 客户端 SDK vs 平台端** 防混淆表；**多模块开发 + 单 Fat JAR** 的 Maven 模块划分与 `repackage` 约束；CI 坐标命名建议。 | +| 2026-04-06 | 关联：[PARALLEL_ITERATION_INDEX.md](./PARALLEL_ITERATION_INDEX.md) 与 `tracks/01–03` 三轨并行执行包。 | +| 2026-04-06 | **§9.1** 锁定平台 **PostgreSQL 15** + **MyBatis-Plus**；`services` 工程对齐依赖与本地 `docker-compose`。 | +| 2026-04-06 | 新增汇总文档 [SYSTEM_ARCHITECTURE.md](./SYSTEM_ARCHITECTURE.md)（系统架构图 + 全量组件清单）。 | +| 2026-04-06 | **§10** 安全边界扩写（密钥、传输、SDK、鉴权、供应链）；**§11** 增补安全评审项；与安全专章 [SYSTEM_ARCHITECTURE §9](./SYSTEM_ARCHITECTURE.md) 交叉引用。 | +| 2026-04-06 | **小团队假设**：凭据以宿主机环境变量/受限文件为主，**不强制** K8s/KMS；**§10.1/10.4** 与 **§11** 对齐 **SDK §9.8** 发布完整性。 | +| 2026-04-06 | **§8** CI/CD 表：平台产物以 **Fat JAR + 部署说明** 为主，**不强制** K8s。 | + + diff --git a/docs/engineering/tracks/01-backend-platform-webhook.md b/docs/engineering/tracks/01-backend-platform-webhook.md new file mode 100644 index 0000000..f7e4694 --- /dev/null +++ b/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 对齐。 | diff --git a/docs/engineering/tracks/02-frontend-platform-ui.md b/docs/engineering/tracks/02-frontend-platform-ui.md new file mode 100644 index 0000000..caca39b --- /dev/null +++ b/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 + `