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. Users must be able to navigate through the folder structure (e.g., backups/SS2/Sales Dashboard) to locate specific files.

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, navigating into a subdirectory, uploading a test file, verifying it appears in the list, downloading it, and then deleting it.

Acceptance Scenarios:

Given the File Storage page is open, When I view the list, Then I see the top-level folders (e.g., backups, repositories) or files.
Given I am viewing a folder, When I click a subfolder name, Then the view updates to show the contents of that subfolder.
Given I am in a subfolder, When I click "Download" on a file, Then the file is downloaded to my local machine.
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.
Given I have a file locally, When I drag and drop it or use the "Upload" button, Then the file is uploaded to the current directory 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:

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.
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).
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 and folders, 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 (including subdirectories) 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 specific folder in the storage directory via the Web UI.
FR-013: System MUST support navigating through the directory hierarchy within the allowed categories.
FR-014: System MUST display breadcrumbs or similar navigation aid to show current path.
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.

6.9 KiB Raw Blame History Unescape Escape