DEV-MERGE-LEGACY-BACKEND-2026/internal/identity/handler/handler.go

// Package handler 身份域 HTTP 接入层（/auth/* 端点，架构规格 §3.2 三层之"Handler"）。
//
// 分层职责：
//   - 本包（Handler）：把请求体绑定/校验（validator）→ 调 service.AuthService（纯业务）→
//     把 *AppError 映射为统一响应信封（response.Fail / OK）。**不写业务逻辑、不直接碰 DB/Redis**。
//   - Service（identity/service）：两步登录 / me / refresh / logout 编排（见其包注释）。
//   - 验签中间件（identity/handler 的 auth.go，T4-5）：受保护路由前置，验签 + 作用域注入；
//     本包 Me/Logout 从 c.Locals 读取中间件写入的已验签 claims（见 ClaimsCtxKey）。
//
// 端点清单（路由挂载在 T4-6 main 完成；此处只定义方法）：
//   - POST /auth/login    两步登录①：验账密 → 一次性票据 + 用户 + 作用域列表（**公开**，无鉴权）
//   - POST /auth/issue    两步登录②：消费票据 + 选作用域 → access+refresh（**公开**，凭票据）
//   - POST /auth/refresh  refresh 轮换：旧 refresh 换新对（**公开**，凭 refresh）
//   - GET  /auth/wechat/qrcode、GET /auth/wechat/status  微信扫码占位（暂未开放）
//   - GET  /auth/me       登录态自查（**受保护**，需 Auth 中间件）
//   - POST /auth/logout   登出（**受保护**，恒 200 幂等；撤销尽力而为）
//
// 契约要点：
//   - HTTP 恒 200，真实状态在 body code（铁律 6；见 infra/response）。
//   - 校验失败由 validator 内部写 code=2001 并返回 false，Handler `return nil` 终止（铁律 7）。
//   - logout 对客户端**恒 200**（本地态必清）：撤销失败只记日志，不阻断（对齐前端 doLogout 幂等语义）。
package handler

import (
	"encoding/json"
	"time"

	"github.com/gofiber/fiber/v2"
	"go.uber.org/zap"

	"yuansiwei/unified-backend/internal/identity/model"
	"yuansiwei/unified-backend/internal/identity/service"
	"yuansiwei/unified-backend/internal/identity/token"
	apperrors "yuansiwei/unified-backend/internal/infra/errors"
	"yuansiwei/unified-backend/internal/infra/response"
	"yuansiwei/unified-backend/internal/infra/validator"
)

// ClaimsCtxKey 已验签 claims 在 fiber.Ctx 局部值（c.Locals）中的键。
//
// 由 T4-5 的 Auth 验签中间件在验签成功后写入（*token.Claims）；本包 Me/Logout
// 经 claimsFromCtx 读回。**中间件写入与 Handler 读取两端用同一常量**，避免字符串散落
// （对齐 infra/scope 的 CtxKey 纪律）。受保护路由若无此值 = 中间件链配置错误，按未登录拒绝。
const ClaimsCtxKey = "authClaims"

// Handler 身份域 HTTP 处理器（启动装配一次，全进程共享）。
//
// 字段（装配入口 New 注入，均必填）：
//   - svc：身份域业务服务（两步登录 / me / refresh / logout 编排，T4-3）。
//   - log：结构化日志器（logout 撤销失败的告警出口；nil 时静默不记，不阻断）。
type Handler struct {
	svc *service.AuthService
	log *zap.Logger
}

// Config Handler 装配参数（T4-6 main 按此构造）。
type Config struct {
	// Svc 身份域业务服务（必填）。
	Svc *service.AuthService
	// Log 结构化日志器（可选；nil 时登出撤销失败不记日志，仍恒 200）。
	Log *zap.Logger
}

// New 构造身份域 HTTP 处理器。
//
// 入参：cfg Config：见 Config 字段说明。
// 出参：
//   - *Handler：就绪处理器。
//   - error：必填依赖缺失（Svc 为 nil，fail-fast——无业务服务不允许挂载端点）。
func New(cfg Config) (*Handler, error) {
	if cfg.Svc == nil {
		return nil, apperrors.New(apperrors.CodeInternal, "handler: AuthService 未注入")
	}
	return &Handler{svc: cfg.Svc, log: cfg.Log}, nil
}

// ---- 请求体 DTO（入参；camelCase 与前端契约严格对齐，见 README 命名规范）----

// LoginReq 两步登录① 请求体（PC 账号密码登录）。
//
// 字段：
//   - Username：登录账号（用户名；归一/校验在 Service，此处仅校验非空与长度上限）。
//   - Password：明文密码（6~128 位；**仅内存调用栈，禁止进日志/响应**）。
type LoginReq struct {
	Username string `json:"username" validate:"required,max=64"`
	Password string `json:"password" validate:"required,min=6,max=128"`
}

// IssueReq 两步登录② 请求体（选定作用域后换取 token）。
//
// 字段：
//   - LoginTicket：① 返回的一次性票据（32 字符 hex；已消费/过期/不存在 → 拒绝）。
//   - InstitutionID：选定机构（scope 根；0=平台级超管，故不标 required）。
//   - CampusID：选定校区（0=机构级/不限，故不标 required）。
type IssueReq struct {
	LoginTicket   string `json:"loginTicket" validate:"required,len=32"`
	InstitutionID int64  `json:"institutionId"`
	CampusID      int64  `json:"campusId"`
}

// RefreshReq refresh 轮换请求体。
type RefreshReq struct {
	// RefreshToken：旧 refresh 不透明串（64 字符 hex = 32 字节随机，Issue 返回的原样值；
	// 见 token.Issue——hex.EncodeToString(32 字节) 恒 64 位）。
	RefreshToken string `json:"refreshToken" validate:"required,len=64"`
}

// LogoutReq 登出请求体（refresh 可空——仅凭 access jti 也能拉黑当前 access）。
type LogoutReq struct {
	// RefreshToken：当前 refresh 串（删其白名单键；空则跳过，仅吊销 access）。
	RefreshToken string `json:"refreshToken"`
}

// ---- 端点 ----

// Login 两步登录**第一步**（POST /auth/login，公开）。
//
// 出参（成功）：LoginStep1 → {loginTicket, user, memberships[]}（**不签 token**）。
// 出参（失败）：code 1001（统一文案防枚举）/ 2001（参数）/ 5002（DB·票据写失败）。
func (h *Handler) Login(c *fiber.Ctx) error {
	var req LoginReq
	if !validator.Validate(c, &req) { // 校验失败：body code=2001 已写出
		return nil
	}
	res, err := h.svc.Login(c.Context(), model.IdentityTypeUsername, req.Username, req.Password)
	if err != nil {
		return response.Fail(c, err)
	}
	return response.OK(c, res)
}

// Issue 两步登录**第二步**（POST /auth/issue，公开，凭一次性票据）。
//
// 出参（成功）：TokenPair → {accessToken, refreshToken, expiresAt, user, roles, institutionId, campusId}。
// 出参（失败）：code 1001（票据失效）/ 1003（作用域越权/归属失效）/ 5002（签发写白名单失败）。
func (h *Handler) Issue(c *fiber.Ctx) error {
	var req IssueReq
	if !validator.Validate(c, &req) {
		return nil
	}
	res, err := h.svc.Issue(c.Context(), req.LoginTicket, req.InstitutionID, req.CampusID)
	if err != nil {
		return response.Fail(c, err)
	}
	return response.OK(c, res)
}

// Me 登录态自查（GET /auth/me，**受保护**——需 T4-5 Auth 中间件前置验签并写入 claims）。
//
// 出参（成功）：MeResult → {user 字段 + roles, institutionId, campusId, memberships[]}（菜单刷新恢复）。
// 出参（失败）：code 1001（中间件未注入 claims = 未登录）/ 3001（用户不存在）/ 5002（DB 故障）。
func (h *Handler) Me(c *fiber.Ctx) error {
	claims := claimsFromCtx(c)
	if claims == nil { // 公开路由误配或中间件未执行：按未登录拒绝
		return response.Fail(c, apperrors.ErrUnauth)
	}
	res, err := h.svc.Me(c.Context(), *claims)
	if err != nil {
		return response.Fail(c, err)
	}
	return response.OK(c, res)
}

// Refresh refresh 轮换（POST /auth/refresh，公开，凭旧 refresh）。
//
// 出参（成功）：TokenPair（新 access + 新 refresh；旧 refresh 立即失效）。
// 出参（失败）：code 1002（refresh 失效，前端跳重新登录）/ 5002（轮换写白名单/回读用户 DB 故障）。
func (h *Handler) Refresh(c *fiber.Ctx) error {
	var req RefreshReq
	if !validator.Validate(c, &req) {
		return nil
	}
	res, err := h.svc.Refresh(c.Context(), req.RefreshToken)
	if err != nil {
		return response.Fail(c, err)
	}
	return response.OK(c, res)
}

// Logout 登出（POST /auth/logout，**受保护**，对客户端**恒 200** 幂等）。
//
// 语义：撤销"尽力而为"——删 refresh 白名单 + 拉黑当前 access jti；任一步失败仅记告警日志，
// 仍返回成功（前端本地态必清；access 30min 自然过期 + 黑名单兜底）。
//
// 出参（恒成功）：code 200，data 省略（无数据体）。
func (h *Handler) Logout(c *fiber.Ctx) error {
	var req LogoutReq
	// 尽力解析（refresh 可空；body 非 JSON 也不阻断——登出幂等，本地态必清）
	_ = json.Unmarshal(c.Body(), &req)

	claims := claimsFromCtx(c)
	if claims == nil {
		// 中间件未注入 claims（理论不该发生——logout 在受保护路由）：仍恒 200，仅记日志
		if h.log != nil {
			h.log.Warn("logout: 无已验签 claims（中间件未注入），仅清本地态")
		}
		return response.OK(c, nil)
	}
	remaining := time.Duration(0)
	if claims.ExpiresAt != nil {
		remaining = time.Until(claims.ExpiresAt.Time) // 黑名单键 TTL = access 剩余有效期
	}
	if err := h.svc.Logout(c.Context(), req.RefreshToken, claims.ID, remaining); err != nil {
		// 撤销失败不阻断登出（对齐前端 doLogout 幂等语义）：记告警供排障
		if h.log != nil {
			h.log.Warn("logout 撤销失败（已忽略，前端本地态必清）",
				zap.String("jti", claims.ID), zap.Error(err))
		}
	}
	return response.OK(c, nil)
}

// WechatQrcode 微信扫码登录——获取二维码（GET /auth/wechat/qrcode，占位）。
//
// 现状：**后端微信扫码端点未就绪**（per-campus 授权链路待实现），返回"暂未开放"占位，
// PC 前端微信 tab 据此显示"暂未开放"。真实实现落地后替换本方法（见 PC 前端契约）。
func (h *Handler) WechatQrcode(c *fiber.Ctx) error {
	return response.Fail(c, apperrors.New(apperrors.CodeInternal, "微信扫码登录暂未开放"))
}

// WechatStatus 微信扫码登录——轮询扫码状态（GET /auth/wechat/status?state=xxx，占位）。
//
// 现状：同 WechatQrcode，**后端未就绪**，返回"暂未开放"占位。
func (h *Handler) WechatStatus(c *fiber.Ctx) error {
	return response.Fail(c, apperrors.New(apperrors.CodeInternal, "微信扫码登录暂未开放"))
}

// claimsFromCtx 从 fiber.Ctx 局部值读取已验签 claims（T4-5 中间件写入 *token.Claims）。
//
// 出参：*token.Claims；未写入或类型不符时返回 nil（调用方按未登录拒绝）。
func claimsFromCtx(c *fiber.Ctx) *token.Claims {
	if c == nil {
		return nil
	}
	if cl, ok := c.Locals(ClaimsCtxKey).(*token.Claims); ok {
		return cl
	}
	return nil
}