diff --git a/.env.development b/.env.development index cff075a..309ce5c 100644 --- a/.env.development +++ b/.env.development @@ -1,11 +1,35 @@ # 开发环境 VITE_NODE_ENV=development -VITE_API_BASE_URL=https://apitest.azizichat.com -# VITE_API_BASE_URL=http://192.168.0.136:1100 +# VITE_API_BASE_URL=https://apitest.azizichat.com +# VITE_API_BASE_URL=http://192.168.0.117:30100 VITE_APP_TITLE=Azizi H5 (Development) # 普通用户 8826602 -#VITE_USER_AUTH=EB4BAD4C6439CF503B16267C712F5AB6.djIlM0ExOTU3MzQ1MzEyOTYxNTI3ODA5JTNBTElLRUklM0ExNzU4Mjc4MDEzNzQ0JTNBMTc1NTY4NjAxMzc0NA== - +# VITE_USER_AUTH=EB4BAD4C6439CF503B16267C712F5AB6.djIlM0ExOTU3MzQ1MzEyOTYxNTI3ODA5JTNBTElLRUklM0ExNzU4Mjc4MDEzNzQ0JTNBMTc1NTY4NjAxMzc0NA== # 代理用户 8826603 -VITE_USER_AUTH=45C34ABC2A47CB323383D9E78175DB2D.djIlM0ExOTkwNjg1NTY1MzMzNTkwMDE3JTNBTElLRUklM0ExNzcyNzgyNTI1MjIzJTNBMTc3MDE5MDUyNTIyMw== \ No newline at end of file +# VITE_USER_AUTH=1004D0372D9E58C41EDC691657AD5FAB.djIlM0ExOTkwNjg1NTY1MzMzNTkwMDE3JTNBTElLRUklM0ExNzc3NDQzNzg2OTI2JTNBMTc3NDg1MTc4NjkyNg== + +# 测试用户 8832199 +# VITE_USER_AUTH=1004D0372D9E58C41EDC691657AD5FAB.djIlM0ExOTkwNjg1NTY1MzMzNTkwMDE3JTNBTElLRUklM0ExNzc3NDQzNzg2OTI2JTNBMTc3NDg1MTc4NjkyNg== +# 测试用户 8826795 +# VITE_USER_AUTH=3EC743264ADF552F610F30C8DC00C650.djIlM0ExOTYzNzg5OTAyMDcxNTA4OTkzJTNBTElLRUklM0ExNzc3NzE0MTY0NTg0JTNBMTc3NTEyMjE2NDU4NA== +# 测试用户 8826796 +# VITE_USER_AUTH=A6AD39218DFC97E5945925770A08D78A.djIlM0ExOTYzNzkwMDM3NzQwNDY2MTc4JTNBTElLRUklM0ExNzc4NzMwODg2MDM0JTNBMTc3NjEzODg4NjAzNA== + +VITE_API_BASE_URL=https://api.likeichat.com +# 正式用户 8832199 +VITE_USER_AUTH=9125B94C72CAA512039AD0F85348F56C.djIlM0ExOTkwNjg1NTY1MzMzNTkwMDE3JTNBTElLRUklM0ExNzc2NTEzNDAyMjM4JTNBMTc3MzkyMTQwMjIzOA== +# 正式用户 8826796 +# VITE_USER_AUTH=23116F749A21862A2B7217CDEE0FBF45.djIlM0ExOTYzNzkwMDM3NzQwNDY2MTc4JTNBTElLRUklM0ExNzc4OTAxNTg4MDA5JTNBMTc3NjMwOTU4ODAwOQ== +# 正式用户 10086 +# VITE_USER_AUTH=E71AE3738A4FA44BD2E895CBE176AC81.djIlM0EyMDA1ODU0NTE0ODQzMTYwNTc4JTNBTElLRUklM0ExNzc4NjQwMzczOTU4JTNBMTc3NjA0ODM3Mzk1OA== + +# VITE_API_BASE_URL=https://api.atuchat.com +# 正式用户 8832199 +# VITE_USER_AUTH=A20B9AAA2E7367D93FF576F4DF8AE2D6.djIlM0ExOTkwNjg1NTY1MzMzNTkwMDE3JTNBQVRZT1UlM0ExNzc4Mjk4MTA1Mzg3JTNBMTc3NTcwNjEwNTM4Nw== +# 正式用户 8826795 +# VITE_USER_AUTH=2B604FE97548D46E87E9799CFCB1EE64.djIlM0ExOTYzNzg5OTAyMDcxNTA4OTkzJTNBQVRZT1UlM0ExNzc4MjIxNzM2MTY5JTNBMTc3NTYyOTczNjE2OQ== +# 正式用户 8826796 +# VITE_USER_AUTH=74B5514EE533EAB873A2C6547E8B683B.djIlM0ExOTYzNzkwMDM3NzQwNDY2MTc4JTNBQVRZT1UlM0ExNzc4MjMyODM0MjAwJTNBMTc3NTY0MDgzNDIwMA== +# 正式用户 19011 +# VITE_USER_AUTH=ED4BC8E374218B276C31A1D32F507BBE.djIlM0EyMDM5OTg5MDk4OTY0NTMzMjUwJTNBQVRZT1UlM0ExNzc4NjU2NjE4MDM5JTNBMTc3NjA2NDYxODAzOQ== \ No newline at end of file diff --git a/README.md b/README.md index 0b2dc0c..ec561db 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,19 @@ -# Azizi H5 项目 +# Likei H5 -这是一个基于 Vue 3 + Vite 的移动端 H5 应用，包含申请加入团队和主播中心两个主要页面。 +项目主文档已迁移到 [docs/project-details.md](docs/project-details.md)。 -## 项目结构 - -``` -src/ -├── components/ -│ ├── MobileHeader.vue # 公共头部导航组件 -│ └── HelloWorld.vue # 示例组件 -├── views/ -│ ├── HomeView.vue # 首页（带导航按钮） -│ ├── ApplyView.vue # 申请加入团队页面 -│ ├── HostCenterView.vue # 主播中心页面 -│ └── AboutView.vue # 关于页面 -├── router/ -│ └── index.js # 路由配置 -├── assets/ # 静态资源 -├── App.vue # 根组件 -└── main.js # 入口文件 -``` - -## 页面说明 - -### 1. 申请加入团队页面 (`/apply`) -- 包含申请表单 -- 用户可以输入代理商ID -- 有帮助提示功能 -- 支持表单验证 - -### 2. 主播中心页面 (`/host-center`) -- 显示用户信息和头像 -- 显示收入统计 -- 显示今日任务进度 -- 包含交换金币、转账、提现等功能按钮 -- 点击Date按钮跳转到历史薪资页面 -- 点击Exchange按钮跳转到兑换金币页面 - -### 3. 主播设置页面 (`/host-setting`) -- 显示代理商信息 -- 银行卡管理 -- KYC认证信息 -- 支持离开代理商操作 - -### 4. 历史薪资页面 (`/history-salary`) -- 按月份查看薪资记录 -- 详细的收入分解（基础薪资、奖金、佣金、扣款） -- 支付状态显示 -- 月度统计汇总 - -### 5. 兑换金币页面 (`/exchange-gold-coins`) -- 显示可用余额 -- 收款人选择和管理 -- 金币选择网格 -- 支持多选金币进行转账 -- 点击收款人可跳转到搜索页面 - -### 6. 搜索收款人页面 (`/search-payee`) -- 实时搜索功能 -- 支持按ID或姓名搜索 -- 显示用户标签（Host、Agency、Salary） -- 搜索结果选择和添加 - -### 3. 公共组件 - -#### MobileHeader.vue -可复用的移动端头部导航组件，支持： -- 自定义标题 -- 返回按钮（可选） -- 帮助按钮（可选） -- 自定义事件处理 - -## 技术特点 - -1. **Vue 3 Composition API**: 使用最新的 Vue 3 语法 -2. **响应式设计**: 适配手机和桌面端 -3. **组件化开发**: 公共组件可复用 -4. **简洁的样式**: 使用原生CSS，无外部UI库依赖 -5. **路由管理**: 使用 Vue Router 4 - -## 开发运行 +## 快速开始 ```bash -# 安装依赖 npm install - -# 开发模式运行 npm run dev - -# 构建生产版本 -npm run build - -# 预览生产版本 -npm run preview ``` -## 代码特点 +## 文档入口 -- **适合初学者**: 代码结构清晰，注释完整 -- **无复杂依赖**: 只使用必要的Vue生态工具 -- **移动端优先**: 专为移动端体验设计 -- **易于扩展**: 组件化架构便于添加新功能 +- 项目详情与开发接手说明: [docs/project-details.md](docs/project-details.md) +- 快速开始跳转页: [START.md](START.md) -## 访问路径 +## 说明 -- 首页: `/` -- 申请页面: `/apply` -- 主播中心: `/host-center` -- 主播设置: `/host-setting` -- 历史薪资: `/history-salary` -- 兑换金币: `/exchange-gold-coins` -- 搜索收款人: `/search-payee` -- 关于页面: `/about` +`README.md` 现在只作为仓库入口页使用，详细架构、模块说明、开发约定和新页面接入流程统一维护在 `docs/project-details.md`。 \ No newline at end of file diff --git a/START.md b/START.md index 7966350..4c5be40 100644 --- a/START.md +++ b/START.md @@ -1,85 +1,21 @@ -# 快速开始 +# Quick Start -## 项目说明 -这是一个Vue3移动端H5项目的演示，包含两个主要页面： -1. **申请加入团队页面** - 模拟用户申请成为主播的流程 -2. **主播中心页面** - 显示主播的收入、任务等信息 +详细文档已统一迁移到 [docs/project-details.md](docs/project-details.md)。 -## 启动步骤 +## 最常用命令 -1. **安装依赖** - ```bash - npm install - ``` - -2. **启动开发服务器** - ```bash - npm run dev - ``` - -3. **访问应用** - - 在浏览器中打开显示的本地地址（通常是 http://localhost:5173） - - 建议用浏览器的移动端模拟器查看效果 - -## 页面预览 - -### 首页 -- 包含三个导航按钮 -- 点击可以跳转到对应的功能页面 - -### 申请页面 (/apply) -- 包含申请表单 -- 输入代理商ID -- 点击帮助按钮查看提示 - -### 主播中心 (/host-center) -- 查看用户信息 -- 查看收入统计 -- 查看任务进度 -- 操作按钮（交换、转账、提现） -- Date按钮跳转到历史薪资 -- Exchange按钮跳转到兑换金币 - -### 主播设置 (/host-setting) -- 查看代理商信息 -- 管理银行卡信息 -- KYC认证管理 - -### 历史薪资 (/history-salary) -- 按月份查看薪资 -- 详细的收入分解 -- 月度统计信息 - -### 兑换金币 (/exchange-gold-coins) -- 金币选择和转账 -- 收款人管理 -- 点击收款人跳转搜索 - -### 搜索收款人 (/search-payee) -- 实时搜索用户 -- 按ID或名称搜索 - -## 技术亮点 - -✅ **Vue 3** - 使用最新的Composition API语法 -✅ **响应式设计** - 适配移动端和桌面端 -✅ **组件化** - MobileHeader作为公共组件复用 -✅ **路由管理** - 使用Vue Router进行页面跳转 -✅ **简洁样式** - 原生CSS，无复杂依赖 -✅ **易于理解** - 代码结构清晰，适合Vue3初学者 - -## 文件结构 -``` -src/ -├── components/MobileHeader.vue # 公共头部组件 -├── views/ -│ ├── HomeView.vue # 首页 -│ ├── ApplyView.vue # 申请页面 -│ ├── HostCenterView.vue # 主播中心 -│ ├── HostSettingView.vue # 主播设置 -│ ├── HistorySalaryView.vue # 历史薪资 -│ ├── ExchangeGoldCoinsView.vue # 兑换金币 -│ └── SearchPayeeView.vue # 搜索收款人 -├── router/index.js # 路由配置 -└── App.vue # 根组件 +```bash +npm install +npm run dev +npm run build +npm run preview ``` + +## 建议阅读顺序 + +1. 先看 [docs/project-details.md](docs/project-details.md) 了解项目结构 +2. 再根据需要进入对应业务模块和页面代码 + +## 说明 + +`START.md` 现在只保留快速入口，不再维护完整项目说明。 \ No newline at end of file diff --git a/docs/project-details.md b/docs/project-details.md new file mode 100644 index 0000000..eea843e --- /dev/null +++ b/docs/project-details.md @@ -0,0 +1,714 @@ +# 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 严格规则与构建产物体积对比。