117 lines
4.5 KiB
Markdown
117 lines
4.5 KiB
Markdown
# Server Agent — Sport Era 后端
|
||
|
||
ThinkPHP / likeadmin 多应用后台系统。**本模块是项目核心，定义 adminapi、api、定时任务、数据库模型与业务逻辑，其他端依赖此模块。**
|
||
|
||
## 技术栈
|
||
|
||
- **PHP** 8.x
|
||
- **框架** ThinkPHP + likeadmin
|
||
- **数据库** MySQL（库名 `sbnews`，表前缀 `la_`）
|
||
- **缓存** Redis（ThinkPHP Cache facade）
|
||
- **Web 服务** Nginx + PHP-FPM
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
app/
|
||
├── adminapi/ # 后台管理 API → admin/ 消费
|
||
├── api/ # 前台公开 API → uniapp/ + pc/ 消费
|
||
├── common/ # 公共模型/服务/缓存/中间件/监听器/枚举
|
||
├── command/ # 控制台命令与定时任务
|
||
├── service/ # 公共服务封装
|
||
├── common.php # 全局函数
|
||
├── middleware.php # 全局中间件
|
||
└── event.php # 事件监听
|
||
config/ # 框架配置
|
||
route/ # 路由定义
|
||
public/ # Web 入口、上传目录、脚本与静态资源
|
||
```
|
||
|
||
## 模块职责
|
||
|
||
| 应用 | 路由前缀 | 消费方 | 控制器目录 |
|
||
| -------- | ------------- | --------------- | -------------------------- |
|
||
| adminapi | `/adminapi/*` | admin/ 管理后台 | `app/adminapi/controller/` |
|
||
| api | `/api/*` | uniapp/ + pc/ | `app/api/controller/` |
|
||
|
||
## 目录约定
|
||
|
||
- `controller/` — 控制器（类名后缀 `Controller`）
|
||
- `logic/` — 业务逻辑层
|
||
- `service/` — 服务层
|
||
- `validate/` — 验证器层
|
||
- `lists/` — 列表查询封装
|
||
- `model/` — ORM 模型
|
||
- `cache/` — Redis 缓存
|
||
- `http/middleware/` — 中间件
|
||
|
||
## 运行命令
|
||
|
||
```bash
|
||
composer install
|
||
php think run
|
||
php think crontab
|
||
```
|
||
|
||
---
|
||
|
||
## 并行协作协议
|
||
|
||
### 新功能开发流程
|
||
|
||
```text
|
||
Step 1: 后端定义契约
|
||
|
||
1.1 确认是否已有数据表、模型、字典或配置可复用
|
||
1.2 创建或调整 Model / Logic / Validate / Lists / Controller
|
||
1.3 输出接口清单：
|
||
|
||
## 新功能: XXX
|
||
### adminapi 接口
|
||
| 方法 | 路径 | 说明 |
|
||
| GET | /adminapi/xxx/lists | 列表 |
|
||
| POST | /adminapi/xxx/add | 新增 |
|
||
| POST | /adminapi/xxx/edit | 编辑 |
|
||
| POST | /adminapi/xxx/del | 删除 |
|
||
|
||
### api 接口
|
||
| 方法 | 路径 | 说明 |
|
||
| GET | /api/xxx/lists | 前台列表 |
|
||
| GET | /api/xxx/detail | 前台详情 |
|
||
|
||
Step 2: 前端并行消费契约
|
||
|
||
┌─ server/ 实现 controller + logic + validate + lists
|
||
├─ admin/ 查看 adminapi controller → 写管理页面
|
||
├─ uniapp/ 查看 api controller → 写手机端页面
|
||
└─ pc/ 查看 api controller → 写 PC 页面
|
||
|
||
Step 3: 集成联调与文档同步
|
||
|
||
- 检查接口响应格式、权限、字段、字典
|
||
- 同步更新 `业务进度管理.md`
|
||
```
|
||
|
||
## 与前端 Agent 的协作方式
|
||
|
||
1. **API 契约即文档**：前端优先查看 controller、validate、logic 获取接口签名、请求参数、响应结构。
|
||
2. **Model 即数据结构**：前端查看 `app/common/model/` 了解字段与访问器。
|
||
3. **枚举共享**：业务枚举优先使用字典表或配置表，不在 PHP / TS 中重复硬编码。
|
||
4. **上传接口统一**：后台使用 adminapi 上传接口，前台使用 api 上传接口，沿用现有封装。
|
||
|
||
## 后端开发硬性规范
|
||
|
||
1. **字典/配置驱动枚举**：状态、类型、分类、开关等优先落入字典表或配置表。
|
||
2. **列表查询沿用 Lists 封装**：后台列表页继承 `BaseAdminDataLists`，实现 `lists()` 和 `count()`。
|
||
3. **控制器沿用基类能力**：后台控制器继承 `BaseAdminController`，列表使用 `$this->dataLists()`。
|
||
4. **菜单与权限**：新增管理后台模块必须同步菜单和按钮权限，SQL 初始化必须幂等。
|
||
5. **接口响应格式**：沿用 likeadmin 统一响应结构，不随意增减顶层字段。
|
||
6. **时间字段处理**：BaseModel 自动转换 `create_time` / `update_time`，不要对已转字符串再次 `date()`。
|
||
7. **SQL 保留字**：原生 SQL 中 `system`、`order`、`group`、`key` 等字段必须用反引号包裹。
|
||
8. **定时任务**：注册在 `la_dev_crontab`，通过 `php think crontab` 统一调度。
|
||
|
||
## 近期踩坑
|
||
|
||
- `Validate::only()` 只限制校验字段范围，不会自动过滤请求参数；新增字段要同时检查 validate、logic、model、保存白名单和数据库列。
|
||
- `adminapi/match.match/edit` 保存失败时，先确认测试库或线上库 `la_match` 是否真的已补上目标字段，测试库缺列会直接导致写入失败。
|