签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,207 @@
+# View层规范
+
+## 概述
+
+View 层负责处理 HTTP 请求和返回响应，使用 Django 类视图（Class-Based Views）。每个视图类对应一个 API 端点，通过装饰器实现登录验证、权限检查和操作日志记录。
+
+:::tip 设计原则
+- 使用类视图（继承 `View`）
+- 通过 `@method_decorator(check_login)` 验证登录
+- 通过 `PermissionRequired` mixin 检查权限
+- 通过 `@operation_log` 记录操作日志
+- 写操作检查 `DJANGO_DEMO` 演示模式
+:::
+
+## 完整示例
+
+以案例模块为例，`application/example/views.py`：
+
+```python
+from django.utils.decorators import method_decorator
+from django.views import View
+from application.example import services
+from config.env import DJANGO_DEMO
+from middleware.login_middleware import check_login
+from middleware.permission_middleware import PermissionRequired
+from utils import R
+from application.operation_log.constants import LogType
+from application.operation_log.decorators import operation_log
+
+
+# =============================================================
+# 分页查询视图
+# =============================================================
+
+@method_decorator(check_login, name="get")
+class ExamplePageView(PermissionRequired, View):
+    """案例分页数据查询视图"""
+    permission_required = ("sys:example:page",)
+
+    @operation_log(title="案例管理-查询分页列表", log_type=LogType.QUERY)
+    def get(self, request):
+        result = services.get_example_page(request)
+        return result
+
+
+# =============================================================
+# 详情查询视图
+# =============================================================
+
+@method_decorator(check_login, name="get")
+class ExampleDetailView(PermissionRequired, View):
+    """案例详情查询视图"""
+    permission_required = ("sys:example:detail",)
+
+    @operation_log(title="案例管理-查询记录详情", log_type=LogType.QUERY)
+    def get(self, request, id):
+        data = services.get_example_detail(id)
+        return R.ok(data=data)
+
+
+# =============================================================
+# 添加视图
+# =============================================================
+
+@method_decorator(check_login, name="post")
+class ExampleAddView(PermissionRequired, View):
+    """添加案例视图"""
+    permission_required = ("sys:example:add",)
+
+    @operation_log(title="案例管理-添加记录", log_type=LogType.ADD)
+    def post(self, request):
+        # 演示环境禁止操作
+        if DJANGO_DEMO:
+            return R.failed("演示环境，暂无操作权限")
+
+        result = services.add_example(request)
+        return result
+
+
+# =============================================================
+# 更新视图
+# =============================================================
+
+@method_decorator(check_login, name="put")
+class ExampleUpdateView(PermissionRequired, View):
+    """更新案例视图"""
+    permission_required = ('sys:example:update',)
+
+    @operation_log(title="案例管理-更新记录", log_type=LogType.UPDATE)
+    def put(self, request):
+        # 演示环境禁止操作
+        if DJANGO_DEMO:
+            return R.failed("演示环境，暂无操作权限")
+
+        result = services.update_example(request)
+        return result
+
+
+# =============================================================
+# 删除视图（支持批量）
+# =============================================================
+
+@method_decorator(check_login, name="delete")
+class ExampleDeleteView(PermissionRequired, View):
+    """删除案例视图"""
+    permission_required = ('sys:example:delete',)
+
+    @operation_log(title="案例管理-删除记录", log_type=LogType.DELETE)
+    def delete(self, request, id):
+        # 演示环境禁止操作
+        if DJANGO_DEMO:
+            return R.failed("演示环境，暂无操作权限")
+
+        result = services.delete_examples(id)
+        return result
+
+
+# =============================================================
+# 状态更新视图
+# =============================================================
+
+@method_decorator(check_login, name="put")
+class ExampleStatusView(PermissionRequired, View):
+    """设置案例状态视图"""
+    permission_required = ('sys:example:status',)
+
+    def put(self, request):
+        # 演示环境禁止操作
+        if DJANGO_DEMO:
+            return R.failed("演示环境，暂无操作权限")
+
+        result = services.update_example_status(request)
+        return result
+```
+
+## 装饰器说明
+
+### @method_decorator(check_login)
+
+验证 JWT 登录状态，从 `Authorization: Bearer <token>` 头解析用户信息。未登录返回 401。
+
+```python
+@method_decorator(check_login, name="get")  # 验证 GET 请求
+@method_decorator(check_login, name="post") # 验证 POST 请求
+@method_decorator(check_login, name="put")  # 验证 PUT 请求
+@method_decorator(check_login, name="delete") # 验证 DELETE 请求
+```
+
+### PermissionRequired
+
+权限检查 mixin，用户 ID 为 1 的超级管理员自动跳过权限检查。
+
+```python
+class ExamplePageView(PermissionRequired, View):
+    permission_required = ("sys:example:page",)  # 权限标识
+```
+
+### @operation_log
+
+操作日志记录装饰器，自动记录请求参数、响应结果、执行时间等。
+
+```python
+@operation_log(title="案例管理-添加记录", log_type=LogType.ADD)
+```
+
+日志类型：
+
+| 类型 | 说明 |
+|:----|:----|
+| `LogType.QUERY` | 查询操作 |
+| `LogType.ADD` | 添加操作 |
+| `LogType.UPDATE` | 更新操作 |
+| `LogType.DELETE` | 删除操作 |
+
+## 演示模式检查
+
+写操作（add/update/delete/status）需检查 `DJANGO_DEMO` 配置：
+
+```python
+if DJANGO_DEMO:
+    return R.failed("演示环境，暂无操作权限")
+```
+
+## 权限标识规范
+
+| 操作 | 权限标识 | 说明 |
+|:----|:----|:----|
+| 分页查询 | `sys:{module}:page` | 查询分页数据 |
+| 列表查询 | `sys:{module}:list` | 查询列表数据 |
+| 详情查询 | `sys:{module}:detail` | 查询单条详情 |
+| 添加 | `sys:{module}:add` | 添加记录 |
+| 更新 | `sys:{module}:update` | 更新记录 |
+| 删除 | `sys:{module}:delete` | 删除记录 |
+| 状态 | `sys:{module}:status` | 更新状态 |
+
+## View 层职责
+
+View 层只负责：
+1. 接收 HTTP 请求
+2. 调用 Service 层函数
+3. 返回 R 响应
+
+禁止在 View 层直接操作数据库或编写业务逻辑。
+
+## 总结
+
+View 层使用 Django 类视图，通过装饰器实现登录验证（`check_login`）、权限检查（`PermissionRequired`）和操作日志记录（`operation_log`）。写操作检查 `DJANGO_DEMO` 演示模式。View 层只负责请求分发和响应返回，业务逻辑集中在 Service 层。