chinese-family-tree-2/README.md

# 华夏家谱 (HuaXiaJiaPu) - 中国家族树管理系统

现代化的中国家族树管理系统，支持多用户协作、权限管理、数据导入导出等功能。

## 技术栈

- **前端**: Next.js 16, React 19, TypeScript, TailwindCSS
- **后端**: Next.js API Routes, Prisma ORM
- **数据库**: PostgreSQL
- **认证**: NextAuth.js
- **UI组件**: shadcn/ui, Radix UI
- **图标**: Lucide Icons

## 功能特性

### 核心功能
- ✅ 家族树可视化展示
- ✅ 成员信息管理（基本信息、照片、故事）
- ✅ 多家族树支持
- ✅ 用户认证与授权
- ✅ 协作者管理（所有者、编辑者、查看者）
- ✅ 操作日志记录
- ✅ GEDCOM 格式导入导出
- ✅ 数据备份与恢复

### 权限系统
- **所有者 (OWNER)**: 完全控制权限
- **编辑者 (EDITOR)**: 可以编辑成员信息
- **查看者 (VIEWER)**: 只读访问权限

## 快速开始

### 环境要求
- Node.js 18+
- PostgreSQL 14+
- pnpm (推荐)

### 安装

```bash
# 克隆项目
git clone <repository-url>
cd chinese-family-tree

# 安装依赖
pnpm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接和认证密钥

# 初始化数据库
pnpm prisma generate
pnpm prisma db push

# 运行开发服务器
pnpm dev
```

访问 http://localhost:3000

### 生产构建

```bash
# 构建
pnpm build

# 启动生产服务器
pnpm start
```

### 生产部署

#### 一键部署脚本

项目提供了自动化部署脚本，支持一键部署到远程服务器：

```bash
# 1. 编辑 deploy.sh 配置服务器信息
# 2. 运行部署脚本
./deploy.sh
```

部署脚本会自动完成：
- SSH密钥配置
- 服务器环境检查
- 本地构建项目
- 文件上传
- 数据库初始化
- PM2进程管理

#### 服务器要求
- 操作系统：Ubuntu 20.04+ / CentOS 7+ / Debian 10+
- 内存：至少 2GB RAM
- 磁盘：至少 10GB 可用空间
- PostgreSQL 14+

### 常见问题

#### 重定向循环问题 (ERR_TOO_MANY_REDIRECTS)

如果遇到重定向循环错误：
1. 检查 `NEXTAUTH_URL` 是否与实际访问URL一致
2. 清除浏览器缓存和Cookie
3. 重启应用：`ssh user@server 'pm2 restart chinese-family-tree'`

#### 其他问题

- 查看应用日志：`ssh user@server 'pm2 logs chinese-family-tree'`
- 检查数据库连接：`npx prisma db pull`
- 重启应用：`ssh user@server 'pm2 restart chinese-family-tree'`

## 环境变量

创建 `.env` 文件并配置以下变量：

```env
# 数据库
DATABASE_URL="postgresql://user:password@localhost:5432/family_tree"

# NextAuth
# ⚠️ 重要: NEXTAUTH_URL 必须与实际访问URL完全一致
# 开发环境:
NEXTAUTH_URL="http://localhost:3000"
# 生产环境示例:
# NEXTAUTH_URL="http://your-server-ip:port"
# NEXTAUTH_URL="https://your-domain.com"

NEXTAUTH_SECRET="your-secret-key-here"

# 邮箱服务器配置（用于发送邀请邮件）
SMTP_HOST="smtp.163.com"
SMTP_PORT="465"
SMTP_USER="cftservice@163.com"
SMTP_PASS="your-smtp-password"
SMTP_FROM="中华家谱 <cftservice@163.com>"

# 可选：OAuth 提供商
# GOOGLE_CLIENT_ID=""
# GOOGLE_CLIENT_SECRET=""
```

> **⚠️ 重要提示**: `NEXTAUTH_URL` 必须与实际访问URL完全一致，否则会导致重定向循环问题 (ERR_TOO_MANY_REDIRECTS)

## 项目结构

```
├── app/                    # Next.js App Router
│   ├── api/               # API 路由
│   ├── auth/              # 认证页面
│   ├── members/           # 成员管理
│   ├── settings/          # 设置页面
│   └── tree/              # 家族树可视化
├── components/            # React 组件
│   ├── ui/               # UI 基础组件
│   ├── members/          # 成员相关组件
│   └── settings/         # 设置相关组件
├── context/              # React Context
├── lib/                  # 工具函数
├── prisma/               # 数据库 Schema
└── types/                # TypeScript 类型定义
```

## 数据库 Schema

主要数据表：
- `User`: 用户信息
- `FamilyTree`: 家族树
- `FamilyMember`: 家族成员
- `TreeCollaborator`: 协作者
- `ActivityLog`: 操作日志

## API 路由

### 认证
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/signin` - 用户登录

### 家族树
- `GET /api/trees` - 获取家族树列表
- `POST /api/trees` - 创建家族树
- `GET /api/trees/[treeId]` - 获取单个家族树
- `PUT /api/trees/[treeId]` - 更新家族树
- `DELETE /api/trees/[treeId]` - 删除家族树

### 成员
- `GET /api/trees/[treeId]/members` - 获取成员列表
- `POST /api/trees/[treeId]/members` - 创建成员
- `PUT /api/trees/[treeId]/members/[memberId]` - 更新成员
- `DELETE /api/trees/[treeId]/members/[memberId]` - 删除成员

### 协作者
- `GET /api/trees/[treeId]/collaborators` - 获取协作者列表
- `POST /api/trees/[treeId]/collaborators` - 添加协作者
- `DELETE /api/trees/[treeId]/collaborators` - 移除协作者

### 操作日志
- `GET /api/trees/[treeId]/activity-logs` - 获取操作日志
- `DELETE /api/trees/[treeId]/activity-logs` - 清空操作日志（仅所有者）

## 开发指南

### 代码规范
- 使用 TypeScript 严格模式
- 遵循 ESLint 规则
- 使用 Prettier 格式化代码

### 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建/工具相关

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

lsof -ti:3000 | xargs kill -9 2>/dev/null; echo "端口已清理"

pnpm dev