147 lines
3.9 KiB
Markdown
147 lines
3.9 KiB
Markdown
# 飞书每日工作汇报系统
|
||
|
||
这是一个轻量的日报提交和浏览工具。员工通过飞书机器人提醒进入填写页提交日报，管理者在浏览页查看所有记录和未提交名单。
|
||
|
||
## 本地启动
|
||
|
||
本项目只使用 Python 标准库，不需要安装第三方依赖。
|
||
|
||
```bash
|
||
python -m daily_report.web
|
||
```
|
||
|
||
默认地址：
|
||
|
||
- 提交页：http://localhost:8787/submit
|
||
- 管理页：http://localhost:8787/manager
|
||
|
||
## 配置
|
||
|
||
复制 `.env.example` 为 `.env`，或直接设置环境变量：
|
||
|
||
- `PORT`：服务端口，默认 `8787`
|
||
- `BASE_URL`：飞书消息里使用的外部访问地址
|
||
- `DATABASE_PATH`：SQLite 数据库路径
|
||
- `EMPLOYEE_SEED_PATH`：员工名单 JSON 路径
|
||
- `WORKDAY_CALENDAR_PATH`：国家法定工作日历 JSON 路径
|
||
- `FEISHU_WEBHOOK_URL`：飞书自定义机器人 Webhook
|
||
- `FEISHU_WEBHOOK_SECRET`：预留字段，后续用于签名校验
|
||
- `FEISHU_APP_ID`：飞书企业自建应用的 App ID，用于自动识别填写人
|
||
- `FEISHU_APP_SECRET`：飞书企业自建应用的 App Secret
|
||
- `SESSION_SECRET`：本系统登录 Cookie 签名密钥，可以填一串自己生成的随机字符
|
||
|
||
## 员工名单
|
||
|
||
第一版通过 `data/employees.json` 维护员工名单。每个员工需要：
|
||
|
||
- `feishu_user_id`
|
||
- `name`
|
||
- `department`
|
||
- `manager`
|
||
- `active`
|
||
|
||
修改员工名单后，重启服务会自动同步到 SQLite。
|
||
|
||
## 飞书机器人
|
||
|
||
在飞书群添加自定义机器人后，将 Webhook 地址配置到 `FEISHU_WEBHOOK_URL`。
|
||
|
||
手动发送提醒：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8787/api/robot/send-reminder
|
||
```
|
||
|
||
手动发送汇总：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8787/api/robot/send-summary -H "content-type: application/json" -d "{\"date\":\"2026-05-07\"}"
|
||
```
|
||
|
||
## 飞书自动识别填写人
|
||
|
||
要让员工打开填写页时自动识别身份，需要使用飞书企业自建应用。
|
||
|
||
在 `.env` 中填写：
|
||
|
||
```dotenv
|
||
FEISHU_APP_ID=你的 App ID
|
||
FEISHU_APP_SECRET=你的 App Secret
|
||
SESSION_SECRET=任意一串较长随机字符
|
||
```
|
||
|
||
然后在飞书开放平台应用后台配置网页应用重定向地址：
|
||
|
||
```text
|
||
http://你的可访问地址:8787/auth/feishu/callback
|
||
```
|
||
|
||
这个地址里的域名和端口要与 `BASE_URL` 一致。配置后重启本系统，员工打开 `/submit` 会先跳转到飞书授权，授权完成后自动回到填写页，并自动带出当前填写人。
|
||
|
||
如果暂时不填 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`，系统会退回手动填写员工 ID 的模式。
|
||
|
||
## Windows 任务计划
|
||
|
||
本项目提供 Windows 任务计划脚本。任务每天触发，但发送前会读取 `data/workday-calendar.json`，只在国家法定工作日发送：
|
||
|
||
- 工作日 18:00：日报填写提醒
|
||
- 工作日 18:50：只提醒仍未提交的人
|
||
- 工作日 19:00：日报提交汇总
|
||
|
||
这意味着：
|
||
|
||
- 周一到周五如果是法定假期，不发送。
|
||
- 周六、周日如果是调休补班，会发送。
|
||
|
||
任务计划会直接运行 Python 模块发送飞书消息，不要求 Web 服务正在运行。但 `BASE_URL` 必须是员工能打开的地址。
|
||
|
||
安装任务：
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
||
.\scripts\install-windows-tasks.ps1
|
||
```
|
||
|
||
也可以直接双击：
|
||
|
||
```text
|
||
install-tasks.bat
|
||
```
|
||
|
||
如果你的 Python 不在默认路径，可以指定：
|
||
|
||
```powershell
|
||
.\scripts\install-windows-tasks.ps1 -PythonPath "C:\Path\To\python.exe"
|
||
```
|
||
|
||
手动测试提醒：
|
||
|
||
```powershell
|
||
python -m daily_report.scheduled reminder
|
||
```
|
||
|
||
手动测试汇总：
|
||
|
||
```powershell
|
||
python -m daily_report.scheduled summary
|
||
```
|
||
|
||
卸载任务：
|
||
|
||
```powershell
|
||
.\scripts\uninstall-windows-tasks.ps1
|
||
```
|
||
|
||
也可以直接双击：
|
||
|
||
```text
|
||
uninstall-tasks.bat
|
||
```
|
||
|
||
## 验证
|
||
|
||
```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/scheduled.py daily_report/web.py daily_report/workday.py
|
||
```
|