api-refactoring-final.md

@@ -22,6 +22,57 @@ Project is in active development with no existing clients. All changes can be ma
 - Service methods
 - API documentation
 
+### 1.2 Reference Images Auto-Detection
+
+**Parameter behavior:**
+- `referenceImages` parameter is **optional**
+- If provided (array of aliases or IDs) → use these images as references
+- If empty or not provided → service must automatically parse prompt and find all aliases
+
+**Auto-detection logic:**
+
+1. **Prompt parsing:**
+   - Scan prompt text for all alias patterns (@name)
+   - Extract all found aliases
+   - Resolve each alias to actual image ID
+
+2. **Manual override:**
+   - If `referenceImages` parameter is provided and not empty → use only specified images
+   - Manual list takes precedence over auto-detected aliases
+
+3. **Combined approach:**
+   - If `referenceImages` provided → add to auto-detected aliases (merge)
+   - Remove duplicates
+   - Maintain order: manual references first, then auto-detected
+
+**Example:**
+```json
+// Auto-detection (no referenceImages parameter)
+{
+  "prompt": "A landscape based on @sunset with elements from @mountain"
+  // System automatically detects @sunset and @mountain
+}
+
+// Manual specification
+{
+  "prompt": "A landscape",
+  "referenceImages": ["@sunset", "image-uuid-123"]
+  // System uses only specified images
+}
+
+// Combined
+{
+  "prompt": "A landscape based on @sunset",
+  "referenceImages": ["@mountain"]
+  // System uses both @mountain (manual) and @sunset (auto-detected)
+}
+```
+
+**Implementation notes:**
+- Alias detection must use the same validation rules as alias creation
+- Invalid aliases in prompt should be logged but not cause generation failure
+- Maximum reference images limit still applies after combining manual + auto-detected
+
 ---
 
 ## 2. Enhanced Prompt Support - Logic Redesign
@@ -780,6 +831,58 @@ Response: { "flowId": "my-flow-uuid", ... }
 
 ---
 
+## 12. Code Documentation Standards
+
+### 12.1 Endpoint JSDoc Comments
+
+**Requirement:** Every API endpoint must have comprehensive JSDoc comment.
+
+**Required sections:**
+
+1. **Purpose:** What this endpoint does (one sentence)
+2. **Logic:** Brief description of how it works (2-3 key steps)
+3. **Parameters:** Description of each parameter and what it affects
+4. **Authentication:** Required authentication level
+5. **Response:** What is returned
+
+**Example format:**
+```typescript
+/**
+ * Generate new image from text prompt with optional reference images.
+ *
+ * Logic:
+ * 1. Parse prompt to auto-detect reference image aliases
+ * 2. Resolve all aliases (auto-detected + manual) to image IDs
+ * 3. Trigger AI generation with prompt and reference images
+ * 4. Store result with metadata and return generation record
+ *
+ * @param {string} prompt - Text description for image generation (affects: output style and content)
+ * @param {string[]} referenceImages - Optional aliases/IDs for reference images (affects: visual style transfer)
+ * @param {string} aspectRatio - Image dimensions ratio (affects: output dimensions, default: 1:1)
+ * @param {string} flowId - Optional flow association (affects: organization and flow-scoped aliases)
+ * @param {string} alias - Optional project-scoped alias (affects: image referencing across project)
+ * @param {string} flowAlias - Optional flow-scoped alias (affects: image referencing within flow)
+ * @param {boolean} autoEnhance - Enable AI prompt enhancement (affects: prompt quality and detail)
+ * @param {object} meta - Custom metadata (affects: searchability and organization)
+ *
+ * @authentication Project Key required
+ * @returns {GenerationResponse} Generation record with status and output image details
+ */
+router.post('/generations', ...);
+```
+
+**Apply to:**
+- All route handlers in `/routes/**/*.ts`
+- All public service methods that implement core business logic
+- Complex utility functions with non-obvious behavior
+
+**Parameter descriptions must include "affects:"**
+- Explain what each parameter influences in the system
+- Help developers understand parameter impact
+- Make API more discoverable and self-documenting
+
+---
+
 ## Summary of Changes
 
 ### Database Changes
@@ -790,15 +893,16 @@ Response: { "flowId": "my-flow-uuid", ... }
 
 ### API Changes
 1. Rename parameters: assignAlias → alias, assignFlowAlias → flowAlias
-2. Rename endpoint: POST /generations/:id/retry → /generations/:id/regenerate
+2. Make referenceImages parameter optional with auto-detection from prompt
-3. Remove endpoint: POST /api/v1/flows (no longer needed)
+3. Rename endpoint: POST /generations/:id/retry → /generations/:id/regenerate
-4. Add endpoint: POST /api/v1/flows/:id/regenerate
+4. Remove endpoint: POST /api/v1/flows (no longer needed)
-5. Add endpoint: PUT /api/v1/generations/:id (modification)
+5. Add endpoint: POST /api/v1/flows/:id/regenerate
-6. Add CDN endpoints:
+6. Add endpoint: PUT /api/v1/generations/:id (modification)
+7. Add CDN endpoints:
    - GET /cdn/:org/:project/img/:filenameOrAlias (all images)
    - GET /cdn/:org/:project/live/:scope (live URLs)
-7. Add scope management endpoints (CRUD for live_scopes)
+8. Add scope management endpoints (CRUD for live_scopes)
-8. Update all image URLs in API responses to use CDN format
+9. Update all image URLs in API responses to use CDN format
 
 ### Behavior Changes
 1. Lazy flow creation (create on second request or when flowAlias present)
@@ -809,9 +913,15 @@ Response: { "flowId": "my-flow-uuid", ... }
 6. Cascade delete for flows (with alias protection)
 7. Live URL caching and scope management
 8. FlowId in responses (generate if undefined, keep if null)
+9. Auto-detect reference images from prompt aliases
 
 ### Validation Changes
 1. @ symbol distinguishes aliases from UUIDs
 2. Technical aliases forbidden in user input
 3. Flow creation on-the-fly for non-existent flowIds
 4. Scope format validation for live URLs
+
+### Documentation Changes
+1. Add comprehensive JSDoc comments to all endpoints
+2. Include purpose, logic, parameters with "affects" descriptions
+3. Document authentication requirements in comments

docs/api/references.rest

@@ -69,7 +69,7 @@ X-API-Key: {{apiKey}}
   "prompt": "A modern lorry truck driving on a winding mountain road during sunset, the truck has a large @logo-snail prominently displayed on its side panel, photorealistic style, golden hour lighting, detailed commercial vehicle, scenic mountain landscape",
   "aspectRatio": "16:9",
   "referenceImages": ["@logo-snail"],
-  "assignAlias": "@lorry-branded",
+  "assignAlias": "@lorry",
   "autoEnhance": false
 }
 
@@ -78,6 +78,21 @@ X-API-Key: {{apiKey}}
 @lorryGenerationId = {{generateLorry.response.body.$.data.id}}
 @lorryImageId = {{generateLorry.response.body.$.data.outputImageId}}
 
+### new
+POST {{base}}/api/v1/generations
+Content-Type: application/json
+X-API-Key: {{apiKey}}
+
+{
+  "prompt": "Грузовик @lorry стоит на разгрузке в аэропорту рядом с огромным грузовым самолетом на фоне гор",
+  "aspectRatio": "16:9",
+  "referenceImages": ["@lorry"],
+  "assignAlias": "@airplane",
+  "autoEnhance": false
+}
+
+###
+
 
 ###############################################################################
 # VERIFICATION: Check Both Generations
@@ -92,7 +107,7 @@ X-API-Key: {{apiKey}}
 
 ### Resolve @lorry-branded Alias
 # Confirm the lorry image alias is assigned
-GET {{base}}/api/v1/images/resolve/@lorry-branded
+GET {{base}}/api/v1/images/resolve/@lorry
 X-API-Key: {{apiKey}}
 
 ###