:::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: ## 公告管理 ### 公告模型 ```python # src/modules/notice/models.py # ============================================================ # 通知公告模型 # ============================================================ class Notice(BaseModel): """通知公告模型类""" # ============================================================ # 表名配置 # ============================================================ __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` | 删除公告 | ## 链接管理 ### 链接模型 ```python # src/modules/link/models.py # ============================================================ # 通知公告模型 # ============================================================ class Notice(BaseModel): """通知公告模型类""" # ============================================================ # 表名配置 # ============================================================ __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` | 删除链接 | ## 城市管理 ### 城市模型 ```python # src/modules/city/models.py # ============================================================ # 城市模型 # ============================================================ class City(BaseModel): """城市/行政区划模型类""" # ============================================================ # 表名配置 # ============================================================ __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) ``` :::tip 行政区划与用户关联 用户表通过 `province_code`、`city_code`、`district_code`、`street_code` 四个字段关联城市表的 `area_code`，`city_info` 字段存储拼接后的城市名称（如"广东省深圳市南山区"）。 ::: ## 通用模式 三个模块均遵循相同的开发模式： ``` 1. models.py：继承 BaseModel 2. schemas.py：继承 BaseSchema，定义 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 均在文件末尾创建单例实例 ```