chinese-family-tree-2/docs/RELATIONSHIP_CALCULATOR.md

家族关系计算器使用文档

概述

本项目集成了 relationship.js 库，用于精确计算中文亲属关系。

功能特点

• ✅ 100% 准确的关系计算
• ✅ 支持复杂的中文称谓系统
• ✅ 自动处理堂/表、伯/叔等细微区别
• ✅ 支持多代关系计算
• ✅ 客户端和服务端双重支持

使用方法

1. 客户端使用（推荐）

import { useRelationship } from '@/hooks/use-relationship'

function MyComponent() {
  const { calculateRelationship } = useRelationship()
  
  // 计算关系
  const result = calculateRelationship('memberA_id', 'memberB_id')
  
  console.log(result.term)         // "堂兄弟"
  console.log(result.path)         // "fbs"
  console.log(result.description)  // "的父亲的哥哥的儿子"
}

2. API使用

GET /api/trees/[treeId]/relationship?from=xxx&to=yyy

响应示例：

{
  "from": {
    "id": "xxx",
    "name": "王建国"
  },
  "to": {
    "id": "yyy",
    "name": "王明华"
  },
  "relationship": "堂兄弟",
  "path": "fbs",
  "description": "的父亲的哥哥的儿子",
  "success": true
}

3. 直接使用计算器类

import { RelationshipCalculator } from '@/lib/relationship-calculator'

const members = [...] // FamilyMember[]
const calculator = new RelationshipCalculator(members)

const result = calculator.getRelationshipDetail('fromId', 'toId')

关系路径说明

基本路径符号

符号	含义	示例
f	父亲	f = 父亲
m	母亲	m = 母亲
h	丈夫	h = 丈夫
w	妻子	w = 妻子
s	儿子	s = 儿子
d	女儿	d = 女儿
ob	哥哥	ob = 哥哥
lb	弟弟	lb = 弟弟
os	姐姐	os = 姐姐
ls	妹妹	ls = 妹妹

组合路径示例

路径	关系	说明
f	父亲	直接父子关系
m	母亲	直接母子关系
ff	爷爷	父亲的父亲
fm	奶奶	父亲的母亲
mf	外公	母亲的父亲
mm	外婆	母亲的母亲
fbs	堂兄弟	父亲的哥哥的儿子
mbs	表兄弟	母亲的哥哥的儿子
ffs	伯父/叔父	父亲的父亲的儿子
fss	孙子	儿子的儿子

Hook API

useRelationship()

返回对象包含以下方法：

calculateRelationship(fromId, toId)

计算两个成员之间的关系（客户端）

参数：

• fromId: 起始成员ID
• toId: 目标成员ID

返回：

{
  term: string        // 关系称谓
  path: string        // 关系路径
  description: string // 关系描述
  success: boolean    // 是否成功
}

getDirectRelatives(memberId)

获取成员的直系亲属

返回：

{
  father: FamilyMember | null
  mother: FamilyMember | null
  spouses: FamilyMember[]
  children: FamilyMember[]
}

getSiblings(memberId)

获取成员的所有兄弟姐妹

返回： FamilyMember[]

getAncestors(memberId, maxGenerations?)

获取成员的所有祖先

参数：

• memberId: 成员ID
• maxGenerations: 最大代数（默认10）

返回： FamilyMember[]

getDescendants(memberId, maxGenerations?)

获取成员的所有后代

参数：

• memberId: 成员ID
• maxGenerations: 最大代数（默认10）

返回： FamilyMember[]

测试页面

访问 /relationship-test 查看关系计算器的演示页面。

支持的关系类型

直系关系

• 父亲、母亲
• 儿子、女儿
• 爷爷、奶奶、外公、外婆
• 孙子、孙女、外孙、外孙女

旁系关系

• 兄弟、姐妹
• 堂兄弟、表兄弟
• 伯父、叔父、姑姑
• 舅舅、姨妈
• 侄子、外甥

姻亲关系

• 丈夫、妻子
• 公公、婆婆、岳父、岳母
• 女婿、儿媳

注意事项

1. 年龄判断：兄弟姐妹的称谓（哥哥/弟弟/姐姐/妹妹）基于出生年份判断
2. 路径长度：关系路径越长，计算时间越长，建议限制在10代以内
3. 无关系：如果两人没有血缘或姻亲关系，返回"无血缘关系"
4. 数据完整性：确保家族数据中的父母、配偶、子女关系完整

性能优化

• 使用BFS算法，时间复杂度 O(V + E)
• 客户端计算，无需网络请求
• 支持缓存计算结果

扩展功能

可以基于关系计算器实现：

1. 智能称呼建议：自动提示如何称呼某个亲戚
2. 关系可视化：绘制关系路径图
3. 辈分计算：自动计算辈分差异
4. 家族统计：统计各种关系的数量
5. 关系验证：检查家族数据的一致性

相关资源

• relationship.js 文档
• 中国亲属关系计算