简介

本开发文档面向 DouPHP 小程序“下载管理”相关能力，覆盖以下目标：

• 下载列表的分类展示、搜索过滤、分页与归档。
• 权限验证与访问控制（后台管理、前台 API）。
• 文件详情页的信息展示、点击统计、SEO 结构化数据。
• 小程序端下载流程：文件类型识别、下载进度条、存储路径管理、队列与通知。
• 数据结构设计：文件名、大小、类型、下载地址、访问权限、下载次数等字段定义。
• 下载机制建议：断点续传、进度监控、错误重试、存储空间管理。
• 常见问题：大文件优化、网络中断处理、空间不足提示等。

项目结构

围绕下载功能的关键代码分布如下：

• 后台管理：控制器、服务、模型、表单校验、视图模板。
• 前台 API：控制器与服务，提供列表与详情接口。
• 小程序前端：下载列表页与详情页的交互逻辑。
• SEO 扩展：为下载条目生成结构化数据。

graph TB
subgraph "后台管理"
AC["Admin DownloadController"]
AM["Admin DownloadModel"]
AR["DownloadFormRequest"]
AV["download.htm"]
end
subgraph "前台API"
FC["Front DownloadController"]
FS["Front DownloadService"]
end
subgraph "小程序前端"
MPDL["download.ts(详情页)"]
MPCAT["download_category.ts(列表页)"]
end
subgraph "SEO"
SS["SchemaService"]
end
AC --> AM
AC --> AR
AC --> AV
FC --> FS
MPDL --> FC
MPCAT --> FC
FC --> SS

核心组件

• 后台下载控制器：负责列表、新增、编辑、删除、批量操作，渲染后台模板并传递分类树、关键词、分页数据。
• 前台下载控制器：提供下载列表与详情 API，支持按分类、归档、分页查询；详情中记录点击量。
• 前台下载服务：封装列表构建、详情构建、分类查询、点击统计等业务逻辑。
• 后台下载模型：声明表名、可写字段、关联分类、关键字筛选、默认排序。
• 表单请求校验：集中定义新增/更新场景的字段白名单与校验规则。
• 小程序下载页：调用详情接口，使用 wx.downloadFile 下载并打开文档，设置分享标题。
• SEO 结构化数据：为下载条目输出 SoftwareApplication 类型 JSON-LD，包含名称、描述、图片、发布时间、下载地址、文件大小等。

架构总览

下载功能的整体调用链如下：

• 小程序详情页加载时，调用前台 API 获取详情数据，并在本地发起下载。
• 前台 API 通过服务层查询数据库，返回格式化后的下载信息，同时记录点击量。
• 后台管理端提供下载条目的增删改查与分类管理，用于维护下载资源元数据。
• SEO 服务在页面渲染时注入结构化数据，提升搜索引擎对下载资源的理解。

sequenceDiagram
participant MP as "小程序详情页"
participant API as "前台下载控制器"
participant SVC as "前台下载服务"
participant DB as "数据库"
participant SEO as "SEO服务"
MP->>API : GET /download/show?id=xxx
API->>SVC : buildDownloadShowData(id)
SVC->>DB : 查询下载条目(已发布)
DB-->>SVC : 下载数据
SVC-->>API : 返回下载数据
API->>SVC : recordDownloadView(id)
SVC->>DB : click+1
API-->>MP : {title, download, defined, cate_info}
MP->>MP : wx.downloadFile(url)
API->>SEO : 生成SoftwareApplication JSON-LD

详细组件分析

后台下载管理（列表、新增、编辑、删除）

• 列表页：接收 category_id、keyword、page，调用服务构建列表数据，渲染模板并传入分类树与分页。
• 新增/编辑：通过表单请求校验，提交后由服务完成插入或更新，跳转回编辑页并提示成功。
• 删除：校验 id，调用服务执行删除，返回统一结果。
• 批量操作：接收 post 参数，交由服务处理并返回消息与跳转地址。

flowchart TD
Start(["进入后台下载列表"]) --> GetParams["读取category_id/keyword/page"]
GetParams --> BuildList["调用服务构建列表数据"]
BuildList --> Render["渲染download.htm模板"]
Render --> End(["结束"])

前台下载 API（列表与详情）

• 列表接口：支持分类、归档、分页；返回下载列表、分类树与当前分类信息。
• 详情接口：根据路由解析 id，构建详情数据，记录点击量，返回标题、下载对象、自定义字段与分类信息。

sequenceDiagram
participant Client as "小程序/浏览器"
participant Ctl as "前台下载控制器"
participant Svc as "前台下载服务"
participant DB as "数据库"
Client->>Ctl : GET /download/index?category_id=&year=&month=&page=
Ctl->>Svc : buildDownloadListData(catId, page, pageSize, archive)
Svc->>DB : 查询已发布条目(含分类、归档过滤)
DB-->>Svc : 分页结果
Svc-->>Ctl : {download_list, pager}
Ctl-->>Client : ApiResponse.success(...)
Client->>Ctl : GET /download/show?id=
Ctl->>Svc : buildDownloadShowData(id)
Svc->>DB : 查询已发布条目
DB-->>Svc : 下载数据
Ctl->>Svc : recordDownloadView(id)
Svc->>DB : click+1
Ctl-->>Client : ApiResponse.success({title, download, defined, cate_info})

小程序下载页（详情与下载）

• 页面加载：通过 http.get 调用详情接口，设置页面标题与分享标题。
• 下载动作：使用 wx.downloadFile 下载文件，成功后用 openDocument 打开文档。
• 失败处理：当前实现静默失败，建议增加用户提示与重试机制。

sequenceDiagram
participant Page as "download.ts"
participant HTTP as "http服务"
participant API as "前台下载控制器"
participant WX as "微信客户端"
Page->>HTTP : GET route('download.show', {id})
HTTP->>API : 请求详情
API-->>HTTP : {download, defined, cate_info}
HTTP-->>Page : 返回数据
Page->>WX : wx.downloadFile({url})
WX-->>Page : success/fail
Page->>WX : openDocument(tempFilePath)

下载列表页（分类与分页）

• 列表页支持按 category_id 筛选，默认加载第一页，支持加载更多。
• 通过 http.get 调用列表接口，渲染分类树与下载列表。

SEO 结构化数据（下载条目）

• 为下载条目输出 SoftwareApplication 类型 JSON-LD，包含名称、描述、图片、URL、发布日期、发布者、下载地址、文件大小等。
• 有助于搜索引擎更好地理解下载资源内容。

依赖关系分析

• 控制器依赖服务层进行业务处理，服务层依赖模型与数据库。
• 表单请求校验集中在 Request 类，确保输入安全与一致性。
• 小程序前端依赖前台 API 提供的数据接口。
• SEO 服务在页面渲染阶段注入结构化数据。

graph LR
AdminCtl["后台控制器"] --> AdminReq["表单请求校验"]
AdminCtl --> AdminModel["后台模型"]
FrontCtl["前台控制器"] --> FrontSvc["前台服务"]
FrontSvc --> DB["数据库"]
MP["小程序前端"] --> FrontCtl
FrontCtl --> SEO["SEO服务"]

性能与体验优化

• 列表分页与归档：通过服务层分页与归档过滤减少数据传输与渲染压力。
• 附件 URL 预热：模型层配置预取器，批量预热附件 URL，减少重复计算。
• 排序策略：根据系统配置选择手动排序或 ID 倒序，提升列表可读性。
• 小程序下载体验：
  • 进度条：建议在 wx.downloadFile 回调中显示进度，提升用户感知。
  • 队列管理：避免并发过多导致内存占用过高，限制同时下载数量。
  • 存储路径：使用临时路径打开文档，必要时持久化到本地缓存并清理过期文件。
  • 错误重试：在网络异常时提供重试按钮与友好提示。
• 大文件优化：
  • 服务端：启用分块传输、Range 头支持以实现断点续传。
  • 客户端：检测文件大小，提示用户 Wi-Fi 环境下载，提供暂停/继续能力。
• 存储空间管理：
  • 定期清理临时文件与过期缓存。
  • 检测可用空间，不足时提示用户释放空间。

故障排查指南

• 下载失败静默：当前小程序详情页在 wx.downloadFile 失败时未提示，建议增加错误提示与重试入口。
• 网络中断：建议在下载过程中监听网络状态变化，自动暂停并提示恢复。
• 存储空间不足：在下载前检查设备可用空间，不足时提示用户清理。
• 大文件卡顿：采用分块下载与进度反馈，降低主线程阻塞。
• 权限问题：确认下载链接是否可访问，必要时通过鉴权中间件保护资源。
• 后台表单校验失败：检查 DownloadFormRequest 中的规则是否与数据库字段一致。

结论

DouPHP 的下载管理模块在后端提供了完善的列表、详情、分类管理与 SEO 支持，前端小程序实现了基本的下载与打开文档流程。为进一步提升用户体验，建议在小程序端增强进度反馈、错误处理、队列管理与存储管理，并在服务端引入断点续传与大文件优化策略。

附录：数据模型与字段说明

• 下载条目字段（基于模型与 SEO 输出推断）：
  • 标识与分类：id、category_id、slug
  • 内容与元数据：title、content、keywords、description、defined、image
  • 下载相关：download_link、size
  • 时间戳与统计：created_at、click
  • 其他：sort、operator_type、operator_id
• 分类字段：
  • name、slug、parent_id、icon、keywords、description、sync_to_nav、sort
• 表单校验与可写字段：
  • 后台表单请求集中定义新增/更新场景的校验规则与字段白名单。
  • 模型层声明可写入字段，确保入库安全。