458 lines
12 KiB
Markdown
458 lines
12 KiB
Markdown
# 建页操作模板
|
||
|
||
这份文档只给用户看：告诉你第一次怎么提需求，以及专属 `页面创建信息.md` 里需要填什么。
|
||
|
||
规则正文不在这里重复维护：
|
||
|
||
- 建页阶段、路由、OSS、多语言图片、预加载、`children` 嵌套规则：看 [建页执行流程.md](./建页执行流程.md)。
|
||
- 组件用法、常用图片名、模块预设、配置代码片段：看 [建页资料库.md](./建页资料库.md)。
|
||
|
||
## 1. 推荐操作流程
|
||
|
||
第一次只告诉我页面名称和创建位置：
|
||
|
||
```text
|
||
新建活动页：Gulben Festival
|
||
创建位置：src/views/Activities/GulbenFestival
|
||
```
|
||
|
||
或：
|
||
|
||
```text
|
||
新建排行榜页：Overall Season2
|
||
创建位置：src/views/Ranking/OverallSeason2
|
||
```
|
||
|
||
我会先做准备阶段：
|
||
|
||
```text
|
||
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 优先放在页面目录里：
|
||
|
||
```text
|
||
src/views/Activities/GulbenFestival/页面创建信息.md
|
||
```
|
||
|
||
你补完 md 中一部分信息后，可以先让我生成可预览底座：
|
||
|
||
```text
|
||
按 src/views/Activities/GulbenFestival/页面创建信息.md 生成可预览底座
|
||
```
|
||
|
||
我会以这份 md 为需求源同步 `page.config.js`，生成 `index.vue` 的 loading、预加载、组件引用、图片工具、页面背景、顶部基础区域、一级/二级 tabs 容器和空内容占位。
|
||
|
||
后续你再一步步告诉我：
|
||
|
||
```text
|
||
生成 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`。基础字段会先自动填好，图片和模块会尽量按扫描结果和预设补齐。
|
||
|
||
````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. 初版页面完成后检查什么
|
||
|
||
```text
|
||
页面能打开
|
||
图片路径不 404
|
||
切语言时图片后缀符合预期
|
||
路由能进入
|
||
security 和 permissionManager 已补
|
||
排行榜能首屏展示
|
||
上拉加载策略正确：remote 请求下一页 / local slice 下一段
|
||
抽奖点击后有高亮转圈，并能停到中奖位置
|
||
弹窗能打开关闭
|
||
npm run build 通过
|
||
```
|