sbnews/server/AGENTS.md

Server Agent — Sport Era 后端

ThinkPHP / likeadmin 多应用后台系统。本模块是项目核心，定义 adminapi、api、定时任务、数据库模型与业务逻辑，其他端依赖此模块。

技术栈

• PHP 8.x
• 框架 ThinkPHP + likeadmin
• 数据库 MySQL（库名 sbnews，表前缀 la_）
• 缓存 Redis（ThinkPHP Cache facade）
• Web 服务 Nginx + PHP-FPM

项目结构

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/ — 中间件

运行命令

composer install
php think run
php think crontab

---

并行协作协议

新功能开发流程

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: 集成联调与文档同步

  - 检查接口响应格式、权限、字段、字典
  - 同步更新 `docs/业务进度管理.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 是否真的已补上目标字段，测试库缺列会直接导致写入失败。