---
name: 0008-datai-salesforce-auth-immediate-fixes
description: datai-salesforce-auth 模块立即修复事项架构决策
---

# 架构决策记录: datai-salesforce-auth 模块立即修复事项

## 背景

经过对 `datai-salesforce-auth` 模块的详细扫描和分析，发现了以下影响系统编译、安全性和稳定性的问题：

1. **语法错误**: DataiSfLoginHistoryController 和 DataiSfLoginSessionController 中存在多余的右括号，导致代码无法编译
2. **密码加密不安全**: 使用对称加密存储密码，可以解密还原明文，存在数据泄露风险
3. **敏感信息日志泄露**: 日志中记录了 Session ID、用户名等敏感信息，存在日志泄露风险
4. **缺少请求频率限制**: 登录接口没有请求频率限制，可能遭受暴力破解攻击

这些问题需要立即修复，以确保系统的正常运行和数据安全。

## 决策

针对上述问题，我们做出以下架构决策：

### 决策 1: 语法错误修复
**方案**: 直接修复语法错误，移除多余的右括号
**理由**: 语法错误导致代码无法编译，必须立即修复
**实施**: 
- 在 DataiSfLoginHistoryController.java:82 移除多余的右括号
- 在 DataiSfLoginSessionController.java:82 移除多余的右括号

### 决策 2: 密码加密方式调整
**方案**: 使用不可逆的哈希算法（BCrypt）替代对称加密
**理由**: 
- 对称加密可以解密还原明文，存在数据泄露风险
- BCrypt 是业界标准的密码哈希算法，具有抗彩虹表攻击能力
- BCrypt 自动处理盐值，提高安全性

**实施**:
- 修改数据库表结构，将 `password_encrypted` 字段改为 `password_hash`
- 修改 SalesforceLoginServiceImpl.java 中的密码存储逻辑
- 使用 BCrypt.hashpw() 方法对密码进行哈希
- 使用 BCrypt.checkpw() 方法验证密码

### 决策 3: 敏感信息日志脱敏
**方案**: 对敏感信息进行脱敏处理后再记录日志
**理由**: 
- 防止日志泄露导致敏感信息泄露
- 满足安全合规要求（如 GDPR、等保三级）
- 保留足够的调试信息（如 Session ID 前 8 位）

**实施**:
- 创建脱敏工具类 `SensitiveInfoMasker`
- 实现 `maskSensitiveInfo(String info)` 方法
- 在 SalesforceLoginServiceImpl.java 中所有日志记录处使用脱敏方法
- 脱敏规则：Session ID 只显示前 8 位，用户 ID 只显示前 4 位

### 决策 4: 请求频率限制
**方案**: 使用 Spring Security 或 Redis 实现请求频率限制
**理由**: 
- 防止暴力破解攻击
- 保护系统资源不被滥用
- 符合安全最佳实践

**实施**:
- 使用 Spring Security 的 `@RateLimiter` 注解
- 配置每分钟最多 5 次登录尝试
- 超过限制时返回明确的错误信息（HTTP 429）
- 使用 Redis 存储请求计数

## 备选方案

### 决策 1: 语法错误修复
**无备选方案**: 语法错误必须直接修复，无其他方案

### 决策 2: 密码加密方式调整

#### 方案 A: BCrypt（已选择）
**优点**:
- 业界标准，广泛使用
- 自动处理盐值
- 抗彩虹表攻击
- 内置成本因子，可调整计算复杂度

**缺点**:
- 计算较慢（但这是优点，防止暴力破解）
- 需要修改数据库表结构

#### 方案 B: PBKDF2
**优点**:
- NIST 推荐算法
- 可配置迭代次数
- 安全性高

**缺点**:
- 不如 BCrypt 常用
- 需要手动处理盐值

#### 方案 C: Argon2
**优点**:
- 密码哈希竞赛冠军
- 抗 GPU/ASIC 攻击
- 可配置内存和计算成本

**缺点**:
- 相对较新，兼容性可能有问题
- 需要额外的依赖

**选择理由**: BCrypt 是业界标准，成熟稳定，安全性足够，易于实施。

### 决策 3: 敏感信息日志脱敏

#### 方案 A: 自定义脱敏工具类（已选择）
**优点**:
- 灵活，可定制脱敏规则
- 不依赖外部库
- 易于维护

**缺点**:
- 需要自己实现

#### 方案 B: 使用 Logback Masking 插件
**优点**:
- 配置简单
- 自动脱敏

**缺点**:
- 灵活性差
- 需要额外配置

#### 方案 C: 使用第三方库（如 logback-mask）
**优点**:
- 开箱即用
- 功能丰富

**缺点**:
- 增加依赖
- 可能不满足定制需求

**选择理由**: 自定义脱敏工具类更灵活，易于维护，不增加外部依赖。

### 决策 4: 请求频率限制

#### 方案 A: Spring Security @RateLimiter（已选择）
**优点**:
- 与 Spring Security 集成良好
- 使用注解，易于使用
- 支持 Redis 分布式部署

**缺点**:
- 需要 Redis 依赖

#### 方案 B: 自定义拦截器
**优点**:
- 不依赖外部库
- 灵活可定制

**缺点**:
- 需要自己实现
- 不支持分布式部署

#### 方案 C: 使用 Guava RateLimiter
**优点**:
- 轻量级
- 性能好

**缺点**:
- 单机限流，不支持分布式
- 需要手动集成

**选择理由**: Spring Security @RateLimiter 与现有架构集成良好，支持分布式部署。

## 影响

### 系统架构影响
1. **密码加密方式变更**: 需要修改数据库表结构，影响现有登录历史数据
2. **日志脱敏**: 需要修改所有日志记录处，影响调试体验
3. **请求频率限制**: 需要添加 Redis 依赖，影响部署架构

### 开发流程影响
1. **语法错误修复**: 立即修复，不影响开发流程
2. **密码加密方式变更**: 需要数据迁移脚本，影响开发流程
3. **日志脱敏**: 需要修改所有日志记录处，影响开发流程
4. **请求频率限制**: 需要添加 Redis 配置，影响开发流程

### 运维管理影响
1. **密码加密方式变更**: 需要执行数据迁移脚本，影响运维
2. **日志脱敏**: 不影响运维，反而提高安全性
3. **请求频率限制**: 需要部署 Redis，影响运维

### 用户体验影响
1. **密码加密方式变更**: 不影响用户体验
2. **日志脱敏**: 不影响用户体验
3. **请求频率限制**: 可能影响用户体验（频繁登录时会被限制）

## 风险

### 技术风险
1. **密码加密方式变更风险**: 
   - **风险**: 现有登录历史数据无法使用
   - **概率**: 高
   - **缓解措施**: 提供数据迁移脚本，保留旧数据作为备份

2. **日志脱敏风险**: 
   - **风险**: 调试困难，无法看到完整信息
   - **概率**: 中
   - **缓解措施**: 提供调试模式开关，调试时可关闭脱敏

3. **请求频率限制风险**: 
   - **风险**: 误伤正常用户
   - **概率**: 低
   - **缓解措施**: 提供清晰的错误信息，用户知道被限制的原因

### 业务风险
1. **密码加密方式变更风险**: 
   - **风险**: 用户需要重新登录
   - **概率**: 高
   - **缓解措施**: 提前通知用户，说明变更原因

2. **请求频率限制风险**: 
   - **风险**: 自动登录可能被限制
   - **概率**: 低
   - **缓解措施**: 自动登录不受频率限制限制

### 实施风险
1. **数据库表结构变更风险**: 
   - **风险**: 表结构变更失败
   - **概率**: 低
   - **缓解措施**: 在测试环境充分测试，准备回滚脚本

## 回滚策略

### 决策 1: 语法错误修复
**回滚策略**: 使用 Git 回滚到修复前的版本

### 决策 2: 密码加密方式变更
**回滚策略**: 
1. 恢复数据库表结构（添加 `password_encrypted` 字段）
2. 恢复代码（使用对称加密）
3. 从备份恢复数据

### 决策 3: 敏感信息日志脱敏
**回滚策略**: 移除脱敏逻辑，恢复原始日志记录

### 决策 4: 请求频率限制
**回滚策略**: 移除 `@RateLimiter` 注解，移除 Redis 配置

## 验收标准

### 决策 1: 语法错误修复
- [ ] AC1: 项目能够正常编译，无编译错误
- [ ] AC2: 登录功能正常工作
- [ ] AC3: 自动登录功能正常工作

### 决策 2: 密码加密方式变更
- [ ] AC1: 数据库表结构已更新（`password_hash` 字段已添加）
- [ ] AC2: 密码使用 BCrypt 哈希存储
- [ ] AC3: 密码验证使用 BCrypt.checkpw() 方法
- [ ] AC4: 现有登录历史数据已迁移
- [ ] AC5: 登录功能正常工作

### 决策 3: 敏感信息日志脱敏
- [ ] AC1: 日志中 Session ID 只显示前 8 位
- [ ] AC2: 日志中用户 ID 只显示前 4 位
- [ ] AC3: 所有日志记录处都使用了脱敏方法
- [ ] AC4: 调试模式开关正常工作

### 决策 4: 请求频率限制
- [ ] AC1: 每分钟最多 5 次登录尝试
- [ ] AC2: 超过限制时返回 HTTP 429 错误
- [ ] AC3: 错误信息清晰明确
- [ ] AC4: 自动登录不受频率限制限制
- [ ] AC5: Redis 存储请求计数正常工作

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 认证模块架构图
- **具体节点**: [DataiSalesforceAuth](../../Authentication.canvas) - datai-salesforce-auth 模块

### Status

- [x] Draft
- [ ] Accepted
- [ ] Superceded

## 参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源。

- [需求文档](../requirements/REQ-008.md) - datai-salesforce-auth 模块立即修复事项
- [BCrypt 官方文档](https://bcrypt-generator.com/) - BCrypt 算法说明
- [Spring Security 文档](https://docs.spring.io/spring-security/reference/) - Spring Security Rate Limiting
- [OWASP 密码存储备忘单](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) - 密码存储最佳实践
- [等保三级要求](https://www.tc260.org.cn/) - 中国网络安全等级保护三级要求