110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# Uniapp Agent — Sport Era 手机端
|
||
|
||
uni-app 跨端移动应用。**消费 `server/app/api/controller/` 的接口。**
|
||
可编译为 H5 / App / 小程序端。
|
||
|
||
## 技术栈
|
||
|
||
- **uni-app** + **Vue** 3
|
||
- **Vite**
|
||
- **Pinia** 状态管理
|
||
- **TypeScript**
|
||
- **z-paging** 分页组件
|
||
- **uniapp-router-next** 路由管理
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/
|
||
├── main.ts # 应用入口
|
||
├── App.vue # 根组件
|
||
├── pages.json # uni-app 页面路由 / tabBar
|
||
├── manifest.json # 应用配置
|
||
├── api/ # 接口请求模块（→ 后端 /api/*）
|
||
├── pages/ # 页面组件（主包）
|
||
├── components/ # 公共组件
|
||
├── stores/ # Pinia Store
|
||
├── hooks/ # 组合式函数
|
||
├── router/ # 路由中间件
|
||
├── utils/ # 工具函数与请求拦截
|
||
├── enums/ # 枚举常量
|
||
├── config/ # 应用配置
|
||
├── styles/ # 全局样式
|
||
├── static/ # 静态资源
|
||
└── uni_modules/ # uni-app 插件
|
||
```
|
||
|
||
## 运行命令
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev:h5
|
||
npm run build:h5
|
||
```
|
||
|
||
---
|
||
|
||
## 并行协作协议
|
||
|
||
### 新功能开发时
|
||
|
||
#### Step 1: 等待或查阅后端 API 契约
|
||
|
||
查看 `server/app/api/controller/` 下对应 controller，并结合 validate、logic、model 获取：
|
||
|
||
- 接口路径和方法
|
||
- 请求参数类型
|
||
- 响应数据结构
|
||
- 登录态与权限要求
|
||
|
||
#### Step 2: 并行实现
|
||
|
||
```text
|
||
1. src/api/ 下新增或复用接口请求模块
|
||
2. src/pages/ 或分包目录下新增页面目录和页面文件
|
||
3. src/pages.json 添加页面路由和必要的 tabBar 配置
|
||
4. 页面样式复用全局样式和现有组件
|
||
```
|
||
|
||
#### Step 3: 构建联调
|
||
|
||
```bash
|
||
npm run build:h5
|
||
```
|
||
|
||
## 从后端 Agent 获取信息的方式
|
||
|
||
| 需要了解 | 查看位置 |
|
||
| ------------------ | ---------------------------------------------------- |
|
||
| 接口路径/参数/响应 | `server/app/api/controller/` 对应 controller |
|
||
| 参数校验 | `server/app/api/validate/` 对应 validate |
|
||
| 数据表字段 | `server/app/common/model/` 对应 model |
|
||
| 枚举/常量 | `server/app/common/enum/` + `src/enums/` + 字典/配置 |
|
||
| Token 机制 | `server/app/common/cache/UserTokenCache.php` |
|
||
|
||
## 设计稿对照
|
||
|
||
设计稿与本项目页面/组件的映射关系集中维护于 [`docs/设计稿映射.md`](../docs/设计稿映射.md)。接到新需求或还原设计稿前先查该文档，确认：
|
||
|
||
- 设计稿名称 ↔ uniapp 页面路径
|
||
- 当前实现状态（已完成 / 待开发 / 部分完成）
|
||
- 备注中的交互、资源或接口说明
|
||
|
||
新增或调整页面后需同步更新该文档的状态字段。
|
||
|
||
## 代码约定
|
||
|
||
- API 请求通过 `src/api/` 模块，沿用 `src/utils/request` 相关封装。
|
||
- 分页列表优先使用 z-paging 组件。
|
||
- 页面路由必须在 `pages.json` 中注册。
|
||
- 跨端兼容用条件编译 `#ifdef H5`、`#ifdef MP-WEIXIN` 等。
|
||
- 状态管理用 Pinia，Store 放在 `src/stores/`。
|
||
- 图片资源放在 `src/static/`。
|
||
- H5 富文本可用 `v-html`，非 H5 端按 uni-app 能力使用 `rich-text` 等方案。
|
||
- 外链图片如遇防盗链，优先通过渲染属性处理引用策略，不擅自清洗原始 URL。
|
||
|
||
## 近期踩坑
|
||
|
||
- 比赛详情页的直播入口只在 `match.live_url` 有值时展示，不要兜底拼默认第三方地址。
|
||
- 世界杯专题页的赛程卡和对阵图卡都要统一跳转到比赛详情页，避免只补一处入口导致列表仍然点不进去。
|