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. 新增项目级文档（如协作规范、业务进度、设计稿映射、产品方案、实现流程、爬虫说明等）统一存放在 docs/；根目录仅保留 README.md、AGENTS.md、文档索引.md 等入口文件。仅子项目专属的 README / AGENTS 等说明可放在对应子目录。

---

常用命令速查

模块	开发命令	构建命令
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"密码" 方式（会暴露在进程列表），改用交互式输入：

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	文档同步	功能完成后更新 docs/业务进度管理.md

代码变更后部署

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

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

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

近期交接总结

• 当前真实开发目录以 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。