715 lines
19 KiB
Markdown
715 lines
19 KiB
Markdown
# Likei H5 项目详情
|
||
|
||
## 1. 项目定位
|
||
|
||
`likei-h5` 是一个运行在宿主 App WebView 中的多业务 H5 项目，技术栈以 `Vue 3 + Vite + Pinia + Vue Router + Vue I18n + Vant` 为主。
|
||
|
||
它不是单一落地页，而是一个按角色和业务域拆分的移动端前端集合，覆盖管理后台入口、代理中心、主播中心、钱包、充值、邀请、排行榜和活动页等场景。
|
||
|
||
当前运行模型默认优先适配 App 宿主环境，再兼容浏览器开发环境。
|
||
|
||
## 2. 快速启动
|
||
|
||
### 2.1 环境要求
|
||
|
||
- Node 版本: `^20.19.0 || >=22.12.0`
|
||
- 包管理器: 当前仓库没有锁文件，默认按 `npm` 命令使用
|
||
|
||
### 2.2 常用命令
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
npm run dev:test
|
||
npm run dev:prod
|
||
npm run build
|
||
npm run build:test
|
||
npm run build:prod
|
||
npm run build:atu-prod
|
||
npm run preview
|
||
npm run lint
|
||
```
|
||
|
||
### 2.3 环境文件
|
||
|
||
根目录当前可见的环境文件包括：
|
||
|
||
- `.env`
|
||
- `.env.development`
|
||
- `.env.production`
|
||
- `.env.production-atu`
|
||
- `.env.test`
|
||
|
||
已确认工作区当前存在本地环境文件改动，至少 `.env.development` 不是干净状态。后续改代码时不要默认重置环境文件。
|
||
|
||
### 2.4 构建说明
|
||
|
||
- 构建入口使用 `vite build`
|
||
- 构建后会执行 `scripts/generate-version.js`
|
||
- 该脚本会在 `dist/version.json` 写入版本信息
|
||
- 当前仓库没有测试脚本，`build` 更接近健康检查而不是测试替代
|
||
|
||
## 3. 架构总览
|
||
|
||
### 3.1 启动主链路
|
||
|
||
项目主链路从 `src/main.js` 开始：
|
||
|
||
1. 注册全局样式
|
||
2. 注册 `Pinia`
|
||
3. 注册 `Router`
|
||
4. 初始化 `i18n`
|
||
5. 执行版本检查
|
||
6. 挂载应用
|
||
|
||
核心入口文件：
|
||
|
||
- `src/main.js`
|
||
- `src/App.vue`
|
||
- `src/router/index.js`
|
||
|
||
### 3.2 运行时核心链路
|
||
|
||
```text
|
||
main.js
|
||
-> router.beforeEach
|
||
-> routeGuard
|
||
-> appBridge / appConnectionManager
|
||
-> http headers 注入
|
||
-> 拉取用户资料 / 身份
|
||
-> permissionManager 计算角色权限
|
||
-> 放行到对应页面
|
||
-> 页面按需调用各自 API
|
||
```
|
||
|
||
### 3.3 宿主 App 适配
|
||
|
||
宿主适配相关逻辑集中在：
|
||
|
||
- `src/utils/appBridge.js`
|
||
- `src/utils/appConnectionManager.js`
|
||
- `src/utils/routeGuard.js`
|
||
|
||
当前桥接代码兼容以下宿主注入方式：
|
||
|
||
- `window.app`
|
||
- `window.webkit`
|
||
- `window.FlutterPageControl`
|
||
|
||
说明：
|
||
|
||
- 项目默认假设自己运行在 App 容器中
|
||
- 浏览器模式主要用于开发调试
|
||
- 宿主传入的认证和设备信息会被解析后写入公共请求头
|
||
|
||
### 3.4 路由与权限
|
||
|
||
路由集中定义在 `src/router/index.js`，使用的是 `createWebHashHistory`。
|
||
|
||
这说明项目路由模型偏向嵌入式 H5，路径切换依赖 hash，而不是服务端 history 回退。
|
||
|
||
权限系统由以下文件共同组成：
|
||
|
||
- `src/utils/routeGuard.js`
|
||
- `src/utils/permissionManager.js`
|
||
- `src/api/wallet.js` 中的身份接口
|
||
- `src/utils/userStore.js`
|
||
|
||
整体机制是：
|
||
|
||
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. 目录结构
|
||
|
||
这里只记录高价值目录，不做全量文件罗列。
|
||
|
||
```text
|
||
.
|
||
├─ public/ 浏览器调试和静态入口文件
|
||
├─ scripts/ 构建辅助脚本
|
||
├─ src/
|
||
│ ├─ api/ 按业务域拆分的接口层
|
||
│ ├─ assets/ 图片、图标、字体、基础样式
|
||
│ ├─ components/ 公共组件
|
||
│ ├─ config/ 配置类文件
|
||
│ ├─ directives/ 自定义指令
|
||
│ ├─ locales/ 多语言资源和 i18n 初始化
|
||
│ ├─ router/ 路由定义
|
||
│ ├─ stores/ Pinia store
|
||
│ ├─ styles/ 全局样式和字体
|
||
│ ├─ utils/ 基础设施、桥接、权限、缓存、工具函数
|
||
│ └─ views/ 页面级业务模块
|
||
├─ .env* 多环境配置
|
||
├─ vite.config.js Vite 配置
|
||
└─ package.json 脚本和依赖
|
||
```
|
||
|
||
## 5. 页面与业务模块地图
|
||
|
||
### 5.1 Landing / 公共入口
|
||
|
||
目录：
|
||
|
||
- `src/views/LandingPage`
|
||
- `src/views/ApplyHost`
|
||
- `src/views/PlatformPolicy`
|
||
|
||
主要职责：
|
||
|
||
- 加载页
|
||
- 非 App 环境提示
|
||
- 申请加入流程
|
||
- 平台政策页
|
||
|
||
### 5.2 角色中心
|
||
|
||
目录：
|
||
|
||
- `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
|
||
- 银行卡
|
||
- 支付结果
|
||
|
||
这部分与角色中心页耦合较高，很多中心页会跳到这里完成具体资金操作。
|
||
|
||
### 5.4 充值与支付
|
||
|
||
目录：
|
||
|
||
- `src/views/Recharge`
|
||
|
||
主要包含：
|
||
|
||
- 充值主页
|
||
- 支付方式
|
||
- 地图
|
||
- 充值引导
|
||
|
||
### 5.5 邀请体系
|
||
|
||
目录：
|
||
|
||
- `src/views/Invitation`
|
||
|
||
主要包含邀请不同角色和邀请注册相关页面。
|
||
|
||
### 5.6 排行榜
|
||
|
||
目录：
|
||
|
||
- `src/views/Ranking`
|
||
|
||
目前包含：
|
||
|
||
- `Couple`
|
||
- `GamesKing`
|
||
- `KingAndQueen`
|
||
- `Overall`
|
||
- `WeeklyStar`
|
||
|
||
### 5.7 活动页
|
||
|
||
目录：
|
||
|
||
- `src/views/Activities`
|
||
|
||
当前活动以专题形式存在，通常是独立业务页或赛季页，例如：
|
||
|
||
- `LuckyDollars`
|
||
- `SpringFestival`
|
||
- `LesserBairam`
|
||
- `LoginReward`
|
||
- `Reward`
|
||
|
||
特点：
|
||
|
||
- 页面独立性高
|
||
- 生命周期强
|
||
- 经常带倒计时、排行榜、奖励展示等逻辑
|
||
|
||
## 6. 权限与角色模型
|
||
|
||
权限中心文件：
|
||
|
||
- `src/utils/permissionManager.js`
|
||
- `src/utils/routeGuard.js`
|
||
|
||
### 6.1 角色列表
|
||
|
||
当前角色常量定义为：
|
||
|
||
- `admin`
|
||
- `bdLeader`
|
||
- `bd`
|
||
- `agent`
|
||
- `anchor`
|
||
- `freightAgent`
|
||
- `guest`
|
||
|
||
### 6.2 默认落地页
|
||
|
||
当前默认落地页映射为：
|
||
|
||
- `admin` -> `/admin-center`
|
||
- `freightAgent` -> `/coin-seller`
|
||
- `agent` -> `/agency-center`
|
||
- `bdLeader` -> `/bd-leader-center`
|
||
- `bd` -> `/bd-center`
|
||
- `anchor` -> `/host-center`
|
||
- `guest` -> `/apply`
|
||
|
||
### 6.3 权限模型特点
|
||
|
||
- 权限是按角色和页面路径做映射，不是按按钮或接口粒度做权限
|
||
- `PUBLIC_PAGES` 中定义了公共可访问页
|
||
- 多角色用户会先算出所有角色，再根据优先级选主角色
|
||
- 页面权限判断核心方法是 `hasPagePermission`
|
||
|
||
### 6.4 什么时候需要改权限配置
|
||
|
||
如果新增页面属于以下情况之一，通常需要同步修改 `permissionManager.js`：
|
||
|
||
- 新增角色专属页面
|
||
- 新增只有部分角色可访问的功能页
|
||
- 新增公共页
|
||
- 新增角色默认首页
|
||
|
||
如果只是现有角色中心下的子功能页，也建议明确补进对应角色的权限数组，避免路由守卫后续重定向异常。
|
||
|
||
## 7. 数据与状态
|
||
|
||
这个项目不是纯 Pinia 架构，而是 `Pinia + utils 单例缓存` 的混合方式。
|
||
|
||
### 7.1 Pinia store
|
||
|
||
当前 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`
|
||
|
||
其中最常见的是：
|
||
|
||
- `lang` 负责语言选择和持久化
|
||
- `identity` 负责页面层身份标签
|
||
|
||
### 7.2 utils 单例缓存
|
||
|
||
下面这些文件承担了比普通工具函数更重的状态职责：
|
||
|
||
- `src/utils/userStore.js`
|
||
- `src/utils/appConnectionManager.js`
|
||
- `src/utils/payeeStore.js`
|
||
- `src/utils/applyStore.js`
|
||
- `src/utils/coinSellerStore.js`
|
||
|
||
它们主要负责：
|
||
|
||
- 用户资料缓存
|
||
- 团队信息缓存
|
||
- App 连接状态缓存
|
||
- 页面跨跳转时的业务状态缓存
|
||
|
||
### 7.3 页面级状态
|
||
|
||
绝大多数页面仍然保留较多页面内 `ref/reactive` 状态，尤其是中心页和钱包页。
|
||
|
||
这意味着：
|
||
|
||
- 通用能力已经抽出来一部分
|
||
- 业务细节仍然主要留在页面组件内部
|
||
|
||
后续改新页面时，优先判断状态到底属于：
|
||
|
||
- 全局复用
|
||
- 多页跨跳转共享
|
||
- 单页临时状态
|
||
|
||
不要默认都进 Pinia。
|
||
|
||
## 8. API 分层
|
||
|
||
接口层目录为 `src/api/`，按业务域拆分，而不是按 HTTP 方法拆分。
|
||
|
||
当前可见模块包括：
|
||
|
||
- `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`
|
||
|
||
### 8.1 HTTP 基础层
|
||
|
||
请求基础能力集中在 `src/utils/http.js`：
|
||
|
||
- `request`
|
||
- `get`
|
||
- `post`
|
||
- `put`
|
||
- `del`
|
||
|
||
同时负责：
|
||
|
||
- 基础 API URL 拼接
|
||
- 公共请求头注入
|
||
- App 桥接后的 header 更新
|
||
- `ApiError` 包装
|
||
- HTTP 错误和业务错误归一化
|
||
|
||
### 8.2 页面消费方式
|
||
|
||
页面通常直接从 `src/api/*` 导入接口方法使用，不会再经过 service facade。
|
||
|
||
常见模式是：
|
||
|
||
1. 页面或组合函数导入业务 API
|
||
2. 调接口后直接在页面中做字段转换
|
||
3. 再把结果写进页面状态
|
||
|
||
这意味着新增页面时，最好沿用现有风格，不要中途引入另一套完全不同的 service 架构，除非是一次明确的重构。
|
||
|
||
### 8.3 什么时候新增 API 文件
|
||
|
||
建议在以下情况新增 `src/api/*.js`：
|
||
|
||
- 新页面属于新的业务域
|
||
- 原有接口文件已经明显跨域和膨胀
|
||
- 新模块后续会持续扩展
|
||
|
||
如果只是现有钱包、邀请、活动、排行榜模块里的小功能，优先复用已有 API 文件。
|
||
|
||
## 9. 国际化与样式
|
||
|
||
### 9.1 国际化
|
||
|
||
国际化入口：
|
||
|
||
- `src/locales/i18n.js`
|
||
|
||
当前语言资源：
|
||
|
||
- `zh`
|
||
- `en`
|
||
- `ar`
|
||
- `tr`
|
||
- `bn`
|
||
|
||
特点：
|
||
|
||
- 支持通过 `Pinia` 中的语言状态驱动切换
|
||
- 会根据语言设置 `document.documentElement` 的 `lang` 和 `dir`
|
||
- 已显式支持 RTL，主要是阿拉伯语场景
|
||
|
||
### 9.2 样式入口
|
||
|
||
全局样式入口：
|
||
|
||
- `src/assets/main.css`
|
||
- `src/styles/fonts.css`
|
||
- `src/styles/global.css`
|
||
|
||
资源目录：
|
||
|
||
- `src/assets/icon`
|
||
- `src/assets/images`
|
||
- `src/assets/fonts`
|
||
|
||
页面样式目前仍以页面内 `scoped style` 和局部内联样式为主，说明 UI 复用度还没有完全组件化。
|
||
|
||
## 10. 开发约定
|
||
|
||
这一节是后续你我一起做新页面时最实用的部分。
|
||
|
||
### 10.1 新页面放哪里
|
||
|
||
优先按业务域放到 `src/views/` 下已有模块目录中。
|
||
|
||
建议：
|
||
|
||
- 角色首页相关功能放到对应角色目录
|
||
- 钱包相关放到 `src/views/Wallet`
|
||
- 排行榜放到 `src/views/Ranking`
|
||
- 活动专题放到 `src/views/Activities`
|
||
|
||
只有在确定是全新业务域时，才新开一级目录。
|
||
|
||
### 10.2 何时复用 `usePageInitialization`
|
||
|
||
适合复用：
|
||
|
||
- 角色中心首页
|
||
- 需要统一拉用户资料、团队信息、余额、工作统计的页面
|
||
- 需要在页面加载时完成 App 连接和数据初始化的页面
|
||
|
||
不一定适合复用：
|
||
|
||
- 单功能表单页
|
||
- 活动专题页
|
||
- 排行榜页
|
||
- 只依赖少量接口的轻页面
|
||
|
||
### 10.3 何时新增 `api/*`
|
||
|
||
优先复用现有 API 文件。只有在业务域明显独立时才新增新文件。
|
||
|
||
### 10.4 何时修改权限配置
|
||
|
||
新增页面只要不是公共页，默认都要检查：
|
||
|
||
- 是否需要在 `src/router/index.js` 注册
|
||
- 是否需要在 `src/utils/permissionManager.js` 增加角色访问权限
|
||
- 是否需要更新默认落地页或公共页配置
|
||
|
||
### 10.5 何时修改用户或连接缓存
|
||
|
||
如果新页面依赖：
|
||
|
||
- 用户资料
|
||
- 团队资料
|
||
- App 宿主头信息
|
||
|
||
优先复用：
|
||
|
||
- `src/utils/userStore.js`
|
||
- `src/utils/appConnectionManager.js`
|
||
|
||
不要在页面里再新造一份重复缓存。
|
||
|
||
### 10.6 文档维护原则
|
||
|
||
后续新增页面、角色、模块后，优先更新这份文档，而不是新增平行说明文档。
|
||
|
||
## 11. 新页面接入流程
|
||
|
||
后续新增一个新页面时，建议按下面顺序处理：
|
||
|
||
1. 建页面目录
|
||
在合适的 `src/views/<业务域>/` 下创建页面文件，优先沿用现有目录结构。
|
||
|
||
2. 注册路由
|
||
在 `src/router/index.js` 中新增路由，明确 `path`、`name`、`component` 和 `meta`。
|
||
|
||
3. 判断是否需要权限配置
|
||
如果不是公共页，检查 `src/utils/permissionManager.js` 是否要补角色权限。
|
||
|
||
4. 判断是否复用页面初始化
|
||
如果页面需要统一接 App、拉用户、余额、团队、统计数据，优先考虑 `usePageInitialization`。
|
||
|
||
5. 新增 API 模块或复用现有 API
|
||
先看 `src/api/` 是否已有相近业务域，再决定是否新增文件。
|
||
|
||
6. 接入 i18n 与公共组件
|
||
文案走 `src/locales/*.json`，头部、遮罩、提示等尽量复用现有组件。
|
||
|
||
补充建议：
|
||
|
||
- 如果页面涉及角色首页入口，顺手检查默认跳转和返回路径
|
||
- 如果页面涉及钱包或收款人选择，优先检查现有 store / utils 是否已有跨页缓存
|
||
- 如果页面是活动专题，先判断是否需要做成独立业务目录
|
||
|
||
## 12. 已知现状
|
||
|
||
### 12.1 文档历史
|
||
|
||
- 仓库原有 `README.md` 和 `START.md` 已经过时
|
||
- 从现在开始，这份 `docs/project-details.md` 是主维护文档
|
||
- 根目录文档只保留跳转作用
|
||
|
||
### 12.2 自动化保障
|
||
|
||
- 当前没有 `test` 脚本
|
||
- `lint` 使用的是 `eslint . --fix`，属于带修改的命令
|
||
- 构建健康度需要通过实际 `build` 验证
|
||
|
||
### 12.3 依赖管理
|
||
|
||
- 当前没有锁文件
|
||
- 不同环境下安装结果可能出现细微差异
|
||
|
||
### 12.4 工作区状态
|
||
|
||
- 当前工作区至少存在 `.env.development` 的本地改动
|
||
- 后续协作时默认不要重置用户本地环境配置
|
||
|
||
### 12.5 架构现状判断
|
||
|
||
项目当前是：
|
||
|
||
- 业务分区清晰
|
||
- 权限和宿主适配已有固定套路
|
||
- 页面初始化开始抽象
|
||
- 但页面组件仍偏厚
|
||
- `utils/` 承担了较多基础设施和状态职责
|
||
|
||
这意味着后续做新页面时，优先遵循现有模式，必要时小步抽象，不建议一边做业务一边大改整体架构。
|
||
|
||
## 13. 关键文件索引
|
||
|
||
后续接手最常看的文件建议从这里进入：
|
||
|
||
- `src/main.js`
|
||
- `src/router/index.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`
|
||
|
||
## 14. 后续维护建议
|
||
|
||
如果以后继续让我参与这个项目，最省沟通成本的方式是：
|
||
|
||
- 新需求先说明属于哪个业务域
|
||
- 标明是否为公共页或角色页
|
||
- 标明是否涉及 App 桥接、权限、钱包、邀请、排行榜、活动中的任一已有体系
|
||
|
||
这样我可以直接沿用这份文档里的路径和规则落地，不需要每次从头扫描仓库。
|
||
# 项目快速综述与建议（2026-04-16）
|
||
|
||
**总体概况**
|
||
- 类型：运行在原生 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 供版本更新检测使用。
|
||
|
||
**关键配置**
|
||
- 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 严格规则与构建产物体积对比。
|