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

## 设计稿对照

设计稿与本项目页面/组件的映射关系集中维护于根目录 [`设计稿映射.md`](../设计稿映射.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` 有值时展示，不要兜底拼默认第三方地址。
- 世界杯专题页的赛程卡和对阵图卡都要统一跳转到比赛详情页，避免只补一处入口导致列表仍然点不进去。