docs: 添加关系质量功能（第二层）实现计划

docs/relationship-layer2-plan.md

@@ -0,0 +1,434 @@
+# 关系质量功能（第二层）实现计划
+
+## 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天无互动触发健康预警
+- [ ] 里程碑显示即将到来的生日
+- [ ] 行维度首页显示关系质量概览