# 家族关系计算器使用文档

## 概述

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

## 功能特点

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

## 使用方法

### 1. 客户端使用（推荐）

```typescript
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使用

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

**响应示例：**
```json
{
  "from": {
    "id": "xxx",
    "name": "王建国"
  },
  "to": {
    "id": "yyy",
    "name": "王明华"
  },
  "relationship": "堂兄弟",
  "path": "fbs",
  "description": "的父亲的哥哥的儿子",
  "success": true
}
```

### 3. 直接使用计算器类

```typescript
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

**返回：**
```typescript
{
  term: string        // 关系称谓
  path: string        // 关系路径
  description: string // 关系描述
  success: boolean    // 是否成功
}
```

#### getDirectRelatives(memberId)
获取成员的直系亲属

**返回：**
```typescript
{
  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 文档](https://github.com/mumuy/relationship)
- [中国亲属关系计算](https://passer-by.com/relationship/)