# third-login

**Repository Path**: grandroutes/third-login

## Basic Information

- **Project Name**: third-login
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-01-16
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# third-login

本项目是奥集能用户第三方登录的后端服务。

## Motivation

用户以第三方账号 (如微信、钉钉等) 登录奥集能，相较于传统的用户名密码登录，更便捷、安全。      
流程：用户在浏览器上拿到一个二维码，然后用手机扫描，从而触发第三方回调，third-login 算出结果 (是否允许登录)后，同步给浏览器，从而完成登录。

## Design

一个典型的登录流程

``` mermaid
sequenceDiagram
  autonumber
  actor U as 用户
  participant B as 浏览器(PC)
  participant S as 绑定服务(third-login)
  participant W as 微信后台(open platform)
  participant R as 关系核/用户系统

  U->>B: 点击「微信扫码登录」

  B->>S: GET /auth/wechat/qr
  S->>S: 生成 ticket + state (TTL)
  S->>S: 保存映射 state -> ticket
  S-->>B: 返回 {ticket, qr_url}

  B->>B: 渲染二维码(qr_url)
  B->>S: WS /auth/qr/ws?ticket=...
  S-->>B: WS建立成功(绑定 ticket->conn)

  U->>W: 手机微信扫码
  W-->>U: 手机端确认授权(同意/取消)

  alt 用户同意授权
    W-->>B: 302 redirect redirect_uri?code=CODE&state=STATE
    Note over B: 注意：微信是让【浏览器跳转】到回调地址而不是直接回调后端
    B->>S: GET /auth/wechat/callback?code=...&state=...

    S->>S: 校验 state(存在/未过期/未使用)
    S->>S: 通过 state 找到 ticket
    S->>W: 用 code 换 access_token + openid(+unionid)
    W-->>S: 返回 access_token, openid, unionid(可选)

    opt 需要头像昵称
      S->>W: GET /sns/userinfo(access_token,openid)
      W-->>S: nickname/avatar...
    end

    S->>R: 请求登录 (wechat+openid|unionid)
    R-->>S: 返回登录结果
    alt 登录成功
      S->>S: 创建站点登录态(session/JWT/exchange_code)
      S-->>B: WS推送 {status:"OK", exchange_code:"..."}
    else 登录失败 (未注册/未绑定)
      S-->>B: WS推送 {status:"NEED_BIND"} 或 {status:"NEED_REGISTER"}
    end
  else 用户取消/拒绝
    W-->>B: 302 redirect redirect_uri?error=access_denied&state=STATE
    B->>S: GET /auth/wechat/callback?error=...&state=...
    S->>S: 校验 state 并标记结束
    S-->>B: WS推送 {status:"CANCEL"}
  end
```

## Contributing guidelines

项目以 Go 实现，使用 [Gin](https://github.com/gin-gonic/gin) 作为 Web 框架。

### Dev stage

1. `go run ./cmd/server`

1. restful request: `curl http://localhost:8068/api/v1/users/123/wechat/qr` or `curl http://localhost:8068/api/v1/health`

1. websocket request: use `wscat` to connect `wscat -c ws://localhost:8068/ws/v1/auth`

### Production stage

Build and deploy instructions.

#### Build

- Intel Linux: `./scripts/build.sh` OR `GOOS=linux GOARCH=amd64 ./scripts/build.sh`

- Apple Silicon（M 系列）: `./scripts/build.sh` OR `GOOS=darwin GOARCH=arm64 ./scripts/build.sh`

注意，交叉编译时需明确指定上述环境变量，且二进制产物只能在对应平台运行 (或同架构的容器中)。

#### Dockerize

镜像制作和推送，执行 `sh scripts/docker_build_and_push.sh` 后，镜像会更新到[dockerhub](https://hub.docker.com/repository/docker/weiguozhu/orginone-third-login)，可自行 pull 下来使用 (本地亦如是)。

#### Deploy

Docker run: `sh scripts/docker_bootstrap.sh`，在生产环境推荐以该种方式发布。

#### Test

执行 `curl http://localhost:8068/api/v1/health` 查看服务是否启动成功。