hy/aslan-h5
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 活动页面建立流程模块化尝试

Browse Source
This commit is contained in:
hzj 2026-05-14 16:07:43 +08:00
parent b75bbeaeb7
commit ac77b82c51
8 changed files with 2452 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

302
docs/活动页/幸运美金第6季创建记录.md Normal file
View File

@ -0,0 +1,302 @@
# LuckyDollars Season6 创建记录
本文记录按《快速建立活动页方案》创建 `LuckyDollars Season6` 新活动页的实际步骤。Season6 被当作一个新页面处理：有独立页面目录、独立图片目录、独立页面配置、独立路由和权限配置。为了先验证页面效果，接口参数暂时沿用 Season5。
## 1. 确认页面类型和模块
Season6 属于复杂活动页，包含以下模块：
```text
reward
ranking
lottery
task
withdraw
history
rule
```
页面功能目标：先做出与 Season5 行为一致的活动页，后续再替换 Season6 的真实图片和活动接口参数。
## 2. 创建页面目录
创建新页面目录：
```text
src/views/Activities/LuckyDollars/Season6/
src/views/Activities/LuckyDollars/Season6/components/
```
创建后包含：
```text
src/views/Activities/LuckyDollars/Season6/index.vue
src/views/Activities/LuckyDollars/Season6/page.config.js
src/views/Activities/LuckyDollars/Season6/components/Barrage.vue
src/views/Activities/LuckyDollars/Season6/components/topUser.vue
```
说明：当前 UI 结构参考 Season5 的实现，但 Season6 已抽出自己的页面配置，不直接依赖 Season5 的图片路径和路由。
## 3. 创建页面配置
新增：
```text
src/views/Activities/LuckyDollars/Season6/page.config.js
```
配置内容包括：
```js
export const pageConfig = {
name: 'LuckyDollars Season6',
routePath: '/activities/lucky-dollars-season6',
assetPath: 'Activities/LuckyDollars/Season6/',
activity: {
activityId: '2007771533999124198',
activityCode: '24198',
rewardActivityType: 'CONSUMPTION_ACTIVITY',
rankingActivityType: 'USER_RECHARGE_DRAW',
},
modules: ['reward', 'ranking', 'lottery', 'task', 'withdraw', 'history', 'rule'],
}
```
当前 `activityId` 和 `activityCode` 沿用 Season5，仅用于验证 Season6 页面是否完整可用。后续接真实 Season6 活动时，只改这里。
## 4. 配置图片路径
页面中不写死路径，统一从 `pageConfig.assetPath` 获取：
```js
const imageUrl = (filename) => getPngUrl(pageConfig.assetPath, filename)
const webpUrl = (filename) => getWebpUrl(pageConfig.assetPath, filename)
```
Season6 的图片路径为：
```text
Activities/LuckyDollars/Season6/
```
开发环境会解析为：
```text
/oss/h5/Azizi/Activities/LuckyDollars/Season6/xxx.png
```
## 5. 创建本地 OSS 图片目录
创建：
```text
public/oss/h5/Azizi/Activities/LuckyDollars/Season6/
```
这个目录用于开发阶段模拟真实 OSS。你已把 Season6 图片补充到该目录。
注意：`vite.config.js` 中 `/oss` 开发代理已调整为“本地 public 文件优先，本地不存在再代理 CDN”。这样本地 Season6 图片可以直接被 dev server 读取。
## 6. 按图片清单配置多语言
Season6 使用图片清单中的支持语言生成多语言图片回退。
在 `page.config.js` 中声明哪些图片支持语言后缀：
```js
images: {
localized: {
helpInfo: ['ar'],
historyBg: ['ar'],
historyBt: ['ar'],
lotteryBt: ['ar'],
lotteryBtActive: ['ar'],
rankBt: ['ar'],
rankBtActive: ['ar'],
rewardReceive: ['ar'],
rewardReceived: ['ar'],
rewardReceiveNot: ['ar'],
rulesBt: ['ar'],
ruleInfo: ['ar'],
},
}
```
页面中使用：
```js
const getImgName = (filename) => {
return getLocalizedImageName(filename, currentLangType.value)
}
```
如果当前语言没有对应图片，自动回退原图，避免请求不存在的图片。
## 7. 配置排行榜模式
Season6 的排行榜沿用 Season5 接口，属于服务端分页模式：
```js
ranking: {
loadMode: 'remote',
pageSize: 20,
topCount: 3,
}
```
数据流：
```text
首次请求 pageNo = 1
上拉触底后请求 pageNo + 1
把新数据追加到 rankingAdd
rankingTotal = ranking + rankingAdd
```
## 8. 配置抽奖模式
Season6 当前奖品已经画在抽奖背景图上，因此抽奖格子属于 `track-only` 模式：
```js
lottery: {
prizeRenderMode: 'track-only',
slotCount: 9,
}
```
含义：
```text
接口奖品用于计算中奖位置
页面只渲染高亮框转圈
不在格子内额外渲染奖品图和文字
```
## 9. 增加路由
在 `src/router/index.js` 中增加：
```js
{
path: '/activities/lucky-dollars-season6',
name: 'lucky-dollars-season6',
component: () => import('../views/Activities/LuckyDollars/Season6/index.vue'),
meta: { requiresAuth: true },
}
```
访问地址：
```text
/activities/lucky-dollars-season6
```
## 10. 补充安全白名单
在 `src/config/security.js` 的 `PUBLIC_PATHS` 中加入：
```js
'/activities/lucky-dollars-season6'
```
否则页面可能被安全路径检查拦截。
## 11. 补充权限配置
在 `src/utils/permissionManager.js` 的 `ACTIVITIES` 中加入：
```js
'/activities/lucky-dollars-season6'
```
否则页面可能被权限管理拦截。
## 12. 修改页面内跳转来源
页面内跳转到提现页时，`from` 参数改为 Season6 自己的路由：
```js
query: { from: '/activities/lucky-dollars-season6', activeAction: 'incomeShow' }
```
## 13. 当前仍沿用的参考实现
为了快速验证视觉和功能，当前 Season6 的主体模板结构、样式细节、弹幕组件、顶部用户组件等仍参考 Season5 的实现。
本次已先接入以下通用能力，避免新页面只能整页复制：
```text
useLotteryDraw
ActivityLotteryGrid
useActivityAssets
```
已落地内容：
- `useActivityAssets`：Season6 的图片 URL、多语言图片名从 `pageConfig` 读取。
- `ActivityLotteryGrid`：Season6 的抽奖格子、高亮框、中心按钮区域从页面模板中抽离。
- `useLotteryDraw`：Season6 的抽奖转圈动画从页面脚本中抽离。
- `pageConfig.lottery`：抽奖背景内容布局、格子布局、历史按钮位置、奖品展示模式改为配置。
暂未强行改造：
```text
useActivityTabs
useActivityRanking
```
原因：Season6 当前标签页和排行榜与大量现有展示状态耦合，继续硬改收益不高。后续真正新建页面时，初始骨架应直接使用这两个 composable，避免一开始就写多个 `reward/rankShow/lotteryShow/incomeShow` 布尔值。
## 14. 后续给 Codex 建类似页面时的输入
以后建立同类页面时，不需要说“复制某页面”。建议先按 [建页操作模板.md](./建页操作模板.md) 让 Codex 创建专属页面信息 md，再把必要信息填进去，例如：
```text
页面类型：Activities
新页面目录：src/views/Activities/LuckyDollars/Season7
参考页面：src/views/Activities/LuckyDollars/Season6
路由 path：/activities/lucky-dollars-season7
OSS 图片路径：Activities/LuckyDollars/Season7/
模块：reward / ranking / lottery / task / withdraw / history / rule
排行榜分页方式：remote
抽奖奖品展示：track-only
多语言图片：按页面创建信息 md 的 3.1 图片清单处理
接口参数：先沿用 Season6 或填写真实 activityId/activityCode
```
Codex 应产出可运行初始版本，你再调整具体样式和图片对位。
## 15. 本地图片 404 处理记录
开发时曾出现：
```text
GET http://localhost:5173/oss/h5/Azizi/Activities/LuckyDollars/Season6/lotteryBtActive.png 404
```
原因：开发环境的 `/oss` 代理会转发到 CDN。如果本地 dev server 没有优先读取 `public/oss/...`，Season6 这种还没上传到服务端 OSS 的图片就会请求失败。
处理方式：调整 `vite.config.js` 的 `/oss` 代理，先判断请求文件是否存在于项目 `public` 目录，存在则直接返回本地 public 路径；不存在再代理到 CDN。
修改配置后需要重启 `npm run dev`，旧 dev server 不会自动吃到 `vite.config.js` 的变更。
## 16. 验证记录
已运行：
```bash
npm run build
```
结果：构建成功。
构建期间仍有既有警告：
```text
../assets/images/Azizi/secondBg.png referenced in ../assets/images/Azizi/secondBg.png didn't resolve at build time
```
该警告不是 Season6 新增代码引起的，构建仍正常完成。

223
docs/活动页/建页执行流程.md Normal file
View File

@ -0,0 +1,223 @@
# 建页执行流程
这份文档给 Codex 执行用。用户不需要阅读这里，用户只需要按 [建页操作模板.md](./建页操作模板.md) 操作。
## 1. 用户只给页面名称和创建位置时
当用户只提供类似信息：
```text
页面名称：LuckyDollars Season7
创建位置：src/views/Activities/LuckyDollars/Season7
```
只执行以下步骤：
```text
1. 根据路径判断页面类型：
- src/views/Activities 下为 Activities
- src/views/Ranking 下为 Ranking
2. 在 docs/活动页/ 下创建专属页面信息 md。
3. md 文件名使用中文或页面名，例如 LuckyDollars-Season7-创建信息.md。
4. 预填页面类型、页面名称、页面目录、route path、route name、OSS 相对路径、本地开发目录。
5. route path 和 route name 根据页面类型、页面名称、页面目录自动生成；用户后续可以自行修改。
6. 安全白名单片段和权限页面片段也使用 route path 自动生成，不留空。
7. OSS 相对路径和本地开发目录根据页面类型和页面目录自动生成；用户后续可以自行修改。
8. 如果本地开发目录已存在且里面有图片，扫描图片文件并预填 3.1 多语言图片清单。
9. 根据页面类型、3.1 图片清单和模块预设，自动预填 3.2、3.3、4.x 模块配置。
10. 只把无法推断或风险较高的字段留空，并在备注中说明需要用户确认。
11. 本轮不创建页面代码，除非用户明确要求继续创建页面。
```
路由自动生成规则：
```text
Activities 页面：
src/views/Activities/LuckyDollars/Season6
-> route path: /activities/lucky-dollars-season6
-> route name: lucky-dollars-season6
Ranking 页面：
src/views/Ranking/OverallSeason2
-> route path: /ranking/overall-season2
-> route name: overall-season2
```
安全白名单和权限页面片段生成规则：
```text
src/config/security.js：使用 route path。
src/utils/permissionManager.js：使用 route path，后面注释使用页面名称。
```
OSS 路径生成规则：
```text
Activities 页面：
src/views/Activities/LuckyDollars/Season6
-> OSS 相对路径: Activities/LuckyDollars/Season6/
-> 本地开发目录: public/oss/h5/Azizi/Activities/LuckyDollars/Season6/
Ranking 页面：
src/views/Ranking/OverallSeason2
-> OSS 相对路径: Ranking/OverallSeason2/
-> 本地开发目录: public/oss/h5/Azizi/Ranking/OverallSeason2/
```
多语言图片自动扫描规则：
```text
scanDir = 专属 md 中的本地开发目录
只扫描常见图片扩展名：png、jpg、jpeg、webp、gif、svg。
忽略 .gitkeep 等非图片文件。
文件名不带语言后缀时，记为 en 原图，例如 bg0.png -> bg0: en。
文件名带 _ar、_bn、_tr 等语言后缀时，按基础名合并，例如 rankBt.png + rankBt_ar.png -> rankBt: en, ar。
如果只有 rankBt_ar.png 且没有 rankBt.png，也生成 rankBt: ar，并在备注里标记缺少原图。
默认支持 ar、bn、tr；遇到其它形如 _xx 的语言后缀时也保留，但生成页面时需要确认是否接入。
生成 3.1 图片清单时，按图片名首字母排序，排序忽略大小写。
专属 md 的 3.1 展示扫描结果；备注优先匹配 docs/活动页/建页资料库.md 中的常用图片中文用途。
能匹配到常用名时不要写“扫描生成”，例如 bg0 写“页面背景第 0 段”，rankBt 写“排行榜按钮”。
匹配不到常用名时，根据图片名语义推断中文用途；用户的图片名通常按功能命名，例如 taskTalk 可写“聊天任务图标”，RewardRecharge500 可写“充值 500 奖励图”。
rankingTopBg 统一解释为“排行榜前几名展示区背景”；历史 topBg 也按该含义解释，不要写成“顶部区域背景”。
只有图片名完全看不出功能时，才备注“待确认用途”，方便用户回头改。
不再要求用户填写“多语言图片规则”；生成页面时直接读取 3.1 中每张图片的支持语言。
3.2 和 3.3 默认按图片用途自动生成：首屏背景、默认标签页、顶部信息、默认模块放 blocking；弹窗、非默认标签页、抽奖结果、下方模块放 background。
```
## 2. 用户补完专属 md 并要求继续建页时
执行顺序：
```text
1. 读取专属页面信息 md。
2. 读取 docs/活动页/建页操作模板.md。
3. 读取 docs/活动页/建页资料库.md。
4. 如果有参考页面，读取参考页面结构和接口用法。
5. 只处理专属 md 中已填写的信息，未填写项跳过。
6. 创建页面目录。
7. 创建 page.config.js。
8. 创建或生成 index.vue 初版。
9. 如果专属 md 中“是否需要 Codex 自动创建本地开发目录”为“是”，创建 public/oss/h5/Azizi/... 本地图片目录。
10. 添加路由。
11. 补充 src/config/security.js。
12. 补充 src/utils/permissionManager.js。
13. 按需接入组件和 composable。
14. 运行 npm run build。
15. 把完成项、跳过项、待补项、验证结果写回专属 md。
```
## 3. 执行原则
```text
专属 md 没填的项，不猜。
专属 md 中需要用户填写的模块配置、接口参数、组件需求，优先使用 JSON 代码块，不使用 Markdown 表格。
扫描生成的图片清单和预加载清单可以保留 Markdown 表格，因为它们主要用于检查和排序。
模块图片优先从 3.1 图片清单中按图片名语义推断；推断不到时再参考建页资料库给默认名，并标记待确认。
模块预设里的图片名只有在 3.1 图片清单存在时才直接写入；不存在时留空，并在 remark 中写“本地图片清单未扫描到 xxx，待确认”。
常见模块接口优先走模块预设，不要求用户重复填写。
如果同一个模块在不同页面存在接口或字段差异，且没有提供参考页面，要先问用户参考哪个页面的模块。
参考页面只作为结构和接口参考，不把新页面当成复制旧页面。
新增 js/vue 文件尽量加中文注释。
docs 下文件和文件夹使用中文命名。
页面初版以能运行、结构清楚、方便微调为目标。
```
## 4. page.config.js 建议结构
新页面优先使用分组后的模块配置，不再使用单纯数组：
```js
export const pageConfig = {
name: '',
routePath: '',
assetPath: '',
activity: {
activityId: '',
activityCode: '',
activityType: '',
rankingActivityType: '',
rewardActivityType: '',
},
modules: {
tabs: [],
sections: [],
popups: [],
features: [],
},
images: {
localized: {},
},
}
```
含义：
```text
tabs：标签页模块，如 reward、ranking、lottery、withdraw
sections：页面区块，如 task、badgeReward、myInfo
popups：弹窗，如 rule、help、history、result
features：功能能力，如 countdown、barrage、transfer、exchange
```
## 5. 路由和权限
每个新页面都要确认：
```text
src/router/index.js
src/config/security.js
src/utils/permissionManager.js
```
如果专属 md 中明确写“不需要”，才跳过。
## 6. 图片和缓存
开发期图片目录：
```text
public/oss/h5/Azizi/Activities/PageName/
public/oss/h5/Azizi/Ranking/PageName/
```
页面代码中仍使用 OSS 相对路径：
```js
assetPath: 'Activities/PageName/'
assetPath: 'Ranking/PageName/'
```
替换同名 OSS 图片时，需要提醒用户更新：
```text
src/config/imageCacheVersion.js
```
分阶段预加载实现规则：
```text
1. page.config.js 中保留两个列表：
- preload.blocking：进入页面前同步预加载，参与加载动画。
- preload.background：进入页面后后台预加载，不参与加载动画。
2. blocking 列表为空时，不强制等待图片，页面可直接进入。
3. background 列表为空时，不生成额外逻辑或生成 no-op 逻辑。
4. 两个列表都要走同一套 imageUrl/getImgName 规则，保证本地 OSS、线上 OSS、图片缓存和多语言后缀一致。
5. 后台预加载在 blocking 完成、页面可见后执行，优先使用 requestIdleCallback，兼容时用 setTimeout。
6. 后台预加载失败只记录日志，不影响页面展示和交互。
```
## 7. 完成后写回专属 md
建页完成后，在专属 md 的“建页后记录”中补充：
```text
已完成：
未填写所以跳过：
待用户微调：
构建结果：
本地图片目录：
路由 path：
```

447
docs/活动页/建页操作模板.md Normal file
View File

@ -0,0 +1,447 @@
# 建页操作模板
这份文档只回答一个问题：你要怎么操作，才能让我快速生成 `src/views/Activities` 或 `src/views/Ranking` 的初版页面。
真正建页时不需要一次说完整需求。推荐先让我创建一份“页面创建信息 md”，你在里面按坑位填写；你没填的项，我生成初版时先不处理。
相关资料：
- [建页资料库.md](./建页资料库.md)：组件用法、常用图片名、配置选项。
- [建页执行流程.md](./建页执行流程.md)：我真正执行建页时遵守的流程。
- [快速建立活动页方案.md](./快速建立活动页方案.md)：文档入口和总览。
## 1. 推荐操作流程
第一次只告诉我页面名称和创建位置：
```text
新建活动页：LuckyDollars Season7
创建位置：src/views/Activities/LuckyDollars/Season7
```
或者：
```text
新建排行榜页：Overall Season2
创建位置：src/views/Ranking/OverallSeason2
```
我收到后只做一件事：在 `docs/活动页/` 下创建专属页面信息 md，例如：
```text
docs/活动页/LuckyDollars-Season7-创建信息.md
```
这份 md 会先填好：
```text
页面类型
页面名称
页面目录
route path
route name
OSS 相对路径
本地开发目录
```
其中 `route path` 和 `route name` 会根据页面类型、页面名称、页面目录自动生成。你有特殊需求时，直接在 md 里改掉即可。
`OSS 相对路径` 和 `本地开发目录` 也会根据页面类型和页面目录自动生成。你只需要选择是否让我自动创建本地开发目录。
其它信息会尽量由图片扫描和模块预设先填好；只有无法推断的地方才留给你补。
你填完后，再告诉我：
```text
按 docs/活动页/LuckyDollars-Season7-创建信息.md 继续生成初版页面
```
我再根据你填写的信息创建页面、配置、路由、权限、本地 OSS 目录，并把执行结果写回这份专属 md。
## 2. 填写规则
- 模块配置：优先由 Codex 根据页面类型、扫描图片和参考页面自动预设；你只改不符合预期的地方。
- 图片名和模块图片：优先从 `3.1 多语言图片清单` 和模块预设中自动推断，通常不用额外填写。
- 模块接口：常见模块会自动预设，例如抽奖、奖池、任务、排行榜、中奖历史这类接口不用每次手写。
- 没填且无法推断的模块：我先不实现，或标记为“待确认”。
- 参考页面只作为结构和接口参考，不代表新页面就是复制旧页面。
- 初版页面只保证结构、路径、接口位置、基础交互可用，图片对位和局部样式后续你再微调。
- 需要你填写的模块配置、接口参数、组件需求，尽量使用 JSON 代码块，避免用 Markdown 表格对齐。
## 3. 专属页面信息 md 模板
我创建专属页面信息 md 时使用下面模板。基础信息会先填好，模块、预加载和图片用途会尽量根据扫描结果自动预设。
````md
# 页面创建信息
## 1. 基础信息
- 页面类型：Activities / Ranking
- 页面名称：
- 页面目录：
- 参考页面：
- 备注：
## 2. 路由和权限
- route path：
- route name：
- 是否需要登录：是 / 否
- 是否加入 `src/config/security.js`：是 / 否
- 是否加入 `src/utils/permissionManager.js`：是 / 否
说明：`route path` 和 `route name` 由 Codex 先自动生成，你可以按需要修改。
生成规则：
| 页面类型 | 示例目录 | route path | route name |
| --- | --- | --- | --- |
| Activities | `src/views/Activities/LuckyDollars/Season6` | `/activities/lucky-dollars-season6` | `lucky-dollars-season6` |
| Ranking | `src/views/Ranking/OverallSeason2` | `/ranking/overall-season2` | `overall-season2` |
### 2.1 路由、白名单、权限片段说明
专属页面信息 md 中可以展示这三个片段，但不需要你重复填写：
```text
路由代码片段：使用 route path、route name 和页面目录生成。
安全白名单片段：值等于 route path，补充到 src/config/security.js。
权限页面片段：值等于 route path，后面注释使用页面名称，补充到 src/utils/permissionManager.js。
```
示例：
```js
'/activities/lucky-dollars-season6'
'/activities/lucky-dollars-season6' // LuckyDollars Season6
```
## 3. OSS 图片目录
- OSS 相对路径：
- 本地开发目录：
- 是否需要 Codex 自动创建本地开发目录：是 / 否
- 图片是否已放入本地目录：是 / 否
说明：OSS 相对路径和本地开发目录由 Codex 自动预填。
生成规则：
| 页面类型 | 示例页面目录 | OSS 相对路径 | 本地开发目录 |
| --- | --- | --- | --- |
| Activities | `src/views/Activities/LuckyDollars/Season6` | `Activities/LuckyDollars/Season6/` | `public/oss/h5/Azizi/Activities/LuckyDollars/Season6/` |
| Ranking | `src/views/Ranking/OverallSeason2` | `Ranking/OverallSeason2/` | `public/oss/h5/Azizi/Ranking/OverallSeason2/` |
如果“是否需要 Codex 自动创建本地开发目录”填“是”，Codex 建页时会创建该目录，方便你直接把图片放进去。
### 3.1 多语言图片清单
这部分可由 Codex 扫描本地开发目录自动生成。规则：
- 无后缀图片视为 `en` 原图，例如 `rankBt.png`。
- `_ar`、`_bn`、`_tr` 这类后缀视为对应语言，例如 `rankBt_ar.png`。
- 扫描时会按基础图片名合并语言，例如 `rankBt.png` + `rankBt_ar.png` 生成 `rankBt | en, ar`。
- 图片清单按图片名首字母排序，排序时忽略大小写，方便你快速找图。
- 备注优先按 [建页资料库.md](./建页资料库.md) 的常用图片名整理成中文用途，例如 `bg0` 写“页面背景第 0 段”，`rankBt` 写“排行榜按钮”。
- 如果资料库里没有对应图片名，Codex 可以按图片名语义自己起中文用途，例如 `taskTalk` 推断为“聊天任务图标”，`RewardRecharge500` 推断为“充值 500 奖励图”。
- 新页面推荐用 `rankingTopBg` 表示“排行榜前几名展示区背景”；历史图片名 `topBg` 也按这个含义识别，不再按“页面顶部背景”处理。
- 其它语言后缀可按页面实际情况扩展；没识别到对应语言图片时，页面代码回退使用原图。
- 页面生成时不再单独填写“多语言图片规则”，直接以这张清单为准。
| 图片名 | 支持语言 | 备注 |
| --- | --- | --- |
| | | Codex 扫描并匹配或推断中文用途，必要时你再改 |
### 3.2 进入页面前同步预加载图片
这里填写需要和进入页面预加载动画同步的关键图片。Codex 生成页面时会先等待这些图片加载完成，再结束加载动画。
| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
| | | |
### 3.3 进入页面后后台预加载图片
这里填写不参与进入页面动画、但希望进入页面后继续自动预加载的图片。适合下方长背景、弹窗图、非默认标签页图片、抽奖结果图等。
| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
| | | |
## 4. 模块配置
这一部分会优先由 Codex 根据页面类型、扫描到的图片名和参考页面自动预设。你只需要改不符合预期的部分；删除或设为 `false` 的模块，初版页面会跳过。
### 4.1 标签页模块
填写方式：
```json
{
"enabled": "",
"defaultValue": "",
"items": [
{
"value": "reward",
"labelKey": "recharge_reward",
"buttonImage": "rewardBt",
"activeButtonImage": "rewardBtActive",
"remark": "奖励"
},
{
"value": "ranking",
"labelKey": "ranking",
"buttonImage": "rankBt",
"activeButtonImage": "rankBtActive",
"remark": "排行榜"
}
]
}
```
### 4.2 页面区块模块
常见区块：
```json
[
{
"name": "reward",
"enabled": "",
"apis": [],
"images": [],
"remark": "奖励区块"
},
{
"name": "ranking",
"enabled": "",
"apis": [],
"images": [],
"remark": "排行榜区块"
},
{
"name": "lottery",
"enabled": "",
"apis": [],
"images": [],
"remark": "抽奖区块"
},
{
"name": "task",
"enabled": "",
"apis": [],
"images": [],
"remark": "任务区块"
},
{
"name": "withdraw",
"enabled": "",
"apis": [],
"images": [],
"remark": "提现/兑换区块"
},
{
"name": "countdown",
"enabled": "",
"apis": [],
"images": [],
"remark": "倒计时区块"
}
]
```
### 4.3 弹窗模块
常见弹窗：
```json
[
{
"name": "rule",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": [],
"remark": "规则弹窗"
},
{
"name": "help",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": [],
"remark": "帮助弹窗"
},
{
"name": "history",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": [],
"remark": "历史记录弹窗"
},
{
"name": "result",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": [],
"remark": "中奖结果弹窗"
},
{
"name": "rewardDetail",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": [],
"remark": "奖励详情弹窗"
}
]
```
### 4.4 排行榜模块
```json
{
"enabled": "",
"api": "",
"loadMode": "remote / local",
"pageSize": "",
"topCount": "",
"myRankingPath": "",
"fieldMap": {
"avatar": "",
"name": "",
"value": "",
"userId": "",
"rank": ""
}
}
```
### 4.5 抽奖模块
```json
{
"enabled": "",
"drawApis": [],
"prizePoolApi": "",
"drawCountApi": "",
"extraApis": [],
"displayMode": "track-only / prize-card / custom",
"slotCount": "",
"centerButtonPosition": "",
"historyButtonPosition": "inside / below / absolute / external / hidden",
"images": {
"background": "",
"activeFrame": "",
"singleDrawButton": "",
"multiDrawButton": "",
"historyButton": "",
"resultBackground": ""
},
"remark": ""
}
```
## 5. 接口参数
```json
{
"activityId": "",
"activityCode": "",
"activityType": "",
"rankingActivityType": "",
"rewardActivityType": "",
"otherParams": {}
}
```
## 6. 组件需求
需要哪个就填“是”，不需要或没填的我先不接。
```json
[
{
"name": "BackgroundLayer",
"enabled": "",
"remark": "长背景分段"
},
{
"name": "itemCenter",
"enabled": "",
"remark": "图片容器"
},
{
"name": "topUser / TopUser",
"enabled": "",
"remark": "前三名用户展示"
},
{
"name": "Barrage",
"enabled": "",
"remark": "弹幕"
},
{
"name": "ActivityTabs",
"enabled": "",
"remark": "标签页"
},
{
"name": "ActivityLotteryGrid",
"enabled": "",
"remark": "抽奖格子"
}
]
```
## 7. 建页后记录
这部分由 Codex 建页后填写。
### 7.1 已完成
-
### 7.2 未填写所以跳过
-
### 7.3 待你微调
-
### 7.4 验证结果
- `npm run build`：
- 备注：
````
## 4. 预设选项说明
这些选项填到专属页面信息 md 时，按下面含义理解。
| 选项 | 可选值 | 说明 |
| --- | --- | --- |
| 页面类型 | `Activities` / `Ranking` | 活动页或排行榜页 |
| 预加载方式 | `同步预加载` / `后台预加载` | 同步预加载参与进入动画，后台预加载不阻塞进入页面 |
| 排行榜加载方式 | `remote` / `local` | `remote` 为接口分页，`local` 为前端切片 |
| 抽奖展示方式 | `track-only` / `prize-card` / `custom` | 只转框 / 显示奖品卡 / 自定义格子 |
| 历史按钮位置 | `inside` / `below` / `absolute` / `external` / `hidden` | 抽奖历史按钮放置方式 |
## 5. 初版页面完成后你检查什么
```text
页面能打开
图片路径不 404
切语言时图片后缀符合预期
路由能进入
security 和 permissionManager 已补
排行榜能首屏展示
上拉加载策略正确：remote 请求下一页 / local slice 下一段
抽奖点击后有高亮转圈，并能停到中奖位置
弹窗能打开关闭
npm run build 通过
```

532
docs/活动页/建页资料库.md Normal file
View File

@ -0,0 +1,532 @@
# 建页资料库
这份文档存放建页时常用但不需要每次都手写的信息：组件用法、常用图片名、配置片段。
## 1. 常用组件用法
### 1.1 BackgroundLayer
用途：长页面背景分段渲染，适合 `bg0/bg1/bg2/bg3` 这类长活动页。
```vue
<BackgroundLayer :backgroundImages="[imageUrl('bg0'), imageUrl('bg1'), imageUrl('bg2')]" />
```
### 1.2 itemCenter
用途：背景图 + 内部绝对定位内容，是活动页最常用的图片容器。
```vue
<itemCenter :imgUrl="imageUrl('rewardBg')" contentStyle="padding: 10vw 6vw;">
<!-- 内容 -->
</itemCenter>
```
### 1.3 topUser / TopUser
用途：前三名用户展示。不同页面可能有自己的 `components/topUser.vue`，新页面可先从参考页面复制一份再微调。
```vue
<TopUser
:avatarUrl="item.userAvatar"
:name="item.userName"
:distributionValue="item.amount"
/>
```
```js
import TopUser from './components/topUser.vue'
```
### 1.4 Barrage
用途：中奖用户、活动动态等弹幕。LuckyDollars 页面常用。
```vue
<Barrage :list="barrageList" />
```
```js
import Barrage from './components/Barrage.vue'
```
### 1.5 ActivityTabs
用途：图片背景标签页。适合初始页面快速搭标签切换。
```vue
<ActivityTabs
:bg-url="imageUrl('tagsBg')"
:indicator-url="imageUrl('tagBtBg')"
:tabs="visibleTabs"
:active-value="currentTab"
@change="changeTab"
/>
```
### 1.6 ActivityLotteryGrid
用途：抽奖格子、高亮框和中心按钮区域。不同抽奖背景只改 `page.config.js` 里的布局。
```vue
<ActivityLotteryGrid
:prizes="prizeList"
:slot-count="pageConfig.lottery.slotCount"
:active-index="activeIndex"
:active-frame-url="imageUrl('prizeActiveFrame')"
:grid-style="pageConfig.lottery.grid.style"
:position-map="pageConfig.lottery.grid.positionMap"
:button-grid-area="pageConfig.lottery.grid.buttonGridArea"
:prize-render-mode="pageConfig.lottery.prizeRenderMode"
:disabled="isRolling"
@draw="draw(1)"
/>
```
## 2. 常用图片名清单
下面的图片名来自 `src/views/Activities` 和 `src/views/Ranking` 中常见的 `imageUrl('xxx')`、`webpUrl('xxx')`、`getImgName('xxx')` 用法。新页面不需要全部准备，按模块挑选即可。
注意：图片名大小写必须和文件名一致。项目里已有一些历史命名，例如 `RankingItem`、`RankingBottomBorder`、`rechargehidden`，这里按现有代码保留。
### 2.1 页面背景和顶部
```js
imageUrl('bg') // 页面主背景
imageUrl('bg0') // 页面背景第 0 段
imageUrl('bg1') // 页面背景第 1 段
imageUrl('bg2') // 页面背景第 2 段
imageUrl('bg3') // 页面背景第 3 段
webpUrl('pageTop') // 页面顶部 WebP 背景
imageUrl('timeBg') // 活动时间背景
imageUrl('dayBg') // 日期/天数背景
imageUrl('TimeBg') // 活动时间背景，历史大写命名
```
### 2.1.1 排行榜前几名展示区
推荐新页面使用 `rankingTopBg`，含义更明确：排行榜前几名展示区背景，不限定一定是前三名。
```js
imageUrl('rankingTopBg') // 排行榜前几名展示区背景，推荐新命名
imageUrl('topBg') // 排行榜前几名展示区背景，历史命名，不再作为页面顶部背景理解
imageUrl('top1') // 第一名头像/排名装饰
imageUrl('top2') // 第二名头像/排名装饰
imageUrl('top3') // 第三名头像/排名装饰
imageUrl('top1Bg') // 第一名独立背景
imageUrl('top2Bg') // 第二名独立背景
imageUrl('top3Bg') // 第三名独立背景
```
### 2.2 标签页和按钮
```js
imageUrl('tagsBg') // 标签页整体背景
imageUrl('tagBtBg') // 标签页选中底图
imageUrl(getImgName('rankBt')) // 排行榜未选中按钮
imageUrl(getImgName('rankBtActive')) // 排行榜选中按钮
imageUrl(getImgName('rankingBt')) // 排行按钮
imageUrl(getImgName('rankingBtActive')) // 排行选中按钮
imageUrl(getImgName('lotteryBt')) // 抽奖未选中按钮
imageUrl(getImgName('lotteryBtActive')) // 抽奖选中按钮
imageUrl(getImgName('rewardBt')) // 奖励未选中按钮
imageUrl(getImgName('rewardBtActive')) // 奖励选中按钮
imageUrl(getImgName('rechargeBt')) // 充值未选中按钮
imageUrl(getImgName('rechargeBtActive')) // 充值选中按钮
imageUrl(getImgName('redeemBt')) // 兑换按钮
imageUrl(getImgName('withdrawalBt')) // 提现未选中按钮
imageUrl(getImgName('withdrawalBtActive')) // 提现选中按钮
```
### 2.3 排行榜
```js
imageUrl('RankingMain') // 排行榜主体背景
imageUrl('RankingItem') // 排行榜列表项背景
imageUrl('rankingItemBg') // 排行榜列表项背景，另一套命名
imageUrl('RankingTopBorder') // 排行榜顶部边框
imageUrl('RankingBottomBorder') // 排行榜底部边框
imageUrl('RankingBorder') // 排行榜通用边框
imageUrl('myRankingBg') // 我的排名固定栏背景
imageUrl('rankingNumBg') // 排名数字背景
imageUrl('rankingTopBg') // 排行榜前几名展示区背景，推荐新命名
imageUrl('topBg') // 排行榜前几名展示区背景，历史命名
imageUrl('top1') // 第一名头像/排名装饰
imageUrl('top2') // 第二名头像/排名装饰
imageUrl('top3') // 第三名头像/排名装饰
imageUrl('top1Bg') // 第一名独立背景
imageUrl('top2Bg') // 第二名独立背景
imageUrl('top3Bg') // 第三名独立背景
imageUrl('top1-charm') // 魅力榜第一名装饰
imageUrl('top2-charm') // 魅力榜第二名装饰
imageUrl('top3-charm') // 魅力榜第三名装饰
imageUrl('top1-wealth') // 财富榜第一名装饰
imageUrl('top2-wealth') // 财富榜第二名装饰
imageUrl('top3-wealth') // 财富榜第三名装饰
imageUrl('top1-room') // 房间榜第一名装饰
imageUrl('top2-room') // 房间榜第二名装饰
imageUrl('top3-room') // 房间榜第三名装饰
imageUrl('myRankingBg-charm') // 魅力榜我的排名背景
imageUrl('myRankingBg-wealth') // 财富榜我的排名背景
imageUrl('myRankingBg-room') // 房间榜我的排名背景
imageUrl('RankingItem-charm') // 魅力榜列表项背景
imageUrl('RankingItem-wealth') // 财富榜列表项背景
imageUrl('RankingItem-room') // 房间榜列表项背景
imageUrl('tabSelectedBg') // 榜单分类选中底图
imageUrl('rankingSeasonBt') // 赛季榜按钮
imageUrl('rankingSeasonBtActive') // 赛季榜选中按钮
imageUrl('rankingWeeklyBt') // 周榜按钮
imageUrl('rankingWeeklyBtActive') // 周榜选中按钮
```
### 2.4 抽奖
```js
imageUrl('lottery') // 抽奖机/抽奖盘背景
imageUrl('lotteryBg') // 抽奖区域背景
imageUrl('prizeActiveFrame') // 抽奖高亮框
imageUrl('draw1BtBg') // 单抽按钮背景
imageUrl('draw10BtBg') // 十连抽按钮背景
imageUrl('resultBg') // 中奖结果弹窗背景
imageUrl('resultBack') // 中奖结果上一页按钮
imageUrl('resultNext') // 中奖结果下一页按钮
imageUrl('resultBt') // 中奖结果确认按钮
imageUrl('resultGoOnBt') // 继续抽奖按钮
```
### 2.5 奖励和奖品
```js
imageUrl('rewardBg') // 奖励模块背景
imageUrl('reward_banner') // 奖励横幅
imageUrl('rewards') // 奖励集合图
imageUrl('rewardBack') // 奖励上一页按钮
imageUrl('rewardNext') // 奖励下一页按钮
imageUrl(getImgName('rewardReceive')) // 奖励领取按钮
imageUrl(getImgName('rewardReceived')) // 奖励已领取按钮
imageUrl(getImgName('rewardReceiveNot')) // 奖励不可领取按钮
imageUrl(getImgName('receiveBt')) // 领取按钮
imageUrl(getImgName('receivedBt')) // 已领取按钮
imageUrl('reward_gift') // 礼物奖励图标
imageUrl('reward_frame') // 头像框奖励图标
imageUrl('reward_ride') // 座驾奖励图标
imageUrl('ticket') // 抽奖券图标
imageUrl('crystal') // 水晶/活动货币图标
imageUrl('debris') // 碎片/道具图标
imageUrl('giftBg') // 礼物背景
imageUrl('giftItemBg') // 礼物列表项背景
imageUrl('RewardRecharge100') // 充值 100 奖励图
imageUrl('RewardRecharge500') // 充值 500 奖励图
imageUrl('RewardRecharge1000') // 充值 1000 奖励图
imageUrl('RewardRecharge3000') // 充值 3000 奖励图
imageUrl('RewardRecharge5000') // 充值 5000 奖励图
imageUrl('RewardRecharge10000') // 充值 10000 奖励图
imageUrl('rechargeReward100') // 充值 100 奖励图，另一套命名
imageUrl('rechargeReward500') // 充值 500 奖励图，另一套命名
imageUrl('rechargeReward1000') // 充值 1000 奖励图，另一套命名
imageUrl('rechargeReward3000') // 充值 3000 奖励图，另一套命名
imageUrl('rechargeReward5000') // 充值 5000 奖励图，另一套命名
imageUrl('rechargeReward10000') // 充值 10000 奖励图，另一套命名
```
### 2.6 任务
```js
imageUrl('taskBtGo') // 任务去完成按钮
imageUrl('taskBtReceive') // 任务领取按钮
imageUrl('taskBtReceived') // 任务已领取按钮
imageUrl('taskGame') // 游戏任务图标
imageUrl('taskGift') // 送礼任务图标
imageUrl('taskRecharge') // 充值任务图标
imageUrl('taskTalk') // 聊天/上麦任务图标
imageUrl('taskItemBg') // 任务列表项背景
imageUrl('taskListBg') // 任务列表背景
imageUrl('taskTypeGame') // 游戏任务类型图标
imageUrl('taskTypeGift') // 礼物任务类型图标
```
### 2.7 弹窗、规则、帮助和历史
```js
imageUrl(getImgName('helpInfo')) // 帮助说明图片
imageUrl('helpBg') // 帮助弹窗背景
imageUrl('helpBt') // 帮助按钮
imageUrl(getImgName('ruleInfo')) // 规则说明图片
imageUrl('ruleInfoBg') // 规则弹窗背景
imageUrl(getImgName('ruleTitle')) // 规则标题图
imageUrl(getImgName('rulesBt')) // 规则按钮
imageUrl(getImgName('historyBt')) // 历史按钮
imageUrl(getImgName('historyBg')) // 历史弹窗背景
imageUrl('historyTopBg') // 历史弹窗顶部背景
imageUrl('recordBg') // 记录列表背景
imageUrl('closeBt') // 关闭按钮
```
### 2.8 用户信息、充值和收益
```js
imageUrl('myInfoBg') // 我的信息背景
imageUrl('myAvatarFrame') // 我的头像框
imageUrl('userNameBorder') // 用户名边框
imageUrl('userFrame') // 用户头像框
imageUrl('earningInfoBg') // 收益信息背景
imageUrl('earningsBg') // 收益背景
imageUrl('distribution') // 分发/派奖图标
imageUrl('rechargehidden') // 充值金额隐藏图标
imageUrl('rechargeShow') // 充值金额显示图标
imageUrl('rechargeNumHidden') // 充值数字隐藏图标
imageUrl('rechargeNumShow') // 充值数字显示图标
imageUrl('amountHiddenBt') // 金额隐藏按钮
imageUrl('amountShowBt') // 金额显示按钮
```
### 2.9 游戏玩法和特殊模块
```js
imageUrl('gameLotteryBt') // 游戏玩法-抽奖按钮
imageUrl('gameLotteryBtActive') // 游戏玩法-抽奖选中按钮
imageUrl('gameSignInBt') // 游戏玩法-签到按钮
imageUrl('gameSignInBtActive') // 游戏玩法-签到选中按钮
imageUrl('gameExchangeBt') // 游戏玩法-兑换按钮
imageUrl('gameExchangeBtActive') // 游戏玩法-兑换选中按钮
imageUrl('goodsItem') // 兑换商品项背景
imageUrl('makeUpBtBg') // 补签按钮背景
imageUrl('rewardGoodsBg') // 奖励物品背景
imageUrl('progressBar') // 进度条图片
imageUrl('timeBack') // 时间/日期上一页按钮
imageUrl('timeNext') // 时间/日期下一页按钮
```
## 3. 模块预设
这些预设用于创建“页面创建信息 md”时自动填充，目标是少问、少填、先生成能跑的初版。图片字段优先从 `3.1 多语言图片清单` 中匹配；没有匹配到的图片名可以留空或标记待确认。
### 3.1 Activities 通用活动页
适用：`src/views/Activities` 下类似 LuckyDollars、LesserBairam、SpringFestival 的活动页。
```json
{
"reward": {
"enabledWhenAnyImageExists": ["rewardBg", "rewardReceive", "rewardReceived", "rewardReceiveNot"],
"apis": ["activityRewardConfigs", "myRecharge", "receiveRechargeReward"],
"defaultImages": ["rewardBg", "rewardReceive", "rewardReceived", "rewardReceiveNot", "ticket", "reward_gift", "reward_frame", "reward_ride"],
"remark": "充值/消费奖励模块"
},
"ranking": {
"enabledWhenAnyImageExists": ["RankingItem", "myRankingBg", "rankingTopBg", "topBg", "top1", "top2", "top3", "rankBt", "rankBtActive"],
"apis": ["ranklist"],
"loadMode": "remote",
"pageSize": 20,
"topCount": 3,
"myRankingPath": "ranklist.body.currentUser",
"fieldMap": {
"avatar": "userAvatar",
"name": "userName",
"value": "amount",
"userId": "userId",
"rank": "rank"
},
"defaultImages": ["RankingItem", "myRankingBg", "rankingTopBg", "top1", "top2", "top3"],
"remark": "活动内排行榜，常见为接口分页"
},
"lottery": {
"enabledWhenAnyImageExists": ["lottery", "lotteryBg", "prizeActiveFrame", "lotteryBt", "lotteryBtActive"],
"drawApis": ["onceDraw", "multiDraw"],
"prizePoolApi": "activityDetail",
"drawCountApi": "myTickets",
"extraApis": ["myTotalDrawCount", "rewardConfigsBadge", "winnerHistory"],
"historyApi": "drawRecords",
"displayMode": "track-only",
"slotCount": 8,
"historyButtonPosition": "inside",
"defaultImages": {
"background": "lottery",
"activeFrame": "prizeActiveFrame",
"historyButton": "historyBt",
"resultBackground": "resultBg"
},
"remark": "抽奖接口基本固定；奖品展示方式按页面图片调整"
},
"task": {
"enabledWhenAnyImageExists": ["taskBtGo", "taskBtReceive", "taskBtReceived", "taskGame", "taskGift", "taskRecharge", "taskTalk"],
"apis": ["ActTaskList", "receiveTickets"],
"defaultImages": ["taskBtGo", "taskBtReceive", "taskBtReceived", "taskGame", "taskGift", "taskRecharge", "taskTalk"],
"remark": "任务列表和任务领奖"
},
"withdraw": {
"enabledWhenAnyImageExists": ["earningInfoBg", "myInfoBg"],
"apis": ["withdrawableAmount", "transferActivityDollar", "exchangeCoin"],
"defaultImages": ["earningInfoBg", "myInfoBg"],
"remark": "提现、转账或兑换模块"
},
"popups": {
"rule": {
"enabledWhenAnyImageExists": ["rulesBt", "ruleInfo"],
"triggerImage": "rulesBt",
"contentImage": "ruleInfo"
},
"help": {
"enabledWhenAnyImageExists": ["helpBt", "helpInfo"],
"triggerImage": "helpBt",
"contentImage": "helpInfo"
},
"history": {
"enabledWhenAnyImageExists": ["historyBt", "historyBg"],
"triggerImage": "historyBt",
"backgroundImage": "historyBg",
"apis": ["drawRecords"]
}
}
}
```
### 3.2 Ranking 独立排行榜页
适用：`src/views/Ranking` 下独立排行榜页。这里要特别区分加载方式：
- `remote`：接口支持 `pageNo/pageSize`，上拉时继续请求下一页。
- `local`：接口一次返回完整榜单，前端先展示一段，上拉时 `slice` 下一段，例如 `src/views/Ranking/Overall/Ranking.vue`。
```json
{
"ranking": {
"loadMode": "local / remote",
"topCount": 3,
"pageSize": 10,
"fieldMap": {
"avatar": "avatar",
"name": "nickname",
"value": "quantityFormat",
"userId": "id",
"rank": "rank"
},
"commonImages": [
"RankingItem",
"myRankingBg",
"top1",
"top2",
"top3",
"tabSelectedBg"
],
"remark": "如果接口差异不明确，先问用户参考哪个 Ranking 页面"
}
}
```
### 3.3 什么时候需要问用户
```text
同一模块存在多个接口版本时，问参考页面。
抽奖模块不是 8 格或不是 track-only 时，问抽奖展示方式。
排行榜接口不知道是 remote 还是 local 时，问参考页面或看接口是否传 pageNo/pageSize。
图片名看不出用途且无法从参考页面推断时，标记待确认，不阻塞初版生成。
```
## 4. 页面配置片段
### 4.1 图片工具
```js
import { useActivityAssets } from '@/composables/activity/useActivityAssets.js'
import { pageConfig } from './page.config.js'
const currentLangType = computed(() => {
return langStore.selectedLang?.type || 'en'
})
const { imageUrl, webpUrl, getImageName: getImgName } = useActivityAssets(
pageConfig,
currentLangType,
)
```
### 4.2 标签页
```js
import { useActivityTabs } from '@/composables/activity/useActivityTabs.js'
const { currentTab, visibleTabs, isTab, changeTab } = useActivityTabs(pageConfig.tabs, {
translate: t,
})
```
### 4.3 排行榜
```js
import { useActivityRanking } from '@/composables/activity/useActivityRanking.js'
const rankingState = useActivityRanking({
loadMode: pageConfig.ranking.loadMode,
pageSize: pageConfig.ranking.pageSize,
topCount: pageConfig.ranking.topCount,
fetchPage: ({ pageNo, pageSize }) => {
return ranklist({
activityId: pageConfig.activity.activityId,
pageNo,
pageSize,
})
},
})
```
### 4.4 抽奖
```js
import { useLotteryDraw } from '@/composables/activity/useLotteryDraw.js'
const { activeIndex, isRolling, startLottery } = useLotteryDraw({
getSlotCount: () => prizeList.value.length || pageConfig.lottery.slotCount,
})
```
### 4.5 分阶段图片预加载
用途：把首屏关键图片和后续图片拆开。首屏关键图片参与进入页面加载动画；弹窗、非默认标签页、下方长背景等图片在页面进入后后台继续预加载。
```js
// 进入页面前必须完成的图片，加载完成后再结束 loading 动画。
const blockingPreloadImageNames = pageConfig.preload?.blocking || []
// 进入页面后继续后台加载的图片，不阻塞页面展示。
const backgroundPreloadImageNames = pageConfig.preload?.background || []
// 统一走 imageUrl 和 getImgName，保证本地 OSS、线上 OSS、缓存版本、多语言后缀规则一致。
const resolvePreloadUrls = (names = []) => {
return [...new Set(names)].map((name) => imageUrl(getImgName(name)))
}
const preloadImageList = (urls = []) => {
return Promise.all(
urls.map((url) => new Promise((resolve) => {
const img = new Image()
img.onload = resolve
img.onerror = resolve
img.src = url
})),
)
}
const preloadBlockingImages = async () => {
await preloadImageList(resolvePreloadUrls(blockingPreloadImageNames))
}
const preloadBackgroundImages = () => {
const urls = resolvePreloadUrls(backgroundPreloadImageNames)
if (!urls.length) return
// 后台预加载不影响当前页面展示，所以失败也只吞掉。
const run = () => preloadImageList(urls).catch(() => {})
if (window.requestIdleCallback) {
window.requestIdleCallback(run)
return
}
setTimeout(run, 0)
}
onMounted(async () => {
await preloadBlockingImages()
isLoading.value = false
preloadBackgroundImages()
})
```

65
docs/活动页/快速建立活动页方案.md Normal file
View File

@ -0,0 +1,65 @@
# 活动页与排行榜页建页文档总览
当前 `src/views/Activities` 和 `src/views/Ranking` 的快速建页流程已经收敛为三份文档。
## 1. 你主要看哪份
优先看：
[建页操作模板.md](./建页操作模板.md)
用途：
```text
告诉你怎么操作
告诉你第一次只需要提供什么
提供专属页面信息 md 模板
保留需要填写的模块、接口、图片名、组件需求
```
以后新建页面时，推荐先告诉 Codex：
```text
页面名称：
创建位置：
```
Codex 会先创建专属页面信息 md 给你填写。
## 2. 有用资料放在哪
[建页资料库.md](./建页资料库.md)
用途：
```text
常用组件用法
常用 imageUrl 图片名和中文用途
图片工具、标签页、排行榜、抽奖配置片段
```
## 3. Codex 执行流程放在哪
[建页执行流程.md](./建页执行流程.md)
用途：
```text
规定 Codex 先建专属页面信息 md
规定 Codex 只处理你填写过的信息
规定 Codex 如何生成初版页面
规定完成后要把结果写回专属 md
```
你平时不需要看这份，除非想确认 Codex 会怎么执行。
## 4. 历史创建记录
[幸运美金第6季创建记录.md](./幸运美金第6季创建记录.md)
用途：
```text
记录 LuckyDollars Season6 当时的创建过程
作为历史参考，不作为新的通用模板
```

429
src/views/Activities/LuckyDollars/Season6/页面创建信息-完整参考.md Normal file
View File

@ -0,0 +1,429 @@
# 页面创建信息
## 1. 基础信息
- 页面类型：Activities
- 页面名称：LuckyDollars Season6
- 页面目录：src/views/Activities/LuckyDollars/Season6
- 参考页面：src/views/Activities/LuckyDollars/Season5
- 备注：作为新页面处理，初版效果参考 Season5，接口参数和图片可先沿用 Season5/Season6 测试数据。
## 2. 路由和权限
- route path：/activities/lucky-dollars-season6
- route name：lucky-dollars-season6
- 是否需要登录：是
- 是否加入 `src/config/security.js`：是
- 是否加入 `src/utils/permissionManager.js`：是
### 2.1 路由代码片段
```js
{
path: '/activities/lucky-dollars-season6',
name: 'lucky-dollars-season6',
component: () => import('../views/Activities/LuckyDollars/Season6/index.vue'),
meta: { requiresAuth: true },
}
```
### 2.2 安全白名单片段
建页时由 Codex 使用上面的 route path 补充到 `src/config/security.js`。
```js
'/activities/lucky-dollars-season6'
```
### 2.3 权限页面片段
建页时由 Codex 使用上面的 route path 补充到 `src/utils/permissionManager.js`，后面的注释使用页面名称。
```js
'/activities/lucky-dollars-season6' // 幸运美金第 6 季
```
## 3. OSS 图片目录
- OSS 相对路径：Activities/LuckyDollars/Season6/
- 本地开发目录：public/oss/h5/Azizi/Activities/LuckyDollars/Season6/
- 是否需要 Codex 自动创建本地开发目录：是
- 图片是否已放入本地目录：是
说明：OSS 相对路径和本地开发目录由 Codex 根据页面类型和页面目录自动生成。如果“是否需要 Codex 自动创建本地开发目录”填“是”，Codex 建页时会先创建这个目录。
### 3.1 多语言图片清单
说明：下面清单由 Codex 扫描本地开发目录自动生成。`en` 表示无后缀原图，`ar` 表示存在 `_ar` 图片。页面生成时以这张清单为准处理多语言图片。
| 图片名 | 支持语言 | 备注 |
| --- | --- | --- |
| bg0 | en | 页面背景第 0 段 |
| bg1 | en | 页面背景第 1 段 |
| bg2 | en | 页面背景第 2 段 |
| bg3 | en | 页面背景第 3 段 |
| helpInfo | en, ar | 帮助说明图 |
| historyBg | en, ar | 历史弹窗背景 |
| historyBt | en, ar | 历史按钮 |
| lottery | en | 抽奖机背景 |
| lotteryBt | en, ar | 抽奖按钮 |
| lotteryBtActive | en, ar | 抽奖选中按钮 |
| myAvatarFrame | en | 我的头像框 |
| myInfoBg | en | 我的信息背景 |
| myRankingBg | en | 我的排名背景 |
| prizeActiveFrame | en | 抽奖高亮框 |
| rankBt | en, ar | 排行榜按钮 |
| rankBtActive | en, ar | 排行榜选中按钮 |
| RankingItem | en | 排行榜列表项背景 |
| rechargehidden | en | 充值隐藏图标 |
| rechargeShow | en | 充值显示图标 |
| reward_frame | en | 头像框奖励图标 |
| reward_gift | en | 礼物奖励图标 |
| reward_ride | en | 座驾奖励图标 |
| rewardBack | en | 奖励上一页 |
| rewardBg | en | 奖励背景 |
| rewardNext | en | 奖励下一页 |
| rewardReceive | en, ar | 奖励领取按钮 |
| rewardReceived | en, ar | 奖励已领取按钮 |
| rewardReceiveNot | en, ar | 奖励不可领取按钮 |
| RewardRecharge100 | en | 充值奖励 100 |
| RewardRecharge1000 | en | 充值奖励 1000 |
| RewardRecharge10000 | en | 充值奖励 10000 |
| RewardRecharge3000 | en | 充值奖励 3000 |
| RewardRecharge500 | en | 充值奖励 500 |
| RewardRecharge5000 | en | 充值奖励 5000 |
| ruleInfo | en, ar | 规则说明图 |
| rulesBt | en, ar | 规则按钮 |
| tagBtBg | en | 标签选中底图 |
| tagsBg | en | 标签背景 |
| taskBtGo | en | 任务去完成按钮 |
| taskBtReceive | en | 任务领取按钮 |
| taskBtReceived | en | 任务已领取按钮 |
| taskGame | en | 游戏任务图标 |
| taskGift | en | 礼物任务图标 |
| taskRecharge | en | 充值任务图标 |
| taskTalk | en | 聊天任务图标 |
| ticket | en | 抽奖券图标 |
| timeBg | en | 时间背景 |
| top1 | en | 第一名装饰 |
| top2 | en | 第二名装饰 |
| top3 | en | 第三名装饰 |
### 3.2 进入页面前同步预加载图片
说明：这里放进入页面后首屏和默认标签页马上会用到的图片。Season6 参考默认把长背景、顶部时间、标签页、用户信息、奖励模块图片放在同步预加载里。
| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
| bg0 | 否 | 首屏长背景 |
| bg1 | 否 | 长背景第 1 段 |
| bg2 | 否 | 长背景第 2 段 |
| bg3 | 否 | 长背景第 3 段 |
| timeBg | 否 | 顶部时间模块 |
| tagsBg | 否 | 标签背景 |
| tagBtBg | 否 | 标签选中底图 |
| rankBt | 是 | 首屏标签按钮 |
| rankBtActive | 是 | 首屏标签按钮 |
| lotteryBt | 是 | 首屏标签按钮 |
| lotteryBtActive | 是 | 首屏标签按钮 |
| myInfoBg | 否 | 我的信息背景 |
| myAvatarFrame | 否 | 我的头像框 |
| rechargehidden | 否 | 充值金额隐藏图标 |
| rechargeShow | 否 | 充值金额显示图标 |
| rewardBg | 否 | 默认奖励模块背景 |
| rewardBack | 否 | 奖励上一页按钮 |
| rewardNext | 否 | 奖励下一页按钮 |
| rewardReceive | 是 | 奖励领取按钮 |
| rewardReceived | 是 | 奖励已领取按钮 |
| rewardReceiveNot | 是 | 奖励不可领取按钮 |
| RewardRecharge100 | 否 | 充值 100 奖励图 |
| RewardRecharge500 | 否 | 充值 500 奖励图 |
| RewardRecharge1000 | 否 | 充值 1000 奖励图 |
| RewardRecharge3000 | 否 | 充值 3000 奖励图 |
| RewardRecharge5000 | 否 | 充值 5000 奖励图 |
| RewardRecharge10000 | 否 | 充值 10000 奖励图 |
### 3.3 进入页面后后台预加载图片
说明：这里放非默认标签页、下方列表、弹窗、抽奖和任务相关图片。它们不阻塞进入页面动画，页面进入后后台继续加载。
| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
| lottery | 否 | 切到抽奖页时使用 |
| prizeActiveFrame | 否 | 抽奖高亮框 |
| ticket | 否 | 抽奖券图标 |
| historyBt | 是 | 抽奖历史按钮 |
| historyBg | 是 | 历史弹窗背景 |
| helpInfo | 是 | 帮助弹窗说明图 |
| ruleInfo | 是 | 规则弹窗说明图 |
| rulesBt | 是 | 规则按钮 |
| RankingItem | 否 | 排行榜列表项背景 |
| myRankingBg | 否 | 我的排名背景 |
| top1 | 否 | 第一名装饰 |
| top2 | 否 | 第二名装饰 |
| top3 | 否 | 第三名装饰 |
| reward_frame | 否 | 头像框奖励图标 |
| reward_gift | 否 | 礼物奖励图标 |
| reward_ride | 否 | 座驾奖励图标 |
| taskBtGo | 否 | 任务去完成按钮 |
| taskBtReceive | 否 | 任务领取按钮 |
| taskBtReceived | 否 | 任务已领取按钮 |
| taskGame | 否 | 游戏任务图标 |
| taskGift | 否 | 礼物任务图标 |
| taskRecharge | 否 | 充值任务图标 |
| taskTalk | 否 | 聊天任务图标 |
## 4. 模块配置
### 4.1 标签页模块
```json
{
"enabled": true,
"defaultValue": "reward",
"items": [
{
"value": "reward",
"labelKey": "recharge_reward",
"buttonImage": "rankBt",
"activeButtonImage": "rankBtActive",
"remark": "奖励组内的充值奖励页"
},
{
"value": "ranking",
"labelKey": "ranking",
"buttonImage": "rankBt",
"activeButtonImage": "rankBtActive",
"remark": "奖励组内的排行榜页"
},
{
"value": "lottery",
"labelKey": "lottery",
"buttonImage": "lotteryBt",
"activeButtonImage": "lotteryBtActive",
"remark": "抽奖组内的抽奖页"
},
{
"value": "withdraw",
"labelKey": "withdraw",
"buttonImage": "lotteryBt",
"activeButtonImage": "lotteryBtActive",
"remark": "抽奖组内的提现页"
}
]
}
```
### 4.2 页面区块模块
```json
[
{
"name": "reward",
"enabled": true,
"apis": ["activityRewardConfigs", "myRecharge", "receiveRechargeReward"],
"images": ["rewardBg", "rewardReceive", "rewardReceived", "rewardReceiveNot"],
"remark": "充值奖励"
},
{
"name": "ranking",
"enabled": true,
"apis": ["ranklist"],
"images": ["RankingItem", "myRankingBg", "top1", "top2", "top3"],
"remark": "服务端分页排行榜"
},
{
"name": "lottery",
"enabled": true,
"apis": ["activityDetail", "onceDraw", "multiDraw", "myTickets", "myTotalDrawCount"],
"images": ["lottery", "prizeActiveFrame", "ticket"],
"remark": "抽奖机"
},
{
"name": "task",
"enabled": true,
"apis": ["ActTaskList", "receiveTickets"],
"images": ["taskBtGo", "taskBtReceive", "taskBtReceived"],
"remark": "任务列表"
},
{
"name": "withdraw",
"enabled": true,
"apis": ["withdrawableAmount", "transferActivityDollar", "exchangeCoin"],
"images": [],
"remark": "提现、转账、兑换；本地图片清单未扫描到 earningInfoBg，图片待确认"
},
{
"name": "countdown",
"enabled": true,
"apis": [],
"images": ["timeBg"],
"remark": "倒计时"
}
]
```
### 4.3 弹窗模块
```json
[
{
"name": "rule",
"triggerImage": "rulesBt",
"backgroundImage": "",
"contentImage": "ruleInfo",
"apis": [],
"remark": "规则说明"
},
{
"name": "help",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "helpInfo",
"apis": [],
"remark": "帮助说明；本地图片清单未扫描到 helpBt，触发按钮待确认"
},
{
"name": "history",
"triggerImage": "historyBt",
"backgroundImage": "historyBg",
"contentImage": "",
"apis": ["drawRecords"],
"remark": "中奖历史"
},
{
"name": "result",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": ["onceDraw", "multiDraw"],
"remark": "中奖结果；本地图片清单未扫描到 resultBg，背景图待确认"
},
{
"name": "rewardDetail",
"triggerImage": "",
"backgroundImage": "rewardBg",
"contentImage": "",
"apis": ["activityRewardConfigs"],
"remark": "奖励详情"
}
]
```
### 4.4 排行榜模块
```json
{
"enabled": true,
"api": "ranklist",
"loadMode": "remote",
"pageSize": 20,
"topCount": 3,
"myRankingPath": "ranklist.body.currentUser",
"fieldMap": {
"avatar": "userAvatar",
"name": "userName",
"value": "amount",
"userId": "userId",
"rank": "rank"
}
}
```
### 4.5 抽奖模块
```json
{
"enabled": true,
"drawApis": ["onceDraw", "multiDraw"],
"prizePoolApi": "activityDetail",
"drawCountApi": "myTickets",
"extraApis": ["myTotalDrawCount", "rewardConfigsBadge", "winnerHistory"],
"displayMode": "track-only",
"slotCount": 8,
"centerButtonPosition": "grid-area: 2 / 2",
"historyButtonPosition": "inside",
"images": {
"background": "lottery",
"activeFrame": "prizeActiveFrame",
"singleDrawButton": "无，按钮区域在背景图上",
"multiDrawButton": "无，按钮区域在背景图上",
"historyButton": "historyBt",
"resultBackground": ""
},
"remark": "奖品内容已画在抽奖背景图上，接口奖品只用于计算高亮框停靠位置；本地图片清单未扫描到 resultBg。"
}
```
## 5. 接口参数
```json
{
"activityId": "2007771533999124198",
"activityCode": "24198",
"activityType": "CONSUMPTION_ACTIVITY",
"rankingActivityType": "USER_RECHARGE_DRAW",
"rewardActivityType": "CONSUMPTION_ACTIVITY",
"otherParams": {
"drawCount": [1, 10]
}
}
```
## 6. 组件需求
```json
[
{
"name": "BackgroundLayer",
"enabled": true,
"remark": "使用 bg0/bg1/bg2/bg3 长背景"
},
{
"name": "itemCenter",
"enabled": true,
"remark": "图片容器"
},
{
"name": "topUser / TopUser",
"enabled": true,
"remark": "从参考页面组件复制后微调"
},
{
"name": "Barrage",
"enabled": true,
"remark": "从参考页面组件复制后微调"
},
{
"name": "ActivityTabs",
"enabled": "可选",
"remark": "如果重做标签页，优先用通用组件"
},
{
"name": "ActivityLotteryGrid",
"enabled": true,
"remark": "抽奖格子和高亮框"
}
]
```
## 7. 建页后记录
这部分由 Codex 建页后填写。
### 7.1 已完成
-
### 7.2 未填写所以跳过
-
### 7.3 待你微调
-
### 7.4 验证结果
- `npm run build`：
- 备注：

433
src/views/Activities/LuckyDollars/Season6/页面创建信息-待填写.md Normal file
View File

@ -0,0 +1,433 @@
# 页面创建信息
## 1. 基础信息
- 页面类型：Activities
- 页面名称：LuckyDollars Season6
- 页面目录：src/views/Activities/LuckyDollars/Season6
- 参考页面：src/views/Activities/LuckyDollars/Season5
- 备注：作为新页面处理，初版效果参考 Season5，接口参数和图片可先沿用 Season5/Season6 测试数据。
## 2. 路由和权限
- route path：/activities/lucky-dollars-season6
- route name：lucky-dollars-season6
- 是否需要登录：是
- 是否加入 `src/config/security.js`：是
- 是否加入 `src/utils/permissionManager.js`：是
### 2.1 路由代码片段
建页时由 Codex 根据上面的 route path、route name 和页面目录生成。
```js
{
path: '/activities/lucky-dollars-season6',
name: 'lucky-dollars-season6',
component: () => import('../views/Activities/LuckyDollars/Season6/index.vue'),
meta: { requiresAuth: true },
}
```
### 2.2 安全白名单片段
建页时由 Codex 使用上面的 route path 补充到 `src/config/security.js`。
```js
'/activities/lucky-dollars-season6'
```
### 2.3 权限页面片段
建页时由 Codex 使用上面的 route path 补充到 `src/utils/permissionManager.js`，后面的注释使用页面名称。
```js
'/activities/lucky-dollars-season6' // 幸运美金第 6 季
```
## 3. OSS 图片目录
- OSS 相对路径：Activities/LuckyDollars/Season6/
- 本地开发目录：public/oss/h5/Azizi/Activities/LuckyDollars/Season6/
- 是否需要 Codex 自动创建本地开发目录：是
- 图片是否已放入本地目录：是
说明：OSS 相对路径和本地开发目录由 Codex 根据页面类型和页面目录自动生成，你可以按需要修改。如果“是否需要 Codex 自动创建本地开发目录”填“是”，Codex 建页时会先创建这个目录，方便你直接放图片。
### 3.1 多语言图片清单
说明：下面清单由 Codex 扫描本地开发目录自动生成。无后缀图片视为 `en` 原图；如存在 `_ar`、`_bn`、`_tr` 等后缀，则合并到同一个图片名的支持语言中。页面生成时以这张清单为准处理多语言图片，你可以按实际需求删除、改名或补备注。
| 图片名 | 支持语言 | 备注 |
| --- | --- | --- |
| bg0 | en | 页面背景第 0 段 |
| bg1 | en | 页面背景第 1 段 |
| bg2 | en | 页面背景第 2 段 |
| bg3 | en | 页面背景第 3 段 |
| helpInfo | en, ar | 帮助说明图 |
| historyBg | en, ar | 历史弹窗背景 |
| historyBt | en, ar | 历史按钮 |
| lottery | en | 抽奖机背景 |
| lotteryBt | en, ar | 抽奖按钮 |
| lotteryBtActive | en, ar | 抽奖选中按钮 |
| myAvatarFrame | en | 我的头像框 |
| myInfoBg | en | 我的信息背景 |
| myRankingBg | en | 我的排名背景 |
| prizeActiveFrame | en | 抽奖高亮框 |
| rankBt | en, ar | 排行榜按钮 |
| rankBtActive | en, ar | 排行榜选中按钮 |
| RankingItem | en | 排行榜列表项背景 |
| rechargehidden | en | 充值金额隐藏图标 |
| rechargeShow | en | 充值金额显示图标 |
| reward_frame | en | 头像框奖励图标 |
| reward_gift | en | 礼物奖励图标 |
| reward_ride | en | 座驾奖励图标 |
| rewardBack | en | 奖励上一页按钮 |
| rewardBg | en | 奖励模块背景 |
| rewardNext | en | 奖励下一页按钮 |
| rewardReceive | en, ar | 奖励领取按钮 |
| rewardReceived | en, ar | 奖励已领取按钮 |
| rewardReceiveNot | en, ar | 奖励不可领取按钮 |
| RewardRecharge100 | en | 充值 100 奖励图 |
| RewardRecharge1000 | en | 充值 1000 奖励图 |
| RewardRecharge10000 | en | 充值 10000 奖励图 |
| RewardRecharge3000 | en | 充值 3000 奖励图 |
| RewardRecharge500 | en | 充值 500 奖励图 |
| RewardRecharge5000 | en | 充值 5000 奖励图 |
| ruleInfo | en, ar | 规则说明图 |
| rulesBt | en, ar | 规则按钮 |
| tagBtBg | en | 标签页选中底图 |
| tagsBg | en | 标签页背景 |
| taskBtGo | en | 任务去完成按钮 |
| taskBtReceive | en | 任务领取按钮 |
| taskBtReceived | en | 任务已领取按钮 |
| taskGame | en | 游戏任务图标 |
| taskGift | en | 礼物任务图标 |
| taskRecharge | en | 充值任务图标 |
| taskTalk | en | 聊天任务图标 |
| ticket | en | 抽奖券图标 |
| timeBg | en | 活动时间背景 |
| top1 | en | 第一名装饰 |
| top2 | en | 第二名装饰 |
| top3 | en | 第三名装饰 |
### 3.2 进入页面前同步预加载图片
说明：这里填写会参与进入页面加载动画的关键图片。Codex 生成页面时会先等待这些图片加载完成，再结束预加载动画。
| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
| bg0 | 否 | 首屏长背景 |
| bg1 | 否 | 长背景第 1 段 |
| bg2 | 否 | 长背景第 2 段 |
| bg3 | 否 | 长背景第 3 段 |
| timeBg | 否 | 顶部时间模块 |
| tagsBg | 否 | 标签背景 |
| tagBtBg | 否 | 标签选中底图 |
| rankBt | 是 | 首屏标签按钮 |
| rankBtActive | 是 | 首屏标签按钮 |
| lotteryBt | 是 | 首屏标签按钮 |
| lotteryBtActive | 是 | 首屏标签按钮 |
| myInfoBg | 否 | 我的信息背景 |
| myAvatarFrame | 否 | 我的头像框 |
| rechargehidden | 否 | 充值金额隐藏图标 |
| rechargeShow | 否 | 充值金额显示图标 |
| rewardBg | 否 | 默认奖励模块背景 |
| rewardBack | 否 | 奖励上一页按钮 |
| rewardNext | 否 | 奖励下一页按钮 |
| rewardReceive | 是 | 奖励领取按钮 |
| rewardReceived | 是 | 奖励已领取按钮 |
| rewardReceiveNot | 是 | 奖励不可领取按钮 |
| RewardRecharge100 | 否 | 充值 100 奖励图 |
| RewardRecharge500 | 否 | 充值 500 奖励图 |
| RewardRecharge1000 | 否 | 充值 1000 奖励图 |
| RewardRecharge3000 | 否 | 充值 3000 奖励图 |
| RewardRecharge5000 | 否 | 充值 5000 奖励图 |
| RewardRecharge10000 | 否 | 充值 10000 奖励图 |
### 3.3 进入页面后后台预加载图片
说明：这里填写不影响进入页面动画的图片。Codex 可以在首屏图片加载完成后继续后台预加载它们，避免后续打开弹窗、切标签页或滚动到下方时才开始请求图片。
| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
| lottery | 否 | 切到抽奖页时使用 |
| prizeActiveFrame | 否 | 抽奖高亮框 |
| ticket | 否 | 抽奖券图标 |
| historyBt | 是 | 抽奖历史按钮 |
| historyBg | 是 | 历史弹窗背景 |
| helpInfo | 是 | 帮助弹窗说明图 |
| ruleInfo | 是 | 规则弹窗说明图 |
| rulesBt | 是 | 规则按钮 |
| RankingItem | 否 | 排行榜列表项背景 |
| myRankingBg | 否 | 我的排名背景 |
| top1 | 否 | 第一名装饰 |
| top2 | 否 | 第二名装饰 |
| top3 | 否 | 第三名装饰 |
| reward_frame | 否 | 头像框奖励图标 |
| reward_gift | 否 | 礼物奖励图标 |
| reward_ride | 否 | 座驾奖励图标 |
| taskBtGo | 否 | 任务去完成按钮 |
| taskBtReceive | 否 | 任务领取按钮 |
| taskBtReceived | 否 | 任务已领取按钮 |
| taskGame | 否 | 游戏任务图标 |
| taskGift | 否 | 礼物任务图标 |
| taskRecharge | 否 | 充值任务图标 |
| taskTalk | 否 | 聊天任务图标 |
## 4. 模块配置
没有填写的模块，初版页面先不处理。
### 4.1 标签页模块
```json
{
"enabled": true,
"defaultValue": "reward",
"items": [
{
"value": "reward",
"labelKey": "recharge_reward",
"buttonImage": "rankBt",
"activeButtonImage": "rankBtActive",
"remark": "奖励组内的充值奖励页"
},
{
"value": "ranking",
"labelKey": "ranking",
"buttonImage": "rankBt",
"activeButtonImage": "rankBtActive",
"remark": "奖励组内的排行榜页"
},
{
"value": "lottery",
"labelKey": "lottery",
"buttonImage": "lotteryBt",
"activeButtonImage": "lotteryBtActive",
"remark": "抽奖组内的抽奖页"
},
{
"value": "withdraw",
"labelKey": "withdraw",
"buttonImage": "lotteryBt",
"activeButtonImage": "lotteryBtActive",
"remark": "抽奖组内的提现页"
}
]
}
```
### 4.2 页面区块模块
```json
[
{
"name": "reward",
"enabled": true,
"apis": ["activityRewardConfigs", "myRecharge", "receiveRechargeReward"],
"images": ["rewardBg", "rewardReceive", "rewardReceived", "rewardReceiveNot"],
"remark": "奖励区块"
},
{
"name": "ranking",
"enabled": true,
"apis": ["ranklist"],
"images": ["RankingItem", "myRankingBg", "top1", "top2", "top3"],
"remark": "排行榜区块"
},
{
"name": "lottery",
"enabled": true,
"apis": ["activityDetail", "onceDraw", "multiDraw", "myTickets", "myTotalDrawCount"],
"images": ["lottery", "prizeActiveFrame", "ticket"],
"remark": "抽奖区块"
},
{
"name": "task",
"enabled": true,
"apis": ["ActTaskList", "receiveTickets"],
"images": ["taskBtGo", "taskBtReceive", "taskBtReceived"],
"remark": "任务区块"
},
{
"name": "withdraw",
"enabled": true,
"apis": ["withdrawableAmount", "transferActivityDollar", "exchangeCoin"],
"images": [],
"remark": "提现/兑换区块；本地图片清单未扫描到 earningInfoBg，图片待确认"
},
{
"name": "countdown",
"enabled": true,
"apis": [],
"images": ["timeBg"],
"remark": "倒计时区块，截止日期为 2026-06-01"
}
]
```
### 4.3 弹窗模块
```json
[
{
"name": "rule",
"triggerImage": "rulesBt",
"backgroundImage": "",
"contentImage": "ruleInfo",
"apis": [],
"remark": "规则弹窗"
},
{
"name": "help",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "helpInfo",
"apis": [],
"remark": "帮助弹窗；本地图片清单未扫描到 helpBt，触发按钮待确认"
},
{
"name": "history",
"triggerImage": "historyBt",
"backgroundImage": "historyBg",
"contentImage": "",
"apis": ["drawRecords"],
"remark": "历史记录弹窗"
},
{
"name": "result",
"triggerImage": "",
"backgroundImage": "",
"contentImage": "",
"apis": ["onceDraw", "multiDraw"],
"remark": "中奖结果弹窗；本地图片清单未扫描到 resultBg，背景图待确认"
},
{
"name": "rewardDetail",
"triggerImage": "",
"backgroundImage": "rewardBg",
"contentImage": "",
"apis": ["activityRewardConfigs"],
"remark": "奖励详情弹窗"
}
]
```
### 4.4 排行榜模块
```json
{
"enabled": true,
"api": "ranklist",
"loadMode": "remote",
"pageSize": 20,
"topCount": 3,
"myRankingPath": "ranklist.body.currentUser",
"fieldMap": {
"avatar": "userAvatar",
"name": "userName",
"value": "amount",
"userId": "userId",
"rank": "rank"
}
}
```
### 4.5 抽奖模块
```json
{
"enabled": true,
"drawApis": ["onceDraw", "multiDraw"],
"prizePoolApi": "activityDetail",
"drawCountApi": "myTickets",
"extraApis": ["myTotalDrawCount", "rewardConfigsBadge", "winnerHistory"],
"displayMode": "track-only",
"slotCount": 8,
"centerButtonPosition": "grid-area: 2 / 2",
"historyButtonPosition": "inside",
"images": {
"background": "lottery",
"activeFrame": "prizeActiveFrame",
"singleDrawButton": "无，按钮区域在背景图上",
"multiDrawButton": "无，按钮区域在背景图上",
"historyButton": "historyBt",
"resultBackground": ""
},
"remark": "奖品内容已画在抽奖背景图上，接口奖品只用于计算高亮框停靠位置；本地图片清单未扫描到 resultBg。"
}
```
## 5. 接口参数
```json
{
"activityId": "",
"activityCode": "",
"activityType": "",
"rankingActivityType": "",
"rewardActivityType": "",
"otherParams": {}
}
```
## 6. 组件需求
需要哪个就填“是”，不需要或没填的初版页面先不接。
```json
[
{
"name": "BackgroundLayer",
"enabled": "",
"remark": "长背景分段"
},
{
"name": "itemCenter",
"enabled": "",
"remark": "图片容器"
},
{
"name": "topUser / TopUser",
"enabled": "",
"remark": "前三名用户展示"
},
{
"name": "Barrage",
"enabled": "",
"remark": "弹幕"
},
{
"name": "ActivityTabs",
"enabled": "",
"remark": "标签页"
},
{
"name": "ActivityLotteryGrid",
"enabled": "",
"remark": "抽奖格子"
}
]
```
## 7. 建页后记录
这部分由 Codex 建页后填写。
### 7.1 已完成
-
### 7.2 未填写所以跳过
-
### 7.3 待你微调
-
### 7.4 验证结果
- `npm run build`：
- 备注：

21
vite.config.js
View File

@ -3,11 +3,15 @@ import Components from 'unplugin-vue-components/vite'
import { defineConfig } from 'vite'
import { fileURLToPath, URL } from 'node:url'
import { existsSync } from 'node:fs'
import { isAbsolute, relative, resolve } from 'node:path'
import { VantResolver } from 'unplugin-vue-components/resolvers'
const buildTimestamp = Date.now()
const PRODUCTION_LIKE_MODES = new Set(['production', 'production-atu'])
const STRIPPABLE_CONSOLE_METHODS = ['log', 'debug', 'info']
const PUBLIC_DIR = fileURLToPath(new URL('./public', import.meta.url))
const PUBLIC_ROOT = resolve(PUBLIC_DIR)
function isEscaped(code, index) {
let backslashCount = 0
@ -315,6 +319,23 @@ export default defineConfig(({ mode }) => {
target: 'https://cdn.azizichat.com',
changeOrigin: true,
secure: true,
bypass: (req) => {
const requestUrl = req.url || ''
try {
const pathname = decodeURIComponent(new URL(requestUrl, 'http://localhost').pathname)
const localPublicFile = resolve(PUBLIC_ROOT, `.${pathname}`)
const localPathInPublic = relative(PUBLIC_ROOT, localPublicFile)
if (!localPathInPublic.startsWith('..') && !isAbsolute(localPathInPublic) && existsSync(localPublicFile)) {
return pathname
}
} catch (error) {
console.warn('Failed to check local OSS fallback:', error)
}
return null
},
rewrite: (path) => path.replace(/^\/oss/, ''),
configure: (proxy) => {
proxy.on('proxyRes', (proxyRes) => {