144 lines
7.0 KiB
Markdown
144 lines
7.0 KiB
Markdown
# 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\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)
|
||
|
||
开发或还原视觉前，先确认设计稿名称、页面路径、实现状态与备注。
|
||
|
||
## 业务进度管理
|
||
|
||
当前业务进度、待办事项、避坑记录统一维护在：
|
||
|
||
- [业务进度管理.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`。
|