freedakgmail
168 lines
3.9 KiB
Markdown
168 lines
3.9 KiB
Markdown
# 华夏谱 (HuaXiaPu) - 中国家族树管理系统
|
||
|
||
现代化的中国家族树管理系统，支持多用户协作、权限管理、数据导入导出等功能。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**: 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
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
创建 `.env` 文件并配置以下变量：
|
||
|
||
```env
|
||
# 数据库
|
||
DATABASE_URL="postgresql://user:password@localhost:5432/family_tree"
|
||
|
||
# NextAuth
|
||
NEXTAUTH_URL="http://localhost:3000"
|
||
NEXTAUTH_SECRET="your-secret-key-here"
|
||
|
||
# 可选：OAuth 提供商
|
||
# GOOGLE_CLIENT_ID=""
|
||
# GOOGLE_CLIENT_SECRET=""
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── 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！
|