IoT Jira Bug Daily Report

Overview

该 skill 用于构建一个可稳定运行的 Jira bug 日报系统：从 https://ai.eaglelab.tcl.com 的“研发效能统一数据助手”获取项目 bug 数据，按项目汇总 bug 总数、已关闭数、未关闭数，并输出超期 >=3 天 未关闭 bug 清单；随后通过飞书机器人 webhook 定时发送到群聊并 @所有人。

本 skill 提供完整的代码、配置模板、执行流程、授权说明、部署调试步骤与故障排查建议，适用于 IoT 研发团队的每日缺陷监控与自动通报。

Workflow Decision Tree

首次搭建
- 若尚未完成网站授权：先完成 references/authorization-guide.md
- 若尚未准备飞书群机器人：先完成 references/feishu-setup.md
- 若尚未确认 Jira 项目列表：先编辑 config/projects.example.json
- 若需要稳定服务器运行：使用 deploy/systemd/ 模板
- 然后配置环境变量并本地执行调试
日常运行
- 定时任务启动脚本
- 脚本读取环境变量与项目配置
- 访问研发效能统一数据助手并获取数据
- 聚合统计并生成飞书消息
- 发送日报并记录日志
发送失败或数据异常
- 先查看 logs 或标准输出错误
- 检查授权状态、Cookie/Token 是否过期
- 检查 webhook / secret 是否有效
- 检查项目编码与接口字段是否变更
- 按 references/troubleshooting.md 排查

Step 1: Solution Architecture

输入

网站授权凭据（Cookie / Token / 会话信息）
Jira 项目配置
飞书机器人 webhook
飞书签名 secret（可选）
运行环境变量

处理

调用研发效能统一数据助手接口
过滤 bug 数据
按项目聚合
识别超期 >=3 天 且未关闭 bug
生成飞书文本或富文本日报
发送飞书群消息
记录滚动日志

输出

每日飞书 bug 日报
可追踪日志
可维护配置
可直接部署的 systemd 模板

Step 2: File Structure

.
├── SKILL.md
├── scripts/
│   ├── daily_report.py
│   └── requirements.txt
├── config/
│   ├── projects.example.json
│   ├── env.example
│   └── runtime.env.example
├── deploy/
│   └── systemd/
│       ├── iot-jira-bug-dailyreport.service
│       └── iot-jira-bug-dailyreport.timer
└── references/
    ├── authorization-guide.md
    ├── feishu-setup.md
    ├── deployment-debug.md
    └── troubleshooting.md

Step 3: Core Capabilities

1. Jira Bug 数据采集

支持从研发效能统一数据助手按项目请求 bug 数据
支持 Cookie / Bearer 两种鉴权模式
支持通过环境变量调整接口路径

2. 项目级统计与超期识别

按项目输出 bug 总数、已关闭数、未关闭数
支持超期阈值配置，默认 3 天
支持兼容多种日期字段与状态字段

3. 飞书日报发送

支持 text 文本消息
支持更易读的 post 富文本消息
支持机器人签名 secret
支持 @所有人

4. 稳定运行与运维

HTTP 自动重试
项目级容错
本地 .env 加载
日志滚动写盘
提供 systemd service/timer 模板

Step 4: Core Implementation

关键增强点

引入 python-dotenv，支持本地 .env 自动加载
引入 RotatingFileHandler，支持日志滚动
新增 FEISHU_SECRET，支持飞书签名校验
新增 FEISHU_MESSAGE_TYPE，支持 text 与 post
新增 deploy/systemd/ 部署模板

scripts/requirements.txt

requests>=2.31.0,<3.0.0
urllib3>=2.0.0,<3.0.0
python-dotenv>=1.0.0,<2.0.0

config/runtime.env.example

EAGLELAB_BASE_URL=https://ai.eaglelab.tcl.com
EAGLELAB_DATA_API_PATH=/api/efficiency/jira/bugs
EAGLELAB_AUTH_MODE=cookie
EAGLELAB_COOKIE=please_fill_valid_cookie
# EAGLELAB_BEARER_TOKEN=please_fill_when_auth_mode_is_bearer

FEISHU_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx
FEISHU_SECRET=
FEISHU_MESSAGE_TYPE=post
PROJECT_CONFIG=config/projects.json
OVERDUE_DAYS=3
CLOSED_STATUSES=done,closed,resolved,已关闭,已解决
HTTP_TIMEOUT=20
REQUEST_INTERVAL=0.2
LOG_LEVEL=INFO
VERIFY_SSL=true
MENTION_ALL=true
LOG_DIR=logs
LOG_FILE=daily_report.log
LOG_MAX_BYTES=5242880
LOG_BACKUP_COUNT=7
ENV_FILE=

deploy/systemd/iot-jira-bug-dailyreport.service

[Unit]
Description=IoT Jira Bug Daily Report Service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
WorkingDirectory=/opt/iot-jira-bug-dailyreport
EnvironmentFile=/opt/iot-jira-bug-dailyreport/config/runtime.env
ExecStart=/opt/iot-jira-bug-dailyreport/.venv/bin/python /opt/iot-jira-bug-dailyreport/scripts/daily_report.py
User=appuser
Group=appuser
StandardOutput=append:/opt/iot-jira-bug-dailyreport/logs/daily_report.log
StandardError=append:/opt/iot-jira-bug-dailyreport/logs/daily_report.log

[Install]
WantedBy=multi-user.target

deploy/systemd/iot-jira-bug-dailyreport.timer

[Unit]
Description=Run IoT Jira Bug Daily Report every day

[Timer]
OnCalendar=*-*-* 09:00:00
Persistent=true
Unit=iot-jira-bug-dailyreport.service

[Install]
WantedBy=timers.target

Step 5: Execution Flow

复制 config/projects.example.json 为 config/projects.json，填写实际 Jira 项目。
复制 config/runtime.env.example 为 config/runtime.env，填写授权与飞书配置。
安装依赖：pip install -r scripts/requirements.txt
本地运行时可使用 .env 或显式环境变量。
执行 python scripts/daily_report.py。
验证飞书消息、日志文件与异常记录。
服务器部署时，使用 deploy/systemd/ 中模板启用定时运行。

Step 6: Deployment Usage

本地调试

cp config/projects.example.json config/projects.json
cp config/runtime.env.example .env
pip install -r scripts/requirements.txt
python scripts/daily_report.py

Linux systemd 部署

cp config/runtime.env.example config/runtime.env
mkdir -p logs
python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
sudo cp deploy/systemd/iot-jira-bug-dailyreport.service /etc/systemd/system/
sudo cp deploy/systemd/iot-jira-bug-dailyreport.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now iot-jira-bug-dailyreport.timer
sudo systemctl list-timers | grep iot-jira-bug-dailyreport

手工触发一次

sudo systemctl start iot-jira-bug-dailyreport.service
sudo journalctl -u iot-jira-bug-dailyreport.service -n 100 --no-pager

Step 7: Stability and Exception Handling

内置 HTTP 重试：针对 429/5xx 自动重试。
项目级容错：单项目失败不会阻塞其他项目统计。
支持日志滚动，避免日志无限膨胀。
支持 .env 自动加载，便于本地和测试环境运行。
支持飞书 secret 签名，适配更严格的群机器人安全策略。
配置化状态字段：可自定义已关闭状态集合。
配置化超期阈值：默认 3 天，可通过环境变量调整。
兼容多种日期字段与 bug 字段命名，降低接口字段差异影响。
webhook 返回值校验，避免“请求成功但发送失败”的隐性问题。

Usage

网站授权

登录 https://ai.eaglelab.tcl.com
打开浏览器开发者工具，确认实际接口请求路径、请求头与鉴权方式
若使用 Cookie 鉴权，提取完整 Cookie 写入 EAGLELAB_COOKIE
若使用 Bearer Token，则配置 EAGLELAB_AUTH_MODE=bearer 与 EAGLELAB_BEARER_TOKEN
首次接入时建议先手工调用接口确认返回字段结构，再按需调整脚本中的 DATA_API_PATH、extract_bug_list() 与 normalize_bug()

飞书配置

在目标群中添加自定义机器人
复制 webhook 地址填入 FEISHU_WEBHOOK
若开启签名校验，填入 FEISHU_SECRET
FEISHU_MESSAGE_TYPE=post 可使用富文本日报，text 则使用纯文本
需要 @所有人 时确认群权限允许机器人 at all

环境变量

所有关键参数均通过环境变量控制，适合本地、CI/CD 与服务器部署
建议将敏感信息通过 .env、密钥平台或 systemd EnvironmentFile 注入，不要硬编码进代码仓库

Jira 项目配置

每个项目单独配置 key、展示名称、查询参数
query_params 应与研发效能统一数据助手真实接口参数保持一致
若不同项目需不同筛选条件，可分别配置版本、团队、状态范围等参数

部署调试

本地先验证单项目，再扩展为多项目
若使用 systemd，优先修改 service 中的 User、Group、WorkingDirectory
建议配合 journalctl 与日志文件双重排查

问题排查

401/403：优先检查授权失效、Cookie 过期、Token 权限不足
返回字段不匹配：根据真实接口调整 extract_bug_list() 与 normalize_bug()
飞书发送失败：检查 webhook、secret、安全策略、机器人权限、消息长度限制
超期计算不准：确认接口日期字段语义（截止时间 / 更新时间 / 创建时间）并调整 find_overdue_days()
项目无数据：检查 query_params 是否正确、筛选条件是否过严
systemd 未触发：检查 timer 状态、service 用户权限、EnvironmentFile 路径

iot-jira-bug-dailyreport