backend/cloudprint-backend/README.md

# 云印享 - 付费打印服务系统

## 项目简介

云印享是一个基于 gRPC 的付费打印服务后端系统，支持用户管理、文件上传下载、订单处理、打印任务调度、微信支付、文库管理等核心功能。

## 技术栈

- **语言**: Go 1.21+
- **框架**: gRPC + Protobuf
- **数据库**: MySQL + GORM
- **认证**: JWT (JSON Web Token)
- **支付**: 微信支付 (gopay)
- **配置**: Viper

## 项目结构

```
cloudprint-backend/
├── cmd/server/           # 应用入口
│   └── main.go
├── config/               # 配置管理
│   └── config.go
├── internal/
│   ├── grpc/             # gRPC 服务层
│   │   ├── interceptor/  # 拦截器 (认证)
│   │   └── service/      # gRPC 服务实现
│   ├── model/            # 数据模型
│   ├── repository/       # 数据访问层
│   └── service/          # 业务逻辑层
├── pkg/                  # 公共工具包
│   ├── jwt/              # JWT 认证
│   ├── pay/              # 微信支付
│   └── upload/           # 文件上传
├── proto/                # Protobuf 定义
│   ├── cloudprint.proto
│   └── generated/        # 生成的代码
├── scripts/              # 数据库脚本
│   └── db.sql
├── config.yaml           # 配置文件
├── go.mod
└── go.sum
```

## 服务列表

| 服务 | 端口 | 描述 |
|------|------|------|
| gRPC Server | 8080 | 主服务端口 |

## 快速开始

### 1. 环境要求

- Go 1.21+
- MySQL 5.7+
- protoc (Protocol Buffer 编译器)

### 2. 数据库初始化

```bash
mysql -u root -p < scripts/db.sql
```

### 3. 配置修改

编辑 `config.yaml` 文件，修改以下配置：

```yaml
database:
  host: "localhost"
  port: 3306
  username: "root"
  password: "your-password"
  database: "cloudprint"

jwt:
  secret: "your-secret-key-change-in-production"

wechat:
  app_id: "your-app-id"
  app_secret: "your-app-secret"
  mch_id: "your-merchant-id"
  api_key: "your-api-key"
  notify_url: "http://your-domain.com/pay/callback"
```

### 4. 编译生成 gRPC 代码

```bash
cd cloudprint-backend
protoc --go_out=./proto/generated --go_opt=paths=source_relative \
       --go-grpc_out=./proto/generated --go-grpc_opt=paths=source_relative \
       proto/cloudprint.proto
```

### 5. 运行服务

```bash
go run cmd/server/main.go -config config.yaml
```

## API 文档

### AuthService (用户认证服务)

| 方法 | 描述 |
|------|------|
| Login | 微信登录，获取 AccessToken 和 RefreshToken |
| RefreshToken | 刷新 AccessToken |
| GetUserInfo | 获取用户信息 |
| UpdateUser | 更新用户信息（昵称、头像） |

### FileService (文件管理服务)

| 方法 | 描述 |
|------|------|
| Upload | 流式上传文件（支持分片） |
| GetFile | 流式下载文件 |
| DeleteFile | 删除文件 |
| AddWatermark | 添加水印 |
| GetFileList | 获取文件列表 |

### OrderService (订单服务)

| 方法 | 描述 |
|------|------|
| CreateOrder | 创建订单 |
| GetOrder | 获取订单详情 |
| GetOrderList | 获取订单列表 |
| UpdateOrderStatus | 更新订单状态 |
| CancelOrder | 取消订单 |

### PrintService (打印服务)

| 方法 | 描述 |
|------|------|
| GetPrinters | 获取打印机列表 |
| GetPrinterStatus | 获取打印机状态 |
| RegisterPrinter | 注册打印机 |
| PrinterHeartbeat | 打印机心跳 |
| SubmitPrintJob | 提交打印任务 |
| CancelPrintJob | 取消打印任务 |
| SubscribeJobs | 订阅打印任务（流式） |
| ReportJobStatus | 上报任务状态 |

### LibraryService (文库服务)

| 方法 | 描述 |
|------|------|
| GetCategories | 获取文库分类 |
| GetFiles | 获取文库文件列表 |
| UploadFile | 上传文库文件 |
| DeleteFile | 删除文库文件 |

### PriceService (价目表服务)

| 方法 | 描述 |
|------|------|
| GetPriceList | 获取价目表 |
| CreatePriceItem | 创建价目项 |
| UpdatePriceItem | 更新价目项 |

### PayService (支付服务)

| 方法 | 描述 |
|------|------|
| CreateWxPayOrder | 创建微信支付订单 |
| QueryPayStatus | 查询支付状态 |
| HandlePayCallback | 处理支付回调 |
| PayByBalance | 余额支付 |

### AdminService (管理后台服务)

| 方法 | 描述 |
|------|------|
| Login | 管理员登录 |
| GetStatistics | 获取统计数据 |

## 数据模型

### 订单状态

| 值 | 状态 |
|----|------|
| 0 | 待支付 |
| 1 | 已支付 |
| 2 | 打印中 |
| 3 | 已完成 |
| 4 | 已取消 |

### 支付状态

| 值 | 状态 |
|----|------|
| 0 | 待支付 |
| 1 | 支付中 |
| 2 | 成功 |
| 3 | 失败 |

### 打印机状态

| 值 | 状态 |
|----|------|
| 0 | 空闲 |
| 1 | 打印中 |
| 2 | 离线 |

### 打印任务状态

| 值 | 状态 |
|----|------|
| pending | 等待中 |
| printing | 打印中 |
| completed | 已完成 |
| failed | 失败 |
| cancelled | 已取消 |

## 默认账号

- 管理员用户名: `admin`
- 管理员密码: `admin123` (需在生产环境修改)

## 初始价目表

| 名称 | 类型 | 价格 | 单位 |
|------|------|------|------|
| A4黑白打印 | A4 | 0.10元 | 页 |
| A4彩色打印 | A4 | 0.30元 | 页 |
| A3黑白打印 | A3 | 0.20元 | 页 |
| A3彩色打印 | A3 | 0.60元 | 页 |
| 照片打印 | 照片纸 | 2.00元 | 张 |

## 许可证

MIT License