# 需求分析

> 时间戳：2026-04-20-10-14-09

---

## 1. 原始需求描述

用户提出三个核心安全问题，要求对纯前端架构下的敏感数据保护机制进行加固：

1. **storage.ts 中 XOR 加密硬编码静态密钥** → 已知明文攻击风险
2. **API_KEY_CODES 字符码数组混淆** → API 密钥客户端暴露与盗刷风险
3. **ADMIN_DISABLE_AUTH_KEY 明文硬编码** → 垂直越权漏洞

用户给出的妥协方案方向（鉴于纯前端限制）：
- 问题1：改用 Web Crypto API (AES-GCM) + 环境变量注入密钥
- 问题2：剥离前端密钥还原逻辑，至少移入构建阶段环境变量
- 问题3：用 SHA-256 哈希替代明文常量比对

---

## 2. 需求拆解

| 序号 | 子需求 | 涉及文件 | 优先级 |
|------|--------|----------|--------|
| 1 | 弃用 XOR 加密，改用 Web Crypto API AES-GCM | `src/utils/storage.ts` | P0 |
| 2 | 密钥从硬编码改为构建时环境变量注入 | `vite.config.ts`, `.env.example` | P0 |
| 3 | 兼容旧 XOR 加密数据的自动迁移读取 | `src/utils/storage.ts` | P0 |
| 4 | 删除 API_KEY_CODES 硬编码字符码数组 | `src/utils/storage.ts` | P0 |
| 5 | 默认 API Key 改为从环境变量读取 | `src/utils/storage.ts`, `vite.config.ts` | P0 |
| 6 | ADMIN_DISABLE_AUTH_KEY 改为 SHA-256 哈希比对 | `src/pages/UserManage.tsx` | P0 |
| 7 | 将源码中明文授权码替换为环境变量哈希值 | `.env.example`, `vite.config.ts` | P0 |
| 8 | 修复 UserManage.tsx 中原生 alert/confirm 使用 | `src/pages/UserManage.tsx` | P1 |

---

## 3. 影响范围评估

### 3.1 需要修改的文件
- `src/utils/storage.ts` — 加密机制重构、API Key 来源变更
- `src/pages/UserManage.tsx` — 授权码哈希比对、alert/confirm 替换
- `vite.config.ts` — 新增环境变量注入
- `.env.example` — 新增必需环境变量模板

### 3.2 潜在风险点
- **数据迁移兼容性**：旧版本用户 localStorage 中的 systemSettings 仍用 XOR 加密，必须支持双轨读取（先尝试 AES-GCM 解密，失败再回退 XOR）
- **Web Crypto API 异步性**：storage.get 当前为同步接口，AES-GCM 解密为异步操作，需调整接口或设计异步包装
- **环境变量缺失导致构建失败**：若用户未配置新环境变量，构建产物中密钥将为空字符串
- **SHA-256 哈希盐值**：若仅做简单 SHA-256，彩虹表仍可攻击，需引入盐值

### 3.3 是否涉及数据迁移
- [x] 是。旧 `systemSettings` 的 XOR 加密数据需兼容读取，新写入全面使用 AES-GCM。

---

## 4. 验收标准

- [ ] `npm run lint` 无类型错误
- [ ] `npm run build` 构建成功
- [ ] storage.ts 中不再出现任何硬编码密钥字符串
- [ ] UserManage.tsx 中不再出现明文授权常量
- [ ] 旧版本 XOR 加密的 systemSettings 仍能被正确读取（向后兼容）
- [ ] 新写入的 systemSettings 使用 AES-GCM 加密
- [ ] 默认 API Key 从环境变量注入，源码中无字符码数组
- [ ] 禁用管理员的授权校验使用 SHA-256 + 盐值比对
- [ ] UserManage.tsx 中原生 alert/confirm 全部替换为自定义 UI 或至少移除硬编码明文提示

---

## 5. 关联历史需求

无直接关联历史需求。但需遵守 AGENTS.md 第 5.6 节数据迁移规范、第 5.7 节禁用原生 alert/confirm 规范。