junhong_cmp_fiber/openspec/changes/archive/2026-01-15-implement-b-end-auth-system/proposal.md

# 提案：实现 B 端认证系统

**Change ID**: `implement-b-end-auth-system`  
**类型**: 新功能  
**优先级**: 高  
**预计工作量**: 3-5 天

---

## 概述

完成 B 端（Web 后台 + H5 端）的完整认证系统，包括后台管理员登录、代理商登录、企业用户登录，以及配套的 token 管理、登出、刷新等功能。

## 背景

### 当前状态

项目已完成：
- ✅ C 端（个人客户）JWT 认证
- ✅ 通用认证中间件框架 (`pkg/middleware/auth.go`)
- ✅ RBAC 权限体系（角色、权限、数据权限过滤）
- ✅ 用户上下文传递机制
- ✅ 密码加密（bcrypt）

缺失功能：
- ❌ B 端登录接口（后台/代理/企业）
- ❌ B 端 token 生成和 Redis 存储
- ❌ 登出功能（token 撤销）
- ❌ Token 刷新机制
- ❌ 多端认证中间件配置

### 用户需求

用户明确要求：
> "目前不需要做个人用户登录，只需要做后台代理商/平台登录，h5端代理/企业用户登录"

需要支持：
1. **Web 后台登录**：平台管理员、代理商账号
2. **H5 端登录**：代理商账号、企业账号

## 目标

### 业务目标

1. 实现后台管理员、代理商、企业用户的账号密码登录
2. 支持多端（Web 后台、H5）分别认证
3. 提供完整的 token 生命周期管理（生成、验证、刷新、撤销）
4. 与现有 RBAC 权限体系无缝集成
5. 保持与 C 端认证的架构一致性

### 技术目标

1. 复用现有认证中间件框架
2. 遵循项目分层架构（Handler → Service → Store → Model）
3. 统一错误处理和响应格式
4. 所有 API 响应时间 < 200ms（P95）
5. Token 验证缓存在 Redis，支持高并发

## 设计决策

### 1. 认证方式选择

**决策**：B 端使用 **Redis Token** 认证，而非 JWT

**理由**：
- ✅ **可撤销性**：支持立即登出和强制下线
- ✅ **灵活性**：可存储额外会话信息（登录时间、设备信息等）
- ✅ **安全性**：Token 可以是随机 UUID，不携带敏感信息
- ✅ **分布式友好**：Redis 集群天然支持多服务器部署
- ✅ **与现有架构一致**：项目已使用 Redis 存储 token（`pkg/validator/token.go`）

**对比 JWT**：
- ❌ JWT 无法撤销（除非维护黑名单，失去无状态优势）
- ❌ JWT payload 可见（Base64 解码即可查看）
- ❌ 不适合需要频繁撤销的场景（后台管理系统）

### 2. Token 存储结构

**Redis Key 设计**：
```
auth:token:{token}          → 用户基本信息（JSON）
auth:user:{userID}:tokens   → 用户的所有 token 列表（Set）
```

**存储内容**：
```json
{
  "user_id": 123,
  "user_type": 2,
  "shop_id": 10,
  "enterprise_id": 0,
  "username": "admin",
  "login_time": "2026-01-15T12:00:00Z",
  "device": "web",
  "ip": "192.168.1.1"
}
```

**TTL 配置**：
- Access Token：24 小时（可配置）
- Refresh Token：7 天（可配置）

### 3. 多端认证设计

**Web 后台**：
- 路由前缀：`/api/admin/*`
- 认证方式：Bearer Token
- 权限过滤：`platform = 'web' OR platform = 'all'`
- 支持用户类型：超级管理员、平台用户、代理账号

**H5 端**：
- 路由前缀：`/api/h5/*`
- 认证方式：Bearer Token
- 权限过滤：`platform = 'h5' OR platform = 'all'`
- 支持用户类型：代理账号、企业账号

### 4. 登录流程设计

```
┌─────────────────────────────────────────────────────────────┐
│                    POST /api/admin/login                     │
│                    POST /api/h5/login                        │
└────────────────────────────┬────────────────────────────────┘
                             │
                  ┌──────────▼──────────┐
                  │ 1. 验证用户名/密码  │
                  │    (bcrypt.Compare)│
                  └──────────┬──────────┘
                             │
                  ┌──────────▼──────────┐
                  │ 2. 检查账号状态     │
                  │    (status=1)      │
                  └──────────┬──────────┘
                             │
                  ┌──────────▼──────────┐
                  │ 3. 生成 UUID Token  │
                  │    (uuid.New())    │
                  └──────────┬──────────┘
                             │
                  ┌──────────▼──────────┐
                  │ 4. 存储到 Redis     │
                  │    (TTL: 24h)      │
                  └──────────┬──────────┘
                             │
                  ┌──────────▼──────────┐
                  │ 5. 返回 Token       │
                  │    (+ 用户信息)    │
                  └──────────┬──────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│ Response: {token, refresh_token, user_info, permissions}    │
└─────────────────────────────────────────────────────────────┘
```

### 5. 权限检查流程

```
请求 → Auth 中间件 → Permission 中间件 → 业务处理器
         ↓                ↓
     验证 Token      检查权限码
         ↓                ↓
   设置用户上下文    验证角色权限
```

## 范围

### 包含功能

#### 核心功能
1. **登录接口**
   - `POST /api/admin/login`：后台登录（平台用户、代理账号）
   - `POST /api/h5/login`：H5 端登录（代理账号、企业账号）
   - 验证用户名/密码
   - 生成 access_token 和 refresh_token
   - 返回用户信息和权限列表

2. **登出接口**
   - `POST /api/admin/logout`：后台登出
   - `POST /api/h5/logout`：H5 端登出
   - 撤销 access_token
   - 撤销 refresh_token
   - 清理 Redis 缓存

3. **Token 刷新接口**
   - `POST /api/admin/refresh-token`：后台刷新 token
   - `POST /api/h5/refresh-token`：H5 端刷新 token
   - 验证 refresh_token
   - 生成新的 access_token
   - 可选：刷新 refresh_token（rotation）

4. **认证中间件配置**
   - Web 后台认证中间件
   - H5 端认证中间件
   - 统一使用 `pkg/middleware/auth.go` 的 `Auth()` 函数
   - 配置不同的 token 验证器

5. **Token 管理服务**
   - Token 生成（access + refresh）
   - Token 验证（从 Redis 查询）
   - Token 撤销（删除 Redis key）
   - Token 续期（更新 TTL）
   - 用户所有 token 查询和批量撤销

#### 辅助功能
6. **获取当前用户信息**
   - `GET /api/admin/me`：后台当前用户
   - `GET /api/h5/me`：H5 当前用户
   - 返回用户信息、角色、权限列表

7. **修改当前用户密码**
   - `PUT /api/admin/password`：后台修改密码
   - `PUT /api/h5/password`：H5 修改密码
   - 验证旧密码
   - 更新密码（bcrypt 哈希）
   - 撤销所有旧 token

### 不包含功能

- ❌ 找回密码（通过邮件/短信）→ 后续迭代
- ❌ 两步验证（2FA）→ 后续迭代
- ❌ 单点登录（SSO）→ 后续迭代
- ❌ OAuth 第三方登录（微信、钉钉等）→ 后续迭代
- ❌ 设备管理和多设备限制 → 后续迭代
- ❌ 登录历史和审计日志 → 后续迭代

## 技术方案

### 1. 目录结构

```
internal/
├── handler/
│   ├── admin/
│   │   └── auth.go           # 后台认证 Handler（新增）
│   └── h5/
│       └── auth.go           # H5 认证 Handler（新增）
├── service/
│   └── auth/
│       └── service.go        # 认证服务（新增）
├── store/
│   └── postgres/
│       └── account_store.go  # 账号查询（已存在，扩展方法）
├── model/
│   └── auth_dto.go           # 认证 DTO（新增）
pkg/
├── auth/
│   └── token.go              # Token 管理工具（新增）
├── constants/
│   └── auth.go               # 认证常量（新增）
└── middleware/
    └── auth.go               # 通用认证中间件（已存在，无需修改）
```

### 2. 核心模块设计

#### 2.1 Token 管理器（pkg/auth/token.go）

```go
package auth

import (
	"context"
	"time"
	"github.com/google/uuid"
	"github.com/redis/go-redis/v9"
)

// TokenManager Token 管理器
type TokenManager struct {
	rdb               *redis.Client
	accessTokenTTL    time.Duration
	refreshTokenTTL   time.Duration
}

// TokenInfo Token 信息（存储在 Redis）
type TokenInfo struct {
	UserID       uint      `json:"user_id"`
	UserType     int       `json:"user_type"`
	ShopID       uint      `json:"shop_id,omitempty"`
	EnterpriseID uint      `json:"enterprise_id,omitempty"`
	Username     string    `json:"username"`
	LoginTime    time.Time `json:"login_time"`
	Device       string    `json:"device"`       // web / h5 / mobile
	IP           string    `json:"ip"`
}

// GenerateTokenPair 生成 access token 和 refresh token
func (m *TokenManager) GenerateTokenPair(ctx context.Context, info *TokenInfo) (accessToken, refreshToken string, err error)

// ValidateAccessToken 验证 access token 并返回用户信息
func (m *TokenManager) ValidateAccessToken(ctx context.Context, token string) (*TokenInfo, error)

// ValidateRefreshToken 验证 refresh token
func (m *TokenManager) ValidateRefreshToken(ctx context.Context, token string) (*TokenInfo, error)

// RefreshAccessToken 使用 refresh token 刷新 access token
func (m *TokenManager) RefreshAccessToken(ctx context.Context, refreshToken string) (newAccessToken string, err error)

// RevokeToken 撤销单个 token
func (m *TokenManager) RevokeToken(ctx context.Context, token string) error

// RevokeAllUserTokens 撤销用户的所有 token
func (m *TokenManager) RevokeAllUserTokens(ctx context.Context, userID uint) error

// RenewTokenTTL 续期 token（用于"记住我"功能）
func (m *TokenManager) RenewTokenTTL(ctx context.Context, token string, ttl time.Duration) error
```

#### 2.2 认证服务（internal/service/auth/service.go）

```go
package auth

import (
	"context"
	"github.com/break/junhong_cmp_fiber/internal/model"
	"github.com/break/junhong_cmp_fiber/pkg/auth"
	"golang.org/x/crypto/bcrypt"
)

// Service 认证服务
type Service struct {
	accountStore AccountStore
	tokenManager *auth.TokenManager
	logger       *zap.Logger
}

// LoginRequest 登录请求
type LoginRequest struct {
	Username string `json:"username" validate:"required"`
	Password string `json:"password" validate:"required"`
	Device   string `json:"device"`   // web / h5 / mobile
}

// LoginResponse 登录响应
type LoginResponse struct {
	AccessToken  string              `json:"access_token"`
	RefreshToken string              `json:"refresh_token"`
	User         *model.Account      `json:"user"`
	Permissions  []string            `json:"permissions"`
}

// Login 用户登录
func (s *Service) Login(ctx context.Context, req *LoginRequest, clientIP string) (*LoginResponse, error)

// Logout 用户登出
func (s *Service) Logout(ctx context.Context, token string) error

// RefreshToken 刷新 token
func (s *Service) RefreshToken(ctx context.Context, refreshToken string) (newAccessToken string, error)

// GetCurrentUser 获取当前用户信息
func (s *Service) GetCurrentUser(ctx context.Context, userID uint) (*model.Account, []string, error)

// ChangePassword 修改密码
func (s *Service) ChangePassword(ctx context.Context, userID uint, oldPassword, newPassword string) error
```

#### 2.3 认证 Handler（internal/handler/admin/auth.go）

```go
package admin

import (
	"github.com/gofiber/fiber/v2"
	"github.com/break/junhong_cmp_fiber/internal/service/auth"
	"github.com/break/junhong_cmp_fiber/pkg/response"
)

// AuthHandler 认证处理器
type AuthHandler struct {
	authService *auth.Service
}

// Login 登录
// POST /api/admin/login
func (h *AuthHandler) Login(c *fiber.Ctx) error

// Logout 登出
// POST /api/admin/logout
func (h *AuthHandler) Logout(c *fiber.Ctx) error

// RefreshToken 刷新 token
// POST /api/admin/refresh-token
func (h *AuthHandler) RefreshToken(c *fiber.Ctx) error

// GetMe 获取当前用户信息
// GET /api/admin/me
func (h *AuthHandler) GetMe(c *fiber.Ctx) error

// ChangePassword 修改密码
// PUT /api/admin/password
func (h *AuthHandler) ChangePassword(c *fiber.Ctx) error
```

### 3. 路由配置

```go
// internal/routes/admin.go

// 公开路由（无需认证）
public := api.Group("/admin")
public.Post("/login", authHandler.Login)
public.Post("/refresh-token", authHandler.RefreshToken)

// 受保护路由（需要认证）
protected := api.Group("/admin")
protected.Use(adminAuthMiddleware)  // 使用后台认证中间件
protected.Post("/logout", authHandler.Logout)
protected.Get("/me", authHandler.GetMe)
protected.Put("/password", authHandler.ChangePassword)

// ... 其他受保护路由
```

### 4. 中间件配置

```go
// internal/bootstrap/middlewares.go

// 后台认证中间件
adminAuthMiddleware := middleware.Auth(middleware.AuthConfig{
	TokenValidator: func(token string) (*middleware.UserContextInfo, error) {
		tokenInfo, err := tokenManager.ValidateAccessToken(ctx, token)
		if err != nil {
			return nil, err
		}
		
		// 检查用户类型（后台只允许平台用户和代理账号）
		if tokenInfo.UserType != constants.UserTypeSuperAdmin &&
		   tokenInfo.UserType != constants.UserTypePlatform &&
		   tokenInfo.UserType != constants.UserTypeAgent {
			return nil, errors.New(errors.CodeForbidden, "无权访问后台")
		}
		
		return &middleware.UserContextInfo{
			UserID:       tokenInfo.UserID,
			UserType:     tokenInfo.UserType,
			ShopID:       tokenInfo.ShopID,
			EnterpriseID: tokenInfo.EnterpriseID,
		}, nil
	},
	SkipPaths: []string{"/api/admin/login", "/api/admin/refresh-token"},
})

// H5 认证中间件
h5AuthMiddleware := middleware.Auth(middleware.AuthConfig{
	TokenValidator: func(token string) (*middleware.UserContextInfo, error) {
		tokenInfo, err := tokenManager.ValidateAccessToken(ctx, token)
		if err != nil {
			return nil, err
		}
		
		// 检查用户类型（H5 只允许代理账号和企业账号）
		if tokenInfo.UserType != constants.UserTypeAgent &&
		   tokenInfo.UserType != constants.UserTypeEnterprise {
			return nil, errors.New(errors.CodeForbidden, "无权访问 H5 端")
		}
		
		return &middleware.UserContextInfo{
			UserID:       tokenInfo.UserID,
			UserType:     tokenInfo.UserType,
			ShopID:       tokenInfo.ShopID,
			EnterpriseID: tokenInfo.EnterpriseID,
		}, nil
	},
	SkipPaths: []string{"/api/h5/login", "/api/h5/refresh-token"},
})
```

### 5. Redis Key 设计

```go
// pkg/constants/auth.go

// RedisAuthTokenKey 生成认证令牌的 Redis 键
func RedisAuthTokenKey(token string) string {
	return fmt.Sprintf("auth:token:%s", token)
}

// RedisRefreshTokenKey 生成刷新令牌的 Redis 键
func RedisRefreshTokenKey(token string) string {
	return fmt.Sprintf("auth:refresh:%s", token)
}

// RedisUserTokensKey 生成用户令牌列表的 Redis 键
func RedisUserTokensKey(userID uint) string {
	return fmt.Sprintf("auth:user:%d:tokens", userID)
}
```

### 6. 错误码扩展

```go
// pkg/errors/codes.go

// 认证相关错误码（已存在）
CodeMissingToken     = 1002 // 缺失认证令牌
CodeInvalidToken     = 1003 // 无效或过期的令牌
CodeUnauthorized     = 1004 // 未授权
CodeForbidden        = 1005 // 禁止访问

// 新增登录相关错误码
CodeInvalidCredentials = 1010 // 用户名或密码错误
CodeAccountDisabled    = 1011 // 账号已禁用
CodeAccountLocked      = 1012 // 账号已锁定
CodePasswordExpired    = 1013 // 密码已过期
CodeInvalidOldPassword = 1014 // 旧密码错误
CodeInvalidPassword    = 1015 // 密码格式不正确（已存在）
CodePasswordTooWeak    = 1016 // 密码强度不足（已存在）
```

## 实现计划

详见 `tasks.md`

## 测试策略

### 单元测试

1. **Token 管理器测试**（`pkg/auth/token_test.go`）
   - 生成 token 对
   - 验证 access token
   - 验证 refresh token
   - 刷新 token
   - 撤销 token
   - Redis 连接失败处理

2. **认证服务测试**（`internal/service/auth/service_test.go`）
   - 登录成功
   - 登录失败（密码错误、账号禁用）
   - 登出
   - 刷新 token
   - 修改密码

### 集成测试

3. **登录接口测试**（`tests/integration/admin_auth_test.go`）
   - 后台登录成功
   - H5 登录成功
   - 用户名不存在
   - 密码错误
   - 账号禁用
   - 返回 token 和用户信息

4. **认证中间件测试**（`tests/integration/admin_auth_middleware_test.go`）
   - 有效 token 访问受保护路由
   - 无效 token 返回 401
   - 缺失 token 返回 401
   - 过期 token 返回 401
   - 用户类型不匹配返回 403

5. **Token 刷新测试**（`tests/integration/token_refresh_test.go`）
   - 使用有效 refresh token 刷新
   - 使用无效 refresh token 失败
   - 撤销后的 refresh token 失败

6. **登出测试**（`tests/integration/logout_test.go`）
   - 登出后 token 失效
   - 登出后无法访问受保护路由

### 性能测试

7. **认证性能测试**（`tests/benchmark/auth_bench_test.go`）
   - Token 验证性能（目标：< 5ms）
   - 登录性能（目标：< 200ms）
   - 并发登录测试（1000 并发）

### 测试覆盖率目标

- 核心业务逻辑：≥ 90%
- Handler 层：≥ 80%
- 整体覆盖率：≥ 70%

## 风险和缓解

### 风险 1：Redis 单点故障导致认证不可用

**影响**：Redis 宕机导致所有用户无法登录和认证

**缓解措施**：
- 使用 Redis 哨兵模式或集群模式（生产环境）
- 实现 Redis 健康检查和自动重连
- 添加 Circuit Breaker 模式，避免雪崩
- 日志记录 Redis 连接失败，便于快速排查

### 风险 2：Token 泄露导致账号被盗用

**影响**：攻击者获取 token 后可以冒充用户

**缓解措施**：
- Token 使用 UUID v4（不可预测）
- HTTPS 强制加密传输
- Token 设置合理的过期时间（24 小时）
- 实现 IP 绑定和设备指纹（后续迭代）
- 异常登录检测和通知（后续迭代）

### 风险 3：暴力破解登录

**影响**：攻击者通过暴力破解获取账号密码

**缓解措施**：
- 集成现有的限流中间件（`pkg/middleware/ratelimit.go`）
- 登录失败次数限制（5 次锁定 15 分钟）
- 添加图形验证码（后续迭代）
- 记录登录失败日志，便于审计

### 风险 4：密码存储安全

**影响**：数据库泄露导致密码被破解

**缓解措施**：
- 已使用 bcrypt 哈希（cost=10）
- 禁止明文密码传输（HTTPS）
- 密码复杂度要求（8-32 位，含字母数字）
- 定期密码过期提醒（后续迭代）

### 风险 5：与现有代码集成冲突

**影响**：新代码与现有认证逻辑冲突

**缓解措施**：
- 复用现有的 `pkg/middleware/auth.go` 框架
- 不修改 C 端认证逻辑（`internal/middleware/personal_auth.go`）
- 充分的集成测试覆盖
- 代码审查（Code Review）

## 依赖

### 外部依赖

- ✅ Redis：token 存储和验证
- ✅ PostgreSQL：用户账号存储
- ✅ bcrypt：密码哈希
- ✅ UUID：token 生成

### 内部依赖

- ✅ `pkg/middleware/auth.go`：通用认证中间件
- ✅ `pkg/errors`：统一错误处理
- ✅ `pkg/response`：统一响应格式
- ✅ `pkg/constants`：常量定义
- ✅ `internal/model/account.go`：账号模型
- ✅ `internal/store/postgres/account_store.go`：账号数据访问

## 文档

需要创建的文档：

1. **API 文档**（`docs/api/auth.md`）
   - 登录接口说明
   - 登出接口说明
   - Token 刷新接口说明
   - 错误码说明
   - 示例请求和响应

2. **使用指南**（`docs/auth-usage-guide.md`）
   - 如何在新路由中集成认证中间件
   - 如何获取当前用户信息
   - 如何撤销用户 token
   - 常见问题（FAQ）

3. **架构说明**（`docs/auth-architecture.md`）
   - 认证流程图
   - Token 存储结构
   - 中间件执行顺序
   - 安全机制说明

## 验收标准

1. ✅ 后台管理员可以使用用户名/密码登录
2. ✅ H5 代理商/企业用户可以使用用户名/密码登录
3. ✅ 登录成功返回 access_token、refresh_token 和用户信息
4. ✅ 受保护的 API 需要携带有效 token 才能访问
5. ✅ Token 过期或无效时返回 401 错误
6. ✅ 用户可以登出，登出后 token 立即失效
7. ✅ 用户可以使用 refresh_token 刷新 access_token
8. ✅ 用户可以修改密码，修改后所有旧 token 失效
9. ✅ 不同用户类型只能访问对应端口的 API（后台/H5）
10. ✅ 所有测试通过，覆盖率达标
11. ✅ API 响应时间 P95 < 200ms
12. ✅ 文档完整，便于其他开发者使用

## 后续迭代

以下功能留待后续迭代：

1. **找回密码**：通过邮件/短信发送重置链接
2. **两步验证（2FA）**：短信验证码、TOTP
3. **单点登录（SSO）**：统一登录入口
4. **OAuth 第三方登录**：微信企业登录、钉钉登录
5. **设备管理**：查看登录设备、强制下线
6. **登录历史**：记录登录时间、IP、设备
7. **审计日志**：记录认证授权相关操作
8. **IP 白名单**：限制特定 IP 访问
9. **账号锁定策略**：登录失败次数限制
10. **密码策略**：强制定期修改、密码历史记录

---

**提案状态**：待审批  
**创建时间**：2026-01-15  
**最后更新**：2026-01-15