hy/aslan-h5

Fork 0

zhx 572c4cee1b fix: switch h5 assets to global interaction cos

2026-07-08 19:46:39 +08:00

20 KiB

Raw Permalink Blame History

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 常用命令

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

启动顺序：

引入全局样式：src/assets/main.css、src/styles/fonts.css、src/styles/global.css。
打印环境信息。
安装运行时安全能力：installRuntimeSecurity()。
安装受保护资源运行时：installProtectedAssetRuntime()。
应用性能模式 class：applyPerformanceModeClass()。
创建 Pinia，并启用 pinia-plugin-persistedstate。
注册全局指令 v-smart-img。
注册全局组件 LoadingContent。
注册 router、pinia、i18n。
按 URL lang 参数和页面规则初始化语言。
挂载到 #app。
空闲时检查版本，开启后每 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. 目录结构

.
├─ 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

流程：

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

7.4 运行时安全

入口安装：

installRuntimeSecurity()
installProtectedAssetRuntime()

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 页面初始化抽象

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

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. 开发接入流程

新增页面建议顺序：

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

新增 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

20 KiB Raw Permalink Blame History Unescape Escape