12 KiB
12 KiB
建页操作模板
这份文档只回答一个问题：你要怎么操作，才能让我快速生成 src/views/Activities 或 src/views/Ranking 的初版页面。
真正建页时不需要一次说完整需求。推荐先让我创建一份“页面创建信息 md”，你在里面按坑位填写；你没填的项，我生成初版时先不处理。
相关资料：
- 建页资料库.md：组件用法、常用图片名、配置选项。
- 建页执行流程.md：我真正执行建页时遵守的流程。
- 快速建立活动页方案.md：文档入口和总览。
1. 推荐操作流程
第一次只告诉我页面名称和创建位置：
新建活动页：LuckyDollars Season7
创建位置：src/views/Activities/LuckyDollars/Season7
或者：
新建排行榜页：Overall Season2
创建位置：src/views/Ranking/OverallSeason2
我收到后只做一件事：在 docs/活动页/ 下创建专属页面信息 md，例如：
docs/活动页/LuckyDollars-Season7-创建信息.md
这份 md 会先填好：
页面类型
页面名称
页面目录
route path
route name
OSS 相对路径
本地开发目录
其中 route path 和 route name 会根据页面类型、页面名称、页面目录自动生成。你有特殊需求时，直接在 md 里改掉即可。
OSS 相对路径 和 本地开发目录 也会根据页面类型和页面目录自动生成。你只需要选择是否让我自动创建本地开发目录。
其它信息会尽量由图片扫描和模块预设先填好；只有无法推断的地方才留给你补。
你填完后，再告诉我：
按 docs/活动页/LuckyDollars-Season7-创建信息.md 继续生成初版页面
我再根据你填写的信息创建页面、配置、路由、权限、本地 OSS 目录，并把执行结果写回这份专属 md。
2. 填写规则
- 模块配置：优先由 Codex 根据页面类型、扫描图片和参考页面自动预设；你只改不符合预期的地方。
- 图片名和模块图片：优先从
3.1 多语言图片清单和模块预设中自动推断，通常不用额外填写。 - 模块接口：常见模块会自动预设，例如抽奖、奖池、任务、排行榜、中奖历史这类接口不用每次手写。
- 没填且无法推断的模块：我先不实现，或标记为“待确认”。
- 参考页面只作为结构和接口参考，不代表新页面就是复制旧页面。
- 初版页面只保证结构、路径、接口位置、基础交互可用，图片对位和局部样式后续你再微调。
- 需要你填写的模块配置、接口参数、组件需求，尽量使用 JSON 代码块，避免用 Markdown 表格对齐。
3. 专属页面信息 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. 初版页面完成后你检查什么
页面能打开
图片路径不 404
切语言时图片后缀符合预期
路由能进入
security 和 permissionManager 已补
排行榜能首屏展示
上拉加载策略正确：remote 请求下一页 / local slice 下一段
抽奖点击后有高亮转圈，并能停到中奖位置
弹窗能打开关闭
npm run build 通过