90707005ed
- 项目详情页三阶段里程碑管理(前期/制作/后期) - 制作卡片改用180px ECharts圆环进度图+右侧数据列表 - 修复损耗率双重计算bug(测试秒数不再重复计入超产) - 新增飞书推送服务、豆包AI风险分析、APScheduler定时报告 - 项目列表页增强(筛选/排序/批量操作/废弃功能) - 成员详情页产出时间轴+效率对比 - 成本页固定开支管理 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
# AirLabs · AI 能力需求文档
|
||
|
||
> V2 功能模块 | 更新日期：2026-02-13
|
||
|
||
---
|
||
|
||
## 1. 功能概述
|
||
|
||
为 AirLabs 项目管理系统接入 AI 能力，实现：
|
||
|
||
1. **自动报告生成** — 系统定时汇总项目、产出、成本数据，由 AI 大模型生成自然语言总结
|
||
2. **飞书私聊推送** — 通过飞书自建应用将报告以卡片消息形式私聊推送给指定管理人员
|
||
3. **项目风险预警** — 基于规则引擎 + AI 分析，识别项目风险并在仪表盘展示
|
||
|
||
**本版本不包含**：
|
||
- 前端 AI 聊天助手页面
|
||
- 自然语言数据问答
|
||
- 按权限分级推送（所有接收人看到相同完整报告）
|
||
|
||
以上功能列入后续迭代计划。
|
||
|
||
---
|
||
|
||
## 2. AI 模型选型
|
||
|
||
| 项目 | 选型 |
|
||
|------|------|
|
||
| 模型 | 豆包（Doubao）— 字节跳动旗下大语言模型 |
|
||
| 平台 | 火山引擎 ARK |
|
||
| 模型版本 | doubao-seed-1-8-251228 |
|
||
| API 协议 | OpenAI 兼容（使用 openai Python SDK） |
|
||
| API 地址 | https://ark.cn-beijing.volces.com/api/v3 |
|
||
|
||
### 调用方式
|
||
|
||
```python
|
||
from openai import OpenAI
|
||
|
||
client = OpenAI(
|
||
api_key="<ARK_API_KEY>",
|
||
base_url="https://ark.cn-beijing.volces.com/api/v3"
|
||
)
|
||
|
||
response = client.chat.completions.create(
|
||
model="doubao-seed-1-8-251228",
|
||
messages=[
|
||
{"role": "system", "content": "你是 AirLabs 项目管理助手..."},
|
||
{"role": "user", "content": "<数据上下文>"}
|
||
]
|
||
)
|
||
```
|
||
|
||
### 降级策略
|
||
|
||
- API Key 未配置 → 报告仅包含数据模板，不含 AI 摘要
|
||
- API 调用失败 → 自动降级为纯数据报告，记录错误日志
|
||
- 超时设置：单次调用 30 秒超时
|
||
|
||
---
|
||
|
||
## 3. 自动报告功能
|
||
|
||
### 3.1 报告类型与推送时间
|
||
|
||
| 报告类型 | 推送时间 | 数据范围 |
|
||
|----------|----------|----------|
|
||
| 日报 | 每天 20:00 | 当天数据 |
|
||
| 周报 | 每周五 20:00 | 本周一至周五 |
|
||
| 月报 | 每月1日 10:00 | 上月完整数据 |
|
||
|
||
时区：Asia/Shanghai（北京时间）
|
||
|
||
### 3.2 日报内容
|
||
|
||
```
|
||
📊 AirLabs 日报 — 2026-02-13
|
||
|
||
【今日概览】
|
||
• 进行中项目：X 个
|
||
• 今日提交：X 人次，总产出 Xm Xs
|
||
• 今日未提交：张三、李四
|
||
|
||
【各项目进展】
|
||
• 项目A：进度 XX%，今日产出 Xs
|
||
• 项目B：进度 XX%，今日产出 Xs
|
||
|
||
【风险提醒】
|
||
⚠️ 项目C：距截止仅剩 X 天，进度仅 XX%
|
||
|
||
【AI 点评】
|
||
（豆包生成的自然语言总结）
|
||
```
|
||
|
||
### 3.3 周报内容
|
||
|
||
```
|
||
📋 AirLabs 周报 — 第X周（MM/DD - MM/DD）
|
||
|
||
【项目进展】
|
||
• 项目A：周初 XX% → 周末 XX%，本周产出 Xs
|
||
• 项目B：周初 XX% → 周末 XX%，本周产出 Xs
|
||
|
||
【团队产出】
|
||
• 本周总产出：Xm Xs
|
||
• 人均日产出：Xs
|
||
• 效率最高：XXX（日均 Xs）
|
||
|
||
【成本概览】
|
||
• 本周人力成本：¥X
|
||
• 本周 AI 工具支出：¥X
|
||
• 本周外包支出：¥X
|
||
|
||
【损耗排行】
|
||
• 项目A：损耗率 XX%
|
||
• 项目B：损耗率 XX%
|
||
|
||
【AI 分析与建议】
|
||
（豆包生成的深度分析）
|
||
```
|
||
|
||
### 3.4 月报内容
|
||
|
||
```
|
||
📈 AirLabs 月报 — 2026年X月
|
||
|
||
【月度总览】
|
||
• 进行中项目：X 个
|
||
• 本月完成项目：X 个
|
||
• 月度总产出：Xm Xs
|
||
• 月度总成本：¥X
|
||
|
||
【各项目成本明细】
|
||
| 项目 | 人力 | AI工具 | 外包 | 固定开支 | 总成本 |
|
||
| ... |
|
||
|
||
【盈亏概览】（仅客户正式项目）
|
||
• 项目A：回款 ¥X，成本 ¥X，利润 ¥X
|
||
• 总利润率：XX%
|
||
|
||
【月度损耗】
|
||
• 总损耗：Xs（损耗率 XX%）
|
||
• 测试损耗：Xs
|
||
• 超产损耗：Xs
|
||
|
||
【人均产出统计】
|
||
• 月度人均产出：Xs
|
||
• 较上月变化：+XX% / -XX%
|
||
|
||
【AI 深度分析】
|
||
（豆包生成的月度总结、趋势分析、改进建议）
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 飞书推送机制
|
||
|
||
### 4.1 接入方式
|
||
|
||
- **类型**：飞书自建应用（非 Webhook 群机器人）
|
||
- **能力**：私聊发送消息给指定个人
|
||
- **消息格式**：飞书交互式卡片（Interactive Card）
|
||
|
||
### 4.2 所需权限
|
||
|
||
| 权限 | 权限标识 | 用途 |
|
||
|------|----------|------|
|
||
| 以应用身份发消息 | im:message:send_as_bot | 发送私聊消息 |
|
||
| 通过手机号获取用户ID | contact:user.id:readonly | 查找接收人 |
|
||
|
||
### 4.3 接收人配置
|
||
|
||
通过 `.env` 文件配置接收人手机号，逗号分隔：
|
||
|
||
```
|
||
REPORT_RECEIVERS=18002277047,13811803069,13636518028,13811126887
|
||
```
|
||
|
||
| 姓名 | 手机号 |
|
||
|------|--------|
|
||
| 沈海川 | 18002277047 |
|
||
| 李海 | 13811803069 |
|
||
| 曾恺 | 13636518028 |
|
||
| 黄雪婷 | 13811126887 |
|
||
|
||
### 4.4 推送流程
|
||
|
||
```
|
||
定时触发 / 手动触发
|
||
↓
|
||
report_service 汇总数据库数据
|
||
↓
|
||
ai_service 调用豆包生成摘要
|
||
↓
|
||
组装飞书卡片 markdown
|
||
↓
|
||
feishu_service 获取 tenant_access_token
|
||
↓
|
||
通过手机号查询每个接收人的 user_id
|
||
↓
|
||
逐个发送私聊卡片消息
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 项目风险预警
|
||
|
||
### 5.1 风险评估维度
|
||
|
||
| 维度 | 规则 | 风险等级 |
|
||
|------|------|----------|
|
||
| 进度风险 | 实际进度 < 预期进度（按时间线性估算） | 中/高 |
|
||
| 超期风险 | 距截止不足 7 天且进度 < 80% | 高 |
|
||
| 损耗风险 | 损耗率 > 50% | 中；> 80% 高 |
|
||
| 产出停滞 | 近 7 天无提交或产出骤降 > 50% | 高 |
|
||
|
||
### 5.2 展示位置
|
||
|
||
- **仪表盘**：新增风险预警卡片区域，展示所有中/高风险项目
|
||
- **日报**：风险提醒段落
|
||
- **周报/月报**：风险汇总段落
|
||
|
||
### 5.3 AI 增强
|
||
|
||
对标记为中/高风险的项目，调用豆包生成：
|
||
- 风险原因分析
|
||
- 改进建议
|
||
- 预估影响
|
||
|
||
---
|
||
|
||
## 6. 技术架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────┐
|
||
│ FastAPI 后端 │
|
||
│ │
|
||
│ ┌─────────────┐ ┌────────────────────┐ │
|
||
│ │ APScheduler │──→│ report_service.py │ │
|
||
│ │ 定时调度 │ │ 数据汇总 │ │
|
||
│ │ • 日报 20:00 │ │ ↓ │ │
|
||
│ │ • 周报 五20:00│ │ ai_service.py │ │
|
||
│ │ • 月报 1日10 │ │ 调用豆包 AI │ │
|
||
│ └─────────────┘ │ ↓ │ │
|
||
│ │ feishu_service.py │ │
|
||
│ ┌─────────────┐ │ 飞书私聊推送 │ │
|
||
│ │ reports.py │──→│ │ │
|
||
│ │ 手动触发 API │ └────────────────────┘ │
|
||
│ └─────────────┘ │
|
||
│ │
|
||
│ ┌─────────────┐ ┌────────────────────┐ │
|
||
│ │ dashboard.py │──→│ ai_service.py │ │
|
||
│ │ 仪表盘 API │ │ 风险预警分析 │ │
|
||
│ └─────────────┘ └────────────────────┘ │
|
||
└──────────────────────────────────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────┐ ┌──────────────┐
|
||
│ SQLite 数据库 │ │ 豆包 AI API │
|
||
│ airlabs.db │ │ ARK 平台 │
|
||
└──────────────┘ └──────────────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 飞书开放平台 │
|
||
│ 私聊消息推送 │
|
||
└──────────────┘
|
||
```
|
||
|
||
### 新增依赖
|
||
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| openai | 调用豆包 AI（OpenAI 兼容协议） |
|
||
| httpx | 异步 HTTP 请求（飞书 API） |
|
||
| apscheduler | 定时任务调度 |
|
||
| python-dotenv | 读取 .env 配置 |
|
||
|
||
---
|
||
|
||
## 7. 新增文件说明
|
||
|
||
| 文件路径 | 用途 |
|
||
|----------|------|
|
||
| backend/.env | 环境变量：API Key、飞书凭证、接收人 |
|
||
| backend/services/__init__.py | services 包初始化 |
|
||
| backend/services/ai_service.py | 豆包模型调用封装 |
|
||
| backend/services/report_service.py | 报告数据汇总 + AI 摘要 |
|
||
| backend/services/feishu_service.py | 飞书应用消息推送 |
|
||
| backend/services/scheduler_service.py | APScheduler 定时任务 |
|
||
| backend/routers/reports.py | 手动触发报告 API |
|
||
|
||
---
|
||
|
||
## 8. API 接口
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| POST | /api/reports/daily | 手动触发日报 | 超级管理员 |
|
||
| POST | /api/reports/weekly | 手动触发周报 | 超级管理员 |
|
||
| POST | /api/reports/monthly | 手动触发月报 | 超级管理员 |
|
||
|
||
---
|
||
|
||
## 9. 后续迭代计划
|
||
|
||
| 优先级 | 功能 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | AI 智能问答助手 | 前端聊天页面，自然语言查询系统数据 |
|
||
| P1 | 按权限分级推送 | 不同角色收到不同内容的报告 |
|
||
| P1 | 报告历史存储 | 保存历史报告，支持回看 |
|
||
| P2 | 飞书交互式操作 | 在飞书卡片上直接查看详情、跳转系统 |
|
||
| P2 | 团队效率 AI 分析 | AI 深度分析成员效率趋势和分配建议 |
|
||
|
||
---
|
||
|
||
## 10. 配置清单
|
||
|
||
### 已获取
|
||
|
||
| 配置项 | 值 |
|
||
|--------|-----|
|
||
| 豆包 API Key | `846b6981-9954-4c58-bb39-63079393bdb8` |
|
||
| 豆包模型 | `doubao-seed-1-8-251228` |
|
||
| 飞书 App ID | `cli_a90478156bf85bd7` |
|
||
| 飞书 App Secret | `87N2nnx6Yv56TPjl2GraLdKOjFiGOSGp` |
|
||
| 接收人 | 沈海川、李海、曾恺、黄雪婷 |
|
||
|
||
### 飞书应用已开通权限
|
||
|
||
- `im:message:send_as_bot` — 以应用身份发消息
|
||
- `contact:user.id:readonly` — 通过手机号获取用户 ID
|
||
|
||
---
|
||
|
||
*本文档为 AirLabs V2 AI 能力的完整需求说明，配合主 PRD 使用。*
|