分享推广API | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

分享推广API

简介

本文件面向营销平台开发者，提供“分享推广”模块的完整API参考与实践指南。当前仓库实现了会员侧分享申请、列表查询与后台审核发放积分等能力；同时预留了扩展点，便于后续接入分享统计、渠道追踪、模板管理与防刷机制。文档基于现有代码进行梳理，确保与实际实现一致，并给出可落地的扩展建议。

项目结构

分享功能在前后端分别有控制器与服务：

API层（会员侧）：路由定义位于 api/route/share.php，控制器位于 api/controller/share/*，业务逻辑委托给 front/service/share/ShareService.php。
管理后台：路由定义位于 admin/route/share.php，控制器位于 admin/controller/share/ShareController.php，业务逻辑位于 admin/service/share/ShareService.php。

graph TB
Client["客户端/小程序"] --> APIRoute["API 路由<br/>api/route/share.php"]
APIRoute --> ShareCtrl["ShareController<br/>api/controller/share/ShareController.php"]
APIRoute --> UserCtrl["UserController<br/>api/controller/share/UserController.php"]
UserCtrl --> FrontSvc["Front ShareService<br/>front/service/share/ShareService.php"]
AdminRoute["Admin 路由<br/>admin/route/share.php"] --> AdminCtrl["Admin ShareController<br/>admin/controller/share/ShareController.php"]
AdminCtrl --> AdminSvc["Admin ShareService<br/>admin/service/share/ShareService.php"]

图表来源

api/route/share.php:15-39
api/controller/share/ShareController.php:26-41
api/controller/share/UserController.php:28-103
front/service/share/ShareService.php:25-124
admin/route/share.php:15-31
admin/controller/share/ShareController.php:28-136
admin/service/share/ShareService.php:32-268

章节来源

api/route/share.php:15-39
admin/route/share.php:15-31

核心组件

API 入口控制器
- ShareController：模块入口，返回空成功响应，用于路由兜底与收录。
- UserController：会员侧分享申请流程（列表、申请、提交）。
前端服务
- Front ShareService：生成分享编号、提交分享申请、构建列表数据、统计待处理数量。
管理后台
- Admin ShareController：列表、详情、审核处理、批量删除、参数初始化。
- Admin ShareService：过滤查询、格式化状态、审核发放积分、批量操作、参数种子。

章节来源

api/controller/share/ShareController.php:26-41
api/controller/share/UserController.php:28-103
front/service/share/ShareService.php:25-124
admin/controller/share/ShareController.php:28-136
admin/service/share/ShareService.php:32-268

架构总览

会员侧通过声明式路由访问分享接口，调用前端服务完成申请与列表展示；后台通过独立路由进入审核页面，由后台服务完成数据过滤、状态格式化与积分发放。

sequenceDiagram
participant C as "客户端"
participant R as "API路由"
participant UC as "UserController"
participant FS as "Front ShareService"
participant A as "附件系统"
participant M as "分享模型"
C->>R : GET /api/?route=share/user/share/index
R->>UC : index()
UC->>FS : buildShareListData(userId, page, url)
FS->>M : forUser().paginate()
FS-->>UC : share_list + pager
UC-->>C : 成功响应(列表+分页)
C->>R : POST /api/?route=share/user/share/apply_post
R->>UC : applyPost()
UC->>A : cleanupUserDrafts()
UC->>A : newDraftToken()
UC->>FS : submitShareApply(userId, draft_token)
FS->>M : create(share_sn,user_id,status=0)
FS->>A : claimByToken('share', token, shareId, 'user', userId)
FS-->>UC : true/false
UC-->>C : 成功/失败响应

图表来源

api/route/share.php:31-39
api/controller/share/UserController.php:51-103
front/service/share/ShareService.php:43-76
front/service/share/ShareService.php:84-115

详细接口说明

会员侧分享接口（API）

基础路径：/api/?route=share/user/share

获取分享列表
- 方法：GET
- 路径：/api/?route=share/user/share/index
- 鉴权：需要登录态
- 请求参数：page（默认1）
- 响应字段：title、share_list[]、pager、total
- 行为：按用户维度分页查询分享记录，附带图片列表、处理记录、处理时间、积分值（若开启积分）、状态与创建时间
- 错误码：业务规则异常时返回422
发起分享申请
- 方法：GET
- 路径：/api/?route=share/user/share/apply
- 鉴权：需要登录态
- 响应字段：title、draft_token、img_list_html
- 行为：清理用户草稿、生成草稿令牌、渲染图片上传区域HTML
提交分享申请
- 方法：POST
- 路径：/api/?route=share/user/share/apply_post
- 鉴权：需要登录态
- 请求体：draft_token（必填）
- 行为：校验未存在待处理申请；清理草稿；生成分享编号；创建分享记录（status=0）；将草稿附件认领到真实主键；无图则回滚
- 错误码：重复申请或提交失败返回422

flowchart TD
Start(["开始"]) --> CheckPending["检查是否存在待处理申请"]
CheckPending --> |是| ErrExist["返回422：已存在申请"]
CheckPending --> |否| Cleanup["清理用户草稿"]
Cleanup --> Token["生成草稿令牌"]
Token --> Submit["提交申请(draft_token)"]
Submit --> Create["创建分享记录(status=0)"]
Create --> Claim["认领草稿附件到真实ID"]
Claim --> HasImage{"是否有图片?"}
HasImage --> |否| Rollback["删除刚创建的记录并返回失败"]
HasImage --> |是| Success["返回成功"]
ErrExist --> End(["结束"])
Rollback --> End
Success --> End

图表来源

api/controller/share/UserController.php:70-103
front/service/share/ShareService.php:43-76

章节来源

api/route/share.php:31-39
api/controller/share/UserController.php:51-103
front/service/share/ShareService.php:43-76
front/service/share/ShareService.php:84-115

管理后台分享接口（Web）

基础路径：?route=share

分享列表
- 方法：GET
- 路径：?route=share
- 筛选：username、share_sn、time_start、time_end、page
- 输出：list[]、pager
- 行为：按用户/单号/时间范围过滤，格式化状态与积分信息，加载图片列表
分享详情
- 方法：GET
- 路径：?route=share/show&id={id}&unlock={可选}
- 输出：share对象、unlock标记
- 行为：校验ID有效性，组装用户信息与图片列表，格式化时间与状态
审核处理
- 方法：POST
- 路径：?route=share/handle
- 请求体：id、handle_record、unlock（可选）
- 行为：校验ID与解锁标志；更新处理记录与时间；设置状态为已通过；若开启积分则发放积分；重定向至详情页
批量取消（删除）
- 方法：POST
- 路径：?route=share/action
- 请求体：checkbox[]（ID数组）
- 行为：安全过滤ID；批量删除；写入管理员日志；返回消息与跳转地址
初始化分享积分参数
- 方法：GET
- 路径：?route=share/set
- 行为：若参数表中不存在分享积分配置项则插入默认条目；重定向至参数设置页

sequenceDiagram
participant A as "管理员"
participant AR as "Admin路由"
participant AC as "Admin ShareController"
participant AS as "Admin ShareService"
participant WS as "钱包服务"
A->>AR : POST /?route=share/handle
AR->>AC : handle(validated)
AC->>AS : handle(validated)
AS->>AS : 校验ID/解锁标志
AS->>AS : 更新处理记录/时间/状态=已通过
AS->>WS : createPoint(user_id, 'share', point, share_sn)
AS-->>AC : 重定向URL
AC-->>A : 跳转至详情页

图表来源

admin/route/share.php:28-31
admin/controller/share/ShareController.php:115-127
admin/service/share/ShareService.php:185-224

章节来源

admin/route/share.php:28-31
admin/controller/share/ShareController.php:60-136
admin/service/share/ShareService.php:91-268

依赖关系分析

控制器依赖服务：API与后台控制器均通过依赖注入使用对应ShareService。
服务依赖模型与外部系统：
- 前端服务依赖分享模型（创建、查询、分页）与附件系统（草稿令牌、认领、图片列表）。
- 后台服务依赖钱包服务（发放积分）、配置中心（是否启用积分、积分值）、审计与语言包。
路由解耦：通过声明式路由将URL映射到控制器方法，便于扩展与维护。

classDiagram
class ShareController_API {
+index(request) Response
}
class UserController_API {
+index(request) Response
+apply() Response
+apply_post(request) Response
-shareService : ShareService
}
class ShareService_Front {
+createShareSn() string
+submitShareApply(userId, draftToken) bool
+buildShareListData(userId, page, url) array
+countPendingByUserId(userId) int
}
class ShareController_Admin {
+index(request) Response
+show(request) Response
+handle(formRequest, request) Response
+action(formRequest) Response
+set() Response
}
class ShareService_Admin {
+buildShareListData(username, shareSn, timeStart, timeEnd, page) array
+buildShareViewData(id, unlock) array|null
+handle(validated) string
+batchCancel(validated) array
+seedSharePointParameter() void
}
UserController_API --> ShareService_Front : "依赖"
ShareController_Admin --> ShareService_Admin : "依赖"

图表来源

api/controller/share/ShareController.php:26-41
api/controller/share/UserController.php:36-45
front/service/share/ShareService.php:25-124
admin/controller/share/ShareController.php:32-42
admin/service/share/ShareService.php:32-268

章节来源

api/controller/share/UserController.php:36-45
front/service/share/ShareService.php:25-124
admin/service/share/ShareService.php:32-268

性能与缓存

列表分页：前后端列表均采用分页查询，避免一次性加载大量数据。
图片资源：图片列表通过附件系统按需加载，减少响应体积。
扩展建议：
- 分享统计：可在点击落地页埋点，异步上报至统计服务，采用队列或批处理降低实时写入压力。
- 缓存策略：对热点分享列表与配置（如积分参数）增加短期缓存，注意失效策略与一致性。
- 防刷机制：对申请接口增加频率限制与设备指纹校验，结合验证码与风控策略。

故障排查

重复申请
- 现象：提交申请时报422
- 原因：该用户已存在待处理申请
- 解决：等待审核或联系管理员处理
- 相关位置：api/controller/share/UserController.php:70-75
提交失败
- 现象：提交申请后返回失败
- 原因：未携带草稿令牌或认领附件为空
- 解决：重新发起申请并确保上传图片后再提交
- 相关位置：front/service/share/ShareService.php:43-76
后台审核异常
- 现象：审核时报错或无法通过
- 原因：ID非法、记录不存在、状态冲突
- 解决：检查入参与记录状态，必要时重置或重新提交
- 相关位置：admin/service/share/ShareService.php:185-224

章节来源

api/controller/share/UserController.php:70-103
front/service/share/ShareService.php:43-76
admin/service/share/ShareService.php:185-224

结论

当前分享推广模块已具备完整的会员申请与后台审核发放积分闭环，支持图片附件与分页展示。建议在现有基础上逐步扩展分享统计、渠道追踪、模板管理与防刷机制，以满足营销场景的数据分析与风控需求。

附录

接口清单速查

会员侧
- GET /api/?route=share/user/share/index
- GET /api/?route=share/user/share/apply
- POST /api/?route=share/user/share/apply_post
管理后台
- GET ?route=share
- GET ?route=share/show
- POST ?route=share/handle
- POST ?route=share/action
- GET ?route=share/set

章节来源

api/route/share.php:31-39
admin/route/share.php:28-31

扩展实践建议

分享统计接口
- 新增事件上报接口，记录分享次数、点击量、转化率；采用异步写入与聚合计算。
- 提供统计查询接口，支持按时间、渠道、活动维度筛选。
邀请奖励机制
- 在分享落地页绑定邀请关系，订单完成后触发奖励发放；支持等级提升与阶梯奖励。
分享活动管理
- 创建活动、设置规则（有效期、目标、奖励）、监控效果（曝光、转化、ROI）。
分享模板与个性化
- 提供模板CRUD与变量替换引擎，支持文案、图片、链接动态定制。
防刷与真实性验证
- 接口限流、设备指纹、IP黑名单、验证码、风控评分；对异常行为进行拦截与告警。

添加日期：2026-10-05