ljwx-health/docs/02-architecture/phase2-behavioral-recommendation-architecture.md

# Phase 2 Sprint 9 - 行为推荐引擎架构设计

## 文档信息

| 项目 | 内容 |
|------|------|
| **文档标题** | 行为推荐引擎架构设计 |
| **版本** | v1.0 |
| **创建日期** | 2026-01-20 |
| **作者** | Backend Dev 1 (Claude Code Sonnet 4.5) |
| **状态** | ✅ 设计评审通过 |
| **关联任务** | T2.3.1 - T2.3.4 |
| **前置依赖** | Sprint 8 - 行为画像系统 |

---

## 📋 目录

1. [系统概述](#系统概述)
2. [推荐引擎设计](#推荐引擎设计)
3. [推荐策略设计](#推荐策略设计)
4. [趋势分析设计](#趋势分析设计)
5. [定时任务设计](#定时任务设计)
6. [API 设计](#api-设计)
7. [数据流架构](#数据流架构)

---

## 系统概述

### 业务目标

基于行为画像分析结果，为用户生成个性化、可执行的健康建议，帮助用户改善不良行为习惯，建立健康生活方式。

### 核心价值

1. **个性化推荐**: 基于用户行为类型和具体指标，生成定制化建议
2. **可执行性强**: 建议具体、可操作，而非泛泛而谈
3. **动态调整**: 根据行为趋势变化，调整推荐内容
4. **智能优先级**: 按优先级排序，帮助用户聚焦最重要的改进点

### 设计原则

1. **基于证据**: 推荐内容基于行为数据分析，而非主观臆断
2. **渐进式改善**: 避免一次性要求过多改变，循序渐进
3. **正向激励**: 强化已有好习惯，温和指出需改进之处
4. **隐私保护**: 推荐内容仅用户本人可见

---

## 推荐引擎设计

### 推荐维度

基于行为画像的四个维度，推荐引擎生成四类建议：

| 推荐维度 | 数据来源 | 推荐触发条件 | 优先级权重 |
|----------|----------|-------------|-----------|
| **运动建议** | ExerciseHabits | activityLevel = SEDENTARY/LIGHTLY_ACTIVE | 30% |
| **睡眠建议** | SleepHabits | qualityRating = POOR/FAIR | 30% |
| **饮食建议** | DietPatterns | regularityLevel = IRREGULAR (未来) | 20% |
| **健康关注建议** | HealthAttention | attentionLevel = PASSIVE/CASUAL | 20% |

### 推荐内容结构

```java
public class HealthRecommendation {
    private String category;           // 类别: EXERCISE/SLEEP/DIET/ATTENTION
    private String priority;            // 优先级: HIGH/MEDIUM/LOW
    private String title;               // 标题: 简短描述
    private String description;         // 详细说明
    private String actionPlan;          // 行动计划: 具体步骤
    private String expectedBenefit;     // 预期收益
    private Integer estimatedDays;      // 预计改善天数
    private String evidence;            // 数据依据: 基于哪些行为指标
}
```

### 推荐生成流程

```
1. 获取用户行为画像
   ↓
2. 识别需要改进的行为维度
   ↓
3. 为每个维度生成候选推荐
   ↓
4. 根据优先级排序 (综合考虑问题严重度、改善可行性)
   ↓
5. 返回 Top 5 推荐
   ↓
6. 存储到 t_user_health_profile.recommendation_json
```

---

## 推荐策略设计

### 1. 运动习惯推荐策略

#### A. SEDENTARY (久坐) 用户

**识别条件**: avgDailySteps < 4000 AND activeWeekDays < 3

**推荐模板**:

```
Priority: HIGH
Title: "增加日常步行量是首要任务"
Description: "您过去7天平均每天仅走{avgDailySteps}步，远低于推荐的6000步。久坐会增加心血管疾病风险。"
ActionPlan:
  1. 设定阶段性目标: 第一周每天5000步，第二周6000步
  2. 利用通勤时间: 提前一站下车步行
  3. 设置每小时提醒: 站立活动5分钟
  4. 记录步数: 每日查看进度，保持动力
ExpectedBenefit: "4周后，心肺功能提升，精力改善，体重可能下降1-2kg"
EstimatedDays: 28
Evidence: "基于您7天平均步数{avgDailySteps}，低于健康基线"
```

#### B. LIGHTLY_ACTIVE (轻度活跃) 用户

**识别条件**: 4000 ≤ avgDailySteps < 7000

**推荐模板**:

```
Priority: MEDIUM
Title: "继续努力，向7000步目标迈进"
Description: "您已经有一定的运动基础（日均{avgDailySteps}步），距离7000步目标仅差{gap}步。"
ActionPlan:
  1. 增加运动强度: 每周2-3次快走30分钟
  2. 利用碎片时间: 午休时间散步15分钟
  3. 周末户外活动: 爬山、骑行等
ExpectedBenefit: "2周内达到7000步，运动习惯更稳定"
EstimatedDays: 14
Evidence: "基于您的步数趋势{trend}和当前日均{avgDailySteps}步"
```

#### C. MODERATELY_ACTIVE / VERY_ACTIVE 用户

**识别条件**: avgDailySteps ≥ 7000

**推荐模板**:

```
Priority: LOW
Title: "保持良好运动习惯"
Description: "您的运动量已经很好（日均{avgDailySteps}步），继续保持！"
ActionPlan:
  1. 维持现有习惯
  2. 尝试多样化运动: 游泳、瑜伽等
  3. 关注运动强度: 每周2次中高强度运动
ExpectedBenefit: "保持健康体重，降低慢性病风险"
EstimatedDays: 7 (仅需巩固)
Evidence: "您的运动水平属于{activityLevel}，请保持"
```

---

### 2. 睡眠习惯推荐策略

#### A. POOR / FAIR 睡眠质量

**识别条件**: qualityRating = POOR OR FAIR

**问题诊断**:
- 睡眠时长不足: avgSleepDuration < 420分钟 (7小时)
- 深睡眠比例低: deepSleepRatio < 20%
- 中断次数多: avgInterruptions > 3

**推荐模板**:

```
Priority: HIGH (如果 POOR) / MEDIUM (如果 FAIR)
Title: "改善睡眠质量刻不容缓"
Description: "您的睡眠质量评级为{qualityRating}。主要问题: {主要问题识别}"
ActionPlan:
  1. 固定作息: 每晚{建议入睡时间}就寝，每日{建议起床时间}起床
  2. 睡前准备: 提前1小时停止使用电子设备
  3. 优化睡眠环境: 保持卧室温度18-22°C，遮光隔音
  4. 放松训练: 睡前10分钟深呼吸或冥想
ExpectedBenefit: "2周内睡眠质量改善，白天精力提升"
EstimatedDays: 14
Evidence: "您的平均睡眠时长{avgSleepDuration}分钟，深睡占比{deepSleepRatio}%"
```

#### B. 睡眠类型针对性建议

**NIGHT_OWL (夜猫子)** - 入睡时间 > 00:00

```
ActionPlan:
  1. 逐步提前入睡时间: 每3天提前15分钟
  2. 早晨增加光照: 起床后立即接触自然光
  3. 下午避免咖啡因: 14:00后停止摄入咖啡/茶
  4. 建立睡前仪式: 固定的睡前流程帮助身体识别睡眠信号
```

---

### 3. 健康关注度推荐策略

#### A. PASSIVE (被动) 用户

**识别条件**: attentionLevel = PASSIVE, deviceWearRate < 40%

**推荐模板**:

```
Priority: MEDIUM
Title: "提高设备佩戴率，才能获得准确健康数据"
Description: "您过去30天设备佩戴率仅{deviceWearRate}%，数据不完整可能导致健康问题被忽视。"
ActionPlan:
  1. 养成佩戴习惯: 早晨起床第一件事戴上设备
  2. 充电提醒: 每晚睡前充电，确保第二天可用
  3. 查看健康报告: 每周查看一次健康数据，了解身体状况
  4. 设置目标: 下周佩戴率提升到60%
ExpectedBenefit: "数据完整后，系统能更准确评估您的健康状况"
EstimatedDays: 7
Evidence: "您的设备佩戴率{deviceWearRate}%，数据查看频率{profileViewsPerMonth}次/月"
```

---

### 4. 饮食规律推荐策略 (占位符)

**当前状态**: 饮食数据采集功能未实现

**推荐模板**:

```
Priority: LOW
Title: "饮食数据采集功能开发中"
Description: "我们正在开发饮食记录功能，敬请期待。"
ActionPlan: "暂无可执行计划"
ExpectedBenefit: "未来可以获得个性化饮食建议"
EstimatedDays: 0
Evidence: "饮食数据暂不可用"
```

---

## 推荐优先级算法

### 优先级计算公式

```
Priority Score = (问题严重度 × 0.5) + (改善可行性 × 0.3) + (用户关注度 × 0.2)
```

### 评分标准

#### 问题严重度 (0-100)

| 行为类型 | 严重度评分 |
|---------|-----------|
| AT_RISK (运动 SEDENTARY + 睡眠 POOR) | 95 |
| NEEDS_IMPROVEMENT | 70 |
| BALANCED | 40 |
| HEALTH_CONSCIOUS | 10 |

#### 改善可行性 (0-100)

| 指标 | 可行性评分 |
|------|-----------|
| 步数从3000→5000 (小幅提升) | 80 |
| 步数从3000→10000 (大幅提升) | 30 |
| 睡眠时长从5h→7h | 60 |
| 设备佩戴率从30%→60% | 70 |

#### 用户关注度 (0-100)

基于 `profileViewsPerMonth`:
- < 2次: 20分 (低关注)
- 2-5次: 50分 (中等关注)
- > 5次: 80分 (高关注)

### Top 5 推荐筛选

1. 计算所有候选推荐的 Priority Score
2. 按评分降序排序
3. 取前5个推荐
4. 确保每个维度至少有1个推荐 (如果该维度需要改进)

---

## 趋势分析设计

### 30天行为趋势分析

#### 数据来源

```sql
SELECT
    profile_date,
    behavioral_score,
    behavioral_type,
    JSON_EXTRACT(behavioral_profile_json, '$.exerciseHabits.avgDailySteps') AS daily_steps,
    JSON_EXTRACT(behavioral_profile_json, '$.sleepHabits.avgSleepDuration') AS sleep_duration,
    JSON_EXTRACT(behavioral_profile_json, '$.healthAttention.deviceWearRate') AS wear_rate
FROM t_user_health_profile
WHERE user_id = ?
  AND behavioral_profile_json IS NOT NULL
  AND profile_date >= DATE_SUB(CURDATE(), INTERVAL 30 DAY)
ORDER BY profile_date ASC;
```

#### 趋势指标

| 趋势类型 | 计算方法 | 阈值 |
|---------|---------|------|
| **整体行为评分趋势** | 线性回归 slope | slope > 0.5: IMPROVING<br>-0.5 ≤ slope ≤ 0.5: STABLE<br>slope < -0.5: DECLINING |
| **步数趋势** | 7天移动平均 | 与14-21天均值对比 |
| **睡眠趋势** | 7天移动平均 | 与14-21天均值对比 |
| **佩戴率趋势** | 周平均佩戴率 | 最近1周 vs 前3周 |

#### 趋势可视化数据结构

```java
public class BehavioralTrendDTO {
    private Long userId;
    private LocalDate startDate;          // 30天开始日期
    private LocalDate endDate;            // 30天结束日期

    // 整体趋势
    private String overallTrend;          // IMPROVING/STABLE/DECLINING
    private Double avgBehavioralScore;    // 30天平均分
    private Double scoreChange;           // 与前30天对比变化

    // 时序数据 (用于图表)
    private List<TrendDataPoint> scoreTimeSeries;
    private List<TrendDataPoint> stepsTimeSeries;
    private List<TrendDataPoint> sleepTimeSeries;

    // 关键里程碑
    private LocalDate bestPerformanceDate;   // 最佳表现日期
    private LocalDate worstPerformanceDate;  // 最差表现日期
    private Integer consistentDays;          // 连续保持良好习惯天数
}

public class TrendDataPoint {
    private LocalDate date;
    private Double value;
    private String behavioralType;  // 该日期的行为类型
}
```

---

## 定时任务设计

### 集成到现有调度系统

修改 `HealthBaselineScoreTasks.java`，新增行为画像生成任务。

#### 任务调度时间

```
Current Schedule:
01:00 - Weight validation
02:00 - User health baseline
02:05 - Department baseline
02:10 - Organization baseline
04:00 - User health score

NEW:
03:30 - User behavioral profile generation (新增)
```

**理由**:
- 在基线生成 (02:00-02:10) 之后执行
- 在评分计算 (04:00) 之前执行
- 确保行为画像基于最新的基线数据

#### 任务实现

```java
/**
 * 每日自动生成用户行为画像
 * 执行时间: 每天 03:30
 */
@Scheduled(cron = "0 30 3 * * ?")
public void generateBehavioralProfiles() {
    log.info("开始执行行为画像生成任务");

    LocalDate yesterday = LocalDate.now().minusDays(1);

    // 1. 获取所有活跃用户 (过去7天有健康数据)
    List<Long> activeUserIds = healthProfileMapper.getActiveUserIds(yesterday.minusDays(7), yesterday);

    log.info("发现{}个活跃用户需要生成行为画像", activeUserIds.size());

    // 2. 批量生成行为画像
    int successCount = 0;
    int failCount = 0;

    for (Long userId : activeUserIds) {
        try {
            behavioralProfileService.generateBehavioralProfile(userId, yesterday);
            successCount++;
        } catch (Exception e) {
            log.error("用户{}行为画像生成失败", userId, e);
            failCount++;
        }
    }

    log.info("行为画像生成任务完成: 成功{}个, 失败{}个", successCount, failCount);
}
```

#### 性能优化

- **批量处理**: 每批处理100个用户
- **并行执行**: 使用线程池并行生成 (可选)
- **错误隔离**: 单个用户失败不影响其他用户
- **监控指标**: 记录成功率、失败原因、执行时长

---

## API 设计

### 1. 生成行为推荐

**Endpoint**: `POST /api/health/behavioral-recommendations/generate`

**Request**:
```json
{
  "userId": 1,
  "profileDate": "2026-01-20"
}
```

**Response**:
```json
{
  "userId": 1,
  "profileDate": "2026-01-20",
  "recommendations": [
    {
      "category": "EXERCISE",
      "priority": "HIGH",
      "title": "增加日常步行量是首要任务",
      "description": "您过去7天平均每天仅走3200步，远低于推荐的6000步...",
      "actionPlan": "1. 设定阶段性目标...\n2. 利用通勤时间...",
      "expectedBenefit": "4周后，心肺功能提升，精力改善...",
      "estimatedDays": 28,
      "evidence": "基于您7天平均步数3200步，低于健康基线"
    },
    {
      "category": "SLEEP",
      "priority": "HIGH",
      "title": "改善睡眠质量刻不容缓",
      "description": "您的睡眠质量评级为POOR...",
      "actionPlan": "1. 固定作息...\n2. 睡前准备...",
      "expectedBenefit": "2周内睡眠质量改善",
      "estimatedDays": 14,
      "evidence": "您的平均睡眠时长360分钟，深睡占比15%"
    }
  ],
  "generatedAt": "2026-01-20T10:30:00"
}
```

---

### 2. 查询行为推荐

**Endpoint**: `GET /api/health/behavioral-recommendations/query`

**Request Parameters**:
- `userId` (Long, required)
- `profileDate` (LocalDate, optional, default: today)

**Response**: 同上

---

### 3. 查询30天行为趋势

**Endpoint**: `GET /api/health/behavioral-trends/query`

**Request Parameters**:
- `userId` (Long, required)
- `endDate` (LocalDate, optional, default: today)

**Response**:
```json
{
  "userId": 1,
  "startDate": "2025-12-21",
  "endDate": "2026-01-20",
  "overallTrend": "IMPROVING",
  "avgBehavioralScore": 72.5,
  "scoreChange": 8.3,
  "scoreTimeSeries": [
    {"date": "2025-12-21", "value": 65.0, "behavioralType": "NEEDS_IMPROVEMENT"},
    {"date": "2025-12-22", "value": 66.5, "behavioralType": "NEEDS_IMPROVEMENT"},
    ...
    {"date": "2026-01-20", "value": 78.0, "behavioralType": "BALANCED"}
  ],
  "stepsTimeSeries": [
    {"date": "2025-12-21", "value": 4200.0},
    {"date": "2025-12-22", "value": 4500.0},
    ...
  ],
  "sleepTimeSeries": [
    {"date": "2025-12-21", "value": 380.0},
    {"date": "2025-12-22", "value": 395.0},
    ...
  ],
  "bestPerformanceDate": "2026-01-18",
  "worstPerformanceDate": "2025-12-25",
  "consistentDays": 7
}
```

---

## 数据流架构

### 推荐生成流程

```
┌─────────────────────────────────────────────────────────────┐
│  Step 1: 获取用户行为画像                                     │
│  BehavioralProfileService.queryBehavioralProfile()           │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 2: 分析各维度，识别需要改进的领域                        │
│  - Exercise: activityLevel = SEDENTARY?                     │
│  - Sleep: qualityRating = POOR/FAIR?                       │
│  - Attention: attentionLevel = PASSIVE?                    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 3: 为每个维度生成候选推荐                                │
│  ExerciseRecommendationStrategy.generateRecommendations()   │
│  SleepRecommendationStrategy.generateRecommendations()      │
│  AttentionRecommendationStrategy.generateRecommendations()  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 4: 计算优先级评分                                        │
│  PriorityScore = (严重度×0.5) + (可行性×0.3) + (关注度×0.2)  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 5: 排序并返回 Top 5                                     │
│  Collections.sort(recommendations, comparingDouble(score))  │
└─────────────────────────────────────────────────────────────┘
```

### 趋势分析流程

```
┌─────────────────────────────────────────────────────────────┐
│  Step 1: 查询30天行为画像历史                                  │
│  SELECT * FROM t_user_health_profile                        │
│  WHERE behavioral_profile_json IS NOT NULL                 │
│    AND profile_date BETWEEN ? AND ?                        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 2: 提取时序数据                                          │
│  - 行为评分序列                                                │
│  - 步数序列                                                    │
│  - 睡眠时长序列                                                │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 3: 线性回归分析趋势                                       │
│  slope = calculateLinearRegressionSlope(scores, dates)      │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 4: 识别关键里程碑                                         │
│  - bestDate = max(score)                                   │
│  - worstDate = min(score)                                  │
│  - consistentDays = countConsecutiveGoodDays()             │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 5: 构建趋势 DTO 返回                                     │
│  BehavioralTrendDTO.builder()...build()                    │
└─────────────────────────────────────────────────────────────┘
```

---

## 集成方案

### 与现有系统集成

#### 1. 与行为画像系统集成

- **依赖**: BehavioralProfileService
- **数据流**: 行为画像 → 推荐引擎
- **触发**: 画像生成后自动生成推荐

#### 2. 与定时任务集成

- **修改文件**: `HealthBaselineScoreTasks.java`
- **新增任务**: `generateBehavioralProfiles()` (03:30)
- **监控**: 记录成功率、失败原因

#### 3. 与前端集成

- **API契约**: OpenAPI 3.0 规范
- **数据可视化**: ECharts 趋势图
- **UI组件**: 推荐卡片 (优先级标识、可操作按钮)

---

## 实施计划

### 开发任务拆解

| 任务ID | 任务名称 | 工作量 | 依赖 |
|--------|---------|--------|------|
| T2.3.1 | 架构设计文档 | 2h | - |
| T2.3.2.1 | RecommendationDTO 定义 | 1h | T2.3.1 |
| T2.3.2.2 | ExerciseRecommendationStrategy | 3h | T2.3.2.1 |
| T2.3.2.3 | SleepRecommendationStrategy | 2h | T2.3.2.1 |
| T2.3.2.4 | AttentionRecommendationStrategy | 1h | T2.3.2.1 |
| T2.3.2.5 | BehavioralRecommendationService | 2h | T2.3.2.2-T2.3.2.4 |
| T2.3.2.6 | RecommendationController | 2h | T2.3.2.5 |
| T2.3.3 | 定时任务集成 | 2h | T2.3.2.5 |
| T2.3.4.1 | BehavioralTrendService | 3h | T2.3.1 |
| T2.3.4.2 | TrendController API | 1h | T2.3.4.1 |
| T2.3.5 | 单元测试 | 4h | T2.3.2.6, T2.3.4.2 |
| T2.3.6 | 集成测试 | 3h | T2.3.5 |
| T2.3.7 | OpenAPI 契约更新 | 1h | T2.3.2.6 |
| **总计** | | **27h** (~3.5天) | |

---

## 验收标准

### 功能验收

- ✅ 4类行为推荐策略实现 (运动/睡眠/饮食占位符/关注度)
- ✅ 优先级算法正确计算
- ✅ Top 5 推荐生成
- ✅ 30天趋势分析准确
- ✅ 定时任务每日自动执行
- ✅ 所有API响应符合OpenAPI契约

### 质量验收

- ✅ 单元测试覆盖率 > 80%
- ✅ 集成测试通过
- ✅ Code Review通过
- ✅ 无P1/P2级别Bug

### 性能验收

- ✅ 推荐生成 < 100ms (单用户)
- ✅ 趋势分析 < 200ms (30天数据)
- ✅ 批量任务处理1000用户 < 5分钟

---

## 附录

### A. 推荐内容示例库

完整的推荐模板库见: `docs/08-reference/recommendation-templates.md`

### B. 趋势分析算法

线性回归算法实现见: `TrendAnalysisUtil.java`

---

**文档状态**: ✅ 设计完成，等待实施
**下一步**: 实施 T2.3.2 - 创建 DTO 和推荐策略