# 微信小程序登录服务

记录小程序端 `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`。

## 启动

```bash
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` 不存在则创建用户，存在则更新资料并返回用户信息。
- **请求体**

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

- **响应体**

```json
{
  "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` 作为维度做统计或挂载其他表。