# family-tree

**Repository Path**: chen_chong/family-tree

## Basic Information

- **Project Name**: family-tree
- **Description**: 家谱 兼容PC端和移动端 react + node + express框架 + JWT + MySQL
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-04-23
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI编程, 族谱or家谱, 全栈, 前端

## README

# 家谱管理系统开发文档

## 1. 项目概述

### 1.1 项目简介
家谱管理系统是一个基于 React + Node.js 的全栈 Web 应用，用于管理和展示家族谱系信息。

### 1.2 技术栈
- **前端**: React 18 + Vite + React Router
- **后端**: Node.js + Express + MySQL
- **数据库**: MySQL 8.0
- **认证**: JWT + Session

### 1.3 项目结构
```
familyTree/
├── client/                 # 前端项目
│   ├── src/
│   │   ├── api/           # API 接口
│   │   ├── components/    # 公共组件
│   │   ├── hooks/         # 自定义 Hooks
│   │   ├── pages/         # 页面组件
│   │   ├── utils/         # 工具函数
│   │   └── styles/        # 样式文件
│   └── package.json
├── server/                 # 后端项目
│   ├── controllers/       # 控制器
│   ├── middleware/        # 中间件
│   ├── models/            # 数据模型
│   ├── routes/            # 路由
│   ├── utils/             # 工具函数
│   └── config/            # 配置文件
├── database/              # 数据库脚本
└── doc/                   # 文档
```

## 2. 功能模块

### 2.1 用户认证模块

#### 2.1.1 注册功能
- **路径**: `/register`
- **功能**: 用户注册，包含图形验证码验证
- **验证码类型**: 数学计算题（加减法）
- **接口**:
  - `POST /api/auth/register` - 用户注册
  - `GET /api/captcha/image` - 获取验证码图片

#### 2.1.2 登录功能
- **路径**: `/login`
- **功能**: 用户登录，支持密码错误次数限制
- **安全策略**:
  - 连续失败 3 次后需要输入验证码
  - 15 分钟内有效
  - 登录成功后重置失败次数
- **接口**:
  - `POST /api/auth/login` - 用户登录
  - `GET /api/auth/check-status?username={username}` - 检查是否需要验证码

#### 2.1.3 图形验证码
- **路径**: `/api/captcha/image`
- **功能**: 生成数学计算验证码
- **特性**:
  - 随机加减法算式
  - SVG 格式图片
  - 干扰线和噪点
  - 5 分钟有效期
  - Session 存储答案

### 2.2 家族管理模块

#### 2.2.1 家族列表
- **路径**: `/families`
- **功能**: 展示用户创建或加入的家族列表
- **操作**: 创建家族、查看详情、删除家族

#### 2.2.2 家谱展示
- **路径**: `/family/:id`
- **功能**: 树形结构展示家族成员
- **特性**: 支持展开/折叠、拖拽查看

### 2.3 成员管理模块

#### 2.3.1 成员列表
- **功能**: 列表形式展示家族成员
- **操作**: 添加、编辑、删除成员

#### 2.3.2 成员信息
- **字段**:
  - 基本信息：姓名、性别、出生日期
  - 关系信息：父母、配偶、子女
  - 其他信息：联系方式、头像、排序

## 3. API 接口文档

### 3.1 认证接口

#### 注册
```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "confirmPassword": "string",
  "captcha": "string"
}
```

#### 登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "username": "string",
  "password": "string",
  "captcha": "string"  // 需要时必填
}
```

#### 检查登录状态
```http
GET /api/auth/check-status?username={username}
```

#### 获取用户信息
```http
GET /api/auth/profile
Authorization: Bearer {token}
```

### 3.2 验证码接口

#### 获取验证码图片
```http
GET /api/captcha/image
```

### 3.3 家族接口

#### 获取家族列表
```http
GET /api/families
Authorization: Bearer {token}
```

#### 创建家族
```http
POST /api/families
Authorization: Bearer {token}
Content-Type: application/json

{
  "family_name": "string",
  "intro": "string"
}
```

### 3.4 成员接口

#### 获取成员列表
```http
GET /api/members?familyId={id}
Authorization: Bearer {token}
```

#### 添加成员
```http
POST /api/members
Authorization: Bearer {token}
Content-Type: application/json

{
  "family_id": "number",
  "name": "string",
  "gender": "number",
  "birth": "date",
  "parent_id": "number",
  "spouse_name": "string",
  "generation": "number"
}
```

## 4. 数据库设计

### 4.1 用户表 (users)
```sql
CREATE TABLE `users` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `username` varchar(50) NOT NULL COMMENT '用户名',
  `password` varchar(255) NOT NULL COMMENT '加密密码',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 4.2 家族表 (families)
```sql
CREATE TABLE `families` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `family_name` varchar(100) NOT NULL COMMENT '家族名称',
  `intro` varchar(500) DEFAULT NULL COMMENT '家族简介',
  `founder_id` int(11) NOT NULL COMMENT '创建者ID',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `founder_id` (`founder_id`),
  CONSTRAINT `families_ibfk_1` FOREIGN KEY (`founder_id`) REFERENCES `users` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 4.3 成员表 (family_members)
```sql
CREATE TABLE `family_members` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `family_id` int(11) NOT NULL COMMENT '所属家族ID',
  `user_id` int(11) NOT NULL COMMENT '关联用户ID',
  `name` varchar(50) NOT NULL COMMENT '成员姓名',
  `gender` tinyint(4) DEFAULT '0' COMMENT '性别：0-未知，1-男，2-女',
  `birth` date DEFAULT NULL COMMENT '出生日期',
  `death_date` date DEFAULT NULL COMMENT '过世日期',
  `relation` varchar(50) DEFAULT NULL COMMENT '与创建者关系',
  `phone` varchar(20) DEFAULT NULL COMMENT '联系方式',
  `marriage_status` varchar(20) DEFAULT '未婚',
  `ranking` varchar(20) DEFAULT NULL COMMENT '排行',
  `life_status` varchar(20) DEFAULT '在世',
  `generation` int(11) DEFAULT '1' COMMENT '世代',
  `parent_id` int(11) DEFAULT NULL COMMENT '父/母ID',
  `spouse_name` varchar(50) DEFAULT NULL COMMENT '配偶姓名',
  `avatar` varchar(255) DEFAULT NULL COMMENT '头像URL',
  `sort_order` int(11) DEFAULT '0' COMMENT '排序顺序',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `family_id` (`family_id`),
  KEY `user_id` (`user_id`),
  KEY `parent_id` (`parent_id`),
  CONSTRAINT `family_members_ibfk_1` FOREIGN KEY (`family_id`) REFERENCES `families` (`id`) ON DELETE CASCADE,
  CONSTRAINT `family_members_ibfk_2` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE,
  CONSTRAINT `family_members_ibfk_3` FOREIGN KEY (`parent_id`) REFERENCES `family_members` (`id`) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

## 5. 安全机制

### 5.1 密码安全
- 使用 bcrypt 加密存储
- 最小长度 6 位

### 5.2 认证安全
- JWT Token 认证
- Token 有效期可配置

### 5.3 验证码安全
- **注册验证码**: 必须验证，5 分钟有效期
- **登录验证码**: 连续失败 3 次触发，15 分钟窗口期
- Session 存储，一次性使用

### 5.4 接口安全
- CORS 配置
- 请求限流（建议后续添加）

## 6. 环境配置

### 6.1 后端环境变量 (.env)
```env
PORT=3000
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=family_tree
JWT_SECRET=your_jwt_secret
SESSION_SECRET=your_session_secret
```

### 6.2 前端配置
- 开发环境代理配置在 `vite.config.js`
- API 基础路径 `/api`

## 7. 启动命令

### 7.1 后端启动
```bash
cd server
npm install
npm run dev
```

### 7.2 前端启动
```bash
cd client
npm install
npm run dev
```

## 8. 部署说明

### 8.1 生产环境配置
1. 修改 `.env.production` 数据库配置
2. 设置 `secure: true`（HTTPS）
3. 配置 Nginx 反向代理

### 8.2 数据库初始化
```bash
mysql -u root -p < database/sql.sql
```

## 9. 开发规范

### 9.1 代码规范
- 使用 ESLint 进行代码检查
- 组件使用函数式组件 + Hooks
- API 请求统一封装

### 9.2 Git 规范
- 提交信息清晰明了
- 功能分支开发
- `uploads/` 目录已加入 .gitignore

## 10. 后续优化建议

1. **性能优化**: 成员数据分页加载
2. **安全增强**: 接口限流、IP 黑名单
3. **功能扩展**: 家族相册、活动记录
4. **移动端**: 响应式优化或开发小程序
5. **数据导出**: 支持 PDF/Excel 导出家谱