freedakgmail
211 lines
4.8 KiB
Markdown
211 lines
4.8 KiB
Markdown
# 家族关系计算器使用文档
|
||
|
||
## 概述
|
||
|
||
本项目集成了 `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/)
|