ylhp-ai-project-manager/docs/features/日报_AI_分析功能说明.md

# 日报 AI 分析功能使用说明

## 一、功能概述

当外部系统通过开放接口提交日报数据后，系统会自动触发 AI 分析任务，对日报内容进行深度分析，识别项目风险、资源需求，并提供进度建议。

## 二、核心特性

### 2.1 异步处理
- 日报提交后立即返回成功响应
- AI 分析在后台线程池中并行运行，不阻塞主流程
- 支持并发处理多个日报分析请求（核心 5 线程，最大 10 线程）

### 2.2 智能分析
AI 会分析以下维度：
1. **整体进度评估**：判断项目进度是提前、正常还是滞后
2. **里程碑风险识别**：识别可能延期的里程碑及风险等级
3. **资源需求分析**：分析是否需要新增人力、物料、设备等资源
4. **进度建议**：针对当前情况提出可操作的调整建议
5. **风险识别**：识别潜在的项目风险并自动入库

### 2.3 自动化处理
- 识别的风险自动保存到 `risk` 表
- 资源需求自动保存到 `resource` 表
- 项目状态根据分析结果自动更新

## 三、接口调用示例

### 3.1 请求示例

```http
POST /api/open/daily-report/sync
Content-Type: application/json

{
  "projectId": 123,
  "userId": "zhangsan",
  "reportDate": "2026-03-31",
  "workContent": "完成了项目需求分析文档的编写，与团队成员进行了技术方案讨论，确定了系统架构设计",
  "tomorrowPlan": "开始进行系统架构设计，绘制 UML 图，组织技术评审会议",
  "workIntensity": 4,
  "needHelp": true,
  "helpContent": "需要架构师协助评审技术方案"
}
```

### 3.2 响应示例

```json
{
  "code": 200,
  "msg": "日报同步成功",
  "data": null
}
```

**注意**：响应中不包含分析结果，因为 AI 分析在后台异步执行。

## 四、分析结果查看

### 4.1 查看识别的风险

```sql
-- 查询某项目通过日报分析识别的风险
SELECT * FROM risk 
WHERE project_id = 123 
  AND risk_source = 'ai_daily_report'
ORDER BY discover_time DESC;
```

### 4.2 查看资源需求

```sql
-- 查询某项目通过日报分析识别的资源需求
SELECT * FROM resource 
WHERE project_id = 123 
  AND resource_code LIKE 'RES_DR%'
ORDER BY create_time DESC;
```

### 4.3 查看项目状态变化

```sql
-- 查询项目状态变化
SELECT id, project_name, status, progress, risk_level 
FROM project 
WHERE id = 123;
```

## 五、技术实现细节

### 5.1 线程池配置

```java
@Bean("dailyReportAnalysisExecutor")
public Executor dailyReportAnalysisExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(5);      // 核心 5 线程
    executor.setMaxPoolSize(10);       // 最大 10 线程
    executor.setQueueCapacity(200);    // 队列容量 200
    executor.setThreadNamePrefix("daily-report-analysis-");
    // ... 其他配置
}
```

### 5.2 分析流程

```
1. OpenApiController 接收日报请求
   ↓
2. OpenApiService.syncDailyReport() 保存日报
   ↓
3. DailyReportAnalysisService.analyzeDailyReportAsync() 异步分析
   ↓
4. 构建项目上下文 (项目信息 + 里程碑 + 任务统计)
   ↓
5. 调用 AI 模型进行分析
   ↓
6. 解析 AI 返回的 JSON 结果
   ↓
7. 保存分析结果到数据库
```

### 5.3 AI 提示词设计

系统使用精心设计的 System Prompt，确保 AI 输出符合要求的 JSON 格式：

```
你是一个专业的项目管理 AI 助手，擅长从项目日报中分析项目状态...

任务:
1. 整体进度评估
2. 里程碑风险识别
3. 资源需求分析
4. 进度建议
5. 风险识别

输出格式 (JSON):
{
  "overallProgressAssessment": {...},
  "milestoneRisks": [...],
  "resourceNeeds": [...],
  "progressSuggestions": [...],
  "identifiedRisks": [...]  
}
```

### 5.4 项目上下文构建

AI 分析时会注入以下项目信息到提示词中:

```markdown
【项目基本信息】
- 项目名称：XXX
- 项目类型：XXX
- 项目状态：XXX
- 计划开始日期：2026-01-01
- 计划结束日期：2026-12-31
- 当前进度：45%
- 项目预算：1000000 CNY
- 已花费成本：450000 CNY

【里程碑信息】
- 需求分析与架构设计 (计划：2026-04-30, 状态：pending, 进度：0%)
- 核心算法模型训练与验证 (计划：2026-06-15, 状态：pending, 进度：0%)
- 系统功能开发完成 (Alpha 版) (计划：2026-07-31, 状态：pending, 进度：0%)

【任务列表】
- T001 [milestone] 需求调研与分析 (计划：2026-04-01 ~ 2026-04-15, 状态：completed, 进度：100%)
- T002 [milestone] 技术架构设计 (计划：2026-04-16 ~ 2026-04-30, 状态：in_progress, 进度：60%)
- T003 [task] 数据库设计 (计划：2026-05-01 ~ 2026-05-10, 状态：pending, 进度：0%)

【任务统计】
- 任务总数：15
- 已完成：3
- 完成率：20.0%

【进度分析】
- 计划工期：270 天
- 已过时间：90 天
- 预期进度：33.3%
- 实际进度：25%
- 进度偏差：-8.3%

【历史日报摘要】
1. 2026-03-30: 完成了技术方案评审，确定了系统架构...
2. 2026-03-29: 进行了需求调研，访谈了 5 个业务部门...
3. 2026-03-28: 编写了需求规格说明书初稿...
```

## 六、错误处理

### 6.1 异常场景

| 场景 | 处理方式 |
|------|----------|
| AI 服务不可用 | 记录错误日志，不影响日报保存 |
| 分析结果为空 | 跳过保存，记录警告日志 |
| 数据库写入失败 | 事务回滚，记录错误日志 |
| 线程池满 | 由调用线程处理 (CallerRuns 策略) |

### 6.2 日志查看

```bash
# 查看日报分析相关日志
grep "日报 AI 分析" logs/application.log

# 查看错误日志
grep "\[日报 AI 分析\] 失败" logs/error.log
```

## 七、性能指标

| 指标 | 目标值 |
|------|--------|
| 单次分析耗时 | 30-60 秒 |
| 并发处理能力 | 10+ 个日报同时分析 |
| 队列容量 | 200 个待分析任务 |
| 风险识别准确率 | >80% |

## 八、扩展开发

### 8.1 添加新的分析维度

修改 `DailyReportAnalysisServiceImpl.java` 中的 `DAILY_REPORT_ANALYSIS_SYSTEM_PROMPT`，添加新的分析要求。

### 8.2 调整线程池大小

根据实际负载情况，修改 `AsyncConfig.java` 中的线程池配置：

```java
executor.setCorePoolSize(10);  // 调整核心线程数
executor.setMaxPoolSize(20);   // 调整最大线程数
```

### 8.3 自定义结果处理

修改 `saveAnalysisResult()` 方法，添加自定义的保存逻辑。

## 九、常见问题

### Q1: 为什么响应中不返回分析结果？
A: 因为 AI 分析是异步执行的，提交日报时分析任务可能还未完成。如果需要查看分析结果，可以通过查询风险表、资源表等获取。

### Q2: 分析任务失败会影响日报保存吗？
A: 不会。分析任务在独立的异步线程中执行，即使失败也不影响日报的正常保存。

### Q3: 如何重新触发分析？
A: 当前版本暂不支持手动重新触发。可以重新提交同一天的日报 (会触发防重拦截)，或者通过数据库直接查看历史分析结果。

### Q4: 分析结果准确吗？
A: AI 分析的准确性取决于提供的项目数据质量和日报内容的详细程度。建议提供完整、准确的日报内容以获得更好的分析结果。

## 十、相关文件

- DTO: `DailyReportAnalysisResult.java`
- Service: `DailyReportAnalysisService.java` / `DailyReportAnalysisServiceImpl.java`
- Controller: `OpenApiController.java`
- Config: `AsyncConfig.java`
- Test: `DailyReportAnalysisServiceTest.java`