# KP-Assess-Miniui **Repository Path**: yxl/Assess-Miniui ## Basic Information - **Project Name**: KP-Assess-Miniui - **Description**: KP-Assess-Miniui - **Primary Language**: JavaScript - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2016-06-06 - **Last Updated**: 2026-07-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 体育资讯小程序 基于 uni-app + Vue3 框架开发的跨平台体育资讯应用，提供球员查询、球队信息、赛事赛程、新闻资讯、数据榜单等一站式体育信息服务。 ## 📋 目录 - [项目简介](#-项目简介) - [功能概述](#-功能概述) - [技术栈](#-技术栈) - [目录结构](#-目录结构) - [环境要求](#-环境要求) - [安装与依赖](#-安装与依赖) - [开发与构建运行](#-开发与构建运行) - [多端支持](#-多端支持) - [项目配置](#-项目配置) - [开发规范](#-开发规范) --- ## 📖 项目简介 本项目是一款专注于体育领域的跨平台应用，采用 [uni-app](https://uniapp.dcloud.io/) 框架开发，一套代码可同时发布至 **H5 网页、微信小程序、App（iOS/Android）** 等多个平台。项目围绕篮球等体育赛事展开，为体育爱好者提供实时赛事数据、球员球队信息、新闻资讯及数据排名等功能。 ## ✨ 功能概述 | 模块 | 功能说明 | |------|----------| | 🏠 **首页** | 轮播图、赛事推荐、最新资讯聚合展示 | | 🔍 **搜索** | 支持按关键词搜索球员、球队、比赛、新闻等多维度数据 | | 👤 **球员** | 球员列表查询、个人资料查看、职业生涯数据统计 | | 🏀 **球队** | 球队列表浏览、球队详情查看、联赛排名与积分信息 | | ⚽ **赛事** | 今日比赛、即将开赛、已结束赛事查询，实时比分展示 | | 📰 **新闻** | 体育资讯分类浏览、热门新闻推荐、文章详情阅读 | | 📊 **数据榜** | 球员/球队排名数据展示，雷达图可视化个人能力分析 | | 👤 **个人中心** | 用户信息、登录管理、地址管理、我的收藏等 | **组件库** 内置 15 个可复用 UI 组件，涵盖： - 数据卡片：球员卡、球队卡、比赛卡、新闻卡、赛况卡 - 图表可视化：雷达图、环形数据图、统计仪表盘 - 交互控件：下拉选择器、运动分类 Tab 切换、区块标题 - 状态反馈：加载动画、空状态占位、骨架屏、微信登录弹窗 ## 🛠 技术栈 | 类别 | 技术选型 | 版本 | |------|----------|------| | 前端框架 | [uni-app](https://uniapp.dcloud.io/) | ^3.0.0 | | 框架底层 | [Vue.js](https://vuejs.org/) | ^3.4.21 (Composition API) | | 构建工具 | [Vite](https://vitejs.dev/) | 5.2.8 | | 插件引擎 | [@dcloudio/vite-plugin-uni](https://uniapp.dcloud.io/) | ^3.0.0 | | 样式方案 | SCSS + rpx 响应式单位 | sass ^1.77.0 | | 网络请求 | uni.request 封装 | 自定义 request 模块 | | 存储方案 | uni.setStorageSync 封装 | 本地持久化 | | 身份认证 | JWT Token + Refresh Token | 自动续期机制 | ## 📁 目录结构 ``` Assess-Miniui/ ├── API_DOCUMENTATION.md # API 接口文档 ├── manifest.json # uni-app 应用配置（应用名称、权限、各端标识等） ├── pages.json # 路由与页面配置（导航栏、TabBar、easycom） ├── package.json # 项目依赖与脚本配置 ├── vite.config.js # Vite 构建配置（SCSS 全局注入） ├── main.js # 应用入口（Vue3 SSR 模式） ├── App.vue # 根组件（全局样式、登录状态管理） ├── uni.scss # 全局样式变量（字体、色彩、间距、混入） ├── uni.promisify.adaptor.js # uni API Promise 适配器 │ ├── pages/ # 页面目录 │ ├── splash/ # 启动页 │ ├── index/ # 首页 │ ├── search/ # 搜索页 │ ├── player/ # 球员列表 & 详情 │ ├── team/ # 球队列表 & 详情 │ ├── match/ # 赛程列表 & 赛事详情 │ ├── news/ # 新闻列表 & 新闻详情 │ ├── ranking/ # 数据榜单页 │ └── profile/ # 个人中心页 │ ├── components/ # 可复用组件库 │ ├── DropdownSelect.vue # 下拉选择器 │ ├── EmptyState.vue # 空状态组件 │ ├── LoadingSpinner.vue # 加载动画 │ ├── PlayerCard.vue # 球员详情卡片 │ ├── PlayerCardSkeleton.vue # 球员卡骨架屏 │ ├── TeamCard.vue # 球队卡片 │ ├── MatchCard.vue # 比赛结果卡片 │ ├── SportsMatchCard.vue # 赛况卡片（多状态） │ ├── NewsCard.vue # 新闻卡片 │ ├── SectionHeader.vue # 区块标题组件 │ ├── SportTab.vue # 运动分类 Tab │ ├── WechatLoginModal.vue # 微信登录弹窗 │ ├── RadarChart.vue # 雷达图组件（SVG） │ ├── DataRadialChart.vue # 环形数据图组件 │ └── SportsStatsChart.vue # 统计数据仪表盘 │ ├── services/ # 业务服务层（17 个服务模块） │ ├── userService.js # 用户服务（登录/登出/Token 刷新） │ ├── playerService.js # 球员服务（列表/详情/排名/Mock 降级） │ ├── teamService.js # 球队服务（列表/详情/排名/Mock 降级） │ ├── matchService.js # 比赛服务（列表/详情/状态筛选） │ ├── gameDataService.js # 赛事数据服务 │ ├── newsService.js # 新闻服务（列表/详情/热门/Mock 降级） │ ├── newsCategoryService.js # 新闻分类服务 │ ├── leagueService.js # 联赛服务 │ ├── searchService.js # 聚合搜索服务 │ ├── guessSportsService.js # 体育竞猜服务 │ ├── slideService.js # 轮播图服务 │ ├── adsService.js # 广告服务 │ ├── announceService.js # 公告服务 │ ├── frontMenuService.js # 菜单服务 │ ├── siteCommentService.js # 评论服务 │ ├── friendshipService.js # 友情链接服务 │ ├── userAddressService.js # 地址管理服务 │ └── request.js # 统一 HTTP 请求封装 │ ├── utils/ # 工具模块 │ ├── auth.js # 认证工具（Token 管理/鉴权守卫） │ ├── request.js # 网络请求封装（拦截器/超时/错误处理） │ ├── storage.js # 本地存储封装（带前缀隔离） │ ├── logger.js # 日志工具 │ └── winRateCalculator.js # 胜率计算工具 │ ├── config/ # 配置文件 │ └── api.js # API 基础地址与端点常量 │ ├── styles/ # 样式文件 │ ├── theme.scss # 主题变量（色彩/字体/间距/阴影/动画） │ └── mixins.scss # 样式混入（布局/卡片/交互效果） │ ├── static/ # 静态资源 │ └── icons/ # 底部 TabBar 图标 │ ├── dist/ # 构建输出目录 ├── tests/ # 测试文件 ├── scripts/ # 脚本工具 └── .workbuddy/ # 项目工作区配置 ``` ## 🌍 环境要求 | 环境 | 最低版本 | 推荐版本 | |------|----------|----------| | Node.js | ≥ 18.0.0 | ≥ 20.0.0 | | npm | ≥ 9.0.0 | ≥ 10.0.0 | | HBuilderX | ≥ 4.0 | 最新版 | | 微信开发者工具 | ≥ 1.06 | 最新版 | > **提示：** 推荐使用 `nvm`（Node 版本管理器）来管理 Node.js 版本。 ## 📦 安装与依赖 ```bash # 1. 克隆项目（如有） git clone cd Assess-Miniui # 2. 安装依赖 npm install # 3. 验证安装 npm ls vue ``` ## ▶️ 开发与构建运行 ```bash # ===================== # 开发模式 # ===================== # H5 开发服务器（热重载） npm run dev:h5 # 微信小程序开发（需在 HBuilderX 或微信开发者工具中运行） npm run dev:mp-weixin # ===================== # 构建输出 # ===================== # 构建 H5（生产包） npm run build:h5 # 构建微信小程序 npm run build:mp-weixin ``` > **注意：** 小程序相关平台的构建推荐使用 [HBuilderX](https://www.dcloud.io/hbuilderx.html) IDE 进行图形化操作，可获得更完整的编译体验。 ## 📱 多端支持 本项目利用 uni-app 框架的跨平台能力，支持以下发布目标： | 平台 | 支持状态 | 运行命令 / 方式 | |------|----------|-----------------| | **H5 网页** | ✅ 完全支持 | `npm run dev:h5` / `npm run build:h5` | | **微信小程序** | ✅ 完全支持 | `npm run dev:mp-weixin` / `npm run build:mp-weixin` | | **App (iOS/Android)** | ✅ 支持 | 通过 HBuilderX 云打包或本地打包 | | **支付宝小程序** | ✅ 支持配置 | manifest.json 中已启用 | | **百度小程序** | ✅ 支持配置 | manifest.json 中已启用 | | **字节跳动小程序** | ✅ 支持配置 | manifest.json 中已启用 | | **快应用** | ✅ 支持配置 | manifest.json 中已预留 | ### 各平台特定配置 | 配置项 | H5 | 微信小程序 | App | |--------|----|-----------|-----| | 导航栏样式 | 自定义 (`navigationStyle: custom`) | 自定义 | 自定义 | | 主题色 | #ff9800 (篮球橙) | #ff9800 | #ff9800 | | 打包签名 | — | appid: wx70336827dfcee168 | Android / iOS 签名 | ## ⚙️ 项目配置 ### manifest.json — 应用配置 | 配置项 | 说明 | 值 | |--------|------|-----| | `name` | 应用名称 | Assess-Miniui | | `appid` | 应用唯一标识 | `__UNI__919D3C8` | | `versionName` | 版本号（显示用） | 1.0.0 | | `versionCode` | 版本号（内部用） | 100 | | `vueVersion` | Vue 版本 | 3 | | `transformPx` | px 转 rpx | false | #### App 端权限配置（Android） ```json "permissions": [ "CHANGE_NETWORK_STATE", "ACCESS_WIFI_STATE", "CAMERA", "READ_PHONE_STATE", "ACCESS_NETWORK_STATE", "WRITE_SETTINGS" ] ``` #### 小程序端配置 ```json "mp-weixin": { "appid": "wx70336827dfcee168", "setting": { "urlCheck": false }, "usingComponents": true } ``` ### pages.json — 路由配置 | 配置项 | 说明 | |--------|------| | `pages` | 页面路由数组，定义所有页面路径与导航样式 | | `globalStyle` | 全局导航栏样式（底色 #ff9800、文字白色） | | `tabBar` | 底部 TabBar 配置（首页 / 数据榜 / 赛程 / 我的） | | `easycom` | 组件自动引入（autoscan: true） | ### 底部 TabBar | Tab | 页面路径 | 文字 | |-----|----------|------| | ① | `pages/index/index` | 首页 | | ② | `pages/ranking/ranking` | 数据榜 | | ③ | `pages/match/list` | 赛程 | | ④ | `pages/profile/profile` | 我的 | ### vite.config.js — 构建配置 ```js // SCSS 全局注入 uni.scss，所有组件自动可用主题变量 css: { preprocessorOptions: { scss: { additionalData: `@import "@/uni.scss";` } } } ``` ### API 配置（config/api.js） | 配置项 | 值 | 说明 | |--------|-----|------| | `BASE_URL` | `http://assess.zcc.com/api` | 后端 API 基础地址 | | `REQUEST_TIMEOUT` | `30000ms` | 请求超时时间 | | `API_ENDPOINTS` | — | 所有接口路径常量定义（共 17 个模块、60+ 端点） | ### 样式系统 - **主题变量**（`styles/theme.scss`）：定义完整的设计令牌体系，包括主色（篮球橙 #ff6b35）、功能色、背景色、文本色、阴影层级、间距阶梯、圆角系统等 - **样式混入**（`styles/mixins.scss`）：提供字体、卡片、布局、动画等常用 SCSS mixin，加速页面开发 - **全局样式**（`App.vue`）：覆盖 `page` 根元素、通用容器、卡片、按钮、标签、Flex 布局等基础样式 ### 认证机制 | 功能 | 实现位置 | 说明 | |------|----------|------| | Token 存取 | `utils/auth.js` | JWT Token 的读写、过期判断 | | 自动刷新 | `services/userService.js` | Token 过期前自动调用 refresh 接口续期 | | 全局监听 | `App.vue` | onLaunch 验证登录态，onShow 静默检查 | | 事件总线 | `auth.js` | onLogin / onLogout / onTokenExpire 全局事件 | ### 数据存储 | 机制 | 实现 | 前缀隔离 | |------|------|----------| | 本地缓存 | `utils/storage.js` | `kp_assess_` 前缀 | | HTTP 缓存 | `services/newsService.js` | 新闻数据本地缓存 + Mock 降级 | ## 🎨 开发规范 ### 命名约定 | 类型 | 规则 | 示例 | |------|------|------| | 页面文件 | kebab-case | `pages/player-detail/player-detail.vue` | | 组件文件 | PascalCase | `PlayerCard.vue` | | 服务文件 | camelCase | `playerService.js` | | 样式变量 | kebab-case | `$primary-color` | | API 常量 | UPPER_SNAKE_CASE | `BASE_URL` | ### 代码组织原则 1. **服务层优先**：所有 HTTP 请求必须通过 `services/` 下的服务模块，禁止在页面中直接使用 `uni.request` 2. **工具封装**：通用逻辑抽取至 `utils/`，保持页面组件轻量化 3. **组件复用**：优先使用 `components/` 中的组件，通过 easycom 自动注册无需手动 import 4. **样式作用域**：页面级样式使用 `