# image-viewer-miniprogram

**Repository Path**: UPUP0326/image-viewer-miniprogram

## Basic Information

- **Project Name**: image-viewer-miniprogram
- **Description**: 使用 Cursor AI 编辑器辅助开发的看图小程序项目 - A mini-program image viewer project developed with Cursor AI editor assistance
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2026-01-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 看图小程序

> 使用 Cursor AI 编辑器辅助开发的看图小程序项目

一个基于 uni-app 3.0 开发的跨平台看图小程序，支持 H5、微信小程序、App 等多端运行。提供图片浏览、分类管理、收藏、历史记录等功能，并配备完整的管理后台系统。

## ✨ 功能特性

### 前端功能
- 📱 **多端支持**：支持 H5、微信小程序、App 等多平台
- 🖼️ **图片浏览**：瀑布流布局，流畅的图片浏览体验
- 📂 **分类管理**：多分类浏览，支持分类切换
- ⭐ **收藏功能**：用户可收藏喜欢的图片
- 📜 **历史记录**：自动记录浏览历史
- 🔍 **搜索功能**：支持关键词搜索图片
- 👤 **用户系统**：用户登录、个人中心
- ⚙️ **设置管理**：个性化设置选项
- 📢 **广告系统**：支持开屏广告和横幅广告

### 后端功能
- 🚀 **高性能 API**：基于 Fastify 框架，低延迟高并发
- 🔐 **权限管理**：JWT 认证，安全的接口访问
- 📊 **管理后台**：完整的后台管理系统
- 🗄️ **数据库管理**：基于 Prisma ORM，类型安全
- 📦 **批量导入**：支持批量图片入库
- 📈 **数据统计**：浏览数、点赞数等统计功能

## 🛠️ 技术栈

### 前端
- **框架**：uni-app 3.0 (Vue 3)
- **构建工具**：Vite 5.0
- **状态管理**：Pinia 2.x
- **UI 框架**：uni-ui（自定义组件）
- **开发语言**：JavaScript / TypeScript

### 后端
- **Web 框架**：Fastify
- **ORM**：Prisma
- **数据库**：SQLite（开发环境）
- **认证**：JWT Token
- **包管理**：pnpm

### 管理后台
- **框架**：Vue 3
- **构建工具**：Vite
- **UI 组件**：Element Plus / Ant Design Vue

## 📁 项目结构

```
项目根目录/
├── src/                    # 前端源代码
│   ├── api/               # API 接口封装
│   ├── components/        # 组件
│   │   ├── ad-banner/     # 广告横幅组件
│   │   ├── ad-splash/     # 开屏广告组件
│   │   ├── category-tabs/ # 分类标签组件
│   │   ├── custom-tabbar/ # 自定义底部导航
│   │   ├── image-card/    # 图片卡片组件
│   │   └── waterfall/     # 瀑布流组件
│   ├── pages/             # 页面
│   │   ├── index/         # 首页
│   │   ├── category/      # 分类页
│   │   ├── detail/        # 详情页
│   │   ├── favorites/     # 收藏页
│   │   ├── history/       # 历史记录页
│   │   ├── profile/       # 个人中心
│   │   └── settings/      # 设置页
│   ├── stores/            # Pinia 状态管理
│   ├── utils/             # 工具函数
│   ├── config/            # 配置文件
│   ├── static/            # 静态资源
│   ├── App.vue            # 根组件
│   ├── main.js            # 入口文件
│   ├── pages.json         # 页面配置
│   └── manifest.json      # 应用配置
│
├── server/                 # 后端服务
│   ├── api/               # API 服务（端口 3000）
│   ├── admin/             # Admin 服务（端口 3001）
│   ├── admin-frontend/    # 管理后台前端（端口 3002）
│   └── shared/            # 共享代码
│       └── prisma/        # 数据库配置
│
├── scripts/                # 脚本工具
├── .cursor/                # Cursor AI 编辑器配置
├── package.json            # 项目配置
├── vite.config.js         # Vite 配置
└── tsconfig.json          # TypeScript 配置
```

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- pnpm >= 8.0.0
- Python 3.x（用于脚本工具，可选）

### 安装依赖

```bash
# 安装前端依赖
pnpm install

# 安装后端依赖
cd server
pnpm install
```

### 配置环境变量

#### 前端环境变量

在项目根目录创建 `.env.development` 文件：

```env
VITE_API_BASE_URL=http://localhost:3000
VITE_API_TIMEOUT=10000
```

创建 `.env.production` 文件：

```env
VITE_API_BASE_URL=https://api.yourdomain.com
VITE_API_TIMEOUT=10000
```

详细配置说明请参考 [README_ENV.md](./README_ENV.md)

#### 后端环境变量

在 `server/api` 目录创建 `.env` 文件：

```env
PORT=3000
DATABASE_URL="file:../shared/prisma/data.db"
API_KEY=your-api-key-for-batch-upload
```

在 `server/admin` 目录创建 `.env` 文件：

```env
PORT=3001
DATABASE_URL="file:../shared/prisma/data.db"
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
API_KEY=your-api-key-for-batch-upload
```

### 初始化数据库

```bash
cd server

# 生成 Prisma Client
pnpm run prisma:generate

# 运行数据库迁移
pnpm run prisma:migrate
```

### 启动开发服务器

#### 方式一：一键启动（推荐）

**Windows:**
```bash
cd server
start.bat
```

**Linux/Mac:**
```bash
cd server
chmod +x start.sh
./start.sh
```

**Node.js（跨平台）:**
```bash
cd server
pnpm run dev
```

#### 方式二：分别启动

**启动后端服务：**
```bash
cd server
pnpm run dev:api      # API 服务（端口 3000）
pnpm run dev:admin    # Admin 服务（端口 3001）
pnpm run dev:frontend # 管理后台（端口 3002）
```

**启动前端开发：**
```bash
# H5 开发
pnpm run dev:h5

# 微信小程序开发
pnpm run dev:mp-weixin

# App 开发
pnpm run dev:app
```

### 访问地址

- **前端 H5**: http://localhost:8080
- **API 服务**: http://localhost:3000
- **Admin 服务**: http://localhost:3001
- **管理后台**: http://localhost:3002

默认管理员账号：
- 用户名: `admin`
- 密码: `admin123`

## 📖 开发指南

### 前端开发

#### 页面开发

页面文件位于 `src/pages/` 目录，使用 Vue 3 Composition API：

```vue
<template>
  <view class="page">
    <!-- 页面内容 -->
  </view>
</template>

<script setup>
import { ref } from 'vue'

const data = ref([])
</script>

<style lang="scss" scoped>
.page {
  // 样式
}
</style>
```

#### 组件开发

组件位于 `src/components/` 目录，支持自动导入：

```vue
<!-- 直接使用，无需导入 -->
<image-card :image="item" />
```

#### API 调用

使用封装的 API 函数：

```javascript
import { getImageList } from '@/api/image'

const images = await getImageList({
  page: 1,
  pageSize: 20,
  categoryId: 1
})
```

#### 状态管理

使用 Pinia 进行状态管理：

```javascript
import { useImageStore } from '@/stores/image'

const imageStore = useImageStore()
imageStore.fetchImages()
```

### 后端开发

#### API 接口开发

API 服务位于 `server/api/src/index.js`，使用 Fastify 框架：

```javascript
fastify.get('/api/images/list', async (request, reply) => {
  // 处理逻辑
  return { code: 200, data: [] }
})
```

#### 数据库操作

使用 Prisma 进行数据库操作：

```javascript
import { prisma } from '../shared/prisma'

const images = await prisma.image.findMany({
  where: { status: 1 },
  include: { category: true }
})
```

#### 批量导入图片

使用提供的脚本或 API：

```bash
# Python 脚本
python server/scripts/batch-upload-images.py

# 或使用 API
curl -X POST http://localhost:3001/admin/images/batch \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d @images.json
```

详细文档请参考：
- [后端 API 设计文档](./server/API_DESIGN.md)
- [图片批量上传 API](./server/docs/IMAGE_UPLOAD_API.md)
- [快速开始指南](./server/docs/QUICK_START.md)

## 🏗️ 构建部署

### 前端构建

```bash
# H5 构建
pnpm run build:h5

# 微信小程序构建
pnpm run build:mp-weixin

# App 构建
pnpm run build:app
```

构建产物位于 `dist/` 目录。

### 后端部署

```bash
cd server

# 构建前端管理后台
pnpm run build

# 启动生产服务
pnpm start
```

## 📚 相关文档

- [环境变量配置说明](./README_ENV.md)
- [项目结构重构说明](./README_RESTRUCTURE.md)
- [后端服务说明](./server/README.md)
- [后端 API 设计文档](./server/API_DESIGN.md)
- [图片批量上传 API](./server/docs/IMAGE_UPLOAD_API.md)
- [快速开始指南](./server/docs/QUICK_START.md)

## 🤝 贡献指南

本项目使用 Cursor AI 编辑器辅助开发。欢迎提交 Issue 和 Pull Request。

### 开发规范

1. 代码风格遵循项目现有规范
2. 提交前运行代码检查
3. 提交信息使用中文，清晰描述变更内容
4. 新功能需要添加相应的文档说明

## 📝 许可证

本项目采用私有许可证，仅供学习和研究使用。

## 🙏 致谢

- [uni-app](https://uniapp.dcloud.net.cn/) - 跨平台应用开发框架
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Fastify](https://www.fastify.io/) - 快速且低开销的 Web 框架
- [Prisma](https://www.prisma.io/) - 下一代 ORM
- [Cursor AI](https://cursor.sh/) - AI 辅助代码编辑器

---

**开发工具**: 本项目使用 [Cursor AI](https://cursor.sh/) 编辑器辅助开发

**仓库地址**: https://gitee.com/UPUP0326/image-viewer-miniprogram