65 lines
7.9 KiB
Markdown
65 lines
7.9 KiB
Markdown
# MyDashboard 个人工作台 操作手册
|
||
|
||
> 模块 slug: mydashboard（对应队列 cma-module-queue.json）
|
||
> 最近一次修复后状态定稿：2026-09-04（project-20260904-my-dashboard-period-label 完成并验证后，commit 7ea0d2e，线上 09-34 部署生效）
|
||
> 展示层口径细节见 cma-fullstack-ops 技能 references/mydashboard-display-layer-20260904.md（改口径前必读）
|
||
|
||
## ① 模块定位
|
||
- **模块名**：MyDashboard 个人工作台（我的工作台）
|
||
- **解决什么问题**：登录后默认落地页，个人关注 KPI 卡片总览（实际值 vs 目标、红黄绿/未评状态一目了然）+ 行动方案待办 + 提醒聚合，让员工不看报表也知道自己指标完成情况与欠账
|
||
- **所属流程环节**：工作台 → 我的KPI（北极星「数据找人」的主动触达面，与 Dashboard 经营看板并列但定位个人）
|
||
- **主要角色**：所有角色（ceo/finance/business/it 均可用；页面只读展示，KPI 卡片点击可下钻详情/行动方案）
|
||
|
||
## ② 操作步骤
|
||
页面路径：登录成功默认跳 /my-dashboard；或侧边栏「我的工作台」。（zone A 只读区）
|
||
|
||
1. **看 KPI 卡片**：每张卡左侧大字号=实际值，右侧小字=目标及频率。展示文案由展示层函数生成，格式：
|
||
- 有采集值：`periodActual(k)` = `{期间}: {数值}`（如 `8月: 15.0万`）；**期间前缀是采集值所属期间**，本年显示「8月」、跨年显示「2025年12月」
|
||
- 未采集（后端无任何 KPIValue 记录 → actual_value=null）：灰字小号「**暂无数据**」（右侧目标仍显示 → 员工理解"有目标但当期未采集"）
|
||
- 真零（有记录但实际值=0）：显示 `8月: 0` ——与「暂无数据」天然区分，不再把采集缺失误读为业绩归零
|
||
- 卡片标签：达标(绿)/预警(黄)/危险(红)/未评(灰)，由后端 level 判定（见④，勿在前端重算）
|
||
2. **理解目标标签**：右侧 `目标(月)` / `目标(季)` / `目标(年)`，按 KPI frequency 由后端 target 取数（monthly/weekly→目标月值、quarterly/half_year→季值、yearly→年值）
|
||
3. **行动方案/提醒区**：页面下方 action_plans 待办列表与 reminders 提醒（含类型/严重度/related 关联）；点「查看」跳对应详情（plan_id 直达详情仅对**当前列表存在**的行生效，跨页静默属既有行为）
|
||
4. **数据口径须知**：actual_value = 该 KPI **最新一条 KPIValue**（按 calculated_at 降序），**不按周期过滤**——可能是上月甚至更早的陈旧采集值；期间前缀就是防"陈旧值伪装成当月值"。若需精确当期数，进 KPI 详情/报表看期间序列
|
||
5. 提醒数据空态：某些账套（如 entity2 博海）无逾期数据时 reminders 为空属正常，不是故障
|
||
|
||
## ③ 验证路径
|
||
- **自动脚本**：无独立 verify_*.py 入库（该修复纯前端展示层，正式脚本未沉淀）；用下列手工/半自动步骤验证，**复用配方**：cma-fullstack-ops references/mydashboard-display-layer-20260904.md「CDP 页面实测配方」段
|
||
- **手工验证步骤**：
|
||
1. CDP 驱动已登录 Chrome（或按技能 CDP 登录序列登录）→ 导航 https://cma.sxbh.ltd/my-dashboard → 等 ~5s
|
||
2. dump 每张卡片：`[...document.querySelectorAll('.kpi-card')].map(c=>c.innerText.replace(/\n/g,' | '))`
|
||
3. 判据：出现 `N月: 值` 期间前缀（=期间标签过）；同屏出现「暂无数据」与 `8月: 0`（=空值/真零区分过）；目标标签仍 `目标(月/季/年)`（=口径一致性）
|
||
4. 产物/部署验证：`md5sum /var/www/cma/assets/MyDashboard-CA66065P.js /root/cma-management/frontend/dist/assets/MyDashboard-CA66065P.js` 应一致（hash 名变则以实际 chunk 名为准），且 chunk 含标记文案「暂无数据」→ curl https://cma.sxbh.ltd/assets/<chunk>.js HTTP 200（懒加载 chunk 不在 index.html 主引用，直接按 hash 名验证）
|
||
- **期望输出**：卡片 dump 样例（entity1 酣客 admin）：
|
||
`渠补率 | 预警 | 4月: 81.7 | 目标(月) 80`；`净利润 | 危险 | 8月: 0 | 目标(月) 62`；`营业收入 | 达标 | 8月: 15.0万 | 目标(季) 1200`；`交付及时率 | 未评 | 暂无数据 | 目标(月) 85`
|
||
- **已测基线**（最近一次验证日期+结果）：2026-09-04 线上 HTTP 200 + chunk 含「暂无数据」+ md5 与 dist 一致（39b1a42dda60af0f133d2eaf73f0b776）+ 构建独立重跑 12.25s 产物 chunk 名不变（内容确定性 hash）
|
||
|
||
## ④ 已知边界 / 坑
|
||
- **历史 bug**：
|
||
- 2026-09-04 口径可理解性（commit 7ea0d2e，仅改 frontend/src/views/MyDashboard.vue +20/-1）：①员工误把"最近采集值"（可能陈旧）当本月值 → 卡片加 `{期间}: {数值}` 前缀（fmtPeriod：本年 '8月' / 跨年 '2025年12月' / 无 period 脏数据回退 '最近'）；②未采集显示成 0 被误读为"业绩归零" → null 显示灰字「暂无数据」，真 0 保持 `8月: 0`。后端零改动（my_dashboard kpi_list 本已返回 period 字段）
|
||
- 2026-08-31 关联修复：dashboard my_plans/reminders 曾漏 entity 过滤（见多租户手册），跨账套待办会出现在本账套工作台
|
||
- **边界条件**：
|
||
- **actual_value 是最新一条采集值而非"本月值"**（order_by calculated_at desc，不按 period 过滤）——这是设计（展示"最近状况"），期间前缀负责自明口径；**勿改后端取数逻辑**去"修正"为当月值，会改红黄绿判定基准
|
||
- 空值判定：无 KPIValue 记录 → actual=None →「暂无数据」；有记录 actual=0 → 真零。**后端天然区分，前端勿把 null 当 0**
|
||
- 红黄绿：正向 ≥0.9 绿 ≥0.7 黄 否则红；反向指标集合（F_COST_RATIO/C_REBATE_RATE/F_AR_DAYS/F_REBATE_RATE/F_FACTORY_REBATE_RATE/F_COST_CONTROL_RATE/F_INV_DAYS/F_DEBT_RATIO/P_BUG_RATE/P_REWORK_PCT）≤目标绿、≤1.1 黄；actual null → level=gray（未评）
|
||
- entity2（博海）无逾期数据 → reminders 空态正常
|
||
- **⚠️ 易踩点**：
|
||
1. **只改展示层**：勿动 level 判定 / kpi_target_by_frequency / REVERSE_INDICATORS / 采集器（2026-09-04 任务红线；改动会破坏红黄绿口径）
|
||
2. el-progress 百分比计算引用 `k.target_value`（`(k.actual_value||0)/k.target_value`），改展示别碰 progress
|
||
3. 目标标签 targetLabel 按 frequency 返回 目标(月/季/年)——保持（quarterly 卡"8月实际 vs 目标(季)"是自解释口径，勿再加角标噪音）
|
||
4. 前端改动部署后验证线上必须**先刷新页面**（懒加载旧 bundle 陷阱：旧 JS 无新 @click/文案，刷新后按 hash 确认新 chunk 才测）
|
||
5. Vite 产物验证先 grep 原文「暂无数据」（本 chunk 中文原文未转义）；hex 转义探测假阴性勿当依据
|
||
|
||
## ⑤ 修改记录
|
||
| 日期 | 修改人 | 改动 | commit | 影响 |
|
||
|------|--------|------|--------|------|
|
||
| 2026-09-04 | - | 手册创建（修复后状态定稿） | - | - |
|
||
| 2026-09-04 | 全栈Bot | KPI 卡实际值加期间前缀（本月 '8月'/跨年 '2025年12月'）+ 未采集显示「暂无数据」（真 0 保持 'X月: 0'）；仅展示层 | 7ea0d2e | 口径可理解性修复 |
|
||
| 2026-08-31 | 全栈Bot | my_plans/reminders 补 entity 过滤（关联多租户） | 815acda | 防跨账套待办 |
|
||
|
||
## ⑥ 关联
|
||
- **依赖表**：kpi_definitions / kpi_values（actual 取最新一条，含 period/calculated_at）/ kpi_targets（target 按 frequency）/ action_plans / kpi_alerts（reminders 来源）
|
||
- **依赖接口**：GET /api/cma/dashboard/my-dashboard（返回 kpi_list 含 period + action_plans + reminders，账套隔离）
|
||
- **关联模块**：Dashboard 经营看板（dashboard.py 同源）、预警（ai_analysis level 判定）、行动方案/自动验证（action_plans + verify.py）、KPI 采集（kpi_value_collector.py 写 period=YYYY-MM）
|
||
- **验证资产**：配方见 cma-fullstack-ops references/mydashboard-display-layer-20260904.md；隔离验证 backend/scripts/verify_dashboard_isolation.py
|