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

## 目标

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

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

## 使用角色

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

## 推荐方案

采用“飞书机器人 + 小型 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 和多维表格同步。
