签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,230 @@
+:::tip 公告/链接
+公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。适用于系统公告、友情链接等场景。
+:::
+
+## 公告管理
+
+### 公告模型
+
+```python
+# application/notice/models.py
+from application.models import BaseModel
+
+class Notice(BaseModel):
+    """通知公告模型类"""
+    class Meta:
+        db_table = 'django_notice'
+
+    title = models.CharField(max_length=255, verbose_name='通知标题')
+    cover = models.CharField(max_length=255, null=True, blank=True, verbose_name='通知封面')
+    type = models.IntegerField(default=1, verbose_name='通知类型：1-通知 2-公告')
+    click_num = models.IntegerField(default=0, verbose_name='点击率')
+    status = models.IntegerField(default=1, verbose_name='通知状态：1-正常 2-停用')
+    content = models.TextField(null=True, blank=True, verbose_name='通知公告内容')
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `title` | str | 通知标题 |
+| `cover` | str | 封面图片路径 |
+| `type` | int | 类型：1-通知 2-公告 |
+| `click_num` | int | 点击次数（自动统计） |
+| `status` | int | 状态：1-正常 2-停用 |
+| `content` | str | 富文本内容（HTML） |
+
+### API 接口
+
+| 接口 | 方法 | 权限节点 | 说明 |
+|------|------|---------|------|
+| `/notice/page` | GET | `sys:notice:page` | 公告分页列表 |
+| `/notice/detail/<int:id>` | GET | `sys:notice:detail` | 公告详情 |
+| `/notice/add` | POST | `sys:notice:add` | 新增公告 |
+| `/notice/update` | PUT | `sys:notice:update` | 编辑公告 |
+| `/notice/delete/<int:id>` | DELETE | `sys:notice:delete` | 删除公告 |
+
+### 分页查询参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `pageNo` | int | 页码 |
+| `pageSize` | int | 每页条数 |
+| `title` | str | 标题（模糊查询） |
+| `type` | int | 类型：1-通知 2-公告 |
+| `status` | int | 状态：1-正常 2-停用 |
+
+### 富文本内容处理
+
+公告内容使用富文本编辑器，支持 HTML 格式：
+
+```python
+# 添加公告时，content 字段接收 HTML 内容
+Notice.objects.create(
+    title="系统升级通知",
+    type=1,
+    status=1,
+    content="<p>系统将于<strong>2026-09-10</strong>进行升级维护...</p>",
+    create_user=get_username(request)
+)
+```
+
+:::warning XSS 防护
+富文本内容存储前需进行 XSS 过滤，防止恶意脚本注入。项目内置了 `utils/common.py` 中的 `clean_html()` 函数用于过滤危险标签。
+:::
+
+## 链接管理
+
+### 链接模型
+
+```python
+# application/link/models.py
+from application.models import BaseModel
+
+class Link(BaseModel):
+    """友情链接模型类"""
+    class Meta:
+        db_table = 'django_link'
+
+    name = models.CharField(max_length=255, verbose_name='链接名称')
+    image = models.CharField(max_length=255, null=True, blank=True, verbose_name='链接图片')
+    url = models.CharField(max_length=255, null=True, blank=True, verbose_name='链接地址')
+    status = models.IntegerField(default=1, verbose_name='链接状态：1-正常 2-停用')
+    sort = models.IntegerField(default=0, verbose_name='排序')
+    note = models.CharField(max_length=255, null=True, blank=True, verbose_name='备注')
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | str | 链接名称 |
+| `image` | str | 链接 Logo 图片路径 |
+| `url` | str | 链接地址 |
+| `status` | int | 状态：1-正常 2-停用 |
+| `sort` | int | 排序权重（数字越小越靠前） |
+| `note` | str | 备注信息 |
+
+### API 接口
+
+| 接口 | 方法 | 权限节点 | 说明 |
+|------|------|---------|------|
+| `/link/page` | GET | `sys:link:page` | 链接分页列表 |
+| `/link/detail/<int:id>` | GET | `sys:link:detail` | 链接详情 |
+| `/link/add` | POST | `sys:link:add` | 新增链接 |
+| `/link/update` | PUT | `sys:link:update` | 编辑链接 |
+| `/link/delete/<int:id>` | DELETE | `sys:link:delete` | 删除链接 |
+| `/link/status` | PUT | `sys:link:status` | 设置状态 |
+
+### 分页查询参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `pageNo` | int | 页码 |
+| `pageSize` | int | 每页条数 |
+| `name` | str | 链接名称（模糊查询） |
+| `status` | int | 状态：1-正常 2-停用 |
+
+### 响应示例
+
+```json
+{
+    "code": 0,
+    "data": {
+        "records": [
+            {
+                "id": 1,
+                "name": "Django 官方网站",
+                "image": "/uploads/link/django.png",
+                "url": "https://www.djangoproject.com",
+                "status": 1,
+                "statusText": "正常",
+                "sort": 1,
+                "note": "Python Web 框架",
+                "createUser": "admin",
+                "createTime": "2026-09-08 10:00:00"
+            }
+        ],
+        "total": 10,
+        "size": 10,
+        "current": 1,
+        "pages": 1
+    },
+    "msg": "操作成功",
+    "ok": true
+}
+```
+
+## 通用模式
+
+两个模块均遵循相同的开发模式：
+
+```
+1. models.py：继承 BaseModel，定义业务字段
+2. forms.py：继承 Django Form，定义字段约束和验证规则
+3. services.py：实现 CRUD 业务逻辑函数
+4. views.py：PermissionRequired + check_login 装饰器
+5. urls.py：路由配置，映射 URL 到视图类
+```
+
+### 文件结构
+
+```
+application/notice/              application/link/
+├── models.py                    ├── models.py
+├── forms.py                     ├── forms.py
+├── services.py                  ├── services.py
+├── views.py                     ├── views.py
+├── urls.py                      ├── urls.py
+├── apps.py                      ├── apps.py
+└── admin.py                     └── admin.py
+```
+
+## 前端实现
+
+### 公告编辑弹窗
+
+公告编辑使用富文本编辑器，支持图片上传：
+
+```vue
+<template>
+    <BasicModal @register="registerModal" @ok="handleSubmit">
+        <BasicForm @register="registerForm" />
+        <!-- 富文本编辑器 -->
+        <div class="editor-container">
+            <Toolbar :editor="editorRef" />
+            <Editor v-model="content" :defaultConfig="editorConfig" />
+        </div>
+    </BasicModal>
+</template>
+```
+
+### 链接列表页
+
+链接列表页使用 BasicTable 组件，支持状态切换和排序：
+
+```vue
+<template>
+    <PageWrapper>
+        <BasicForm @register="registerSearch" />
+        <BasicTable @register="registerTable">
+            <template #tableTitle>
+                <el-button type="primary" @click="handleAdd">新增链接</el-button>
+            </template>
+        </BasicTable>
+    </PageWrapper>
+</template>
+```
+
+## 总结
+
+内容管理模块具备以下特点：
+
+```
+1. 简单 CRUD：标准增删改查接口，遵循五层架构
+2. 公告管理：支持富文本内容、封面图片、类型区分（通知/公告）
+3. 链接管理：友情链接，支持 Logo 图片、排序权重、状态管理
+4. 统一模式：models/forms/services/views/urls 五层结构
+5. XSS 防护：富文本内容自动过滤危险标签
+6. 状态管理：支持启用/停用状态切换
+```