# 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` |

## 代码变更后部署

- 仅在用户明确要求部署、上线、发布或同步到测试服时，执行以下命令，将最新代码更新到测试服运行环境：

```powershell
cd D:\www\gs-sport-era
powershell -ExecutionPolicy Bypass -File .\scripts\deploy-server.ps1 -Sudo -AutoIncremental -AutoIncrementalCommits 3 -RemoteDir /www/wwwroot/test-server.sbnews.net
```

- 不要把部署视为代码变更后的默认必做步骤；未明确要求部署时，只提示可执行的部署命令。

## 设计稿映射

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

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

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

## 业务进度管理

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

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

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

## 近期交接总结

- 当前真实开发目录以 `D:\www\gs-sport-era` 为准；Codex worktree（如 `C:\Users\Administrator\.codex\worktrees\...\gs-sport-era`）中的改动不会自动进入真实仓库、`git log` 或服务器运行目录。涉及可部署代码时，先确认改动已经同步到真实目录并形成清晰提交。
- 正确的服务器运行目录是 `/www/wwwroot/test-server.sbnews.net`；`/www/wwwroot/api.sbnews.net` 不是当前项目的有效同步目录，不要再部署到该路径。排查“代码已更新但服务器没生效”时，本地真实仓库看 `git log`，服务器侧看文件内容、修改时间、容器内 `/app` 文件与定时任务日志。
- Docker crawler 任务真实执行入口是 `sport-era-crawler` 容器。更新 `docker/crawler` 源码或 `config/crawler_tasks.yaml` 后，必须在服务器 `docker` 目录执行 `sudo docker compose -f docker-compose.crawler.yml build crawler` 和 `sudo docker compose -f docker-compose.crawler.yml up -d --no-deps crawler`；仅重启旧容器不能保证镜像内代码更新，必要时使用 `--no-cache` 重建。
- 重启 crawler 后必须核验容器内代码和 cron，而不是只看宿主机源码：例如检查 `/app/match_live_stream.py`、`/app/config/crawler_tasks.yaml`，以及 `cat /etc/cron.d/* | grep match_live_stream`。
- 雨燕直播间任务 `match_live_stream` 当前应直接同步 `all_live_rooms.json`，写入主播 `anchor_id`、`anchor_name`、`anchor_avatar`、`anchor_level` 以及直播间观看/关注/公告/简介字段；对应 SQL 为 `docs/sql/alter_match_live_anchor_fields.sql` 和 `docs/sql/insert_crontab_match_live_stream.sql`。上线后用 `la_match_live` 主播字段统计和 `la_crawler_task_log` 最近任务状态共同确认是否生效。

## 近期踩坑

- `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`。