wxmp-backend

微信小程序后端 API，基于 NestJS + Prisma + PostgreSQL + Redis + BullMQ + 腾讯云 COS。

技术栈

层	选型
运行时	Node.js 22 + TypeScript
框架	NestJS 11
ORM	Prisma 6
数据库	PostgreSQL 16
缓存/队列	Redis 7 + BullMQ
对象存储	腾讯云 COS
鉴权	JWT（passport-jwt）
文档	Swagger / OpenAPI（/docs）
部署	Docker + docker compose

目录约定

src/
├── common/      # 公共：统一响应、全局守卫/过滤器/拦截器、装饰器、通用 DTO
├── config/      # 环境变量读取 + Joi 启动校验
├── prisma/      # PrismaService（全局单例）
├── redis/       # ioredis 实例（全局）
├── wechat/      # 微信 SDK 封装：code2Session（已实现）、支付（占位）
├── auth/        # 微信登录 + JWT 签发与校验（已完整实现）
├── users/       # 用户查/建、/users/me
├── products/ categories/ design-list/ addresses/  # 业务（空壳+路由+DTO，逻辑 TODO）
├── orders/ payments/ upload/                       # 业务（同上）
├── queue/       # BullMQ 定制任务（占位处理器）
└── health/      # 健康检查

统一响应格式：{ code, message, data }（成功 code:0，失败为对应 HTTP 状态码）。

本地启动

1. 安装依赖

   npm install
   

2. 复制环境变量并填写

   cp .env.example .env
   # 填入 WX_APPID / WX_SECRET / JWT_SECRET 等
   

3. 起 PostgreSQL + Redis（需 Docker）

   npm run db:up
   

4. 初始化数据库

   npx prisma migrate dev --name init
   npm run prisma:seed
   

5. 启动开发服务

   npm run start:dev
   

6. 访问
   • 健康检查：http://localhost:3000/health
   • Swagger 文档：http://localhost:3000/docs

微信登录流程（安全要点）

核心原则：服务端以微信 code2Session 返回的 openid 为准，绝不信任前端传入的 openid。

1. 小程序端 wx.login() 拿到临时 code。
2. POST /api/auth/login，请求体仅需 { code }。
3. 服务端 wechat.code2Session(code) 用服务端持有的 appid + secret 请求微信 sns/jscode2session，换得 openid + session_key。
4. users.findOrCreateByOpenid(openid) 查/建用户。
5. session_key 存入 Redis（wx:session:{userId}，TTL 7 天），供后续解密小程序 encryptedData / 手机号。
6. 用 @nestjs/jwt 签发 { sub: userId, openid } 的 JWT 返回 accessToken。
7. 小程序将 accessToken 存 storage，后续请求带 Authorization: Bearer <token>；JwtAuthGuard 默认守护所有路由，@Public() 标记的路由（如 /auth/login、/health）免鉴权。

无真实 appid 时，可临时 mock WechatService.code2Session 返回固定 openid 走通链路。

常用脚本

命令	说明
npm run start:dev	开发热重载
npm run build	编译到 dist/
npm run prisma:migrate:dev	生成并应用迁移（开发）
npm run prisma:migrate	应用迁移（生产，deploy 模式）
npm run prisma:seed	写入种子数据
npm run db:up / db:down	起/停本地 postgres + redis

环境变量

见 .env.example。关键项（缺失即启动失败）：

• DATABASE_URL — PostgreSQL 连接串
• REDIS_URL — Redis 连接串
• JWT_SECRET — JWT 签名密钥（≥16 位，生产用高熵随机串）
• JWT_EXPIRES — access token 有效期（秒）
• WX_APPID / WX_SECRET — 微信小程序凭证（服务端持有，不下发前端）

微信支付、COS 相关变量本轮可留空。

当前状态与后续迭代

已实现：工程骨架、Prisma 全量 schema、微信登录 + JWT、统一响应/异常、Swagger、Docker、健康检查。

待实现（已预留模块/路由/DTO，标 TODO）：

• 商品/分类/设计清单/地址/订单/上传的完整业务逻辑（分页、权限、事务、金额重算等）
• 微信支付 V3（统一下单、回调验签、查单、退款）
• COS 直传凭证 / 预签名
• BullMQ 定制任务真实处理
• 管理后台（React + Ant Design，独立仓库）
• 单元 / e2e 测试