# jiyipintu

**Repository Path**: mzh1030/jiyipintu

## Basic Information

- **Project Name**: jiyipintu
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 适老化记忆拼图（uni-app + Vue 3 版）

> 高职软件技术专业毕业设计项目。原始版本为微信原生小程序，现使用 **uni-app + Vue 3 + Vite + Pinia** 技术栈重构，功能完整扩展为多页面应用，支持多端编译（H5 / 微信小程序 / App 等）。

## 技术栈

| 类别 | 选型 |
| --- | --- |
| 跨端框架 | uni-app（`@dcloudio/*` 3.x） |
| 前端框架 | Vue 3（`<script setup>` Composition API） |
| 状态管理 | **Pinia**（setup 风格 store） |
| 构建工具 | Vite 5 |
| 样式方案 | SCSS + `rpx` 跨端单位 |
| 本地存储 | `uni.storage`（历史成绩 / 用户设置） |

## 目录结构

```
jiyipintu/
├── package.json
├── vite.config.js          # Vite + uni 插件 + @ 别名
├── index.html              # H5 入口
├── .gitignore
├── README.md
├── src/
│   ├── main.js             # createSSRApp + 注册 Pinia
│   ├── App.vue
│   ├── manifest.json       # uni-app 多端配置
│   ├── pages.json          # 4 页路由 + tabBar 导航
│   │
│   ├── constants/
│   │   └── index.js        # HISTORY_KEY / BOARD_RPX / 字号档位等
│   ├── config/
│   │   └── themes.js       # 主题与图片数据（后续可替换为 API）
│   │
│   ├── composables/        # 通用组合函数
│   │   ├── usePuzzle.js    # 洗牌/判胜/进度提示
│   │   └── useTimer.js     # 计时器
│   │
│   ├── stores/             # Pinia 状态管理
│   │   ├── game.js         # 游戏当前状态
│   │   ├── history.js      # 历史成绩 + 统计衍生数据
│   │   └── settings.js     # 用户偏好（字号/震动/音效/对比）
│   │
│   ├── components/         # 可复用 UI 组件
│   │   ├── PuzzleBoard.vue
│   │   ├── DifficultyPicker.vue
│   │   ├── ThemeSelector.vue
│   │   ├── GalleryPicker.vue
│   │   ├── StatsPanel.vue
│   │   └── HistoryList.vue
│   │
│   ├── pages/              # 4 个页面
│   │   ├── index/index.vue      # 拼图主界面
│   │   ├── stats/stats.vue      # 成绩统计（含简易条形图）
│   │   ├── settings/settings.vue # 设置（字号/震动/清缓存）
│   │   └── about/about.vue      # 关于 / 使用说明
│   │
│   └── static/images/      # 三主题九图片
├── 小程序/                  # ⚠️ 旧版原生代码，仅作参考（可删除）
├── project.config.json     # 旧 WX DevTools 配置（uni-app 不使用，可删除）
└── project.private.config.json
```

## 功能

### 拼图页（首页）
- 三大主题：怀旧生活 / 自然风景 / 文化记忆，每主题 3 张图
- 两种难度：3×3 简单 / 4×4 进阶
- 两次点击交换拼图块，直至还原整图
- 实时计时、步数统计、动态操作建议
- 接近完成震动 + Toast 提醒
- 完成后自动保存成绩并弹窗提示
- 显示/隐藏提示原图

### 成绩页
- 完成总局数、最佳用时、平均用时、平均步数 四维统计
- **按难度分组的条形图**（纯 CSS 实现，不依赖图表库）
- 最近 10 条历史记录列表（主题、图片、难度、用时、步数、日期）
- 一键清空历史记录（带确认弹窗）

### 设置页
- 字号档位：标准 / 大字号 / 超大（带实时预览）
- 震动反馈开关
- 音效提示开关（预留接入位）
- 高对比模式开关（预留接入位）
- 所有设置自动持久化到 `uni.storage`

### 关于页
- 项目简介、技术栈展示、操作指南、版本信息

## 架构亮点（答辩可以讲）

1. **分层清晰**：常量 / 配置 / 算法 / 状态 / 组件 / 页面 六层解耦
2. **Composition API + Pinia setup 风格**：符合 Vue 3 最佳实践，可测试性强
3. **组件化**：6 个独立可复用组件，单一职责
4. **状态集中管理**：Pinia 多 store（`game` / `history` / `settings`）按领域拆分
5. **响应式布局**：拼图板和 tile 尺寸统一使用 `rpx`，跨设备对齐
6. **错误边界**：存储读写使用 try/catch 降级处理
7. **多端部署**：一套代码同时支持 H5、微信小程序等多端

## 环境要求

- Node.js **≥ 18**（推荐 LTS 版本）
- npm / pnpm / yarn（下文以 `npm` 为例）
- 微信小程序端：**微信开发者工具**（最新稳定版）

## 快速开始

### 1. 安装依赖

```bash
npm install
```

> **关于 uni-app 版本号**：uni-app 的 Vue 3 版本不在 `latest` dist-tag 下（`latest` 指向 Vue 2 版本），而是发布在 `vue3` tag。想升级到最新的 Vue 3 版本：
> ```bash
> npm install @dcloudio/uni-app@vue3 @dcloudio/uni-h5@vue3 \
>   @dcloudio/uni-mp-weixin@vue3 @dcloudio/uni-components@vue3 \
>   @dcloudio/vite-plugin-uni@vue3 @dcloudio/uni-cli-shared@vue3 \
>   @dcloudio/uni-automator@vue3 @dcloudio/uni-stacktracey@vue3
> ```
> 所有 `@dcloudio/*` 包必须使用**同一个版本号**，否则会报运行时错误。

### 2. H5 端开发预览（推荐先用这个验证）

```bash
npm run dev:h5
```

浏览器打开终端输出的地址（默认 `http://localhost:5173`），热更新已开启。

### 3. 微信小程序端

```bash
npm run dev:mp-weixin
```

编译产物在 `dist/dev/mp-weixin/`，然后：

1. 打开 **微信开发者工具**
2. 选择"导入项目"，目录指向 `dist/dev/mp-weixin/`
3. AppID 选择"测试号"或填入自己的
4. 即可在模拟器中预览

> ⚠️ **TabBar 图标说明**：当前 `pages.json` 的 tabBar 未配置 `iconPath`，在 H5 端显示为纯文字即可正常使用。如需在微信小程序端显示图标，请：
> 1. 准备 8 张 PNG 图标（每页各一个普通态、选中态），建议尺寸 81×81px
> 2. 放到 `src/static/tabs/` 目录
> 3. 在 `pages.json` 的每个 tabBar list 项添加 `"iconPath"` 和 `"selectedIconPath"` 字段

### 4. 生产构建

```bash
npm run build:h5          # 产物：dist/build/h5/
npm run build:mp-weixin   # 产物：dist/build/mp-weixin/
```

## 开发提示

### 路径别名
`@` 指向 `src/`，例如 `import { useGameStore } from '@/stores/game'`。

### 状态管理约定
- **`useGameStore`**：只管当前这一局的状态（难度、主题、拼图块、选中项）
- **`useHistoryStore`**：历史记录 + 派生统计（最佳/平均/分组）
- **`useSettingsStore`**：跨会话的用户偏好

所有 store 都通过 `load()` 初始化，通过 watch 或显式调用自动持久化。

### 添加新主题
只需在 `src/config/themes.js` 添加一项，并把图片放到 `src/static/images/<themeId>/`。整个应用会自动识别。

### 添加新页面
1. 在 `src/pages/<name>/<name>.vue` 新建
2. 在 `src/pages.json` 的 `pages` 数组注册
3. 如需进 tabBar，追加到 `tabBar.list`

## 毕业设计配套交付建议

以下文档建议一并准备（不在本仓库内）：

- 开题报告
- 需求规格说明书（含用例图、功能列表）
- 概要设计（含系统架构图、模块划分图）
- 详细设计（含 E-R 图、关键时序图、接口说明）
- 测试用例表与测试报告
- 用户手册（带截图）
- 毕业论文（建议 1-2 万字，重点写架构设计与组件拆分思路）
- 答辩 PPT（含演示视频）

## License

仅用于毕业设计用途。