# techhero-guangxi-uniapp-ui

**Repository Path**: defaultjs2105/techhero-guangxi-uniapp-ui

## Basic Information

- **Project Name**: techhero-guangxi-uniapp-ui
- **Description**: 广西前端初始化
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# techhero-guangxi-uniapp-ui

<a id="top"></a>

广西招生考试院公众服务平台 — 优化前端项目，基于 uni-app (Vue 3) 构建，支持多端运行。

---

## <a id="project-intro"></a>项目简介

本项目是对 `techhero-uni/` 前端工程的全面优化重构，保留所有功能逻辑和组件版本，优化程序结构，支持 iOS、Android、HarmonyOS、微信小程序、支付宝小程序、H5 多平台共存。

**原始工程：** `techhero-uni/`（源，只读）
**后端工程：** `techhero-guangxi-server/`（源，只读）
**优化工程：** `techhero-guangxi-uniapp-ui/`（本项目）

---

## <a id="tech-stack"></a>技术栈

| 层级 | 技术 |
|------|------|
| 框架 | uni-app (Vue 3) |
| 状态管理 | Pinia 2.x |
| HTTP客户端 | 自定义封装 (HMAC-SHA256签名) |
| 样式 | SCSS + 自定义图标字体 |
| 加密 | CryptoJS (AES-ECB, HMAC-SHA256) |
| 构建工具 | Vite 7（Rollup）+ Babel |
| 组件库 | @dcloudio/uni-ui 1.5.7 |

---

## <a id="platform-support"></a>平台支持

| 平台 | 状态 | 说明 |
|------|------|------|
| 微信小程序 | ✅ 已配置 | AppID: wx5c99a8ca5915fdbb |
| 支付宝小程序 | ✅ 已配置 | 需填入 AppID |
| HarmonyOS 小程序 | ✅ 已配置 | 需填入 AppID |
| iOS App | ✅ 已配置 | 需完善证书配置 |
| Android App | ✅ 已配置 | 权限已配置 |
| H5 | ✅ 已配置 | DevServer代理配置就绪 |

---

## <a id="quick-start"></a>快速开始

### 环境要求

- Node.js 18+
- HBuilderX 4.x（用于小程序/App编译）
- 微信开发者工具（微信小程序调试）
- 支付宝小程序开发者工具（支付宝小程序调试）

### 安装

```bash
cd techhero-guangxi-uniapp-ui
npm install
```

### 开发

```bash
# H5 开发服务器（带热更新）
npm run dev:h5

# 微信小程序（需HBuilderX）
# 运行 → 运行到小程序模拟器 → 微信开发者工具

# 支付宝小程序（需HBuilderX）
# 运行 → 运行到小程序模拟器 → 支付宝开发者工具
```

### 构建

```bash
npm run build:h5          # H5
npm run build:mp-weixin   # 微信小程序
npm run build:mp-alipay   # 支付宝小程序
```

### 验证

```bash
npm run verify            # 运行代码质量验证（50项检查）
```

---

## <a id="troubleshooting"></a>故障排除

| 问题 | 解决方案 |
|------|---------|
| npm install 失败 | 检查 Node.js 版本 ≥18，清除 `node_modules` 和 `package-lock.json` 重试 |
| HBuilderX 编译报错 | 检查 `manifest.json` 和 `pages.json` 语法（含条件编译注释） |
| 微信小程序白屏 | 确认合法域名已配置，或在开发者工具中关闭域名校验 |
| 路由跳转失败 | 确认使用完整子包路径（如 `/pages/login/examinee-login`，不是 `/pages/examinee-login/examinee-login`） |
| 支付宝小程序编译错误 | 确认 `mp-alipay` 配置已填入有效 AppID |

---

## <a id="git-state"></a>Git 状态记录

| 仓库 | 分支 | 最新提交 | 说明 |
|------|------|---------|------|
| `techhero-uni/` | master | `2dae3aa` — feat: 首页时间文案修改 | 源前端代码（只读） |
| `techhero-guangxi-server/` | — | `a945e1ad` — 向下取整改为四舍五入 | 源后端代码（只读） |
| `techhero-guangxi-uniapp-ui/` | master | 初始提交 | 优化后的前端代码 |

---

## <a id="directory-structure"></a>目录结构

```
techhero-guangxi-uniapp-ui/
├── .gitignore
├── README.md                    # 本文档 [↗](#top)
├── DESIGN.md                    # 交互设计文档
├── package.json                 # 依赖配置（pinia替代vuex）
├── vite.config.js               # Vite构建配置
├── babel.config.js              # Babel配置
├── pages.json                   # 路由配置（含subPackages分包）
├── manifest.json                # 应用配置（6端支持）
├── main.js                      # 入口（Pinia + sharePlugin）
├── App.vue                      # 应用根组件（adStore集中管理）
│
├── api/                         # API模块（17个，完整保留）
├── stores/                      # [新增] Pinia状态管理（5个store）
├── composables/                 # [新增] Vue3组合式函数（4个）
├── plugins/                     # [新增] sharePlugin全局分享
├── utils/                       # 工具层
│   ├── request/                 #   HTTP请求层（拆分为4个逻辑模块）
│   ├── storage.js               #   本地存储封装（TTL过期）
│   ├── format.js                #   格式化/签名/HMAC工具
│   ├── crypto.js                #   AES-ECB加密
│   ├── network.js               #   网络状态检测
│   └── ...
├── components/                  # 组件（全部kebab-case命名）
│   ├── custom-tabbar/           #   自定义底部标签栏
│   ├── collect-dialog.vue       #   收藏专业弹窗
│   ├── search-bar.vue           #   搜索输入栏
│   ├── search-key-word.vue      #   关键词联想搜索
│   └── search-select-box.vue    #   综合筛选弹窗
├── pages/                       # 页面（按功能分包）
│   ├── main/                    #   主包（main + mainIndex）
│   ├── mine/                    #   我的 分包（9页）
│   ├── login/                   #   登录 分包（3页）
│   ├── enrollment/              #   招生录取 分包（7页）
│   ├── score/                   #   分数查询 分包（2页）
│   ├── info/                    #   信息查询 分包（5页）
│   ├── admission/               #   直播投档 分包（4页）
│   └── common/                  #   公共页面 分包（10页）
├── static/                      # 静态资源（完整保留）
├── uni_modules/                 # uni_modules（49个包，完整保留）
└── scripts/
    ├── verify.mjs               # 验证脚本
    └── fix-*.mjs                # 代码修复工具脚本
```

---

## <a id="before-after-comparison"></a>Before/After 对比

### <a id="compare-1"></a>1. 状态管理

**Before:** 仅使用 `getApp().globalData` + 裸 `uni.setStorageSync/getStorageSync`。
```js
uni.setStorageSync('token', token)
uni.removeStorageSync('token')
```

**After:** Pinia 统一管理，手动同步 storage 保证向后兼容。
```js
import { useUserStore } from '@/stores/useUserStore'
const userStore = useUserStore()
userStore.login({ token, loginStatus, userRole })
```

### <a id="compare-2"></a>2. 分享功能

**Before:** 32 个页面分别导入 `shareMixin`。
**After:** 全局插件 `sharePlugin` 一次性注入，页面无需导入。

### <a id="compare-3"></a>3. 导航栏计算

**Before:** ~30 个页面重复 statusBarHeight/navigationBarHeight 计算（每页约25行）。
**After:** `useNavigationBar()` composable，一行导入。

### <a id="compare-4"></a>4. 招生计划/往年录取页面

**Before:** `enrollment-plan.vue`（1383行）和 `score-destination.vue`（1895行）各自独立，大量重复代码。
**After:** 已通过共享 composables（useDict、usePagination、useAd）和共享组件（search-bar、search-select-box）消除冗余，页面逻辑模块化。

### <a id="compare-5"></a>5. 广告状态

**Before:** App.vue onLaunch 中 20 个独立 `uni.removeStorageSync('closedAds*')`。
**After:** `useAdStore.resetAds()` 一行集中管理。

### <a id="compare-6"></a>6. HTTP 请求模块

**Before:** `utils/request/index.js` 单体文件 627 行。
**After:** 拆分为 4 个逻辑模块：`index.js`（整合）、`interceptors.js`（拦截器）、`errorHandler.js`（错误+重试）、`fileExport.js`（文件导出）。

### <a id="compare-7"></a>7. 字典数据

**Before:** `mixins/dictMixin.js` 不必要的 Promise 包裹层。
**After:** `useDict()` composable 直接返回 API Promise。

### <a id="compare-8"></a>8. 页面分包

**Before:** 40 个页面全部在主包。
**After:** 主包仅 2 页面，其余 38 页面分布在 7 个子包中。

### <a id="compare-9"></a>9. 多平台支持

**Before:** 仅 `mp-weixin`、`h5`、`app-plus`。
**After:** 新增 `mp-alipay`、`mp-harmony`，实现六端支持。

### <a id="compare-10"></a>10. 平台兼容性

**Before:** `wx.getMenuButtonBoundingClientRect()` 等多处微信专属 API 无保护。
**After:** 全部包裹 `#ifdef MP-WEIXIN` 条件编译保护，非微信平台使用 uni.* 通用 API。

### <a id="compare-11"></a>11. Vue 3 兼容

**Before:** 30+ 处 `this.$set()` 调用（Vue 2 专属，Vue 3 已移除）。
**After:** 全部替换为直接赋值（Vue 3 Proxy 响应式系统自动处理）。

### <a id="compare-12"></a>12. 代码规范

**Before:** 组件命名混用 camelCase/kebab-case，CSS 单位混用 px/rpx，pages.json 含非法 `scripts` 字段。
**After:** 组件统一 kebab-case，CSS 统一 rpx，pages.json 符合 uni-app 规范。

---

## <a id="architecture"></a>架构说明

### 数据流

```
用户操作 → 页面组件 → Pinia Store（手动同步 uni.storage）
                ↓
          Composables → API模块 → HTTP客户端
                ↓
          HMAC-SHA256签名 → 后端服务
```

### 分包策略

| 分包 | 页面数 | 预加载 | 说明 |
|------|--------|--------|------|
| 主包 (pages/main) | 2 | — | main + mainIndex |
| pages/mine | 9 | ✅ 从首页预加载 | 个人中心相关 |
| pages/enrollment | 7 | ✅ 从首页预加载 | 招生计划、往年录取 |
| pages/login | 3 | — | 登录认证 |
| pages/score | 2 | — | 分数线查询 |
| pages/info | 5 | — | 排名、问答、公告 |
| pages/admission | 4 | — | 直播、投档查询 |
| pages/common | 10 | — | 通用页面 |

---

## <a id="verification"></a>验证

```bash
npm run verify    # 自动化验证（文件完整性、导入路径、分包覆盖、平台配置等50项检查）
```

编译验证：
- H5: `npm run build:h5`
- 微信小程序: HBuilderX → 运行到微信开发者工具
- 支付宝小程序: HBuilderX → 运行到支付宝开发者工具

---

## <a id="known-limitations"></a>已知限制

- **预留组件**：`custom-header.vue`、`no-data.vue`、`ad-banner.vue` 已提取模板但尚未集成到所有页面中，各页面仍使用内联导航栏和空状态模板
- **BaseList 通用列表组件**：enrollment-plan 和 score-destination 页面已通过共享 composables 减少冗余，但提取为单一 BaseList 组件的工作仍在规划中
- **自动化测试**：当前仅有代码结构验证脚本（`npm run verify`），缺少单元测试和 E2E 测试覆盖
- **微信/支付宝 AppID**：开发环境与生产环境的 AppID 需分别配置（`manifest.json` vs `project.config.json`）

---

## <a id="notes"></a>注意事项

- 原始代码 `techhero-uni/` 和 `techhero-guangxi-server/` 为只读
- 所有 uni_modules 和组件版本与原始代码保持一致，未升级
- Pinia stores 通过各 action 方法手动同步到 `uni.setStorageSync`，保证外部代码读取兼容
- 条件编译保留所有原有 `#ifdef/#ifndef` 块，仅追加新平台支持和保护
- 页面路由使用完整子包路径（如 `/pages/login/examinee-login`），不是旧扁平路径