diff --git a/docs/superpowers/specs/2026-05-25-mid-prototype-m7-m8-m9-design.md b/docs/superpowers/specs/2026-05-25-mid-prototype-m7-m8-m9-design.md new file mode 100644 index 0000000..86c822c --- /dev/null +++ b/docs/superpowers/specs/2026-05-25-mid-prototype-m7-m8-m9-design.md @@ -0,0 +1,401 @@ +# Mid 阶段原型设计 — M7 设备管理 / M8 通知待办 / M9 报表对账 + +> **基于**：PRD `docs/chuangfei-platform-product-modules.md`（2026-05-25 更新版）§16 原型已知局限 +> **设计目标**：补齐 I1～I9 未覆盖的三个模块的 UI 原型，完善完整产品流程（登录 → 客户 → 合同 → 交付 → SN → Callback → 设备 → 待办 → 报表） +> **设计验证**：通过 Visual Companion 线框图确认，2026-05-25 +> **关联文档**：[BPM 与版本排期](../../chuangfei-platform-bpm-and-roadmap.md) · [并行迭代索引](../../engineering/PARALLEL_ITERATION_INDEX.md) + +--- + +## 1. 背景与动机 + +### 1.1 当前状态 + +I1～I9 已交付 M1～M6 + M10-F01 + M11 基础 + 自研许可证管理（V6）。三个模块完全未开始： + +| 模块 | PRD 优先级 | 计划迭代 | 功能点数 | +|------|-----------|---------|---------| +| M7 设备与终端治理 | P1 | I10～I12 | 6（F01～F06） | +| M8 通知与待办 | P1 | I10～I12 | 5（F01～F05） | +| M9 报表与对账 | P1 | I11 | 6（F01～F06） | + +### 1.2 设计原则 + +- **遵循现有模式**：与 I1～I9 的 Vue 3 + Element Plus + Pinia 风格一致 +- **渐进增强**：现有原型框架不变，新增菜单项和路由 +- **数据溯源**：优先复用已有 API 和数据库表，新增表最小化 +- **角色一致的访问控制**：按 PRD §13 权限矩阵控制可见性 + +--- + +## 2. 导航结构更新 + +### 2.1 左侧菜单（新增项以 ★ 标记） + +``` +📊 首页 +👥 客户管理 +📋 项目 +📋 合同管理 +📦 交付管理 +🔑 许可 SN +📨 Callback 收件箱 +⚙️ 集成配置 +🖥️ 设备管理 ★ M7 - SYS_ADMIN / DELIVERY / LICENSE_OPS +🔔 待办中心 / 通知设置 ★ M8 - 全员（按角色过滤） +📊 报表中心 ★ M9 - 管理层 / FINANCE_VIEW / COMPLIANCE +🔍 审计日志 +``` + +### 2.2 新增路由表 + +| 路由 | 页面组件 | 模块 | 角色 | +|------|---------|------|------| +| `/devices` | `DeviceListView.vue` | M7 | SYS_ADMIN, DELIVERY, LICENSE_OPS | +| `/devices/:id` | `DeviceDetailView.vue` | M7 | 同上 | +| `/todos` | `TodoCenterView.vue` | M8 | 全员 | +| `/notifications/settings` | `NotificationSettingsView.vue` | M8 | SYS_ADMIN 或各角色自配置 | +| `/reports/contract-sn` | `ContractSnReportView.vue` | M9 | FINANCE_VIEW, COMPLIANCE, EXEC_VIEW | +| `/reports/callback-stats` | `CallbackStatsView.vue` | M9 | LICENSE_OPS, COMPLIANCE | +| `/reports/project-health` | `ProjectHealthView.vue` | M9 | EXEC_VIEW, SYS_ADMIN | + +--- + +## 3. M7 设备与终端治理 + +### 3.1 数据模型（新增表） + +```sql +-- M7：设备主表 +CREATE TABLE platform_device ( + id BIGSERIAL PRIMARY KEY, + mid VARCHAR(128) NOT NULL UNIQUE, -- 设备指纹 / 标识 + alias VARCHAR(256), -- 别名（可读名称） + site VARCHAR(256), -- 场站 / 部署位置 + customer_id BIGINT REFERENCES platform_customer(id), + project_id BIGINT REFERENCES platform_project(id), + status VARCHAR(32) NOT NULL DEFAULT 'ACTIVE', -- ACTIVE / INACTIVE / DECOMMISSIONED + first_seen_at TIMESTAMPTZ, + last_heartbeat_at TIMESTAMPTZ, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +-- M7：设备↔SN 绑定历史（时间线） +CREATE TABLE platform_device_sn_binding ( + id BIGSERIAL PRIMARY KEY, + device_id BIGINT NOT NULL REFERENCES platform_device(id), + license_sn_id BIGINT NOT NULL REFERENCES platform_license_sn(id), + bind_type VARCHAR(32) NOT NULL DEFAULT 'ACTIVATE', -- ACTIVATE / SWAP / RELEASE + bind_at TIMESTAMPTZ NOT NULL DEFAULT now(), + remark TEXT, + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +-- M7：换机申请记录 +CREATE TABLE platform_device_swap_request ( + id BIGSERIAL PRIMARY KEY, + old_device_id BIGINT NOT NULL REFERENCES platform_device(id), + new_mid VARCHAR(128) NOT NULL, + sn_id BIGINT NOT NULL REFERENCES platform_license_sn(id), + reason VARCHAR(512), + status VARCHAR(32) NOT NULL DEFAULT 'PENDING', -- PENDING / APPROVED / REJECTED + processed_by VARCHAR(256), + processed_at TIMESTAMPTZ, + remark TEXT, + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +``` + +### 3.2 页面规格 + +**P1. 设备列表页（/devices）** + +| 组件 | 说明 | +|------|------| +| 筛选栏 | 客户下拉（可搜索）、场站文本、SN 关键词、「查询」「重置」 | +| 工具栏 | 「登记设备」按钮 → 弹出登记对话框 | +| 表格列 | mid、别名、场站、关联客户、关联 SN、状态（Tag）、最近心跳时间、操作（详情） | +| 状态枚举 | Online（在线）/ Offline（离线）/ Decommissioned（已退役） | +| 分页 | 同现有模式：10/20/50 | + +**P2. 设备详情页（/devices/:id）** + +| 区块 | 内容 | +|------|------| +| 头部 | ← 设备列表；mid 标识；状态 Tag | +| 信息区 | mid、别名、场站、客户/项目、首次发现时间、最近心跳时间 | +| 操作区 | 「编辑设备信息」按钮、「发起换机申请」按钮、「查看 SN 绑定历史」按钮 | +| SN 绑定时间线 | 列表展示：首次激活、换机、解绑等事件，按时间倒序 | + +**P3. 换机申请对话框** + +| 字段 | 类型 | 校验 | +|------|------|------| +| 原设备 | 只读 | 从设备详情传入 | +| 原 SN | 只读 | 该设备当前绑定的 SN | +| 新设备 mid | 文本输入 | 必填，maxlength=128 | +| 换机原因 | 下拉选择 | 硬件更换 / 场地迁移 / 性能升级 / 其他 | +| 备注 | 文本框 | 选填，maxlength=512 | + +**P4. 登记设备对话框** + +| 字段 | 类型 | 校验 | +|------|------|------| +| mid | 文本输入 | 必填，maxlength=128，唯一性校验 | +| 别名 | 文本输入 | 选填，maxlength=256 | +| 场站 | 文本输入 | 选填，maxlength=256 | +| 关联客户 | 下拉选择 | 选填，从已有客户列表选取 | +| 关联项目 | 下拉选择 | 选填，依赖所选客户过滤 | + +### 3.3 API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/v1/devices` | 设备分页列表（支持 customerId, site, snCode 筛选） | +| POST | `/api/v1/devices` | 登记设备 | +| GET | `/api/v1/devices/{id}` | 设备详情 | +| PUT | `/api/v1/devices/{id}` | 编辑设备信息 | +| GET | `/api/v1/devices/{id}/bindings` | SN 绑定时间线 | +| POST | `/api/v1/devices/{id}/swap-request` | 提交换机申请 | +| GET | `/api/v1/swap-requests` | 换机申请列表（Ops 审批用） | +| PATCH | `/api/v1/swap-requests/{id}/status` | 审批换机申请 | + +--- + +## 4. M8 通知与待办 + +### 4.1 数据模型（新增表） + +```sql +-- M8：待办事项 +CREATE TABLE platform_todo_item ( + id BIGSERIAL PRIMARY KEY, + todo_type VARCHAR(64) NOT NULL, -- CALLBACK_PENDING / SN_PENDING / ACTIVATION_OVERDUE + title VARCHAR(512) NOT NULL, + source_id BIGINT, -- 关联业务 ID（如 callback_inbox_id） + source_type VARCHAR(64), -- 关联业务类型 + priority VARCHAR(16) NOT NULL DEFAULT 'MEDIUM', -- HIGH / MEDIUM / LOW + status VARCHAR(32) NOT NULL DEFAULT 'PENDING', -- PENDING / PROCESSED / IGNORED + assigned_role VARCHAR(64), -- 目标角色 + assigned_user_id VARCHAR(256), -- 认领人 + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + processed_at TIMESTAMPTZ, + remark TEXT +); + +-- M8：通知配置（每个用户或角色） +CREATE TABLE platform_notification_config ( + id BIGSERIAL PRIMARY KEY, + role_code VARCHAR(64), -- 角色级别默认配置 + channel_email BOOLEAN DEFAULT FALSE, + channel_wecom BOOLEAN DEFAULT FALSE, + channel_in_app BOOLEAN DEFAULT TRUE, + event_type VARCHAR(64) NOT NULL, -- 订阅的事件类型 + aggregation_rule VARCHAR(64), -- 聚合规则：NONE / 30MIN / DAILY_DIGEST + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +``` + +### 4.2 页面规格 + +**P1. 待办中心（/todos）** + +| 组件 | 说明 | +|------|------| +| 统计卡片 | 3 个 KPI 卡片：待处理 Callback 数 / 待发放 SN 数 / 待核对激活数（带角色过滤） | +| 筛选栏 | 类型下拉（全部 / Callback / SN 发放 / 激活核对）、状态、「查询」 | +| 表格列 | 类型（Tag）、标题、来源、优先级（高/中/低）、创建时间、操作（认领/前往/忽略） | +| 批量操作 | 「批量标记已处理」「批量忽略」 | + +**P2. 通知设置（/notifications/settings）** + +| 区块 | 内容 | +|------|------| +| 通知通道 | 复选框组：站内待办 / 邮件 / 企业微信 / 短信。**MVP 实际仅实现「站内待办」**；邮件和企微为配置项占位，实际发送通道依赖独立基建，列 Mid 增强 | +| 事件订阅表 | 事件类型、通知方式、订阅角色、静默规则 | +| 操作 | "保存配置"按钮 | + +**事件类型订阅清单**（与 Callback 事件类型对齐）： + +| 事件类型 | 默认通道 | 默认角色 | 聚合规则 | +|---------|---------|---------|---------| +| Callback 待处理 | 站内 + 邮件 | LICENSE_OPS | 30 分钟内合并 | +| SN 待发放 | 站内 | LICENSE_OPS | 每日汇总 | +| 激活超期 7 日 | 站内 + 邮件 | DELIVERY + LICENSE_OPS | 不重复 | +| 换机申请待审批 | 站内 | LICENSE_OPS | 不重复 | +| 合同到期提醒 | 邮件 | SALES | 每周汇总 | + +### 4.3 API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/v1/todos` | 待办列表（支持 type, status, role 筛选） | +| PATCH | `/api/v1/todos/{id}/status` | 更新待办状态（认领/完成/忽略） | +| POST | `/api/v1/todos/batch-status` | 批量更新待办状态 | +| GET | `/api/v1/notifications/config` | 获取通知配置 | +| PUT | `/api/v1/notifications/config` | 更新通知配置 | + +--- + +## 5. M9 报表与对账 + +### 5.1 数据说明 + +M9 **不新增独立表**，全部基于已有业务表做聚合查询： + +| 视图 | 数据源 | 聚合逻辑 | +|------|--------|---------| +| 合同 vs SN 对账 | `platform_contract` + `platform_contract_line` + `platform_license_sn` | 按合同行分组 COUNT SN | +| 已发 vs 已激活 | `platform_license_sn` | 按 status 分组统计 | +| Callback 统计 | `platform_callback_inbox` | 按 event_type / status / 时间聚合 | +| 项目健康度 | 多表联合 | 交付率 / SN 发放率 / 激活率 加权计算 | + +### 5.2 页面规格 + +**P1. 履约对账（/reports/contract-sn）** + +| 组件 | 说明 | +|------|------| +| 筛选栏 | 项目下拉、合同下拉、「查询」「导出 CSV」 | +| KPI 卡片 | 合同总行项数、已发 SN 数、未发缺口、已激活/已发 | +| 表格列 | 合同编号、客户、行项、应发、实发、已激活、缺口、状态（正常/缺额/超发） | + +**P2. Callback 统计（/reports/callback-stats）** + +| 区块 | 内容 | +|------|------| +| 时间段选择 | 近 24 小时 / 近 7 天 / 近 30 天 / 自定义 | +| 事件类型分布 | 柱状图或百分比条：各事件类型占比 | +| 处理成功率趋势 | 日/周/月成功率 + 总量 | +| Top 失败原因 | 排名列表（失败原因 + 占比 + 趋势） | + +**P3. 项目健康度看板（/reports/project-health）** + +| 组件 | 说明 | +|------|------| +| 表格列 | 项目名称、交付完成率、SN 发放率、激活率、健康度（🟢正常/🟡关注/🔴风险） | +| 健康度规则 | 绿：三项均 ≥80%；黄：任一项 <80%；红：任一项 <50% | + +### 5.3 API 端点 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/v1/reports/contract-sn` | 履约对账报表（支持 projectId, contractId 筛选） | +| GET | `/api/v1/reports/callback-stats` | Callback 统计（支持时间范围、eventType 筛选） | +| GET | `/api/v1/reports/project-health` | 项目健康度列表 | +| GET | `/api/v1/reports/export` | 导出 CSV — 后端生成文件流，前端触发下载（Content-Disposition: attachment） | + +--- + +## 6. 实现注意事项 + +### 6.1 与现有系统的集成 + +- **设备↔SN 绑定**：`platform_device_sn_binding.license_sn_id` → 引用已有 `platform_license_sn.id` +- **待办自动生成**：`platform_todo_item` 的 `source_id` + `source_type` 可指向 `platform_callback_inbox.id` 等已有业务表 +- **报表聚合**：复用现有 MyBatis-Plus Mapper，新增报表专用的 `@Select` 查询方法 + +### 6.2 角色与权限 + +- 初始角色配置使用简化三角色（SYS_ADMIN / DEVELOPER / OPS） +- Mid 阶段实际交付时应按 PRD §13.2 的产品定义角色集落地： + - DELIVERY → M7 设备读写 + - LICENSE_OPS → M7 设备读写、M8 待办、M9 Callback 统计 + - SALES → M9 合同对账只读 + - FINANCE_VIEW / COMPLIANCE → M9 报表只读 + - EXEC_VIEW → M9 项目健康度只读 + +### 6.3 M7-F05 设备事件联动实现机制 + +Callback `device:*` 事件（`device:pre_activate` / `post_activate`）到达时： + +1. Webhook Ingress 接收并写入 `platform_callback_inbox` +2. `CallbackInboxService` 解析事件中的 `mid` 字段 +3. 若 `mid` 在 `platform_device` 中已存在 → 更新 `last_heartbeat_at`，并在 `platform_device_sn_binding` 添加记录 +4. 若 `mid` 不存在 → 自动创建设备草稿记录（status=INACTIVE），并在待办中心生成一条「新设备待确认」待办 +5. Ops 可在设备详情页手动补充别名/场站/客户关联 + +此机制**不依赖 M7 管理页面存在**即可在后台运行；M7 页面提供的是查看和手工干预入口。 + +### 6.4 与 PRD 状态对照 + +| 功能点 | 本设计覆盖 | 说明 | +|--------|-----------|------| +| M7-F01 设备登记 | ✅ | 登记对话框 + 列表 | +| M7-F02 绑定历史 | ✅ | 设备详情时间线 | +| M7-F03 换机申请 | ✅ | 换机申请对话框 + 审批 | +| M7-F04 设备检索 | ✅ | 列表多维度筛选 | +| M7-F05 Callback 联动 | ✅ | 待办自动生成 | +| M7-F06 策略展示 | ❌ 后续 | 依赖 BitAnswer 策略查询 | +| M8-F01 待办列表 | ✅ | 待办中心 | +| M8-F02 认领/完成 | ✅ | 状态 PATCH + 批量 | +| M8-F03 通知通道 | ✅ | 通知配置页 | +| M8-F04 通知模板 | ✅ | 事件→模板配置 | +| M8-F05 静默规则 | ✅ | 聚合规则配置 | +| M9-F01 合同 vs SN | ✅ | 履约对账页 | +| M9-F02 已发 vs 激活 | ✅ | 履约对账页含 | +| M9-F03 Callback 统计 | ✅ | Callback 统计页 | +| M9-F04 导出 CSV | ✅ | 导出按钮 | +| M9-F05 项目健康度 | ✅ | 健康度看板 | +| M9-F06 订阅报表 | ❌ 后续 | 定时邮件推送 | + +--- + +## 7. 页面关系图 + +```mermaid +flowchart TB + subgraph Existing["已有页面（I1-I9）"] + Login[登录页] + Home[首页] + Customers[客户管理] + Projects[项目] + Contracts[合同管理] + Deliveries[交付管理] + SNS[许可 SN] + Callbacks[Callback 收件箱] + Integration[集成配置] + Audit[审计日志] + end + + subgraph New["新增页面（Mid）"] + Devices[设备列表] + DeviceDetail[设备详情] + SwapRequest[换机申请] + Todos[待办中心] + NotifConfig[通知设置] + ReportCS[履约对账] + ReportCB[Callback 统计] + ReportPH[项目健康度] + end + + Login --> Home + Home --> Customers --> Projects + Projects --> Contracts + Contracts --> Deliveries + Deliveries --> SNS + Callbacks --> SNS + Integration --> SNS + + SNS --> Devices + Devices --> DeviceDetail + DeviceDetail --> SwapRequest + Callbacks --> Todos + SNS --> Todos + Devices --> Todos + Contracts --> ReportCS + SNS --> ReportCS + Callbacks --> ReportCB + ReportCS --> ReportPH + ReportCB --> ReportPH +``` + +--- + +## 8. 修订记录 + +| 日期 | 说明 | +|------|------| +| 2026-05-25 | 初版：基于 PRD 更新版和 Visual Companion 线框图确认结果撰写 |