no message

2026-06-11 12:15:29 +08:00
parent 10ebe39c30
commit 96efa1d905
5859 changed files with 815501 additions and 5 deletions
@@ -0,0 +1,116 @@
+# 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` 是否真的已补上目标字段，测试库缺列会直接导致写入失败。