mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
huangping
76ff98db87
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
392 lines
27 KiB
Markdown
392 lines
27 KiB
Markdown
# 广州创飞人工智能技术有限公司 — 与比特安索对接：平台与交付物能力评估
|
||
|
||
> **平台定义**：**广州创飞人工智能技术有限公司客户商务与交付管理平台** —— 收口 **客户与项目、合同、交付产品、具体授权（含比特安索集成）** 等功能模块，支撑规模化商务履约与许可运营。
|
||
> **目的**：在 [回调与地址走查](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 等）同代演进说明。 |
|