公告/链接/城市

公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。

公告管理

公告模型

# src/modules/notice/models.py
# ============================================================
# 通知公告模型
# ============================================================
class Notice(base_model, base_db):
    """通知公告模型类"""
    # ============================================================
    # 表名配置
    # ============================================================
    __tablename__ = DB_PREFIX + "notice"
    __table_comment__ = "通知公告表"

    # ============================================================
    # 字段定义
    # ============================================================
    # 通知标题
    title = Column(String(255), nullable=False, index=True, comment="通知标题")
    # 通知封面
    cover = Column(String(255), nullable=True, comment="通知封面")
    # 通知类型：1-通知 2-公告
    type = Column(Integer, default=1, server_default=text('1'), index=True, comment="通知类型：1-通知 2-公告")
    # 点击率
    click_num = Column(Integer, default=0, server_default=text('0'), comment="点击率")
    # 通知状态：1-正常 2-停用
    status = Column(Integer, default=1, server_default=text('1'), index=True, comment="通知状态：1-正常 2-停用")
    # 通知公告内容
    content = Column(Text, nullable=True, comment="通知公告内容")

    # ============================================================
    # 内置方法
    # ============================================================
    def __str__(self):
        """返回通知标题作为字符串表示"""
        return "通知公告{}".format(self.title)

API 接口

接口	方法	权限节点	说明
/api/v1/notice/list	GET	sys:notice:list	公告列表
/api/v1/notice/add	POST	sys:notice:add	新增公告
/api/v1/notice/update	PUT	sys:notice:update	编辑公告
/api/v1/notice/delete/{id}	DELETE	sys:notice:delete	删除公告

链接管理

链接模型

# src/modules/link/models.py
# ============================================================
# 通知公告模型
# ============================================================
class Notice(base_model, base_db):
    """通知公告模型类"""
    # ============================================================
    # 表名配置
    # ============================================================
    __tablename__ = DB_PREFIX + "notice"
    __table_comment__ = "通知公告表"

    # ============================================================
    # 字段定义
    # ============================================================
    # 通知标题
    title = Column(String(255), nullable=False, index=True, comment="通知标题")
    # 通知封面
    cover = Column(String(255), nullable=True, comment="通知封面")
    # 通知类型：1-通知 2-公告
    type = Column(Integer, default=1, server_default=text('1'), index=True, comment="通知类型：1-通知 2-公告")
    # 点击率
    click_num = Column(Integer, default=0, server_default=text('0'), comment="点击率")
    # 通知状态：1-正常 2-停用
    status = Column(Integer, default=1, server_default=text('1'), index=True, comment="通知状态：1-正常 2-停用")
    # 通知公告内容
    content = Column(Text, nullable=True, comment="通知公告内容")

    # ============================================================
    # 内置方法
    # ============================================================
    def __str__(self):
        """返回通知标题作为字符串表示"""
        return "通知公告{}".format(self.title)

API 接口

接口	方法	权限节点	说明
/api/v1/link/list	GET	sys:link:list	链接列表
/api/v1/link/add	POST	sys:link:add	新增链接
/api/v1/link/update	PUT	sys:link:update	编辑链接
/api/v1/link/delete/{id}	DELETE	sys:link:delete	删除链接

城市管理

城市模型

# src/modules/city/models.py
# ============================================================
# 城市模型
# ============================================================
class City(base_model, base_db):
    """城市/行政区划模型类"""
    # ============================================================
    # 表名配置
    # ============================================================
    __tablename__ = DB_PREFIX + "city"
    __table_comment__ = "城市行政区划表"

    # ============================================================
    # 字段定义
    # ============================================================
    # 城市区号
    city_code = Column(String(6), nullable=False, index=True, comment="城市区号")
    # 行政编码
    area_code = Column(String(20), nullable=False, index=True, comment="行政编码")
    # 上级行政编码（顶级/省级无上级，为 NULL）
    parent_code = Column(String(20), nullable=True, index=True, comment="上级行政编码")
    # 邮政编码
    zip_code = Column(String(6), nullable=False, comment="邮政编码")
    # 城市级别：0-省份 1-城市 2-县区 3-街道 4-社区
    level = Column(Integer, default=0, server_default=text('0'), index=True, comment="城市级别：0-省份 1-城市 2-县区 3-街道 4-社区")
    # 上级城市ID
    pid = Column(Integer, default=0, server_default=text('0'), index=True, comment="上级城市ID")
    # 城市名称
    name = Column(String(150), nullable=False, index=True, comment="城市名称")
    # 城市简称
    short_name = Column(String(150), nullable=False, comment="城市简称")
    # 城市全称
    full_name = Column(String(150), nullable=True, comment="城市全称")
    # 城市拼音
    pinyin = Column(String(150), nullable=True, comment="城市拼音")
    # 城市经度
    lng = Column(String(150), nullable=True, comment="城市经度")
    # 城市纬度
    lat = Column(String(150), nullable=True, comment="城市纬度")

    # ============================================================
    # 内置方法
    # ============================================================
    def __str__(self):
        """返回城市ID作为字符串表示"""
        return '城市{}'.format(self.id)

树形结构

城市通过 parent_code 字段形成五级行政区划树形结构（省-市-区-街道-社区），level 字段标识级别：

中国 (parent_code=null, level=0)
├── 广东省 (parent_code=100000, level=0)
│ ├── 深圳市 (parent_code=440000, level=1)
│ │ ├── 南山区 (parent_code=440300, level=2)
│ │ │ └── 粤海街道 (parent_code=440305, level=3)
│ │ └── 福田区 (parent_code=440300, level=2)
│ └── 广州市 (parent_code=440000, level=1)
└── 浙江省 (parent_code=100000, level=0)
 └── 杭州市 (parent_code=330000, level=1)

行政区划与用户关联

用户表通过 province_code、city_code、district_code、street_code 四个字段关联城市表的 area_code，city_info 字段存储拼接后的城市名称（如"广东省深圳市南山区"）。

通用模式

三个模块均遵循相同的开发模式：

1. models.py：继承 base_model + base_db
2. schemas.py：继承 BaseForm，定义 Field 约束
3. repository.py：继承 BaseRepository，模块级单例
4. service.py：继承 BaseService，声明差异字段
5. endpoints：@permission_required + @check_demo 装饰器

总结

内容管理模块具备以下特点：

1. 简单 CRUD：继承 BaseService，声明差异点即可获得完整接口
2. 公告管理：支持富文本内容、状态管理
3. 链接管理：友情链接、合作伙伴链接，支持 Logo 图片
4. 城市管理：省/市/区/街道/社区五级行政区划，含经纬度、拼音等丰富字段
5. 统一模式：models/schemas/repository/service/endpoints 五层结构
6. 模块级单例：repository 和 service 均在文件末尾创建单例实例