# 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 使用。*