202 lines
8.2 KiB
Markdown
202 lines
8.2 KiB
Markdown
:::tip 公告/链接/城市
|
||
公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。
|
||
:::
|
||
|
||
## 公告管理
|
||
|
||
### 公告模型
|
||
|
||
```python
|
||
# src/modules/notice/models.py
|
||
# ============================================================
|
||
# 通知公告模型
|
||
# ============================================================
|
||
class Notice(BaseModel, BaseDB):
|
||
"""通知公告模型类"""
|
||
# ============================================================
|
||
# 表名配置
|
||
# ============================================================
|
||
__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, BaseDB):
|
||
"""通知公告模型类"""
|
||
# ============================================================
|
||
# 表名配置
|
||
# ============================================================
|
||
__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, BaseDB):
|
||
"""城市/行政区划模型类"""
|
||
# ============================================================
|
||
# 表名配置
|
||
# ============================================================
|
||
__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 + BaseDB
|
||
2. schema.py：继承 BaseForm，定义 WTForms 字段约束
|
||
3. repository.py：继承 BaseRepository，实现 page / list_enabled
|
||
4. service.py：继承 BaseService，声明 repository / form / model_name
|
||
5. router.py：Blueprint + @check_permission + @check_demo 装饰器
|
||
```
|
||
|
||
## 总结
|
||
|
||
内容管理模块具备以下特点：
|
||
|
||
```
|
||
1. 简单 CRUD：继承 BaseService，声明差异点即可获得完整接口
|
||
2. 公告管理：支持富文本内容、状态管理
|
||
3. 链接管理：友情链接、合作伙伴链接，支持 Logo 图片
|
||
4. 城市管理：省/市/区/街道/社区五级行政区划，含经纬度、拼音等丰富字段
|
||
5. 统一模式：models/schema/repository/service/router 五文件结构
|
||
6. 模块级代理函数：service 末尾暴露代理函数供 router 调用
|
||
```
|