755 lines
20 KiB
Markdown
755 lines
20 KiB
Markdown
# 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`
|