chore(建页方案): 文件结构调整，内容更新
This commit is contained in:
hzj
parent
92e3e59ee4
commit
da33832cb2
9
docs/活动页/README.md
Normal file
9
docs/活动页/README.md
Normal file
@ -0,0 +1,9 @@
|
|||||||
|
# 活动页文档索引
|
||||||
|
|
||||||
|
`docs/活动页` 已按用途拆分，后续联系文档时优先读取对应子目录，避免把所有 md 一次性读入。
|
||||||
|
|
||||||
|
- `建页/`：活动页/排行榜页的新建页面流程、操作模板、组件资料库和建页总览。更新页面、新建页面、补模块时优先联系这里。
|
||||||
|
- `创建记录/`：具体页面的历史创建记录，只在追溯某个旧页面做法时读取。
|
||||||
|
- `分析/`：性能分析、竞品调研和优化记录，只在做性能或调研任务时读取。
|
||||||
|
|
||||||
|
页面目录下的 `页面创建信息.md` 是单个页面的需求和同步记录；页面改动时，应同时联系本页 `页面创建信息.md` 与 `docs/活动页/建页/` 下的建页规则。
|
||||||
@ -262,7 +262,7 @@ useActivityRanking
|
|||||||
3. 再让 Codex 按该 md 继续生成 index.vue 初版页面。
|
3. 再让 Codex 按该 md 继续生成 index.vue 初版页面。
|
||||||
```
|
```
|
||||||
|
|
||||||
最新规则以 [建页执行流程.md](./建页执行流程.md) 为准，组件和配置片段以 [建页资料库.md](./建页资料库.md) 为准。
|
最新规则以 [建页执行流程.md](../建页/建页执行流程.md) 为准，组件和配置片段以 [建页资料库.md](../建页/建页资料库.md) 为准。
|
||||||
|
|
||||||
## 15. 本地图片 404 处理记录
|
## 15. 本地图片 404 处理记录
|
||||||
|
|
||||||
@ -20,7 +20,8 @@
|
|||||||
2. 创建页面目录。
|
2. 创建页面目录。
|
||||||
3. 在页面目录下创建专属页面信息 md，优先命名为 `页面创建信息.md`。
|
3. 在页面目录下创建专属页面信息 md，优先命名为 `页面创建信息.md`。
|
||||||
- 示例：`src/views/Activities/LuckyDollars/Season7/页面创建信息.md`
|
- 示例：`src/views/Activities/LuckyDollars/Season7/页面创建信息.md`
|
||||||
- 如果页面目录不适合存放，再放到 `docs/活动页/` 下。
|
- 如果页面目录不适合存放，再放到 `docs/活动页/页面信息/` 下。
|
||||||
|
- 新建 `页面创建信息.md` 时必须加入“建页规则关联”说明：页面改动、模块补充、接口对接和样式同步都要联系 `docs/活动页/建页/` 下的建页规则执行。
|
||||||
4. 以专属页面信息 md 为源创建 `page.config.js` 初始配置，只写可从页面信息和图片清单推断出的字段。
|
4. 以专属页面信息 md 为源创建 `page.config.js` 初始配置，只写可从页面信息和图片清单推断出的字段。
|
||||||
5. 预填页面类型、页面名称、页面目录、route path、route name、OSS 相对路径、本地开发目录。
|
5. 预填页面类型、页面名称、页面目录、route path、route name、OSS 相对路径、本地开发目录。
|
||||||
6. route path 和 route name 根据页面类型、页面名称、页面目录自动生成；用户后续可以自行修改。
|
6. route path 和 route name 根据页面类型、页面名称、页面目录自动生成；用户后续可以自行修改。
|
||||||
@ -83,7 +84,7 @@ scanDir = 专属 md 中的本地开发目录
|
|||||||
如果只有 rankBt_ar.png 且没有 rankBt.png，也生成 rankBt: ar，并在备注里标记缺少原图。
|
如果只有 rankBt_ar.png 且没有 rankBt.png，也生成 rankBt: ar，并在备注里标记缺少原图。
|
||||||
默认支持 ar、bn、tr；遇到其它形如 _xx 的语言后缀时也保留，但生成页面时需要确认是否接入。
|
默认支持 ar、bn、tr；遇到其它形如 _xx 的语言后缀时也保留，但生成页面时需要确认是否接入。
|
||||||
生成 3.1 图片清单时，按图片名首字母排序，排序忽略大小写。
|
生成 3.1 图片清单时，按图片名首字母排序，排序忽略大小写。
|
||||||
专属 md 的 3.1 展示扫描结果；备注优先匹配 docs/活动页/建页资料库.md 中的常用图片中文用途。
|
专属 md 的 3.1 展示扫描结果；备注优先匹配 docs/活动页/建页/建页资料库.md 中的常用图片中文用途。
|
||||||
能匹配到常用名时不要写“扫描生成”，例如 bg0 写“页面背景第 0 段”，rankBt 写“排行榜按钮”。
|
能匹配到常用名时不要写“扫描生成”，例如 bg0 写“页面背景第 0 段”，rankBt 写“排行榜按钮”。
|
||||||
匹配不到常用名时，根据图片名语义推断中文用途；用户的图片名通常按功能命名，例如 taskTalk 可写“聊天任务图标”，RewardRecharge500 可写“充值 500 奖励图”。
|
匹配不到常用名时，根据图片名语义推断中文用途；用户的图片名通常按功能命名，例如 taskTalk 可写“聊天任务图标”，RewardRecharge500 可写“充值 500 奖励图”。
|
||||||
rankingTopBg 统一解释为“排行榜前几名展示区背景”；历史 topBg 也按该含义解释，不要写成“顶部区域背景”。
|
rankingTopBg 统一解释为“排行榜前几名展示区背景”；历史 topBg 也按该含义解释，不要写成“顶部区域背景”。
|
||||||
@ -100,8 +101,8 @@ rankingTopBg 统一解释为“排行榜前几名展示区背景”；历史 top
|
|||||||
```text
|
```text
|
||||||
1. 读取专属页面信息 md。
|
1. 读取专属页面信息 md。
|
||||||
2. 读取同目录的 `page.config.js`；如果还不存在，则根据专属 md 创建。
|
2. 读取同目录的 `page.config.js`；如果还不存在，则根据专属 md 创建。
|
||||||
3. 读取 docs/活动页/建页操作模板.md。
|
3. 读取 docs/活动页/建页/建页操作模板.md。
|
||||||
4. 读取 docs/活动页/建页资料库.md。
|
4. 读取 docs/活动页/建页/建页资料库.md。
|
||||||
5. 如果有参考页面，只读取可复用的基础结构和组件用法，不复制业务模块。
|
5. 如果有参考页面，只读取可复用的基础结构和组件用法，不复制业务模块。
|
||||||
6. 只处理专属 md 中已填写的信息，未填写项跳过。
|
6. 只处理专属 md 中已填写的信息，未填写项跳过。
|
||||||
7. 以专属页面信息 md 为唯一生成源，同步更新 page.config.js，把已填写的活动字段、预加载、tabs、sections、children、popups、features 写入配置。
|
7. 以专属页面信息 md 为唯一生成源，同步更新 page.config.js，把已填写的活动字段、预加载、tabs、sections、children、popups、features 写入配置。
|
||||||
@ -144,6 +145,7 @@ page.config.js 是 md 的结构化落地结果，不能脱离 md 自行新增业
|
|||||||
可预览底座只包含预加载、组件引用、图片工具、背景、基础顶部、标签容器和空内容占位，方便用户实时预览页面效果。
|
可预览底座只包含预加载、组件引用、图片工具、背景、基础顶部、标签容器和空内容占位，方便用户实时预览页面效果。
|
||||||
新建页面只要生成 `index.vue`，必须补充统一加载动画：模板首层使用 `v-if="isLoading"` 展示居中的 `LoadingContent`，主页面内容使用 `v-else`，避免加载阶段提前挂载背景图和业务节点。`isLoading` 默认为 `true`，进入页面时至少执行一次 `completePreloading()`；即使 blocking 预加载列表为空，也要通过 `finally` 关闭 loading，防止页面卡死。
|
新建页面只要生成 `index.vue`，必须补充统一加载动画：模板首层使用 `v-if="isLoading"` 展示居中的 `LoadingContent`，主页面内容使用 `v-else`，避免加载阶段提前挂载背景图和业务节点。`isLoading` 默认为 `true`，进入页面时至少执行一次 `completePreloading()`；即使 blocking 预加载列表为空，也要通过 `finally` 关闭 loading，防止页面卡死。
|
||||||
业务模块不得一次性全部生成；抽奖、任务、排行榜、奖励、弹窗、接口对接都要等用户明确说生成哪一块再做。
|
业务模块不得一次性全部生成；抽奖、任务、排行榜、奖励、弹窗、接口对接都要等用户明确说生成哪一块再做。
|
||||||
|
页面中的规则、奖励、历史、结果等弹窗模块必须统一使用公共组件 `src/components/MaskLayer.vue` 作为遮罩层和背景滚动锁定容器；弹窗内容放入默认插槽，需要点击遮罩空白关闭时，在插槽内再包一层全屏内容容器并使用 `@click.self` 关闭。
|
||||||
开发预览阶段，样式优先靠近结构：能直接用内联样式表达的固定不变、一次性布局尺寸、间距、定位，直接写在模板内联样式里，方便实时调整并减少不必要的 class 拆分；可复用样式、状态样式、伪类/媒体查询/RTL 规则、复杂模块样式仍使用 class。
|
开发预览阶段，样式优先靠近结构：能直接用内联样式表达的固定不变、一次性布局尺寸、间距、定位，直接写在模板内联样式里，方便实时调整并减少不必要的 class 拆分；可复用样式、状态样式、伪类/媒体查询/RTL 规则、复杂模块样式仍使用 class。
|
||||||
动态样式不要优先使用 `:style="{ ... }"` 对象写法；涉及状态切换、选中态、方向、显隐、尺寸变化等动态效果时优先切换 class。只有必须绑定运行时数值且不适合枚举成 class 时，才使用动态 style。
|
动态样式不要优先使用 `:style="{ ... }"` 对象写法；涉及状态切换、选中态、方向、显隐、尺寸变化等动态效果时优先切换 class。只有必须绑定运行时数值且不适合枚举成 class 时，才使用动态 style。
|
||||||
内联样式和 class 在普通静态场景下性能差异通常很小；需要避免的是大量节点重复生成动态 style 对象、频繁变更大段内联样式。开发结束或模块稳定后，再按复用性和可维护性统一抽成 class。
|
内联样式和 class 在普通静态场景下性能差异通常很小；需要避免的是大量节点重复生成动态 style 对象、频繁变更大段内联样式。开发结束或模块稳定后，再按复用性和可维护性统一抽成 class。
|
||||||
@ -318,6 +320,14 @@ assetPath: 'Ranking/PageName/'
|
|||||||
src/config/imageCacheVersion.js
|
src/config/imageCacheVersion.js
|
||||||
```
|
```
|
||||||
|
|
||||||
|
`v-smart-img` 使用规则：
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. `v-smart-img` 只用于项目自身静态图片，例如通过 `src/config/imagePaths.js` 中 `getPngUrl`、`getWebpUrl` 等方法，或活动页 `imageUrl`、`webpUrl` 等封装得到的图片地址。
|
||||||
|
2. 接口返回的远程图片链接、用户头像、礼物图标、奖励图标等网络图片，直接使用原生 `<img :src="接口字段">`，不要加 `v-smart-img`。
|
||||||
|
3. 判断不清图片来源时，按接口网络图处理，不加 `v-smart-img`，避免把外部图片误纳入本地静态图片缓存规则。
|
||||||
|
```
|
||||||
|
|
||||||
分阶段预加载实现规则：
|
分阶段预加载实现规则：
|
||||||
|
|
||||||
```text
|
```text
|
||||||
263
docs/活动页/建页/建页操作模板.md
Normal file
263
docs/活动页/建页/建页操作模板.md
Normal file
@ -0,0 +1,263 @@
|
|||||||
|
# 建页操作模板
|
||||||
|
|
||||||
|
这份文档用于活动页创建和后续迭代时对齐规则。页面目录里的 `页面创建信息.md` 是当前页面的需求源；通用规则变更先更新 `docs/活动页/建页/`，再同步到页面目录文档和 Vue 代码。
|
||||||
|
|
||||||
|
## 1. 推荐流程
|
||||||
|
|
||||||
|
第一次只需要告诉页面名和创建位置，例如：
|
||||||
|
|
||||||
|
```text
|
||||||
|
新建活动页：WorldCup
|
||||||
|
创建位置：src/views/Activities/WorldCup
|
||||||
|
```
|
||||||
|
|
||||||
|
Codex 会先做准备阶段：
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. 创建页面目录。
|
||||||
|
2. 在页面目录中创建 页面创建信息.md。
|
||||||
|
3. 根据 页面创建信息.md 创建 page.config.js 初始配置。
|
||||||
|
4. 按需要创建本地 OSS 图片目录。
|
||||||
|
5. 写入 route path、security 白名单和 permissionManager 页面列表。
|
||||||
|
6. 预填 route、OSS、图片清单、预加载和模块配置。
|
||||||
|
7. 不生成 index.vue，除非用户明确要求继续创建页面。
|
||||||
|
```
|
||||||
|
|
||||||
|
专属页面信息 md 优先放在页面目录里：
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/views/Activities/WorldCup/页面创建信息.md
|
||||||
|
```
|
||||||
|
|
||||||
|
后续用户逐步补充模块时，先同步页面 md，再同步 Vue；如果用户明确说“按当前 Vue 同步到 md”，则以 Vue 当前实现为准反向更新 md。
|
||||||
|
|
||||||
|
## 2. 通用建页规则
|
||||||
|
|
||||||
|
- 没填的字段，初版页面先不猜。
|
||||||
|
- `页面创建信息.md` 是 `page.config.js` 和 `index.vue` 的生成来源；后续补需求先改 md，再同步代码。
|
||||||
|
- 每轮可以指定同步方向：`md -> vue` 或 `vue -> md`；方向不明确且两边冲突时，先确认再改。
|
||||||
|
- 新建页面只要生成 `index.vue`，都必须带统一加载动画：先展示 `LoadingContent`，关键图片和初始化完成后再展示正式页面。
|
||||||
|
- 页面根容器推荐固定 `height: 100vh`、`overflow: hidden`，内部主内容容器负责 `overflow-y: auto` 垂直滚动并隐藏滚动条。
|
||||||
|
- 页面任何模块都不要出现可见滚动条。
|
||||||
|
- 页面模块布局可以使用 flex column，模块间距按需求设置，常见活动页默认可用 `gap: 2vw`。
|
||||||
|
- 能用内联样式直接表达的固定布局、尺寸、间距、定位，优先使用内联样式，方便实时调位置。
|
||||||
|
- 可复用样式、伪类、媒体查询、RTL 规则和复杂状态样式可以写 class。
|
||||||
|
- 动态选中态、显隐和尺寸变化可以使用方法返回内联 style 字符串；如果复用明显，再抽 class。
|
||||||
|
- 使用 `itemCenter` 承载图片背景时，要按图片比例补 `min-height`，避免图片未加载时内部内容挤在一起。
|
||||||
|
- `itemCenter` 承载大背景图时，宽度优先写 `100vw`，父级从上往下 flex 排列。
|
||||||
|
- `v-smart-img` 只用于项目自身静态图片，例如通过 `src/config/imagePaths.js` 中 `getPngUrl`、`getWebpUrl` 等方法，或活动页 `imageUrl`、`webpUrl` 等封装得到的图片地址。
|
||||||
|
- 接口返回的远程图片链接不要使用 `v-smart-img`，直接用原生 `<img :src="接口字段">` 展示，不走本地图片缓存或智能图片指令。
|
||||||
|
- 页面展示字号默认使用 `font-size: 1em`，跟随页面响应式基础字号变化。
|
||||||
|
- 页面后续更新模块、接口或方法时，新增或调整的方法和关键模块逻辑都要添加简短中文注释。
|
||||||
|
- 模板里的主要 `div`、`section`、`itemCenter` 等结构模块也要补中文注释，说明当前块负责的视觉区域或业务含义。
|
||||||
|
- 对接 POST 接口时，如果接口没有业务参数，也必须传空对象 `{}`，不要省略 body。
|
||||||
|
- 多 tab 或多分类列表不要共用同一个承载数组；每个 tab 使用独立数据源，避免接口慢返回或快速切换时数据混用。
|
||||||
|
- 多 tab 列表请求建议使用每个 tab 独立的请求序号或 token，只忽略同 tab 内更旧的响应，不影响其他 tab 的缓存。
|
||||||
|
- 弹窗统一使用公共组件 `src/components/MaskLayer.vue`。规则、奖励、历史、结果等弹窗内容放在 `MaskLayer` 默认插槽内；需要点击空白关闭时，在插槽内包一层全屏容器并使用 `@click.self` 关闭。
|
||||||
|
|
||||||
|
## 3. 页面信息 md 模板
|
||||||
|
|
||||||
|
````md
|
||||||
|
# 页面创建信息
|
||||||
|
|
||||||
|
## 0. 建页规则关联
|
||||||
|
|
||||||
|
- 页面改动、模块补充、接口对接、样式同步和文档同步，都需要先联系 `docs/活动页/建页/` 下的建页规则执行。
|
||||||
|
- 如果建页规则变化，先更新 `docs/活动页/建页/` 下的建页 md，再同步当前页面的 `页面创建信息.md` 和 Vue 代码。
|
||||||
|
|
||||||
|
## 1. 基础信息
|
||||||
|
|
||||||
|
- 页面类型：Activities / Ranking
|
||||||
|
- 页面名称：
|
||||||
|
- 页面目录：
|
||||||
|
- 页面入口：
|
||||||
|
- 页面配置：
|
||||||
|
- 专用接口：
|
||||||
|
- 参考页面：
|
||||||
|
- 备注：
|
||||||
|
|
||||||
|
## 2. 路由和权限
|
||||||
|
|
||||||
|
- route path：
|
||||||
|
- route name：
|
||||||
|
- 是否需要登录：是 / 否
|
||||||
|
- 是否加入 `src/config/security.js`：是 / 否
|
||||||
|
- 是否加入 `src/utils/permissionManager.js`：是 / 否
|
||||||
|
|
||||||
|
### 2.1 路由代码片段
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 由 Codex 按 route path、route name 和页面目录生成
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. OSS 图片目录
|
||||||
|
|
||||||
|
- OSS 相对路径：
|
||||||
|
- 本地开发目录：
|
||||||
|
- 是否需要 Codex 自动创建本地开发目录：是 / 否
|
||||||
|
- 图片是否已放入本地目录：是 / 否
|
||||||
|
|
||||||
|
说明：本地 OSS 图片目录只作为开发期图片镜像使用，发布时图片由用户上传到真实 OSS；目录内图片和空目录占位文件不作为 Git 提交内容。
|
||||||
|
|
||||||
|
### 3.1 图片清单
|
||||||
|
|
||||||
|
| 图片名 | 支持语言 | 备注 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| | 默认 | |
|
||||||
|
|
||||||
|
### 3.2 阻塞预加载图片
|
||||||
|
|
||||||
|
| 图片名 | 是否包含多语言 | 备注 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| | 否 | |
|
||||||
|
|
||||||
|
### 3.3 后台预加载图片
|
||||||
|
|
||||||
|
| 图片名 | 是否包含多语言 | 备注 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| | 否 | |
|
||||||
|
|
||||||
|
## 4. 模块配置
|
||||||
|
|
||||||
|
没有填写的模块，初版页面先不处理。
|
||||||
|
|
||||||
|
### 4.1 标签页模块
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"enabled": false,
|
||||||
|
"defaultValue": "",
|
||||||
|
"items": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 页面区块模块
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "header",
|
||||||
|
"enabled": true,
|
||||||
|
"apis": [],
|
||||||
|
"images": [],
|
||||||
|
"remark": "头部模块",
|
||||||
|
"children": {}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "ranking",
|
||||||
|
"enabled": false,
|
||||||
|
"apis": [],
|
||||||
|
"images": [],
|
||||||
|
"remark": "排行榜模块",
|
||||||
|
"children": {}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "reward",
|
||||||
|
"enabled": false,
|
||||||
|
"apis": [],
|
||||||
|
"images": [],
|
||||||
|
"remark": "奖励模块",
|
||||||
|
"children": {}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "task",
|
||||||
|
"enabled": false,
|
||||||
|
"apis": [],
|
||||||
|
"images": [],
|
||||||
|
"remark": "任务模块",
|
||||||
|
"children": {}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 弹窗模块
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "rule",
|
||||||
|
"enabled": false,
|
||||||
|
"triggerImage": "",
|
||||||
|
"backgroundImage": "",
|
||||||
|
"component": "src/components/MaskLayer.vue",
|
||||||
|
"remark": "规则弹窗"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "reward",
|
||||||
|
"enabled": false,
|
||||||
|
"triggerImage": "",
|
||||||
|
"backgroundImage": "",
|
||||||
|
"component": "src/components/MaskLayer.vue",
|
||||||
|
"remark": "奖励弹窗"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. 接口参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"activityId": "",
|
||||||
|
"activityCode": "",
|
||||||
|
"activityType": "",
|
||||||
|
"rankingActivityType": "",
|
||||||
|
"rewardActivityType": "",
|
||||||
|
"otherParams": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. 组件需求
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "itemCenter",
|
||||||
|
"enabled": "",
|
||||||
|
"remark": "图片背景容器"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "TopUser",
|
||||||
|
"enabled": "",
|
||||||
|
"remark": "前三名用户展示"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "MaskLayer",
|
||||||
|
"enabled": "",
|
||||||
|
"remark": "公共弹窗遮罩"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7. 建页后记录
|
||||||
|
|
||||||
|
### 7.1 已完成
|
||||||
|
|
||||||
|
-
|
||||||
|
|
||||||
|
### 7.2 后续补充
|
||||||
|
|
||||||
|
-
|
||||||
|
|
||||||
|
### 7.3 待微调
|
||||||
|
|
||||||
|
-
|
||||||
|
|
||||||
|
### 7.4 验证结果
|
||||||
|
|
||||||
|
- `npm run build`：
|
||||||
|
- 备注：
|
||||||
|
````
|
||||||
|
|
||||||
|
## 4. 初版页面完成后检查
|
||||||
|
|
||||||
|
```text
|
||||||
|
页面能打开
|
||||||
|
图片路径无 404
|
||||||
|
路由能进入
|
||||||
|
security 和 permissionManager 已补
|
||||||
|
LoadingContent 展示和关闭正常
|
||||||
|
页面内部滚动正常且无可见滚动条
|
||||||
|
弹窗能打开和关闭
|
||||||
|
多 tab 列表数据不混用
|
||||||
|
npm run build 通过
|
||||||
|
```
|
||||||
@ -248,6 +248,19 @@ imageUrl('taskTypeGift') // 礼物任务类型图标
|
|||||||
|
|
||||||
### 2.7 弹窗、规则、帮助和历史
|
### 2.7 弹窗、规则、帮助和历史
|
||||||
|
|
||||||
|
弹窗遮罩统一使用公共组件 `src/components/MaskLayer.vue`，不要在页面里重复手写固定定位遮罩、背景滚动锁定和滚动阻止逻辑。弹窗内容放入默认插槽；如果要点击空白关闭，在插槽内包一层全屏容器并绑定 `@click.self`。
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<MaskLayer :maskLayerShow="showPopup">
|
||||||
|
<div
|
||||||
|
style="width: 100vw; min-height: 100vh; display: flex; align-items: flex-start; justify-content: center; padding: 6vh 0 10vh; box-sizing: border-box;"
|
||||||
|
@click.self="showPopup = false"
|
||||||
|
>
|
||||||
|
<!-- 弹窗内容模块：使用 itemCenter 或普通 div 承载弹窗背景和内容 -->
|
||||||
|
</div>
|
||||||
|
</MaskLayer>
|
||||||
|
```
|
||||||
|
|
||||||
```js
|
```js
|
||||||
imageUrl(getImgName('helpInfo')) // 帮助说明图片
|
imageUrl(getImgName('helpInfo')) // 帮助说明图片
|
||||||
imageUrl('helpBg') // 帮助弹窗背景
|
imageUrl('helpBg') // 帮助弹窗背景
|
||||||
@ -1,457 +0,0 @@
|
|||||||
# 建页操作模板
|
|
||||||
|
|
||||||
这份文档只给用户看：告诉你第一次怎么提需求，以及专属 `页面创建信息.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 通过
|
|
||||||
```
|
|
||||||
Loading…
x
Reference in New Issue
Block a user