wx_service/docs

微信小程序登录服务

记录小程序端 wx.login 换取 openid 并写入数据库的后端服务说明。

配置

1. 复制 .env.example 为 .env。
2. 按实际环境填写以下变量：
   • SERVER_PORT：HTTP 服务端口，例如 8080。
   • DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME：MySQL 连接信息。
3. 如果需要，替换 GIN_MODE、JWT_SECRET 等其他变量。
4. 通过 docs/sql/users.sql 初始化 mini_programs 与 users 表，并插入每个小程序的 name/app_id/app_secret。

启动

go run ./cmd/api

启动流程：

1. 加载 .env。
2. 初始化数据库连接（参见 internal/database/database.go）。
3. 自动迁移 internal/model/user.go 中的 users 表。
4. 注册路由并启动 Gin HTTP 服务。

数据表

mini_programs

字段	类型	说明
id	bigint unsigned	小程序 ID，登录接口需传
name	varchar(100)	业务名称或备注
app_id	varchar(100), unique	微信小程序 appId
app_secret	varchar(200)	微信小程序 appSecret（明文存储，注意权限）
description	varchar(255)	可选描述
created_at/updated_at/deleted_at	timestamp	GORM 默认时间戳

users

字段	类型	说明
id	bigint unsigned (auto increment)	主键
mini_program_id	bigint unsigned	外键，关联 mini_programs.id
open_id	varchar(100)	与 mini_program_id 组合成唯一键
union_id	varchar(100), nullable	微信 unionid（若有）
nick_name	varchar(100)	用户昵称
avatar_url	varchar(500)	头像地址
gender	tinyint, default 0	性别（与小程序一致）
phone	varchar(20)	手机号
session_key	varchar(100)	微信会话密钥
created_at/updated_at/deleted_at	timestamp	GORM 默认时间戳

接口

POST /api/v1/auth/login

• 说明：接收小程序端 wx.login 返回的 code，向微信 jscode2session 请求 openid / session_key。若 open_id 不存在则创建用户，存在则更新资料并返回用户信息。
• 请求体

{
  "mini_program_id": 1,
  "code": "wx.login返回的code",
  "nickname": "可选",
  "avatar_url": "可选",
  "gender": 1,
  "phone": "110"
}

• 响应体

{
  "code": 200,
  "message": "success",
  "data": {
    "user": {
      "id": 1,
      "mini_program_id": 1,
      "open_id": "oXXX",
      "union_id": "可选",
      "nickname": "昵称",
      "avatar_url": "链接",
      "gender": 1,
      "phone": "110"
    },
    "session_key": "wx-session-key",
    "mini_program": {
      "id": 1,
      "name": "商城小程序",
      "app_id": "wx67444119b166caa0"
    }
  }
}

• 错误
  • 400：code 或 mini_program_id 缺失、请求体非法、小程序不存在。
  • 502：微信 API 返回错误。
  • 500：数据库或其他内部异常。

健康检查

GET /healthz 返回 {"status": "ok"}，用于部署探活。

更多子系统/专题文档请查阅 docs/* 子目录，例如 docs/remove_watermark/README.md 描述了去水印小程序的详细需求。

多小程序共用后台设计

• 凭证管理表：mini_programs 持久化 name/app_id/app_secret，可通过后台页面或 SQL 插入，避免把密钥写进环境变量。
• 接口约定：小程序端调用登录接口时传入 mini_program_id。服务端通过该 ID 读取凭证，动态拼装 jscode2session 请求。
• 数据隔离：users 以 mini_program_id + open_id 建立唯一索引，同一 openid 在不同小程序下互不影响。
• 扩展性：后续如需在用户层面区分策略（如积分、营销），可直接以 mini_program_id 作为维度做统计或挂载其他表。