云开发做部门数据看板：把手工汇总变成自动刷新

摘要： 用云开发 CloudBase 做部门数据看板，把每周手工汇总变成自动刷新的页面。统计用定时云函数预先算好，页面只读结果，数据再多也不卡。 开通环境做看板：云开发 CloudBase

手工汇总周报的问题不是麻烦，是数据永远是过期的——周一花两小时做出上周的表，看的人已经不关心了。做成自动刷新的看板之后，数据实时或准实时更新，谁都能随时打开看。下面给完整实现，重点讲清一个架构决策：统计要预先算好，不要页面打开时现算。

一、先定清楚看板要回答什么问题

看板做不好的最常见原因是堆指标——把所有能算的都放上去，结果谁都不看。正确做法是先定问题，再定指标。

一张好看板通常只回答三到五个问题，比如部门业务看板：

定不出这五个问题，说明看板需求还没想清楚，先别动手。

二、关键架构决策：预计算，不要现算

这是整篇文章最重要的一节。

错误做法：页面打开时去查原始数据表，前端或云函数现场算统计结果。数据量小的时候没问题，数据涨到几万条之后，页面打开要等好几秒，而且每次打开都重算一遍，资源消耗也高。

正确做法：用定时云函数每天（或每小时）预先算好统计结果，写进一张专门的统计表。页面只读这张统计表，一次查询拿到所有数字，打开就显示。

怎么选：日报、周报、月报类看板用预计算，一天更新一次完全够用；需要分钟级实时的（比如活动当天的报名进度），可以把定时频率调到每 5 分钟，或者对关键数字用现算、其余用预计算的混合方案。

三、数据结构：原始表加统计表

原始业务表（已有，不用改）。比如 projects 集合，字段包含 stage、owner、deadline、createTime 等。

统计表（新建）。按统计粒度设计，这里以每日快照为例：

用 date 字段做唯一标识很关键，它是实现幂等的基础——定时任务重复执行时，先查这一天的记录是否已存在，存在就更新而不是新增。

四、定时云函数：怎么写统计逻辑

统计云函数要处理好四件事：

第一件：分批查询。 数据量大时不能一次拉全表，按每批 100 条循环查询累加。云函数有执行时长限制，一次拉几万条很可能超时。

第二件：幂等处理。 执行开始前先查统计表里这一天的记录，存在就走更新路径，不存在才新增。否则定时任务重试会产生重复数据。

第三件：日志覆盖关键节点。 在查询开始、每批完成、统计完成、写入完成四个节点打日志。统计数字不对时，靠日志能快速定位是哪一步算错了。

第四件：失败不要静默。 统计失败要在日志里留下完整错误，并考虑写一条失败标记，避免看板显示旧数据却没人发现。

五、给 AI 的完整提示词

用云开发做一个部门项目数据看板，数据自动刷新。

已有数据：projects 集合，字段包括 projectName、owner、stage（待启动 / 进行中 / 已完成 / 已暂停）、deadline（date）、createTime（date）

要新建的统计表（daily_stats 集合）：
- date: string，格式 YYYY-MM-DD，唯一标识
- totalCount: number，项目总数
- byStage: object，各阶段数量
- byOwner: object，各负责人项目数
- overdueCount: number，已过 deadline 且 stage 不为已完成的数量
- newCount: number，当日新增项目数
- createTime: date，统计生成时间

定时云函数 generateDailyStats：
1. 每天凌晨 2 点执行
2. 分批查询 projects 集合，每批 100 条，累加统计
3. 执行前先查 daily_stats 里当天记录是否存在，存在则更新、不存在则新增（幂等）
4. 在查询开始、每批完成、统计完成、写入完成四个节点打调试日志
5. 失败时在日志记录完整错误信息

看板页面（Web 单页）：
1. 顶部四个大数字卡片：项目总数、进行中、已完成、逾期数（逾期数标红）
2. 中部折线图：近 30 天的项目总数变化，数据来自 daily_stats
3. 下部左侧饼图：各阶段分布；右侧横向条形图：各负责人项目数（按数量降序）
4. 页面顶部显示「数据更新于 X」，取最新一条统计记录的 createTime
5. 提供「手动刷新」按钮，点击调用统计云函数立即重算

权限：
- daily_stats 集合：所有用户可读，仅云函数可写
- 手动刷新按钮调用云函数，云函数里校验调用者身份

技术约束：
- React + Vite，图表用轻量图表库，不引整套 UI 框架
- 页面只读 daily_stats，不直接查 projects 原始表
- 移动端自适应，卡片改为两列、图表可横向滚动
- 数据加载中显示骨架屏，不要白屏

开发阶段规划
注意：你每完成一个阶段，都需要让我本地体验确认后，再进入下一阶段。
阶段 1：建 daily_stats 集合与权限，写定时统计云函数并手动触发验证
阶段 2：看板页面四个数字卡片
阶段 3：三个图表
阶段 4：手动刷新、移动端适配、部署

生成完成后列出需要我手动完成的步骤（包括定时触发器配置）。

六、验收：先验数字，再验页面

第一步：手动触发统计云函数，检查统计表数据。 到云开发控制台手动调用一次云函数，然后去 daily_stats 集合里看生成的记录。逐个字段对一遍，特别是逾期数这类有条件判断的字段。

第二步：用原始数据交叉验证。 手动在 projects 集合里按条件查一次，和统计结果对比。数字不一致说明统计逻辑有问题，这时候改云函数比改页面重要。

第三步：测幂等。 再手动触发一次云函数，确认 daily_stats 里这一天还是一条记录，不是两条。

第四步：验页面展示。 数字卡片、折线图、饼图、条形图都要和统计表数据对得上。

第五步：验数据新鲜度提示。 页面上的「数据更新于 X」要显示正确，这个提示很重要——看的人需要知道数据是什么时候的。

七、常见卡点

页面打开很慢。大概率是页面在直接查原始表现算。改成读统计表。

统计数字不对。先确认是统计逻辑错还是展示错：去数据库看统计表里的原始数字。表里就是错的，改云函数；表里对、页面错，改前端。

定时任务没执行。检查定时触发器是否配置并启用，云开发控制台能看到云函数的执行记录。没有记录说明触发器没生效。

统计表出现重复记录。幂等判断没做或判断条件不对。确认是按 date 字段查重，且日期格式前后一致。

逾期数算错了。这类有条件判断的指标最容易错。常见问题是日期比较时类型不一致（字符串和日期对象比），或者没排除已完成状态。

八、往前走一步：看板之后做什么

加对比维度。环比上月、同比去年，让数字有参照。实现上是从统计表里取多个时间点的记录做计算。

加异常告警。统计云函数算完之后，如果逾期数超过阈值，发一条通知。可以配合云函数调用消息推送能力。

加明细下钻。点击饼图的某个扇区，跳转到对应状态的项目明细列表。这一步会用到原始表查询，但只在用户主动点击时才查，不影响看板加载速度。

做多个看板。按部门、按业务线拆成多张看板，统计云函数里按维度分别算，写进不同的统计记录。

总结

做数据看板的关键决策只有一个：用定时云函数预先算好统计结果，页面只读结果表，不要打开时现算。这个决策决定了看板在数据量涨上去之后还能不能用。实现上先定清楚看板要回答的三到五个问题，设计原始表加统计表两层结构，统计云函数做好分批查询、幂等处理和关键节点日志。验收时先验统计表里的数字对不对，再验页面展示，顺序不能反。

开通环境，把手工汇总变成自动看板：云开发 CloudBase 购买页