数据模型（Model）

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

文件位置

src/modules/system/position/models.py

完整代码

以下为 src/modules/system/position/models.py 的核心代码（省略版权头）：

"""
岗位模型模块
=============================================================

提供岗位管理的数据模型定义，用于定义员工岗位信息。

企业级特性：
    1. 使用枚举类管理状态常量，确保类型安全
    2. 状态文本自动转换，便于前端展示
    3. 便捷的查询方法，提高开发效率
    4. 继承 BaseModel 和 BaseDB，复用通用功能
    5. __init__ 由 BaseModel 统一管理，无需重复定义
"""

from enum import IntEnum
from typing import Optional, List

from src.common.base_db import BaseDB
from src.common.base_model import BaseModel
from config import DB_PREFIX
from sqlalchemy import text
from src.core.database import db
from src.common.utils.request import like_contains


# ============================================================
# 岗位状态枚举
# ============================================================

class PositionStatus(IntEnum):
    """
    岗位状态枚举

    使用 IntEnum 确保类型安全，避免魔法数字。
    可直接用于数据库查询和比较。
    """
    DISABLED = 0  # 停用
    ENABLED = 1  # 启用


# ============================================================
# 岗位模型
# ============================================================

class Position(BaseModel, BaseDB):
    """
    岗位模型

    用于存储员工岗位信息，如：技术总监、产品经理等。
    继承自 BaseModel（通用字段）和 BaseDB（数据库操作方法）。
    """

    # 表名：使用配置前缀 + 模型名
    __tablename__ = DB_PREFIX + "position"
    __table_comment__ = "岗位表"

    # ============================================================
    # 字段定义
    # ============================================================

    # 岗位名称：必填字段，最长255字符
    name = db.Column(
        db.String(255),
        nullable=False,
        index=True,
        comment="岗位名称"
    )

    # 岗位状态：使用枚举确保类型安全
    # 默认值为停用，创建后需手动启用
    status = db.Column(
        db.Integer,
        index=True,
        default=PositionStatus.DISABLED,
        server_default=text('0'),
        comment="岗位状态：0-停用 1-启用"
    )

    # 岗位排序：数值越小越靠前
    sort = db.Column(
        db.Integer,
        default=0,
        server_default=text('0'),
        comment="岗位排序"
    )

    # ============================================================
    # 注意：__init__ 方法在 BaseModel 中已实现，无需重复定义
    # BaseModel 已处理驼峰转换、字段过滤等逻辑
    # ============================================================

    # ============================================================
    # 便捷属性
    # ============================================================

    @property
    def status_text(self) -> str:
        """获取岗位状态文本：将数字状态转换为可读的中文文本"""
        status_map = {
            PositionStatus.DISABLED: '停用',
            PositionStatus.ENABLED: '启用'
        }
        return status_map.get(self.status, '未知')

    @property
    def is_enabled(self) -> bool:
        """判断岗位是否启用"""
        return self.status == PositionStatus.ENABLED

    @property
    def is_disabled(self) -> bool:
        """判断岗位是否停用"""
        return self.status == PositionStatus.DISABLED

    # ============================================================
    # 自定义查询方法
    # ============================================================

    @classmethod
    def get_enabled(cls) -> List['Position']:
        """获取所有启用的岗位，按排序值升序排列"""
        return cls.query.filter(
            cls.is_delete == 0,
            cls.status == PositionStatus.ENABLED
        ).order_by(cls.sort.asc()).all()

    @classmethod
    def get_by_name(cls, name: Optional[str]) -> Optional['Position']:
        """根据岗位名称精确查询"""
        if not name:
            return None
        return cls.query.filter(
            cls.name == name,
            cls.is_delete == 0
        ).first()

    def __repr__(self) -> str:
        return f'岗位：{self.name}'

代码解析

基类继承

class Position(BaseModel, BaseDB):

基类	来源	提供能力
BaseModel	src/common/base_model.py	通用字段：id、create_user、create_time、update_user、update_time、is_delete
BaseDB	src/common/base_db.py	save() 持久化方法（仅 flush，不 commit）、to_dict() 序列化方法

状态枚举

项目推荐使用 IntEnum 管理状态常量，避免魔法数字：

class PositionStatus(IntEnum):
    DISABLED = 0  # 停用
    ENABLED = 1  # 启用

值	含义
0	停用 / 禁用
1	启用 / 在用

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

字段定义风格

项目使用 db.Column（从 src.core.database 导入的 db 实例），而非直接导入 Column：

from src.core.database import db

name = db.Column(db.String(255), nullable=False, index=True, comment="岗位名称")

表名配置

__tablename__ = DB_PREFIX + "position"

DB_PREFIX 从 .env 读取（默认 flask_），最终表名为 flask_position。

开发要点

1. 业务字段仅定义差异部分：通用字段（id、时间、软删除等）由基类自动提供
2. 表名必须加 DB_PREFIX 前缀：保持命名一致性
3. 使用 db.Column 而非直接导入 Column：保持与项目一致的导入风格
4. 状态字段使用 IntEnum：避免魔法数字，提高代码可读性
5. 同时设置 default 和 server_default：确保 ORM 和直 SQL 两种场景都能正确赋默认值
6. __init__ 由 BaseModel 统一管理：无需在子类中重复定义

总结

数据模型继承 BaseModel（公共字段）和 BaseDB（save 方法），表名必须加 DB_PREFIX 前缀。状态字段使用 IntEnum 枚举类管理，字段定义使用 db.Column 风格。__init__ 由 BaseModel 统一处理驼峰转换和字段过滤，子类无需重复定义。