# 后端功能实施方案

## 概述

以下功能需要后端服务支持，目前应用是纯前端应用（使用 IndexedDB 本地存储）。要实现这些功能，需要搭建后端服务。

---

## 1. 多用户系统

### 需求分析
- 支持多个用户注册和登录
- 每个用户可以创建和管理自己的家族树
- 用户可以邀请其他用户协作编辑同一个家族树

### 技术方案

#### 后端技术栈选择
- **Node.js + Express** 或 **Next.js API Routes**
- **数据库**: PostgreSQL / MongoDB
- **认证**: NextAuth.js / Auth0 / Supabase Auth

#### 数据模型

```typescript
// 用户表
interface User {
  id: string
  email: string
  name: string
  avatar?: string
  createdAt: string
  updatedAt: string
}

// 家族树表
interface FamilyTree {
  id: string
  name: string // 家族名称，如"李氏家族"
  ownerId: string // 创建者
  rootMemberId: string
  createdAt: string
  updatedAt: string
}

// 家族成员表（扩展现有 FamilyMember）
interface FamilyMember {
  // ... 现有字段
  treeId: string // 所属家族树
}

// 用户-家族树关系表（协作者）
interface TreeCollaborator {
  id: string
  treeId: string
  userId: string
  role: 'owner' | 'editor' | 'viewer'
  invitedBy: string
  invitedAt: string
}
```

#### API 端点

```typescript
// 用户认证
POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me

// 家族树管理
GET    /api/trees              // 获取用户的所有家族树
POST   /api/trees              // 创建新家族树
GET    /api/trees/:id          // 获取家族树详情
PUT    /api/trees/:id          // 更新家族树
DELETE /api/trees/:id          // 删除家族树

// 协作者管理
GET    /api/trees/:id/collaborators
POST   /api/trees/:id/invite   // 邀请协作者
DELETE /api/trees/:id/collaborators/:userId
```

---

## 2. 云端同步

### 需求分析
- 数据自动同步到云端
- 多设备数据同步
- 离线编辑，在线时自动同步
- 冲突检测和解决

### 技术方案

#### 同步策略

**1. 实时同步（推荐）**
- 使用 WebSocket 或 Server-Sent Events
- 每次操作立即同步到服务器
- 其他客户端实时接收更新

**2. 定时同步**
- 每隔一定时间（如 30 秒）同步一次
- 适合网络不稳定的场景

**3. 混合模式**
- 在线时实时同步
- 离线时本地存储
- 重新联网时批量同步

#### 数据同步流程

```typescript
// 同步记录表
interface SyncRecord {
  id: string
  treeId: string
  userId: string
  action: 'create' | 'update' | 'delete'
  entityType: 'member' | 'photo' | 'story'
  entityId: string
  data: any
  timestamp: string
  synced: boolean
}

// 同步 API
POST   /api/sync/push          // 推送本地更改
GET    /api/sync/pull          // 拉取远程更改
GET    /api/sync/status        // 获取同步状态
```

#### 冲突解决策略

1. **最后写入优先（Last Write Wins）**
   - 简单但可能丢失数据
   
2. **版本控制**
   - 每条记录有版本号
   - 冲突时提示用户选择

3. **操作转换（Operational Transformation）**
   - 复杂但最准确
   - 类似 Google Docs 的协作编辑

#### 实现示例（使用 Supabase）

```typescript
// lib/sync.ts
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

// 推送本地更改到云端
export async function pushChanges(changes: SyncRecord[]) {
  const { data, error } = await supabase
    .from('sync_records')
    .insert(changes)
  
  if (error) throw error
  return data
}

// 从云端拉取更改
export async function pullChanges(treeId: string, lastSyncTime: string) {
  const { data, error } = await supabase
    .from('sync_records')
    .select('*')
    .eq('treeId', treeId)
    .gt('timestamp', lastSyncTime)
    .order('timestamp', { ascending: true })
  
  if (error) throw error
  return data
}

// 实时订阅更改
export function subscribeToChanges(treeId: string, callback: (change: any) => void) {
  return supabase
    .channel(`tree:${treeId}`)
    .on('postgres_changes', {
      event: '*',
      schema: 'public',
      table: 'family_members',
      filter: `treeId=eq.${treeId}`
    }, callback)
    .subscribe()
}
```

---

## 3. 权限管理

### 需求分析
- 不同用户有不同的操作权限
- 支持角色：所有者、编辑者、查看者
- 细粒度权限控制

### 权限模型

```typescript
// 角色定义
enum Role {
  OWNER = 'owner',       // 所有者：完全控制
  EDITOR = 'editor',     // 编辑者：可以增删改
  VIEWER = 'viewer'      // 查看者：只读
}

// 权限定义
interface Permission {
  canView: boolean
  canCreate: boolean
  canUpdate: boolean
  canDelete: boolean
  canInvite: boolean
  canExport: boolean
  canManageSettings: boolean
}

// 角色权限映射
const rolePermissions: Record<Role, Permission> = {
  owner: {
    canView: true,
    canCreate: true,
    canUpdate: true,
    canDelete: true,
    canInvite: true,
    canExport: true,
    canManageSettings: true,
  },
  editor: {
    canView: true,
    canCreate: true,
    canUpdate: true,
    canDelete: false,
    canInvite: false,
    canExport: true,
    canManageSettings: false,
  },
  viewer: {
    canView: true,
    canCreate: false,
    canUpdate: false,
    canDelete: false,
    canInvite: false,
    canExport: true,
    canManageSettings: false,
  },
}
```

### 权限检查中间件

```typescript
// middleware/auth.ts
import { NextRequest, NextResponse } from 'next/server'

export async function requireAuth(req: NextRequest) {
  const token = req.headers.get('authorization')
  if (!token) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  
  // 验证 token
  const user = await verifyToken(token)
  if (!user) {
    return NextResponse.json({ error: 'Invalid token' }, { status: 401 })
  }
  
  return user
}

export async function requirePermission(
  userId: string,
  treeId: string,
  permission: keyof Permission
) {
  // 获取用户在该家族树的角色
  const collaborator = await db.treeCollaborators.findFirst({
    where: { userId, treeId }
  })
  
  if (!collaborator) {
    throw new Error('No access to this tree')
  }
  
  const permissions = rolePermissions[collaborator.role]
  if (!permissions[permission]) {
    throw new Error(`Permission denied: ${permission}`)
  }
  
  return true
}
```

### 前端权限控制

```typescript
// hooks/usePermissions.ts
import { useAuth } from './useAuth'
import { useFamilyTree } from './useFamilyTree'

export function usePermissions() {
  const { user } = useAuth()
  const { currentTree } = useFamilyTree()
  
  const [permissions, setPermissions] = useState<Permission>()
  
  useEffect(() => {
    if (user && currentTree) {
      fetchPermissions(user.id, currentTree.id).then(setPermissions)
    }
  }, [user, currentTree])
  
  return permissions
}

// 使用示例
function MemberForm() {
  const permissions = usePermissions()
  
  if (!permissions?.canCreate) {
    return <div>您没有权限添加成员</div>
  }
  
  return <form>...</form>
}
```

---

## 推荐的实施方案

### 方案 A：使用 Supabase（最简单）

**优点**：
- 开箱即用的认证、数据库、实时订阅
- 无需自己搭建后端
- 免费额度足够个人使用
- 自动处理权限和 RLS（Row Level Security）

**步骤**：
1. 创建 Supabase 项目
2. 设计数据库表结构
3. 配置 RLS 规则
4. 集成 Supabase 客户端
5. 迁移现有 IndexedDB 数据

### 方案 B：使用 Next.js API Routes + PostgreSQL

**优点**：
- 完全控制后端逻辑
- 可以部署在 Vercel
- 适合需要复杂业务逻辑的场景

**步骤**：
1. 添加 API Routes
2. 配置数据库（Vercel Postgres / Neon）
3. 实现认证逻辑（NextAuth.js）
4. 实现同步 API
5. 添加权限中间件

### 方案 C：使用 Firebase

**优点**：
- Google 生态系统
- 实时数据库
- 免费额度较大

**步骤**：
1. 创建 Firebase 项目
2. 配置 Firestore
3. 设置 Firebase Auth
4. 配置安全规则
5. 集成 Firebase SDK

---

## 估算工作量

| 功能 | 使用 Supabase | 自建后端 |
|------|--------------|----------|
| 多用户系统 | 2-3 天 | 5-7 天 |
| 云端同步 | 3-5 天 | 7-10 天 |
| 权限管理 | 2-3 天 | 5-7 天 |
| **总计** | **1-2 周** | **3-4 周** |

---

## 下一步行动

1. **选择技术方案**：推荐 Supabase（快速、简单）
2. **数据迁移计划**：设计从 IndexedDB 到云端的迁移方案
3. **逐步实施**：
   - 第一阶段：多用户系统
   - 第二阶段：云端同步
   - 第三阶段：权限管理

---

## 注意事项

1. **数据安全**：
   - 使用 HTTPS
   - 加密敏感数据
   - 定期备份

2. **性能优化**：
   - 使用缓存
   - 分页加载
   - 图片 CDN

3. **用户体验**：
   - 离线优先
   - 乐观更新
   - 友好的错误提示

---

**建议**：如果您想快速实现这些功能，我推荐使用 Supabase。我可以帮您：
1. 设计 Supabase 数据库结构
2. 实现认证和权限
3. 添加实时同步功能

是否需要我开始实施？