kaikai_test/docs/superpowers/specs/2026-05-07-feishu-daily-report-design.md

飞书每日工作汇报系统设计

目标

建设一个轻量、实用的飞书每日工作汇报系统。员工每天通过飞书机器人提醒进入填写页面提交日报，管理者可以在一个内部浏览页面查看所有人的日报记录。

第一版优先保证快速上线、流程顺畅、后续容易扩展。核心能力包括：每日提醒、员工填写、数据保存、管理者统一浏览、未提交统计和每日汇总。

使用角色

• 员工：每天提交一份工作日报。
• 管理者：查看日报、检查未提交人员、复制或导出汇总。
• 管理员：维护员工名单和飞书机器人配置。

推荐方案

采用“飞书机器人 + 小型 Web 应用”的方案。

• 飞书机器人每天在指定群发送日报提醒。
• 提醒消息里包含“填写日报”的按钮或链接。
• 员工打开填写页面并提交日报。
• 管理者打开浏览页面，在一个页面里查看所有记录。
• 日报数据由应用保存，后续可以按需同步到飞书多维表格。

这个方案比只使用多维表格更适合阅读和管理，也比完整飞书自建应用更容易启动。

日报字段

第一版采用标准四段式日报模板：

• 员工姓名和飞书用户 ID
• 汇报日期
• 今日完成
• 明日计划
• 遇到的问题或阻塞
• 需要协助的事项
• 提交时间
• 更新时间
• 提交状态

必填字段：

• 员工身份
• 汇报日期
• 今日完成
• 明日计划

选填字段：

• 遇到的问题或阻塞
• 需要协助的事项

如果员工当天重复提交，系统更新当天已有记录，不额外创建重复日报。

飞书流程

1. 到达配置的提醒时间，例如 18:00，机器人在工作汇报群发送日报提醒。
2. 员工点击提醒消息中的“填写日报”。
3. 系统打开日报填写页面，并默认选择当天日期。
4. 员工填写四段式日报并提交。
5. 后端校验并保存日报。
6. 页面显示提交成功状态。
7. 到达配置的汇总时间，例如 19:00，机器人在群里发送完成情况汇总：
   • 应提交人数
   • 已提交人数
   • 未提交人员名单
   • 管理者浏览页面链接

第一版可以先使用带签名的链接或简单的员工选择方式识别员工。后续版本再接入飞书 OAuth，自动识别当前登录用户。

管理者浏览页面

管理者浏览页是日常查看日报的主工作台，打开后默认展示当天日报。

筛选控件：

• 日期选择
• 员工筛选
• 部门筛选，如果已配置部门
• 关键词搜索
• 只看未提交
• 只看有问题或需要协助的日报

主要内容：

• 当前日期的提交统计
• 按员工分组展示已提交日报
• 未提交人员名单
• 每条日报展示今日完成、明日计划、问题、协助需求和提交时间

管理操作：

• 复制今日汇总
• 导出 CSV
• 打开原始数据表

页面应优先保证阅读体验，而不是做成纯表格。管理者应该能在一个页面里快速扫完当天所有日报。

数据模型

employees

• id
• feishu_user_id
• name
• department
• manager
• active
• created_at
• updated_at

daily_reports

• id
• feishu_user_id
• employee_name
• report_date
• today_done
• tomorrow_plan
• blockers
• help_needed
• submitted_at
• updated_at

唯一约束：

• 同一个 feishu_user_id 在同一个 report_date 只能有一条日报

API 设计

员工接口

• GET /submit

  • 展示日报填写页面。

• POST /api/reports

  • 创建或更新某员工某日期的日报。

管理者接口

• GET /manager

  • 展示日报浏览页面。

• GET /api/reports?date=YYYY-MM-DD

  • 返回指定日期的已提交日报和未提交人员。

• GET /api/reports/export?date=YYYY-MM-DD

  • 导出指定日期的日报 CSV。

机器人接口

• POST /api/robot/send-reminder

  • 向飞书群发送日报提醒。

• POST /api/robot/send-summary

  • 向飞书群发送日报完成情况汇总。

这些接口第一版可以由本地定时任务或手动脚本调用。

技术方案

第一版实际技术栈：

• 后端：Python 标准库 http.server
• 前端：原生 HTML/CSS/JavaScript
• 数据库：SQLite
• 飞书集成：飞书自定义机器人 Webhook，用于发送提醒和汇总

Python 标准库方案不依赖 npm 或第三方包，适合当前本地环境快速运行。SQLite 足够支撑第一版，并且部署简单。如果后续多人并发或权限要求增强，可以迁移到 PostgreSQL，用户流程不需要变化。

错误处理

• 必填字段缺失时，在表单内展示校验错误。
• 当天重复提交时，更新已有日报。
• 机器人发送失败时记录日志，并支持手动重试。
• 管理页在指定日期没有日报时展示空状态。
• 无法识别员工身份时，提交页要求员工从有效员工名单中选择姓名。

安全设计

第一版：

• 使用难以猜测的提交链接，或仅在公司内部网络/内部成员范围内访问。
• 管理页面只在内部使用。
• 飞书 Webhook 密钥不写入源代码。

后续版本：

• 接入飞书 OAuth 自动识别员工身份。
• 增加管理者权限控制。
• 增加日报编辑审计日志。

测试范围

核心检查项：

• 可以提交一份完整日报。
• 缺少必填字段时拒绝提交。
• 同一天重复提交会更新原记录。
• 管理页能展示某日期的已提交和未提交人员。
• 管理页能按员工和关键词筛选。
• 可以导出 CSV。
• 可以生成提醒消息和汇总消息。

里程碑

1. 搭建本地数据模型和日报提交流程。
2. 搭建管理者浏览页面。
3. 通过种子文件或简单配置维护员工名单。
4. 接入飞书机器人提醒和汇总发送。
5. 增加 CSV 导出和复制汇总功能。
6. 可选：接入飞书 OAuth 和多维表格同步。