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 设计
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%

推荐内容结构

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天行为趋势分析

数据来源

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 -0.5 ≤ slope ≤ 0.5: STABLE slope < -0.5: DECLINING
步数趋势	7天移动平均	与14-21天均值对比
睡眠趋势	7天移动平均	与14-21天均值对比
佩戴率趋势	周平均佩戴率	最近1周 vs 前3周

趋势可视化数据结构

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) 之前执行
• 确保行为画像基于最新的基线数据

任务实现

/**
 * 每日自动生成用户行为画像
 * 执行时间: 每天 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:

{
  "userId": 1,
  "profileDate": "2026-01-20"
}

Response:

{
  "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:

{
  "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 和推荐策略