no message

2026-06-11 12:15:29 +08:00
parent 10ebe39c30
commit 96efa1d905
5859 changed files with 815501 additions and 5 deletions
@@ -0,0 +1,109 @@
+# 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` 有值时展示，不要兜底拼默认第三方地址。
+- 世界杯专题页的赛程卡和对阵图卡都要统一跳转到比赛详情页，避免只补一处入口导致列表仍然点不进去。