后端代码目录结构说明

1. src/ 与 Bundle 总览

src/ 下共 50 个 *Bundle 目录，每个 Bundle 对应一块独立业务域，采用 Action → Service → Repository/Entity 分层。
平台级公共能力集中在 EspierBundle。

1.1 平台基础

Bundle	一句话说明
EspierBundle	平台核心：认证授权、Dingo 集成、中间件、通用 SDK、Redis 脚本、Fractal 转换
SuperAdminBundle	超级管理员与平台级运维
CompanysBundle	企业/公司主体、多租户与公司维度配置
OpenapiBundle	对外开放 API 网关：鉴权、过滤、规则校验
DataCubeBundle	数据统计立方体与报表分析
FormBundle	自定义表单定义与数据采集
ThemeBundle	店铺主题、页面装修与视觉配置
TdksetBundle	页面 SEO 的 Title / Description / Keywords
ShopmenuBorderBundle	店铺导航菜单边框与样式配置

1.2 商品

Bundle	说明
GoodsBundle	商品 SPU/SKU、分类、属性、库存
TbItemsBundle	淘宝/外部平台商品同步
PointsmallBundle	积分商城商品与兑换
CommentsBundle	商品评价、晒单与评论

1.3 订单 / 交易

Bundle	说明
OrdersBundle	订单创建、状态流转、支付与履约
AftersalesBundle	售后申请、退款、退货
ReservationBundle	预约类/服务类订单
DepositBundle	定金、预售与分阶段支付
CrossBorderBundle	跨境贸易订单、报关

1.4 支付

Bundle	说明
PaymentBundle	支付抽象层（无 Entity，交易以 trade 表为代表）
AdaPayBundle	汇付 AdaPay
BsPayBundle	汇付斗拱（BsPay）
ChinaumsPayBundle	银联商务
HfPayBundle	汇付 HfPay
IcbcPayBundle	工商银行 ICBC

1.5 会员 / 营销

Bundle	说明
MembersBundle	会员注册、资料、等级
PointBundle	积分规则与流水
PromotionsBundle	满减、折扣、活动等促销
KaquanBundle	卡券、优惠券模板与核销
PopularizeBundle	推广员、裂变与分享
OneCodeBundle	一物一码、扫码溯源
EmployeePurchaseBundle	员工内购专区

1.6 渠道 / 店铺

Bundle	说明
DistributionBundle	分销渠道、经销商与分润
MerchantBundle	商户入驻、门店管理
SupplierBundle	供应商档案、供货与结算
SalespersonBundle	导购员与业绩归属
SelfserviceBundle	自助收银、自助终端

1.7 微信 / 社交

Bundle	说明
WechatBundle	微信公众号、小程序消息与 OAuth
WorkWechatBundle	企业微信通讯录、客户联系
ImBundle	即时通讯、在线客服
CommunityBundle	社区帖子、话题与互动
WsugcBundle	微信侧 UGC 同步

1.8 第三方 / ERP

Bundle	说明
SystemLinkBundle	Shopex ERP / 系统链路同步
ThirdPartyBundle	通用第三方回调与适配
ShuyunBundle	数云 CRM 对接
ShuyunOpenPlatformBundle	数云开放平台
YoushuBundle	有数数据分析
ShopexAIBundle	ShopeX AI 能力
KujialeBundle	酷家乐 3D 设计对接
AliBundle	阿里云 OSS、日志等
AliyunsmsBundle	阿里云短信

---

2. 典型 Bundle 内部结构

以 GoodsBundle 为典型示例：

GoodsBundle/
├── Api/              # 对外 API 契约或 DTO（部分 Bundle）
├── ApiServices/      # API 层专用服务
├── Console/          # Artisan 命令
├── Entities/         # Doctrine 实体
├── Events/           # 领域事件
├── Http/             # Action 控制器（Api / Frontapi / Admin 等）
├── Jobs/             # 异步队列任务
├── Listeners/        # 事件监听器
├── Providers/        # Service Provider
├── Repositories/     # 数据访问层
├── Routes/           # Bundle 内路由片段（若有）
├── Services/         # 业务逻辑层
└── Traits/           # 可复用 Trait

HTTP 分层示例：

Http/Api/V1/Action/Items.php    # 商品 API 入口

结构变体

Bundle	特点
EspierBundle	含 Auth、Dingo、Middleware、Sdk、RedisLuaScript、Fractal
GoodsBundle	完整业务栈参考模板
CommentsBundle	精简型：Entities、Http、Repositories、Services
OpenapiBundle	网关型：Constants、Filter、Middleware、Rules、Exceptions

---

3. 架构分层

层级	位置	职责
路由	routes/{端}/{模块}.php	URL、HTTP 方法、中间件、Action 绑定
控制器	{Bundle}\Http\{Api|Frontapi}\V1\Action\{Name}	参数校验、调用 Service、返回响应
服务	{Bundle}\Services\{Name}Service	业务规则、事务编排
仓储	{Bundle}\Repositories\{Name}Repository	Doctrine 查询与持久化
实体	{Bundle}\Entities\{Name}	表结构与字段映射

商品列表示例链路：

routes/api/goods.php
  → GoodsBundle\Http\Api\V1\Action\Items@getItemsList
    → GoodsBundle\Services\ItemsService
      → GoodsBundle\Repositories\ItemsRepository
        → GoodsBundle\Entities\Items

---

4. 命名规范

类型	约定	示例
Bundle 目录	{Domain}Bundle，PascalCase	GoodsBundle
Action	{Resource}.php，方法动词开头	Items@getItemsList
Service	{Resource}Service.php	ItemsService.php
Repository	{Resource}Repository.php	ItemsRepository.php
Entity	单数名词	Items、Orders
路由文件	小写模块名	routes/api/goods.php
路由命名 as	{模块}.{资源}.{动作}	goods.items.lists
Console 命令	{Bundle}\Console\Commands\{Name}Command	—
测试类	{被测类}{场景}Test.php	tests/ 下

命名空间与 PSR-4 见 composer.json 的 autoload.psr-4（src/ 映射到各 Bundle 根命名空间）。

---

5. 新增功能放哪

1. 新业务域：在 src/ 下新建 {Domain}Bundle，注册 Provider，在 routes/ 对应端增加路由文件。
2. 现有域扩展：在对应 Bundle 的 Http/Action、Services、Entities 中扩展。
3. 横切能力（认证、缓存、日志）：优先扩展 EspierBundle；确需应用级横切时可放在 app/（不写业务域逻辑）。
4. 对外开放 API：经 OpenapiBundle 网关注册与校验。