140 lines
5.0 KiB
Markdown
140 lines
5.0 KiB
Markdown
# 飞书每日工作汇报系统实施计划
|
||
|
||
> **给执行代理的要求：** 实施本计划时必须使用 `superpowers:subagent-driven-development`（推荐）或 `superpowers:executing-plans`。所有步骤使用复选框语法，便于逐项跟踪。
|
||
|
||
**目标：** 构建第一版飞书日报 Web 应用，让员工提交每日报告，让管理者在一个页面浏览所有日报记录。
|
||
|
||
**架构：** 使用 Python 标准库实现一个零第三方依赖的小型 Web 应用。后端使用 `http.server` 提供页面和 API，使用 `sqlite3` 保存员工与日报数据，使用 `urllib.request` 调用飞书机器人 Webhook。前端使用原生 HTML/CSS/JavaScript。
|
||
|
||
**技术栈：** Python 标准库、`http.server`、`sqlite3`、`unittest`、原生 HTML/CSS/JavaScript、飞书自定义机器人 Webhook。
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
- `requirements.txt`：说明项目只使用 Python 标准库。
|
||
- `.env.example`：环境变量示例。
|
||
- `.gitignore`：忽略本地数据库、环境变量和缓存文件。
|
||
- `data/employees.json`：第一版员工名单种子文件。
|
||
- `daily_report/config.py`：读取环境变量和 `.env` 配置。
|
||
- `daily_report/db.py`：SQLite 建表、员工导入和基础查询。
|
||
- `daily_report/report_service.py`：日报校验、创建/更新、列表、未提交人员和 CSV 导出。
|
||
- `daily_report/robot_service.py`：飞书机器人提醒/汇总消息体和 Webhook 发送。
|
||
- `daily_report/web.py`：HTTP 页面路由、API 路由和静态文件服务。
|
||
- `daily_report/static/styles.css`：提交页和管理页样式。
|
||
- `daily_report/static/manager.js`：管理页筛选、复制汇总和数据加载逻辑。
|
||
- `tests/test_report_service.py`：日报业务测试。
|
||
- `tests/test_robot_service.py`：机器人消息体测试。
|
||
- `tests/test_web.py`：页面和 API 冒烟测试。
|
||
- `README.md`：中文使用说明。
|
||
|
||
## 任务 1：项目骨架
|
||
|
||
- [x] 创建 Python 包 `daily_report`。
|
||
- [x] 创建 `requirements.txt`，说明无需第三方依赖。
|
||
- [x] 创建 `.gitignore`。
|
||
- [x] 创建 `.env.example`。
|
||
- [x] 创建 `data/employees.json` 示例员工名单。
|
||
- [x] 实现 `daily_report/config.py`，读取端口、基础 URL、数据库路径、员工名单路径和飞书 Webhook 配置。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
python -m py_compile daily_report/config.py
|
||
```
|
||
|
||
## 任务 2：数据层和日报服务
|
||
|
||
- [x] 实现 `daily_report/db.py`。
|
||
- [x] 创建 `employees` 表。
|
||
- [x] 创建 `daily_reports` 表。
|
||
- [x] 导入 `data/employees.json` 中的有效员工。
|
||
- [x] 实现同一员工同一天唯一日报。
|
||
- [x] 实现 `daily_report/report_service.py`。
|
||
- [x] 校验必填字段：员工 ID、日期、今日完成、明日计划。
|
||
- [x] 重复提交时更新当天已有日报。
|
||
- [x] 计算已提交、未提交和应提交人数。
|
||
- [x] 导出 CSV。
|
||
- [x] 编写 `tests/test_report_service.py`。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
python -m unittest tests.test_report_service
|
||
```
|
||
|
||
## 任务 3：飞书机器人服务
|
||
|
||
- [x] 实现 `daily_report/robot_service.py`。
|
||
- [x] 生成“填写日报”提醒消息体。
|
||
- [x] 生成“日报提交汇总”消息体。
|
||
- [x] 支持调用飞书自定义机器人 Webhook。
|
||
- [x] 编写 `tests/test_robot_service.py`。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
python -m unittest tests.test_robot_service
|
||
```
|
||
|
||
## 任务 4：页面和 API
|
||
|
||
- [x] 实现 `daily_report/web.py`。
|
||
- [x] 提供 `/submit` 员工日报提交页。
|
||
- [x] 提供 `/manager` 管理者日报浏览页。
|
||
- [x] 提供 `POST /api/reports` 创建或更新日报。
|
||
- [x] 提供 `GET /api/reports?date=YYYY-MM-DD` 查询某日汇总。
|
||
- [x] 提供 `GET /api/reports/export?date=YYYY-MM-DD` 导出 CSV。
|
||
- [x] 提供 `POST /api/robot/send-reminder` 发送飞书提醒。
|
||
- [x] 提供 `POST /api/robot/send-summary` 发送飞书汇总。
|
||
- [x] 实现 `daily_report/static/styles.css`。
|
||
- [x] 实现 `daily_report/static/manager.js`。
|
||
- [x] 编写 `tests/test_web.py`。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
python -m unittest tests.test_web
|
||
```
|
||
|
||
## 任务 5：文档和手动验证
|
||
|
||
- [x] 编写中文 `README.md`。
|
||
- [x] 更新设计文档中的实际技术方案。
|
||
- [x] 启动本地服务。
|
||
- [x] 验证管理页可以访问。
|
||
- [x] 验证日报提交 API 可以写入数据。
|
||
- [x] 验证日报汇总 API 可以读取数据。
|
||
|
||
启动：
|
||
|
||
```bash
|
||
python -m daily_report.web
|
||
```
|
||
|
||
访问：
|
||
|
||
- 提交页：http://localhost:8787/submit
|
||
- 管理页：http://localhost:8787/manager
|
||
|
||
## 最终验证
|
||
|
||
```bash
|
||
python -m unittest discover -s tests
|
||
python -m py_compile daily_report/config.py daily_report/db.py daily_report/report_service.py daily_report/robot_service.py daily_report/web.py
|
||
```
|
||
|
||
当前验证结果：
|
||
|
||
- `python -m unittest discover -s tests`：8 个测试通过。
|
||
- `python -m py_compile ...`：通过。
|
||
- `http://localhost:8787/manager`：返回 200。
|
||
|
||
## 后续增强
|
||
|
||
- 接入飞书 OAuth，自动识别员工身份。
|
||
- 增加管理者登录和权限控制。
|
||
- 增加飞书多维表格同步。
|
||
- 增加定时任务，让提醒和汇总自动发送。
|
||
- 增加员工名单管理页面，减少手工编辑 JSON。
|