:::tip 文章管理
文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。
:::

## 模块结构

```
application/article/
├── models.py     # 文章模型
├── forms.py      # 表单验证
├── services.py   # 业务逻辑层（自定义函数）
├── views.py      # 视图层
└── urls.py       # 路由配置
```

:::warning 自定义 Service
文章模块因涉及文件处理、富文本清洗、图集解析等复杂逻辑，编写自定义 service 函数而非继承通用模式。
:::

## 文章模型

```python
# application/article/models.py
from application.models import BaseModel

class Article(BaseModel):
    """文章模型类"""
    class Meta:
        db_table = 'django_article'

    category_id = models.IntegerField(null=True, blank=True, verbose_name='分类ID')
    title = models.CharField(max_length=150, null=True, blank=True, verbose_name='文章标题')
    cover = models.CharField(max_length=255, null=True, blank=True, verbose_name='文章封面')
    images = models.TextField(null=True, blank=True, verbose_name='文章图集')
    intro = models.CharField(max_length=255, null=True, blank=True, verbose_name='文章导读')
    content = models.TextField(null=True, blank=True, verbose_name='文章内容')
    author = models.CharField(max_length=100, null=True, blank=True, verbose_name='文章作者')
    status = models.IntegerField(default=0, verbose_name='文章状态：0-正常 1-下架')
    click = models.IntegerField(default=0, verbose_name='文章点击率')
    sort = models.IntegerField(default=0, verbose_name='文章排序')
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `category_id` | int | 所属分类 ID（关联 category 表） |
| `title` | str | 文章标题 |
| `cover` | str | 封面图片路径 |
| `images` | str | 图集路径（逗号分隔） |
| `intro` | str | 文章导读/摘要 |
| `content` | str | 富文本内容（HTML） |
| `author` | str | 文章作者 |
| `status` | int | 状态：0-正常 1-下架 |
| `click` | int | 点击次数（自动统计） |
| `sort` | int | 排序权重 |

## 文章状态流转

```
草稿(0) → 发布(0) → 下架(1) → 重新发布(0)
```

| 状态 | 说明 | 可执行操作 |
|------|------|-----------|
| 0-正常 | 文章已发布，前台可见 | 编辑、下架、删除 |
| 1-下架 | 文章已下架，前台不可见 | 编辑、重新发布、删除 |

## 文件处理机制

文章模块涉及三类文件字段，处理方式各不相同：

### 1. 封面图片（cover）-- save_file

```python
# 新增时
cover = save_file(data.cover, "article") if data.cover else None
```

`save_file(url, directory)` 的处理逻辑：
1. 将前端传来的 URL 还原为磁盘绝对路径
2. 若文件在临时目录（`temp/`），移动到正式目录（`upload/article/日期/`）
3. 返回相对路径存入数据库

### 2. 图集（images）-- _build_images / _parse_images

图集在数据库中存储为逗号分隔的相对路径字符串：

```
/article/20260907/a.png,/article/20260907/b.png
```

前端传入数组，后端拼接为字符串存储：

```python
def _build_images(images_list):
    """将图片列表拼接为逗号分隔的字符串"""
    if not images_list:
        return None
    return ",".join([save_file(img, "article") for img in images_list])

def _parse_images(images_str):
    """将逗号分隔的字符串解析为完整 URL 列表"""
    if not images_str:
        return []
    return [get_file_url(img) for img in images_str.split(",")]
```

### 3. 富文本内容（content）-- save_content

```
原始 HTML → 提取图片 → 迁移文件 → 替换路径 → 设置 alt → 存库
```

```python
from utils.common import save_content

# 处理富文本内容
content = save_content(content, title, "article")
```

## 添加文章

```python
def add_article(request):
    """添加文章"""
    data, error = parse_request_body(request)
    if error:
        return R.failed(msg=error)

    # 表单验证
    form = forms.ArticleForm(data)
    if not form.is_valid():
        return R.failed(msg=regular.get_err(form))

    try:
        cleaned_data = form.cleaned_data

        # 处理封面图片
        cover = save_file(cleaned_data.get('cover'), "article") if cleaned_data.get('cover') else None

        # 处理图集
        images = _build_images(cleaned_data.get('images'))

        # 处理富文本内容
        content = save_content(cleaned_data.get('content'), cleaned_data.get('title'), "article")

        # 创建文章
        Article.objects.create(
            category_id=cleaned_data.get('categoryId'),
            title=cleaned_data.get('title'),
            cover=cover,
            images=images,
            intro=cleaned_data.get('intro'),
            content=content,
            author=cleaned_data.get('author'),
            status=cleaned_data.get('status', 0),
            sort=cleaned_data.get('sort', 0),
            create_user=get_username(request),
            update_user=get_username(request)
        )
        return R.ok(msg="创建成功")
    except Exception as e:
        logging.error(f"添加文章异常: {str(e)}")
        return R.failed(msg="添加失败，请稍后重试")
```

## 查询分页

### 过滤条件

| 参数 | 类型 | 说明 |
|------|------|------|
| `title` | 模糊搜索 | 文章标题 |
| `category_id` | 精确匹配 | 分类 ID |
| `status` | 精确匹配 | 文章状态 |

### 排序规则

按 `sort` 降序 -> `id` 降序。

### 响应数据

```json
{
    "id": 1,
    "title": "DjangoAdmin 3.0 发布",
    "cover": "http://domain/uploads/article/20260908/cover.png",
    "images": ["http://domain/uploads/article/20260908/1.png"],
    "intro": "DjangoAdmin 3.0 正式发布...",
    "content": "<p>文章内容...</p>",
    "author": "admin",
    "status": 0,
    "statusText": "正常",
    "click": 100,
    "sort": 1,
    "categoryId": 1,
    "categoryName": "产品动态",
    "createUser": "admin",
    "createTime": "2026-09-08 10:00:00"
}
```

## API 接口

| 接口 | 方法 | 权限节点 | 说明 |
|------|------|---------|------|
| `/article/page` | GET | `sys:article:page` | 分页查询 |
| `/article/detail/<int:article_id>` | GET | `sys:article:detail` | 详情查询 |
| `/article/add` | POST | `sys:article:add` | 新增文章 |
| `/article/update` | PUT | `sys:article:update` | 编辑文章 |
| `/article/status` | PUT | `sys:article:status` | 设置状态 |
| `/article/delete/<int:article_ids>` | DELETE | `sys:article:delete` | 删除文章（支持批量） |

## 前端实现

### 编辑弹窗

文章编辑弹窗包含：标题、分类选择、封面上传、图集上传、富文本编辑器、状态选择、排序。

```vue
<BasicModal @register="registerModal" @ok="handleSubmit" width="800px">
    <BasicForm @register="registerForm" />
    <!-- 富文本编辑器 -->
    <Editor v-model="formData.content" :defaultConfig="editorConfig" />
</BasicModal>
```

### 文章列表

文章列表页支持按标题、分类、状态筛选，展示封面缩略图和状态标签。

## 总结

文章管理模块是项目中典型的「带文件处理」复杂业务模块，核心特点：

```
1. 自定义 Service：文件处理/富文本清洗/图集解析均为自定义逻辑
2. 三类文件字段：封面（save_file）、图集（逗号分隔）、富文本（save_content）
3. 临时文件迁移：前端上传到临时目录 -> 提交表单后后端迁移到正式目录
4. XSS 防护：富文本经 bleach 白名单清洗
5. 分类关联：通过 category_id 关联分类表
6. 状态管理：支持发布/下架状态切换
7. 点击统计：自动统计文章点击次数
```