# Feature Specification: File Storage Management & UI

**Feature Branch**: `014-file-storage-ui`
**Created**: 2026-01-24
**Status**: Draft
**Input**: User description: "Я хочу проработать механизм хранения файлов и доступа к ним - бекапов дашбордов и репозиториев дашбордов. Во первых, нужно иметь указывать место хранения, по умолчанию оно должно быть за файловой системой сервера (чтобы не влиять на git репозиторий. Во вторых, нужен web ui для базового доступа ко всем файлам - возможность скачивания/удаления, информация о датах создания, возможность загрузки"

## User Scenarios & Testing *(mandatory)*

### User Story 1 - File Management Dashboard (Priority: P1)

Users need a visual interface to manage the artifacts generated by the system (dashboard backups, exported repositories) without needing direct server access. This ensures that non-technical users or users without SSH access can still retrieve or clean up data.

**Why this priority**: Core functionality requested. Without the UI, the storage mechanism is opaque and hard to use.

**Independent Test**: Can be fully tested by opening the new "File Storage" page, uploading a test file, verifying it appears in the list with correct metadata, downloading it, and then deleting it.

**Acceptance Scenarios**:

1. **Given** the File Storage page is open, **When** I view the list, **Then** I see all files in the configured storage directory with their names, sizes, and creation dates.
2. **Given** a file exists in the list, **When** I click "Download", **Then** the file is downloaded to my local machine.
3. **Given** a file exists in the list, **When** I click "Delete" and confirm, **Then** the file is removed from the list and the server filesystem.
4. **Given** I have a file locally, **When** I drag and drop it or use the "Upload" button, **Then** the file is uploaded to the server storage and appears in the list.

---

### User Story 2 - Storage Location Configuration (Priority: P2)

Administrators need to control where potentially large or sensitive files are stored. Crucially, these files must not accidentally pollute the source code repository or the application's working directory.

**Why this priority**: Essential for system stability and cleanliness (preventing git pollution), but the system could theoretically start with a hardcoded safe default.

**Independent Test**: Change the storage path in Settings, generate a file (or upload one), and verify it exists in the new location on the server disk.

**Acceptance Scenarios**:

1. **Given** I am in the Settings page, **When** I enter a new absolute path for "File Storage Path" and save, **Then** the system updates the configuration.
2. **Given** the default configuration, **When** the system starts, **Then** the storage path defaults to a location outside the project's git scope (or is properly ignored).
3. **Given** an invalid path (e.g., no write permissions), **When** I try to save, **Then** the system shows an error message.

---

### Edge Cases

- **File Name Conflicts**: What happens when uploading a file that already exists? (System should likely rename or ask to overwrite).
- **Storage Quota/Disk Space**: What happens if the disk is full during upload?
- **Path Traversal**: Ensure users cannot access files outside the configured storage directory via the API.
- **Large Files**: Handling uploads/downloads of large backup archives (e.g., > 100MB).

## Clarifications

### Session 2026-01-24

- Q: Should the system enforce a structure to keep backups and repositories separate? → A: **Structured**: System creates and enforces `backups/` and `repositories/` folders; UI separates them.

### Session 2026-01-24 (Update)

- Q: Should the system allow advanced configuration of file structure and naming conventions? → A: **Yes**: Users should be able to configure the directory structure (e.g., include dashboard/environment names) and file naming patterns (e.g., include timestamps).

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST allow configuring a local filesystem root path for storing artifacts.
- **FR-002**: The default storage path MUST be configured such that it does not interfere with the application's git repository (e.g., a directory outside the workspace or explicitly git-ignored).
- **FR-003**: System MUST enforce a directory structure within the storage root: `backups/` for dashboard backups and `repositories/` for exported repositories.
- **FR-004**: System MUST provide a Web UI to list files, organized by their type (Backup vs Repository).
- **FR-005**: System MUST display file metadata in the UI: Filename, Size, Creation Date.
- **FR-006**: System MUST allow users to download files from the storage directory via the Web UI.
- **FR-007**: System MUST allow users to delete files from the storage directory via the Web UI.
- **FR-008**: System MUST allow users to upload files to the storage directory via the Web UI, requiring them to select the target category (Backup or Repository).
- **FR-009**: System MUST validate that the configured storage path is accessible and writable.
- **FR-010**: System MUST prevent access to files outside the configured storage directory (Path Traversal protection).
- **FR-011**: System MUST allow configuring the directory structure pattern for backups and repositories (e.g., `{environment}/{dashboard_name}/`).
- **FR-012**: System MUST allow configuring the filename pattern for generated files (e.g., `{dashboard_name}_{timestamp}.zip`).

### Key Entities

- **StorageConfig**: Settings defining the root directory path.
- **StoredFile**: Conceptual representation of a file (Name, Path, Size, CreatedAt, MimeType).

### Assumptions

- The application server has access to a writable local filesystem.
- Users utilizing this feature have appropriate permissions within the application to manage system-wide storage settings and files.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can successfully upload and then download a file of at least 50MB size.
- **SC-002**: Files created or uploaded via the system do not appear in the application's `git status` output by default.
- **SC-003**: File list loads in under 1 second for a directory containing 100 files.
- **SC-004**: Users can delete a file via UI and confirm it is physically removed from the disk.