建页操作模板

这份文档用于活动页创建和后续迭代时对齐规则。页面目录里的 页面创建信息.md 是当前页面的需求源；通用规则变更先更新 docs/活动页/建页/，再同步到页面目录文档和 Vue 代码。

1. 推荐流程

第一次只需要告诉页面名和创建位置，例如：

新建活动页：WorldCup
创建位置：src/views/Activities/WorldCup

Codex 会先做准备阶段：

1. 创建页面目录。
2. 在页面目录中创建 页面创建信息.md。
3. 根据 页面创建信息.md 创建 page.config.js 初始配置。
4. 按需要创建本地 OSS 图片目录。
5. 写入 route path、security 白名单和 permissionManager 页面列表。
6. 预填 route、OSS、图片清单、预加载和模块配置。
7. 不生成 index.vue，除非用户明确要求继续创建页面。

专属页面信息 md 优先放在页面目录里：

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 模板

# 页面创建信息

## 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. 初版页面完成后检查

页面能打开
图片路径无 404
路由能进入
security 和 permissionManager 已补
LoadingContent 展示和关闭正常
页面内部滚动正常且无可见滚动条
弹窗能打开和关闭
多 tab 列表数据不混用
npm run build 通过

7.4 KiB Raw Blame History Unescape Escape

建页操作模板

1. 推荐流程

2. 通用建页规则

3. 页面信息 md 模板

4. 初版页面完成后检查

7.4 KiB

Raw Blame History