user-system/docs/code-review/PRD_GAP_DESIGN_PLAN.md

# PRD 功能缺口精确分析与完善规划设计

**文档版本**: v1.0  
**编写日期**: 2026-04-01  
**基于**: CODE_REVIEW_REPORT_2026-04-01-V2.md + 实际代码逐行核查  
**目的**: 纠正历史报告的模糊描述，提供可执行的实现规划

---

## 一、核查方法与结论修正

本次对七项"已知缺口"进行了**逐文件逐行**的实际代码核查，结论如下：

| 缺口编号 | 历史报告结论 | 本次核查实际结论 | 变更 |
|---------|-------------|----------------|------|
| GAP-01 | 角色继承递归查询未实现 | ⚠️ **部分实现** — 逻辑层完整，但启动时未接入 | ↑ 修正 |
| GAP-02 | 密码重置（手机短信）未实现 | ✅ **已完整实现** — Service + Handler + 路由全部到位 | ✅ 关闭 |
| GAP-03 | 设备信任功能未实现 | ⚠️ **部分实现** — CRUD 完整，但登录流程未接入信任检查 | ↑ 修正 |
| GAP-04 | SSO（CAS/SAML）未实现 | ❌ **确认未实现** — SSOManager 是 OAuth2 包装，无 CAS/SAML | 维持 |
| GAP-05 | 异地登录检测未实现 | ⚠️ **部分实现** — AnomalyDetector 已有检测逻辑，但未接入启动流程 | ↑ 修正 |
| GAP-06 | 异常设备检测未实现 | ⚠️ **部分实现** — AnomalyDetector 有 NewDevice 事件，但设备指纹未采集 | ↑ 修正 |
| GAP-07 | SDK 支持未实现 | ❌ **确认未实现** — 无任何 SDK 文件 | 维持 |

**重新分类后**：
- ✅ 已完整实现（可关闭）：1 项（GAP-02）
- ⚠️ 骨架已有、接线缺失（低成本完成）：3 项（GAP-01、GAP-03、GAP-05/06）
- ❌ 需从零构建（高成本）：2 项（GAP-04 SSO、GAP-07 SDK）

---

## 二、各缺口精确诊断

---

### GAP-01：角色继承递归查询

#### 现状核查

**已实现的部分（代码证据）：**

```go
// internal/repository/role.go:178-213
// GetAncestorIDs 获取角色的所有祖先角色ID
func (r *RoleRepository) GetAncestorIDs(ctx context.Context, roleID int64) ([]int64, error) {
    // 循环向上查找父角色，直到没有父角色为止 ✅
}

// GetAncestors — 完整继承链 ✅

// internal/service/role.go:191-213
// GetRolePermissions — 已调用 GetAncestorIDs，合并所有祖先权限 ✅
```

**缺失的部分：**

1. **循环引用检测缺失**：`UpdateRole` 允许修改 `parent_id`，但不检测循环：A 的父是 B，B 的父又改成 A → 死循环
2. **深度限制缺失**：PRD 要求"继承深度可配置"，代码无上限保护
3. **用户权限查询未走继承路径**：
   - `authMiddleware` 中校验用户权限时，直接查 `user_role_permissions`，未调用 `GetRolePermissions`
   - 实际登录时 JWT 中的 permissions 也未包含继承权限

```go
// cmd/server/main.go — 完全没有以下调用：
// authService.SetAnomalyDetector(...)  ← 未接入
// 角色继承在 auth middleware 中也未走 GetRolePermissions
```

#### 问题等级
🟡 **中危** — 角色继承数据结构完整，但运行时不生效，是"假继承"

---

### GAP-02：密码重置（手机短信）

#### 现状核查

**完整实现证据：**

```
internal/service/password_reset.go
  - ForgotPasswordByPhone()     ✅ 生成6位验证码，缓存用户ID
  - ResetPasswordByPhone()      ✅ 验证码校验 + 密码重置

internal/api/handler/password_reset_handler.go
  - ForgotPasswordByPhone()     ✅ Handler 完整
  - ResetPasswordByPhone()      ✅ Handler 完整

internal/api/router/router.go:138-139
  - POST /api/v1/auth/forgot-password/phone  ✅ 路由已注册
  - POST /api/v1/auth/reset-password/phone   ✅ 路由已注册
```

**遗留问题（不影响功能闭合，但有质量风险）：**

```go
// password_reset_handler.go:100-101
// 获取验证码（不发送，由调用方通过其他渠道发送）
code, err := h.passwordResetService.ForgotPasswordByPhone(c.Request.Context(), req.Phone)
// 问题：code 被返回给 HTTP 调用方（可能是接口直接返回了明文验证码）
```

需确认 handler 是否把 code 暴露在响应体中。

#### 结论
✅ **此条缺口可关闭**，但需确认验证码不在响应中明文返回。

---

### GAP-03：设备信任功能

#### 现状核查

**已实现的部分：**

```
internal/domain/device.go
  - Device 模型：IsTrusted、TrustExpiresAt 字段 ✅

internal/repository/device.go
  - TrustDevice() / UntrustDevice()    ✅
  - GetTrustedDevices()               ✅

internal/service/device.go
  - TrustDevice(ctx, deviceID, trustDuration)  ✅
  - UntrustDevice()                   ✅
  - GetTrustedDevices()               ✅

internal/api/handler/device_handler.go
  - TrustDevice Handler               ✅
  - UntrustDevice Handler             ✅
  - GetMyTrustedDevices Handler       ✅

internal/api/router/router.go
  - POST /api/v1/devices/:id/trust     ✅
  - DELETE /api/v1/devices/:id/trust   ✅
  - GET /api/v1/devices/me/trusted     ✅
```

**缺失的关键接线：**

1. **登录流程未检查设备信任**：登录时没有"设备是否已信任 → 跳过 2FA"的逻辑
2. **登录请求无设备指纹字段**：`LoginRequest` 中无 `device_id` 或 `device_fingerprint`
3. **注册/登录后未自动创建 Device 记录**：用户登录后设备不会自动登记
4. **信任期限过期检查仅在查询时**：没有后台清理过期信任设备的 goroutine（虽然查询已过滤，但数据库垃圾数据会积累）
5. **前端无设备管理页面**：无法让用户查看/管理已登录设备

#### 问题等级
🟡 **中危** — API 骨架完整，但核心场景（信任设备免二次验证）未接线

---

### GAP-04：SSO（CAS/SAML 协议）

#### 现状核查

```go
// internal/auth/sso.go（SSOManager）
// 实现了 OAuth2 客户端模式的单点登录
// 支持：GitHub、Google 等 OAuth2 提供商的 SSO 接入

// 不支持的协议：
// - CAS (Central Authentication Service)：无任何实现
// - SAML 2.0：无任何实现
```

PRD 3.3 要求："支持 CAS、SAML 协议（**可选**）"

#### 分析
PRD 明确标注"可选"，CAS/SAML 是企业级 IdP（如 Okta、Active Directory）集成所需。
实现成本：**每个协议 ≥ 2 周**，属于大型独立特性。

#### 问题等级
💭 **低优先级** — PRD 标注可选，且 OAuth2 SSO 已实现；建议推迟到 v2.0

---

### GAP-05：异地登录检测

#### 现状核查

**已实现的部分：**

```go
// internal/security/ip_filter.go:182-359
// AnomalyDetector 完整实现：
//   - AnomalyNewLocation：新地区登录检测 ✅
//   - AnomalyBruteForce：暴力破解检测 ✅  
//   - AnomalyMultipleIP：多IP检测 ✅
//   - AnomalyNewDevice：新设备检测 ✅
//   - 自动封禁 IP ✅

// internal/service/auth.go:62-64
// anomalyRecorder 接口已定义 ✅

// internal/service/auth.go:199-201
// SetAnomalyDetector(detector anomalyRecorder) ✅ 方法存在
```

**关键缺口：**

```go
// cmd/server/main.go — 完全没有这两行：
anomalyDetector := security.NewAnomalyDetector(...)
authService.SetAnomalyDetector(anomalyDetector)
// 结果：anomalyDetector == nil，所有检测静默跳过
```

```go
// internal/service/auth.go:659-660（登录时传入的地理位置）
s.recordLoginAnomaly(ctx, &user.ID, ip, "", "", false)
// location 和 deviceFingerprint 都是空字符串！
// 即使接入了 AnomalyDetector，新地区检测也无法工作
```

**根本原因**：缺少 IP 地理位置解析模块（需要 MaxMind GeoIP 或类似数据库）

#### 问题等级
🟡 **中危** — 检测引擎已有，但需要两步接线：① 启动时注入 ② 登录时传入真实地理位置

---

### GAP-06：异常设备检测

#### 现状核查

**已实现：**
- `AnomalyDetector.detect()` 中的 `AnomalyNewDevice` 事件检测逻辑 ✅
- `Device` domain 模型完整 ✅

**缺失：**
1. **前端无设备指纹采集**：登录请求中无 `device_fingerprint` 字段
2. **后端 Login 接口不接收指纹**：`LoginRequest` 中无此字段
3. **即使有指纹，检测器未注入**（同 GAP-05）

#### 与 GAP-05 的关系
GAP-05（异地登录）和 GAP-06（异常设备）共享同一套 `AnomalyDetector` 基础设施，**同一批工作可以一起完成**。

---

### GAP-07：SDK 支持（Java/Go/Rust）

#### 现状核查
无任何 SDK 代码或目录结构。

#### 分析
SDK 本质上是对 RESTful API 的客户端包装，而当前 API 文档（Swagger）已完整。

**优先级**：每个 SDK 工作量 ≥ 2 周，且需独立仓库、版本管理、CI 发布；属于产品生态建设，与当前版本核心功能无关。

#### 问题等级
💭 **低优先级** — 建议 v2.0 后根据实际用户需求再决定

---

## 三、密码历史记录（新发现缺口）

### 现状核查

```
internal/repository/password_history.go — Repository 完整实现 ✅
internal/domain/  — PasswordHistory 模型存在（需确认）
```

**缺失：**
```go
// cmd/server/main.go — 无以下初始化：
passwordHistoryRepo := repository.NewPasswordHistoryRepository(db.DB)
// authService 中也无 "修改密码时检查历史记录" 的逻辑
```

PRD 1.4 要求："密码历史记录（防止重复使用）"

**等级**：🟡 建议级 — Repository 已有，service 层接线缺失

---

## 四、完善规划设计

### 4.1 优先级矩阵

| 缺口 | 优先级 | 工作量 | 依赖 | 建议迭代 |
|------|--------|--------|------|---------|
| GAP-01 角色继承接线 + 循环检测 | P1 🔴 | S（2天）| 无 | 当前迭代 |
| GAP-03 设备信任接线（登录检查）| P1 🔴 | M（4天）| 前端配合 | 当前迭代 |
| GAP-05/06 异常检测接线 | P2 🟡 | M（5天）| IP 地理库 | 下一迭代 |
| 密码历史记录（新发现）| P2 🟡 | S（1天）| 无 | 当前迭代 |
| GAP-02 验证码安全确认 | P1 🔴 | XS（0.5天）| 无 | 当前迭代 |
| GAP-04 CAS/SAML | P4 | L（2周+）| 无 | v2.0 |
| GAP-07 SDK | P5 | L（2周+/SDK）| API 稳定 | v2.0 |

---

### 4.2 GAP-01：角色继承 — 完整规划

#### 问题根因
角色继承的 Repository/Service 层已完整，但：
1. `authMiddleware` 权限校验未使用 `GetRolePermissions`（含继承）
2. `UpdateRole` 无环形继承检测
3. 无继承深度上限

#### 实现方案

**Step 1：修复 UpdateRole 循环检测（`internal/service/role.go`）**

```go
func (s *RoleService) UpdateRole(ctx context.Context, roleID int64, req *UpdateRoleRequest) (*domain.Role, error) {
    // ... 现有逻辑 ...
    if req.ParentID != nil {
        if *req.ParentID == roleID {
            return nil, errors.New("不能将角色设置为自己的父角色")
        }
        // 新增：检测循环引用
        if err := s.checkCircularInheritance(ctx, roleID, *req.ParentID); err != nil {
            return nil, err
        }
        // 新增：检测深度
        if err := s.checkInheritanceDepth(ctx, *req.ParentID, maxRoleDepth); err != nil {
            return nil, err
        }
    }
}

const maxRoleDepth = 5 // 可配置

func (s *RoleService) checkCircularInheritance(ctx context.Context, roleID, newParentID int64) error {
    // 向上遍历 newParentID 的祖先链，检查 roleID 是否出现
    ancestors, err := s.roleRepo.GetAncestorIDs(ctx, newParentID)
    if err != nil {
        return err
    }
    for _, id := range ancestors {
        if id == roleID {
            return errors.New("检测到循环继承，操作被拒绝")
        }
    }
    return nil
}
```

**Step 2：auth middleware 使用继承权限（`internal/api/middleware/auth.go`）**

```go
// 修改 getUserPermissions 方法
// 当前：直接查 role_permissions 表
// 目标：调用 roleService.GetRolePermissions(ctx, roleID)（含继承）
// 注意：需要把 roleService 注入到 authMiddleware，或在 rolePermissionRepo 层实现
```

**Step 3：JWT 生成时包含继承权限**

当用户登录后生成 JWT，在 `generateLoginResponse` 中调用 `GetRolePermissions` 替代直接查询：

```go
// internal/service/auth.go:generateLoginResponse
// 现状：permissions 只来自直接绑定的权限
// 目标：permissions = 直接权限 ∪ 所有祖先角色的权限
```

#### 测试用例设计
```
1. 创建角色 A（根）→ 角色 B（parent=A）→ 角色 C（parent=B）
2. 给角色 A 分配权限 P1，给角色 B 分配 P2
3. 用户分配角色 C → 应能访问 P1、P2、以及 C 自身权限
4. 尝试设置角色 A 的 parent 为 C → 应报错"循环继承"
5. 创建深度 > maxRoleDepth 的继承链 → 应报错
```

---

### 4.3 GAP-02：密码短信重置 — 安全确认

#### 需确认的问题

```go
// internal/api/handler/password_reset_handler.go:100-124
code, err := h.passwordResetService.ForgotPasswordByPhone(c.Request.Context(), req.Phone)
// 需要检查：code 是否被写入了 HTTP 响应体
```

**预期正确行为**：
- code 生成后，应通过 SMS 服务发送到用户手机（或 `h.smsService.Send(phone, code)`）
- HTTP 响应仅返回 `{"message": "verification code sent"}`，不返回 code 明文

**如果当前实现了直接返回 code**：这是 🔴 安全漏洞，必须修复。

#### 修复方案
```go
func (h *PasswordResetHandler) ForgotPasswordByPhone(c *gin.Context) {
    // ...
    code, err := h.passwordResetService.ForgotPasswordByPhone(c.Request.Context(), req.Phone)
    if err != nil {
        handleError(c, err)
        return
    }
    
    // 通过 SMS 服务发送验证码（不在响应中返回）
    if h.smsService != nil {
        if err := h.smsService.SendCode(req.Phone, code); err != nil {
            // fail-closed：SMS 发送失败应报错，不假装成功
            c.JSON(http.StatusServiceUnavailable, gin.H{"error": "验证码发送失败，请稍后重试"})
            return
        }
    }
    
    // 响应不包含 code
    c.JSON(http.StatusOK, gin.H{"message": "verification code sent"})
}
```

---

### 4.4 GAP-03：设备信任接线 — 完整规划

#### 实现方案

**Step 1：登录请求接收设备标识**

```go
// internal/service/auth.go
type LoginRequest struct {
    Account      string `json:"account"`
    Password     string `json:"password"`
    Remember     bool   `json:"remember"`
    DeviceID     string `json:"device_id,omitempty"`      // 新增
    DeviceName   string `json:"device_name,omitempty"`    // 新增
    DeviceBrowser string `json:"device_browser,omitempty"` // 新增
    DeviceOS     string `json:"device_os,omitempty"`      // 新增
}
```

**Step 2：登录时自动记录设备**

```go
// internal/service/auth.go:generateLoginResponse 中增加设备记录
func (s *AuthService) generateLoginResponse(ctx context.Context, user *domain.User, req *LoginRequest) (*LoginResponse, error) {
    // ... token 生成 ...
    
    // 自动注册/更新设备记录
    if s.deviceRepo != nil && req.DeviceID != "" {
        s.bestEffortRegisterDevice(ctx, user.ID, req)
    }
    
    // ... 返回 ...
}
```

**Step 3：TOTP 验证时检查设备信任**

```go
// internal/service/auth.go — 2FA 验证流程中
func (s *AuthService) VerifyTOTP(ctx context.Context, ..., deviceID string) error {
    // 检查设备是否已信任
    if deviceID != "" && s.deviceRepo != nil {
        device, err := s.deviceRepo.GetByDeviceID(ctx, userID, deviceID)
        if err == nil && device.IsTrusted {
            // 检查信任是否过期
            if device.TrustExpiresAt == nil || device.TrustExpiresAt.After(time.Now()) {
                return nil // 跳过 2FA
            }
        }
    }
    // 正常 TOTP 验证流程
}
```

**Step 4："记住此设备"信任接口**

已有 `POST /devices/:id/trust`，但需要前端在 2FA 验证通过时提供"记住此设备"选项并调用该接口。

**前端工作（ProfileSecurityPage 或登录流程）**：
- 登录时在设备指纹字段传入 `navigator.userAgent + screen.width + timezone` 的 hash
- 2FA 验证界面添加"记住此设备（30天）"复选框
- 勾选后调用 `POST /devices/:id/trust { trust_duration: "30d" }`

---

### 4.5 GAP-05/06：异常登录检测接线 — 完整规划

#### 方案A：纯内存检测（无 GeoIP，当前可立即实现）

只做 IP/设备维度的检测，不依赖地理位置：

```go
// cmd/server/main.go — 加入以下代码
anomalyDetector := security.NewAnomalyDetector(security.AnomalyDetectorConfig{
    WindowSize:          24 * time.Hour,
    MaxFailures:         10,
    MaxIPs:              5,
    MaxRecords:          100,
    AutoBlockDuration:   30 * time.Minute,
    KnownLocationsLimit: 3,
    KnownDevicesLimit:   5,
    IPFilter:            ipFilter, // 复用现有 ipFilter
})
authService.SetAnomalyDetector(anomalyDetector)
```

登录时传入真实设备指纹（从 User-Agent 等提取）：

```go
// internal/service/auth.go:Login()
deviceFingerprint := extractDeviceFingerprint(req.UserAgent, req.DeviceID)
s.recordLoginAnomaly(ctx, &user.ID, ip, "", deviceFingerprint, true)
// （location 暂为空，等 GeoIP 接入后再填）
```

#### 方案B：接入 GeoIP（可选，v1.1 引入）

```go
// 使用 MaxMind GeoLite2（免费）或 ip-api.com（HTTP 方式）
// 在登录时：
location := geoip.Lookup(ip) // → "广东省广州市" or "US/California"
s.recordLoginAnomaly(ctx, &user.ID, ip, location, deviceFingerprint, true)
```

**建议**：方案A 立即实现（工作量约 1 天），方案B 作为可选增强。

#### 异常事件通知
`AnomalyDetector` 检测到异常后，当前只记录日志（通过 `publishEvent`）。  
需补充：
- 邮件通知用户（利用现有 `auth_email.go` 的邮件发送能力）
- 写入 OperationLog 或专门的 SecurityAlert 表

---

### 4.6 密码历史记录（新发现缺口）— 规划

#### 工作量
极小，所有基础设施已就绪。

#### 实现步骤

**Step 1：`cmd/server/main.go` 初始化**
```go
passwordHistoryRepo := repository.NewPasswordHistoryRepository(db.DB)
authService.SetPasswordHistoryRepository(passwordHistoryRepo)
```

**Step 2：AuthService 接收依赖**
```go
type AuthService struct {
    // ...
    passwordHistoryRepo passwordHistoryRepositoryInterface // 新增
}
```

**Step 3：修改密码时检查历史**
```go
func (s *AuthService) ChangePassword(ctx context.Context, userID int64, newPassword string) error {
    // ... 验证新密码强度 ...
    
    // 检查密码历史（默认保留最近5个）
    if s.passwordHistoryRepo != nil {
        histories, _ := s.passwordHistoryRepo.GetByUserID(ctx, userID, 5)
        for _, h := range histories {
            if auth.VerifyPassword(h.PasswordHash, newPassword) {
                return errors.New("新密码不能与最近5次密码相同")
            }
        }
    }
    
    // 保存新密码哈希到历史
    go func() {
        _ = s.passwordHistoryRepo.Create(ctx, &domain.PasswordHistory{
            UserID:       userID,
            PasswordHash: newHashedPassword,
        })
        _ = s.passwordHistoryRepo.DeleteOldRecords(ctx, userID, 5)
    }()
}
```

---

## 五、实现时序建议

### Sprint 1（当前迭代，约 1 周）

| 任务 | 负责层 | 工作量 |
|------|--------|--------|
| GAP-02 验证码安全确认 + fix | 后端 handler | 0.5d |
| 密码历史记录接线 | 后端 service | 1d |
| GAP-01 循环继承检测 | 后端 service | 1d |
| GAP-05 方案A：AnomalyDetector 接入启动流程 | 后端 main.go | 1d |
| GAP-01 auth middleware 使用继承权限 | 后端 middleware | 1.5d |

### Sprint 2（下一迭代，约 2 周）

| 任务 | 负责层 | 工作量 |
|------|--------|--------|
| GAP-03 登录接收设备指纹 | 后端 service + 前端 | 2d |
| GAP-03 2FA 信任设备免验证 | 后端 service | 1d |
| GAP-03 前端设备管理页面 | 前端 | 3d |
| GAP-05/06 设备指纹采集 + 新设备通知 | 前端 + 后端 | 2d |

### v2.0 规划（暂不排期）

| 任务 | 说明 |
|------|------|
| GAP-04 CAS 协议 | 需引入 `gosaml2` 或 `cas` 库 |
| GAP-04 SAML 2.0 | 需引入 `saml` 相关库 |
| GAP-07 Go SDK | 基于已有 API 生成 SDK，独立仓库 |
| GAP-07 Java SDK | 独立仓库，Maven/Gradle |
| GAP-05 GeoIP 接入 | MaxMind GeoLite2 或 ip-api.com |

---

## 六、验收标准

每个 Gap 修复完成后，必须满足以下验收条件：

### GAP-01 角色继承
- [ ] 单元测试：用户持有子角色，能访问父角色绑定的权限
- [ ] 单元测试：设置循环继承返回 `errors.New("循环继承")`
- [ ] 手动验证：深度 > 5 的继承被拒绝
- [ ] `go test ./...` 全通过

### GAP-02 密码短信重置
- [ ] 代码确认响应体中无明文验证码
- [ ] 单元测试：错误验证码返回 401
- [ ] 单元测试：验证码过期后返回失败

### GAP-03 设备信任
- [ ] 登录接口能接收 `device_id`
- [ ] 登录后 `/devices` 列表出现新设备记录
- [ ] 信任设备后，2FA 验证被跳过
- [ ] 信任过期后，重新要求 2FA

### GAP-05/06 异常检测
- [ ] 启动日志出现 "anomaly detector initialized"
- [ ] 10次失败登录触发 `AnomalyBruteForce` 事件
- [ ] 事件写入 operation_log 或日志可查
- [ ] `go test ./...` 全通过

### 密码历史记录
- [ ] 修改密码时，使用历史密码被拒绝
- [ ] 历史记录不超过 5 条（旧的被清理）

---

## 七、文件变更清单（预计）

### 后端变更文件

| 文件 | 变更类型 | Gap |
|------|---------|-----|
| `cmd/server/main.go` | 修改：注入 anomalyDetector、passwordHistoryRepo | GAP-05、密码历史 |
| `internal/service/role.go` | 修改：增加循环检测和深度检测 | GAP-01 |
| `internal/service/auth.go` | 修改：generateLoginResponse 含继承权限；登录时传设备指纹 | GAP-01、GAP-03、GAP-05 |
| `internal/api/middleware/auth.go` | 修改：权限校验走继承路径 | GAP-01 |
| `internal/api/handler/password_reset_handler.go` | 修改：确认不返回明文 code | GAP-02 |

### 前端变更文件（Sprint 2）

| 文件 | 变更类型 | Gap |
|------|---------|-----|
| `src/pages/auth/LoginPage.tsx` | 修改：登录时采集设备指纹 | GAP-03、GAP-06 |
| `src/pages/profile/ProfileSecurityPage.tsx` | 修改：2FA 验证加"记住设备"选项 | GAP-03 |
| `src/pages/admin/DevicesPage.tsx` | 新增：设备管理页面 | GAP-03 |

---

*本文档由代码审查专家 Agent 生成，2026-04-01*  
*基于实际代码逐行核查，历史报告中的模糊描述已全部纠正*