mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
huangping
b2968dc327
Updated all module status columns in product modules doc to reflect actual code state. Removed duplicate @Bean import in SecurityConfig. Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
533 lines
42 KiB
Markdown
533 lines
42 KiB
Markdown
# 客户商务与交付管理平台 — 功能模块划分与功能点（产品视角）
|
||
|
||
> **平台全称**：广州创飞人工智能技术有限公司客户商务与交付管理平台。
|
||
> **文档性质**：产品经理视角的 **模块划分** 与 **功能点清单**，用于需求评审、版本切片与验收对齐。
|
||
> **关联文档**：[平台与比特对接总览](chuangfei-bitanswer-integration-platform.md)（定位、架构、分阶段路线） · [**业务流程与版本排期**](chuangfei-platform-bpm-and-roadmap.md)（BPM、迭代计划） · [工作区工程划分](engineering/WORKSPACE_ENGINEERING_LAYOUT.md)。
|
||
> **优先级约定**：**P0** = MVP 必含；**P1** = 增强运营效率；**P2** = 治理与规模化。同一功能可在多期迭代交付，表中标注为「首期目标优先级」。
|
||
> **实现状态约定**：**✅** = 已实现（I1～I9 迭代交付）；**◐** = 部分实现（缺字段或功能不完整）；**○** = 未实现（规划中）；**—** = 不适用（依赖前置模块）。状态反映截至 2026-05-25 的实现情况。
|
||
|
||
---
|
||
|
||
## 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 | ◐ 部分实现 — 仅 name + credit_code，缺行业/地址/开票信息 |
|
||
| M1-F02 | 客户列表与检索 | 多条件筛选、分页、关键字搜索 | P0 | ✅ |
|
||
| M1-F03 | 客户详情聚合视图 | 关联项目数、在履约合同数、在途 SN 数等摘要（只读统计） | P0 | ✅ — 后端 `/summary` + 前端详情页摘要卡片已实现 |
|
||
| M1-F04 | 项目创建/编辑 | 项目名称、所属客户、阶段、计划起止、项目经理 | P0 | ◐ 部分实现 — 仅 name + customer_id + phase，缺计划起止、项目经理 |
|
||
| M1-F05 | 项目列表与筛选 | 按客户、阶段、时间筛选 | P0 | ✅ |
|
||
| M1-F06 | 项目干系人 | 客户侧联系人、内部负责人、角色标签 | P0 | ◐ — 后端 CRUD 已实现，前端 UI 待补 |
|
||
| M1-F07 | 客户/项目冻结与解冻 | 禁止新业务挂载或仅允许只读（规则可配置） | P1 | ◐ — 后端 PATCH 端点已实现，前端 UI 待补 |
|
||
| M1-F08 | 客户合并与去重 | 疑似重复客户识别、合并流程与审计 | P2 | ○ |
|
||
| M1-F09 | 与外部 CRM 主数据同步 | 以外部 ID 关联、增量同步状态展示（不替代 CRM 全能力） | P2 | ○ |
|
||
|
||
|
||
---
|
||
|
||
## 3. M2 合同与履约行
|
||
|
||
**定位**：合同是「卖什么」的权威来源之一；履约行/合同行是 SN 与交付的锚点。
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------ | --------------- | ------------------------------- | --- | --- |
|
||
| M2-F01 | 合同登记与编辑 | 合同编号、客户、关联项目、签订日、生效日、终止条件 | P0 | ✅ |
|
||
| M2-F02 | 合同状态机 | 草稿、待生效、生效、变更中、终止/到期等；非法跳转拦截 | P0 | ✅ 状态机含 DRAFT→PENDING_EFFECTIVE→EFFECTIVE→CHANGING→TERMINATED |
|
||
| M2-F03 | 合同标的摘要 | 产品/模块/数量/期限/席位等业务口径展示（可与行项汇总一致） | P0 | ✅ |
|
||
| M2-F04 | 合同行项（履约行） | 多行：SKU 或产品包、数量、单价（可选）、交付与授权口径 | P0 | ✅ |
|
||
| M2-F05 | 合同附件 | 上传扫描件/电子签输出（存储与权限受控） | P1 | ◐ — 后端 POST 端点已实现，前端上传 UI 待补 |
|
||
| M2-F06 | 合同与订单关联 | 外部订单号、内部订单记录 ID（若存在订单系统） | P1 | ○ |
|
||
| M2-F07 | 合同变更与版本 | 变更单、版本号、影响授权差异提示（与 M4 联动） | P1 | ◐ — 后端 changes/complete 端点已实现，前端 UI 待补 |
|
||
| 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 | ✅ 状态含 PENDING→DELIVERED→CANCELLED |
|
||
| M3-F05 | 交付完成确认 | 责任人、完成时间、可选客户签收记录 | P0 | ✅ |
|
||
| M3-F06 | 现场环境信息 | 部署地址、网络要求、联系人（敏感字段权限控制） | P1 | ○ |
|
||
| M3-F07 | 交付与 SN 发放门禁 | 规则：仅「已交付」合同范围可生成/绑定 SN（可配置为强/弱） | P1 | ◐ — 后端 deliveryGateEnabled 参数+闸门检查已实现，前端 SystemParamsView 已对接后端 API |
|
||
| M3-F08 | 交付模板 | 按产品线预置交付清单模板 | P2 | ○ |
|
||
|
||
|
||
---
|
||
|
||
## 5. M4 授权与许可运营
|
||
|
||
**定位**：SN 与激活事实的台账中心；不替代比特控制台，但与比特状态 **摘要对齐、可追溯**。
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------ | -------------- | ---------------------------- | --- | --- |
|
||
| M4-F01 | SN 手工录入/导入 | 单条新增、批量导入（模板校验、重复提示） | P0 | ◐ 手工录入已实现，批量导入 UI 待补（后端 POST /batch-import 已就绪） |
|
||
| M4-F02 | SN 与合同/项目/客户绑定 | 必选关联路径之一（合同行或项目），禁止裸 SN 或仅警告 | P0 | ✅ |
|
||
| M4-F03 | SN 生命周期状态 | 未发放、已发放、已激活、已冻结、已回收、异常等 | P0 | ✅ 状态含 REGISTERED→ISSUED→ACTIVATED→SUSPENDED→REVOKED |
|
||
| M4-F04 | SN 详情页 | 展示绑定关系、发放记录、激活时间、最近事件摘要 | P0 | ✅ |
|
||
| M4-F05 | 激活结果回写 | 人工录入或接口同步：成功/失败及原因码分类 | P0 | ◐ 支持手工状态更新，缺原因码分类 |
|
||
| M4-F06 | 比特控制台状态摘要 | 同一 SN 的关键字段摘要或控制台链接（只读，权限控制） | **P1**（原 P0，因依赖比特控制台对接未完成降级） | ○ |
|
||
| M4-F07 | 批量 SN 操作 | 批量绑定、批量状态变更（审批可选） | P1 | ◐ — 后端 batch-import 已实现，前端批量操作 UI 待补 |
|
||
| M4-F08 | 授权需求单 | 由合同/交付生成的「待发放 SN」清单，供 Ops 执行 | P1 | ○ |
|
||
| M4-F09 | 试用/正式/续期标签 | 与业务口径一致的标签，便于筛选与报表 | P1 | ○ |
|
||
| M4-F10 | SN 与设备关联视图 | 展示绑定 `mid` 列表与历史（依赖 M7） | P1 | — 依赖 M7 |
|
||
| M4-F11 | 授权策略生效视图 | 展示当前映射版本、环境（与 M6 联动） | P2 | ○ |
|
||
|
||
|
||
---
|
||
|
||
## 6. M5 许可事件（Callback）运营
|
||
|
||
**定位**：承接比特规则 **HTTPS Callback**，保证 **不断链、可关联、可处置**。
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------ | ----------- | -------------------------------------------------------------------------------------------------------------------- | --- | --- |
|
||
| M5-F01 | 事件收件箱列表 | 按时间、事件类型、`sn`、处理状态筛选 | P0 | ✅ 支持多维度筛选 |
|
||
| M5-F02 | 事件详情 | 展示解析后字段 + 脱敏后的原始 payload；关联 SN/合同 | P0 | ✅ 含 payload 脱敏预览 |
|
||
| M5-F03 | 处理状态 | 待处理、已处理、失败、忽略；处理人与时间 | P0 | ✅ 状态含 PENDING→PROCESSED/FAILED/IGNORED |
|
||
| M5-F04 | 关联解析失败兜底 | 无法关联主数据时保留事件并支持人工挂接 | P0 | ✅ 支持人工挂接 SN/项目/合同 |
|
||
| M5-F05 | 事件类型字典 | `sn:pre_activate`、`sn:post_activate`、`device:pre_activate`、`device:post_activate`、`yunbaobao:session_logout` 等展示名与说明 | P0 | ✅ |
|
||
| M5-F06 | 失败原因标注 | Ops 可选分类，便于报表 | P1 | ✅ — 前端失败原因下拉 + 后端 DTO 已实现 |
|
||
| M5-F07 | 批量重处理/重试入口 | 在业务允许范围内触发补偿（与后端幂等策略一致） | P1 | ✅ 单条 + 批量重试均已实现（I8 单条 + I10 批量端点） |
|
||
| M5-F08 | 死信与积压监控视图 | 队列深度、最久未处理 TOP（与可观测联动） | P1 | ◐ — 后端 GET /stats/backlog + 前端积压统计卡片已实现 |
|
||
| M5-F09 | 事件驱动待办 | 自动生成待办卡片（与 M8 联动） | P1 | — 依赖 M8 |
|
||
| M5-F10 | 模拟投递（仅测试环境） | 联调验收工具 | P2 | ◐ — 后端 POST /simulate 已实现，前端 UI 待补 |
|
||
|
||
|
||
---
|
||
|
||
## 7. M6 授权集成与配置
|
||
|
||
**定位**：把「产品线—比特产品/模版/业务/特征 ID—环境 URL」管起来，支撑客户端 JSON 与联调。
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------ | ----------------- | -------------------------------------------------------------- | --- | --- |
|
||
| M6-F01 | 产品线定义 | 产品线编码、名称、说明 | P0 | ✅ |
|
||
| M6-F02 | 环境维度 | 开发/测试/预发/生产及对应 `bitanswer.url` 登记 | P0 | ✅ 含 seed 数据（dev/prod） |
|
||
| M6-F03 | 比特侧 ID 映射 | 产品、模版、业务 ID 与产品线+环境绑定（与控制台一致） | P1 | ✅ — 前后端均已实现（IntegrationIdMappingView） |
|
||
| M6-F04 | 逻辑功能键 ↔ 特征项映射 | 对齐 `craftlabs-auth-config` 中 `features.*.bitanswerFeatureId` 等 | P1 | ✅ — 前后端均已实现（IntegrationFeatureMappingView） |
|
||
| M6-F05 | 授权 JSON 模板管理 | 模板版本、变更说明、与 Schema 校验结果（可接 CI） | P1 | ◐ — 前后端 CRUD 已实现（IntegrationJsonTemplateView），Schema 校验未关联 UI |
|
||
| 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 | ◐ — 后端 swap-request 端点已实现，审批流待补 |
|
||
| 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 | ◐ — 通知通道配置 UI 已上线，实际发送逻辑未接入 |
|
||
| M8-F04 | 通知模板 | 事件类型 → 模板变量 | P2 | ○ |
|
||
| M8-F05 | 静默规则 | 重复事件聚合、防骚扰 | P2 | ○ |
|
||
|
||
|
||
---
|
||
|
||
## 10. M9 报表与对账
|
||
|
||
**定位**：给管理层与 Ops **履约 vs 授权** 的一致性视图。
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------ | ---------------- | ------------------- | --- | --- |
|
||
| M9-F01 | 合同标的 vs 已发 SN 视图 | 按合同/行项汇总应发、实发 | P1 | ◐ — ContractSnReportView 已上线，数据维度待确认 |
|
||
| M9-F02 | 已发 vs 已激活视图 | 未激活占比、超期未激活列表 | P1 | ○ |
|
||
| M9-F03 | Callback 统计 | 按类型、状态、时间段的成功率与耗时分布 | P1 | ◐ — CallbackStatsView 已上线 |
|
||
| M9-F04 | 导出 CSV/Excel | 权限与脱敏策略受控 | P1 | ◐ — 后端 GET /reports/export 已存在，前端导出按钮待补 |
|
||
| M9-F05 | 项目健康度看板 | 多项目并行时的红黄绿（规则可配置） | P2 | ◐ — ProjectHealthView 已上线，红黄绿规则可配置性待确认 |
|
||
| M9-F06 | 订阅报表 | 定期邮件推送 | P2 | ◐ — SubscriptionReportView 已上线，后端推送逻辑待确认 |
|
||
|
||
|
||
---
|
||
|
||
## 11. M10 审计与合规
|
||
|
||
**定位**：满足内审与客户抽样举证，**关键操作不可抵赖**。
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------- | -------- | --------------------------- | --- | --- |
|
||
| M10-F01 | 关键字段变更日志 | 客户、合同、SN 绑定、状态变更：旧值/新值/人/时间 | P0 | ✅ |
|
||
| M10-F02 | 审计检索 | 按对象 ID、用户、时间范围查询 | P1 | ◐ — AuditSearchView 已上线，筛选维度待确认 |
|
||
| M10-F03 | 导出审计包 | 范围可选（项目/合同/时间窗），水印与权限 | P2 | ○ |
|
||
| M10-F04 | 留存策略配置 | 与法务对齐的保留周期说明（技术实现另见架构） | P2 | ◐ — AuditRetentionView 已上线，配置生效性待确认 |
|
||
|
||
|
||
---
|
||
|
||
## 12. M11 身份、访问与平台管理
|
||
|
||
**定位**：**账户如何安全进入与退出系统**；进入后**能看能改什么**由角色与数据范围控制；以下为 **认证与会话**、**授权模型落地**、**平台配置** 三部分。
|
||
|
||
### 12.1 账户登录、登出与会话
|
||
|
||
|
||
| 功能点 ID | 功能点名称 | 说明 | 优先级 | 实现状态 |
|
||
| ------- | ------------- | ----------------------------------------------- | --- | --- |
|
||
| M11-F01 | 登录页 | 账号（工号/邮箱/登录名可配置一种为主）+ 密码登录入口；错误提示不暴露用户是否存在（防枚举） | P0 | ✅ |
|
||
| M11-F02 | 登出 | 主动登出：清除服务端会话或作废令牌、前端清理本地凭证 | P0 | ✅ |
|
||
| M11-F03 | 登录态保持与超时 | **空闲超时**自动登出并提示；可选「记住本次会话」策略（与安全基线平衡，默认保守） | P0 | ◐ — 前端 idleTimer 已实现（从 systemParams 读取 sessionTimeoutMinutes），后端会话管理待补 |
|
||
| M11-F04 | 未登录访问拦截 | 访问受保护路由时跳转登录页，登录成功后回跳原目标 URL（或安全白名单内路径） | P0 | ✅ |
|
||
| M11-F05 | 登录失败与锁定 | 连续失败次数阈值触发**临时锁定**或验证码；解锁策略（时长/管理员解锁）可配置 | P0 | ○ |
|
||
| M11-F06 | 登录/登出审计 | 记录成功/失败登出、时间、来源 IP、客户端类型（脱敏与留存策略另定） | P0 | ✅ |
|
||
| M11-F07 | 密码修改 | 已登录用户修改本人密码；校验旧密码强度与新密码策略 | P0 | ✅ — Profile 页改密弹窗已实现 |
|
||
| M11-F08 | 密码重置 | 管理员重置密码或邮件/短信重置链接（通道选一种即可）；重置后可选强制首次登录改密 | P1 | ◐ — 后端 `POST /admin/reset-password` 已实现（非空操作），前端管理 UI 待补 |
|
||
| 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 | ◐ — 后端 CRUD + 前端管理页面已实现（`/admin/users`），SSO 同步未做 |
|
||
| M11-F15 | 角色定义与分配 | 预置角色（见 §13）+ 可选自定义角色；用户可挂多角色 | P0 | ◐ 仅实现 SYS_ADMIN/DEVELOPER/OPS 三角色，产品定义 10+ 角色待补齐 |
|
||
| M11-F16 | 功能权限（RBAC） | 菜单、按钮、API 操作与 **§13 权限码** 对齐；支持按环境预览「某用户看见什么」 | P0 | ◐ 路由级 RBAC 已实现，按钮级权限码未落地 |
|
||
| M11-F17 | 数据范围（Data Scope） | 按事业部/区域/客户组限制列表可见行（与 M11-F18 二选一或组合） | P2 | ○ |
|
||
| M11-F18 | 数据属主/团队 | 如「仅本人负责客户」「本团队项目」（字段：负责人、协作人） | P1 | ○ |
|
||
| M11-F19 | 业务字典 | 合同类型、交付类型、SN 异常原因分类等 | P0 | ✅ |
|
||
| M11-F20 | 系统参数 | 「孤儿 SN」强校验、交付门禁、会话超时分钟数、密码策略等 | P1 | ✅ — SystemParamController + platform_system_param 表 + 前端对接后端 API 已实现 |
|
||
| 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` | 系统管理员 | 平台配置与账号治理 | 用户/角色/字典/系统参数；**不默认拥有业务全量数据**时可配置为「仅管理」 | ✅ |
|
||
| `DEVELOPER` | 研发/开发人员 | 技术研发与调试 | M1～M4/M6 业务 CRUD + 集成配置只读；**无** Callback 处置权限 | ✅ *注：产品定义中无此角色，为 MVP 简化引入，I10 起废弃，由 SALES 替代* |
|
||
| `OPS` | 运营人员 | 许可运营 | Callback 处置 + 集成配置只读；**无** 客户/项目/合同/交付/SN 写权限 | ✅ *注：产品定义中无此角色，为 MVP 简化引入，I10 起废弃，由 LICENSE_OPS 替代* |
|
||
| `SECURITY_ADMIN` | 安全管理员（可选） | 账号与登录安全 | 锁定策略、强制下线、审计检索；与 `SYS_ADMIN` 分离（职责分离，P2） | ○ |
|
||
| `SALES` | 商务经理 | 客户与签约侧 | 客户、项目、合同维护；发起交付与授权需求 | ✅ I10 已实现—替代原 DEVELOPER 角色 |
|
||
| `ORDER_SUPPORT` | 订单/运营支持 | 履约对齐 | 合同行与 SKU、订单号关联；协助商务核对「卖授一致」 | ○ *产品定义角色，仍在规划* |
|
||
| `DELIVERY` | 交付工程师 | 现场交付 | 交付批次与清单、环境信息、交付完成确认 | ✅ I10 已实现（售前演示账号 delivery/delivery） |
|
||
| `LICENSE_OPS` | 授权运营 | 许可台账与比特协同 | SN 全生命周期、Callback 处置、与控制台操作配合 | ✅ I10 已实现—替代原 OPS 角色 |
|
||
| `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（I1～I9，已完成）**：§12.1 的 F01/F02/F04/F06 + §12.2 的 F14（基础）/F15（简化三角色）/F16（路由级）/F19；§13.2 **实际落地 `SYS_ADMIN` + `DEVELOPER` + `OPS`**（简化角色集，非产品定义全量）；§13.3 矩阵为 **粗粒度模块级**。MVP 未覆盖的 P0 项（如 M1-F03/F06、M11-F03/F05/F07）标记为已知缺口，Mid 阶段补齐。
|
||
- **Mid（I10～I13，待实现）**：M7 设备 + M8 通知/待办 + M9 报表对账 + 补齐 MVP 遗留 P0 + M2/M4/M5/M6 P1 增强项 + SSO/并发会话/强制下线/密码重置 + 废弃 `DEVELOPER`/`OPS`，落地产品定义角色集。
|
||
- **Full（V2.0，规划）**：MFA、`SECURITY_ADMIN`、事业部数据范围、审计导出包、CRM 同步、细粒度互斥策略。
|
||
|
||
---
|
||
|
||
## 14. 按版本包的功能边界（与 P0 / P1 / P2 对齐）
|
||
|
||
|
||
| 版本包 | 状态 | 包含模块与要点 |
|
||
| -------- | --- | ---------- |
|
||
| **MVP（I1～I9）** | ✅ **已完成** | M1/M2/M3/M4 核心功能 + M5 收件箱与处置 + M6 环境/产品线只读 + M10 审计日志 + **M11 JWT 登录/路由守卫/粗粒度三角色/字典**。角色矩阵为 **§13.3 粗粒度（简化三角色）**；自研许可证管理（V6）为额外交付。详见 §16 原型章节。 |
|
||
| **Mid（I10～I13）** | 🕐 **进行中** | MVP + M7 设备 + M8 通知待办 + M9 报表对账 + 补齐 MVP 未覆盖的 P0 项 + M2/M4/M5/M6 P1 增强 + M10-F02 审计检索 + **M11 SSO/并发/强制下线/密码重置/数据属主** + **权限码细拆** + **角色模型对标产品定义集**。 |
|
||
| **Full（V2.0）** | 📋 **规划中** | Mid + M2/M6/M9/M10/M11 的 P2 项 + M1/M8 集成与智能化增强 + **MFA、安全管理员、事业部数据范围、审计导出包、CRM 同步**。 |
|
||
|
||
|
||
---
|
||
|
||
## 15. 修订记录
|
||
|
||
|
||
| 日期 | 说明 |
|
||
| ---------- | ---------------------------------------------------------------------------------- |
|
||
| 2026-04-06 | 初版：产品视角模块划分与功能点表。 |
|
||
| 2026-04-06 | 增补：M11 扩展为身份/访问/平台管理；**登录/登出/会话**功能点；**§13 角色与权限体系**（预置角色、模块矩阵、权限码示例）；版本包与 §14 对齐。 |
|
||
| 2026-05-25 | **全面更新**：所有功能点表增加「实现状态」列，标注 ✅/◐/○；M4-F06 降级至 P1；§13 角色表增加当前实现对照列；§14 版本包反映 I1～I9 完成状态；新增 **§16 原型实现说明**。 |
|
||
|
||
---
|
||
|
||
## 16. 原型实现说明（I1～I9 迭代交付）
|
||
|
||
> 本章记录 **2026-04 至 2026-05（I1～I9）** 已交付原型的具体范围，供产品验收、集成方评估与后续迭代规划使用。原型基于 **三轨并行**（后端双 JAR + 前端 Vue + 客户端 SDK）模式交付。
|
||
|
||
### 16.1 原型定位与范围
|
||
|
||
| 维度 | 说明 |
|
||
|------|------|
|
||
| **迭代范围** | I1（脚手架/M11）→ I9（Webhook 出库状态只读），共 9 个迭代 |
|
||
| **原型目标** | 跑通 BP-01～06、11 主链路：客户→项目→合同→交付→SN→Callback→审计 |
|
||
| **交付形态** | 两枚 Fat JAR（delivery-platform-api :8080 + license-webhook-ingress :8081）+ Vue 3 SPA + Rust cdylib + Java SDK JAR |
|
||
| **部署方式** | Docker Compose（PostgreSQL 15 + 双 JAR + Prometheus/Grafana 可选）或单机 `java -jar` |
|
||
| **覆盖模块** | M1～M6 P0 核心功能 + M10-F01 + M11 基础身份与访问 + 自研许可证管理（V6 额外） |
|
||
|
||
### 16.2 前端原型（delivery-platform-ui）
|
||
|
||
| 页面 | 路由 | 对应模块 | 实现说明 |
|
||
|------|------|---------|---------|
|
||
| 登录页 | `/login` | M11 | JWT Bearer 认证，演示账号 `admin/admin`、`ops/ops` |
|
||
| 首页 | `/` | — | 角色感知的模块快捷链接 + `GET /api/v1/ping` 调试 |
|
||
| 客户管理 | `/customers` | M1 | 列表/搜索/分页/新建/编辑对话框/删除（软删） |
|
||
| 项目管理 | `/projects` | M1 | 列表/按客户筛选/新建/编辑/删除（物理删） |
|
||
| 合同管理 | `/contracts` | M2 | 列表 + 三步创建向导 + 详情（状态机操作、行项管理、审计列表） |
|
||
| 交付管理 | `/deliveries` | M3 | 列表 + 新建向导 + 详情（抬头编辑、行项管理、状态变更） |
|
||
| 许可 SN | `/licenses/sn` | M4 | 列表 + 新建 + 详情（绑定/状态变更） |
|
||
| Callback 收件箱 | `/callbacks` | M5 | 列表（多维筛选）+ 详情（payload 脱敏预览、人工挂接、状态处置、DEAD 重放、出库状态） |
|
||
| 集成环境 | `/integration/environments` | M6 | 只读列表 |
|
||
| 产品线 | `/integration/product-lines` | M6 | 只读列表 |
|
||
| 403/404 | `/403` / `/*` | M11 | 路由级无权限/未找到提示 |
|
||
|
||
**技术栈**：Vue 3 (Composition API) + Vite + Pinia + vue-router + axios + Element Plus。Token 存 `localStorage`（**已知安全缺陷**，Mid 阶段应迁移至 HttpOnly Cookie）。
|
||
|
||
### 16.3 后端 API 原型
|
||
|
||
#### delivery-platform-api（:8080）
|
||
|
||
| Controller | 路由前缀 | 覆盖的模块 | 关键端点 |
|
||
|-----------|---------|-----------|---------|
|
||
| `AuthController` | `POST /api/v1/auth/login` | M11 | 登录（返回 JWT） |
|
||
| `CustomerController` | `/api/v1/customers` | M1 | CRUD + 分页列表 + 软删 |
|
||
| `ProjectController` | `/api/v1/projects` | M1 | CRUD + 分页列表 + 物理删 |
|
||
| `ContractController` | `/api/v1/contracts` | M2 | CRUD + 行项管理 + 状态机 PATCH |
|
||
| `DeliveryBatchController` | `/api/v1/delivery-batches` | M3 | CRUD + 行项管理 + 状态 PATCH |
|
||
| `LicenseSnController` | `/api/v1/license-sns` | M4 | CRUD + 状态 PATCH |
|
||
| `LicenseController` | `/api/v1/licenses` | 自研许可 | License CRUD + 激活 + 过期（V6 额外） |
|
||
| `CallbackInboxController` | `/api/v1/callback-inbox` | M5 | 列表/详情/状态 PATCH/人工挂接/重放 Webhook 出库 |
|
||
| `IntegrationCatalogController` | `/api/v1/integration/*` | M6 | 产品线/环境只读列表与详情 |
|
||
| `PingController` | `/api/v1/ping` | — | 健康探测 |
|
||
| `CallbackInternalController` | `/internal/v1/callback-events` | M5 | Webhook→平台内部投递入口 |
|
||
|
||
**安全**：JWT Bearer（`PLATFORM_JWT_SECRET`）+ 内部共享 Token（`X-Platform-Internal-Token`）+ 角色路由 `/api/v1/auth/login` `/actuator/health` 免认证。
|
||
|
||
#### license-webhook-ingress（:8081）
|
||
|
||
| Controller | 路径 | 职责 |
|
||
|-----------|------|------|
|
||
| `CallbackIngestController` | `POST /webhook/bitanswer/callback` | 比特 Callback 入站：验签（`x-bitanswer-token`）、幂等（`Idempotency-Key` 或 `externalMessageId`）、落收据表、入队投递 |
|
||
| `WebhookPlatformDeliveryOpsController` | `GET …/by-receipt/{receiptId}` | 出库状态只读查询 |
|
||
| `WebhookPlatformDeliveryOpsController` | `POST …/by-receipt/{receiptId}/replay` | DEAD 行重放 |
|
||
|
||
**安全**：`CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` + `X-Webhook-Ops-Token`（I8 起）。
|
||
|
||
### 16.4 Rust 核心库原型（native/craft-core）
|
||
|
||
| 模块 | 文件 | 实现程度 |
|
||
|------|------|---------|
|
||
| **C ABI** | `lib.rs` | ✅ 8 个导出函数：`craft_initialize/activate/check_license/get_license_info/has_feature/release/heartbeat/destroy` |
|
||
| **Provider trait** | `trait_provider.rs` | ✅ 定义 Provider 接口：initialize/activate/check_license/heartbeat/has_feature/release/get_license_info/close |
|
||
| **自研 Provider** | `provider_selfhosted/` | ✅ 完整实现：activate + heartbeat + cache + license + protocol |
|
||
| **加密模块** | `crypto.rs` | ✅ AES-256-GCM 加解密、HKDF 密钥派生、RSA PKCS1v15 签名验证 |
|
||
| **设备指纹** | `device.rs` | ✅ 设备标识生成与校验 |
|
||
| **安全加固** | `security/` | ✅ 反调试（`anti_debug.rs`）、代码混淆（`obfuscation.rs`）、字符串加密（`string_encrypt.rs`）、完整性校验（`integrity.rs`）、动态 API 解析（`dynamic_api.rs`） |
|
||
| **许可管理** | `license.rs` / `activate.rs` / `heartbeat.rs` / `session.rs` / `error.rs` | ✅ 核心许可状态、激活/心跳业务流程、错误码定义 |
|
||
| **公钥嵌入** | `build.rs` | ✅ 构建时嵌入 RSA 公钥 |
|
||
|
||
**已知局限**：仅实现 `SelfHostedProvider`；`BitAnswerProvider` 在 Rust 侧未实现。
|
||
|
||
### 16.5 Java SDK 原型（java/）
|
||
|
||
| 模块 | 覆盖率 | 说明 |
|
||
|------|--------|------|
|
||
| `craftlabs-auth-core` | ✅ `AuthConfigs`（解析/校验/序列化）+ `AuthConfig`/`AuthConfigs` 配置模型 + `AuthProvider` 接口 + `AuthResult` + `LicenseInfo` + `NativeBridge`（JNI 接口声明） |
|
||
| `craftlabs-auth-bitanswer` | ⚠️ `BitAnswerProvider` 实现 `AuthProvider` 接口但 **JNI 未对接真实原生库**，属于 Stub 状态 |
|
||
| `craftlabs-auth-selfhosted` | ⚠️ `SelfHostedAuthProvider` 基础实现，未对接 Rust 核心库（当前为独立 Java 实现） |
|
||
| `craftlabs-auth-tests` | ✅ Schema 校验测试 + BitAnswerProvider 基础测试 |
|
||
| `schemas/craftlabs-auth-config.schema.json` | ✅ 完整 JSON Schema Draft 2020-12，支持 3 种 scenario + 2 种 provider |
|
||
|
||
### 16.6 原型已知局限
|
||
|
||
以下为审计发现的 25 个问题中与原型直接相关的重大局限：
|
||
|
||
| 类别 | 问题 | 影响 | 计划迭代 |
|
||
|------|------|------|---------|
|
||
| **安全** | 前端 Token 存 `localStorage`（非 HttpOnly Cookie） | XSS 窃取风险 | Mid |
|
||
| **安全** | Callback `raw_payload` 全字段明文落库 | 可能含 PII，未脱敏 | I10 |
|
||
| **SDK** | `BitAnswerProvider` 未对接真实原生库 | SDK 无法实际与比特安索通信 | Mid |
|
||
| **SDK** | Java SelfHostedProvider 未调用 Rust 核心 | 自研授权路径不通 | Mid |
|
||
| **角色** | 仅实现 3 个角色（产品定义 10+），存在 `DEVELOPER`/`OPS` 非标角色 | 角色模型与产品定义不匹配 | I12 |
|
||
| **M1** | 客户表缺行业/地址/开票信息、项目表缺计划起止/项目经理 | 字段覆盖不足 | I10 |
|
||
| **M4** | 比特控制台状态摘要未实现（原 P0） | 需跳转比特控制台查看 | P1/Mid |
|
||
| **M6** | 产品线→比特 ID 映射、特征映射、JSON 模板管理均未实现 | BP-10 配置发布流程不完整 | Mid |
|
||
| **M7～M9** | 设备/通知/报表模块完全未开始 | Mid 核心范围 | I10～I12 |
|
||
| **测试** | 无 Playwright E2E 测试 | 回归覆盖不足 | I10 |
|
||
| **基础设施** | 无消息队列，Webhook→API 走轮询 HTTP | 无削峰能力，高并发受限 | I11 |
|
||
|
||
### 16.7 从原型到产品化的演进路径
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph MVP["MVP（已完成 I1～I9）"]
|
||
A["BP-01～06+11 主链路<br/>M1～M6 P0 + M10-F01 + M11 基础<br/>自研许可证 V6 额外"]
|
||
end
|
||
subgraph Mid["Mid（I10～I13）"]
|
||
B["补齐 M1/M4/M11 P0 缺口<br/>M7 设备 + M8 通知 + M9 报表<br/>M2/M5/M6 P1 增强<br/>SSO + 角色模型对齐<br/>BitAnswerProvider 对接"]
|
||
end
|
||
subgraph Full["Full（V2.0）"]
|
||
C["MFA / SECURITY_ADMIN<br/>数据范围 / 审计导出<br/>CRM 同步 / 变更治理<br/>消息队列 / 读模型分离"]
|
||
end
|
||
MVP --> Mid --> Full
|
||
```
|
||
|
||
**关键里程碑**：
|
||
- **当前**：MVP 原型已完成，可支撑一条真实或准生产项目全链路 UAT
|
||
- **Mid（目标 T0+24～28 周）**：具备设备治理、通知协作、对账报表，角色模型对标产品定义
|
||
- **Full（目标 T0+34～42 周）**：合规审计、深度集成、规模化运营能力
|
||
|
||
|