@clidey/dory 0.1.0 → 0.3.0

package/docs/usage/api-usage/api-purchase-orders.mdx

@@ -1,289 +0,0 @@
----
-title: 'Purchase Orders API'
-description: 'Endpoints to create, update, delete, and manage purchase orders and shipments.'
----
-
-## Purchase Orders API - Internal Developer Documentation
-
-### 1. Purpose and Scope
-
-The Purchase Orders API serves as the core backend module responsible for managing the lifecycle and data of purchase orders within the Genie platform. It handles creation, retrieval, updating, deletion, shipment management, payment processing, item variant management, import/export of purchase orders, and status transitions.
-
-This service encapsulates all business logic related to purchase orders, including complex internal state updates such as shipment receipt processing and integration with external systems (e.g., Shopify). It operates within the broader context of team-based multi-tenancy and is integral to inventory planning and supplier coordination.
-
-The API module boundaries cover:
-- Purchase order CRUD operations
-- Purchase order item and shipment management
-- Purchase order status and payment status updates
-- Integration points with email notifications and Shopify
-- PDF export and multi-format data export
-
-It interacts closely with user/team management services for authorization and compliance, and with shipment cost, bundle, and product variant services.
-
-
-### 2. Technical Overview
-
-The Purchase Orders API is implemented as a NestJS module exposing a comprehensive RESTful API and internal service methods. It leverages TypeORM for data persistence and transaction support. Key features include:
-
-- **PurchaseOrdersController**: Exposes HTTP endpoints for CRUD and specialized operations.
-- **PurchaseOrdersService**: Contains business logic and database operations.
-- **Transactional Operations**: Key operations such as purchase order duplication, creation with shipments, and status updates are performed within database transactions to ensure consistency.
-- **Integration with Email and Slack**: Sends notifications upon shipment receipt, import requests, and reminders.
-- **Data Export**: Supports PDF generation and CSV export of POs for downstream reporting or user download.
-
-#### Dependencies & Shared Libraries
-- `@genie/shared`: Common Typescript DTOs, enums, and helper utilities (e.g., error codes, date utilities).
-- `typeorm`: ORM for data access.
-- External services:
-  - ShopifyProductsService for inventory adjustments
-  - EmailService and SlackService for notifications
-  - TeamsService for team plan and user info
-
-#### Architectural Patterns
-- Structurally, the module adheres to the **MVC** pattern with controller, service, and entity layers.
-- Uses **repository pattern** via TypeORM.
-- Employs **transactional consistency** for multi-entity updates.
-- Implements **soft delete** semantics for data retention.
-
-
-### Mermaid Diagram
-
-```mermaid
-flowchart TD
-  subgraph Backend API
-    POController["PurchaseOrdersController"]:::controller
-    POService["PurchaseOrdersService"]:::service
-    PORepo["PurchaseOrderRepository (TypeORM)"]:::repository
-    POItemRepo["PurchaseOrderItemRepository"]:::repository
-    POShipmentRepo["PurchaseOrderShipmentRepository"]:::repository
-    POShipmentItemRepo["PurchaseOrderShipmentItemRepository"]:::repository
-    POPaymentRepo["PurchaseOrderPaymentRepository"]:::repository
-    ProductVariantRepo["ProductVariantRepository"]:::repository
-    TeamRepo["TeamRepository"]:::repository
-    LocationRepo["LocationRepository"]:::repository
-    AssetsService["AssetsService"]:::service
-    WorkflowService["WorkflowService"]:::service
-    ShopifyStoreService["ShopifyStoreService"]:::service
-    ExportService["ExportService"]:::service
-    SlackService["SlackService"]:::service
-    TeamsService["TeamsService"]:::service
-    ShopifyProductsService["ShopifyProductsService"]:::service
-    EmailService["EmailService"]:::service
-  end
-
-  POController -->|calls| POService
-  POService -->|reads/writes| PORepo
-  POService -->|reads/writes| POItemRepo
-  POService -->|reads/writes| POShipmentRepo
-  POService -->|reads/writes| POShipmentItemRepo
-  POService -->|reads/writes| POPaymentRepo
-  POService -->|reads| ProductVariantRepo
-  POService -->|reads| TeamRepo
-  POService -->|reads| LocationRepo
-  POService -->|calls| AssetsService
-  POService -->|calls| WorkflowService
-  POService -->|calls| ShopifyStoreService
-  POService -->|calls| ExportService
-  POService -->|calls| SlackService
-  POService -->|calls| TeamsService
-  POService -->|calls| ShopifyProductsService
-  POService -->|calls| EmailService
-
-  classDef controller fill:#A3CEF1,stroke:#0366d6,color:#000,stroke-width:1px
-  classDef service fill:#FFE156,stroke:#996515,color:#000,stroke-width:1px
-  classDef repository fill:#3F72AF,stroke:#1C385F,color:#fff,stroke-width:1px
-
-  class POController controller
-  class POService,AssetsService,WorkflowService,ShopifyStoreService,ExportService,SlackService,TeamsService,ShopifyProductsService,EmailService service
-  class PORepo,POItemRepo,POShipmentRepo,POShipmentItemRepo,POPaymentRepo,ProductVariantRepo,TeamRepo,LocationRepo repository
-```
-
-
-### 3. Core Concepts and Responsibilities
-
-- **Purchase Order (PO)**: Represents a formal request to a supplier for products including details such as supplier, items, shipments, and costs.
-- **PO Item**: Individual product variant entries within a purchase order, including quantities and unit costs.
-- **Shipment**: Defines delivery batches and dates linked to POs with associated costs and receipt status.
-- **Payment**: Payment schedule and status related to a PO.
-
-The service maintains strict ownership of PO data, ensuring state transitions and shipment receipt are synchronized with inventory and external systems (Shopify).
-
-#### Key Assumptions & Decisions
-- Soft deleting POs for data retention and audit.
-- Payments and shipments are managed as child entities to POs.
-- Duplicate PO functionality resets status to Draft and clears received dates, while retaining items, shipments, and payments logically linked to new PO.
-- Exchange rates per currency are stored against POs for accurate financial calculations.
-
-#### Maintainers & Logging
-- Maintained by backend engineering team.
-- Uses NestJS Logger extensively for method tracing.
-- Exception handling centralizes on `GenieException` with domain-specific error codes.
-
-#### Non-Functional Requirements
-- Transactional integrity during complex updates (PO update, shipment receipt).
-- Scalable queries with pagination and filtering (e.g., shipment query API).
-- Security enforced via team membership checks (throwing `GenieException` if user not on a team).
-
-
-### 4. Code Structure
-
-- **Controllers**
-  - `PurchaseOrdersController` ([app/api/src/purchase-order/controllers/purchase-orders.controller.ts](apps/api/src/purchase-order/controllers/purchase-orders.controller.ts))
-    - Handles REST API routes such as:
-      - `POST /purchase-orders` (list POs)
-      - `GET /purchase-orders/:id`
-      - `POST /create`, `/create-with-quantities`
-      - `PUT /:id`, `PUT /:id/status`
-      - `DELETE /:id` and bulk deletes
-      - `POST /:id/duplicate`
-      - Shipment updates, payment updates, PO item additions
-      - Export endpoints
-
-- **Services**
-  - `PurchaseOrdersService` ([app/api/src/purchase-order/services/purchase-orders.service.ts](apps/api/src/purchase-order/services/purchase-orders.service.ts))
-    - Core business logic
-    - Uses injected repositories for DB operations
-    - Contains methods for:
-      - Fetching POs with flexible filters
-      - Summary aggregation of purchase orders
-      - Creating purchase orders with and without quantities
-      - Updating POs, statuses, shipments, payments
-      - Duplication logic with full entity cloning except IDs
-      - Import notification handling
-      - Shipment receipt processing with Shopify sync
-      - PDF generation via ExportService
-
-- **Repositories**
-  - TypeORM repos for PO entities (purchase order, items, shipments, payments, shipment costs, etc.).
-
-- **Utilities & Helpers**
-  - Use of `@genie/shared` modules for enums, DTOs, error handling, date utilities.
-  - Helper methods for stock coverage calculations, cost resolutions.
-
-### Example Snippet: Updating a Purchase Order
-```ts
-async updatePurchaseOrder({ id, teamId, data }) {
-  await this.handleAttachmentsUpdate(id, data.content?.attachmentUrls || []);
-
-  let purchaseOrder = await this.poRepository.findOneOrFail({
-    where: { teamId, id },
-    relations: ["items", "shipments", "shipments.items", "shipments.costs"],
-  });
-
-  purchaseOrder.status = data.status;
-  purchaseOrder.content = data.content;
-  purchaseOrder.supplierId = data.supplierId;
-  purchaseOrder.payments = data.payments.map((payment) =>
-    this.poPaymentRepository.create({
-      ...payment,
-      id: payment.id ?? undefined,
-      purchaseOrderId: purchaseOrder.id,
-      teamId,
-    })
-  );
-
-  purchaseOrder.issueDate = toDate(data.issueDate) ?? null;
-
-  // Update shipment costs
-  purchaseOrder.shipments = purchaseOrder.shipments!.map((shipment) => {
-    const newCosts = data.shipmentCosts.find((s) => s.shipmentId === shipment.id)?.costs ?? [];
-    shipment.costs = newCosts.map((cost) =>
-      this.poShipmentCostRepository.create({ ...cost, teamId, purchaseOrderShipmentId: shipment.id })
-    );
-    return shipment;
-  });
-
-  // Update items preserving IDs
-  purchaseOrder.items = data.items?.map((newItem) => {
-    const item = purchaseOrder.items!.find(i => newItem.productVariantId === i.productVariantId);
-    return this.poItemRepository.create({ ...newItem, id: item?.id, purchaseOrderId: purchaseOrder.id, teamId });
-  });
-
-  await this.poRepository.save(purchaseOrder);
-
-  // If only one shipment, re-sync shipment items quantities
-  if (purchaseOrder.shipments!.length === 1) {
-    purchaseOrder = await this.poRepository.findOneOrFail({
-      where: { teamId, id },
-      relations: ["items", "shipments", "shipments.items", "payments"],
-    });
-
-    purchaseOrder.shipments!.forEach(shipment => {
-      purchaseOrder.items!.forEach(poItem => {
-        const shipmentItem = shipment.items!.find(item => item.purchaseOrderItemId === poItem.id);
-        const orderedQuantity = poItem.quantity ?? 0;
-
-        if (shipmentItem) {
-          shipmentItem.orderedQuantity = orderedQuantity;
-        } else {
-          shipment.items!.push(
-            this.poShipmentItemRepository.create({
-              teamId,
-              purchaseOrderShipmentId: shipment.id,
-              purchaseOrderItemId: poItem.id,
-              orderedQuantity,
-            })
-          );
-        }
-      });
-    });
-
-    await this.poRepository.save(purchaseOrder);
-  }
-}
-```
-
-
-### 5. API and Interfaces
-
-The primary API endpoints are exposed via `PurchaseOrdersController` with payload validation powered by Zod schemas from `@genie/shared`:
-
-| Endpoint | HTTP Method | Purpose |
-|--------------------------|---------------|--------------------------|
-| `/purchase-orders` | POST | List purchase orders for a team with optional filters |
-| `/purchase-orders/summary` | GET | Summary of purchase orders for a team |
-| `/purchase-orders/:id` | GET | Get detailed purchase order by ID |
-| `/purchase-orders/create` | POST | Create a new purchase order |
-| `/purchase-orders/create-with-quantities` | POST | Create a new PO with explicit quantities |
-| `/purchase-orders/:id` | PUT | Update purchase order data |
-| `/purchase-orders/:id/status` | PUT | Update status of a specific PO |
-| `/purchase-orders/delete` | POST | Delete multiple POs in bulk |
-| `/purchase-orders/:id/delete` | DELETE | Soft delete a specific PO |
-| `/purchase-orders/:id/add-product-variants` | PUT | Add new product variants to existing PO |
-| `/purchase-orders/:id/shipments` | PUT | Update shipments of a PO |
-| `/purchase-orders/:id/shipments/:shipmentId` | PUT | Update a specific shipment within a PO |
-| `/purchase-orders/:id/duplicate` | POST | Duplicate an existing PO |
-| `/purchase-orders/import` | POST | Trigger import and notify process for POs
-| `/purchase-orders/:id/export/pdf` | POST | Export PO as PDF with sorted items |
-
-Requests and responses adhere to strict DTO validation. Errors produce consistent HTTP status codes such as `400` for bad requests, `404` for missing POs, and custom error bodies via `GenieException`.
-
-
-### 6. Environment & Configuration
-
-- No direct environment variables specific to purchase orders documented here.
-- Requires database connection for TypeORM repositories.
-- External credentials/configurations for:
-  - Shopify integration in `ShopifyStoreService` and `ShopifyProductsService`
-  - Email service credentials for `EmailService`
-  - Slack bot tokens for `SlackService`
-
-
-### 7. Testing, Monitoring, and Deployment
-
-- Testing strategy is not explicitly detailed in the provided context.
-- The system uses NestJS `Logger` for auditing main flows and error capture.
-- Errors are monitored using `captureException` with `GenieException` wrappers.
-- Transactions are used for critical update flows ensuring data integrity.
-
-
-### 8. Troubleshooting and Known Issues
-
-- When purchase order not found, service throws a `GenieException` with code `PurchaseOrderNotFound` handled as `404` on controller level.
-- Shipment receipt updates include rigorous validation and proper error wrapping to prevent inconsistent state.
-- Duplicate PO includes validation to ensure related items exist before copying shipments and items.
-
-
----
-
-This documentation enables backend developers to understand, maintain, and extend the Purchase Orders API with confidence, ensuring coherent purchase order management across the Genie platform.

package/docs/usage/api-usage/api-reports.mdx

@@ -1,227 +0,0 @@
----
-title: 'Reports API'
-description: 'APIs for generating reports, managing report definitions and email alert definitions.'
----
-
-# Reports API Developer Documentation
-
-## 1. Purpose and Scope
-
-The **Reports API** is responsible for managing the lifecycle and content of inventory and purchase order reports within the Genie system. It serves to generate, store, update, and deliver detailed reports that provide inventory insights, alerts, and operational snapshots.
-
-This API handles:
-
-- Defining and initializing report definitions and email alert definitions per team.
-- Generating report instances (both scheduled and manual).
-- Providing data for reports including detailed inventory statuses, purchase orders, and dashboard snapshots.
-- Emailing reports and alert emails to designated recipients.
-
-**System boundaries:**
-- Operates primarily within the backend service layer, interacting with database repositories (e.g., ReportDefinitionEntity, ReportInstanceEntity).
-- Integrates tightly with services handling inventory data, purchase orders, suppliers, dashboard data, and email delivery.
-
-
-## 2. Technical Overview
-
-The Reports API is implemented as a NestJS injectable service producing report instances based on saved definitions. It uses TypeORM for data persistence and relies on several domain-specific services for gathering required data:
-
-- `InventoryService`: Retrieves inventory items and their attributes.
-- `PurchaseOrdersService`: Provides summaries and details of purchase orders.
-- `SupplierService`: Supplies supplier information.
-- `DashboardService`: Collects dashboard snapshot data.
-- `SettingsService`: Provides user/team-specific settings such as timezone.
-- `EmailService`: Sends generated reports and alert emails.
-
-Report generation is type-driven: each report type maps to a dedicated content-generation method.
-
-### Architecture Diagram
-
-```mermaid
-flowchart TD
-  subgraph Backend Services
-    ReportsService["ReportsService"]:::service
-    InventoryService["InventoryService"]:::service
-    PurchaseOrdersService["PurchaseOrdersService"]:::service
-    SupplierService["SupplierService"]:::service
-    DashboardService["DashboardService"]:::service
-    SettingsService["SettingsService"]:::service
-    EmailService["EmailService"]:::service
-    ReportRepository["ReportDefinition & ReportInstance Repos"]:::database
-    EmailAlertRepo["EmailAlertDefinition Repository"]:::database
-  end
-  subgraph Database
-    Postgres[("PostgreSQL DB")]:::db
-  end
-
-  ReportsService -->|uses| InventoryService
-  ReportsService -->|uses| PurchaseOrdersService
-  ReportsService -->|uses| SupplierService
-  ReportsService -->|uses| DashboardService
-  ReportsService -->|uses| SettingsService
-  ReportsService -->|reads/writes| ReportRepository
-  ReportsService -->|reads/writes| EmailAlertRepo
-  ReportsService -->|generates emails via| EmailService
-
-  InventoryService -->|reads inventory data| Postgres
-  PurchaseOrdersService -->|reads purchase orders| Postgres
-  SupplierService -->|reads suppliers| Postgres
-  DashboardService -->|reads dashboard info| Postgres
-  SettingsService -->|fetches settings| Postgres
-
-  classDef service fill:#147efb,color:#fff,stroke:#005da8,stroke-width:1px
-  classDef database fill:#ffb74d,color:#000,stroke:#cc7a00,stroke-width:1px
-  classDef db fill:#8bc34a,color:#000,stroke:#689f38,stroke-width:1px
-```
-
-
-## 3. Core Concepts and Responsibilities
-
-### Terminology
-- **Report Definition:** A persisted template describing the type of report, frequency, schedule, and settings.
-- **Report Instance:** A generated report based on a definition, containing snapshot data at the generation time.
-- **Email Alert Definition:** Defines configuration for alert emails for inventory or purchase order states.
-- **Report Types:** Enumerated constants describing report categories (e.g., dead stock, stockout risk, purchase order snapshots).
-- **Report Frequency and Schedule:** Controls when reports are generated or sent.
-
-### Responsibility
-- The ReportsService is owned by the backend development team.
-- It logs its operations via NestJS Logger for traceability.
-- Error conditions use the custom `GenieException` for consistent exception handling.
-- Data consistency and report validity are enforced before generating instances.
-
-### Non-Functional Requirements
-- **Reliability:** Handles data errors by capturing exceptions and logging without crashing.
-- **Performance:** Implements pagination when fetching large data (e.g., inventory snapshots) to support scalability.
-- **Security:** Uses teamId scoping for all data queries to ensure multi-tenancy data isolation.
-- **Extensibility:** Supports adding new report types by implementing corresponding content generation methods.
-
-
-## 4. Code Structure
-
-### Key Files
-- [apps/api/src/reports/services/reports.service.ts](apps/api/src/reports/services/reports.service.ts): Main service implementing report generation logic, CRUD on report definitions, exclusions, and email alert handling.
-- [apps/web/src/components/pages/reports/reports.tsx](apps/web/src/components/pages/reports/reports.tsx): React frontend for listing and managing reports; uses API to fetch definitions.
-- [apps/api/src/admin/controllers/report.controller.ts](apps/api/src/admin/controllers/report.controller.ts): Admin controller exposing backend endpoints for reports.
-- [apps/api/src/admin/services/report.service.ts](apps/api/src/admin/services/report.service.ts): Service for admin report data health and purchase order reports.
-- [apps/api/src/email/services/email.service.ts](apps/api/src/email/services/email.service.ts): Handles email sending, including report alert emails.
-
-
-### Core Methods in `ReportsService`
-
-- `getReportDefinitionsDto(teamId)`: Fetches all report definitions for a team with the next scheduled run.
-
-- `initReportDefinitions(teamId)`: Ensures default report definitions exist with valid default settings.
-
-- `generateReportInstance({teamId, definitionId, type})`: Creates and stores a new report instance, generating content for the report type.
-
-- `generateReportContent(instance)`: Routes to the appropriate report content generation method based on report type.
-
-- `getReportDefinitionExcludedProductVariantIds(teamId, definitionId)`: Determines which product variants are excluded from the report.
-
-- `excludeReportDefinitionProductVariants(...)` and `includeReportDefinitionProductVariants(...)`: Manage exclusions by updating the database.
-
-
-### Report Content Generation
-
-Each report type has a corresponding method, e.g.,
-
-```ts
-private async generateInventoryStockoutRiskAlertContent(instance: ReportInstanceEntity): Promise<InventoryItemsStockoutRiskListReport> {
-  // Fetch stockout risk items and exclusions
-  // Filter out excluded variants
-  // Format and return structured report content
-}
-```
-
-These methods gather raw data from domain services, apply filtering and business logic, and format results according to predefined report content types.
-
-### Example snippet: Creating a report instance
-
-```ts
-async generateReportInstance({ teamId, definitionId, type }) {
-  const definition = await this.getReportDefinition(teamId, definitionId);
-  if (!definition.isValid()) {
-    throw new GenieException("Invalid report definition", {definition, teamId});
-  }
-  const instance = this.reportInstanceRepository.create({
-    teamId,
-    reportDefinitionId: definitionId,
-    reportDefinitionSnapshot: definition.getSnapshot(),
-    type,
-  });
-
-  instance.content = await this.generateReportContent(instance);
-  await this.reportInstanceRepository.save(instance);
-  return instance;
-}
-```
-
-
-## 5. API and Interfaces
-
-The ReportController exposes API endpoints (admin restricted) for:
-
-- `GET /admin/reports/data-health` - Returns health status of reports and Shopify integrations for all teams.
-- `GET /admin/reports/teams/:teamId/purchase-orders` - Returns purchase order report data for a team.
-- `POST /admin/reports/send-email-alert` - Sends alert emails for specified report instances to given email addresses.
-
-### Report Types Enum
-`ReportType` enumerates the available report categories:
-
-| Enum Value                        | Description                         |
-|---------------------------------|-------------------------------------|
-| INVENTORY_STOCKOUT_RISK_ALERT   | Stockout risk alert                |
-| INVENTORY_OUT_OF_STOCK_ALERT    | Out of stock alert                 |
-| INVENTORY_DEAD_STOCK_ALERT      | Dead stock alert                   |
-| INVENTORY_SALES_VELOCITY_ALERT  | Sales velocity alert               |
-| INVENTORY_ACTIVE_STOCK_ASSET_VALUE | Asset value report (active products) |
-| INVENTORY_ALL_STOCK_ASSET_VALUE| Asset value report (all products) |
-| INVENTORY_NEGATIVE_ON_HAND_ALERT| Negative on-hand alert             |
-| INVENTORY_SNAPSHOT             | Inventory snapshot                 |
-| INVENTORY_SALES_SNAPSHOT       | Inventory sales snapshot           |
-| PURCHASE_ORDER_ACTIVE_SNAPSHOT | Purchase order active snapshot     |
-| DASHBOARD_SNAPSHOT             | Dashboard snapshot                 |
-| INVENTORY_ITEMS_VARIANCE       | Inventory variance report          |
-| INVENTORY_IN_TRANSIT           | Inventory in transit report        |
-
-
-### Report Frequency and Schedule
-- Frequencies include Daily, Weekly, Monthly.
-- Schedule represents the time of day for scheduled reports (e.g., 0900, 1200).
-
-
-## 6. Environment & Configuration
-
-- Requires configuration of `APP_URL` for front-end link generation.
-- Uses `SENDGRID_API_KEY` for email delivery via SendGrid (configured in EmailService).
-- Environment variables control email sending behavior (e.g., prevents email sending in non-production environments to external domains).
-
-
-## 7. Testing, Monitoring, and Deployment
-
-- Logging uses NestJS Logger module; exceptions are captured via `captureException` for centralized error tracking.
-- Email sending failures log exceptions without blocking overall operations.
-- Report instance generation performs input validation and throws `GenieException` on invalid states.
-- Deployment uses TypeORM migrations for DB schema updates, including inventory view adjustments.
-
-
-## 8. Troubleshooting & Known Issues
-
-- Report instances are only generated for valid definition statuses (`Active`).
-- Generating report content without required type-specific settings throws exceptions.
-- Excluded product variants are filtered correctly to avoid irrelevant data in reports.
-
-
-## 9. References & Source Links
-
-- [Reports Service Implementation](apps/api/src/reports/services/reports.service.ts)
-- [Report Controller](apps/api/src/admin/controllers/report.controller.ts)
-- [Report Admin Service](apps/api/src/admin/services/report.service.ts)
-- [Email Service for Reports](apps/api/src/email/services/email.service.ts)
-- [Web UI Reports Listing](apps/web/src/components/pages/reports/reports.tsx)
-- [Report Instance CSV Export Utils](apps/web/src/components/pages/report-instance/utils.ts)
-
-
----
-
-This documentation provides an authoritative technical overview of the Genie Reports API backend implementation, enabling developers to understand, maintain, and extend report generation and delivery capabilities effectively.