> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 后端概览

后端是基于 Laravel 13 的应用，要求 PHP 8.3。代码保留 Laravel 的目录习惯，并通过注解路由、统一响应和系统管理模型提供后台开发基础。

## 主要分层

| 位置                            | 职责                          |
| ----------------------------- | --------------------------- |
| `app/Http/Controllers/Admin/` | 用户、角色、部门、字典、文件、配置和 AI 等管理接口 |
| `app/Http/Controllers/Api/`   | 面向其他客户端的接口                  |
| `app/Http/Requests/Admin/`    | 后台表单验证与授权请求                 |
| `app/Models/`                 | Eloquent 模型与关联关系            |
| `app/Services/`               | 文件等业务服务                     |
| `app/Trait/RequestJson.php`   | 成功、失败、警告和通知响应               |
| `database/migrations/`        | 系统表、用户表、任务表和 AI 相关表结构       |
| `database/seeders/`           | 初始账号、角色、菜单权限和站点配置           |

## 认证与用户模型

项目使用 Laravel Sanctum 个人访问令牌。`AppServiceProvider` 将令牌模型指定为 `SysAccessToken`，默认认证用户模型为 `SysUserModel`。前端从本地存储读取令牌并添加 Bearer 认证头。

## 控制器基础能力

`BaseController` 提供列表查询的通用构建逻辑，包括：

- 字段筛选和快速关键字搜索；
- 日期范围查询；
- 前端排序参数转换；
- 配合 `searchField` 与 `quickSearchField` 声明控制器可查询字段。

具体业务控制器负责模型操作、参数校验和响应，通用接口结构由 `RequestJson` 统一生成。

## 下一步

- [注解路由与权限](/backend/routing.md)：声明接口路径、HTTP 方法和权限标识。
- [接口响应约定](/backend/api-conventions.md)：理解 `success`、`data`、`msg` 和 `showType`。