# 4.5 目录结构设计

:::tip 概述
目录结构遵循"按职责分层、按模块分组"的原则。后端以 `app/` 为核心，按 Controller → Logic → Model → Validate 四层组织；前端以 `src/` 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。
:::

## 后端整体结构

```text
项目根目录/
├── app/                    ← 应用代码（核心）
├── config/                 ← 配置文件
├── extend/                 ← 扩展类库（非 Composer）
├── public/                 ← Web 入口 + 静态资源
├── route/                  ← 路由定义
├── templates/              ← 代码生成器模板
├── runtime/                ← 运行时缓存（自动生成）
├── vendor/                 ← Composer 依赖
├── document/               ← 开发参考手册（txt）
├── .env                    ← 环境变量配置
└── think                   ← ThinkPHP 命令行入口
```

## app/ 目录详解

```text
app/
├── BaseController.php        控制器基类
├── BaseModel.php             模型基类
├── BaseLogic.php             业务逻辑基类（系统共享模块）
├── BaseTenantLogic.php       租户逻辑基类（租户隔离模块）
├── ExceptionHandle.php       统一异常处理（JSON 响应）
├── Request.php               请求类扩展
├── common.php                公共函数库
├── event.php                 事件定义
├── middleware.php             全局中间件注册
│
├── controller/               控制器层（28 个）
├── logic/                    业务逻辑层（26 个）
├── model/                    数据模型层（25 个）
├── validate/                 验证器（21 个）
├── service/                  通用服务层（11 个）
├── middleware/               中间件（5 个）
├── attribute/                注解定义（3 个）
├── command/                  命令行命令（4 个）
└── task/                     定时任务处理器（3 个）
```

### 各目录职责与命名规范

| 目录 | 职责 | 命名规则 | 数量 | 说明 |
|------|------|----------|------|------|
| `controller/` | HTTP 请求入口 | `{Module}Controller.php` | 28 | 一个模块一个文件，注解标注权限和日志 |
| `logic/` | 业务逻辑 | `{Module}Logic.php` | 26 | 属性配置 + 生命周期钩子，核心业务层 |
| `model/` | 数据库映射 | `{TableName}.php`（大驼峰） | 25 | 继承 BaseModel，获软删除 + 审计字段 |
| `validate/` | 参数校验 | `{Module}Validate.php` | 21 | 定义规则 + 场景，Logic 层自动调用 |
| `service/` | 通用服务 | `{Name}Service.php` | 11 | 跨模块复用的无状态工具类 |
| `middleware/` | 中间件 | `{Name}Middleware.php` | 5 | 请求拦截：认证、租户、日志等 |
| `attribute/` | 注解类 | `{Name}.php` | 3 | PHP 8 注解：Log、Permission、DemoAllow |
| `command/` | 命令行 | `{Name}Command.php` | 4 | CLI 命令：定时任务、代码生成、迁移 |
| `task/` | 任务处理器 | `{Name}Task.php` | 3 | 定时任务的具体执行逻辑 |

### 模块文件对应关系

以"用户管理"模块为例，一个完整模块包含 4 个文件：

```text
app/
├── controller/UserController.php    ← HTTP 入口（路由指向这里）
├── logic/UserLogic.php              ← 业务逻辑（属性配置 + 钩子）
├── model/User.php                   ← 数据模型（表映射）
└── validate/UserValidate.php        ← 参数校验（规则 + 场景）
```

请求流转：`Controller → Logic → Model → 数据库`

### 基类与公共文件

| 文件 | 说明 |
|------|------|
| `BaseController.php` | 控制器基类：统一响应、参数获取、通用 CRUD 快捷方法 |
| `BaseLogic.php` | 逻辑基类：声明式 CRUD、生命周期钩子、自动参数校验、文件/富文本/枚举/权限/租户处理 |
| `BaseTenantLogic.php` | 租户逻辑基类：继承 BaseLogic，自动启用 `tenant_id` 隔离 |
| `BaseModel.php` | 模型基类：软删除（`is_delete`）、审计字段自动写入 |
| `ExceptionHandle.php` | 异常处理：所有异常统一渲染为 JSON 响应 |
| `common.php` | 公共函数：字符串处理、加密、文件操作、驼峰转换等 |
| `event.php` | 事件定义：全局事件监听 |
| `middleware.php` | 全局中间件注册：CORS 等 |

### service/ 服务层清单

服务层提供跨模块复用的无状态能力，按单一职责拆分：

| 服务 | 文件 | 说明 |
|------|------|------|
| JWT 认证 | `JwtService.php` | 登录、刷新、解析 Token |
| 密码加密 | `PasswordService.php` | bcrypt 双重加盐 |
| 字典服务 | `DictService.php` | 字典缓存与查询（两级缓存） |
| 系统参数 | `ParamService.php` | 系统参数服务（两级缓存） |
| 验证码 | `CaptchaService.php` | 图片验证码生成与校验 |
| 请求信息 | `RequestInfoService.php` | 客户端 IP、UA、归属地解析 |
| 注解读取 | `AttributeService.php` | PHP 8 注解反射读取 + 缓存 |
| 代码生成 | `GeneratorService.php` | 根据数据库表生成 CRUD 代码 |
| 数据库迁移 | `DbMigrateService.php` | 跨数据库迁移引擎 |
| DDL 生成 | `DbSchemaBuilder.php` | 跨库类型映射的 DDL 生成器 |
| Excel | `ExcelService.php` | 导入导出（支持大数据量分批） |

### middleware/ 中间件清单

| 中间件 | 文件 | 作用域 | 说明 |
|--------|------|--------|------|
| 跨域 | `CorsMiddleware.php` | 全局 | CORS 头设置 |
| 认证权限 | `AuthMiddleware.php` | 路由级 | JWT 校验 + 权限校验 |
| 租户上下文 | `TenantMiddleware.php` | 路由级 | 解析注入 tenantId |
| 演示环境 | `DemoMiddleware.php` | 路由级 | 演示环境写操作拦截 |
| 操作日志 | `LogMiddleware.php` | 路由级 | 基于注解记录操作日志 |

### command/ 命令行清单

| 命令 | 文件 | 说明 |
|------|------|------|
| 定时任务执行 | `JobRunCommand.php` | 执行一次定时任务 |
| 定时任务守护 | `JobDaemonCommand.php` | 常驻进程循环扫描执行 |
| 代码生成 | `GeneratorCommand.php` | CLI 方式生成 CRUD 代码 |
| 数据库迁移 | `DbMigrateCommand.php` | 跨数据库迁移 CLI 工具 |

## config/ 配置文件

```text
config/
├── api.php                   API 配置（驼峰转换开关）
├── app.php                   应用配置（调试模式、异常处理）
├── cache.php                 缓存配置（支持 Redis）
├── console.php               命令行配置
├── cors.php                  跨域配置
├── database.php              数据库配置
├── file.php                  文件上传配置（域名、大小限制）
├── jwt.php                   JWT 配置（密钥、过期时间）
├── middleware.php            中间件排除列表
└── route.php                 路由配置
```

| 配置文件 | 关键配置项 | 说明 |
|----------|-----------|------|
| `api.php` | `camel_snake_convert` | 驼峰/下划线自动转换开关 |
| `database.php` | `type` / `hostname` / `database` | 数据库连接（支持 MySQL/PG/SqlServer/Oracle/SQLite） |
| `file.php` | `domain_url` / `max_size` | 文件上传域名和大小限制 |
| `jwt.php` | `secret` / `access_ttl` / `refresh_ttl` | JWT 密钥和令牌有效期 |
| `cache.php` | `type` / `host` | 缓存驱动（file/redis） |

## extend/ 扩展类库

存放不通过 Composer 管理的自定义类库，按 PSR-4 自动加载：

```text
extend/
├── jwt/
│   └── Jwt.php               JWT 工具类（封装 firebase/php-jwt）
├── response/
│   └── Result.php            统一响应类（success/fail/page 等）
└── (无自定义扩展类)
```

使用方式：直接通过命名空间引用，如 `\response\Result::success()`、`\jwt\Jwt::getTokenFromHeader()`。

## route/ 路由定义

```text
route/
└── app.php                   应用路由定义（所有 API 路由）
```

路由按模块分组，示例：

```php
// 公开接口（无需认证）
Route::group('login', function () {
    Route::post('login', 'LoginController/login');
    Route::get('captcha', 'LoginController/captcha');
});

// 需认证接口（AuthMiddleware）
Route::group('article', function () {
    Route::get('page', 'ArticleController/page');
    Route::post('add', 'ArticleController/add');
    Route::put('update', 'ArticleController/update');
    Route::delete('delete/:id', 'ArticleController/delete');
})->middleware(AuthMiddleware::class);
```

## templates/ 代码生成模板

```text
templates/
├── controller.php.tpl        控制器模板
├── logic.php.tpl             业务逻辑模板
├── model.php.tpl             模型模板
├── validate.php.tpl          验证器模板
├── ui/                       普通列表前端模板
└── ui2/                      树形结构前端模板
```

由 `GeneratorService` 渲染，通过代码生成器 CLI 或 API 调用。

## 前端目录设计

```text
ui/src/
├── api/            ← API 接口（按业务域分组）
├── views/          ← 页面视图（按业务域分组）
├── components/     ← 公共组件（跨页面复用）
├── store/          ← 状态管理（Pinia）
├── router/         ← 路由配置
├── hooks/          ← 组合式函数
├── directives/     ← 自定义指令
├── enums/          ← 枚举常量
├── styles/         ← 全局样式
├── utils/          ← 工具函数
├── layout/         ← 布局组件
├── plugins/        ← 插件
├── settings/       ← 项目配置
└── assets/         ← 静态资源
```

## 前后端目录对应关系

| 后端 | 前端 | 说明 |
|------|------|------|
| `app/controller/UserController.php` | `src/api/system/user.ts` | API 接口函数 |
| `app/logic/UserLogic.php` | `src/views/system/user/` | 业务页面 |
| `app/model/User.php` | — | 前端不直接操作模型 |
| `app/validate/UserValidate.php` | — | 前端校验由表单组件处理 |
| `route/app.php` | `src/api/**/*.ts` | 路由 ↔ API 函数映射 |
| `config/dict*.php` | `src/enums/` | 字典 ↔ 枚举常量 |

## 设计原则

### 按职责分层

每层只做一件事，层间通过方法调用串联：

| 层 | 职责 | 不应该做 |
|----|------|----------|
| Controller | 参数获取、响应封装、注解标注 | 业务逻辑、数据库操作 |
| Logic | 业务编排、钩子处理、校验 | 直接 HTTP 交互 |
| Model | 表映射、关联关系、软删除 | 复杂业务判断 |
| Validate | 参数格式校验 | 业务规则校验 |

### 按模块分组

同一业务模块的 4 个文件（Controller / Logic / Model / Validate）分散在各自目录中，通过命名前缀关联。这种"水平分层 + 垂直命名"的方式：

- 便于按职责查找（所有控制器在一起）
- 便于代码生成器按模板批量生成
- 便于基类统一处理（如 BaseLogic 的属性驱动）

### 文件命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 控制器 | 大驼峰 + Controller | `ArticleController.php` |
| 逻辑层 | 大驼峰 + Logic | `ArticleLogic.php` |
| 模型 | 大驼峰（表名） | `Article.php` |
| 验证器 | 大驼峰 + Validate | `ArticleValidate.php` |
| 服务 | 大驼峰 + Service | `DictService.php` |
| 中间件 | 大驼峰 + Middleware | `AuthMiddleware.php` |
| 注解 | 大驼峰 | `Log.php`、`Permission.php` |
| 命令 | 大驼峰 + Command | `GeneratorCommand.php` |
| 任务 | 大驼峰 + Task | `SendSmsTask.php` |