sbnews/AGENTS.md

# Sport Era 项目说明

## 思考语言

思考过程请使用中文。

## 项目信息

- 基于 likeadmin 的体育资讯 AI 分析 App / 流量平台
- 后端：PHP 8.x + ThinkPHP / likeadmin
- 管理后台：Vue 3 + Vite + Element Plus + TypeScript
- 手机端：uni-app + Vue 3
- PC 前台：Nuxt 3 + Vue 3
- 数据库：MySQL（`sbnews`，表前缀 `la_`）
- 缓存：Redis（ThinkPHP Cache facade）

## 子项目开发规范

修改到哪个子项目，则需要遵循对应子项目的 Agent 说明：

| 模块 | Agent 文件 | 职责 |
| --- | --- | --- |
| 后端 | `server/AGENTS.md` | API 接口、数据库建模、业务逻辑、定时任务 |
| 管理后台 | `admin/AGENTS.md` | 消费 adminapi 接口，构建管理页面 |
| 手机端 | `uniapp/AGENTS.md` | 消费 api 接口，构建 H5/App/小程序页面 |
| PC 前台 | `pc/AGENTS.md` | 消费 api 接口，构建 Nuxt PC 页面 |
| 测试 | `qa/AGENTS.md` | 后端 API 验证与前端页面验证 |

---

## 编程准则

1. 做新功能之前必须先检查现有代码是否已有相关功能，避免重复开发。
2. 创建新数据表时，用到的字典、枚举值、状态码等必须配置在现有的数据表或配置表内统一管理，不能硬编码。
3. 相同或相似的功能必须封装为可复用的方法，避免重复代码。
4. 查询字段、路由、菜单、配置前，优先以当前项目代码和 `sbnews.sql` / `docs/sql/` 中结构为准；如需线上核对，再按用户要求使用可用 MCP 或指定连接方式。
5. 不通过 WSL sshpass/scp 上传代码到服务器；项目代码更新由用户自行通过 SFTP 等方式处理。
6. 项目级文档（如协作规范、业务进度、设计稿映射、产品方案、实现流程、爬虫说明等）统一存放在项目根目录；仅子项目专属文档放在对应子目录。

---

## 常用命令速查

| 模块 | 开发命令 | 构建命令 |
| --- | --- | --- |
| server | `php think run` | — |
| admin | `npm run dev` | `npm run build` |
| uniapp | `npm run dev:h5` | `npm run build:h5` |
| pc | `npm run dev` | `npm run generate` / `npm run build` |

## 数据库结构基准

- 数据库表前缀：`la_`。
- 配置存储在 `la_config` 表，通过 `ConfigService::get/set` 读写。
- 菜单存储在 `la_system_menu` 表，type: M=目录、C=页面、A=按钮权限。
- 定时任务注册在 `la_dev_crontab`，通过 `php think crontab` 统一调度。
- MySQL 保留字如 `system`、`order`、`group`、`key` 等写原生 SQL 时必须用反引号包裹。

### 数据库连接方式

测试数据库连接信息位于 `server/.env`（不入库）。连接参数：

| 配置项 | 值 |
| --- | --- |
| Host | `95.40.220.223` |
| Port | `3300` |
| Database | `sbnews` |
| User | `sbnews` |
| Password | 见 `server/.env` 中 `PASSWORD` 字段 |

> ⚠️ 安全提醒：密码禁止硬编码到代码或文档中，统一从 `.env` 读取。命令行查询时避免 `-p"密码"` 方式（会暴露在进程列表），改用交互式输入：
>
> ```bash
> mysql -h 95.40.220.223 -P 3300 -u sbnews -p sbnews -e "SELECT ..."
> # 回车后输入密码
> ```

## 代码修改后验证与评审

除非用户特别说明不需要验证，代码修改完成后按改动类型选择验证方式：

### 后端接口修改

1. PHP 语法检查：`php -l <modified_file.php>`。
2. 涉及接口时确认控制器、逻辑层、验证器、列表类、模型字段一致。
3. 涉及数据库字段时确认表结构、索引、字典或配置存在。
4. 检查前端调用方是否需要同步更新。

### 前端页面修改

1. 检查接口请求模块、页面路由、组件引用是否一致。
2. 新增 uniapp 页面必须检查 `pages.json`。
3. 涉及条件编译时确认 H5/App/小程序差异。
4. 检查控制台、网络请求和页面渲染问题。

### 通用代码评审清单

| 序号 | 检查项 | 说明 |
| --- | --- | --- |
| 1 | 改动范围 | 确认改动文件列表，是否有遗漏或多余文件 |
| 2 | 跨文件依赖 | 修改 model/controller/API 后，检查引用方是否同步 |
| 3 | 硬编码检查 | 业务枚举、分类、状态优先走字典或配置 |
| 4 | 未使用引入 | 检查多余 import/use |
| 5 | 命名一致性 | 字段、方法、路由命名与现有风格一致 |
| 6 | 安全性 | SQL 拼接、用户输入、权限校验是否安全 |
| 7 | 幂等性 | SQL 初始化必须可重复执行 |
| 8 | 文档同步 | 功能完成后更新 `业务进度管理.md` |

## 设计稿映射

设计稿与页面/组件映射统一维护在：

- [设计稿映射.md](./设计稿映射.md)

开发或还原视觉前，先确认设计稿名称、页面路径、实现状态与备注。

## 业务进度管理

当前业务进度、待办事项、避坑记录统一维护在：

- [业务进度管理.md](./业务进度管理.md)

开发或接手任务前，先查看该文档确认已完成事项、进行中事项、待办事项与避坑记录。

## 近期踩坑

- `Validate::only()` 只限制校验字段范围，不会自动过滤请求参数；新增字段落库前，要同时检查 validate、logic、model、保存白名单和数据库列是否同步。
- `adminapi/match.match/edit` 写入失败时，先查测试库或线上库表结构，确认 `la_match` 已补齐对应字段，不要只盯业务代码。
- 世界杯专题页、比赛详情页这类前后端联动改动，要统一入口显示规则和跳转目标，避免只改一处导致入口不一致。
- 构建产生的 `server/public/admin`、`server/public/mobile` 等产物不要混进提交，提交前先清理临时截图和生成文件。
- **uni-app iOS 端 scroll-view+JS 计算高度 间隙问题**：在 iOS（APP-PLUS/MP）端，通过 `uni.createSelectorQuery()` 计算 `windowHeight - topBar - inputBar` 然后设置 `scroll-view` 的 inline `height` 会因安全区域、设备像素比等因素产生几像素偏差，导致 `scroll-view` 底部与固定输入栏之间出现间隙。**正确做法**：页面使用 `height: 100vh; display: flex; flex-direction: column`，topbar 和 input-bar 设 `flex-shrink: 0`，scroll-view 设 `flex: 1; min-height: 0` 自然填满剩余空间，不再用 JS 计算高度。
- **Vue3 `<script setup>` 中 `defineEmits` 和 `defineProps` 返回值必须赋值**：`defineEmits(...)` 的返回值才是可调用的 emit 函数，直接写 `defineEmits([...])` 不赋值会导致 "Can't find variable: emit"；`defineProps` 的返回值才能通过 `props.xxx` 访问属性，模板中自动解包但脚本中必须用 `props.xxx`。