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. 数据库初始化

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

3. 配置修改

编辑 config.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 代码

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. 运行服务

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