docs: add Mid prototype design spec (M7 device / M8 notification / M9 reporting)

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 线框图确认结果撰写 |