# 关系管理功能需求分析

## 一、当前实现范围

关系管理是浠艾福平台的核心基础能力——以家庭为单位的服务平台，关系管理贯穿家庭构成、服务商绑定、社会联系人等场景。当前已实现以下能力：

### 1.1 家庭内部关系

| 能力 | 数据结构 | 前端 | 后端 API | 状态 |
|------|---------|------|----------|:----:|
| 家庭创建 | `family` 表 | — | `FamilyController` | ✅ |
| 家庭成员添加 | `family_members` 表 | `add-member.vue` | `FamilyMembersController.add` | ✅ |
| 家庭成员列表 | `family_members` 表 | `family-members.vue` | `FamilyMembersController.list` | ✅ |
| 成员关系类型编辑 | `family_members.relationshipType` | `RelationshipPicker.vue` 组件 | `FamilyMembersController.update` | ✅ |
| 切换成员视角 | `family_members` 表 | `family-members.vue` | `FamilyMembersController.switch` | ✅ |
| 踢出成员 | `family_members` 表 | `family-members.vue` | `FamilyMembersController.kick` | ✅ |
| 孩子管理 | 关联 `family_members`+`user` | `children.vue` / `create-child.vue` / `edit-child.vue` | 家长端接口 | ✅ |
| 关系类型字典 CRUD | `relationship_types` 表 | `RelationshipTypes.vue`（管理端） | `RelationshipTypeAdminController` | ✅ |
| 家庭邀请码 | `family.inviteCode` | 小程序码 | `FamilyController` | ✅ |
| 家庭邀请处理 | `family_invitation` 表 | 落地页 | `FamilyInviteController` | ✅ |
| 家庭地址编辑 | `family` 表地址字段 | `address-edit.vue` | — | ✅ |
| 家庭属性配置 | `family_member_attributes` 表 | — | `FamilyAttributeController` | ✅ |
| 家庭关系图 | Canvas 绘制 | `FamilyRelationGraph.vue` 组件 | 前端绘制 | ✅ |

### 1.2 社会联系人（非家庭成员）

| 能力 | 数据结构 | 前端 | 后端 API | 状态 |
|------|---------|------|----------|:----:|
| 联系人列表 | `contacts` 表 | `ContactCard.vue` 组件 | `ContactController.list` | ✅ |
| 创建联系人 | `contacts` 表 | 表单 | `ContactController.create` | ✅ |
| 编辑联系人 | `contacts` 表 | 表单 | `ContactController.update` | ✅ |
| 删除联系人 | `contacts` 表 | 删除操作 | `ContactController.delete` | ✅ |
| 联系人详情 | `contacts` 表 | `ContactCard.vue` | `ContactController.detail` | ✅ |
| 手机通讯录导入 | `contacts` 表 | `ContactImport.vue` 组件 | `ContactController.importPhone` | ✅ |
| 互动记录 | `contacts` 表 + contactCount | — | `ContactController.interaction` | ✅ |

### 1.3 服务商-家庭绑定

| 能力 | 数据结构 | 前端 | 后端 API | 状态 |
|------|---------|------|----------|:----:|
| 家长-规划师绑定 | `guide_family_relations` + `family.teacherId` | 绑定页面 | `BindController` | ✅ |
| 规划师邀请绑定 | `guide_family_relations` | 邀请链接 | `BindInviteController` | ✅ |
| 规划师家庭列表 | `guide_family_relations` | `FamilyList.vue`（管理端） | `GuideFamilyService` | ✅ |
| 规划师-家庭关系 | `guide_family_relations`（relationType, status） | — | `GuideFamilyRelationService` | ✅ |

### 1.4 其他关系

| 能力 | 数据结构 | 状态 |
|------|---------|:----:|
| 分销关系 | `distribution_relation` 表 | ✅ 存在但未见前端对接 |
| 家庭会员关系 | `family_memberships` 表 | ✅ 基础实现 |
| 成员属性扩展 | `family_member_attributes` 表 | ✅ |

---

## 二、现有功能覆盖评估

### 已覆盖的维度（5分/5分）

- **成员 CRUD**：完整的家庭成员增删改查
- **关系类型字典**：管理端可配置
- **关系图可视化**：Canvas 绘制家庭关系图
- **联系人管理**：社会联系人 CRUD + 手机导入
- **规划师-家庭绑定**：两端双向绑定流程
- **邀请机制**：通过邀请码加入家庭

### 部分覆盖的维度（3分/5分）

- **关系类型体系**：只有 typeKey/typeName/capabilityRole 三要素，缺少关系属性（如"亲密度"、"关系年限"、"共同居住"等）
- **家庭关系图交互**：仅查看，不支持在图上直接编辑
- **联系人与家庭成员的打通**：联系人和家庭成员互不关联，无法将联系人直接邀请为家庭成员
- **关系历史/时间线**：成员关系变更没有记录

### 未覆盖的维度（0分/5分）

- **关系统计分析**：无任何关系数据统计功能
- **关系事件提醒**：无生日提醒、纪念日提醒等
- **家庭成员角色/标签**：无自定义标签（如"主要照顾者"、"紧急联系人"等）
- **关系健康度评估**：无关系质量打分、互动频率分析
- **多家庭归属**：一个人是否可属于多个家庭
- **家庭树谱系图**：跨代家庭关系展示

---

## 三、功能需求建议

### P0 - 核心补齐（建议立即纳入）

#### 3.1 关系类型体系扩展
- **问题**：当前关系类型只有 typeKey/typeName/capabilityRole，无法表达关系的多维属性
- **需求**：
  - 关系属性扩展：亲属关系可配置"父系/母系"、"血缘/姻亲"等维度
  - 关系有效期：临时关系（如"保姆"）可设置有效期
  - 关系等级：成员在家庭中的权限等级（管理员/普通成员/受限成员）
- **涉及范围**：`RelationshipType` 实体扩展、`family_members` 加字段

#### 3.2 联系人→家庭成员升级路径
- **问题**：联系人与家庭成员是两套独立的数据，无法互通
- **需求**：
  - 联系人的"邀请加入家庭"操作
  - 联系人详情页显示"已在家庭中"的状态
  - 导入手机通讯录后，自动匹配已注册用户，显示"可邀请加入家庭"提示
- **涉及范围**：`ContactController` 新增邀请接口、`ContactCard.vue` 扩展

#### 3.3 家庭关系时间线
- **问题**：家庭成员的关系变更、加入、离开无历史记录
- **需求**：
  - 记录家庭成员每次关系类型变更
  - 记录新成员加入时间、退出时间
  - 可在家庭关系图中按时间节点回溯关系状态
- **涉及范围**：新增 `family_member_logs` 表、更新时间线组件

### P1 - 体验增强（建议下个迭代）

#### 3.4 家庭关系图增强
- 单击节点显示成员详情（弹窗）
- 双击节点切换为该成员视角（复用现有 switch 能力）
- 关系线 hover 显示关系类型名称
- 支持按关系类型筛选显示/隐藏
- 支持缩放和平移（大数据量家庭）

#### 3.5 家庭成员标签系统
- 可为成员添加自定义标签（如"接送人"、"紧急联系人"、"过敏体质"等）
- 标签在家庭关系图中以图标展示
- 标签由家长管理

#### 3.6 关系事件提醒
- 成员生日提醒
- 关系纪念日提醒（如 "爸爸加入家庭一周年"）
- 互动频率低提醒（如 "和孩子已 7 天未互动"）

### P2 - 高阶能力（建议规划）

#### 3.7 关系健康度评估
- 基于互动频率、任务完成情况、能量流动方向等，计算成员之间的关系健康度
- 关系健康度在家庭关系图中以颜色/动画表现
- 低健康度时 AI 提醒并提供改善建议

#### 3.8 多家庭/跨家庭场景
- 一个人可同时属于多个家庭（如祖父母属于多个子女家庭）
- 跨家庭能量互动、任务协作
- 家庭联姻关系管理（两个家庭因婚姻关系关联）

#### 3.9 家族谱系（Tree）
- 支持跨代关系展示（祖父母→父母→子女）
- 支持"家庭成员"和"已故长辈"的标注
- 族谱导出（图片/PDF）

---

## 四、现有数据模型改进建议

### 4.1 `relationship_types` 表扩展

```sql
-- 当前字段：typeKey, typeName, capabilityRole, sortOrder, enabled
-- 建议新增：
ALTER TABLE relationship_types ADD COLUMN category VARCHAR(32) DEFAULT 'family' COMMENT '分类: family/contact/workplace';
ALTER TABLE relationship_types ADD COLUMN is_blood_relation TINYINT(1) DEFAULT 0 COMMENT '是否血缘关系';
ALTER TABLE relationship_types ADD COLUMN is_immediate_family TINYINT(1) DEFAULT 0 COMMENT '是否直系亲属';
```

### 4.2 `family_members` 表扩展

```sql
-- 当前字段：userId, familyId, relationshipType, nickname, avatar, etc.
-- 建议新增：
ALTER TABLE family_members ADD COLUMN is_primary TINYINT(1) DEFAULT 0 COMMENT '是否主要家庭成员';
ALTER TABLE family_members ADD COLUMN permission_level VARCHAR(16) DEFAULT 'member' COMMENT '权限等级: admin/member/restricted';
ALTER TABLE family_members ADD COLUMN joined_at DATETIME COMMENT '加入时间';
```

### 4.3 新增表：`family_member_tags`

```sql
CREATE TABLE family_member_tags (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    family_id BIGINT NOT NULL,
    member_id BIGINT NOT NULL,
    tag_name VARCHAR(32) NOT NULL COMMENT '标签名',
    tag_type VARCHAR(16) DEFAULT 'custom' COMMENT '标签类型: system/custom',
    created_at DATETIME
);
```

### 4.4 新增表：`family_member_logs`

```sql
CREATE TABLE family_member_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    family_id BIGINT NOT NULL,
    member_id BIGINT NOT NULL,
    action VARCHAR(32) NOT NULL COMMENT '操作: join/leave/change_role/change_relation',
    old_value VARCHAR(64) COMMENT '旧值',
    new_value VARCHAR(64) COMMENT '新值',
    operator_id BIGINT COMMENT '操作人',
    created_at DATETIME
);
```

### 4.5 `contacts` 表扩展

```sql
-- 建议新增字段：
ALTER TABLE contacts ADD COLUMN family_member_id BIGINT DEFAULT NULL COMMENT '关联的家庭成员ID';
ALTER TABLE contacts ADD COLUMN invited_status VARCHAR(16) DEFAULT 'none' COMMENT '邀请加入家庭状态: none/invited/accepted/declined';
```

---

## 五、优先级建议

| 优先级 | 需求 | 工作估 | 依赖 |
|:------:|------|:------:|:----:|
| **P0** | 关系类型体系扩展（属性/有效期/权限） | 2-3 天 | 后端实体改、管理端 UI |
| **P0** | 联系人→家庭成员升级路径 | 3-4 天 | 后端 API + 前端组件 |
| **P0** | 家庭关系时间线 | 3-5 天 | 新建表 + 后端 + 前端 |
| **P1** | 关系图增强交互 | 2-3 天 | 前端组件改 |
| **P1** | 成员标签系统 | 2-3 天 | 新建表 + 管理端 |
| **P1** | 关系事件提醒 | 2-3 天 | 定时任务 + 消息推送 |
| **P2** | 关系健康度评估 | 5-7 天 | AI 分析 + 可视化 |
| **P2** | 多家庭场景 | 5-8 天 | 架构级改动 |
| **P2** | 家族谱系 | 4-6 天 | 前端组件 + 后端 |

---

## 六、总结

当前关系管理功能覆盖了基本 CRUD 和核心流程（家庭构成、联系人管理、服务商绑定），已经是一个可用的基础版本。主要短板在于：

1. **数据隔离**：联系人和家庭成员是两套独立数据，缺少互通路径
2. **历史缺失**：关系变更无记录，无法回溯
3. **交互单薄**：关系图展示能力强但交互弱（仅查看、无编辑）
4. **智能不足**：无关系分析、健康度评估等 AI 能力

建议 P0 需求在 1-2 个迭代内完成，补齐基础能力；P1 优化体验；P2 作为 AI 差异化能力规划。

---

*文档版本: v0.1*
*日期: 2026-06-26*