chore: 基线提交（重构前代码快照）

- git 初始化 + .gitignore 补全（根 .env / logs / instance / __pycache__ 等） - 修复 utils/.gitignore 误将整个 utils/ 源码层忽略的问题，补入全部工具源码（含 ip2region.xdb） - 含后端全部代码：application / extensions / utils / config / migrations - 含前端 ui/（后续整体迁走） - 不含根 .env（含密钥，本地保留） Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-07 12:12:06 +08:00
commit 15f2a5e097
591 changed files with 95894 additions and 0 deletions
@@ -0,0 +1,218 @@
+"""
+文章表单验证模块
+=============================================================
+
+提供文章相关的表单验证功能，包括：
+- 文章添加/更新表单验证
+- 文章状态设置表单验证
+"""
+
+from wtforms import IntegerField, StringField, TextAreaField
+from wtforms.validators import NumberRange, DataRequired, Length, Optional
+
+from application.forms.base_form import BaseForm
+
+
+# ============================================================
+# 文章表单验证（添加和更新共用）
+# ============================================================
+
+class ArticleForm(BaseForm):
+    """
+    文章表单验证类
+
+    用于添加和更新文章时的数据验证。
+    添加时 id 为 None，更新时 id 必须有值。
+
+    Attributes:
+        id: 文章ID（更新时必填，添加时可选）
+        categoryId: 分类ID（可选）
+        title: 文章标题（可选，最长150字符）
+        cover: 文章封面（可选，最长255字符）
+        images: 文章图集（可选，JSON格式）
+        intro: 文章导读（可选，最长255字符）
+        content: 文章内容（可选）
+        author: 文章作者（可选，最长100字符）
+        status: 文章状态（可选，0-正常，1-下架）
+        sort: 文章排序（可选，0-99999之间的整数）
+    """
+
+    # ============================================================
+    # 文章ID
+    # ============================================================
+    id = IntegerField(
+        label='文章ID',
+        validators=[
+            Optional(),
+            NumberRange(min=1, message='文章ID必须大于0')
+        ],
+        description='文章唯一标识，更新时必填，添加时自动生成'
+    )
+
+    # ============================================================
+    # 分类ID
+    # ============================================================
+    categoryId = IntegerField(
+        label='分类ID',
+        validators=[
+            Optional(),
+            NumberRange(min=0, message='分类ID必须大于等于0')
+        ],
+        description='文章所属分类ID'
+    )
+
+    # ============================================================
+    # 文章标题
+    # ============================================================
+    title = StringField(
+        label='文章标题',
+        validators=[
+            Optional(),
+            Length(max=150, message='文章标题长度不得超过150个字符')
+        ],
+        description='文章标题'
+    )
+
+    # ============================================================
+    # 文章封面（逗号分隔的图片路径）
+    # ============================================================
+    cover = StringField(
+        label='文章封面',
+        validators=[
+            Optional(),
+            Length(max=255, message='文章封面路径长度不得超过255个字符')
+        ],
+        description='文章封面图片URL'
+    )
+
+    # ============================================================
+    # 文章图集
+    # ============================================================
+    images = TextAreaField(
+        label='文章图集',
+        validators=[
+            Optional()
+        ],
+        description='文章图集，JSON格式存储多张图片'
+    )
+
+    # ============================================================
+    # 文章导读
+    # ============================================================
+    intro = StringField(
+        label='文章导读',
+        validators=[
+            Optional(),
+            Length(max=255, message='文章导读长度不得超过255个字符')
+        ],
+        description='文章简介/导读'
+    )
+
+    # ============================================================
+    # 文章内容
+    # ============================================================
+    content = TextAreaField(
+        label='文章内容',
+        validators=[
+            Optional()
+        ],
+        description='文章正文内容，支持富文本'
+    )
+
+    # ============================================================
+    # 文章作者
+    # ============================================================
+    author = StringField(
+        label='文章作者',
+        validators=[
+            Optional(),
+            Length(max=100, message='文章作者长度不得超过100个字符')
+        ],
+        description='文章作者名称'
+    )
+
+    # ============================================================
+    # 文章状态
+    # ============================================================
+    status = IntegerField(
+        label='文章状态',
+        validators=[
+            Optional(),
+            NumberRange(min=0, max=1, message='文章状态值在0~1之间')
+        ],
+        description='文章状态：0-正常，1-下架'
+    )
+
+    # ============================================================
+    # 文章排序
+    # ============================================================
+    sort = IntegerField(
+        label='文章排序',
+        validators=[
+            Optional(),
+            NumberRange(min=0, max=99999, message='文章排序值在0~99999之间')
+        ],
+        description='排序值，数值越小越靠前'
+    )
+
+    # # ============================================================
+    # # 自定义验证方法
+    # # ============================================================
+    #
+    # def validate_images(self, field):
+    #     """
+    #     自定义验证：验证images字段是否为有效的JSON格式
+    #
+    #     Args:
+    #         field: images 字段对象
+    #
+    #     Raises:
+    #         ValidationError: JSON格式无效时抛出验证错误
+    #     """
+    #     if field.data:
+    #         try:
+    #             # 尝试解析JSON
+    #             if isinstance(field.data, str):
+    #                 json.loads(field.data)
+    #         except json.JSONDecodeError:
+    #             raise ValidationError("图集格式无效，请传入有效的JSON数组")
+
+
+# ============================================================
+# 文章状态设置表单
+# ============================================================
+
+class ArticleStatusForm(BaseForm):
+    """
+    文章状态设置表单验证类
+
+    用于单独修改文章状态时的数据验证。
+
+    Attributes:
+        id: 文章ID（必填，必须大于0）
+        status: 文章状态（必填，0-正常，1-下架）
+    """
+
+    # ============================================================
+    # 文章ID
+    # ============================================================
+    id = IntegerField(
+        label='文章ID',
+        validators=[
+            DataRequired(message='文章ID不能为空'),
+            NumberRange(min=1, message='文章ID必须大于0')
+        ],
+        description='要修改状态的文章ID'
+    )
+
+    # ============================================================
+    # 文章状态
+    # ============================================================
+    status = IntegerField(
+        label='文章状态',
+        validators=[
+            DataRequired(message='文章状态不能为空'),
+            NumberRange(min=0, max=1, message='文章状态值在0~1之间')
+        ],
+        description='目标状态：0-正常，1-下架'
+    )