# 需求文档

## 简介

本功能允许用户在没有 AWS Access Key 的情况下，通过 AWS CloudShell 环境运行独立的 Python 扫描脚本来收集 AWS 资源数据。用户将扫描结果（JSON 文件）上传到前端界面，由后端 Worker 处理并生成报告。这种方式适用于安全策略严格、不允许创建长期访问密钥的 AWS 账户。

## 术语表

- **CloudShell_Scanner**: 在 AWS CloudShell 环境中运行的独立 Python 扫描脚本
- **Scan_Data**: CloudShell_Scanner 生成的 JSON 格式扫描结果数据
- **Upload_Handler**: 后端处理上传 JSON 数据的服务组件
- **Report_Generator**: 现有的报告生成服务，用于将扫描数据转换为 Word 文档
- **Worker**: 后端 Celery 异步任务处理器

## 需求

### 需求 1：CloudShell 扫描脚本

**用户故事：** 作为 AWS 管理员，我希望在 CloudShell 中运行一个独立的 Python 脚本来扫描 AWS 资源，以便在不创建 Access Key 的情况下收集资源数据。

#### 验收标准

1. THE CloudShell_Scanner SHALL 是一个单体 Python 文件，仅依赖 boto3 和 Python 标准库
2. WHEN CloudShell_Scanner 启动时，THE CloudShell_Scanner SHALL 自动使用 CloudShell 环境的 IAM 凭证
3. WHEN 用户指定扫描区域时，THE CloudShell_Scanner SHALL 仅扫描指定的区域
4. WHEN 用户未指定区域时，THE CloudShell_Scanner SHALL 扫描所有可用区域
5. THE CloudShell_Scanner SHALL 扫描与现有 AWSScanner 相同的所有服务类型
6. WHEN 扫描完成时，THE CloudShell_Scanner SHALL 将结果导出为 JSON 文件
7. THE CloudShell_Scanner SHALL 在扫描过程中显示进度信息
8. IF 扫描某个服务或区域失败，THEN THE CloudShell_Scanner SHALL 记录错误并继续扫描其他资源

### 需求 2：JSON 数据格式

**用户故事：** 作为开发者，我希望扫描数据使用标准化的 JSON 格式，以便后端能够正确解析和处理。

#### 验收标准

1. THE Scan_Data SHALL 包含元数据字段：account_id、scan_timestamp、regions_scanned、services_scanned
2. THE Scan_Data SHALL 包含 resources 字段，按服务类型组织资源数据
3. THE Scan_Data SHALL 包含 errors 字段，记录扫描过程中的错误信息
4. WHEN 序列化 Scan_Data 时，THE CloudShell_Scanner SHALL 使用 JSON 格式编码
5. WHEN 解析 Scan_Data 时，THE Upload_Handler SHALL 能够还原完整的资源数据结构（往返一致性）

### 需求 3：前端上传界面

**用户故事：** 作为用户，我希望通过前端界面上传 JSON 扫描数据，以便系统能够处理并生成报告。

#### 验收标准

1. WHEN 用户访问任务创建页面时，THE System SHALL 显示两种数据来源选项：使用凭证扫描或上传 JSON 文件
2. WHEN 用户选择上传 JSON 文件时，THE System SHALL 显示文件上传组件和项目元数据表单
3. WHEN 用户上传文件时，THE System SHALL 验证文件格式为有效的 JSON
4. WHEN 用户上传文件时，THE System SHALL 验证 JSON 结构符合 Scan_Data 格式
5. IF 文件格式无效，THEN THE System SHALL 显示明确的错误提示
6. WHEN 用户提交上传表单时，THE System SHALL 将 JSON 数据和项目元数据发送到后端

### 需求 4：后端上传处理

**用户故事：** 作为系统，我需要处理上传的 JSON 数据并创建报告生成任务。

#### 验收标准

1. THE Upload_Handler SHALL 提供 API 端点接收上传的 JSON 数据
2. WHEN 接收到上传数据时，THE Upload_Handler SHALL 验证 JSON 结构的完整性
3. WHEN 验证通过时，THE Upload_Handler SHALL 创建一个新的任务记录
4. WHEN 任务创建成功时，THE Upload_Handler SHALL 触发 Worker 处理数据并生成报告
5. IF JSON 数据验证失败，THEN THE Upload_Handler SHALL 返回详细的错误信息
6. THE Upload_Handler SHALL 支持大文件上传（最大 50MB）

### 需求 5：报告生成集成

**用户故事：** 作为用户，我希望从上传的 JSON 数据生成与现有扫描任务相同格式的报告。

#### 验收标准

1. WHEN Worker 处理上传的 Scan_Data 时，THE Report_Generator SHALL 生成与现有扫描任务相同格式的 Word 报告
2. THE Report_Generator SHALL 使用上传数据中的 account_id 作为报告的账户标识
3. WHEN 报告生成完成时，THE System SHALL 更新任务状态为已完成
4. WHEN 报告生成完成时，THE System SHALL 允许用户下载生成的报告
5. IF 报告生成失败，THEN THE System SHALL 记录错误并更新任务状态为失败

### 需求 6：错误处理和日志

**用户故事：** 作为用户，我希望在出现问题时能够看到清晰的错误信息，以便排查问题。

#### 验收标准

1. WHEN CloudShell_Scanner 遇到权限错误时，THE CloudShell_Scanner SHALL 显示缺少的权限信息
2. WHEN 上传的 JSON 缺少必要字段时，THE System SHALL 返回缺失字段的列表
3. WHEN 任务处理失败时，THE System SHALL 在任务详情中显示错误日志
4. THE System SHALL 记录所有上传和处理操作的审计日志