# 关系质量功能（第二层）实现计划

## TL;DR

> **Quick Summary**: 为"行·人际和谐"维度实现完整的关系质量管理体系，包含 AI 生成问卷评分、互动记录追踪、健康预警、里程碑提醒五大功能
>
> **Deliverables**:
> - 后端：3 个新 Service、1 个 Controller、4 个新 Entity、3 个 DTO、新数据表
> - 前端：family-members 增强、新问卷页面、互动记录组件、健康预警提示
> - AI：基于 Dify 的动态问卷生成
>
> **Estimated Effort**: Large
> **Parallel Execution**: YES - 3 waves
> **Critical Path**: T1 (schema) → T5 (backend APIs) → T10 (frontend integration) → T14 (AI questionnaire) → T17 (health alerts)

---

## Context

### Original Request
实现"行·人际和谐"维度的第二层关系质量功能（五项全量）

### Interview Summary
**Key Discussions**:
- 关系质量三维：信任(trust) + 亲密(intimacy) + 沟通(communication)
- 评分方式：AI 动态生成问卷（每次不同模板）→ 用户填写 → 自动计算 + 互动记录辅助
- 展示：成员卡片显示三围评分；联系人单独实现
- A2 报告：是 DAN 评估的特定模板，非数据库字段
- 全量实现所有 5 个功能

**Research Findings**:
- `AIService.java` 已封装 Dify AI（`/chat-messages` 端点，blocking 模式）
- `DanAssessmentResult.java` 已有 EMI 维度（情绪商数/心理韧性/压力应对/自我认知）可作为关系质量参考
- 前端 `action/index.vue` 已有 FamilyEnergyBar + FamilyRelationGraph + ContactCard 组件
- `FamilyRelationGraph.vue` 已有 `intimacyMap` + `energyMap` props（但 family-members.vue 当前不传入）
- `ContactCard.vue` 已有 `intimacyLevel` 显示
- `Contact` 实体已有 `intimacyLevel` 字段
- 评分展示模式已有参考：FamilyEnergyBar（进度条）、PointsProgressRing（环形）

---

## Work Objectives

### Core Objective
在"行·人际和谐"维度建立完整的关系质量管理体系，用户可以通过 AI 问卷 + 互动记录了解家庭成员间的关系健康度，并获得改善建议。

### Concrete Deliverables
- 后端 Schema：`family_members` 新增 4 字段 + 3 张新表
- 后端 API：`/api/family/relationship/*`、`/api/family/interaction/*`
- 前端成员卡片：显示信任/亲密/沟通三围评分（进度条）
- 前端问卷页面：AI 生成问卷 → 填写 → 提交 → 计算评分
- 前端互动记录：记录家庭成员互动（类型+描述+时间）
- 前端健康预警：长期未互动提醒（30天无互动）
- 前端里程碑：生日/纪念日即将到来提醒
- 前端行维度首页：关系质量概览

### Definition of Done
- [ ] `mvn clean compile` 后端编译通过
- [ ] 所有 API 端点返回 `Result<T>` 格式
- [ ] family-members.vue 成员卡片显示三围评分
- [ ] 问卷页面可 AI 生成问题并提交计算
- [ ] 互动记录可添加/查看
- [ ] 健康预警正确计算（30天无互动触发）
- [ ] 里程碑正确显示即将到来的生日/纪念日
- [ ] 行维度首页显示关系质量概览

### Must Have
- AI 动态生成问卷（每次不同，基于关系类型和成员信息）
- 三维评分计算（信任/亲密/沟通）
- 互动记录 CRUD
- 成员卡片三色进度条展示
- 健康度预警

### Must NOT Have (Guardrails)
- 不修改现有的 `Contact` 实体和联系人功能（联系人单独实现）
- 不修改 DAN 测评相关表结构（只读 A2 报告数据）
- 不使用可选链 `?.`（微信小程序限制）
- 不使用 CSS Grid（用 flexbox）
- 不在 Controller 直接调用 Mapper

---

## Execution Strategy

### Parallel Execution Waves

```
Wave 1 (Foundation — 8 tasks, MAX PARALLEL):
├── T1: Schema 变更 + Entity 定义 [quick]
├── T2: InteractionLog Entity + Mapper [quick]
├── T3: RelationshipQuestionnaireSnapshot Entity + Mapper [quick]
├── T4: RelationshipQuestionnaireResponse Entity + Mapper [quick]
├── T5: RelationshipQualityController + Service [unspecified-high]
├── T6: InteractionLogController + Service [unspecified-high]
├── T7: RelationshipQuestionnaireController + Service [unspecified-high]
└── T8: 前端 API 封装 (utils/api.js) [quick]

Wave 2 (Frontend Core — 6 tasks, MAX PARALLEL):
├── T9:  family-members.vue 三维评分展示 [visual-engineering]
├── T10: member-action-detail.vue 增强 [visual-engineering]
├── T11: action/index.vue 关系质量概览 [visual-engineering]
├── T12: 互动记录弹窗/页面 [visual-engineering]
├── T13: 联系人卡片增强 (ContactCard intimacyLevel) [visual-engineering]
└── T14: 问卷填写页面 (relationship-questionnaire.vue) [visual-engineering]

Wave 3 (AI + Advanced — 4 tasks):
├── T15: AI 问卷生成（Dify 集成） [unspecified-high]
├── T16: 评分计算逻辑（问卷 + 互动记录） [deep]
├── T17: 健康预警 + 里程碑计算 [deep]
└── T18: 行维度首页完整集成 [deep]

Wave FINAL:
└── T19: 端到端验证 + 提交推送
```

### Dependency Matrix

| Task | Deps | Blocks |
|------|------|--------|
| T1: Schema | - | T5, T6, T7 |
| T2: InteractionLog Entity | - | T6 |
| T3: Snapshot Entity | - | T7 |
| T4: Response Entity | T3 | T7 |
| T5: RelationshipQuality Ctrl+Svc | T1 | T8 (验证) |
| T6: InteractionLog Ctrl+Svc | T1, T2 | T8 (验证) |
| T7: Questionnaire Ctrl+Svc | T1, T3, T4 | T8 (验证) |
| T8: Frontend API | T5, T6, T7 | T9, T12, T13, T14 |
| T9: family-members 增强 | T8 | T11 |
| T10: member-action-detail | T8 | - |
| T11: action/index 概览 | T9, T10 | T18 |
| T12: 互动记录 UI | T8 | - |
| T13: ContactCard 增强 | T8 | - |
| T14: 问卷页面 | T8 | T15, T16 |
| T15: AI 问卷生成 | T14 | T16, T18 |
| T16: 评分计算 | T15 | T18 |
| T17: 健康预警+里程碑 | T5, T6 | T18 |
| T18: 行首页集成 | T11, T15, T16, T17 | T19 |
| T19: 端到端验证 | T18 | - |

---

## TODOs

> 每个任务格式：推荐 Agent + 并行信息 + 参考文件 + 验收标准 + QA 场景

---

### Wave 1 — Foundation (后端基础设施)

#### T1. Schema 变更 + 扩展 FamilyMember 实体

**SQL 变更**：
```sql
ALTER TABLE family_members
ADD COLUMN trust_score DECIMAL(5,2) DEFAULT 0 COMMENT '信任度 0-100',
ADD COLUMN intimacy_score DECIMAL(5,2) DEFAULT 0 COMMENT '亲密度 0-100',
ADD COLUMN communication_score DECIMAL(5,2) DEFAULT 0 COMMENT '沟通质量 0-100',
ADD COLUMN last_interaction_at DATETIME DEFAULT NULL COMMENT '最近互动时间';

CREATE TABLE interaction_logs (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  family_id BIGINT NOT,
  from_member_id BIGINT NOT,
  to_member_id BIGINT NOT,
  interaction_type VARCHAR(32) NOT COMMENT 'dining/outgoing/call/video/chat/play/gift',
  description VARCHAR(256),
  happened_at DATETIME NOT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_family (family_id),
  INDEX idx_member (from_member_id),
  INDEX idx_happened (happened_at)
) COMMENT '家庭成员互动记录';

CREATE TABLE relationship_questionnaire_snapshots (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  family_member_id BIGINT NOT,
  respondent_id BIGINT NOT,
  member_name VARCHAR(64),
  relationship_type VARCHAR(32),
  ai_generated_json LONGTEXT NOT NULL COMMENT 'AI生成的题目 JSON',
  version VARCHAR(32),
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_member (family_member_id),
  UNIQUE INDEX idx_version (family_member_id, version)
) COMMENT '关系问卷快照';

CREATE TABLE relationship_questionnaire_responses (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  snapshot_id BIGINT NOT,
  respondent_id BIGINT NOT,
  answers_json LONGTEXT NOT NULL COMMENT '用户回答 JSON',
  trust_score DECIMAL(5,2),
  intimacy_score DECIMAL(5,2),
  communication_score DECIMAL(5,2),
  interaction_bonus DECIMAL(5,2) DEFAULT 0 COMMENT '互动记录加分',
  total_score DECIMAL(5,2),
  calculated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_snapshot (snapshot_id),
  INDEX idx_respondent (respondent_id)
) COMMENT '关系问卷回答结果';
```

**Entity 变更**：`FamilyMember.java` 新增 `trustScore`, `intimacyScore`, `communicationScore`, `lastInteractionAt` 字段

**Agent**: `quick`

---

#### T2. InteractionLog Entity + Mapper

**Entity**：`InteractionLog.java` — familyId, fromMemberId, toMemberId, interactionType, description, happenedAt, createdAt

**Agent**: `quick`

---

#### T3. RelationshipQuestionnaireSnapshot Entity + Mapper

**Entity**：`RelationshipQuestionnaireSnapshot.java` — familyMemberId, respondentId, memberName, relationshipType, aiGeneratedJson, version, createdAt

**Agent**: `quick`

---

#### T4. RelationshipQuestionnaireResponse Entity + Mapper

**Entity**：`RelationshipQuestionnaireResponse.java` — snapshotId, respondentId, answersJson, trustScore, intimacyScore, communicationScore, interactionBonus, totalScore, calculatedAt

**Agent**: `quick`

---

#### T5. RelationshipQualityController + RelationshipQualityService

**API 端点**：
- `POST /api/family/relationship/scores` — 获取评分
- `POST /api/family/relationship/calculate` — 计算并保存评分
- `POST /api/family/relationship/health-alerts` — 健康预警
- `POST /api/family/relationship/milestones` — 里程碑

**Agent**: `unspecified-high`

---

#### T6. InteractionLogController + InteractionLogService

**API 端点**：
- `POST /api/family/interaction/add` — 添加互动
- `POST /api/family/interaction/list` — 查询互动记录
- `GET /api/family/interaction/types` — 获取互动类型列表

**Agent**: `unspecified-high`

---

#### T7. RelationshipQuestionnaireController + RelationshipQuestionnaireService

**API 端点**：
- `POST /api/family/questionnaire/generate` — AI 生成问卷
- `POST /api/family/questionnaire/submit` — 提交问卷
- `GET /api/family/questionnaire/snapshot/{memberId}` — 获取快照
- `GET /api/family/questionnaire/history/{memberId}` — 获取历史

**Agent**: `unspecified-high`

---

#### T8. 前端 API 封装 (cfc-frontend/utils/api.js)

**新增函数**：
```javascript
// 关系质量评分
export const getRelationshipScores = (familyId) => request('/api/family/relationship/scores', 'POST', { familyId })
export const calculateRelationshipScore = (data) => request('/api/family/relationship/calculate', 'POST', data)
export const getHealthAlerts = (familyId) => request('/api/family/relationship/health-alerts', 'POST', { familyId })
export const getMilestones = (familyId, daysAhead) => request('/api/family/relationship/milestones', 'POST', { familyId, daysAhead })

// 互动记录
export const addInteraction = (data) => request('/api/family/interaction/add', 'POST', data)
export const listInteractions = (data) => request('/api/family/interaction/list', 'POST', data)
export const getInteractionTypes = () => request('/api/family/interaction/types', 'GET', {})

// 关系问卷
export const generateQuestionnaire = (data) => request('/api/family/questionnaire/generate', 'POST', data)
export const submitQuestionnaire = (data) => request('/api/family/questionnaire/submit', 'POST', data)
export const getQuestionnaireSnapshot = (memberId) => request('/api/family/questionnaire/snapshot/' + memberId, 'GET', {})
export const getQuestionnaireHistory = (memberId) => request('/api/family/questionnaire/history/' + memberId, 'GET', {})
```

**Agent**: `quick`

---

### Wave 2 — Frontend Core (前端界面)

#### T9. family-members.vue 三维评分展示

每个成员卡片增加三个进度条（信任绿色/亲密粉色/沟通蓝色），显示 trust/intimacy/communication 评分。增加"做问卷"和"记录互动"按钮。

**Agent**: `visual-engineering`

---

#### T10. member-action-detail.vue 关系质量增强

三维评分大号展示 + 最近互动记录列表 + 互动类型分布 + 关系健康状态指示（健康/注意/预警）。

**Agent**: `visual-engineering`

---

#### T11. action/index.vue 关系质量概览

在 `FamilyRelationGraph` 下方新增关系质量概览区块：家庭整体关系健康度 + 健康预警列表 + 即将到来的里程碑 + 快速入口。

**Agent**: `visual-engineering`

---

#### T12. 互动记录弹窗/页面

新建 `pages/action/interaction-log.vue`：选择互动类型（dining/outgoing/call/video/chat/play/gift/other）+ 选择互动对象 + 填写描述 + 选择时间。

**Agent**: `visual-engineering`

---

#### T13. ContactCard 亲密关系评分增强

`ContactCard.vue` 已有 `intimacyLevel` 改为进度条样式展示，低分显示预警色。

**Agent**: `visual-engineering`

---

#### T14. 问卷填写页面 (relationship-questionnaire.vue)

新建 `pages/action/relationship-questionnaire.vue`：显示 AI 生成的问卷题目 + 用户选择选项 + 提交后显示三维评分。

**Agent**: `visual-engineering`

---

### Wave 3 — AI + Advanced (AI集成)

#### T15. AI 问卷生成（Dify 集成）

扩展 `AIService.java`，新增 `generateRelationshipQuestionnaire()` 方法：
- 构建 Dify prompt（9-15 题，覆盖信任/亲密/沟通三个维度）
- 调用 Dify `/chat-messages` 端点（blocking 模式）
- 解析 AI 返回 JSON，保存到 `relationship_questionnaire_snapshots` 表
- 返回快照 ID 和题目 JSON

**Agent**: `unspecified-high`

---

#### T16. 评分计算逻辑（问卷 + 互动记录）

实现评分计算：
- 问卷得分 = 各维度平均分（0-100）
- 互动加分 = min(10, 30天内互动次数 × 0.5)
- 最终分 = 问卷分 × 0.8 + 互动加分
- 更新 `family_members` 三围字段 + `last_interaction_at`

**Agent**: `deep`

---

#### T17. 健康预警 + 里程碑计算

`getHealthAlerts()`：30 天无互动触发预警，返回预警列表（成员名、关系类型、无互动天数、建议）

`getUpcomingMilestones()`：查询 `family_member_attributes.birthDatetime`，返回未来 7 天内的生日/纪念日

**Agent**: `deep`

---

#### T18. 行维度首页完整集成

整合 T11 + T15 + T16 + T17 到 `action/index.vue`：关系质量概览 + 健康预警列表 + 里程碑列表 + 问卷/互动入口

**Agent**: `deep`

---

### Wave FINAL

#### T19. 端到端验证 + Git 提交

- `mvn clean compile` 验证
- API 端点 curl 测试
- 前端页面 Playwright 验证
- `git add` + `git commit` + `git push`

---

## Commit Strategy

```
Wave 1 完成: git add cfc-backend/src/main/java/com/etotem/cfc/entity/InteractionLog.java cfc-backend/src/main/java/com/etotem/cfc/entity/Relationship*.java ...; git commit -m "feat: 关系质量后端基础架构"
Wave 2 完成: git add cfc-frontend/pages/profile/family-members.vue cfc-frontend/pages/action/...; git commit -m "feat: 关系质量前端UI"
Wave 3 完成: git add ...; git commit -m "feat: AI问卷生成+健康预警+里程碑"
最终: git push origin cfclub
```

---

## Success Criteria

### 验收命令
```bash
# 后端编译
cd cfc-backend && mvn clean compile

# 后端启动
mvn spring-boot:run  # localhost:9082

# API 验证
curl -X POST http://localhost:9082/api/family/relationship/scores -d '{"familyId":1}'
curl -X POST http://localhost:9082/api/family/interaction/add -d '{"familyId":1,"fromMemberId":2,"toMemberId":3,"type":"dining"}'
curl -X POST http://localhost:9082/api/family/questionnaire/generate -d '{"memberId":2,"respondentId":1}'
```

### 最终检查清单
- [ ] 所有 API 端点返回 `Result<T>` 格式
- [ ] `mvn clean compile` 无 error
- [ ] 成员卡片显示三维评分（trust/intimacy/communication）
- [ ] AI 可生成问卷题目
- [ ] 互动记录可添加/查看
- [ ] 30天无互动触发健康预警
- [ ] 里程碑显示即将到来的生日
- [ ] 行维度首页显示关系质量概览