# 1.5 技术栈说明

## 后端技术栈

| 类别 | 技术选型 | 版本 | 说明 |
|------|----------|------|------|
| 语言 | PHP | >= 8.3 | 强类型严格模式（composer.json `^8.3`） |
| 框架 | Laravel | 13.x | 核心 Web 框架（`laravel/framework ^13.0`） |
| ORM | Eloquent | 随框架 | 数据库操作，模型薄封装 + Trait 复用 |
| 认证 | firebase/php-jwt | 7.1+ | JWT 双令牌签发与解析（Redis 有状态） |
| Excel | phpoffice/phpspreadsheet | 5.10+ | Excel 导入导出 |
| IP 归属地 | zoujingli/ip2region | 3.0+ | 登录日志 IP 归属地解析（IPv4/IPv6） |
| 数据库 | MySQL | 8.0+ | 主数据库（另支持 PostgreSQL / SQL Server / Oracle / SQLite，五套初始化脚本齐备） |
| 缓存 | Redis | 6.0+ | **必需**：JWT 会话、权限缓存、验证码、字典缓存（phpredis 扩展） |
| Web 服务器 | Nginx | 1.18+ | 推荐（Docker 方案内置） |
| Web 服务器 | Apache | 2.4+ | 兼容（Laragon mod_php 方式，见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)） |
| 包管理 | Composer | 2.x | 依赖管理（`composer setup` 一键初始化） |
| 代码格式化 | laravel/pint | 1.27+（dev） | 提交前格式化（Pint 风格） |
| 日志查看 | laravel/pail | 1.2+（dev） | 实时日志流（`composer dev` 内置） |
| 测试 | phpunit/phpunit | 12.5+（dev） | Feature / Unit 测试 |

## 前端技术栈

前端为本仓库 `ui/` 目录内的 AntdVue 管理后台（Vue3 + AntDesign），与本后端通过 API 对接：

| 类别 | 技术选型 | 版本 | 说明 |
|------|----------|------|------|
| 框架 | Vue | 3.4+ | 核心 UI 框架（Composition API） |
| 语言 | TypeScript | 4.9+（实际 ^4.9.5） | 类型安全 |
| UI 库 | AntDesign Vue | 3.2+（实际 3.2.20） | 组件库 |
| 构建工具 | Vite | 3.2+（实际 ^3.2.10） | 开发服务器与构建 |
| 状态管理 | Pinia | 2.1+ | 全局状态管理 |
| 路由 | Vue Router | 4.3+ | 路由管理 |
| HTTP | Axios | 0.27+（实际 ^0.27.2） | HTTP 请求（注：0.27.x 版本较老） |
| 富文本 | TinyMce | 5.10+ | 富文本编辑器 |
| 图表 | ECharts | 5.5+ | 数据可视化 |
| CSS | TailwindCSS | 3.4+ | 原子化 CSS |
| 权限 | v-perm 指令 | - | 按钮级权限指令，与后端 `#[Permission]` 对应 |
| 包管理 | pnpm | - | 高效包管理器 |

:::tip
前端工程结构、开发实践详见 [第 9 章 前端开发](/zh/frontend/overview.html)；后端代码生成器会把前端页面模板输出到 `ui/` 目录（见 [10.6 自定义模板开发](/zh/generator/templates.html)）。
:::

## 架构特点

一次 API 请求的完整链路（与 [4.2 请求处理链路](/zh/architecture/request-flow.html) 一致）：

```text
┌─────────────────────────────────────────────────────────┐
│                  前端（Vue3 + AntDesign）               │
│            通过 API 调用后端服务，纯 JSON 交互              │
└──────────────────────────┬──────────────────────────────┘
                           │ HTTP (JSON)
                           ▼
┌─────────────────────────────────────────────────────────┐
│                     后端（Laravel 13）                    │
│                                                          │
│  路由(routes/api.php) → 中间件栈 → 控制器 → 服务 → 模型    │
│                                                          │
│  中间件栈（7 个）：                                        │
│  Proxy(真实IP) → Cors(跨域) → ForceJsonResponse(强制JSON) │
│    → auth.jwt(JWT认证+#[Permission]鉴权)                   │
│    → tenant(租户上下文) → log.operation(操作日志)            │
│    → Demo(演示模式防护)                                    │
│                                                          │
│  Service 层：BaseService 属性声明 + 6 个 Trait 组合          │
│  （CRUD / 查询 / 文件 / 数据权限 / 字典翻译 / 唯一校验）      │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   数据层（MySQL + Redis）                  │
│   MySQL 主存储（Eloquent + 软删除 + 审计字段）               │
│   Redis 会话 / 缓存 / 队列（JWT 双令牌、字典、权限缓存）      │
└─────────────────────────────────────────────────────────┘
```

核心设计决策：

| 决策 | 说明 |
|------|------|
| 声明式配置 + 基类钩子 | Service 子类只声明属性（查询字段、唯一规则、字典映射…），通用逻辑由 BaseService + 6 个 Trait 完成 |
| 菜单即权限 | `menu.permission` 字段即权限编码，`#[Permission]` 注解 + 中间件反射鉴权 |
| 统一响应 | HTTP 200 + body `{code, ok, msg, data}`，camelCase/snake_case 自动转换 |
| fail-close 安全 | `JWT_SECRET` 为空或不足 32 字符时拒绝启动（AppServiceProvider 启动校验） |
| 验证职责分层 | FormRequest 只做格式验证，Service 只做业务规则 |