# 数据模型（Model）

数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承基类自动获得通用字段和方法。

## 文件位置

```
src/modules/system/position/models.py
```

## 完整代码

```python
from sqlalchemy import Column, String, Integer, text

from core.base_db import base_db
from core.base_model import base_model
from core.config import DB_PREFIX


class Position(base_model, base_db):
    """岗位模型类"""
    # 表名配置
    __tablename__ = DB_PREFIX + "position"
    __table_comment__ = "岗位表"

    # 业务字段定义
    # 岗位名称
    name = Column(String(255), nullable=False, index=True, comment="岗位名称")
    # 岗位状态：1-在用 2-停用
    status = Column(Integer, default=0, server_default=text('0'), index=True, comment="岗位状态：1-在用 2-停用")
    # 岗位排序
    sort = Column(Integer, default=0, server_default=text('0'), comment="岗位排序")

    def __repr__(self):
        """返回岗位名称作为字符串表示"""
        return '岗位：{}'.format(self.name)
```

## 代码解析

### 基类继承

```python
class Position(base_model, base_db):
```

| 基类 | 来源 | 提供能力 |
|:----|:----|:----|
| `base_model` | `core/base_model.py` | 通用字段：id、create_user、create_time、update_user、update_time、is_delete |
| `base_db` | `core/base_db.py` | `save()` 持久化方法、`delete()` 删除方法、`to_dict()` 序列化方法 |

### 表名配置

```python
__tablename__ = DB_PREFIX + "position"
```

`DB_PREFIX` 从 `.env` 读取（默认 `fastapi_`），最终表名为 `fastapi_position`。所有业务表都使用此前缀，便于区分框架表与业务表。

### 字段定义

```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'), index=True, comment="岗位状态：1-在用 2-停用")
```

`default=0` 是 Python 端默认值，`server_default=text('0')` 是数据库端默认值。两者都设置可确保无论通过 ORM 还是直接 SQL 插入，都能正确赋默认值。

### 枚举值约定

项目中状态字段统一使用整数枚举：

| 值 | 含义 |
|:----|:----|
| 1 | 启用 / 在用 |
| 2 | 停用 / 禁用 |

软删除字段 `is_delete` 由基类提供：`0` = 正常，`1` = 已删除。

## 数据表 DDL（参考）

模型定义对应的 MySQL 建表语句：

```sql
CREATE TABLE `fastapi_position` (
  `name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '岗位名称',
  `status` int DEFAULT '0' COMMENT '岗位状态：1-在用 2-停用',
  `sort` int DEFAULT '0' COMMENT '岗位排序',
  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `create_user` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '创建人',
  `create_time` datetime DEFAULT (now()) COMMENT '创建时间',
  `update_user` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '更新人',
  `update_time` datetime DEFAULT (now()) COMMENT '更新时间',
  `is_delete` int DEFAULT '0' COMMENT '删除标识：0-正常 1-已删除',
  PRIMARY KEY (`id`) USING BTREE,
  KEY `idx_fastapi_position_name` (`name`) USING BTREE,
  KEY `idx_fastapi_position_status` (`status`) USING BTREE,
  KEY `idx_fastapi_position_is_delete` (`is_delete`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=0 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci ROW_FORMAT=DYNAMIC COMMENT='岗位表';
```

:::tip 温馨提示
实际开发中不需要手写 DDL。模型定义完成后，框架会通过 `Base.metadata.create_all()` 自动建表，或通过 `alembic revision --autogenerate` 生成迁移脚本。
:::

## 开发要点

1. **业务字段仅定义差异部分**：通用字段（id、时间、软删除等）由基类自动提供
2. **表名必须加 `DB_PREFIX` 前缀**：保持命名一致性
3. **合理使用索引**：查询频繁的字段（如 name、status）设置 `index=True`
4. **同时设置 `default` 和 `server_default`**：确保 ORM 和直 SQL 两种场景都能正确赋默认值

## 总结

数据模型继承 `base_model`（公共字段）和 `base_db`（save/delete 方法），表名必须加 `DB_PREFIX` 前缀。查询频繁的字段设置索引，同时设置 `default` 和 `server_default` 确保 ORM 和直 SQL 两种场景都能正确赋默认值。