docs(gateway): gateway 剩余文件注释改中文（逐行 1:1，代码零字节改动）

主人 2026-10-03 拍板「注释一律中文」；gateway 至此整包注释中文化完成（本会话共 3 批：
已推库 16 个文件 + 本批剩余文件）。
校验：机械校验（非注释改动行）= 空；剥注释后代码文本逐行比对全等（不一致文件数 0）；
全树 go test ./... 58 包 ok / 0 FAIL；交叉编译绿。

internal/services/gateway/auth_refresh.go

@@ -12,17 +12,17 @@ import (
 	apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
 )
 
-// defaultRefreshTTL is the refresh-token lifetime used when cfg.Auth.RefreshTTL
-// is unset (an undecoded config in tests), matching the AUTH_REFRESH_TTL default.
+// defaultRefreshTTL 是 cfg.Auth.RefreshTTL 未设置时（测试中未解码的
+// 配置）使用的 refresh token 生命周期，与 AUTH_REFRESH_TTL 默认值一致。
 const defaultRefreshTTL = 720 * time.Hour
 
-// refreshRequest is the POST /api/v1/auth/refresh body.
+// refreshRequest 是 POST /api/v1/auth/refresh 的请求体。
 type refreshRequest struct {
 	RefreshToken string `json:"refreshToken"`
 }
 
-// refreshResponse is the refresh success payload: a fresh access token plus the
-// rotated refresh token (omitted when rotation is disabled by config).
+// refreshResponse 是刷新成功的载荷：新的访问令牌加上
+// 轮换后的 refresh token（配置禁用轮换时省略）。
 type refreshResponse struct {
 	Token        string `json:"token"`
 	ExpiresAt    int64  `json:"expiresAt"`
@@ -30,13 +30,13 @@ type refreshResponse struct {
 	RefreshToken string `json:"refreshToken,omitempty"`
 }
 
-// logoutRequest is the POST /api/v1/auth/logout body.
+// logoutRequest 是 POST /api/v1/auth/logout 的请求体。
 type logoutRequest struct {
 	RefreshToken string `json:"refreshToken"`
 }
 
-// refreshTTL returns the configured refresh-token lifetime, falling back to
-// defaultRefreshTTL when the config was not decoded (zero value).
+// refreshTTL 返回已配置的 refresh token 生命周期，配置未解码
+// （零值）时回退到 defaultRefreshTTL。
 func (s *Server) refreshTTL() time.Duration {
 	if s.cfg != nil && s.cfg.Auth.RefreshTTL > 0 {
 		return s.cfg.Auth.RefreshTTL
@@ -44,16 +44,16 @@ func (s *Server) refreshTTL() time.Duration {
 	return defaultRefreshTTL
 }
 
-// refreshRotate reports whether single-use rotation is enabled. Rotation is the
-// default; only an explicit AUTH_REFRESH_ROTATE_DISABLED=true opts out.
+// refreshRotate 报告是否启用一次性轮换。轮换是
+// 默认；只有显式 AUTH_REFRESH_ROTATE_DISABLED=true 才选择退出。
 func (s *Server) refreshRotate() bool {
 	return s.cfg == nil || !s.cfg.Auth.RefreshRotateDisabled
 }
 
-// handleRefresh exchanges a valid opaque refresh token for a new access token,
-// rotating the refresh token by default. It is public (the refresh token is the
-// credential) and returns 401 invalid_grant for an unknown, revoked, or expired
-// token. A successful rotation is audited; the token itself is never logged.
+// handleRefresh 用有效的非透明 refresh token 换取新的访问令牌，
+// 默认轮换 refresh token。它是公开的（refresh token 就是
+// 凭据），对未知、已吊销或已过期的 token 返回 401 invalid_grant。
+// 成功的轮换会被审计；token 本身绝不记日志。
 func (s *Server) handleRefresh(w http.ResponseWriter, r *http.Request) {
 	var req refreshRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
@@ -92,18 +92,18 @@ func (s *Server) handleRefresh(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
-// handleLogout revokes the refresh token in the body. It is public and
-// idempotent: an unknown or already revoked token yields {"revoked": false} with
-// 200 rather than an error, so a client can always clear its local state.
+// handleLogout 吊销请求体中的 refresh token。它公开且
+// 幂等：未知或已吊销的 token 返回 {"revoked": false} 与
+// 200 而不是错误，因此客户端总能清理其本地状态。
 //
-// The body may carry either a refreshToken (revokes that one grant) or nothing,
-// in which case the Authorization Bearer access token identifies the account and
-// every refresh grant for it is revoked (logout on all devices). A request with
-// neither is a 400.
+// 请求体可以携带 refreshToken（只吊销那一份授权），也可以不携带，
+// 此时 Authorization Bearer 访问令牌标识账号，该账号的
+// 每一份 refresh 授权都被吊销（全设备登出）。两者都
+// 没有的请求是 400。
 func (s *Server) handleLogout(w http.ResponseWriter, r *http.Request) {
 	var req logoutRequest
-	// An empty body is valid: it means "no refreshToken", and the account is
-	// identified by the bearer access token below.
+	// 空请求体是合法的：它意味着「无 refreshToken」，账号由
+	// 下面的 bearer 访问令牌标识。
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil && !errors.Is(err, io.EOF) {
 		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid request body"))
 		return
@@ -141,8 +141,8 @@ func (s *Server) handleLogout(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"revoked": n > 0, "revokedCount": n})
 }
 
-// bearerFromRequest extracts the Bearer credential from the Authorization
-// header, returning "" when the header is absent or malformed.
+// bearerFromRequest 从 Authorization 头提取 Bearer 凭据，
+// 头缺失或畸形时返回 ""。
 func bearerFromRequest(r *http.Request) string {
 	const prefix = "Bearer "
 	h := r.Header.Get("Authorization")