chinese-family-tree-2/docs/BUTTON_PERMISSIONS.md

# 🔐 按钮权限分类清单

## 📋 按钮分类

### 一、增删改类按钮（写操作）

#### 1. 增加类（Create）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **添加成员** | 首页、成员列表 | ✅ | ✅ | ❌ |
| **新增成员** | 成员列表 | ✅ | ✅ | ❌ |
| **添加父亲** | 成员详情 | ✅ | ✅ | ❌ |
| **添加母亲** | 成员详情 | ✅ | ✅ | ❌ |
| **添加子女** | 成员详情 | ✅ | ✅ | ❌ |
| **添加配偶** | 成员详情 | ✅ | ✅ | ❌ |
| **创建家族树** | 导航、创建页 | ✅ | ✅ | ❌ |
| **邀请协作者** | 设置 | ✅ | ❌ | ❌ |

#### 2. 修改类（Update）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **编辑** | 成员详情 | ✅ | ✅ | ❌ |
| **保存** | 编辑页面 | ✅ | ✅ | ❌ |
| **修改密码** | 设置 | ✅ | ✅ | ✅ |
| **导入数据** | 设置 | ✅ | ✅ | ❌ |
| **导入GEDCOM** | 设置 | ✅ | ✅ | ❌ |

#### 3. 删除类（Delete）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **删除成员** | 成员详情 | ✅ | ✅ | ❌ |
| **删除家族树** | 导航 | ✅ | ❌ | ❌ |
| **移除协作者** | 设置 | ✅ | ❌ | ❌ |
| **清空数据** | 设置 | ✅ | ❌ | ❌ |
| **清空日志** | 设置 | ✅ | ❌ | ❌ |

---

### 二、查类按钮（读操作）

#### 1. 查看类（View）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **查看详情** | 所有列表 | ✅ | ✅ | ✅ |
| **查看全部** | 首页 | ✅ | ✅ | ✅ |
| **查看族谱图** | 首页、导航 | ✅ | ✅ | ✅ |
| **查看大事记** | 导航 | ✅ | ✅ | ✅ |
| **查看时间线** | 大事记 | ✅ | ✅ | ✅ |
| **查看迁徙记录** | 大事记 | ✅ | ✅ | ✅ |

#### 2. 搜索查询类（Search/Query）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **搜索** | 导航、成员列表 | ✅ | ✅ | ✅ |
| **筛选** | 成员列表 | ✅ | ✅ | ✅ |
| **关系查询** | 族谱图 | ✅ | ✅ | ✅ |
| **计算关系** | 关系计算 | ✅ | ✅ | ✅ |
| **在族谱图中定位** | 成员列表 | ✅ | ✅ | ✅ |

#### 3. 导出类（Export）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **导出数据** | 设置 | ✅ | ✅ | ✅ |
| **导出GEDCOM** | 设置 | ✅ | ✅ | ✅ |
| **导出图片** | 族谱图 | ✅ | ✅ | ✅ |
| **打印** | 成员详情 | ✅ | ✅ | ✅ |

#### 4. 视图控制类（View Control）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **放大** | 族谱图 | ✅ | ✅ | ✅ |
| **缩小** | 族谱图 | ✅ | ✅ | ✅ |
| **重置** | 族谱图 | ✅ | ✅ | ✅ |
| **切换视图** | 族谱图 | ✅ | ✅ | ✅ |
| **切换标签** | 大事记 | ✅ | ✅ | ✅ |

#### 5. 导航类（Navigation）
| 按钮名称 | 位置 | OWNER | EDITOR | VIEWER |
|---------|------|-------|--------|--------|
| **返回** | 所有页面 | ✅ | ✅ | ✅ |
| **取消** | 编辑页面 | ✅ | ✅ | ✅ |
| **关闭** | 对话框 | ✅ | ✅ | ✅ |

---

## 🎯 权限总结

### OWNER（创建者）- 全部权限
**可用按钮**: 80+ 个

#### 独有权限（只有 OWNER 可以）
- ❌ 删除家族树
- ❌ 邀请协作者
- ❌ 移除协作者
- ❌ 清空数据
- ❌ 清空日志

#### 完整权限列表
- ✅ 所有增加操作
- ✅ 所有修改操作
- ✅ 所有删除操作
- ✅ 所有查看操作
- ✅ 所有管理操作

---

### EDITOR（编辑者）- 编辑权限
**可用按钮**: 60+ 个

#### 可以执行的操作
- ✅ 添加成员（所有类型）
- ✅ 编辑成员信息
- ✅ 删除成员
- ✅ 导入数据
- ✅ 所有查看操作
- ✅ 所有查询操作
- ✅ 所有导出操作

#### 不能执行的操作
- ❌ 删除家族树
- ❌ 邀请协作者
- ❌ 移除协作者
- ❌ 清空数据
- ❌ 清空日志

---

### VIEWER（查看者）- 只读权限
**可用按钮**: 30+ 个

#### 可以执行的操作
- ✅ 查看所有信息
- ✅ 搜索和筛选
- ✅ 关系查询
- ✅ 导出数据
- ✅ 打印
- ✅ 视图控制（放大、缩小等）
- ✅ 修改自己的密码

#### 不能执行的操作
- ❌ 添加成员
- ❌ 编辑成员
- ❌ 删除成员
- ❌ 导入数据
- ❌ 删除家族树
- ❌ 管理协作者
- ❌ 清空数据

---

## 💻 代码实现

### 1. 权限检查函数

```typescript
// lib/permissions.ts
export type Role = "OWNER" | "EDITOR" | "VIEWER"

export const permissions = {
  // 增加权限
  canCreate: (role: Role) => role === "OWNER" || role === "EDITOR",
  
  // 修改权限
  canUpdate: (role: Role) => role === "OWNER" || role === "EDITOR",
  
  // 删除成员权限
  canDeleteMember: (role: Role) => role === "OWNER" || role === "EDITOR",
  
  // 删除家族树权限（仅 OWNER）
  canDeleteTree: (role: Role) => role === "OWNER",
  
  // 管理协作者权限（仅 OWNER）
  canManageCollaborators: (role: Role) => role === "OWNER",
  
  // 清空数据权限（仅 OWNER）
  canClearData: (role: Role) => role === "OWNER",
  
  // 查看权限（所有人）
  canView: (role: Role) => true,
  
  // 导出权限（所有人）
  canExport: (role: Role) => true,
}
```

### 2. 按钮权限控制

```tsx
// 方式1: 条件渲染（推荐）
import { permissions } from "@/lib/permissions"

{permissions.canCreate(role) && (
  <Button onClick={handleAdd}>
    <Plus className="h-4 w-4 mr-2" />
    添加成员
  </Button>
)}

{permissions.canDeleteTree(role) && (
  <Button variant="destructive" onClick={handleDeleteTree}>
    删除家族树
  </Button>
)}

// 方式2: 禁用状态
<Button 
  disabled={!permissions.canUpdate(role)}
  onClick={handleEdit}
>
  编辑
</Button>
```

### 3. 完整示例

```tsx
// components/member-actions.tsx
import { permissions } from "@/lib/permissions"
import { useFamily } from "@/context/family-context"

export function MemberActions({ memberId }: { memberId: string }) {
  const { currentTree } = useFamily()
  const role = currentTree?.currentUserRole
  
  if (!role) return null
  
  return (
    <div className="flex gap-2">
      {/* 查看按钮 - 所有人可见 */}
      <Button variant="outline" onClick={handleView}>
        查看详情
      </Button>
      
      {/* 编辑按钮 - OWNER 和 EDITOR 可见 */}
      {permissions.canUpdate(role) && (
        <Button variant="outline" onClick={handleEdit}>
          <Edit className="h-4 w-4 mr-2" />
          编辑
        </Button>
      )}
      
      {/* 删除按钮 - OWNER 和 EDITOR 可见 */}
      {permissions.canDeleteMember(role) && (
        <Button variant="destructive" onClick={handleDelete}>
          <Trash className="h-4 w-4 mr-2" />
          删除
        </Button>
      )}
    </div>
  )
}
```

---

## 📊 权限对比表

| 操作类型 | OWNER | EDITOR | VIEWER | 说明 |
|---------|-------|--------|--------|------|
| **查看信息** | ✅ | ✅ | ✅ | 所有人可查看 |
| **搜索查询** | ✅ | ✅ | ✅ | 所有人可查询 |
| **导出数据** | ✅ | ✅ | ✅ | 所有人可导出 |
| **添加成员** | ✅ | ✅ | ❌ | 编辑权限 |
| **编辑成员** | ✅ | ✅ | ❌ | 编辑权限 |
| **删除成员** | ✅ | ✅ | ❌ | 编辑权限 |
| **导入数据** | ✅ | ✅ | ❌ | 编辑权限 |
| **邀请协作者** | ✅ | ❌ | ❌ | 仅创建者 |
| **删除家族树** | ✅ | ❌ | ❌ | 仅创建者 |
| **清空数据** | ✅ | ❌ | ❌ | 仅创建者 |

---

## 🔍 快速查找

### 需要 OWNER 权限的按钮（5个）
1. 删除家族树
2. 邀请协作者
3. 移除协作者
4. 清空数据
5. 清空日志

### 需要 EDITOR 权限的按钮（25个）
1. 所有"添加"按钮（8个）
2. 所有"编辑"按钮（5个）
3. 删除成员（1个）
4. 导入相关（2个）
5. 其他编辑操作（9个）

### VIEWER 可用的按钮（30个）
1. 所有"查看"按钮（6个）
2. 所有"搜索"按钮（5个）
3. 所有"导出"按钮（4个）
4. 所有"视图控制"按钮（5个）
5. 所有"导航"按钮（10个）

---

## 📝 实施检查清单

### 代码实施
- [ ] 创建权限检查函数 (`lib/permissions.ts`)
- [ ] 更新所有按钮组件，添加权限检查
- [ ] 测试 OWNER 权限
- [ ] 测试 EDITOR 权限
- [ ] 测试 VIEWER 权限

### API 层面
- [ ] API 路由添加权限验证
- [ ] 数据库操作添加权限检查
- [ ] 返回适当的错误信息

### 用户界面
- [ ] 无权限的按钮隐藏或禁用
- [ ] 添加权限提示信息
- [ ] 测试所有页面的权限显示

### 文档更新
- [ ] 更新用户手册
- [ ] 更新 API 文档
- [ ] 更新开发文档

---

**文档版本**: v1.0  
**最后更新**: 2025-11-23  
**维护人员**: System