# 建页操作模板

这份文档只回答一个问题：你要怎么操作，才能让我快速生成 `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 通过
```