项目介绍与特性 | DouPHP 开发手册 | 文档中心

项目介绍与特性

简介

DouPHP 企业级内容管理系统是一套面向企业官网、电商平台、内容管理与教育平台的综合解决方案。系统以模块化与插件化为核心，提供 CMS（文章、产品、案例、课程等）、电商（商品管理、订单处理、支付集成）、用户系统（注册登录、权限管理、会员等级）、营销工具（优惠券、促销活动、分销系统）以及 AI 能力（智能聊天、图像生成）等完整功能集。通过多主题与多语言国际化支持，满足企业级复杂业务场景的构建与扩展需求。

最新更新：系统已完成导航集中化改造，采用AdminMenuRegistry统一管理后台菜单，并通过AdminNavResolver实现基于路由名的集中式高亮计算，同时在前台提供$route_module/$route_action页面事实变量用于内容分支判断。

项目结构

入口与引导：根入口 index.php 负责路由委派与异常处理；core/bootstrap.php 完成环境检测、路径常量定义、配置加载、自动加载、DI 容器初始化与请求对象绑定。
三端分离：前台 front、后台 admin、API 接口 api，各自具备独立的控制器、服务、模型、路由与中间件。
模块与主题：config/module.php 声明列模块与单模块，统一控制菜单与导航展示；theme 与 newtheme 提供多主题切换能力。
插件生态：plugin 目录内置多种支付与第三方接入插件，便于按需启用。
小程序：miniprogram 提供小程序端类型与页面资源，配合后端 features 开关实现动态能力下发。

graph TB
A["入口 index.php"] --> B["引导 core/bootstrap.php"]
B --> C["配置 config/config.php"]
B --> D["模块清单 config/module.php"]
A --> E["前台 front"]
A --> F["后台 admin"]
A --> G["API api"]
E --> H["主题 theme / newtheme"]
F --> I["插件 plugin"]
G --> J["小程序 miniprogram"]
F --> K["导航集中化 AdminMenuRegistry"]
E --> L["页面事实变量 $route_module/$route_action"]

图表来源

index.php:1-126
core/bootstrap.php:1-180
config/config.php:1-53
config/module.php:1-132
admin/service/menu/AdminMenuRegistry.php:23-63
front/controller/BaseController.php:64-109

章节来源

index.php:1-126
core/bootstrap.php:1-180
config/config.php:1-53
config/module.php:1-132

核心组件

路由与请求：入口将路由委派给前台路由器，解析语言前缀并注入 Request；全局异常处理器根据 JSON 请求或站点调试模式输出错误。
配置与模块：集中定义数据库连接、应用密钥、调试开关；模块清单决定前端菜单、导航与小程序能力开关。
数据模型与 ORM：各模块通过 AR 模型定义表映射、字段转换、可翻译字段与列表预取策略，提升查询与渲染效率。
服务层：业务逻辑集中在 Service，如订单详情组装、评论权限校验、优惠券计算等，保证控制器轻量与职责清晰。
表单与校验：后台使用 FormRequest 进行输入校验，失败时抛出领域异常并由统一入口捕获。
多语言与主题：语言包按模块组织，主题目录提供模板与静态资源，支持多主题切换。
小程序对接：通过 features 字段向小程序下发可用模块，前端据此渲染对应页面。
导航集中化：后台采用AdminMenuRegistry统一管理菜单定义，通过AdminNavResolver实现基于路由名的集中式高亮计算。

章节来源

index.php:1-126
core/bootstrap.php:1-180
config/module.php:1-132
front/model/certificate/Certificate.php:43-89
admin/request/order/OrderTrackingFormRequest.php:1-46
miniprogram/company/types/api.d.ts:46-106
admin/service/menu/AdminMenuRegistry.php:23-63

架构总览

系统采用"入口-引导-路由-控制器-服务-模型"的分层架构，结合 DI 容器与门面简化依赖注入与全局访问。前台、后台与 API 共享核心库与服务，确保一致的业务语义与数据一致性。

sequenceDiagram
participant U as "浏览器"
participant R as "入口 index.php"
participant B as "引导 bootstrap.php"
participant RT as "前台路由器"
participant C as "控制器"
participant S as "服务层"
participant M as "模型/ORM"
participant DB as "数据库"
U->>R : HTTP 请求
R->>B : 启动引导
B-->>R : 已就绪(配置/容器/请求)
R->>RT : 分发路由
RT->>C : 调用控制器动作
C->>S : 执行业务逻辑
S->>M : 读取/写入数据
M->>DB : SQL 操作
DB-->>M : 结果集
M-->>S : 模型对象
S-->>C : 业务结果
C-->>U : 响应(HTML/JSON)
Note over C : 前台控制器注入$route_module/$route_action<br/>后台控制器通过AdminNavResolver解析菜单

图表来源

index.php:1-126
core/bootstrap.php:1-180
front/controller/BaseController.php:64-109
admin/service/menu/AdminMenuRegistry.php:23-63

详细组件分析

内容管理（CMS）

能力范围：文章、产品、案例、课程、文档、下载、图库、视频、证书等列模块与单模块统一管理。
模型设计：以 AR 模型定义表名、主键、字段转换、可翻译字段与列表预取，减少 N+1 查询。
示例说明：资质证书模型定义了单模块、列表可展示、附件 URL 转换与多语言字段映射。

classDiagram
class Certificate {
+table : "certificate"
+moduleSchema() array
+casts : array
+appends : array
+translatable : array
+prefetchers : array
+findPublishedById(id) Model|null
}

图表来源

front/model/certificate/Certificate.php:43-89

章节来源

front/model/certificate/Certificate.php:43-89

电商平台（商品与订单）

商品管理：商品类目、属性、品牌、库存、价格等由对应模块管理，配合主题模板展示。
订单处理：后台订单服务负责列表筛选、详情组装、发货与线下付款审核、批量删除与取消、销售额统计与自动化任务触发。
物流跟踪：后台表单请求对物流字段进行校验，服务层在首次发货时推进状态并解锁库存。

flowchart TD
Start(["开始"]) --> Validate["校验物流字段<br/>order_id/shipping_id/tracking_no"]
Validate --> Valid{"校验通过?"}
Valid -- 否 --> Err["返回校验错误"]
Valid -- 是 --> Update["更新订单物流信息"]
Update --> FirstShip{"是否首次发货?"}
FirstShip -- 是 --> Advance["推进订单状态并解锁库存"]
FirstShip -- 否 --> Skip["仅记录物流信息"]
Advance --> Done(["结束"])
Skip --> Done
Err --> Done

图表来源

admin/request/order/OrderTrackingFormRequest.php:1-46
_'/module/order/admin/service/order/OrderService.php:1-304

章节来源

_'/module/order/admin/service/order/OrderService.php:1-304
admin/request/order/OrderTrackingFormRequest.php:1-46

用户系统（注册登录、权限、会员等级）

登录模式：支持邮箱、手机号、微信登录等多种方式，可通过参数配置选择唯一 ID（如 unionid）。
会员中心：会员资料、余额、积分、消费统计、推广金等聚合视图，便于运营与数据分析。
权限与角色：后台基于中间件与授权服务控制管理员与角色的访问权限。

sequenceDiagram
participant U as "用户"
participant F as "前台控制器"
participant S as "用户服务"
participant DB as "数据库"
U->>F : 提交登录(邮箱/手机/微信)
F->>S : 验证账号与密码/第三方凭证
S->>DB : 查询用户与等级信息
DB-->>S : 用户数据
S-->>F : 登录结果(会话/令牌)
F-->>U : 跳转会员中心或首页

章节来源

_'/module/user/languages/zh_cn/admin/user.lang.php:1-177

营销工具（优惠券、促销、分销）

优惠券：支持领取、使用与核销，订单详情中汇总使用的优惠券与折扣金额。
促销活动：可与商品、类目、活动页联动，灵活设置优惠规则。
分销系统：支持多级分销、佣金结算与提现流程，结合会员等级与积分体系增强转化。

sequenceDiagram
participant O as "订单服务"
participant C as "优惠券服务"
participant P as "支付服务"
participant DB as "数据库"
O->>C : 计算可用优惠券与折扣
C->>DB : 查询优惠券状态与条件
DB-->>C : 优惠券明细
C-->>O : 折扣信息与使用记录
O->>P : 发起支付(含优惠后金额)
P-->>O : 支付结果
O-->>O : 更新订单状态与发放权益

图表来源

_'/module/order/admin/service/order/OrderService.php:264-304

章节来源

_'/module/order/admin/service/order/OrderService.php:264-304

AI 功能（智能聊天、图像生成）

智能聊天：提供会话管理、知识库、任务调度与配额控制，支持后台配置与监控。
图像生成：集成多提供商，支持批量生成、字段填充与翻译辅助，提升内容生产效率。
能力下发：小程序通过 features 字段感知 AI 能力是否启用，动态渲染相应页面。

graph LR
A["AI 控制器"] --> B["AI 服务"]
B --> C["提供商接口"]
B --> D["任务队列"]
A --> E["会话/知识/配额管理"]
F["小程序 features"] --> |能力开关| A

图表来源

miniprogram/company/types/api.d.ts:46-106

章节来源

miniprogram/company/types/api.d.ts:46-106

导航集中化管理（新增）

后台菜单集中化：采用AdminMenuRegistry统一管理所有后台菜单定义，支持声明式配置和动态装配。
路由名匹配机制：通过AdminNavResolver基于路由名进行菜单高亮计算，替代传统的手写cur变量方式。
模块菜单声明：各模块通过admin/nav/<module>.php文件声明子菜单族，随模块安装/卸载生命周期管理。
侧栏节点管理：sideNodes()方法定义侧边栏节点，支持权限控制和条件显示。

flowchart TD
A["路由命中"] --> B["AdminNavResolver::resolve()"]
B --> C["匹配AdminMenuRegistry中的match规则"]
C --> D["计算当前激活菜单项"]
D --> E["返回$nav契约结构"]
E --> F["模板渲染高亮菜单"]

图表来源

admin/service/menu/AdminMenuRegistry.php:23-63
admin/nav/ai.php:15-49

章节来源

admin/service/menu/AdminMenuRegistry.php:23-63
admin/nav/ai.php:15-49

页面事实变量与语义分离（新增）

$route_module/$route_action变量：前台控制器自动注入当前路由的模块名和动作名，作为页面事实变量供模板使用。
语义分离原则：$route_module/$route_action用于内容分支判断，cur用于菜单高亮，两者职责明确分离。
NavigationBuilder上下文：通过contextModule()方法获取最近一次middle()解析的归属模块，派生顶层cur变量。
防混用机制：禁止使用$route_module/$route_action进行菜单高亮，避免复活字符串比较链。

sequenceDiagram
participant C as "控制器"
participant NB as "NavigationBuilder"
participant BC as "BaseController"
participant T as "模板"
C->>NB : middle(currentModule, currentId, parentId)
NB->>NB : contextModule = currentModule
C->>BC : view(template, data)
BC->>BC : pageFactVars()
BC->>T : 注入$route_module/$route_action
T->>T : 使用变量进行内容分支判断
Note over T : 菜单高亮使用cur而非$route_*变量

图表来源

front/controller/BaseController.php:64-109
front/service/nav/NavigationBuilder.php:72-90

章节来源

front/controller/BaseController.php:64-109
front/service/nav/NavigationBuilder.php:72-90
_'\doc\开发手册\系统结构分析.md:220-230

多主题与多语言国际化

多主题：theme 与 newtheme 目录提供丰富模板与样式，支持一键切换与定制。
多语言：languages 目录按语言组织文案，模块内语言包便于本地化维护。
小程序：bootstrap 下发 site、param、features、lang_v 等，客户端据此拉取语言包并缓存。

章节来源

config/config.php:1-53
miniprogram/company/types/api.d.ts:108-154

依赖关系分析

入口与引导：index.php 依赖 bootstrap 完成环境准备与路由委派；bootstrap 加载配置与模块清单，注册自动加载与门面别名。
模块与能力：config/module.php 决定前台菜单、导航与小程序 features；小程序据此决定是否显示相关页面。
业务耦合：订单服务依赖优惠券与支付服务，形成清晰的依赖链；评论服务依赖订单与商品模型，进行权限校验与链接构建。
导航依赖：AdminMenuRegistry依赖模块声明文件，AdminNavResolver依赖路由名匹配规则，NavigationBuilder依赖Request对象获取路由事实。

graph TB
X["入口 index.php"] --> Y["引导 bootstrap.php"]
Y --> Z["配置 module.php"]
Z --> W["小程序 features"]
O["_'/module/order/admin/service/order/OrderService.php"] --> Q["优惠券服务"]
O --> R["支付服务"]
C["front/service/comment/CommentService.php"] --> D["订单模型"]
C --> E["商品模型"]
K["AdminMenuRegistry"] --> L["模块nav声明文件"]
M["AdminNavResolver"] --> K
N["NavigationBuilder"] --> O["Request对象"]

图表来源

index.php:1-126
core/bootstrap.php:1-180
config/module.php:1-132
_'/module/order/admin/service/order/OrderService.php:1-304
front/service/comment/CommentService.php:142-162
admin/service/menu/AdminMenuRegistry.php:23-63

章节来源

config/module.php:1-132
front/service/comment/CommentService.php:142-162

性能考量

模型预取：通过 casts、appends 与 prefetchers 减少重复查询与格式化开销。
列表优化：在服务层按需 enrich 字段，避免在模型层做重计算。
缓存与指纹：小程序通过 lang_v 与 version 进行缓存失效判断，降低重复请求。
路由与中间件：统一异常处理与 JSON 协商，减少分支判断成本。
导航性能优化：AdminMenuRegistry采用请求级缓存，NavigationBuilder全表静态缓存，避免重复数据库查询。

故障排查指南

未安装引导：若 storage/install.lock 不存在，入口会跳转到安装程序，需先完成安装。
异常处理：入口捕获 DomainException 与全局异常，根据 JSON 请求与站点调试模式输出 HTML 或 JSON 错误。
配置检查：确认数据库连接与应用密钥正确，必要时开启 DOU_DEBUG 获取更详细错误信息。
导航问题排查：检查AdminMenuRegistry中的match规则是否正确，确认模块nav声明文件是否存在且格式正确。

章节来源

core/bootstrap.php:42-57
index.php:46-75
config/config.php:48-53

结论

DouPHP 以模块化与插件化为核心，覆盖 CMS、电商、用户、营销与 AI 等企业级关键能力，并通过多主题与多语言国际化满足多样化业务场景。其分层架构与统一异常处理保障了系统的可维护性与稳定性，适合用于企业官网建设、电商网站开发、内容管理平台与教育平台等项目。

最新改进：导航集中化改造显著提升了菜单管理的可维护性，通过AdminMenuRegistry和AdminNavResolver实现了声明式菜单配置和基于路由名的智能高亮计算。页面事实变量$route_module/$route_action提供了清晰的内容分支判断机制，与菜单高亮职责分离，避免了传统的字符串比较链问题。

附录

适用场景
- 企业官网：品牌展示、新闻公告、案例与技术支持。
- 电商平台：商品管理、订单处理、支付集成与售后。
- 内容管理平台：文章、文档、下载、图库与视频。
- 教育平台：课程、讲师、报名与学习进度。
核心价值主张
- 开箱即用：内置丰富模块与主题，快速搭建。
- 灵活扩展：插件化与模块化，按需启用与定制。
- 全渠道覆盖：PC、移动端与小程序一体化体验。
- 智能化赋能：AI 聊天与图像生成提升内容生产效率。
- 现代化架构：导航集中化与页面事实变量分离，提升代码可维护性和扩展性。

添加日期：2026-10-05