签入版本

2026-09-16 13:28:20 +08:00
parent 6cd5e80de0
commit c97d87847f
410 changed files with 68726 additions and 0 deletions
@@ -0,0 +1,120 @@
+# 数据模型（Model）
+
+数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承 `BaseModel` 自动获得通用字段和方法。
+
+## 文件位置
+
+```
+src/modules/link/models.py
+```
+
+## 完整代码
+
+```python
+# +======================================================================
+# | 模块: 友链数据模型层
+# | 说明: 定义友链表结构，继承 BaseModel 获得通用字段与序列化能力
+# +======================================================================
+"""友链数据模型。"""
+
+from sqlalchemy import Column, Integer, String, text
+
+from config.database import DB_PREFIX
+from core.base_model import BaseModel
+
+
+class Link(BaseModel):
+    """友情链接模型"""
+    __tablename__ = DB_PREFIX + "link"
+    __table_args__ = {"comment": "友情链接表"}
+
+    # 链接名称
+    name = Column(String(255), nullable=False, index=True, comment="链接名称")
+    # 链接类型
+    type = Column(String(50), default="", comment="链接类型")
+    # 链接来源
+    form = Column(String(50), default="", comment="链接来源")
+    # 链接图片
+    image = Column(String(500), default="", comment="链接图片")
+    # 链接地址
+    url = Column(String(500), default="", comment="链接地址")
+    # 状态：0-正常 1-停用
+    status = Column(Integer, default=0, server_default=text("0"), comment="状态")
+    # 排序
+    sort = Column(Integer, default=0, server_default=text("0"), comment="排序")
+```
+
+## 代码解析
+
+### 基类继承
+
+```python
+class Link(BaseModel):
+```
+
+| 基类 | 来源 | 提供能力 |
+|:----|:----|:----|
+| `BaseModel` | `core/base_model.py` | 通用字段：id、create_user、create_time、update_user、update_time、is_delete；`to_dict()` 序列化方法（自动排除 password/salt/is_delete） |
+
+:::tip BaseModel 说明
+`BaseModel` 是所有业务模型的基类，提供6个通用审计字段和 `to_dict()` 序列化方法。模型实例不暴露 `save()/delete()` 方法，数据操作通过 Repository 层进行。
+:::
+
+### 表名配置
+
+```python
+__tablename__ = DB_PREFIX + "link"
+```
+
+`DB_PREFIX` 从 `.env` 读取（默认 `tornado_`），最终表名为 `tornado_link`。所有业务表都使用此前缀，便于区分不同应用的同库表。
+
+### 表注释
+
+```python
+__table_args__ = {"comment": "友情链接表"}
+```
+
+使用 `__table_args` 字典设置表注释，同步到数据库元数据。
+
+### 字段定义
+
+```python
+name = Column(String(255), nullable=False, index=True, comment="链接名称")
+```
+
+| 参数 | 说明 |
+|:----|:----|
+| `String(255)` | 字段类型，VARCHAR(255) |
+| `nullable=False` | 非空约束 |
+| `index=True` | 创建索引，加速查询 |
+| `comment` | 字段注释，同步到数据库 |
+
+```python
+status = Column(Integer, default=0, server_default=text("0"), comment="状态")
+```
+
+`default=0` 是 Python 端默认值，`server_default=text("0")` 是数据库端默认值。两者都设置可确保无论通过 ORM 还是直接 SQL 插入，都能正确赋默认值。
+
+### 枚举值约定
+
+状态字段使用 `0` 和 `1` 而非 `1` 和 `2`：
+
+| 字段 | 值 | 含义 |
+|:----|:----|:----|
+| `status` | `0` | 正常 |
+| `status` | `1` | 停用 |
+| `is_delete` | `0` | 未删除 |
+| `is_delete` | `1` | 已删除 |
+
+## 开发要点
+
+1. **所有模型继承 `BaseModel`**：自动获得通用字段和序列化能力
+2. **表名必须加 `DB_PREFIX` 前缀**：`DB_PREFIX + "表名"`
+3. **使用 `__table_args__` 设置表注释**：字典格式 `{"comment": "表注释"}`
+4. **查询频繁的字段设置索引**：`index=True`
+5. **同时设置 `default` 和 `server_default`**：ORM 和直 SQL 都能正确赋默认值
+6. **模型不暴露 save/delete 方法**：数据操作通过 Repository 层进行
+
+## 总结
+
+数据模型通过继承 `BaseModel` 获得通用审计字段和序列化能力。表名使用 `DB_PREFIX` 前缀，字段定义同时设置 Python 端和数据库端默认值。模型只定义表结构，不包含业务逻辑。