# Likei H5 项目详情

最后扫描时间：2026-06-09

## 1. 项目定位

`likei-h5` 是一个运行在宿主 App WebView 内的多业务移动端 H5 项目，核心技术栈为 `Vue 3 + Vite 7 + Pinia 3 + Vue Router 4 + Vue I18n 11 + Vant 4`。

项目不是单一落地页，而是按业务域拆分的前端集合，覆盖：

- 角色中心：管理员、代理、BD、BD Leader、主播、金币代理。
- 钱包与资金流：提现、转账、兑换、薪资、KYC、银行卡。
- 充值与邀请：充值链路、支付方式、邀请不同角色或新用户。
- 排行榜与活动页：固定榜单、限时活动、游戏活动、世界杯专题。

默认运行模型优先适配 App 宿主环境，浏览器环境主要用于本地开发和调试。

## 2. 快速启动

### 2.1 环境要求

- Node：`^20.19.0 || >=22.12.0`
- 包管理器：当前仓库没有锁文件，默认按 `npm` 使用。
- 开发服务：Vite，默认端口 `5173`，`strictPort: true`。

### 2.2 常用命令

```bash
npm install
npm run dev
npm run dev:test
npm run dev:prod
npm run build
npm run build:dev
npm run build:test
npm run build:prod
npm run build:atu-prod
npm run build:azizi-prod
npm run preview
npm run lint
npm run docs:sync:security
```

说明：

- `npm run lint` 执行的是 `eslint . --fix`，会直接修改文件。
- 当前没有 `test` 脚本，构建是主要健康检查方式。
- 构建后会执行 `scripts/generate-version.js`，生成 `dist/version.json`。

### 2.3 环境文件

根目录当前存在：

- `.env`
- `.env.development`
- `.env.production`
- `.env.production-atu`
- `.env.production-azizi`
- `.env.test`

环境读取集中在 `src/utils/env.js`，常用变量包括：

- `VITE_USER_AUTH`
- `VITE_NODE_ENV`
- `VITE_API_BASE_URL`
- `VITE_APP_TITLE`
- `VITE_APP_VERSION`
- `VITE_ENABLE_VERSION_CHECK`

协作注意：环境文件可能有本地改动，不要默认重置。

## 3. 启动与运行链路

### 3.1 主入口

入口文件：`src/main.js`

启动顺序：

1. 引入全局样式：`src/assets/main.css`、`src/styles/fonts.css`、`src/styles/global.css`。
2. 打印环境信息。
3. 安装运行时安全能力：`installRuntimeSecurity()`。
4. 安装受保护资源运行时：`installProtectedAssetRuntime()`。
5. 应用性能模式 class：`applyPerformanceModeClass()`。
6. 创建 Pinia，并启用 `pinia-plugin-persistedstate`。
7. 注册全局指令 `v-smart-img`。
8. 注册全局组件 `LoadingContent`。
9. 注册 router、pinia、i18n。
10. 按 URL `lang` 参数和页面规则初始化语言。
11. 挂载到 `#app`。
12. 空闲时检查版本，开启后每 5 分钟轮询版本。

### 3.2 路由

路由文件：`src/router/index.js`

特点：

- 使用 `createWebHashHistory`，适合 App WebView 和无需服务端 history rewrite 的 H5。
- 页面均为动态 import。
- 统一安装 `installRouteGuard(router)`。
- 未匹配路由重定向到 `/apply`。

当前主要路由域：

- 公共入口：`/`、`/loading`、`/apply`、`/not_app`。
- 角色中心：`/admin-center`、`/agency-center`、`/bd-center`、`/bd-leader-center`、`/host-center`、`/coin-seller`。
- 钱包资金：`/available-income`、`/transfer`、`/exchange-gold-coins`、`/cash-withdraw`、`/cash-out`、`/KYC`、`/bank-card`。
- 充值：`/recharge`、`/recharge-pay-way`、`/map`、`/recharge-guide`。
- 邀请：`/invitation/invite-new-user`、`/invite-bd`、`/invite-bd-leader`、`/invite-agency`、`/invite-recharge-agency`。
- 排行榜：`/couple`、`/top-list`、`/weekly-star`、`/ranking`、`/games-king`。
- 活动页：`/recharge-reward`、`/login-reward`、`/daily-recharge`、`/activities/*`。

### 3.3 App 桥接与请求头

宿主适配相关文件：

- `src/utils/appBridge.js`
- `src/utils/appConnectionManager.js`
- `src/utils/appConnector.js`
- `src/utils/routeGuard.js`

宿主注入兼容：

- `window.app`
- `window.webkit`
- `window.FlutterPageControl`

推荐用法：

- 路由守卫使用 `routeGuard` 保证受保护页面在 App 内建立连接。
- 页面如果自己直接使用接口，必须先通过 `connectToApp` 设置请求头。
- 活动页当前规则是：图片预加载和接口初始化分离，loading 只等待图片，业务接口在 `connectToApp(() => { loadInitialPageData() })` 成功后独立请求。

## 4. 构建与 Vite 配置

配置文件：`vite.config.js`

关键点：

- Vue 插件：`@vitejs/plugin-vue`。
- 自动按需组件：`unplugin-vue-components` + `VantResolver`。
- 路径别名：`@ -> src`。
- 开发服务：
  - host: `0.0.0.0`
  - port: `5173`
  - strictPort: `true`
  - `/oss` 代理到 `https://asset.global-interaction.com`
- 预览服务：
  - host: `0.0.0.0`
  - port: `4173`
  - strictPort: `true`
- 本地开发额外提供 `/oss` 本地静态资源中间件，优先读取 `public/oss`。
- 生产类模式会去掉部分日志：
  - `production`
  - `production-atu`
- 默认移除 `console.log`、`console.debug`、`console.info` 和 `debugger`。
- 可通过 `LIKEI_KEEP_BUILD_LOGS=true` 保留构建日志。

构建产物命名：

- JS：`js/[hash].js`
- CSS：`css/[hash].[ext]`
- 其他资源：`assets/[hash].[ext]`

## 5. 目录结构

```text
.
├─ docs/                    项目文档、活动页建页规则、安全文档
├─ nginx/                   部署相关配置
├─ public/                  公共静态资源，本地 OSS 镜像目录在 public/oss
├─ scripts/                 构建后版本生成、安全文档同步等脚本
├─ src/
│  ├─ api/                  按业务域拆分的接口层
│  ├─ assets/               本地图片、图标、字体、基础样式
│  ├─ components/           公共组件
│  ├─ config/               图片路径、安全白名单等配置
│  ├─ directives/           自定义指令
│  ├─ locales/              多语言资源与 i18n 初始化
│  ├─ router/               路由定义
│  ├─ stores/               Pinia store
│  ├─ styles/               全局样式和字体
│  ├─ utils/                桥接、HTTP、权限、缓存、图片、支付等基础设施
│  └─ views/                页面级业务模块
├─ vite.config.js
└─ package.json
```

## 6. 页面与业务地图

### 6.1 `src/views`

当前一级页面目录：

- `Activities`
- `AdminCenter`
- `AgencyCenter`
- `ApplyHost`
- `BDCenter`
- `BDLeaderCenter`
- `CPReward`
- `GoodID`
- `HostCenter`
- `Invitation`
- `LandingPage`
- `PlatformPolicy`
- `Ranking`
- `Recharge`
- `RechargeAgency`
- `Wallet`

### 6.2 角色中心

- `AdminCenter`：管理员中心、团队管理、商品赠送、管理员政策。
- `AgencyCenter`：代理中心、消息、设置、团队账单、团队成员、邀请成员。
- `BDCenter`：BD 中心、收益详情、政策、商品赠送。
- `BDLeaderCenter`：BD Leader 中心。
- `HostCenter`：主播中心与主播设置。
- `RechargeAgency`：金币代理首页、搜索用户、卖家记录、招募说明。

### 6.3 钱包与资金

目录：`src/views/Wallet`

包含：

- 可用收益
- 转账与收款人搜索
- 金币兑换
- 资金详情
- 历史薪资
- 支付结果
- 提现、提现详情、KYC、银行卡

### 6.4 充值与邀请

- `src/views/Recharge`：充值主页、支付方式、地图、充值引导。
- `src/views/Invitation`：邀请新用户、BD、BD Leader、代理、金币代理。

### 6.5 排行榜

目录：`src/views/Ranking`

当前包含：

- `Couple`
- `GamesKing`
- `KingAndQueen`
- `Overall`
- `WeeklyStar`

### 6.6 活动页

目录：`src/views/Activities`

当前包含：

- `DailyRecharge`
- `Games`
- `GulbenFestival`
- `LesserBairam`
- `LoginReward`
- `LuckyDollars`
- `Reward`
- `SpringFestival`
- `WorldCup`

活动页特点：

- 独立性高，常有专属 `page.config.js` 和 `页面创建信息.md`。
- 常见模块包括背景、排行榜、奖励弹窗、规则弹窗、任务、倒计时、赛事列表等。
- 当前活动页建页规则集中维护在 `docs/活动页/建页/`。

### 6.7 WorldCup 当前状态

世界杯专题目录：`src/views/Activities/WorldCup`

当前包括：

- 首页：`index.vue`
- 详情页：`EventDetail/index.vue`
- 专用接口：`src/api/worldCup.js`
- 页面信息：`页面创建信息.md`
- 接口说明：`世界杯接口说明.md`

已接入能力：

- 排行榜与我的排名。
- Predict Now / Ended 赛事列表。
- 赛事详情。
- 押注模块。
- 押注记录。
- 奖励弹窗与规则弹窗。
- `connectToApp` 请求头初始化。
- loading 只等待阻塞图片，接口独立初始化。
- 大整数 `matchId` 按字符串处理，避免 JS 精度丢失。

## 7. 权限与安全

### 7.1 公共路径

公共路径白名单在：

- `src/config/security.js`
- `src/utils/permissionManager.js`

`security.js` 中的 `PUBLIC_PATHS` 用于 HTTP 和路由安全判断；`permissionManager.js` 中的 `ROLE_PERMISSIONS.PUBLIC_PAGES` 用于权限矩阵。

新增公共页时，两处都要检查是否需要同步。

### 7.2 角色模型

角色定义在 `src/utils/permissionManager.js`：

- `admin`
- `freightAgent`
- `bdLeader`
- `bd`
- `agent`
- `anchor`
- `guest`

默认首页：

- `admin` -> `/admin-center`
- `freightAgent` -> `/coin-seller`
- `agent` -> `/agency-center`
- `bdLeader` -> `/bd-leader-center`
- `bd` -> `/bd-center`
- `anchor` -> `/host-center`
- `guest` -> `/apply`

角色优先级：

`admin > freightAgent > bdLeader > bd > agent > anchor > guest`

### 7.3 路由守卫

文件：`src/utils/routeGuard.js`

流程：

1. 公共页直接放行。
2. 非公共页检查 App 连接。
3. Debug 环境允许浏览器模式调试，非 Debug 环境受保护页面必须在官方 App 内。
4. 拉取用户资料和身份。
5. 用 `permissionManager` 判断页面权限。
6. 无权限时跳转到该用户默认首页。

### 7.4 运行时安全

入口安装：

- `installRuntimeSecurity()`
- `installProtectedAssetRuntime()`

相关文件：

- `src/utils/runtimeSecurity.js`
- `src/utils/protectedAssets.js`
- `src/utils/protectedAssetRuntime.js`

受保护资源策略：

- 生产类模式下，`Activities/` 和 `Ranking/` 的 OSS 资源 URL 会被包装为 `likei-protected:<base64>`。
- 运行时再解析为真实 URL。
- `development` 和 `test` 模式不启用资源保护。

## 8. API 与网络层

### 8.1 接口目录

接口目录：`src/api`

当前模块：

- `activity.js`
- `admin.js`
- `bdCenter.js`
- `bdLeaderCenter.js`
- `couple.js`
- `goodId.js`
- `host.js`
- `invitation.js`
- `itemDistribution.js`
- `lottery.js`
- `pay.js`
- `ranking.js`
- `recruit.js`
- `task.js`
- `teamBill.js`
- `topList.js`
- `upload.js`
- `userInfo.js`
- `wallet.js`
- `weeklyStar.js`
- `worldCup.js`

接口按业务域拆分。新增业务如果明显独立，可以新增 API 文件；已有业务的小扩展优先复用现有文件。

### 8.2 HTTP 封装

文件：`src/utils/http.js`

导出：

- `request`
- `get`
- `post`
- `put`
- `del`
- `COMMON_HEADERS`
- `ApiError`

职责：

- 拼接 `VITE_API_BASE_URL`。
- 合并公共请求头和页面传入请求头。
- 支持 JSON 与 FormData。
- 统一包装 HTTP 错误、业务错误和网络错误。
- 非 Debug 环境中，非公共页接口必须在官方 App 连接后才允许请求。

当前注意点：

- `post(url, data)` 如果 `data` 是空对象 `{}` 会正常发送 body。
- 如果 `data` 为 `null/undefined`，当前 HTTP 封装不会写 body。
- 活动页规则要求：POST 接口无业务参数时也传 `{}`。

### 8.3 请求头来源

默认头在 `http.js` 中声明，App 连接成功后通过：

- `setHeadersFromApp`
- `updateCommonHeaders`
- `connectToApp`
- `setHttpHeaders`

更新到公共请求头。

页面直接请求接口前，需要确认是否已完成 `connectToApp`。

## 9. 状态管理

### 9.1 Pinia

当前 store：

- `country`
- `couple`
- `gamesKing`
- `identity`
- `lang`
- `lastImg`
- `rechargeTarget`
- `springFestival`

Pinia 启用了 persisted state。

### 9.2 utils 单例缓存

项目同时使用一些 utils 单例缓存：

- `src/utils/userStore.js`
- `src/utils/appConnectionManager.js`
- `src/utils/applyStore.js`
- `src/utils/coinSellerStore.js`
- `src/utils/payeeStore.js`

这些不是普通纯函数，承担跨页面状态缓存职责。新增跨页状态前要先检查是否已有对应 store 或 utils。

### 9.3 页面初始化抽象

相关文件：

- `src/utils/usePageInitialization.js`
- `src/utils/pageConfig.js`

适合用于角色中心类页面，统一处理：

- App 连接。
- 用户信息。
- 团队信息。
- 余额。
- 工作统计。
- 初始化完成回调。

活动页或轻页面通常不强制使用这套抽象。

## 10. 国际化与方向

入口：`src/locales/i18n.js`

语言资源：

- `zh`
- `en`
- `ar`
- `tr`
- `bn`

特点：

- `src/main.js` 会读取 URL hash query 中的 `lang` 参数。
- 阿语会设置 `dir=rtl`。
- 页面可根据语言或页面名单强制默认语言。

新增页面时：

- 可复用现有 key 时优先复用。
- 新增多语言文案要同步所有目标语言文件。
- 活动页如果暂时使用英文固定文案，要在页面信息 md 中记录。

## 11. 图片、资源与预加载

### 11.1 本地与线上 OSS

图片路径配置：`src/config/imagePaths.js`

规则：

- 开发环境：`/oss/h5/Azizi/`
- 非开发环境：`https://asset.global-interaction.com/h5/Azizi/`

常用方法：

- `getPngUrl(imagePath, filename)`
- `getWebpUrl(imagePath, filename)`
- `getMp4Url(imagePath, filename)`

本地 OSS 镜像目录：

- `public/oss/h5/Azizi`

当前本地主要包含：

- `Activities`

### 11.2 智能图片

全局指令：

- `v-smart-img`

相关文件：

- `src/directives/smartImage.js`
- `src/utils/image/imageCacheManager.js`
- `src/utils/image/imageHandler.js`
- `src/utils/image/imagePreloader.js`
- `src/config/imageCacheVersion.js`

活动页约定：

- 项目自身静态图、OSS 活动图可用 `v-smart-img`。
- 接口返回的远程图片链接不要使用 `v-smart-img`，直接使用原生 `<img :src="接口字段">`。

### 11.3 预加载

预加载工具：

- `preloadImages`
- `preloadImagesIdle`

当前活动页建页规则：

- 新建 `index.vue` 必须有统一 loading。
- `completePreloading()` 只负责阻塞图片预加载。
- loading 不等待业务接口。
- 业务接口提取到 `loadInitialPageData()` 或同名页面初始化方法。
- 接口初始化在 `connectToApp` 成功后执行。

## 12. 公共组件

常用公共组件：

- `BackgroundLayer.vue`
- `GeneralHeader.vue`
- `itemCenter.vue`
- `LoadingContent.vue`
- `MaskLayer.vue`
- `PageContainer.vue`
- `PermissionGuard.vue`
- `Toast.vue`
- `VapMp4Player.vue`

活动页常用：

- `itemCenter`：背景图 + 绝对定位内容层。
- `LoadingContent`：统一加载动画。
- `MaskLayer`：规则、奖励、历史、结果等弹窗遮罩。
- `GeneralHeader`：带标题与返回按钮的通用头部。

`itemCenter` 注意：

- 页面初建阶段不预设 `min-height`。
- 页面开发完成后，如需稳定图片容器高度，再按图片比例补。
- 补 `min-height` 时同步补接近的 `max-height`，默认可用 `max-height = min-height + 1vw`。

## 13. 活动页建页规则索引

活动页文档目录：

- `docs/活动页/README.md`
- `docs/活动页/建页/快速建立活动页方案.md`
- `docs/活动页/建页/建页执行流程.md`
- `docs/活动页/建页/建页操作模板.md`
- `docs/活动页/建页/建页资料库.md`
- `docs/活动页/创建记录/`
- `docs/活动页/分析/`

当前核心规则：

- 页面改动、模块补充、接口对接、样式同步和文档同步，都要联系建页规则执行。
- 新建或更新活动页时，页面模块、div 结构、方法、接口处理都要补中文注释。
- 能使用内联样式表达的固定布局、尺寸、间距、定位，优先使用内联样式。
- 页面根容器使用 `height: 100vh`，内部主内容滚动并隐藏滚动条。
- 页面任何模块都不展示可见滚动条。
- 弹窗统一使用 `MaskLayer`。
- 使用接口前必须先 `connectToApp`。
- loading 只等阻塞图片预加载，接口初始化独立。
- 多 tab 数据要使用独立数组和独立 request token。
- 多 tab 内容如果固定图片多，优先用 `v-show` 保留 DOM，避免图片反复加载。
- POST 接口无业务参数时也要传 `{}`。
- 大整数 ID，如 WorldCup `matchId`，按字符串传参，禁止 `Number(id)`。

## 14. 开发接入流程

新增页面建议顺序：

1. 判断业务域，选择合适的 `src/views/<domain>` 目录。
2. 注册路由，明确 `path`、`name`、`component`、`meta`。
3. 判断是否公共页；如是公共页，同步检查 `security.js` 和 `permissionManager.js`。
4. 判断是否需要角色权限；如需要，补对应角色权限列表。
5. 判断是否使用 `usePageInitialization`。
6. 判断是否新增或复用 `src/api/*`。
7. 接入 `connectToApp`，确保接口请求头。
8. 接入 i18n、公共组件、Toast、MaskLayer 等现有能力。
9. 如果是活动页，同步 `页面创建信息.md` 或接口说明 md。
10. 跑构建验证。

新增 API 建议：

- 明显新业务域：新增 `src/api/<domain>.js`。
- 现有业务小扩展：复用已有 API 文件。
- POST 无参数：传 `{}`。
- 大整数 ID：保持字符串。

新增活动页建议：

- 先建页面信息 md。
- 再建 `page.config.js`。
- 扫描本地 OSS 图片清单。
- 生成基础 loading、背景、模块容器。
- 逐个模块迭代，不一次性生成所有业务。

## 15. 脚本与版本

脚本目录：`scripts`

当前脚本：

- `generate-version.js`：构建后生成版本文件。
- `build-with-version.js`：带版本日志控制的构建脚本。
- `sync-security-docs.js`：同步安全文档。

版本检查：

- 文件：`src/utils/versionChecker.js`
- 构建后版本信息写入 `dist/version.json`。
- 运行时可通过 `VITE_ENABLE_VERSION_CHECK` 开启版本检查。
- 默认每 5 分钟轮询一次。
- `major` 更新会清理更完整缓存。
- `minor/patch` 会检查图片缓存版本并清理 session 数据。

## 16. 已知现状与风险

### 16.1 README 路径

当前 `README.md` 和 `START.md` 仍指向 `docs/project-details.md`，但当前主维护文档是：

- `docs/项目详情.md`

后续可以按需要同步根目录入口文档。

### 16.2 无测试脚本

当前没有 `test` 脚本。验证主要依赖：

- `npm run build`
- 必要时手动打开本地页面检查。

### 16.3 无锁文件

当前未见包管理锁文件，不同环境重新安装可能产生依赖解析差异。

### 16.4 HTTP 错误解析

`src/utils/http.js` 在非 2xx 响应时直接 `await response.json()`，如果服务端返回非 JSON，可能额外抛解析错误。后续可优化为先 try JSON，失败再 fallback text。

### 16.5 文档与页面演进快

活动页需求迭代频繁，建议每次页面改动后同步：

- 页面自身 `页面创建信息.md`
- 接口说明 md
- 必要时同步 `docs/活动页/建页/`

## 17. 常用文件索引

项目入口：

- `src/main.js`
- `src/App.vue`
- `src/router/index.js`

基础设施：

- `src/utils/http.js`
- `src/utils/env.js`
- `src/utils/routeGuard.js`
- `src/utils/permissionManager.js`
- `src/utils/appBridge.js`
- `src/utils/appConnector.js`
- `src/utils/appConnectionManager.js`
- `src/utils/versionChecker.js`

资源：

- `src/config/imagePaths.js`
- `src/directives/smartImage.js`
- `src/utils/image/imagePreloader.js`
- `src/utils/image/imageCacheManager.js`

活动页：

- `docs/活动页/建页/建页执行流程.md`
- `docs/活动页/建页/建页操作模板.md`
- `docs/活动页/建页/建页资料库.md`
- `src/views/Activities/WorldCup/页面创建信息.md`
- `src/views/Activities/WorldCup/世界杯接口说明.md`

权限与安全：

- `src/config/security.js`
- `src/utils/runtimeSecurity.js`
- `src/utils/protectedAssets.js`
- `docs/安全/前端加固-中文.md`

构建：

- `vite.config.js`
- `scripts/generate-version.js`
- `scripts/build-with-version.js`