sxbh_admin/cma-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
22ec40052da8afbc5cb4372faa096f140dee9817
cma-management/docs/manuals/mydashboard.md
T

7.9 KiB
Raw Blame History

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/.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
Reference in New Issue View Git Blame Copy Permalink