224 lines
8.2 KiB
Markdown
224 lines
8.2 KiB
Markdown
# 建页执行流程
|
||
|
||
这份文档给 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：
|
||
```
|