# 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` 是否真的已补上目标字段，测试库缺列会直接导致写入失败。