增加对于权限控制系统的解释

README.md

@@ -1 +1,196 @@
+# 多级权限控制数据结构说明
+
+## 核心概念
+
+该设计通过 **关键字匹配（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()"