简介

本开发文档面向DouPHP业务开发者，围绕内容管理、电商交易、用户与营销等核心模块，系统阐述设计理念、业务流程、数据流转与扩展方式。重点覆盖：

• 商品展示与详情构建（前台）
• 订单列表、详情、发货与线下支付审核（后台）
• 优惠券发放、领取与折扣计算（营销）
• 微信事件回调处理（第三方集成）
• 入口引导、路由与异常处理（框架层）

文档同时给出关键流程图与时序图，帮助快速理解模块间协作与事务边界。

项目结构

• 入口与引导
  • 根入口 index.php 负责加载引导、解析语言前缀、初始化并调度路由。
  • core/bootstrap.php 定义路径常量、加载配置、注册自动加载、容器与门面、以及场景事件注册器。
• 配置
  • config/config.php 提供数据库连接、表前缀、应用密钥与调试开关等基础配置。
  • config/module.php 声明列式/单页模块、菜单与工作区关联，决定前端导航与功能可见性。
• 业务模块
  • 前台服务：如 front/service/product/ProductService.php 负责商品列表与详情数据组装。
  • 后台服务：如 admin/service/order/OrderService.php 负责订单筛选、详情、发货、批量取消与自动化任务触发。
  • 营销服务：core/service/coupon/CouponService.php 提供优惠券查询、状态、折扣计算与领取记录。
  • 第三方集成：core/service/weixin/WeixinService.php 处理微信被动消息与事件。
• API 与路由
  • 各端通过声明式路由将 URL 映射到控制器与服务，例如 coupon API 路由在 _'\module/coupon/api/route/coupon.php 中定义。

graph TB
A["入口 index.php"] --> B["引导 bootstrap.php"]
B --> C["配置 config/config.php"]
B --> D["模块清单 config/module.php"]
A --> E["路由分发"]
E --> F["前台 ProductService"]
E --> G["后台 OrderService"]
E --> H["营销 CouponService"]
E --> I["微信 WeixinService"]

图示来源

• index.php:1-75
• core/bootstrap.php:59-180
• config/config.php:15-53
• config/module.php:1-132

章节来源

• index.php:1-75
• core/bootstrap.php:59-180
• config/config.php:15-53
• config/module.php:1-132

核心组件

• 商品服务（前台）
  • 职责：分类列表构建、品牌筛选、排序选项、分页、附件与价格计算、收藏状态、型号关联商品等。
  • 关键点：使用 AR 模型 with('category') 预加载；API 场景返回销量占比；Markdown 渲染详情内容。
• 订单服务（后台）
  • 职责：订单列表筛选（用户名、状态、时间、收件人）、详情组装、物流填写与发货、线下支付审核、批量删除与取消、自动化任务触发。
  • 关键点：与 PaymentService 联动处理支付台账；状态机推进；事务化批量操作；审计日志。
• 优惠券服务（营销）
  • 职责：可领优惠券列表、用户已持有券、折扣计算、过期判断、券码生成。
  • 关键点：支持按比例或固定金额扣减；上限控制；条件门槛校验。
• 微信服务（第三方）
  • 职责：接收微信服务器 XML 消息，按事件类型分发处理（关注、点击等）。
  • 关键点：安全读取输入、兼容 PHP 版本、事件键匹配媒体资源。

章节来源

• front/service/product/ProductService.php:61-346
• admin/service/order/OrderService.php:90-793
• core/service/coupon/CouponService.php:37-220
• core/service/weixin/WeixinService.php:67-99

架构总览

请求从入口进入，经引导完成环境初始化后，由路由分发至具体控制器或服务。服务层调用 ORM、存储、支付、营销等能力，必要时触发事件或异步任务。异常统一捕获并按 JSON/HTML 响应。

sequenceDiagram
participant Client as "客户端"
participant Entry as "入口 index.php"
participant Boot as "引导 bootstrap.php"
participant Router as "路由分发"
participant Service as "业务服务"
participant DB as "数据库"
participant Ext as "第三方/插件"
Client->>Entry : HTTP 请求
Entry->>Boot : 初始化环境
Boot-->>Entry : 就绪
Entry->>Router : 解析 route 并调度
Router->>Service : 调用具体服务方法
Service->>DB : 读写数据
Service->>Ext : 调用支付/微信/插件
Service-->>Router : 返回结果
Router-->>Client : 响应JSON/HTML

图示来源

• index.php:18-75
• core/bootstrap.php:115-180

详细组件分析

商品模块（前台）

• 设计要点
  • 列表页：支持分类、品牌、归档区间、排序与分页；聚合收藏状态与首图；API 场景补充销量占比。
  • 详情页：Markdown 渲染内容；价格与促销价计算；品牌信息；型号关联商品列表；多语言字段处理。
• 数据流
  • 控制器传入分类ID、品牌ID、排序参数与用户ID → 服务构建查询 → 分页 → 组装视图数据 → 返回模板或API响应。
• 扩展点
  • 新增属性对价格影响：AttributeService 参与价格调整。
  • 收藏模块：Module::make('favorites') 动态注入。
  • 图片与附件：attachment() 统一处理URL与缩略图。

flowchart TD
Start(["进入商品列表/详情"]) --> BuildList["构建列表数据<br/>分类/品牌/归档/排序/分页"]
BuildList --> Attachments["附件与缩略图映射"]
Attachments --> Pricing["价格与促销价计算"]
Pricing --> Favorites["收藏状态查询"]
Favorites --> Render["渲染列表/详情"]
Render --> End(["返回页面或API"])

图示来源

• front/service/product/ProductService.php:61-201
• front/service/product/ProductService.php:203-346

章节来源

• front/service/product/ProductService.php:61-346

订单模块（后台）

• 设计要点
  • 列表：支持用户名、状态、订单号、收件人、时间范围筛选；分页与状态选项。
  • 详情：订单主体、支付历史、物流公司、收货地址、优惠券汇总、是否允许重试支付。
  • 发货：首次填写运单时推进为已发货并解锁库存；后续更新仅记录物流信息。
  • 线下支付审核：确认收款标记支付成功并推进订单；驳回回退订单状态并标记失败。
  • 批量操作：批量删除与批量取消（事务保护），审计日志记录。
  • 自动化任务：自动取消超时订单、售后状态更新、评论状态更新。
• 数据流
  • 控制器接收输入 → 服务校验与构造查询 → 调用核心订单服务与支付服务 → 事务提交 → 返回结果。
• 事务与一致性
  • 批量取消使用 DB 事务，确保订单、明细、关联模块状态一致；异常时回滚并记录日志。
  • 线下支付审核通过 PaymentService 的状态机推进，避免静默失败。

sequenceDiagram
participant Admin as "管理员"
participant OrderSvc as "OrderService"
participant CoreOrder as "核心订单服务"
participant PaySvc as "PaymentService"
participant DB as "数据库"
Admin->>OrderSvc : 打开订单列表
OrderSvc->>CoreOrder : 执行自动化任务
OrderSvc->>DB : 构建筛选条件并分页
DB-->>OrderSvc : 订单列表
OrderSvc-->>Admin : 返回列表
Admin->>OrderSvc : 线下支付审核确认/驳回
OrderSvc->>PaySvc : markSucceeded/markFailed
PaySvc->>CoreOrder : 推进订单状态
CoreOrder->>DB : 更新订单与明细
DB-->>OrderSvc : 提交结果
OrderSvc-->>Admin : 跳转详情页

图示来源

• admin/service/order/OrderService.php:90-793

章节来源

• admin/service/order/OrderService.php:90-793

优惠券模块（营销）

• 设计要点
  • 可领列表：过滤有效期与启用状态；语言化名称与摘要；状态标注（可领/已领/已用/过期）。
  • 用户券包：基于 coupon_log 查询未使用且未过期的券。
  • 折扣计算：支持比例与固定金额；条件门槛；最大折扣上限；金额精度保留。
  • 券码生成：唯一性检查。
• 数据流
  • 控制器/服务调用 CouponService → 查询 coupon/coupon_log → 计算折扣 → 返回视图或API数据。
• 扩展点
  • 新券类型：在 discount 分支扩展逻辑。
  • 条件文本：language()->langBox 支持多语言。

flowchart TD
Start(["进入优惠券流程"]) --> List["获取可领/用户券列表"]
List --> Check["校验有效期与状态"]
Check --> Calc["计算折扣比例/固定/上限"]
Calc --> Return["返回折扣结果"]
Return --> End(["结束"])

图示来源

• core/service/coupon/CouponService.php:37-220

章节来源

• core/service/coupon/CouponService.php:37-220

优惠券API（接口端）

• 路由定义
  • GET /api/?route=coupon：列出可领优惠券。
  • POST /api/?route=coupon/claim：领取优惠券。
  • GET /api/?route=user/coupon：会员侧查看我的优惠券。
• 控制器映射
  • CouponController 与 UserController 分别处理主接口与会员子接口。

sequenceDiagram
participant Client as "客户端"
participant Route as "coupon 路由"
participant Ctrl as "CouponController/UserController"
participant Svc as "CouponService"
participant DB as "数据库"
Client->>Route : 访问 /api/?route=coupon
Route->>Ctrl : 分发到控制器
Ctrl->>Svc : 查询/领取优惠券
Svc->>DB : 读写 coupon/coupon_log
DB-->>Svc : 结果
Svc-->>Ctrl : 返回数据
Ctrl-->>Client : JSON 响应

图示来源

• _'\module/coupon/api/route/coupon.php:15-39
• core/service/coupon/CouponService.php:37-220

章节来源

• _'\module/coupon/api/route/coupon.php:15-39
• core/service/coupon/CouponService.php:37-220

微信事件处理（第三方集成）

• 设计要点
  • 安全读取原始XML输入；兼容不同PHP版本的实体加载限制。
  • 事件分发：subscribe（关注）、CLICK（菜单点击）等；根据 EventKey 匹配媒体资源推送。
• 数据流
  • 微信服务器POST → WeixinService.responseMsg → 解析XML → 事件分支 → 推送媒体或回复。

sequenceDiagram
participant WX as "微信服务器"
participant WSvc as "WeixinService"
participant DB as "数据库"
WX->>WSvc : POST XML 消息
WSvc->>WSvc : 解析XML与事件类型
alt 关注事件
WSvc->>DB : 查询媒体资源
DB-->>WSvc : 媒体数据
WSvc-->>WX : 推送新闻或多图文
else 点击事件
WSvc->>DB : 根据EventKey查找媒体
DB-->>WSvc : 媒体数据
WSvc-->>WX : 推送对应媒体
end

图示来源

• core/service/weixin/WeixinService.php:67-99

章节来源

• core/service/weixin/WeixinService.php:67-99

依赖关系分析

• 模块耦合
  • 商品服务依赖定价服务、Markdown渲染、附件服务与收藏模块（可选）。
  • 订单服务依赖核心订单服务、支付服务、支付方式名称解析、审计日志。
  • 优惠券服务依赖数据库与语言服务。
  • 微信服务依赖数据库与媒体资源。
• 外部依赖
  • 支付插件（如支付宝、微信支付）通过 PaymentService 抽象接入。
  • 第三方事件（微信）通过专用服务处理。
• 潜在循环依赖
  • 服务间通过构造函数注入与门面解耦，降低循环引用风险。
• 接口契约
  • 服务方法签名明确输入输出，便于单元测试与替换实现。

graph LR
Product["ProductService"] --> Pricing["PricingService"]
Product --> Markdown["MarkdownRenderer"]
Product --> Attachment["Attachment"]
Product --> Favorites["Favorites(可选)"]
Order["OrderService"] --> CoreOrder["核心订单服务"]
Order --> Payment["PaymentService"]
Order --> Audit["审计日志"]
Coupon["CouponService"] --> DB["数据库"]
Weixin["WeixinService"] --> DB

图示来源

• front/service/product/ProductService.php:35-59
• admin/service/order/OrderService.php:45-69
• core/service/coupon/CouponService.php:37-220
• core/service/weixin/WeixinService.php:67-99

章节来源

• front/service/product/ProductService.php:35-59
• admin/service/order/OrderService.php:45-69
• core/service/coupon/CouponService.php:37-220
• core/service/weixin/WeixinService.php:67-99

性能考量

• 列表与详情
  • 使用 AR 的 with('category') 预加载减少N+1查询。
  • 附件与缩略图批量映射，避免逐条URL转换。
  • API 场景按需附加销量占比，减少不必要计算。
• 订单筛选
  • 收件人多维模糊条件通过 EXISTS-IN 子查询优化。
  • 分页与默认排序提升列表性能。
• 事务与批量
  • 批量取消使用事务，减少多次提交开销；异常回滚保证一致性。
• 缓存与配置
  • 模块清单与配置在引导阶段一次性加载，减少重复IO。
• 第三方回调
  • 微信事件处理尽量轻量，避免阻塞；媒体资源查询命中索引。

故障排查指南

• 入口异常
  • 未安装引导：bootstrap.php 检测 install.lock，未安装则跳转安装程序。
  • 未捕获异常：index.php 统一捕获并输出调试页或JSON错误。
• 订单问题
  • 线下支付审核失败：检查 PaymentService 状态机推进是否成功；查看审计日志与支付台账。
  • 批量取消失败：确认事务是否回滚；检查订单状态与明细一致性。
• 优惠券问题
  • 折扣计算异常：核对条件门槛、有效期与最大折扣上限；检查 coupon_log 记录。
• 微信事件
  • XML解析失败：检查输入是否为空或格式非法；确认PHP版本与实体加载设置。

章节来源

• core/bootstrap.php:42-57
• index.php:38-75
• admin/service/order/OrderService.php:391-464
• core/service/coupon/CouponService.php:111-208
• core/service/weixin/WeixinService.php:67-99

结论

DouPHP 的业务模块以清晰的服务分层与模块化组织为核心，结合ORM、事件与事务机制，实现了商品、订单、营销与第三方集成的稳定运行。开发者可通过服务扩展点、声明式路由与配置项快速扩展现有功能，满足多样化业务需求。

附录

• 开发示例指引
  • 扩展现有功能：在服务类中添加新方法，并在控制器或路由中调用；利用 Module::make 动态注入可选模块。
  • 添加新业务逻辑：遵循 BaseService 模式，封装领域规则；使用 DB 事务保证一致性。
  • 集成第三方服务：通过专用服务类封装外部API；处理回调与事件分发。
• 业务规则配置
  • 订单相关参数：order_pay_timeout、order_allow_aftersale_time、order_allow_comment_time、order_quick_buy。
  • 模块可见性：config/module.php 控制菜单与工作区显示。
• 工作流定义
  • 订单状态机：通过核心订单服务推进；线下支付审核与批量取消需严格校验。
  • 优惠券生命周期：可领→已领→已用/过期；折扣计算贯穿下单流程。
• 权限控制
  • 后台操作通过中间件与审计日志保障；敏感操作记录管理员行为。