简介
本设计文档聚焦 DouPHP 辅助功能模块的数据库表结构设计，覆盖区域管理、品牌展示、证书管理与文件下载等能力。文档从表结构、字段语义、状态与权限控制、数据关联、扩展性等方面给出系统化说明，并配合类图、时序图与流程图帮助管理员与开发者快速理解与落地。
项目结构
围绕辅助功能的四个核心领域：
- 区域（area）：地区树形结构，支持层级与排序。
- 品牌（brand）：品牌信息、图片、SEO、点击统计与启用状态。
- 证书（certificate）：资质证书列表，支持创建者类型与ID、启用状态与排序。
- 下载（download）：文件下载条目，含分类、链接、大小、内容、SEO、状态与时间戳；配套分类表 download_category。
graph TB
subgraph "辅助功能"
A["区域表 dou_area"]
B["品牌表 dou_brand"]
C["证书表 dou_certificate"]
D["下载表 dou_download"]
E["下载分类表 dou_download_category"]
end
D --> E核心组件
- 区域表（dou_area）：以 parent_id 实现树形结构，name 存储名称，iso_code_2/iso_code_3 提供标准代码，sort 控制排序。
- 品牌表（dou_brand）：包含品牌名、分组、介绍、图片、SEO 字段、点击数、排序与启用状态，以及创建时间。
- 证书表（dou_certificate）：记录证书名称、图片、排序、启用状态，并通过 operator_type/operator_id 标识创建者（如管理员或员工）。
- 下载表（dou_download）：与文章表结构相近，额外包含 download_link 与 size；通过 category_id 关联下载分类；具备 SEO、内容、状态、时间戳等通用字段。
- 下载分类表（dou_download_category）：用于对下载资源进行分类组织，被 download.category_id 引用。
架构总览
辅助功能的数据访问由“后台模型 + 核心/前台服务”共同完成：
- 区域：核心服务 AreaService 负责读取与缓存，后台模型 Area 提供写入白名单与子级判断。
- 品牌：后台模型 Brand 定义 casts/prefetchers，统一图片与时间格式化。
- 证书：前台模型 Certificate 声明多语言 name、附件 URL 预热与发布过滤。
- 下载：后台模型 Download 定义分类关联、筛选与默认排序策略。
classDiagram
class AreaModel {
+table = "area"
+fillable
+hasChildArea(id) bool
}
class AreaCoreService {
+loadAllAreas()
}
class BrandModel {
+table = "brand"
+casts
+prefetchers
}
class CertificateModel {
+table = "certificate"
+translatable
+prefetchers
+findPublishedById(id)
}
class DownloadModel {
+table = "download"
+category()
+scopeFilterByKeyword(query, keyword)
+scopeApplyDefaultOrder(query)
}
class DownloadCategoryModel {
+table = "download_category"
+recordsTable = "download"
}
DownloadModel --> DownloadCategoryModel : "belongsTo(category_id)"
AreaCoreService --> AreaModel : "读取/缓存"详细组件分析
区域表（dou_area）
- 设计要点
- 树形结构：parent_id 指向父级，根节点通常为 0。
- 标准化编码：iso_code_2/iso_code_3 便于国际化与对接。
- 排序：sort 控制显示顺序。
- 业务逻辑
- 列表加载采用全量缓存并按 sort 与 id 排序，减少重复查询。
- 删除前需校验是否存在子区域，避免破坏树结构。
- 权限与状态
- 无显式 status 字段，通常通过业务层控制可见性与编辑权限。
- 扩展建议
- 如需多级国家/省市区，可在现有 parent_id 上继续扩展层级。
- 可追加拼音首字母、经纬度等检索与展示字段。
flowchart TD
Start(["开始"]) --> Load["加载全部区域<br/>按 sort ASC, id ASC"]
Load --> Cache{"是否命中缓存"}
Cache --> |是| ReturnCache["返回缓存结果"]
Cache --> |否| QueryDB["查询 dou_area 表"]
QueryDB --> BuildTree["构建父子树结构"]
BuildTree --> SetCache["写入缓存"]
SetCache --> ReturnData["返回数据"]
ReturnCache --> End(["结束"])
ReturnData --> End品牌表（dou_brand）
- 设计要点
- 基础信息：name、class（分组）、content（介绍）。
- 媒体与SEO：image、keywords、description。
- 行为统计：click 记录点击次数。
- 展示控制：sort 排序，status 启用/禁用，created_at 创建时间。
- 业务逻辑
- 列表渲染时对 image 进行附件URL转换，对 created_at 进行日期格式化。
- 可通过 status 控制前端展示与后台可见性。
- 权限与状态
- 使用 status 控制启用/禁用；结合后台权限控制编辑与删除。
- 扩展建议
- 可增加外链、品牌Logo多尺寸、品牌标签等字段。
sequenceDiagram
participant Admin as "后台界面"
participant Model as "Brand 模型"
participant DB as "数据库"
Admin->>Model : 请求品牌列表
Model->>DB : 查询 dou_brand
DB-->>Model : 返回品牌记录
Model->>Model : 格式化 image / created_at
Model-->>Admin : 返回列表数据证书表（dou_certificate）
- 设计要点
- 创建者追踪：operator_type（admin/work）+ operator_id 组合索引 idx_operator，便于按创建者查询。
- 基本信息：name、image、sort、status、created_at。
- 业务逻辑
- 前台列表走 AR 模型，自动处理图片附件URL、多语言 name、url 预热。
- 提供 findPublishedById 仅返回已发布记录。
- 权限与状态
- status 控制启用/禁用；operator_type/operator_id 可用于区分不同角色创建的证书。
- 扩展建议
- 可增加有效期、颁发机构、编号等字段以满足合规展示需求。
sequenceDiagram
participant Front as "前台页面"
participant Service as "CertificateService"
participant Model as "Certificate 模型"
participant DB as "数据库"
Front->>Service : 获取证书详情
Service->>Model : findPublishedById(id)
Model->>DB : 查询 dou_certificate (已发布)
DB-->>Model : 返回记录
Model->>Model : 格式化 image / name(多语言) / url
Model-->>Service : 返回对象
Service-->>Front : 渲染详情下载表（dou_download）与分类（dou_download_category）
- 设计要点
- 下载表：与文章表结构相近，新增 download_link、size；具备 SEO、内容、状态、时间戳等通用字段。
- 分类表：download_category 作为分类维度，download.category_id 外键引用。
- 业务逻辑
- 列表支持按标题关键字模糊筛选。
- 默认排序根据系统配置决定：开启手动排序则 sort ASC, id DESC，否则 id DESC。
- 删除时通过 PurgesRelatedOnDelete 清理相关附件。
- 权限与状态
- 使用 status 控制启用/禁用；结合后台权限控制增删改查。
- 扩展建议
- 可增加下载次数、访问统计、标签、版本等字段。
erDiagram
DOWNLOAD_CATEGORY {
int id PK
string name
string slug
int parent_id
string icon
string keywords
text description
boolean sync_to_nav
int sort
}
DOWNLOAD {
int id PK
enum operator_type
int operator_id
int category_id FK
string title
string slug
text defined
longtext content
string keywords
text description
tinyint sort
datetime created_at
string image
string download_link
string size
tinyint status
}
DOWNLOAD_CATEGORY ||--o{ DOWNLOAD : "一对多"依赖关系分析
- 表间关系
- dou_download.category_id → dou_download_category.id（一对多）。
- dou_certificate 通过复合索引 idx_operator(operator_type, operator_id) 提升按创建者查询效率。
- dou_area 通过 parent_id 形成自关联树。
- 模型与服务依赖
- 区域：核心服务 AreaService 依赖 area 表，后台模型 Area 提供写入白名单与子级检查。
- 品牌：后台模型 Brand 负责字段格式化与附件预热。
- 证书：前台模型 Certificate 负责多语言与发布过滤。
- 下载：后台模型 Download 负责分类关联、筛选与排序策略。
graph LR
A["dou_area"] --> |parent_id| A
C["dou_certificate"] --> |idx_operator| C
D["dou_download"] --> |category_id| DC["dou_download_category"]性能考虑
- 区域表
- 全量缓存并按 sort、id 排序，降低频繁树构建开销。
- 建议在 parent_id 建立索引以优化子级查询（当前未显式定义，可按需添加）。
- 品牌表
- 列表渲染时对 image 与 created_at 进行批量预处理，减少 N+1 问题。
- click 字段适合异步更新以避免写放大。
- 证书表
- 复合索引 idx_operator 提升按创建者查询性能。
- 前台列表通过 prefetchers 预热 url、language、attachment，减少多次IO。
- 下载表
- 默认排序依据系统配置，避免不必要的复杂排序。
- 标题模糊搜索建议使用全文索引或搜索引擎以提升性能。
故障排查指南
- 区域删除失败
- 现象：尝试删除存在子区域的父级时报错。
- 排查：调用 hasChildArea 检查是否存在子区域，先删除或转移子区域后再操作。
- 证书详情为空
- 现象：前台无法获取证书详情。
- 排查：确认记录 status=1（已发布），并使用 findPublishedById 查询。
- 下载列表排序异常
- 现象：排序不符合预期。
- 排查：检查 features.sort 配置，确认 scopeApplyDefaultOrder 生效；必要时在数据库层面增加 sort 索引。
- 品牌图片不显示
- 现象：列表图片路径错误。
- 排查：确认 casts 中 attachment 映射正确，且 Prefetchers 已启用图片URL预热。
结论
DouPHP 辅助功能模块的表结构设计遵循简洁、可扩展与高性能原则：
- 区域表通过 parent_id 实现灵活树形结构，配合缓存与排序满足高效展示。
- 品牌表完善SEO与统计字段，便于运营与推广。
- 证书表通过创建者追踪与发布状态，支撑资质展示与权限控制。
- 下载表与分类表解耦内容与分类，提供灵活的资源组织方式。 建议在生产环境中按需补充索引、监控关键指标（如点击、下载量），并结合权限体系保障数据安全。
附录
- 常用字段约定
- id：主键，自增。
- sort：排序权重，数值越小越靠前。
- status：启用/禁用，1 启用，0 禁用。
- created_at：创建时间，datetime 类型。
- image：附件路径，经模型 casts 转换为可用URL。
- 扩展点
- 区域：可增加拼音、经纬度、行政代码等。
- 品牌：可增加外链、品牌标签、多语言描述。
- 证书：可增加有效期、颁发机构、编号、多语言描述。
- 下载：可增加下载次数、版本、标签、多语言标题与描述。