feat: schedule periodic reports asynchronously

ai_knowledge_base_v2/deployment/DEPLOYMENT_GUIDE.md

@@ -140,6 +140,29 @@ RESTORE_CONFIRM=YES \
 
 恢复后必须检查迁移版本、`/api/ready`、管理员登录、用户登录和一次真实问答。备份文件与 `CONFIG_ENCRYPTION_KEY` 必须分别保存；只有数据库备份而没有对应加密密钥时，敏感配置无法解密。
 
+## 周期报告后台任务
+
+周期报告使用数据库保存任务状态，Redis 只用于限制多进程并发。服务重启后，等待中的任务会继续执行，超过 30 分钟仍处于执行中的任务会自动恢复并重试。
+
+默认调度规则：
+
+- 每周一 02:00（Asia/Shanghai）生成上一自然周周报；
+- 每月 1 日 03:00（Asia/Shanghai）生成上一自然月月报；
+- 只处理权益已开启周期报告、账号有效且该周期存在成功主题摘要的用户；
+- 单个任务最多自动执行 3 次，失败后可在后台用户详情中手动重新生成。
+
+可通过以下环境变量关闭或调整：
+
+```text
+PERIODIC_REPORT_WORKER_ENABLED=true
+PERIODIC_REPORT_WEEKLY_ENABLED=true
+PERIODIC_REPORT_MONTHLY_ENABLED=true
+PERIODIC_REPORT_TIMEZONE=Asia/Shanghai
+PERIODIC_REPORT_POLL_SECONDS=5
+PERIODIC_REPORT_STALE_MINUTES=30
+PERIODIC_REPORT_MAX_ATTEMPTS=3
+```
+
 ## 回滚原则
 
 1. 先停止新版本服务。
@@ -164,6 +187,7 @@ RESTORE_CONFIRM=YES \
 - 5 分钟内 HTTP 5xx 比例超过 2%。
 - `/api/ready` 连续失败。
 - AI 请求超时或外部服务错误持续增长。
+- 周期报告任务持续失败、长期停留在“生成中”或队列持续积压。
 - 问答队列持续接近上限或频繁拒绝请求。
 - MySQL、Redis 容器重启或磁盘使用率超过 80%。
 - 定时备份任务失败、校验文件缺失或超过 24 小时没有新备份。