feat(ai-analysis): 添加日报 AI 分析功能说明文档及实现
- 新增详尽的日报 AI 分析功能使用说明文档，包含功能概述、接口示例、 技术细节、错误处理和性能指标 - 添加 AsyncConfig 配置，新增日报 AI 分析任务线程池，支持异步并发处理 - 创建 DailyReportAnalysisResult DTO，定义分析结果数据结构 - 实现 DailyReportAnalysisService 接口，支持异步分析日报并保存分析结果 - 实现 DailyReportAnalysisServiceImpl，集成 AI 分析模型调用和业务数据处理 - 设置 AI 分析系统提示词，规范输出 JSON 结构，确保分析质量和准确性 - 异步执行分析任务，线程池采用 CallerRunsPolicy 拒绝策略保证稳定性 - 设计项目上下文构建逻辑，整合项目信息、里程碑、任务和统计数据为 AI 提示 - 实现分析结果持久化，保存识别风险、资源需求，更新项目进度信息 - 日报 AI 分析任务异步执行异常记录，保证主流程稳定不受影响
This commit is contained in:
260
docs/features/日报_AI_分析功能说明.md
Normal file
260
docs/features/日报_AI_分析功能说明.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# 日报 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`
|
||||
Reference in New Issue
Block a user