diff --git a/docs/活动页/README.md b/docs/活动页/README.md
new file mode 100644
index 0000000..cd99110
--- /dev/null
+++ b/docs/活动页/README.md
@@ -0,0 +1,9 @@
+# 活动页文档索引
+
+`docs/活动页` 已按用途拆分,后续联系文档时优先读取对应子目录,避免把所有 md 一次性读入。
+
+- `建页/`:活动页/排行榜页的新建页面流程、操作模板、组件资料库和建页总览。更新页面、新建页面、补模块时优先联系这里。
+- `创建记录/`:具体页面的历史创建记录,只在追溯某个旧页面做法时读取。
+- `分析/`:性能分析、竞品调研和优化记录,只在做性能或调研任务时读取。
+
+页面目录下的 `页面创建信息.md` 是单个页面的需求和同步记录;页面改动时,应同时联系本页 `页面创建信息.md` 与 `docs/活动页/建页/` 下的建页规则。
diff --git a/docs/活动页/竞品H5与性能优化分析.md b/docs/活动页/分析/竞品H5与性能优化分析.md
similarity index 100%
rename from docs/活动页/竞品H5与性能优化分析.md
rename to docs/活动页/分析/竞品H5与性能优化分析.md
diff --git a/docs/活动页/幸运美金第6季创建记录.md b/docs/活动页/创建记录/幸运美金第6季创建记录.md
similarity index 97%
rename from docs/活动页/幸运美金第6季创建记录.md
rename to docs/活动页/创建记录/幸运美金第6季创建记录.md
index 1b73eac..c7e58ff 100644
--- a/docs/活动页/幸运美金第6季创建记录.md
+++ b/docs/活动页/创建记录/幸运美金第6季创建记录.md
@@ -262,7 +262,7 @@ useActivityRanking
3. 再让 Codex 按该 md 继续生成 index.vue 初版页面。
```
-最新规则以 [建页执行流程.md](./建页执行流程.md) 为准,组件和配置片段以 [建页资料库.md](./建页资料库.md) 为准。
+最新规则以 [建页执行流程.md](../建页/建页执行流程.md) 为准,组件和配置片段以 [建页资料库.md](../建页/建页资料库.md) 为准。
## 15. 本地图片 404 处理记录
diff --git a/docs/活动页/建页执行流程.md b/docs/活动页/建页/建页执行流程.md
similarity index 93%
rename from docs/活动页/建页执行流程.md
rename to docs/活动页/建页/建页执行流程.md
index d87503a..5d66884 100644
--- a/docs/活动页/建页执行流程.md
+++ b/docs/活动页/建页/建页执行流程.md
@@ -20,7 +20,8 @@
2. 创建页面目录。
3. 在页面目录下创建专属页面信息 md,优先命名为 `页面创建信息.md`。
- 示例:`src/views/Activities/LuckyDollars/Season7/页面创建信息.md`
- - 如果页面目录不适合存放,再放到 `docs/活动页/` 下。
+ - 如果页面目录不适合存放,再放到 `docs/活动页/页面信息/` 下。
+ - 新建 `页面创建信息.md` 时必须加入“建页规则关联”说明:页面改动、模块补充、接口对接和样式同步都要联系 `docs/活动页/建页/` 下的建页规则执行。
4. 以专属页面信息 md 为源创建 `page.config.js` 初始配置,只写可从页面信息和图片清单推断出的字段。
5. 预填页面类型、页面名称、页面目录、route path、route name、OSS 相对路径、本地开发目录。
6. route path 和 route name 根据页面类型、页面名称、页面目录自动生成;用户后续可以自行修改。
@@ -83,7 +84,7 @@ scanDir = 专属 md 中的本地开发目录
如果只有 rankBt_ar.png 且没有 rankBt.png,也生成 rankBt: ar,并在备注里标记缺少原图。
默认支持 ar、bn、tr;遇到其它形如 _xx 的语言后缀时也保留,但生成页面时需要确认是否接入。
生成 3.1 图片清单时,按图片名首字母排序,排序忽略大小写。
-专属 md 的 3.1 展示扫描结果;备注优先匹配 docs/活动页/建页资料库.md 中的常用图片中文用途。
+专属 md 的 3.1 展示扫描结果;备注优先匹配 docs/活动页/建页/建页资料库.md 中的常用图片中文用途。
能匹配到常用名时不要写“扫描生成”,例如 bg0 写“页面背景第 0 段”,rankBt 写“排行榜按钮”。
匹配不到常用名时,根据图片名语义推断中文用途;用户的图片名通常按功能命名,例如 taskTalk 可写“聊天任务图标”,RewardRecharge500 可写“充值 500 奖励图”。
rankingTopBg 统一解释为“排行榜前几名展示区背景”;历史 topBg 也按该含义解释,不要写成“顶部区域背景”。
@@ -100,8 +101,8 @@ rankingTopBg 统一解释为“排行榜前几名展示区背景”;历史 top
```text
1. 读取专属页面信息 md。
2. 读取同目录的 `page.config.js`;如果还不存在,则根据专属 md 创建。
-3. 读取 docs/活动页/建页操作模板.md。
-4. 读取 docs/活动页/建页资料库.md。
+3. 读取 docs/活动页/建页/建页操作模板.md。
+4. 读取 docs/活动页/建页/建页资料库.md。
5. 如果有参考页面,只读取可复用的基础结构和组件用法,不复制业务模块。
6. 只处理专属 md 中已填写的信息,未填写项跳过。
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,防止页面卡死。
业务模块不得一次性全部生成;抽奖、任务、排行榜、奖励、弹窗、接口对接都要等用户明确说生成哪一块再做。
+页面中的规则、奖励、历史、结果等弹窗模块必须统一使用公共组件 `src/components/MaskLayer.vue` 作为遮罩层和背景滚动锁定容器;弹窗内容放入默认插槽,需要点击遮罩空白关闭时,在插槽内再包一层全屏内容容器并使用 `@click.self` 关闭。
开发预览阶段,样式优先靠近结构:能直接用内联样式表达的固定不变、一次性布局尺寸、间距、定位,直接写在模板内联样式里,方便实时调整并减少不必要的 class 拆分;可复用样式、状态样式、伪类/媒体查询/RTL 规则、复杂模块样式仍使用 class。
动态样式不要优先使用 `:style="{ ... }"` 对象写法;涉及状态切换、选中态、方向、显隐、尺寸变化等动态效果时优先切换 class。只有必须绑定运行时数值且不适合枚举成 class 时,才使用动态 style。
内联样式和 class 在普通静态场景下性能差异通常很小;需要避免的是大量节点重复生成动态 style 对象、频繁变更大段内联样式。开发结束或模块稳定后,再按复用性和可维护性统一抽成 class。
@@ -318,6 +320,14 @@ assetPath: 'Ranking/PageName/'
src/config/imageCacheVersion.js
```
+`v-smart-img` 使用规则:
+
+```text
+1. `v-smart-img` 只用于项目自身静态图片,例如通过 `src/config/imagePaths.js` 中 `getPngUrl`、`getWebpUrl` 等方法,或活动页 `imageUrl`、`webpUrl` 等封装得到的图片地址。
+2. 接口返回的远程图片链接、用户头像、礼物图标、奖励图标等网络图片,直接使用原生 `
`,不要加 `v-smart-img`。
+3. 判断不清图片来源时,按接口网络图处理,不加 `v-smart-img`,避免把外部图片误纳入本地静态图片缓存规则。
+```
+
分阶段预加载实现规则:
```text
diff --git a/docs/活动页/建页/建页操作模板.md b/docs/活动页/建页/建页操作模板.md
new file mode 100644
index 0000000..5b58907
--- /dev/null
+++ b/docs/活动页/建页/建页操作模板.md
@@ -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`,直接用原生 `
` 展示,不走本地图片缓存或智能图片指令。
+- 页面展示字号默认使用 `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 通过
+```
diff --git a/docs/活动页/建页资料库.md b/docs/活动页/建页/建页资料库.md
similarity index 96%
rename from docs/活动页/建页资料库.md
rename to docs/活动页/建页/建页资料库.md
index c622cb0..328cfe3 100644
--- a/docs/活动页/建页资料库.md
+++ b/docs/活动页/建页/建页资料库.md
@@ -248,6 +248,19 @@ imageUrl('taskTypeGift') // 礼物任务类型图标
### 2.7 弹窗、规则、帮助和历史
+弹窗遮罩统一使用公共组件 `src/components/MaskLayer.vue`,不要在页面里重复手写固定定位遮罩、背景滚动锁定和滚动阻止逻辑。弹窗内容放入默认插槽;如果要点击空白关闭,在插槽内包一层全屏容器并绑定 `@click.self`。
+
+```vue
+
+
+
+
+
+```
+
```js
imageUrl(getImgName('helpInfo')) // 帮助说明图片
imageUrl('helpBg') // 帮助弹窗背景
diff --git a/docs/活动页/快速建立活动页方案.md b/docs/活动页/建页/快速建立活动页方案.md
similarity index 100%
rename from docs/活动页/快速建立活动页方案.md
rename to docs/活动页/建页/快速建立活动页方案.md
diff --git a/docs/活动页/建页操作模板.md b/docs/活动页/建页操作模板.md
deleted file mode 100644
index 2f68c1f..0000000
--- a/docs/活动页/建页操作模板.md
+++ /dev/null
@@ -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 文件统一使用 `