# 建页执行流程

这份文档给 Codex 执行用。用户不需要阅读这里，用户只需要按 [建页操作模板.md](./建页操作模板.md) 操作。

## 1. 用户只给页面名称和创建位置时

当用户只提供类似信息：

```text
页面名称：LuckyDollars Season7
创建位置：src/views/Activities/LuckyDollars/Season7
```

只执行以下步骤：

```text
1. 根据路径判断页面类型：
   - src/views/Activities 下为 Activities
   - src/views/Ranking 下为 Ranking
2. 在 docs/活动页/ 下创建专属页面信息 md。
3. md 文件名使用中文或页面名，例如 LuckyDollars-Season7-创建信息.md。
4. 预填页面类型、页面名称、页面目录、route path、route name、OSS 相对路径、本地开发目录。
5. route path 和 route name 根据页面类型、页面名称、页面目录自动生成；用户后续可以自行修改。
6. 安全白名单片段和权限页面片段也使用 route path 自动生成，不留空。
7. OSS 相对路径和本地开发目录根据页面类型和页面目录自动生成；用户后续可以自行修改。
8. 如果本地开发目录已存在且里面有图片，扫描图片文件并预填 3.1 多语言图片清单。
9. 根据页面类型、3.1 图片清单和模块预设，自动预填 3.2、3.3、4.x 模块配置。
10. 只把无法推断或风险较高的字段留空，并在备注中说明需要用户确认。
11. 本轮不创建页面代码，除非用户明确要求继续创建页面。
```

路由自动生成规则：

```text
Activities 页面：
src/views/Activities/LuckyDollars/Season6
-> route path: /activities/lucky-dollars-season6
-> route name: lucky-dollars-season6

Ranking 页面：
src/views/Ranking/OverallSeason2
-> route path: /ranking/overall-season2
-> route name: overall-season2
```

安全白名单和权限页面片段生成规则：

```text
src/config/security.js：使用 route path。
src/utils/permissionManager.js：使用 route path，后面注释使用页面名称。
```

OSS 路径生成规则：

```text
Activities 页面：
src/views/Activities/LuckyDollars/Season6
-> OSS 相对路径: Activities/LuckyDollars/Season6/
-> 本地开发目录: public/oss/h5/Azizi/Activities/LuckyDollars/Season6/

Ranking 页面：
src/views/Ranking/OverallSeason2
-> OSS 相对路径: Ranking/OverallSeason2/
-> 本地开发目录: public/oss/h5/Azizi/Ranking/OverallSeason2/
```

多语言图片自动扫描规则：

```text
scanDir = 专属 md 中的本地开发目录
只扫描常见图片扩展名：png、jpg、jpeg、webp、gif、svg。
忽略 .gitkeep 等非图片文件。
文件名不带语言后缀时，记为 en 原图，例如 bg0.png -> bg0: en。
文件名带 _ar、_bn、_tr 等语言后缀时，按基础名合并，例如 rankBt.png + rankBt_ar.png -> rankBt: en, ar。
如果只有 rankBt_ar.png 且没有 rankBt.png，也生成 rankBt: ar，并在备注里标记缺少原图。
默认支持 ar、bn、tr；遇到其它形如 _xx 的语言后缀时也保留，但生成页面时需要确认是否接入。
生成 3.1 图片清单时，按图片名首字母排序，排序忽略大小写。
专属 md 的 3.1 展示扫描结果；备注优先匹配 docs/活动页/建页资料库.md 中的常用图片中文用途。
能匹配到常用名时不要写“扫描生成”，例如 bg0 写“页面背景第 0 段”，rankBt 写“排行榜按钮”。
匹配不到常用名时，根据图片名语义推断中文用途；用户的图片名通常按功能命名，例如 taskTalk 可写“聊天任务图标”，RewardRecharge500 可写“充值 500 奖励图”。
rankingTopBg 统一解释为“排行榜前几名展示区背景”；历史 topBg 也按该含义解释，不要写成“顶部区域背景”。
只有图片名完全看不出功能时，才备注“待确认用途”，方便用户回头改。
不再要求用户填写“多语言图片规则”；生成页面时直接读取 3.1 中每张图片的支持语言。
3.2 和 3.3 默认按图片用途自动生成：首屏背景、默认标签页、顶部信息、默认模块放 blocking；弹窗、非默认标签页、抽奖结果、下方模块放 background。
```

## 2. 用户补完专属 md 并要求继续建页时

执行顺序：

```text
1. 读取专属页面信息 md。
2. 读取 docs/活动页/建页操作模板.md。
3. 读取 docs/活动页/建页资料库.md。
4. 如果有参考页面，读取参考页面结构和接口用法。
5. 只处理专属 md 中已填写的信息，未填写项跳过。
6. 创建页面目录。
7. 创建 page.config.js。
8. 创建或生成 index.vue 初版。
9. 如果专属 md 中“是否需要 Codex 自动创建本地开发目录”为“是”，创建 public/oss/h5/Azizi/... 本地图片目录。
10. 添加路由。
11. 补充 src/config/security.js。
12. 补充 src/utils/permissionManager.js。
13. 按需接入组件和 composable。
14. 运行 npm run build。
15. 把完成项、跳过项、待补项、验证结果写回专属 md。
```

## 3. 执行原则

```text
专属 md 没填的项，不猜。
专属 md 中需要用户填写的模块配置、接口参数、组件需求，优先使用 JSON 代码块，不使用 Markdown 表格。
扫描生成的图片清单和预加载清单可以保留 Markdown 表格，因为它们主要用于检查和排序。
模块图片优先从 3.1 图片清单中按图片名语义推断；推断不到时再参考建页资料库给默认名，并标记待确认。
模块预设里的图片名只有在 3.1 图片清单存在时才直接写入；不存在时留空，并在 remark 中写“本地图片清单未扫描到 xxx，待确认”。
常见模块接口优先走模块预设，不要求用户重复填写。
如果同一个模块在不同页面存在接口或字段差异，且没有提供参考页面，要先问用户参考哪个页面的模块。
参考页面只作为结构和接口参考，不把新页面当成复制旧页面。
新增 js/vue 文件尽量加中文注释。
docs 下文件和文件夹使用中文命名。
页面初版以能运行、结构清楚、方便微调为目标。
```

## 4. page.config.js 建议结构

新页面优先使用分组后的模块配置，不再使用单纯数组：

```js
export const pageConfig = {
  name: '',
  routePath: '',
  assetPath: '',

  activity: {
    activityId: '',
    activityCode: '',
    activityType: '',
    rankingActivityType: '',
    rewardActivityType: '',
  },

  modules: {
    tabs: [],
    sections: [],
    popups: [],
    features: [],
  },

  images: {
    localized: {},
  },
}
```

含义：

```text
tabs：标签页模块，如 reward、ranking、lottery、withdraw
sections：页面区块，如 task、badgeReward、myInfo
popups：弹窗，如 rule、help、history、result
features：功能能力，如 countdown、barrage、transfer、exchange
```

## 5. 路由和权限

每个新页面都要确认：

```text
src/router/index.js
src/config/security.js
src/utils/permissionManager.js
```

如果专属 md 中明确写“不需要”，才跳过。

## 6. 图片和缓存

开发期图片目录：

```text
public/oss/h5/Azizi/Activities/PageName/
public/oss/h5/Azizi/Ranking/PageName/
```

页面代码中仍使用 OSS 相对路径：

```js
assetPath: 'Activities/PageName/'
assetPath: 'Ranking/PageName/'
```

替换同名 OSS 图片时，需要提醒用户更新：

```text
src/config/imageCacheVersion.js
```

分阶段预加载实现规则：

```text
1. page.config.js 中保留两个列表：
   - preload.blocking：进入页面前同步预加载，参与加载动画。
   - preload.background：进入页面后后台预加载，不参与加载动画。
2. blocking 列表为空时，不强制等待图片，页面可直接进入。
3. background 列表为空时，不生成额外逻辑或生成 no-op 逻辑。
4. 两个列表都要走同一套 imageUrl/getImgName 规则，保证本地 OSS、线上 OSS、图片缓存和多语言后缀一致。
5. 后台预加载在 blocking 完成、页面可见后执行，优先使用 requestIdleCallback，兼容时用 setTimeout。
6. 后台预加载失败只记录日志，不影响页面展示和交互。
```

## 7. 完成后写回专属 md

建页完成后，在专属 md 的“建页后记录”中补充：

```text
已完成：
未填写所以跳过：
待用户微调：
构建结果：
本地图片目录：
路由 path：
```