cfc/docs/superpowers/tickets/TASK-P0-001-generation-refactor.md

P0 任务工作票 — 家庭成员辈分重构

任务 ID: TASK-P0-001
优先级: P0（阻塞性）
预计工时: 3-5 天（后端 3d + 前端 2d）
状态: 已实施
负责人: 待分配
关联文档: plans/2026-07-07-家庭成员辈分重构实施计划.md

---

业务背景

当前家庭成员关系使用 relationship_types 表定义关系类型（spouse/parent/child/sibling），存在以下问题：

1. 关系类型与辈分耦合——spouse/parent/child/sibling 混合了辈分和关系性质
2. 无法表达多代关系——缺少祖辈/孙辈等辈分定义
3. 视角转换复杂——需要遍历关系树计算相对标签

辈分重构用 generation（辈分值）模型替代关系类型，简化视角转换逻辑。

---

范围

包含

• 数据库迁移：添加 generation、is_spouse 列，迁移旧数据，删除废弃列和表
• 后端实体/DTO/Service 重写
• 管理端（cfc-web）关系类型管理页面删除，成员添加页面改为辈分选择器
• 小程序前端 GenerationPicker 组件，替换 RelationshipPicker

不包含

• 家庭关系图谱 UI 重设计（已独立完成）
• 成员卡片样式变更（仅数据模型变更）
• 其他维度功能

---

技术方案

数据库变更

-- 迁移 1: 添加新列
ALTER TABLE family_members
  ADD COLUMN generation INT COMMENT '辈分值（0=家庭创建者，+n=向上，-n=向下）',
  ADD COLUMN is_spouse TINYINT(1) DEFAULT 0 COMMENT '是否配偶（同辈）';

-- 迁移 2: 旧数据映射
UPDATE family_members SET generation = 0, is_spouse = 1 WHERE relationship_type = 'spouse';
UPDATE family_members SET generation = 1  WHERE relationship_type = 'parent';
UPDATE family_members SET generation = -1 WHERE relationship_type = 'child';
UPDATE family_members SET generation = 0  WHERE relationship_type = 'sibling';
UPDATE family_members SET generation = 0  WHERE generation IS NULL;

-- 迁移 3: 删除废弃列（确认无引用后）
ALTER TABLE family_members DROP COLUMN relationship_type;
ALTER TABLE family_members DROP COLUMN role_override;

-- 迁移 4: 删除关系类型表
DROP TABLE IF EXISTS relationship_types;

后端改动

文件	改动类型	说明
enums/GenerationLevel.java	新建	7级辈分枚举
entity/FamilyMember.java	修改	删除 relationshipType/roleOverride，新增 generation/isSpouse
dto/FamilyMemberVO.java	修改	删除 relationshipType/relationshipTypeName，新增 generation
dto/AddFamilyMemberDTO.java	新建	relativeMemberId + generationLevel + peerType
service/FamilyMemberService.java	重写	computeEffectiveRole, computeRelativeLabel, addMember, listMembers, toFamilyMemberVO
controller/family/FamilyMembersController.java	修改	更新请求/响应 DTO
config/DatabaseInitializer.java	修改	新增 4 个迁移
mapper/FamilyMemberMapper.java	无改动	-
schema.sql	同步	更新表结构

前端改动

文件	改动类型	说明
utils/generationLevel.js	新建	辈分选项常量（7级 + 同辈类型）
components/GenerationPicker.vue	新建	辈分选择器组件
components/RelationshipPicker.vue	删除	旧关系类型选择器
pages/family/member-add.vue	修改	替换关系类型选择为辈分选择
pages/family/member-edit.vue	修改	同上
cfc-web/src/views/family/member-add.vue	修改	管理端成员添加页面
cfc-web/src/router/family.js	无改动	-

---

API 变更

废弃端点

端点	操作	替代方案
GET /api/family/member/types	获取关系类型列表	删除（前端使用 generationLevel.js 常量）
POST /api/admin/relationship-type/save	保存关系类型	删除（关系类型不再可配置）
POST /api/admin/relationship-type/list	查询关系类型	删除

修改端点

端点	请求体变更	响应体变更
POST /api/family/member/add	{relativeMemberId, generationLevel, peerType?, ...}	{..., generation}
POST /api/family/member/list	无	移除 relationshipType、relationshipTypeName，新增 generation
POST /api/family/member/update	同上	同上

---

验收标准

功能验收

• 添加成员时可选择辈分（7级）和同辈类型（亲兄弟姐妹/配偶）
• 添加配偶后，is_spouse=1，generation=0
• 添加子侄辈后，generation=-1
• 成员列表显示正确的相对标签（"我"、"爸爸"、"妈妈"、"儿子"、"女儿"等）
• 家长切换视角后，相对标签自动更新
• 管理端成员添加页面无关系类型字段

数据迁移验收

• 旧数据 relationship_type='spouse' → generation=0, is_spouse=1
• 旧数据 relationship_type='parent' → generation=1
• 旧数据 relationship_type='child' → generation=-1
• 旧数据 relationship_type='sibling' → generation=0, is_spouse=0
• 迁移后 SELECT relationship_type FROM family_members 返回空

代码质量验收

• mvn clean compile 零错误
• 单元测试覆盖率 ≥ 80%（核心方法）
• LSP 诊断零错误
• grep -r "relationshipType" cfc-backend/src/main/java 返回空
• grep -r "RelationshipType" cfc-backend/src/main/java 返回空
• 前端小程序编译零警告

性能验收

• 成员列表 API 响应时间 ≤ 200ms（100 个成员以内）
• 相对标签计算性能：1000 次调用 ≤ 50ms

---

测试策略

单元测试（后端）

@Test
void computeRelativeLabel_shouldReturnCorrectLabel() {
    // 测试所有辈分组合
    // case: 我 vs 爸爸 (genDiff=1) → "爸爸"
    // case: 我 vs 儿子 (genDiff=-1) → "儿子"
    // case: 我 vs 配偶 (genDiff=0, isSpouse=true) → "配偶"
    // case: 我 vs 兄弟 (genDiff=0, isSpouse=false) → "哥哥"/"弟弟"（按年龄）
}

集成测试（后端）

@Test
void addMember_withGenerationLevel_shouldPersistGeneration() {
    // 添加配偶
    // 验证 generation=0, is_spouse=1
    // 添加子侄辈
    // 验证 generation=-1
}

E2E 测试（前端）

• 添加成员流程：选择参照成员 → 选择辈分 → 填写信息 → 提交成功
• 成员列表：显示正确的相对标签
• 视角切换：切换角色后标签自动更新

---

部署检查清单

• 数据库迁移脚本在预生产环境演练通过
• 生产环境数据库备份完成
• 回滚方案准备（恢复 relationship_type 列和表）
• 管理端关系类型管理页面已下线
• 小程序前端新版本已提交审核
• 监控指标：family_member_add_duration、relative_label_compute_duration

---

回滚计划

触发条件

• 数据迁移失败且无法恢复
• 核心功能（添加成员、成员列表）严重故障
• 性能下降 ≥ 50%

回滚步骤

1. 数据库回滚：恢复 relationship_type、role_override 列，恢复 relationship_types 表
2. 代码回滚：切换至上一版本分支
3. 前端回滚：小程序回滚至旧版本
4. 验证：核心功能恢复，数据无丢失

---

联系信息

• 技术负责人: 见 Git 仓库 MAINTAINERS.md
  
• 产品负责人: 见 PROJECT-OVERVIEW.md 维护字段
  
• DevOps 支持: 见 cfc-backend/start.sh

---

文档结束