# 多级权限控制数据结构说明

## 核心概念

该设计通过 **关键字匹配（Keyword Matching）** 实现数据行级权限控制，适用于学校、企业等层级组织架构场景。

### 字段定义

| 字段 | 类型 | 说明 |
|------|------|------|
| `key` | `KeywordField(multi=True)` | **身份标识关键字** - 表示用户所属的层级/组织，用于匹配"自己的数据" |
| `manage_key` | `KeywordField(multi=True)` | **管理范围关键字** - 表示用户能管理的数据范围，用于匹配"管辖范围内的数据" |

---

## 权限模型图解

```
数据权限 = (数据.key ∩ 用户.key) ∪ (数据.key ∩ 用户.manage_key)

解释：
- 用户能看到的数据 = 自己的数据 OR 管辖范围内的数据
- 两者都满足"用户权限"（非管理员），只是数据范围不同
```

---

## 具体场景示例

### 场景1：学生视角

**用户：学生A（2024届人工智能1班）**

```json
{
  "name": "张三",
  "role": "学生",
  "key": [
    "2024届人工智能1班",      // 班级（最细粒度）
    "2024届",                 // 年级
    "计算机与人工智能学院"     // 学院
  ],
  "manage_key": []           // 学生没有管理权限
}
```

**数据匹配逻辑：**
- 查询获奖数据时，系统查找 `key` 包含 `"2024届人工智能1班"` 的数据
- 结果：只能看到自己的获奖记录

---

### 场景2：班导师视角

**用户：班导师B（负责2024届人工智能1班）**

```json
{
  "name": "李老师",
  "role": "班导师",
  "key": [
    "计算机与人工智能学院"     // 所属学院
  ],
  "manage_key": [
    "2024届人工智能1班"       // 管理的班级
  ]
}
```

**数据匹配逻辑：**
- 查询时匹配：`key` 包含 `"计算机与人工智能学院"` **OR** `key` 包含 `"2024届人工智能1班"`
- 结果：可以看到
  1. 学院层级的公共数据（通过 `key` 匹配）
  2. 人工智能1班所有学生的获奖数据（通过 `manage_key` 匹配）

---

### 场景3：扩展案例 - 多级管理员

**用户：学院教务C（管理学院所有班级）**

```json
{
  "name": "王教务",
  "role": "教务",
  "key": [
    "计算机与人工智能学院"
  ],
  "manage_key": [
    "2024届人工智能1班",
    "2024届人工智能2班", 
    "2023届软件工程1班",
    "计算机与人工智能学院"    // 管理整个学院
  ]
}
```

**权限效果：**
- 可以查看学院内所有班级的获奖数据
- 仍然只是"用户权限"，只是管理范围更大

---

### 场景4：跨角色对比

| 角色 | key | manage_key | 可见数据范围 |
|------|-----|------------|-------------|
| **学生A** | 班级、年级、学院 | - | 仅自己的记录 |
| **班导师B** | 学院 | 班级 | 所带班级的全部记录 |
| **辅导员** | 学院 | 年级 | 整个年级的全部记录 |
| **院领导** | 学院 | 学院 | 整个学院的全部记录 |
| **校管理员** | 学校 | 学校 | 全校数据（真正的admin） |

---

## 数据结构存储示例

### 用户表（User Index）

```json
{
  "user_id": "stu_2024001",
  "name": "张三",
  "key": ["2024届人工智能1班", "2024届", "计算机与人工智能学院"],
  "manage_key": [],
  "role": "student"
}
```

```json
{
  "user_id": "tch_10086",
  "name": "李老师", 
  "key": ["计算机与人工智能学院"],
  "manage_key": ["2024届人工智能1班"],
  "role": "advisor"
}
```

### 数据表（Award Index）

```json
{
  "award_id": "awd_001",
  "title": "校级编程大赛一等奖",
  "student_name": "张三",
  "key": ["2024届人工智能1班", "2024届", "计算机与人工智能学院"],  // 所属层级
  "created_by": "stu_2024001"
}
```

---

## 查询逻辑伪代码

```python
def get_visible_data(current_user):
    """
    获取当前用户可见的数据
    """
    query = {
        "bool": {
            "should": [
                # 条件1：数据的关键字与用户的key有交集（自己的数据）
                {
                    "terms": {
                        "key": current_user.key
                    }
                },
                # 条件2：数据的关键字与用户的manage_key有交集（管辖的数据）
                {
                    "terms": {
                        "key": current_user.manage_key
                    }
                }
            ],
            "minimum_should_match": 1
        }
    }

    return es.search(index="awards", body=query)
```

---

## 设计优势

1. **扁平化权限**：不需要复杂的角色表（RBAC），通过关键字即可控制权限
2. **灵活扩展**：新增班级/年级只需添加关键字，无需修改权限架构
3. **层级继承**：数据自带完整层级路径（班级→年级→学院），支持多级查询
4. **细粒度控制**：可以精确到班级级别，也可以放宽到学院级别



生产环境用于创建数据库结构的临时命令：
python manage.py shell -c "from elastic.es_connect import create_index_with_mapping; create_index_with_mapping()"