21 目录架构文档

本篇是 03 目录结构 的进阶版，补充分层职责、关键服务清单与数据表全景，方便快速定位代码。

顶层结构

kede-finance/
├── app/                # ThinkPHP 应用代码（多应用）
│   ├── admin/          # 后台 API 控制器
│   ├── home/           # 会员中心 / 前台 API 控制器
│   ├── api/            # 支付回调 + 开放 API（V1 上下游）
│   ├── setup/          # 安装向导
│   ├── common/         # 公共：模型/服务/驱动/助手/统一返回
│   ├── middleware/     # 鉴权、安装检测
│   ├── BaseController.php
│   ├── Request.php / ExceptionHandle.php / AppService.php
│   ├── middleware.php  # 全局中间件
│   └── common.php / event.php / provider.php / service.php
├── config/             # 应用配置（app/route/cache/database...）
├── route/app.php       # 全局路由（仅 / 与 /ping）
├── extend/modules/     # 第三方开通模块（cpanel/directadmin/plesk）
├── frontend/           # 前端源码（admin / home / theme-sdk / themes）
├── public/             # Web 根（入口、SPA 产物、插件、主题）
│   ├── index.php       # PHP 入口
│   ├── router.php      # 开发服务器分流（生产由 nginx 实现）
│   ├── admin/          # 后台 SPA 构建产物
│   ├── assets/         # 前台 SPA 构建产物
│   ├── plugins/        # 插件根目录（addon/gateway/sms/mail/certification）
│   └── themes/         # 主题（web/clientarea/cart）
├── resources/marketplace/  # 插件市场目录与发布包
├── scripts/            # 开发/构建/打包脚本
├── deploy/             # 部署：nginx 伪静态、package.sh、宝塔说明
└── vendor/             # Composer 依赖

应用分层职责

层	位置	职责
控制器 Controller	app/{admin,home,api,setup}/controller/	仅做参数收集 + 调用服务 + 统一返回，不写业务逻辑
服务 Service	app/common/service/	业务核心：订单、支付、插件、主题、迁移、升级等
模型 Model	app/common/model/	数据实体（部分表直接用 Db::name()）
助手 Helper	app/common/helper/	纯函数工具：模板渲染、商品描述、上游配置等
驱动 Driver	app/common/{gateway,notify,module}/	支付/通知/开通的可插拔驱动
中间件 Middleware	app/middleware/	InstallCheck、AdminAuth、UserAuth

核心服务清单

服务类	作用
AuthService	JWT 签发/校验、密码哈希（含魔方迁移兼容算法）
AdminPermissionService	后台 RBAC：模块权限 + 控制器映射
SettingService	系统配置读写（请求级 + 持久缓存，写入按组失效）
ProductService / ProductGroupService	商品、定价（批量）、商店目录树
ProductRuleService	上架规则、购买元数据、定价过滤
OrderService / InvoiceService	下单、账单、余额结算、续费
PaymentService	支付网关驱动调度与回调验签
ModuleService	开通/管理模块调度（人工/演示/上游/cPanel 等）
UpstreamService	上下游对接（可得↔可得、魔方/V10↔可得）
PluginService / MarketplaceService	插件扫描安装、市场目录下载
NotifyService / RealnameService	邮件短信、实名认证驱动
ThemeService	主题切换、.tpl SSR
HookService	全局钩子注册与触发
UpgradeService	官方热更新（验签/备份/应用/回滚）
MigrationService	魔方 / V10 数据库无损迁移
MaintenanceService	维护公告（按商品/分组生效）
SchemaPatch	已装系统缺列/缺索引时自动补丁（幂等）

数据表全景（前缀 kd_）

域	表
管理端	admins、admin_roles、admin_logs
客户	users、credits、realname_pending
商品	products、product_group、pricing、config_option_groups、config_options、config_suboptions、product_config_links
交易	orders、invoices、invoice_items、transactions、currencies
服务实例	hosts
营销	promo_codes、promo_uses、affiliates、affiliate_commissions、withdrawals、banners
上下游	upstreams、upstream_products、api_keys
支持	tickets、ticket_replies、ticket_departments、announcements、kb_categories、kb_articles、maintenance_notices、maintenance_scopes
平台	configs、themes、payment_gateways、addons、hooks、licenses
迁移/更新	migration_id_map、migration_logs、upgrade_logs
购物车	cart

表结构以安装向导建表 + SchemaPatch 增量补丁为准；高频查询索引由 SchemaPatch::ensureIndexes() 首次运行自动补加。

插件 / 模块 / 主题约定

• 插件：public/plugins/<type>/<name>/<CamelName>.php，命名空间 <type>\<name>，详见 04 插件系统
• 开通模块：extend/modules/<Name>/<Name>Module.php，实现 app\common\module\ModuleInterface，详见 09 开通模块
• 主题：public/themes/<web|clientarea|cart>/<theme>/，详见 10 主题与 SSR

---

下一篇：22 子用户后期开发文档