# 建页操作模板

这份文档用于活动页创建和后续迭代时对齐规则。页面目录里的 `页面创建信息.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`，关键图片预加载完成后再展示正式页面；loading 只针对图片，不等待业务接口。
- 页面只要使用接口，就必须引入 `connectToApp` 并先完成 App 连接；初始化接口统一放在 `connectToApp(() => { loadInitialPageData() })` 成功回调后执行，确保请求头已设置。图片预加载方法和接口初始化方法必须分离。
- 页面根容器推荐固定 `height: 100vh`、`overflow: hidden`，内部主内容容器负责 `overflow-y: auto` 垂直滚动并隐藏滚动条。
- 页面任何模块都不要出现可见滚动条。
- 页面模块布局可以使用 flex column，模块间距按需求设置，常见活动页默认可用 `gap: 2vw`。
- 能用内联样式直接表达的固定布局、尺寸、间距、定位，优先使用内联样式，方便实时调位置。
- 可复用样式、伪类、媒体查询、RTL 规则和复杂状态样式可以写 class。
- 动态选中态、显隐和尺寸变化可以使用方法返回内联 style 字符串；如果复用明显，再抽 class。
- 普通业务模块一般不要提前设置 `min-height` 和 `line-height`；`min-height` 只在基础页面容器（如 `.full-page` / `.fullPage`）中按需使用，`itemCenter` 的 `min-height` 只在页面开发完成后确实需要稳定图片容器高度时再补；补充时同步设置接近的 `max-height`，默认可按 `max-height = min-height + 1vw`，例如 `min-height: 21vw; max-height: 22vw`。
- `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 的缓存。
- 多 tab 列表如果内部有大量固定图片、`itemCenter` 背景图或本地 OSS 图标，tab 内容容器优先使用 `v-show` 保留 DOM，避免每次切换时因 `v-if` 销毁重建导致固定图片反复加载；接口仍可在切换时重新请求最新数据。
- 弹窗统一使用公共组件 `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 通过
```