241 lines
5.5 KiB
Markdown
241 lines
5.5 KiB
Markdown
# 云印享 - 付费打印服务系统
|
|
|
|
## 项目简介
|
|
|
|
云印享是一个基于 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 | 获取统计数据 |
|
|
| CreateAdmin | 创建管理员账号 |
|
|
| GetAdminList | 获取管理员列表 |
|
|
| UpdateAdmin | 更新管理员信息 |
|
|
| DeleteAdmin | 删除管理员 |
|
|
|
|
## 数据模型
|
|
|
|
### 订单状态
|
|
|
|
| 值 | 状态 |
|
|
|----|------|
|
|
| 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
|