# 智绘微刻后端技术栈建议方案

> 本文档面向「智绘微刻」小程序团队，提供从 0 到 1 搭建后端服务的完整技术选型建议。  
> 撰写日期：2026-07-27  
> 适用场景：初期 MVP 上线（日活 < 1万），兼顾未来扩展。

---

## 一、总体架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                        微信小程序端                            │
│   Taro 3.6 + React + Local Storage（当前无后端缓存阶段）      │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS / JSON
┌──────────────────────────▼──────────────────────────────────┐
│                    Nginx（反向代理 + 静态文件）               │
│               ┌─────────────┬─────────────┐                 │
│               │  SSL 证书    │  负载均衡    │                 │
│               └─────────────┴─────────────┘                 │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                    FastAPI (Python 3.11+)                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  用户/订单   │  │  词云生成   │  │  设计清单   │         │
│  │   REST API  │  │  异步任务   │  │   REST API  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└──────────────────────────┬──────────────────────────────────┘
           │                 │                 │
    ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
    │ PostgreSQL  │  │   Redis     │  │   MinIO     │
    │  (主数据库)   │  │  缓存/队列   │  │  对象存储    │
    └─────────────┘  └─────────────┘  └─────────────┘
                           │
                    ┌──────▼──────┐
                    │   Celery    │
                    │  异步任务队列 │
                    │  (词云渲染)   │
                    └─────────────┘
```

---

## 二、技术选型与理由

### 1. API 框架：FastAPI (Python)

| 维度 | 选型 | 理由 |
|------|------|------|
| 框架 | **FastAPI** | 自动生成 OpenAPI/Swagger 文档；异步原生支持（`async/await`）；类型提示驱动开发，与前端 TS 思维一致 |
| 替代方案 | Django / Flask / Go-Gin | Django 太重、Flask 需手写异步、Go 学习成本高；团队若熟悉 Python，FastAPI 是最佳平衡点 |
| Python 版本 | **3.11+** | 性能优化显著（CPython 3.11 比 3.10 快 10~25%），且支持 `TaskGroup` 等现代并发原语 |

**核心职责**：
- 用户登录（微信 OAuth2 → JWT Token）
- 商品/品类/价格/工期配置读取
- 设计清单 CRUD
- 订单创建/支付回调/状态流转
- 词云生成任务投递（异步）
- 文件上传预签名 URL（MinIO）

---

### 2. 数据库：PostgreSQL 15+

| 维度 | 选型 | 理由 |
|------|------|------|
| 主数据库 | **PostgreSQL 15+** | 开源、稳定、JSONB 支持灵活存储设计稿元数据；PostGIS 扩展未来可做配送区域 |
| ORM | **SQLAlchemy 2.0** + Alembic | 成熟、类型安全、迁移脚本自动化 |
| 连接池 | asyncpg | FastAPI 原生异步兼容 |

**核心表结构设计（MVP 版）**：

```sql
-- 用户表（微信授权）
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    openid TEXT UNIQUE NOT NULL,
    unionid TEXT,
    nickname TEXT,
    avatar_url TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 商品品类表（与前端 productConfig 同步）
CREATE TABLE products (
    id TEXT PRIMARY KEY,  -- notebook-small, coaster, penbox ...
    name TEXT NOT NULL,
    desc TEXT,
    price INT NOT NULL,        -- 单位：分，避免浮点
    lead_time TEXT,
    description TEXT,
    images TEXT[],             -- 图片 URL 数组
    mask JSONB NOT NULL,       -- {shape, width, height, borderRadius}
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 设计清单表
CREATE TABLE designs (
    id TEXT PRIMARY KEY,       -- DSG + 时间戳
    user_id UUID REFERENCES users(id),
    product_id TEXT REFERENCES products(id),
    count INT NOT NULL DEFAULT 1,
    status TEXT NOT NULL CHECK (status IN ('undesigned','designing','ordered')),
    design_data JSONB,         -- {imageSrc, imagePos, category}
    order_id TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 订单表
CREATE TABLE orders (
    id TEXT PRIMARY KEY,       -- ORD + 时间戳
    user_id UUID REFERENCES users(id),
    design_id TEXT REFERENCES designs(id),
    product_id TEXT REFERENCES products(id),
    product_name TEXT NOT NULL,
    count INT NOT NULL,
    unit_price INT NOT NULL,   -- 单位：分
    total_price INT NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('pending','paid','shipping','done','cancelled')),
    sku TEXT,
    paid_at TIMESTAMPTZ,
    shipped_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 词云生成任务表（追踪异步任务状态）
CREATE TABLE wordcloud_jobs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    base_image_key TEXT NOT NULL,   -- MinIO 对象 key
    names TEXT[] NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('queued','processing','completed','failed')),
    result_key TEXT,
    error_msg TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    completed_at TIMESTAMPTZ
);
```

---

### 3. 缓存与消息队列：Redis 7+

| 用途 | 说明 |
|------|------|
| **JWT 黑名单 / Session 缓存** | 用户登出时令牌失效 |
| **_rate limiting_** | 防止词云接口被刷（每用户 5 次/分钟） |
| **Celery Broker** | Redis List 作为 Celery 任务队列 |
| **热点数据缓存** | 商品配置表、首页轮播数据（TTL 10 分钟） |

---

### 4. 异步任务：Celery + Redis

| 场景 | 处理方式 |
|------|----------|
| **词云图片生成** | 用户上传底图 → 投递 Celery Task → C++ 布局引擎 / Python 词云库生成 → 结果上传 MinIO → WebSocket/轮询通知前端 |
| **订单支付回调处理** | 微信 notify_url → FastAPI 接收 → Celery Task 异步更新订单状态、发送通知 |
| **批量邮件/短信** | 发货通知、营销短信异步发送 |

**为什么不用 RabbitMQ？**  
Redis 作为 Broker 在初期足够（架构简单、少维护一个组件）。当每日任务量 > 10万 时，再迁移到 RabbitMQ 或 AWS SQS。

---

### 5. 对象存储：MinIO

| 用途 | 说明 |
|------|------|
| **用户上传底图** | 微信小程序 → 直传 MinIO（预签名 URL）→ 返回 key 给后端 |
| **词云生成结果图** | Celery Worker 生成后上传 → 前端通过 CDN 域名访问 |
| **商品实物照片** | 运营后台上传 → 前端展示 |

**为什么不存数据库？**  
图片二进制存数据库会导致表体积膨胀、备份慢、查询性能下降。MinIO（S3 兼容）是对象存储的最优解。

**云服务器部署建议**：
- 若使用阿里云：可无缝切换到 **阿里云 OSS**（代码只需改 endpoint + access key）。
- 若自建服务器：MinIO 单机版 Docker 运行，占用 < 200MB 内存。

---

### 6. 部署与运维：Docker Compose（初期）

```yaml
# docker-compose.yml 示例（MVP 单服务器）
version: "3.8"

services:
  api:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/smart_engraving
      - REDIS_URL=redis://redis:6379/0
      - MINIO_ENDPOINT=minio:9000
    depends_on:
      - db
      - redis
      - minio

  celery_worker:
    build: ./backend
    command: celery -A tasks worker --loglevel=info --concurrency=2
    environment:
      - DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/smart_engraving
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis
      - minio

  db:
    image: postgres:15-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: smart_engraving
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass

  redis:
    image: redis:7-alpine
    volumes:
      - redisdata:/data

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - miniodata:/data
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin

volumes:
  pgdata:
  redisdata:
  miniodata:
```

---

## 三、API 设计速查（供前端联调用）

### 认证
```http
POST /api/v1/auth/wechat
Body: { code: "wx_auth_code" }
Response: { access_token: "jwt", refresh_token: "jwt", user: {...} }
```

### 商品
```http
GET /api/v1/products
Response: [ { id, name, desc, price, leadTime, images[], mask } ]
```

### 设计清单
```http
GET    /api/v1/designs              # 列表
POST   /api/v1/designs              # 新建（加入清单）
PATCH  /api/v1/designs/{id}         # 更新（保存设计稿）
DELETE /api/v1/designs/{id}         # 删除
POST   /api/v1/designs/{id}/order   # 确认下单（design → order）
```

### 词云
```http
POST /api/v1/wordcloud/jobs
Body: { baseImageKey, names: [] }
Response: { jobId, status: "queued" }

GET /api/v1/wordcloud/jobs/{jobId}
Response: { status, resultUrl, progress }
```

### 订单
```http
GET  /api/v1/orders
POST /api/v1/orders                  # 创建预支付订单
POST /api/v1/orders/{id}/pay         # 调起微信支付（返回 prepay_id）
POST /api/v1/orders/wechat_notify    # 微信支付回调（服务端内部）
```

### 上传
```http
GET /api/v1/upload/presign?filename=xxx.jpg&contentType=image/jpeg
Response: { url, key, expires }
# 前端使用 `url` 直传 MinIO / OSS
```

---

## 四、费用预估（阿里云 / 腾讯云，MVP 阶段）

| 资源 | 配置 | 月费用（人民币） |
|------|------|-----------------|
| 云服务器 ECS | 2核4G，共享型 | ~¥60-100 |
| 云数据库 RDS PostgreSQL | 1核1G，基础版 | ~¥35-60 |
| 云数据库 Redis | 256MB 主从 | ~¥20-40 |
| 对象存储 OSS | 50GB 标准存储 | ~¥5-10 |
| CDN 流量 | 100GB/月 | ~¥15-25 |
| 域名 + SSL 证书 | 通配符一年 | ~¥200-400/年 |
| **合计** | | **~¥150-260/月** |

> 若用户量极小（< 1000 日活），可将 PostgreSQL 和 Redis 都部署在同一台 ECS 上，初期费用可压到 **¥60-80/月**。

---

## 五、开发排期建议（后端 MVP，2 人团队）

| 阶段 | 周期 | 内容 |
|------|------|------|
| **Week 1** | 环境搭建 | Docker Compose 本地跑通；FastAPI 项目脚手架；PostgreSQL + Redis 联调 |
| **Week 2** | 核心 API | 微信登录 JWT / 商品列表 / 设计清单 CRUD / 订单创建 |
| **Week 3** | 词云 & 支付 | 词云异步任务接入（Celery）；微信支付预支付+回调；MinIO 预签名上传 |
| **Week 4** | 联调 & 部署 | 小程序前端联调；阿里云 ECS 生产部署；监控告警（日志 + 告警） |

---

## 六、风险与预案

| 风险 | 影响 | 预案 |
|------|------|------|
| 微信登录 code 换取 session_key 失败 | 用户无法登录 | 后端增加 Mock 登录接口（开发环境）|
| 词云生成耗时长（>30s） | 用户体验差 | 前端轮询 + 后端加进度反馈；高并发时排队提示 |
| 支付回调网络抖动 | 订单状态不一致 | 支付回调幂等设计（按微信 `out_trade_no` 去重）|
| 图片存储流量激增 | CDN 费用上升 | 启用 OSS 图片压缩 + WebP 转换 |

---

## 七、推荐的开箱即用工具链

| 工具 | 用途 |
|------|------|
| **uv** | Python 包管理与虚拟环境（比 pip + venv 快 10 倍）|
| **Pydantic v2** | 数据校验与序列化（FastAPI 内置）|
| **sqlalchemy[asyncio]** | 异步 ORM |
| **celery[redis]** | 异步任务队列 |
| **boto3** | MinIO / OSS S3 兼容客户端 |
| **loguru** | 结构化日志 |
| **sentry-sdk** | 线上异常追踪（免费额度够用）|

---

## 八、总结

> **推荐技术栈：FastAPI + PostgreSQL + Redis + MinIO + Celery，Docker Compose 单服务器部署。**

- **FastAPI**：异步高性能、自动生成文档、团队上手快。
- **PostgreSQL**：JSONB 灵活存储设计稿元数据，未来扩展无需换库。
- **Redis**：一物三用（缓存 + 队列 + 限流）。
- **MinIO**：自托管 S3 兼容对象存储，未来可一键切阿里云 OSS。
- **Celery**：词云生成、支付回调、通知推送全部异步化，前端响应 < 100ms。

该方案在 **日活 1 万以内** 完全不需要 Kubernetes 或微服务拆分，单台 2 核 4G 服务器即可承载。