# 数据模型（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 端和数据库端默认值。模型只定义表结构，不包含业务逻辑。