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"密码" 方式（会暴露在进程列表），改用交互式输入：

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

代码变更后部署

• 只要本项目有代码变更，完成必要验证后，必须执行以下命令，将最新代码更新到测试服运行环境：

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

• 默认将这条部署命令视为 Sport Era 项目代码变更后的必做步骤，除非用户在当前任务中明确说明“不需要部署”。

设计稿映射

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

• 设计稿映射.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。