231 lines
7.0 KiB
Markdown
231 lines
7.0 KiB
Markdown
:::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>
|
||
<n-button type="primary" @click="handleAdd">新增链接</n-button>
|
||
</template>
|
||
</BasicTable>
|
||
</PageWrapper>
|
||
</template>
|
||
```
|
||
|
||
## 总结
|
||
|
||
内容管理模块具备以下特点：
|
||
|
||
```
|
||
1. 简单 CRUD：标准增删改查接口，遵循五层架构
|
||
2. 公告管理：支持富文本内容、封面图片、类型区分（通知/公告）
|
||
3. 链接管理：友情链接，支持 Logo 图片、排序权重、状态管理
|
||
4. 统一模式：models/forms/services/views/urls 五层结构
|
||
5. XSS 防护：富文本内容自动过滤危险标签
|
||
6. 状态管理：支持启用/停用状态切换
|
||
```
|