From da33832cb294717ba566249d5b0f2268d55b3ae0 Mon Sep 17 00:00:00 2001 From: hzj <1304805162@qq.com> Date: Fri, 5 Jun 2026 20:59:35 +0800 Subject: [PATCH] =?UTF-8?q?chore(=E5=BB=BA=E9=A1=B5=E6=96=B9=E6=A1=88):=20?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E7=BB=93=E6=9E=84=E8=B0=83=E6=95=B4=EF=BC=8C?= =?UTF-8?q?=E5=86=85=E5=AE=B9=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/活动页/README.md | 9 + .../活动页/{ => 分析}/竞品H5与性能优化分析.md | 0 .../{ => 创建记录}/幸运美金第6季创建记录.md | 2 +- docs/活动页/{ => 建页}/建页执行流程.md | 18 +- docs/活动页/建页/建页操作模板.md | 263 ++++++++++ docs/活动页/{ => 建页}/建页资料库.md | 13 + docs/活动页/{ => 建页}/快速建立活动页方案.md | 0 docs/活动页/建页操作模板.md | 457 ------------------ 8 files changed, 300 insertions(+), 462 deletions(-) create mode 100644 docs/活动页/README.md rename docs/活动页/{ => 分析}/竞品H5与性能优化分析.md (100%) rename docs/活动页/{ => 创建记录}/幸运美金第6季创建记录.md (97%) rename docs/活动页/{ => 建页}/建页执行流程.md (93%) create mode 100644 docs/活动页/建页/建页操作模板.md rename docs/活动页/{ => 建页}/建页资料库.md (96%) rename docs/活动页/{ => 建页}/快速建立活动页方案.md (100%) delete mode 100644 docs/活动页/建页操作模板.md 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 文件统一使用 `