semantic update

frontend/src/services/storageService.js

@@ -3,6 +3,7 @@
  * @purpose Frontend API client for file storage management.
  * @layer   Service
  * @relation DEPENDS_ON -> backend.api.storage
+ * @SEMANTICS: storage, api, client
  */
 
 const API_BASE = '/api/storage';
@@ -13,6 +14,8 @@ const API_BASE = '/api/storage';
  * @param   {string} [category] - Optional category filter.
  * @param   {string} [path] - Optional subpath filter.
  * @returns {Promise<Array>}
+ * @PRE     category and path should be valid strings if provided.
+ * @POST    Returns a promise resolving to an array of StoredFile objects.
  */
 export async function listFiles(category, path) {
     const params = new URLSearchParams();
@@ -37,6 +40,8 @@ export async function listFiles(category, path) {
  * @param   {string} category - Target category.
  * @param   {string} [path] - Target subpath.
  * @returns {Promise<Object>}
+ * @PRE     file must be a valid File object; category must be specified.
+ * @POST    Returns a promise resolving to the metadata of the uploaded file.
  */
 export async function uploadFile(file, category, path) {
     const formData = new FormData();
@@ -65,6 +70,8 @@ export async function uploadFile(file, category, path) {
  * @param   {string} category - File category.
  * @param   {string} path - Relative path of the item.
  * @returns {Promise<void>}
+ * @PRE     category and path must identify an existing file or directory.
+ * @POST    The specified file or directory is removed from storage.
  */
 export async function deleteFile(category, path) {
     const response = await fetch(`${API_BASE}/files/${category}/${path}`, {
@@ -84,6 +91,8 @@ export async function deleteFile(category, path) {
  * @param   {string} category - File category.
  * @param   {string} path - Relative path of the file.
  * @returns {string}
+ * @PRE     category and path must identify an existing file.
+ * @POST    Returns a valid API URL for file download.
  */
 export function downloadFileUrl(category, path) {
     return `${API_BASE}/download/${category}/${path}`;