From 5c26f868a152ac4b5801b951a6ae52237e1310b9 Mon Sep 17 00:00:00 2001 From: hzj <1304805162@qq.com> Date: Tue, 9 Jun 2026 15:07:23 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E9=A1=B9=E7=9B=AE=E6=80=BB=E7=BB=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/项目详情.md | 934 ++++++++++++++++++++++++----------------------- 1 file changed, 487 insertions(+), 447 deletions(-) diff --git a/docs/项目详情.md b/docs/项目详情.md index aa09f2c..64f5be0 100644 --- a/docs/项目详情.md +++ b/docs/项目详情.md @@ -1,19 +1,27 @@ # Likei H5 项目详情 +最后扫描时间：2026-06-09 + ## 1. 项目定位 -`likei-h5` 是一个运行在宿主 App WebView 中的多业务 H5 项目，技术栈以 `Vue 3 + Vite + Pinia + Vue Router + Vue I18n + Vant` 为主。 +`likei-h5` 是一个运行在宿主 App WebView 内的多业务移动端 H5 项目，核心技术栈为 `Vue 3 + Vite 7 + Pinia 3 + Vue Router 4 + Vue I18n 11 + Vant 4`。 -它不是单一落地页，而是一个按角色和业务域拆分的移动端前端集合，覆盖管理后台入口、代理中心、主播中心、钱包、充值、邀请、排行榜和活动页等场景。 +项目不是单一落地页，而是按业务域拆分的前端集合，覆盖： -当前运行模型默认优先适配 App 宿主环境，再兼容浏览器开发环境。 +- 角色中心：管理员、代理、BD、BD Leader、主播、金币代理。 +- 钱包与资金流：提现、转账、兑换、薪资、KYC、银行卡。 +- 充值与邀请：充值链路、支付方式、邀请不同角色或新用户。 +- 排行榜与活动页：固定榜单、限时活动、游戏活动、世界杯专题。 + +默认运行模型优先适配 App 宿主环境，浏览器环境主要用于本地开发和调试。 ## 2. 快速启动 ### 2.1 环境要求 -- Node 版本: `^20.19.0 || >=22.12.0` -- 包管理器: 当前仓库没有锁文件，默认按 `npm` 命令使用 +- Node：`^20.19.0 || >=22.12.0` +- 包管理器：当前仓库没有锁文件，默认按 `npm` 使用。 +- 开发服务：Vite，默认端口 `5173`，`strictPort: true`。 ### 2.2 常用命令 @@ -23,246 +31,218 @@ 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` -已确认工作区当前存在本地环境文件改动，至少 `.env.development` 不是干净状态。后续改代码时不要默认重置环境文件。 +环境读取集中在 `src/utils/env.js`，常用变量包括： -### 2.4 构建说明 +- `VITE_USER_AUTH` +- `VITE_NODE_ENV` +- `VITE_API_BASE_URL` +- `VITE_APP_TITLE` +- `VITE_APP_VERSION` +- `VITE_ENABLE_VERSION_CHECK` -- 构建入口使用 `vite build` -- 构建后会执行 `scripts/generate-version.js` -- 该脚本会在 `dist/version.json` 写入版本信息 -- 当前仓库没有测试脚本，`build` 更接近健康检查而不是测试替代 +协作注意：环境文件可能有本地改动，不要默认重置。 -## 3. 架构总览 +## 3. 启动与运行链路 -### 3.1 启动主链路 +### 3.1 主入口 -项目主链路从 `src/main.js` 开始： +入口文件：`src/main.js` -1. 注册全局样式 -2. 注册 `Pinia` -3. 注册 `Router` -4. 初始化 `i18n` -5. 执行版本检查 -6. 挂载应用 +启动顺序： -核心入口文件： +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 分钟轮询版本。 -- `src/main.js` -- `src/App.vue` -- `src/router/index.js` +### 3.2 路由 -### 3.2 运行时核心链路 +路由文件：`src/router/index.js` -```text -main.js - -> router.beforeEach - -> routeGuard - -> appBridge / appConnectionManager - -> http headers 注入 - -> 拉取用户资料 / 身份 - -> permissionManager 计算角色权限 - -> 放行到对应页面 - -> 页面按需调用各自 API -``` +特点： -### 3.3 宿主 App 适配 +- 使用 `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` -说明： +推荐用法： -- 项目默认假设自己运行在 App 容器中 -- 浏览器模式主要用于开发调试 -- 宿主传入的认证和设备信息会被解析后写入公共请求头 +- 路由守卫使用 `routeGuard` 保证受保护页面在 App 内建立连接。 +- 页面如果自己直接使用接口，必须先通过 `connectToApp` 设置请求头。 +- 活动页当前规则是：图片预加载和接口初始化分离，loading 只等待图片，业务接口在 `connectToApp(() => { loadInitialPageData() })` 成功后独立请求。 -### 3.4 路由与权限 +## 4. 构建与 Vite 配置 -路由集中定义在 `src/router/index.js`，使用的是 `createWebHashHistory`。 +配置文件：`vite.config.js` -这说明项目路由模型偏向嵌入式 H5，路径切换依赖 hash，而不是服务端 history 回退。 +关键点： -权限系统由以下文件共同组成： +- Vue 插件：`@vitejs/plugin-vue`。 +- 自动按需组件：`unplugin-vue-components` + `VantResolver`。 +- 路径别名：`@ -> src`。 +- 开发服务： + - host: `0.0.0.0` + - port: `5173` + - strictPort: `true` + - `/oss` 代理到 `https://cdn.azizichat.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` 保留构建日志。 -- `src/utils/routeGuard.js` -- `src/utils/permissionManager.js` -- `src/api/wallet.js` 中的身份接口 -- `src/utils/userStore.js` +构建产物命名： -整体机制是： +- JS：`js/[hash].js` +- CSS：`css/[hash].[ext]` +- 其他资源：`assets/[hash].[ext]` -1. 先判断是否为公共页 -2. 非公共页先建立 App 连接 -3. 再取用户资料与身份 -4. 由 `permissionManager` 计算角色和可访问页面 -5. 根据结果决定放行还是重定向 - -### 3.5 页面初始化抽象 - -多个中心页复用了统一的页面初始化组合函数： - -- `src/utils/usePageInitialization.js` -- `src/utils/pageConfig.js` - -这套抽象负责统一处理： - -- App 连接 -- 请求头注入 -- 用户资料拉取 -- 团队信息拉取 -- 余额拉取 -- 工作统计拉取 -- 初始化完成后的回调 - -适合复用的页面类型主要是： - -- `HostCenter` -- `AgencyCenter` -- `BDCenter` -- `BDLeaderCenter` -- `Coin Seller` -- 类似的首页/中心页 - -如果只是简单的活动页、排行榜页或单功能页，不一定需要接这套初始化。 - -## 4. 目录结构 - -这里只记录高价值目录，不做全量文件罗列。 +## 5. 目录结构 ```text . -├─ public/ 浏览器调试和静态入口文件 -├─ scripts/ 构建辅助脚本 +├─ docs/ 项目文档、活动页建页规则、安全文档 +├─ nginx/ 部署相关配置 +├─ public/ 公共静态资源，本地 OSS 镜像目录在 public/oss +├─ scripts/ 构建后版本生成、安全文档同步等脚本 ├─ src/ -│ ├─ api/ 按业务域拆分的接口层 -│ ├─ assets/ 图片、图标、字体、基础样式 -│ ├─ components/ 公共组件 -│ ├─ config/ 配置类文件 -│ ├─ directives/ 自定义指令 -│ ├─ locales/ 多语言资源和 i18n 初始化 -│ ├─ router/ 路由定义 -│ ├─ stores/ Pinia store -│ ├─ styles/ 全局样式和字体 -│ ├─ utils/ 基础设施、桥接、权限、缓存、工具函数 -│ └─ views/ 页面级业务模块 -├─ .env* 多环境配置 -├─ vite.config.js Vite 配置 -└─ package.json 脚本和依赖 +│ ├─ api/ 按业务域拆分的接口层 +│ ├─ assets/ 本地图片、图标、字体、基础样式 +│ ├─ components/ 公共组件 +│ ├─ config/ 图片路径、安全白名单等配置 +│ ├─ directives/ 自定义指令 +│ ├─ locales/ 多语言资源与 i18n 初始化 +│ ├─ router/ 路由定义 +│ ├─ stores/ Pinia store +│ ├─ styles/ 全局样式和字体 +│ ├─ utils/ 桥接、HTTP、权限、缓存、图片、支付等基础设施 +│ └─ views/ 页面级业务模块 +├─ vite.config.js +└─ package.json ``` -## 5. 页面与业务模块地图 +## 6. 页面与业务地图 -### 5.1 Landing / 公共入口 +### 6.1 `src/views` -目录： +当前一级页面目录： -- `src/views/LandingPage` -- `src/views/ApplyHost` -- `src/views/PlatformPolicy` +- `Activities` +- `AdminCenter` +- `AgencyCenter` +- `ApplyHost` +- `BDCenter` +- `BDLeaderCenter` +- `CPReward` +- `GoodID` +- `HostCenter` +- `Invitation` +- `LandingPage` +- `PlatformPolicy` +- `Ranking` +- `Recharge` +- `RechargeAgency` +- `Wallet` -主要职责： +### 6.2 角色中心 -- 加载页 -- 非 App 环境提示 -- 申请加入流程 -- 平台政策页 +- `AdminCenter`：管理员中心、团队管理、商品赠送、管理员政策。 +- `AgencyCenter`：代理中心、消息、设置、团队账单、团队成员、邀请成员。 +- `BDCenter`：BD 中心、收益详情、政策、商品赠送。 +- `BDLeaderCenter`：BD Leader 中心。 +- `HostCenter`：主播中心与主播设置。 +- `RechargeAgency`：金币代理首页、搜索用户、卖家记录、招募说明。 -### 5.2 角色中心 +### 6.3 钱包与资金 -目录： +目录：`src/views/Wallet` -- `src/views/AdminCenter` -- `src/views/AgencyCenter` -- `src/views/BDCenter` -- `src/views/BDLeaderCenter` -- `src/views/HostCenter` -- `src/views/RechargeAgency` +包含： -这些目录是最核心的业务承载区，分别对应不同角色首页和管理能力。 - -其中： - -- `AdminCenter` 负责多团队管理、邀请和策略配置 -- `AgencyCenter` 负责代理视角的团队、账单、消息和提现入口 -- `BDCenter` / `BDLeaderCenter` 负责 BD 及其上级角色能力 -- `HostCenter` 负责主播视角首页、工资、提现、设置 -- `RechargeAgency` 对应 Coin Seller / Freight Agent 相关页面 - -### 5.3 钱包与资金流 - -目录： - -- `src/views/Wallet` - -主要包含： - -- 余额 -- 转账 -- 搜索收款人 +- 可用收益 +- 转账与收款人搜索 - 金币兑换 +- 资金详情 - 历史薪资 -- 资金明细 -- 提现 -- KYC -- 银行卡 - 支付结果 +- 提现、提现详情、KYC、银行卡 -这部分与角色中心页耦合较高，很多中心页会跳到这里完成具体资金操作。 +### 6.4 充值与邀请 -### 5.4 充值与支付 +- `src/views/Recharge`：充值主页、支付方式、地图、充值引导。 +- `src/views/Invitation`：邀请新用户、BD、BD Leader、代理、金币代理。 -目录： +### 6.5 排行榜 -- `src/views/Recharge` +目录：`src/views/Ranking` -主要包含： - -- 充值主页 -- 支付方式 -- 地图 -- 充值引导 - -### 5.5 邀请体系 - -目录： - -- `src/views/Invitation` - -主要包含邀请不同角色和邀请注册相关页面。 - -### 5.6 排行榜 - -目录： - -- `src/views/Ranking` - -目前包含： +当前包含： - `Couple` - `GamesKing` @@ -270,48 +250,78 @@ main.js - `Overall` - `WeeklyStar` -### 5.7 活动页 +### 6.6 活动页 -目录： +目录：`src/views/Activities` -- `src/views/Activities` +当前包含： -当前活动以专题形式存在，通常是独立业务页或赛季页，例如： - -- `LuckyDollars` -- `SpringFestival` +- `DailyRecharge` +- `Games` +- `GulbenFestival` - `LesserBairam` - `LoginReward` +- `LuckyDollars` - `Reward` +- `SpringFestival` +- `WorldCup` -特点： +活动页特点： -- 页面独立性高 -- 生命周期强 -- 经常带倒计时、排行榜、奖励展示等逻辑 +- 独立性高，常有专属 `page.config.js` 和 `页面创建信息.md`。 +- 常见模块包括背景、排行榜、奖励弹窗、规则弹窗、任务、倒计时、赛事列表等。 +- 当前活动页建页规则集中维护在 `docs/活动页/建页/`。 -## 6. 权限与角色模型 +### 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` -- `src/utils/routeGuard.js` -### 6.1 角色列表 +`security.js` 中的 `PUBLIC_PATHS` 用于 HTTP 和路由安全判断；`permissionManager.js` 中的 `ROLE_PERMISSIONS.PUBLIC_PAGES` 用于权限矩阵。 -当前角色常量定义为： +新增公共页时，两处都要检查是否需要同步。 + +### 7.2 角色模型 + +角色定义在 `src/utils/permissionManager.js`： - `admin` +- `freightAgent` - `bdLeader` - `bd` - `agent` - `anchor` -- `freightAgent` - `guest` -### 6.2 默认落地页 - -当前默认落地页映射为： +默认首页： - `admin` -> `/admin-center` - `freightAgent` -> `/coin-seller` @@ -321,85 +331,49 @@ main.js - `anchor` -> `/host-center` - `guest` -> `/apply` -### 6.3 权限模型特点 +角色优先级： -- 权限是按角色和页面路径做映射，不是按按钮或接口粒度做权限 -- `PUBLIC_PAGES` 中定义了公共可访问页 -- 多角色用户会先算出所有角色，再根据优先级选主角色 -- 页面权限判断核心方法是 `hasPagePermission` +`admin > freightAgent > bdLeader > bd > agent > anchor > guest` -### 6.4 什么时候需要改权限配置 +### 7.3 路由守卫 -如果新增页面属于以下情况之一，通常需要同步修改 `permissionManager.js`： +文件：`src/utils/routeGuard.js` -- 新增角色专属页面 -- 新增只有部分角色可访问的功能页 -- 新增公共页 -- 新增角色默认首页 +流程： -如果只是现有角色中心下的子功能页，也建议明确补进对应角色的权限数组，避免路由守卫后续重定向异常。 +1. 公共页直接放行。 +2. 非公共页检查 App 连接。 +3. Debug 环境允许浏览器模式调试，非 Debug 环境受保护页面必须在官方 App 内。 +4. 拉取用户资料和身份。 +5. 用 `permissionManager` 判断页面权限。 +6. 无权限时跳转到该用户默认首页。 -## 7. 数据与状态 +### 7.4 运行时安全 -这个项目不是纯 Pinia 架构，而是 `Pinia + utils 单例缓存` 的混合方式。 +入口安装： -### 7.1 Pinia store +- `installRuntimeSecurity()` +- `installProtectedAssetRuntime()` -当前 store 主要承担轻量或跨页状态： +相关文件： -- `src/stores/lang.js` -- `src/stores/identity.js` -- `src/stores/country.js` -- `src/stores/couple.js` -- `src/stores/gamesKing.js` -- `src/stores/rechargeTarget.js` -- `src/stores/springFestival.js` -- `src/stores/lastImg.js` +- `src/utils/runtimeSecurity.js` +- `src/utils/protectedAssets.js` +- `src/utils/protectedAssetRuntime.js` -其中最常见的是： +受保护资源策略： -- `lang` 负责语言选择和持久化 -- `identity` 负责页面层身份标签 +- 生产类模式下，`Activities/` 和 `Ranking/` 的 OSS 资源 URL 会被包装为 `likei-protected:`。 +- 运行时再解析为真实 URL。 +- `development` 和 `test` 模式不启用资源保护。 -### 7.2 utils 单例缓存 +## 8. API 与网络层 -下面这些文件承担了比普通工具函数更重的状态职责： +### 8.1 接口目录 -- `src/utils/userStore.js` -- `src/utils/appConnectionManager.js` -- `src/utils/payeeStore.js` -- `src/utils/applyStore.js` -- `src/utils/coinSellerStore.js` +接口目录：`src/api` -它们主要负责： - -- 用户资料缓存 -- 团队信息缓存 -- App 连接状态缓存 -- 页面跨跳转时的业务状态缓存 - -### 7.3 页面级状态 - -绝大多数页面仍然保留较多页面内 `ref/reactive` 状态，尤其是中心页和钱包页。 - -这意味着： - -- 通用能力已经抽出来一部分 -- 业务细节仍然主要留在页面组件内部 - -后续改新页面时，优先判断状态到底属于： - -- 全局复用 -- 多页跨跳转共享 -- 单页临时状态 - -不要默认都进 Pinia。 - -## 8. API 分层 - -接口层目录为 `src/api/`，按业务域拆分，而不是按 HTTP 方法拆分。 - -当前可见模块包括： +当前模块： - `activity.js` - `admin.js` @@ -421,56 +395,103 @@ main.js - `userInfo.js` - `wallet.js` - `weeklyStar.js` +- `worldCup.js` -### 8.1 HTTP 基础层 +接口按业务域拆分。新增业务如果明显独立，可以新增 API 文件；已有业务的小扩展优先复用现有文件。 -请求基础能力集中在 `src/utils/http.js`： +### 8.2 HTTP 封装 + +文件：`src/utils/http.js` + +导出： - `request` - `get` - `post` - `put` - `del` +- `COMMON_HEADERS` +- `ApiError` -同时负责： +职责： -- 基础 API URL 拼接 -- 公共请求头注入 -- App 桥接后的 header 更新 -- `ApiError` 包装 -- HTTP 错误和业务错误归一化 +- 拼接 `VITE_API_BASE_URL`。 +- 合并公共请求头和页面传入请求头。 +- 支持 JSON 与 FormData。 +- 统一包装 HTTP 错误、业务错误和网络错误。 +- 非 Debug 环境中，非公共页接口必须在官方 App 连接后才允许请求。 -### 8.2 页面消费方式 +当前注意点： -页面通常直接从 `src/api/*` 导入接口方法使用，不会再经过 service facade。 +- `post(url, data)` 如果 `data` 是空对象 `{}` 会正常发送 body。 +- 如果 `data` 为 `null/undefined`，当前 HTTP 封装不会写 body。 +- 活动页规则要求：POST 接口无业务参数时也传 `{}`。 -常见模式是： +### 8.3 请求头来源 -1. 页面或组合函数导入业务 API -2. 调接口后直接在页面中做字段转换 -3. 再把结果写进页面状态 +默认头在 `http.js` 中声明，App 连接成功后通过： -这意味着新增页面时，最好沿用现有风格，不要中途引入另一套完全不同的 service 架构，除非是一次明确的重构。 +- `setHeadersFromApp` +- `updateCommonHeaders` +- `connectToApp` +- `setHttpHeaders` -### 8.3 什么时候新增 API 文件 +更新到公共请求头。 -建议在以下情况新增 `src/api/*.js`： +页面直接请求接口前，需要确认是否已完成 `connectToApp`。 -- 新页面属于新的业务域 -- 原有接口文件已经明显跨域和膨胀 -- 新模块后续会持续扩展 +## 9. 状态管理 -如果只是现有钱包、邀请、活动、排行榜模块里的小功能，优先复用已有 API 文件。 +### 9.1 Pinia -## 9. 国际化与样式 +当前 store： -### 9.1 国际化 +- `country` +- `couple` +- `gamesKing` +- `identity` +- `lang` +- `lastImg` +- `rechargeTarget` +- `springFestival` -国际化入口： +Pinia 启用了 persisted state。 -- `src/locales/i18n.js` +### 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` @@ -480,235 +501,254 @@ main.js 特点： -- 支持通过 `Pinia` 中的语言状态驱动切换 -- 会根据语言设置 `document.documentElement` 的 `lang` 和 `dir` -- 已显式支持 RTL，主要是阿拉伯语场景 +- `src/main.js` 会读取 URL hash query 中的 `lang` 参数。 +- 阿语会设置 `dir=rtl`。 +- 页面可根据语言或页面名单强制默认语言。 -### 9.2 样式入口 +新增页面时： -全局样式入口： +- 可复用现有 key 时优先复用。 +- 新增多语言文案要同步所有目标语言文件。 +- 活动页如果暂时使用英文固定文案，要在页面信息 md 中记录。 -- `src/assets/main.css` -- `src/styles/fonts.css` -- `src/styles/global.css` +## 11. 图片、资源与预加载 -资源目录： +### 11.1 本地与线上 OSS -- `src/assets/icon` -- `src/assets/images` -- `src/assets/fonts` +图片路径配置：`src/config/imagePaths.js` -页面样式目前仍以页面内 `scoped style` 和局部内联样式为主，说明 UI 复用度还没有完全组件化。 +规则： -## 10. 开发约定 +- 开发环境：`/oss/h5/Azizi/` +- 非开发环境：`https://cdn.azizichat.com/h5/Azizi/` -这一节是后续你我一起做新页面时最实用的部分。 +常用方法： -### 10.1 新页面放哪里 +- `getPngUrl(imagePath, filename)` +- `getWebpUrl(imagePath, filename)` +- `getMp4Url(imagePath, filename)` -优先按业务域放到 `src/views/` 下已有模块目录中。 +本地 OSS 镜像目录： -建议： +- `public/oss/h5/Azizi` -- 角色首页相关功能放到对应角色目录 -- 钱包相关放到 `src/views/Wallet` -- 排行榜放到 `src/views/Ranking` -- 活动专题放到 `src/views/Activities` +当前本地主要包含： -只有在确定是全新业务域时，才新开一级目录。 +- `Activities` -### 10.2 何时复用 `usePageInitialization` +### 11.2 智能图片 -适合复用： +全局指令： -- 角色中心首页 -- 需要统一拉用户资料、团队信息、余额、工作统计的页面 -- 需要在页面加载时完成 App 连接和数据初始化的页面 +- `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` -### 10.3 何时新增 `api/*` +活动页约定： -优先复用现有 API 文件。只有在业务域明显独立时才新增新文件。 +- 项目自身静态图、OSS 活动图可用 `v-smart-img`。 +- 接口返回的远程图片链接不要使用 `v-smart-img`，直接使用原生 ``。 -### 10.4 何时修改权限配置 +### 11.3 预加载 -新增页面只要不是公共页，默认都要检查： +预加载工具： -- 是否需要在 `src/router/index.js` 注册 -- 是否需要在 `src/utils/permissionManager.js` 增加角色访问权限 -- 是否需要更新默认落地页或公共页配置 +- `preloadImages` +- `preloadImagesIdle` -### 10.5 何时修改用户或连接缓存 +当前活动页建页规则： -如果新页面依赖： +- 新建 `index.vue` 必须有统一 loading。 +- `completePreloading()` 只负责阻塞图片预加载。 +- loading 不等待业务接口。 +- 业务接口提取到 `loadInitialPageData()` 或同名页面初始化方法。 +- 接口初始化在 `connectToApp` 成功后执行。 -- 用户资料 -- 团队资料 -- App 宿主头信息 +## 12. 公共组件 -优先复用： +常用公共组件： -- `src/utils/userStore.js` -- `src/utils/appConnectionManager.js` +- `BackgroundLayer.vue` +- `GeneralHeader.vue` +- `itemCenter.vue` +- `LoadingContent.vue` +- `MaskLayer.vue` +- `PageContainer.vue` +- `PermissionGuard.vue` +- `Toast.vue` +- `VapMp4Player.vue` -不要在页面里再新造一份重复缓存。 +活动页常用： -### 10.6 文档维护原则 +- `itemCenter`：背景图 + 绝对定位内容层。 +- `LoadingContent`：统一加载动画。 +- `MaskLayer`：规则、奖励、历史、结果等弹窗遮罩。 +- `GeneralHeader`：带标题与返回按钮的通用头部。 -后续新增页面、角色、模块后，优先更新这份文档，而不是新增平行说明文档。 +`itemCenter` 注意： -## 11. 新页面接入流程 +- 页面初建阶段不预设 `min-height`。 +- 页面开发完成后，如需稳定图片容器高度，再按图片比例补。 +- 补 `min-height` 时同步补接近的 `max-height`，默认可用 `max-height = min-height + 1vw`。 -后续新增一个新页面时，建议按下面顺序处理： +## 13. 活动页建页规则索引 -1. 建页面目录 - 在合适的 `src/views/<业务域>/` 下创建页面文件，优先沿用现有目录结构。 +活动页文档目录： -2. 注册路由 - 在 `src/router/index.js` 中新增路由，明确 `path`、`name`、`component` 和 `meta`。 +- `docs/活动页/README.md` +- `docs/活动页/建页/快速建立活动页方案.md` +- `docs/活动页/建页/建页执行流程.md` +- `docs/活动页/建页/建页操作模板.md` +- `docs/活动页/建页/建页资料库.md` +- `docs/活动页/创建记录/` +- `docs/活动页/分析/` -3. 判断是否需要权限配置 - 如果不是公共页，检查 `src/utils/permissionManager.js` 是否要补角色权限。 +当前核心规则： -4. 判断是否复用页面初始化 - 如果页面需要统一接 App、拉用户、余额、团队、统计数据，优先考虑 `usePageInitialization`。 +- 页面改动、模块补充、接口对接、样式同步和文档同步，都要联系建页规则执行。 +- 新建或更新活动页时，页面模块、div 结构、方法、接口处理都要补中文注释。 +- 能使用内联样式表达的固定布局、尺寸、间距、定位，优先使用内联样式。 +- 页面根容器使用 `height: 100vh`，内部主内容滚动并隐藏滚动条。 +- 页面任何模块都不展示可见滚动条。 +- 弹窗统一使用 `MaskLayer`。 +- 使用接口前必须先 `connectToApp`。 +- loading 只等阻塞图片预加载，接口初始化独立。 +- 多 tab 数据要使用独立数组和独立 request token。 +- 多 tab 内容如果固定图片多，优先用 `v-show` 保留 DOM，避免图片反复加载。 +- POST 接口无业务参数时也要传 `{}`。 +- 大整数 ID，如 WorldCup `matchId`，按字符串传参，禁止 `Number(id)`。 -5. 新增 API 模块或复用现有 API - 先看 `src/api/` 是否已有相近业务域，再决定是否新增文件。 +## 14. 开发接入流程 -6. 接入 i18n 与公共组件 - 文案走 `src/locales/*.json`，头部、遮罩、提示等尽量复用现有组件。 +新增页面建议顺序： -补充建议： +1. 判断业务域，选择合适的 `src/views/` 目录。 +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. 跑构建验证。 -- 如果页面涉及角色首页入口，顺手检查默认跳转和返回路径 -- 如果页面涉及钱包或收款人选择，优先检查现有 store / utils 是否已有跨页缓存 -- 如果页面是活动专题，先判断是否需要做成独立业务目录 +新增 API 建议： -## 12. 已知现状 +- 明显新业务域：新增 `src/api/.js`。 +- 现有业务小扩展：复用已有 API 文件。 +- POST 无参数：传 `{}`。 +- 大整数 ID：保持字符串。 -### 12.1 文档历史 +新增活动页建议： -- 仓库原有 `README.md` 和 `START.md` 已经过时 -- 从现在开始，这份 `docs/项目详情.md` 是主维护文档 -- 根目录文档只保留跳转作用 +- 先建页面信息 md。 +- 再建 `page.config.js`。 +- 扫描本地 OSS 图片清单。 +- 生成基础 loading、背景、模块容器。 +- 逐个模块迭代，不一次性生成所有业务。 -### 12.2 自动化保障 +## 15. 脚本与版本 -- 当前没有 `test` 脚本 -- `lint` 使用的是 `eslint . --fix`，属于带修改的命令 -- 构建健康度需要通过实际 `build` 验证 +脚本目录：`scripts` -### 12.3 依赖管理 +当前脚本： -- 当前没有锁文件 -- 不同环境下安装结果可能出现细微差异 +- `generate-version.js`：构建后生成版本文件。 +- `build-with-version.js`：带版本日志控制的构建脚本。 +- `sync-security-docs.js`：同步安全文档。 -### 12.4 工作区状态 +版本检查： -- 当前工作区至少存在 `.env.development` 的本地改动 -- 后续协作时默认不要重置用户本地环境配置 +- 文件：`src/utils/versionChecker.js` +- 构建后版本信息写入 `dist/version.json`。 +- 运行时可通过 `VITE_ENABLE_VERSION_CHECK` 开启版本检查。 +- 默认每 5 分钟轮询一次。 +- `major` 更新会清理更完整缓存。 +- `minor/patch` 会检查图片缓存版本并清理 session 数据。 -### 12.5 架构现状判断 +## 16. 已知现状与风险 -项目当前是： +### 16.1 README 路径 -- 业务分区清晰 -- 权限和宿主适配已有固定套路 -- 页面初始化开始抽象 -- 但页面组件仍偏厚 -- `utils/` 承担了较多基础设施和状态职责 +当前 `README.md` 和 `START.md` 仍指向 `docs/project-details.md`，但当前主维护文档是： -这意味着后续做新页面时，优先遵循现有模式，必要时小步抽象，不建议一边做业务一边大改整体架构。 +- `docs/项目详情.md` -## 13. 关键文件索引 +后续可以按需要同步根目录入口文档。 -后续接手最常看的文件建议从这里进入： +### 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/usePageInitialization.js` -- `src/utils/http.js` - `src/utils/appBridge.js` -- `src/utils/userStore.js` -- `src/locales/i18n.js` -- `src/views/HostCenter/index.vue` -- `src/views/AgencyCenter/index.vue` +- `src/utils/appConnector.js` +- `src/utils/appConnectionManager.js` +- `src/utils/versionChecker.js` -## 14. 后续维护建议 +资源： -如果以后继续让我参与这个项目，最省沟通成本的方式是： +- `src/config/imagePaths.js` +- `src/directives/smartImage.js` +- `src/utils/image/imagePreloader.js` +- `src/utils/image/imageCacheManager.js` -- 新需求先说明属于哪个业务域 -- 标明是否为公共页或角色页 -- 标明是否涉及 App 桥接、权限、钱包、邀请、排行榜、活动中的任一已有体系 +活动页： -这样我可以直接沿用这份文档里的路径和规则落地，不需要每次从头扫描仓库。 -# 项目快速综述与建议（2026-04-16） +- `docs/活动页/建页/建页执行流程.md` +- `docs/活动页/建页/建页操作模板.md` +- `docs/活动页/建页/建页资料库.md` +- `src/views/Activities/WorldCup/页面创建信息.md` +- `src/views/Activities/WorldCup/世界杯接口说明.md` -**总体概况** -- 类型：运行在原生 App WebView 内的多业务 H5 前端（管理/运营中心 + 活动/排行榜聚合）。 -- 技术栈：Vue 3 + Vite 7 + Pinia 3 + Vue Router 4 + Vue I18n 11 + Vant 4。 -- 路由模式：Hash（便于 App 内离线/弱网与无后端改写）。 -- 目录核心：src 下业务域清晰（views/api/stores/utils/router/locales）。 +权限与安全： -**启动与构建** -- Node 要求：^20.19.0 || >=22.12.0（package.json）。 -- 常用脚本：dev/dev:test/dev:prod/build/build:test/build:prod/preview/lint。 -- 构建后执行 scripts/generate-version.js 生成 dist/version.json 供版本更新检测使用。 +- `src/config/security.js` +- `src/utils/runtimeSecurity.js` +- `src/utils/protectedAssets.js` +- `docs/安全/前端加固-中文.md` -**关键配置** -- Vite：按需注册 Vant 组件（unplugin-vue-components + VantResolver）、@ 指向 src、产物文件名带时间戳避免缓存（vite.config.js）。 -- 环境变量：.env* 多套，通过 import.meta.env 读取（utils/env.js）。 +构建： -**入口与初始化链路** -- src/main.js：注册样式/指令 → Pinia（含持久化）→ Router → I18n 初始化（从 store/URL 获取语言并设置 dir）→ 版本检测（周期轮询，必要时静默更新）。 -- App 适配：通过 ppBridge/ppConnectionManager 兼容 window.app/window.webkit/window.FlutterPageControl，解析原生注入头信息并写入 HTTP 公共请求头。 - -**路由与权限** -- 路由：src/router/index.js 动态按需加载，统一前置守卫 installRouteGuard。 -- 权限：permissionManager 基于角色矩阵（Admin/BDLeader/BD/Agent/Anchor/FreightAgent/Guest）判定可访问页面并决定默认首页；公共页（排行榜/活动/充值相关）可直接访问。 - -**状态与多语言** -- 状态：Pinia + 持久化（如 stores/lang 等）。 -- 多语言：默认 en，支持 r/tr/bn；阿语自动设置 dir=rtl（locales/i18n.js）。 - -**API 与网络** -- HTTP 封装：utils/http.js 基于 fetch，统一 ApiError、公共头、FormData/JSON 处理，调试模式打印环境和网关信息。 -- API 模块：src/api/ 按业务拆分（钱包/排行/充值/活动/邀请等）。 - -**页面与业务域** -- 中心类：AdminCenter/AgencyCenter/BDCenter/BDLeaderCenter/HostCenter/Coin Seller。 -- 活动类：Activities/* 与固定活动入口（如 echarge-reward/login-reward）。 -- 排行类：Ranking/*（Couple/GamesKing/WeeklyStar/Overall/TopList）。 -- 钱包与收支： iews/Wallet/*。 - -**资产与性能** -- 静态资源分层：icons/images/fonts；图片指令 -smart-img、预加载与缓存版本控制（utils/image/*，config/imageCacheVersion.js）。 -- 产物强制避缓存：输出名带时间戳（vite.config.js）。 - -**本地开发与联调** -- 启动： -pm install && npm run dev。 -- 代理：/oss 指向阿里云 OSS，并移除缓存相关响应头，避免浏览器缓存干扰（vite.config.js/server.proxy）。 -- 非 App 环境：ppBridge 在开发模式注入 mock 头，便于浏览器调试。 - -**风险与改进建议** -- 注释乱码：多处中文注释出现编码乱码，建议统一 UTF-8（无 BOM）并清理日志字符串，提升可维护性。 -- 错误处理：http.js 对非 JSON 错误响应尝试 esponse.json() 可能抛错，建议先 ry json()，失败则回退 ext() 并封装。 -- 类型与约束：当前为 JS 项目，建议为核心模块补充 JSDoc/严格 eslint 规则；中长期可评估迁移 TS。 -- 测试缺失：缺少单测/E2E，建议为路由守卫、权限矩阵、HTTP 封装补充最小可用测试。 -- I18n 完整性：建议在构建阶段引入 key 覆盖校验，运行期对缺失项告警。 - -**可选后续工作（如需我协助）** -- 增补《联调自检页》（显示 env、headers、权限判定与路由重定向结果）。 -- 输出“页面-角色访问表”与“守卫时序图”，辅助排错与验收。 -- 编写小型 CI 检查：i18n key 校验、eslint 严格规则与构建产物体积对比。 +- `vite.config.js` +- `scripts/generate-version.js` +- `scripts/build-with-version.js`