简介

本开发文档面向DouPHP的图库管理模块，覆盖图片资源的增删改查、分类体系、标签与SEO优化、上传流程（含草稿与批量）、水印添加、缩略图生成、懒加载与响应式显示、存储策略与CDN集成、性能优化等主题。文档以代码级为依据，提供流程图与时序图，帮助开发者快速理解并扩展该模块。

项目结构

图库管理在后台、前台与API层均有对应实现：

• 后台管理：控制器负责页面渲染与表单处理，服务层封装业务逻辑，模型负责数据访问。
• 前台展示：控制器负责列表与详情页面的数据组装，服务层提供查询与分页。
• 用户侧上传：前端用户控制器调用附件门面进行上传、草稿保存与画廊渲染。
• 文件系统：统一的磁盘契约与配置，支持本地与未来云存储扩展。

graph TB
subgraph "后台"
AC["Admin GalleryController"]
CC["Admin CategoryController"]
ASvc["GalleryService / CategoryService"]
AModel["GalleryCategory 模型"]
end
subgraph "前台"
FC["Front GalleryController"]
FSvc["Front GalleryService"]
end
subgraph "用户侧"
UC["User Controller"]
end
subgraph "基础设施"
FS["Filesystem 契约"]
CFG["file.php 配置"]
end
AC --> ASvc
CC --> ASvc
FC --> FSvc
UC --> FS
ASvc --> AModel
FSvc --> AModel
FS --- CFG

核心组件

• 后台图片控制器：提供图片列表、新增、编辑、删除与批量操作入口；通过服务层构建数据与执行变更。
• 后台分类控制器：提供分类树形列表、新增、编辑、删除；用于组织图片资源。
• 前台图片控制器：提供按分类、归档的列表与详情页数据组装，返回统一API响应。
• 用户侧上传：支持普通上传与草稿模式，支持多文件内容区上传、尺寸限制、水印与业务字段标记。
• 文件系统契约：定义统一的磁盘操作接口，屏蔽底层驱动差异，便于接入CDN或对象存储。
• 配置文件：集中管理上传大小、允许扩展名、图片质量、缩略图目录等。

架构总览

下图展示了从请求到数据落盘与展示的完整链路，涵盖后台管理、前台展示与用户侧上传。

sequenceDiagram
participant Admin as "后台控制器"
participant Front as "前台控制器"
participant User as "用户侧控制器"
participant Svc as "服务层"
participant Model as "模型"
participant FS as "文件系统"
participant Disk as "磁盘/CDN"
Admin->>Svc : 构建列表/默认数据/更新/删除
Front->>Svc : 构建列表/详情数据
User->>FS : store/storeDraft(带选项)
Svc->>Model : 读写 gallery / gallery_category
FS->>Disk : putFile/putFileAs/url/path
Note over FS,Disk : 本地路径或CDN地址由驱动决定

详细组件分析

后台图片管理（增删改查与批量）

• 列表：支持按分类过滤与关键词搜索，分页返回。
• 新增/编辑：表单校验由请求类完成；支持草稿令牌清理与默认数据构建。
• 删除：参数校验后委托服务层执行，返回统一删除结果。
• 批量：接收POST参数，交由服务层处理并返回跳转与消息。

flowchart TD
Start(["进入后台图片页"]) --> List["获取分类ID/关键词/页码"]
List --> BuildList["服务层构建列表数据"]
BuildList --> Render["渲染模板"]
Render --> |新增| CreateForm["生成新增表单"]
Render --> |编辑| EditForm["加载编辑数据"]
CreateForm --> Store["提交新增"]
EditForm --> Update["提交更新"]
Store --> Redirect["重定向至编辑页并提示成功"]
Update --> Redirect
Render --> Delete["删除/批量操作"]
Delete --> ServiceCall["服务层执行删除/批量"]
ServiceCall --> Respond["返回统一删除结果"]

后台图片分类管理

• 列表：返回扁平化分类树，支持创建入口。
• 新增/编辑：默认数据构建与语言按钮生成。
• 删除：参数校验后委托服务层执行。

flowchart TD
CatStart["进入分类页"] --> CatList["获取分类树"]
CatList --> CatRender["渲染分类模板"]
CatRender --> CatCreate["新增分类表单"]
CatRender --> CatEdit["编辑分类表单"]
CatCreate --> CatStore["提交新增"]
CatEdit --> CatUpdate["提交更新"]
CatStore --> CatRedirect["重定向至编辑页"]
CatUpdate --> CatRedirect
CatRender --> CatDelete["删除分类"]
CatDelete --> CatService["服务层执行删除"]
CatService --> CatRespond["返回删除结果"]

前台图片展示（列表与详情）

• 列表：支持分类路由、归档（年/月）与分页；返回标题、分类信息、列表与分页器。
• 详情：根据路由解析ID，返回图片详情与所属分类信息。

sequenceDiagram
participant Client as "客户端"
participant API as "前台控制器"
participant Svc as "前台服务"
participant Model as "模型"
Client->>API : GET /gallery (id/category_slug/page/year/month)
API->>API : 解析分类/归档/分页
API->>Svc : buildListingData(...)
Svc->>Model : 查询分类与图片
Model-->>Svc : 数据集合
Svc-->>API : 列表数据
API-->>Client : ApiResponse{title, category_id, gallery_list, pager}
Client->>API : GET /gallery/show (id/slug)
API->>Svc : getShowPageData(id)
Svc-->>API : {gallery, cate_info}
API-->>Client : ApiResponse{title, gallery, defined, cate_info}

图片上传流程（含草稿、批量、水印与尺寸）

• 普通上传：构造上传选项（文件名、宽度、水印、业务字段），调用附件门面存储。
• 草稿模式：先存草稿，再渲染草稿画廊，适合富文本编辑器场景。
• 批量内容区上传：将多文件数组重组为独立文件项，逐个上传并拼接预览HTML。
• 数量限制：示例中针对特定模块与类型限制最大数量。

flowchart TD
UStart["用户触发上传"] --> Mode{"草稿模式?"}
Mode -- 是 --> Draft["storeDraft(..., 选项)"]
Mode -- 否 --> Direct["store(..., 选项)"]
Draft --> GalleryDraft["galleryByDraft(...)"]
Direct --> Gallery["gallery(...)"]
Draft --> Preview["返回预览HTML"]
Gallery --> Preview
Preview --> End["结束"]

缩略图生成与懒加载、响应式显示

• 缩略图：可通过配置指定缩略图目录；结合文件系统url方法输出可访问路径。
• 懒加载：在前端模板中使用data属性与原生loading="lazy"或JS库实现按需加载。
• 响应式：使用srcset与picture元素适配不同屏幕密度与尺寸。

flowchart TD
TStart["读取原图URL"] --> ThumbCfg{"是否启用缩略图目录?"}
ThumbCfg -- 是 --> GenThumb["生成缩略图路径"]
ThumbCfg -- 否 --> UseOrig["直接使用原图URL"]
GenThumb --> Lazy["懒加载加载"]
UseOrig --> Lazy
Lazy --> Responsive["响应式srcset/picture"]
Responsive --> Rend["渲染图片"]

SEO优化要点

• 标题与描述：列表与详情页根据分类名称或归档年份动态设置title。
• 关键词与描述：后台表单支持keywords与description字段，便于搜索引擎抓取。
• 结构化数据：可在模板中注入JSON-LD等元数据以提升展示效果。

依赖关系分析

• 控制器依赖服务层：后台与前台控制器均通过服务层聚合业务逻辑，降低耦合。
• 服务层依赖模型：数据访问集中在模型层，保证单一职责。
• 上传流程依赖文件系统契约：通过统一接口屏蔽本地与远端存储差异。
• 配置驱动行为：upload_max_kb、allow_extensions、image_quality、thumb_directory等影响上传与处理。

graph LR
AC["后台控制器"] --> ASvc["后台服务"]
FC["前台控制器"] --> FSvc["前台服务"]
UC["用户控制器"] --> FS["文件系统契约"]
ASvc --> AM["模型"]
FSvc --> AM
FS --- CFG["file.php 配置"]

性能考虑

• 上传限制与压缩：通过配置控制单文件大小与图片质量，避免过大图片影响带宽与存储。
• 缩略图策略：启用缩略图目录并按需生成，减少首屏传输体积。
• 懒加载与响应式：前端采用懒加载与srcset，提升首屏加载速度与移动端体验。
• CDN集成：通过文件系统契约的url方法返回CDN地址，后端无需感知具体域名与签名逻辑。
• 分页与归档：列表支持分页与归档，减少单次数据量。

故障排查指南

• 非法参数：控制器对id等关键参数进行校验，非法时抛出领域异常并重定向。
• 上传失败：检查允许扩展名、文件大小上限与磁盘空间；确认文件系统根目录可写。
• 草稿未生效：确认草稿令牌有效且已清理过期草稿；核对草稿画廊渲染参数。
• 缩略图缺失：检查缩略图目录配置与权限；确认生成逻辑是否被调用。

结论

DouPHP图库管理模块通过清晰的控制器-服务-模型分层与统一文件系统契约，实现了稳定的CRUD、分类组织、上传与展示能力。借助配置化的上传策略与可扩展的存储抽象，可平滑对接CDN与对象存储。结合懒加载、响应式与分页归档，满足高性能与良好用户体验的需求。

附录：API参考与扩展指南

后台接口概览

• 图片列表：GET 列表页，支持category_id、keyword、page。
• 新增：POST 提交表单，返回编辑页重定向与成功消息。
• 编辑：GET 加载编辑数据；POST 提交更新。
• 删除：POST 删除单条或批量操作，返回统一结果。
• 分类管理：列表、新增、编辑、删除，返回分类树与操作结果。

前台API

• 列表：GET /gallery，支持id、category_slug、page、year、month；返回title、category_id、gallery_list、pager。
• 详情：GET /gallery/show，支持id、category_slug、slug；返回gallery、defined、cate_info。

上传与草稿

• 普通上传：构造上传选项（basename、image_width、watermark、business_field），调用附件门面store。
• 草稿上传：storeDraft + galleryByDraft，适合富文本编辑器。
• 批量内容区：将多文件数组拆分后逐个上传，拼接预览HTML。

存储策略与CDN集成

• 本地存储：默认磁盘local指向images/upload/，可通过配置调整。
• 远端存储：通过文件系统契约实现url与path，返回CDN或签名地址。
• 配置项：upload_max_kb、allow_extensions、image_quality、thumb_directory。

扩展点与建议

• 自定义水印：在服务层或上传选项中启用水印开关。
• 缩略图策略：按业务需求配置缩略图目录与生成规则。
• 安全加固：严格校验扩展名与文件大小，避免恶意文件上传。
• 缓存与CDN：结合CDN缓存策略与浏览器缓存头，提升访问速度。