建页操作模板

这份文档只给用户看：告诉你第一次怎么提需求，以及专属 页面创建信息.md 里需要填什么。

规则正文不在这里重复维护：

建页阶段、路由、OSS、多语言图片、预加载、children 嵌套规则：看建页执行流程.md。
组件用法、常用图片名、模块预设、配置代码片段：看建页资料库.md。

1. 推荐操作流程

第一次只告诉我页面名称和创建位置：

新建活动页：Gulben Festival
创建位置：src/views/Activities/GulbenFestival

或：

新建排行榜页：Overall Season2
创建位置：src/views/Ranking/OverallSeason2

我会先做准备阶段：

1. 创建页面目录。
2. 在页面目录中创建 页面创建信息.md。
3. 根据 页面创建信息.md 创建 page.config.js 初始配置。
4. 按需要创建本地 OSS 图片目录。
   - 本地 OSS 图片目录仅用于开发期存放图片，方便页面读取本地资源；发布时图片由你上传到真实 OSS，不随项目提交 Git。
   - Codex 仍会按需要创建这个文件夹，但不会生成 `.gitkeep`；空文件夹不被 Git 追踪是正常现象。
5. 立即按 route path 写入 `src/router/index.js`、`src/config/security.js`、`src/utils/permissionManager.js`；这一步属于首次新建页面准备工作，不等后续生成页面时再补。
6. 预填 route、OSS、图片清单、预加载和模块配置。
7. 不生成 index.vue，除非你明确要求继续创建页面；如果此时还没有 index.vue，不运行构建，等生成页面后再验证。

专属 md 优先放在页面目录里：

src/views/Activities/GulbenFestival/页面创建信息.md

你补完 md 中一部分信息后，可以先让我生成可预览底座：

按 src/views/Activities/GulbenFestival/页面创建信息.md 生成可预览底座

我会以这份 md 为需求源同步 page.config.js，生成 index.vue 的 loading、预加载、组件引用、图片工具、页面背景、顶部基础区域、一级/二级 tabs 容器和空内容占位。

后续你再一步步告诉我：

生成 CollectCards 的抽奖结构
对接 Personal Rank 的 Ranking 接口
生成 Room Rank 的 Reward 展示

我再按你指定的模块继续补，不会一次性把所有业务模块和接口都生成出来。

2. 填写规则

没填的字段，初版页面先不猜。
页面创建信息.md 是 page.config.js 和 index.vue 的生成来源；后续补需求先改 md，再同步代码。
如果你已经在 Vue 里实时调好了布局或样式，可以明确说“按实时 Vue 同步到 md”；这时 Codex 会反向更新 页面创建信息.md，不会用旧 md 覆盖当前 Vue。
每轮可以指定同步方向：md -> vue 或 vue -> md；方向不明确且两边冲突时，先确认再改。
index.vue 采用渐进式生成：先生成可预览底座，再按你的指令逐步补模块和接口。
可预览底座只放预加载、组件引用、图片背景、基础顶部、tabs 容器和占位内容。
新建页面只要生成 index.vue，都会默认带统一加载动画：先展示 LoadingContent，关键图片/初始化完成后再显示正式页面。
开发预览阶段，能直接用内联样式表达的固定不变、一次性布局、尺寸、间距、定位，就直接写内联样式，方便实时调位置并减少不必要的 class 拆分；稳定后再按复用性抽成 class。
动态样式不要优先写 :style="{ ... }"，状态切换、选中态、方向、显隐、尺寸变化优先用 class。
可复用样式、伪类、媒体查询和 RTL 规则仍建议写 class。
使用 itemCenter 承载图片背景时，要按图片比例补 min-height，避免图片未加载时内部信息挤在一起。公式：min-height = Math.ceil(展示宽度vw * 图片高度 / 图片宽度) + 'vw'；展示宽度取组件在页面上的实际占用宽度，多语言图片取最高计算结果。
生成的 Vue 文件统一使用 <style lang="scss" scoped>，顶部固定放 * { color: #fff; }、.fullPage {} 和响应式基础字号 media query；阿语样式用 [dir='rtl'] 集中写在 style 里。
除基础 media query 外，页面内展示字号统一写 font-size: 1em，跟随响应式基准字号变化。
images.container / containerImages 这类模块大背景图统一用 itemCenter，宽度先写 100vw，父级从上往下 flex 排列，gap、padding、margin 初始写 0，不额外加边框虚线。
页面后续更新模块、接口或方法时，新增/调整的方法和关键模块逻辑都要添加简短中文注释，说明用途、接口来源、字段映射或展示规则；模板里的主要 div、section、itemCenter 等结构模块也要补中文注释，说明当前块负责的视觉区域或业务含义。
页面任何模块都不要出现可见滚动条；推荐页面根容器固定 height: 100vh、overflow: hidden，由内部主内容容器负责 overflow-y: auto 垂直滚动并隐藏滚动条。
模块配置、接口参数、组件需求优先使用 JSON 代码块。
图片清单和预加载清单保留 Markdown 表格，方便检查。
一级标签下面还有二级标签或子区块时，在对应 section 中写 children。
children.tabs 表示子标签，children.sections 表示子内容。
children: {} 表示当前区块暂时没有子模块。
倒计时模块可以不启用，但要保留 enabled、截止日期、使用图片和 remark 填空位。
如果备注写“开发期间不加翻译”，初版页面直接展示 md 里的文本。

3. 专属页面信息 md 模板

创建新页面时，Codex 会按下面结构生成 页面创建信息.md。基础字段会先自动填好，图片和模块会尽量按扫描结果和预设补齐。

# 页面创建信息

## 1. 基础信息

- 页面类型：Activities / Ranking
- 页面名称：
- 页面目录：
- 参考页面：
- 备注：

## 2. 路由和权限

- route path：
- route name：
- 是否需要登录：是 / 否
- 是否加入 `src/config/security.js`：是 / 否
- 是否加入 `src/utils/permissionManager.js`：是 / 否

### 2.1 路由代码片段

```js
// 由 Codex 按 route path、route name 和页面目录生成
```

### 2.2 安全白名单片段

```js
// 由 Codex 按 route path 生成
```

### 2.3 权限页面片段

```js
// 由 Codex 按 route path 和页面名称生成
```

## 3. OSS 图片目录

- OSS 相对路径：
- 本地开发目录：
- 是否需要 Codex 自动创建本地开发目录：是 / 否
- 图片是否已放入本地目录：是 / 否

说明：本地开发目录只作为开发期 OSS 图片镜像使用，Codex 需要保留创建文件夹的能力，便于你放入开发用图片；目录内图片和空目录占位文件不作为 Git 提交内容，新建时不要生成 `.gitkeep`。

### 3.1 多语言图片清单

| 图片名 | 支持语言 | 备注 |
| --- | --- | --- |
|  |  | Codex 扫描并匹配或推断中文用途，必要时你再改 |

### 3.2 进入页面前同步预加载图片

| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
|  |  |  |

### 3.3 进入页面后后台预加载图片

| 图片名 | 是否包含多语言 | 备注 |
| --- | --- | --- |
|  |  |  |

## 4. 模块配置

没有填写的模块，初版页面先不处理。

### 4.1 标签页模块

```json
{
  "enabled": true,
  "defaultValue": "",
  "items": []
}
```

`items` 可以先写字符串；需要图片、翻译 key、埋点等信息时再改成对象。

字符串写法：

```json
{
  "enabled": true,
  "defaultValue": "Personal Rank",
  "items": ["CollectCards to Win Prizes", "Personal Rank", "Room Rank"]
}
```

对象写法：

```json
{
  "enabled": true,
  "defaultValue": "reward",
  "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": "奖励区块",
    "children": {}
  },
  {
    "name": "ranking",
    "enabled": "",
    "apis": [],
    "images": [],
    "remark": "排行榜区块",
    "children": {}
  },
  {
    "name": "lottery",
    "enabled": "",
    "apis": [],
    "images": [],
    "remark": "抽奖区块",
    "children": {}
  },
  {
    "name": "task",
    "enabled": "",
    "apis": [],
    "images": [],
    "remark": "任务区块",
    "children": {}
  }
]
```

倒计时模块固定保留：

```json
{
  "name": "countdown",
  "enabled": "",
  "deadline": "",
  "images": ["timeBg"],
  "fields": {
    "endTime": "",
    "remainingText": ""
  },
  "remark": "天数补 D；天时分秒分别使用 itemCenter 图片背景；时分秒之间使用英文冒号；时间格宽度约 20vw 并避免溢出屏幕"
}
```

嵌套标签示例：

```json
{
  "name": "personalRank",
  "enabled": true,
  "apis": [],
  "images": ["tagActiveBg", "tagBg"],
  "remark": "一级标签，图片为背景图，使用 itemCenter 居中展示英文标题文本，开发期间不加翻译",
  "children": {
    "tabs": {
      "enabled": true,
      "defaultValue": "Reward",
      "items": ["Reward", "Ranking"]
    },
    "sections": [
      {
        "name": "Reward",
        "enabled": true,
        "apis": [],
        "images": ["moduleActiveBg", "moduleBg"],
        "remark": "二级奖励标签",
        "children": {}
      },
      {
        "name": "Ranking",
        "enabled": true,
        "apis": [],
        "images": ["moduleActiveBg", "moduleBg"],
        "remark": "二级排行榜标签",
        "children": {}
      }
    ]
  }
}
```

### 4.3 弹窗模块

```json
[
  {
    "name": "rule",
    "triggerImage": "",
    "backgroundImage": "",
    "contentImage": "",
    "apis": [],
    "remark": "规则弹窗"
  },
  {
    "name": "history",
    "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": "",
  "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. 初版页面完成后检查什么

页面能打开
图片路径不 404
切语言时图片后缀符合预期
路由能进入
security 和 permissionManager 已补
排行榜能首屏展示
上拉加载策略正确：remote 请求下一页 / local slice 下一段
抽奖点击后有高亮转圈，并能停到中奖位置
弹窗能打开关闭
npm run build 通过

12 KiB Raw Blame History Unescape Escape

建页操作模板

1. 推荐操作流程

2. 填写规则

3. 专属页面信息 md 模板

4. 初版页面完成后检查什么

12 KiB

Raw Blame History