# Requirements Document

## Introduction

AWS资源扫描报告工具是一个全栈Web应用，用于扫描AWS账号中的资源信息，并按照Word模板生成专业的项目报告文档。系统支持多账号、多区域并行扫描，具有完整的用户权限管理、任务调度和报告管理功能。系统设计为可扩展架构，预留接入其他云厂商的能力。

## Glossary

- **Scanner**: 资源扫描器，负责通过boto3扫描AWS资源
- **Worker**: 工作进程，执行用户提交的扫描任务
- **Report**: 生成的Word格式项目报告文档
- **AWS_Credential**: AWS凭证，包括IAM Role或Access Key
- **Assume_Role**: AWS跨账号访问机制，通过STS获取临时凭证
- **Global_Resource**: 全局资源，如CloudFront、IAM等不区分区域的服务
- **Task**: 用户提交的扫描任务，包含账号、区域、项目信息等
- **JWT**: JSON Web Token，用于用户认证和会话管理
- **Admin**: 管理员角色，拥有系统全部权限
- **Power_User**: 高级用户角色，可使用所有凭证生成报告
- **User**: 普通用户角色，仅可使用分配的凭证和查看自己的报告

## Requirements

### Requirement 1: 用户认证与授权

**User Story:** 作为系统管理员，我希望系统具有完善的用户认证和权限管理，以确保系统安全和数据隔离。

#### Acceptance Criteria

1. WHEN a user attempts to login THEN THE System SHALL validate credentials and return a JWT token upon success
2. WHEN a JWT token expires THEN THE System SHALL reject the request and require re-authentication
3. WHEN an Admin user accesses the system THEN THE System SHALL allow management of all AWS credentials, reports, and system users
4. WHEN a Power_User accesses the system THEN THE System SHALL allow selection of all AWS credentials and viewing of all reports
5. WHEN a User accesses the system THEN THE System SHALL only allow viewing reports created by that user and using assigned AWS credentials
6. IF an unauthorized user attempts to access restricted resources THEN THE System SHALL return a 403 Forbidden response
7. WHEN an Admin creates a new user THEN THE System SHALL require username, password, email, and role assignment
8. WHEN an Admin assigns AWS credentials to a User THEN THE System SHALL record the assignment and enforce it during task creation

### Requirement 2: AWS凭证管理

**User Story:** 作为管理员，我希望能够管理AWS凭证（IAM Role Arn和Access Key），IAM Role用于Assume Role，以便用户可以安全地扫描不同的AWS账号。

#### Acceptance Criteria

1. WHEN an Admin adds an AWS credential THEN THE System SHALL store the credential type (Role or Access Key), account ID, and related configuration
2. WHEN using Assume_Role authentication THEN THE System SHALL use a centralized base account configured by Admin to assume roles in target accounts
3. WHEN using Access_Key authentication THEN THE System SHALL securely store and use the Access Key ID and Secret Access Key
4. WHEN an Admin configures the base Assume_Role account THEN THE System SHALL validate the credentials before saving
5. WHEN an Admin assigns credentials to a User THEN THE System SHALL create an association record between the user and credential
6. IF AWS credential validation fails THEN THE System SHALL display a clear error message and not save invalid credentials
7. WHEN listing credentials THEN THE System SHALL mask sensitive information like Secret Access Keys

### Requirement 3: 扫描任务管理

**User Story:** 作为用户，我希望能够创建和管理AWS资源扫描任务，以便生成项目报告。

#### Acceptance Criteria

1. WHEN a user creates a scan task THEN THE System SHALL require selection of AWS accounts, regions, and project metadata
2. WHEN a user selects regions THEN THE System SHALL allow multiple region selection and always include Global_Resource scanning
3. WHEN a user selects multiple AWS accounts THEN THE System SHALL add an AWS Account column to all resource tables in the report
4. WHEN a task is submitted THEN THE System SHALL queue it for Worker processing and return a task ID
5. WHILE a task is in progress THEN THE System SHALL provide real-time status updates via automatic refresh
6. WHEN a task completes THEN THE System SHALL generate a Word report using the configured template
7. IF a task fails THEN THE System SHALL log the error details and display them to the user
8. WHEN a user provides project metadata THEN THE System SHALL include Client Name, Project Name, BD Manager, Solutions Architect, Cloud Engineer, and Network Diagram in the report

### Requirement 4: Worker任务执行

**User Story:** 作为系统，我需要通过Celery Worker执行扫描任务，以实现任务隔离和并行处理。

#### Acceptance Criteria

1. WHEN the main program receives a task THEN THE System SHALL dispatch it to Celery queue for Worker processing
2. WHEN a Worker receives a task THEN THE Worker SHALL execute the scan for all specified accounts and regions
3. WHILE scanning multiple accounts or regions THEN THE Worker SHALL process them in parallel to improve performance
4. WHEN scanning a single account THEN THE Worker SHALL scan all supported AWS services concurrently
5. IF a service scan encounters an error THEN THE Worker SHALL log the error and continue with other services
6. WHEN a service has no resources THEN THE Worker SHALL exclude it from the final report
7. WHEN scanning completes THEN THE Worker SHALL generate the Word report and update task status in database
8. WHEN an Admin views workers THEN THE System SHALL display Celery worker status from Redis
9. WHILE a task is running THEN THE Worker SHALL report progress updates to Redis for real-time status display
10. IF a task fails THEN THE Worker SHALL retry up to 3 times with exponential backoff

### Requirement 5: AWS资源扫描

**User Story:** 作为用户，我希望工具能够全面扫描AWS资源，以便生成完整的资源清单报告。

#### Acceptance Criteria

1. WHEN scanning AWS resources THEN THE Scanner SHALL use boto3 to query the following services:
   - VPC: VPCs, Subnets, Route Tables, Internet Gateways, NAT Gateways, Security Groups, VPC Endpoints, VPC Peering Connections
   - VPN: Customer Gateways, Virtual Private Gateways, VPN Connections
   - EC2: Instances (with EBS volumes, AMI info), Elastic IPs
   - Auto Scaling Group: Auto Scaling Groups (with Launch Templates)
   - ELB: Application Load Balancers, Network Load Balancers, Classic Load Balancers, Target Groups
   - RDS: DB Instances
   - ElastiCache: Cache Clusters
   - EKS: Clusters
   - Lambda: Functions
   - S3: Buckets, S3 Event Notifications
   - CloudFront: Distributions (Global)
   - Route 53: Hosted Zones (Global)
   - ACM: Certificates (Global)
   - WAF: Web ACLs (Global)
   - SNS: Topics, Subscriptions
   - CloudWatch: Log Groups
   - EventBridge: Rules
   - CloudTrail: Trails
   - Config: Configuration Recorders
2. WHEN scanning Global_Resource services (CloudFront, Route 53, ACM, WAF) THEN THE Scanner SHALL scan them regardless of selected regions
3. WHEN scanning regional services THEN THE Scanner SHALL only scan the user-selected regions
4. WHEN a resource is found THEN THE Scanner SHALL extract relevant attributes for the report based on service-specific column definitions
5. IF an API call fails THEN THE Scanner SHALL retry with exponential backoff up to 3 times
6. IF all retries fail THEN THE Scanner SHALL log the error and skip that resource type
7. WHEN scanning multiple accounts THEN THE Scanner SHALL include the AWS Account ID in each resource record

### Requirement 6: 报告生成

**User Story:** 作为用户，我希望生成的报告符合专业模板格式，以便直接用于客户交付。

#### Acceptance Criteria

1. WHEN generating a report THEN THE System SHALL use the Word template from sample-reports folder
2. WHEN filling template placeholders THEN THE System SHALL replace all [placeholder] markers with actual values including [Project Name], [Client Name], [Cloud Engineer Name], [Cloud Engineer Email], [BD Manager], [Solutions Architect], and date fields
3. WHEN generating Implementation List THEN THE System SHALL create tables for each service with resources organized by service category
4. WHEN a service has no resources THEN THE System SHALL exclude that service section from the report
5. WHEN report generation completes THEN THE System SHALL update the document table of contents automatically
6. WHEN a report is ready THEN THE System SHALL store it and make it available for download
7. WHEN displaying reports THEN THE System SHALL show report metadata including creation time, status, and file size
8. WHEN user provides a Network Diagram image THEN THE System SHALL embed it in the appropriate section of the report
9. WHEN generating Update History THEN THE System SHALL include version, date, modifier, and details

### Requirement 7: 前端用户界面

**User Story:** 作为用户，我希望有一个简洁美观的前端界面，以便轻松操作系统功能。

#### Acceptance Criteria

1. WHEN a user accesses the frontend THEN THE System SHALL display a clean and modern React-based interface
2. WHEN viewing the dashboard THEN THE System SHALL show task status summary and recent reports
3. WHEN creating a task THEN THE System SHALL provide intuitive forms for account, region, and metadata selection
4. WHILE a task is running THEN THE System SHALL auto-refresh the status display
5. WHEN viewing reports THEN THE System SHALL allow preview, download, and deletion operations
6. WHEN an Admin accesses admin pages THEN THE System SHALL display user management, credential management, and worker management interfaces
7. IF an error occurs THEN THE System SHALL display user-friendly error messages with details available

### Requirement 8: 错误处理与日志

**User Story:** 作为管理员，我希望系统具有完善的错误处理和日志机制，以便排查问题。

#### Acceptance Criteria

1. WHEN any operation fails THEN THE System SHALL log the error with timestamp, context, and stack trace
2. WHEN a scan task encounters errors THEN THE System SHALL record error details in the task record
3. WHEN viewing task details THEN THE System SHALL display any error logs associated with that task
4. WHEN an Admin views system logs THEN THE System SHALL provide filtering and search capabilities
5. IF a critical error occurs THEN THE System SHALL not crash but gracefully handle and report the error

### Requirement 9: 数据持久化

**User Story:** 作为系统，我需要可靠的数据存储，以便在不同环境下正常运行。

#### Acceptance Criteria

1. WHEN running in production THEN THE System SHALL use PostgreSQL as the database
2. WHEN running in test/development THEN THE System SHALL use SQLite3 as the database
3. WHEN storing sensitive data (passwords, AWS secrets) THEN THE System SHALL encrypt them before storage
4. WHEN the database schema changes THEN THE System SHALL support migrations without data loss

### Requirement 10: 系统扩展性

**User Story:** 作为架构师，我希望系统设计具有扩展性，以便未来接入其他云厂商。

#### Acceptance Criteria

1. WHEN designing the scanner module THEN THE System SHALL use an abstract interface that can be implemented for different cloud providers
2. WHEN adding a new cloud provider THEN THE System SHALL only require implementing the provider-specific scanner without modifying core logic
3. WHEN storing credentials THEN THE System SHALL support different credential types for different cloud providers
4. WHEN generating reports THEN THE System SHALL use a provider-agnostic data format internally