@endora-commerce/mod-returns 0.100.0

package/dist/migrations/20260625T144227_returns_init.js

@@ -0,0 +1,241 @@
+import { Migration } from '@mikro-orm/migrations';
+import { randomUUID } from 'crypto';
+import { DEFAULT_RETURN_STATUSES, computeDefaultTransitions, } from '../backend/domain/return-status-graph.js';
+import { DEFAULT_RETURN_REASONS } from '../backend/domain/default-reasons.js';
+/**
+ * Feature 046 — Returns & Complaints (Refunds, RMA).
+ *
+ * Creates the returns module schema: the RMA case + items, the configurable
+ * status graph (`return_statuses` + `return_status_transitions`) seeded from the
+ * single source of truth in `domain/return-status-graph.ts`, comments, managed
+ * reasons (seeded with defaults), return delivery methods, refunds, return
+ * shipments, attachments, saved views, and the `return_cases_rma_seq` sequence.
+ */
+export class Migration20260625T144227ReturnsInit extends Migration {
+    async up() {
+        // --- Configurable status graph -----------------------------------------
+        this.addSql(`
+      create table "return_statuses" (
+        "id" uuid not null,
+        "code" varchar(64) not null,
+        "name" jsonb not null,
+        "default_name" varchar(120) not null,
+        "is_initial" boolean not null default false,
+        "is_terminal" boolean not null default false,
+        "is_system" boolean not null default false,
+        "weight" int not null default 100,
+        "color" varchar(16) not null default '#64748b',
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "return_statuses_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`alter table "return_statuses" add constraint "return_statuses_code_unique" unique ("code");`);
+        this.addSql(`
+      create table "return_status_transitions" (
+        "id" uuid not null,
+        "from_status_code" varchar(64) not null,
+        "to_status_code" varchar(64) not null,
+        "is_system" boolean not null default false,
+        "created_at" timestamptz not null,
+        constraint "return_status_transitions_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`alter table "return_status_transitions" add constraint "return_status_transitions_pair_unique" unique ("from_status_code", "to_status_code");`);
+        this.addSql(`create index "return_status_transitions_from_idx" on "return_status_transitions" ("from_status_code");`);
+        for (const s of DEFAULT_RETURN_STATUSES) {
+            this.addSql(`insert into "return_statuses" ("id", "code", "name", "default_name", "is_initial", "is_terminal", "is_system", "weight", "color", "created_at", "updated_at") ` +
+                `values ('${randomUUID()}', '${s.code}', '${jsonLiteral(s.name)}'::jsonb, '${s.defaultName}', ${s.isInitial}, ${s.isTerminal}, ${s.isSystem}, ${s.weight}, '${s.color}', now(), now());`);
+        }
+        for (const t of computeDefaultTransitions()) {
+            this.addSql(`insert into "return_status_transitions" ("id", "from_status_code", "to_status_code", "is_system", "created_at") ` +
+                `values ('${randomUUID()}', '${t.fromStatusCode}', '${t.toStatusCode}', ${t.isSystem}, now());`);
+        }
+        // --- RMA case number sequence ------------------------------------------
+        this.addSql(`create sequence if not exists "return_cases_rma_seq";`);
+        // --- Cases & items ------------------------------------------------------
+        this.addSql(`
+      create table "return_cases" (
+        "id" uuid not null,
+        "kind" varchar(16) not null,
+        "rma_number" varchar(64) null,
+        "order_id" uuid not null,
+        "sales_channel_id" uuid not null,
+        "customer_account_id" uuid not null,
+        "organization_id" uuid null,
+        "status_code" varchar(64) not null,
+        "currency" varchar(3) not null,
+        "return_delivery_method_id" uuid null,
+        "applied_return_cost" numeric(14,2) not null default 0,
+        "return_cost_bearer" varchar(16) not null default 'customer',
+        "free_return_eligible" boolean not null default false,
+        "resolution_type" varchar(16) null,
+        "refund_payment_method_id" uuid null,
+        "total_refund_amount" numeric(14,2) not null default 0,
+        "rejection_reason" text null,
+        "submitted_at" timestamptz not null,
+        "authorized_at" timestamptz null,
+        "resolved_at" timestamptz null,
+        "closed_at" timestamptz null,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "return_cases_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`alter table "return_cases" add constraint "return_cases_rma_number_unique" unique ("rma_number");`);
+        this.addSql(`create index "return_cases_order_idx" on "return_cases" ("order_id");`);
+        this.addSql(`create index "return_cases_sales_channel_idx" on "return_cases" ("sales_channel_id");`);
+        this.addSql(`create index "return_cases_customer_idx" on "return_cases" ("customer_account_id");`);
+        this.addSql(`create index "return_cases_organization_idx" on "return_cases" ("organization_id");`);
+        this.addSql(`create index "return_cases_status_idx" on "return_cases" ("status_code");`);
+        this.addSql(`
+      create table "return_case_items" (
+        "id" uuid not null,
+        "return_case_id" uuid not null,
+        "order_item_id" uuid not null,
+        "product_id" uuid not null,
+        "product_name" varchar(512) not null,
+        "quantity" int not null,
+        "reason_id" uuid null,
+        "description" text null,
+        "inspection_outcome" varchar(16) null,
+        "default_refund_amount" numeric(14,2) not null,
+        "approved_refund_amount" numeric(14,2) not null default 0,
+        constraint "return_case_items_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "return_case_items_case_idx" on "return_case_items" ("return_case_id");`);
+        this.addSql(`create index "return_case_items_order_item_idx" on "return_case_items" ("order_item_id");`);
+        // --- Comments -----------------------------------------------------------
+        this.addSql(`
+      create table "return_case_comments" (
+        "id" uuid not null,
+        "return_case_id" uuid not null,
+        "author_admin_user_id" uuid null,
+        "author_customer_account_id" uuid null,
+        "body" text not null,
+        "is_customer_visible" boolean not null default true,
+        "notify_customer" boolean not null default false,
+        "created_at" timestamptz not null,
+        constraint "return_case_comments_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "return_case_comments_case_idx" on "return_case_comments" ("return_case_id");`);
+        this.addSql(`create index "return_case_comments_created_idx" on "return_case_comments" ("created_at");`);
+        // --- Reasons (seeded with defaults) ------------------------------------
+        this.addSql(`
+      create table "return_reasons" (
+        "id" uuid not null,
+        "label" jsonb not null,
+        "applies_to" varchar(16) not null,
+        "is_active" boolean not null default true,
+        "weight" int not null default 100,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "return_reasons_pkey" primary key ("id")
+      );
+    `);
+        for (const r of DEFAULT_RETURN_REASONS) {
+            this.addSql(`insert into "return_reasons" ("id", "label", "applies_to", "is_active", "weight", "created_at", "updated_at") ` +
+                `values ('${randomUUID()}', '${jsonLiteral(r.label)}'::jsonb, '${r.appliesTo}', true, ${r.weight}, now(), now());`);
+        }
+        // --- Return delivery methods -------------------------------------------
+        this.addSql(`
+      create table "return_delivery_methods" (
+        "id" uuid not null,
+        "delivery_method_id" uuid not null,
+        "return_cost" numeric(14,2) not null,
+        "currency" varchar(3) not null,
+        "is_active" boolean not null default true,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "return_delivery_methods_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "return_delivery_methods_method_idx" on "return_delivery_methods" ("delivery_method_id");`);
+        // --- Refunds ------------------------------------------------------------
+        this.addSql(`
+      create table "refunds" (
+        "id" uuid not null,
+        "return_case_id" uuid not null,
+        "resolution_type" varchar(16) not null,
+        "amount" numeric(14,2) not null,
+        "currency" varchar(3) not null,
+        "payment_method_id" uuid null,
+        "settlement_state" varchar(16) not null,
+        "external_reference" varchar(128) null,
+        "provider_details" jsonb null,
+        "failure_reason" text null,
+        "corrective_invoice_id" uuid null,
+        "credit_limit_topup_applied" boolean not null default false,
+        "attempt_no" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "refunds_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "refunds_case_idx" on "refunds" ("return_case_id");`);
+        // --- Return shipments ---------------------------------------------------
+        this.addSql(`
+      create table "return_shipments" (
+        "id" uuid not null,
+        "return_case_id" uuid not null,
+        "direction" varchar(16) not null,
+        "delivery_method_id" uuid null,
+        "external_reference" varchar(128) null,
+        "status" varchar(16) not null default 'pending',
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "return_shipments_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "return_shipments_case_idx" on "return_shipments" ("return_case_id");`);
+        // --- Attachments --------------------------------------------------------
+        this.addSql(`
+      create table "return_case_attachments" (
+        "id" uuid not null,
+        "return_case_id" uuid not null,
+        "return_case_item_id" uuid null,
+        "asset_id" uuid not null,
+        "created_at" timestamptz not null,
+        constraint "return_case_attachments_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "return_case_attachments_case_idx" on "return_case_attachments" ("return_case_id");`);
+        // --- Saved views --------------------------------------------------------
+        this.addSql(`
+      create table "return_list_saved_views" (
+        "id" uuid not null,
+        "owner_admin_user_id" uuid not null,
+        "name" varchar(200) not null,
+        "shared" boolean not null default false,
+        "filters" jsonb not null,
+        "sort" jsonb not null,
+        "visible_columns" jsonb null,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "return_list_saved_views_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "return_list_saved_views_owner_idx" on "return_list_saved_views" ("owner_admin_user_id");`);
+    }
+    async down() {
+        this.addSql(`drop table if exists "return_list_saved_views";`);
+        this.addSql(`drop table if exists "return_case_attachments";`);
+        this.addSql(`drop table if exists "return_shipments";`);
+        this.addSql(`drop table if exists "refunds";`);
+        this.addSql(`drop table if exists "return_delivery_methods";`);
+        this.addSql(`drop table if exists "return_reasons";`);
+        this.addSql(`drop table if exists "return_case_comments";`);
+        this.addSql(`drop table if exists "return_case_items";`);
+        this.addSql(`drop table if exists "return_cases";`);
+        this.addSql(`drop sequence if exists "return_cases_rma_seq";`);
+        this.addSql(`drop table if exists "return_status_transitions";`);
+        this.addSql(`drop table if exists "return_statuses";`);
+    }
+}
+/** Serialize a localized label map to a single-quoted SQL JSON literal. */
+function jsonLiteral(value) {
+    return JSON.stringify(value).replace(/'/g, "''");
+}
+//# sourceMappingURL=20260625T144227_returns_init.js.map

package/dist/migrations/20260625T144227_returns_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260625T144227_returns_init.js","sourceRoot":"","sources":["../../src/migrations/20260625T144227_returns_init.ts"],"names":[],"mappings":"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"}

package/dist/migrations/20260817T203206_returns_refund_corrective_invoice_outcome.d.ts

@@ -0,0 +1,25 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `refunds.corrective_invoice_outcome` — the three-way answer, persisted
+ * (D-92, issue #156).
+ *
+ * The row held `corrective_invoice_id` alone, so `null` stood for "no
+ * correction was due", "none was asked for" and "one was asked for and we do
+ * not know" at once. The distinction lived in the settlement response and the
+ * audit entry, neither of which survives a page reload — which is exactly the
+ * confusion the explicit `reason` field was added to prevent (#135).
+ *
+ * `not_requested` is the default because it is what a row with no correction
+ * asked for means, and the backfill promotes the rows that carry a document.
+ * `corrective_invoice_id` stays, and stays non-null exactly when the outcome is
+ * `issued`.
+ *
+ * The pre-D-92 rows with no document are backfilled to `not_requested` rather
+ * than `not_due`: which of the two they were is not recoverable from the row,
+ * and claiming the more specific answer would invent it.
+ */
+export declare class Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260817T203206_returns_refund_corrective_invoice_outcome.d.ts.map

package/dist/migrations/20260817T203206_returns_refund_corrective_invoice_outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260817T203206_returns_refund_corrective_invoice_outcome.d.ts","sourceRoot":"","sources":["../../src/migrations/20260817T203206_returns_refund_corrective_invoice_outcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,6DAA8D,SAAQ,SAAS;IAC3E,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAOrC"}

package/dist/migrations/20260817T203206_returns_refund_corrective_invoice_outcome.js

@@ -0,0 +1,46 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `refunds.corrective_invoice_outcome` — the three-way answer, persisted
+ * (D-92, issue #156).
+ *
+ * The row held `corrective_invoice_id` alone, so `null` stood for "no
+ * correction was due", "none was asked for" and "one was asked for and we do
+ * not know" at once. The distinction lived in the settlement response and the
+ * audit entry, neither of which survives a page reload — which is exactly the
+ * confusion the explicit `reason` field was added to prevent (#135).
+ *
+ * `not_requested` is the default because it is what a row with no correction
+ * asked for means, and the backfill promotes the rows that carry a document.
+ * `corrective_invoice_id` stays, and stays non-null exactly when the outcome is
+ * `issued`.
+ *
+ * The pre-D-92 rows with no document are backfilled to `not_requested` rather
+ * than `not_due`: which of the two they were is not recoverable from the row,
+ * and claiming the more specific answer would invent it.
+ */
+export class Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome extends Migration {
+    async up() {
+        this.addSql(`
+      alter table "refunds"
+        add column "corrective_invoice_outcome" varchar(16) not null default 'not_requested';
+    `);
+        this.addSql(`
+      alter table "refunds"
+        add constraint "refunds_corrective_invoice_outcome_check"
+        check ("corrective_invoice_outcome" in ('issued', 'not_due', 'not_requested'));
+    `);
+        this.addSql(`
+      update "refunds"
+         set "corrective_invoice_outcome" = 'issued'
+       where "corrective_invoice_id" is not null;
+    `);
+    }
+    async down() {
+        this.addSql(`
+      alter table "refunds"
+        drop constraint if exists "refunds_corrective_invoice_outcome_check";
+    `);
+        this.addSql(`alter table "refunds" drop column if exists "corrective_invoice_outcome";`);
+    }
+}
+//# sourceMappingURL=20260817T203206_returns_refund_corrective_invoice_outcome.js.map

package/dist/migrations/20260817T203206_returns_refund_corrective_invoice_outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260817T203206_returns_refund_corrective_invoice_outcome.js","sourceRoot":"","sources":["../../src/migrations/20260817T203206_returns_refund_corrective_invoice_outcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,6DAA8D,SAAQ,SAAS;IACjF,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,2EAA2E,CAAC,CAAC;IAC3F,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260625T144227ReturnsInit } from './20260625T144227_returns_init.js';
+import { Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome } from './20260817T203206_returns_refund_corrective_invoice_outcome.js';
+export declare const migrations: (typeof Migration20260625T144227ReturnsInit)[];
+export { Migration20260625T144227ReturnsInit, Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome, };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,mCAAmC,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,6DAA6D,EAAE,MAAM,gEAAgE,CAAC;AAE/I,eAAO,MAAM,UAAU,gDAGtB,CAAC;AAEF,OAAO,EACL,mCAAmC,EACnC,6DAA6D,GAC9D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,31 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260625T144227ReturnsInit } from './20260625T144227_returns_init.js';
+import { Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome } from './20260817T203206_returns_refund_corrective_invoice_outcome.js';
+export const migrations = [
+    Migration20260625T144227ReturnsInit,
+    Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome,
+];
+export { Migration20260625T144227ReturnsInit, Migration20260817T203206ReturnsRefundCorrectiveInvoiceOutcome, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,mCAAmC,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,6DAA6D,EAAE,MAAM,gEAAgE,CAAC;AAE/I,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mCAAmC;IACnC,6DAA6D;CAC9D,CAAC;AAEF,OAAO,EACL,mCAAmC,EACnC,6DAA6D,GAC9D,CAAC"}

package/docs/returns.md

@@ -0,0 +1,103 @@
+---
+title: returns
+description: Returns and complaints (RMA) — submission, verification, reverse-logistics shipments and settlement over a configurable status graph
+---
+
+# `returns`
+
+Returns & complaints (Refunds, RMA). Manages the lifecycle of a return or
+complaint case raised against a completed order — submission, verification and
+RMA-number assignment, reverse-logistics shipments, and settlement (money
+refund, store credit, replacement, or repair) including the corrective invoice.
+Mirrors the `orders` module's configurable status-graph workflow.
+
+## Public surface
+
+Admin routes are gated by `returns:read` (read) / `returns:write` (mutations).
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/orders/:orderId/returnable` | customer | Returnable lines + eligibility for an order |
+| `POST /api/v1/returns` | customer | Open a return/complaint case |
+| `GET /api/v1/returns` | customer | List the caller's cases |
+| `GET /api/v1/returns/:id` | customer | Case detail (customer-visible comments only) |
+| `POST /api/v1/returns/:id/comments` | customer | Reply on a case |
+| `POST /api/v1/returns/:id/select-delivery-method` | customer | Choose a return delivery method |
+| `POST /api/v1/returns/:id/cancel` | customer | Withdraw the case |
+| `GET /api/v1/returns/reasons` | customer | Active reasons for the storefront form |
+| `GET /api/v1/admin/returns` | admin | List/filter/search cases + per-status counts |
+| `GET /api/v1/admin/returns/export` | admin | CSV export of the current view |
+| `POST /api/v1/admin/returns/bulk-transition` | admin | Bulk status change (skips disallowed) |
+| `GET /api/v1/admin/returns/:id` | admin | Case detail (incl. internal comments) |
+| `POST /api/v1/admin/returns/:id/authorize` | admin | Assign RMA number, advance to `authorized` |
+| `POST /api/v1/admin/returns/:id/reject` | admin | Reject with a mandatory reason |
+| `POST /api/v1/admin/returns/:id/transition` | admin | Guarded status transition |
+| `GET\|POST /api/v1/admin/returns/:id/settlement` | admin | Prefill / execute settlement |
+| `GET\|POST /api/v1/admin/returns/:id/comments` | admin | List / add comment (visibility + notify) |
+| `GET\|POST /api/v1/admin/returns/:id/shipments` + `/:shipmentId/receive` | admin | Return shipments |
+| `…/statuses`, `…/transitions`, `…/reasons`, `…/delivery-methods`, `…/list-views` | admin | Configuration + saved views |
+
+## Status machine (configurable)
+
+The case lifecycle is **admin-configurable** (`return_statuses` +
+`return_status_transitions`, seeded on install). Defaults:
+
+- **new** (initial) → **authorized** → **received** → **resolved** → **closed** (terminal)
+- **rejected** (terminal) reachable from new/authorized/received; **cancelled** (terminal) from new/authorized.
+
+Transitions are enforced; the initial status is immutable; terminal statuses
+have no outgoing edges. Each transition emits templated `return.status.*`
+before/after events and is written to the audit log.
+
+## Key behaviours
+
+- **Eligibility & free-return window** — a case is allowed once the order
+  reaches its fulfilment-completing status; the free-return window
+  (`returns.free_return_days`, default **14** per EU Directive (EU) 2023/2673)
+  is counted from that moment and governs who bears the return shipping cost.
+- **RMA numbering** — `${prefix}${sequence}${suffix}` from
+  `returns.rma_number_prefix` / `returns.rma_number_suffix`, assigned on
+  authorization, unique and never reused.
+- **Partial / repeat returns** — per-line quantity up to the remaining
+  returnable amount, excluding quantities already covered by non-rejected /
+  non-cancelled cases.
+- **Settlement** — per-line refund defaults to the amount paid for the returned
+  quantity and may never exceed it. Resolutions: refund (money), credit (tops up
+  the organization's `credit_limits` grant), replacement, or repair. A corrective
+  invoice (`invoices` kind `correction`) is requested for money/credit settlements.
+  An order that was never invoiced has no VAT document to correct, so none is
+  issued: the settlement succeeds, the refund is recorded on the return case and
+  the payment record, and the result states `correctiveInvoice: { issued: false,
+  reason: "order_not_invoiced" }`.
+- **A switched-off payment gateway refuses the settlement**.
+  Money resolutions on a gateway-paid order call the PSP module that took the
+  payment; when an operator has that module switched off — or the deployment
+  does not offer it — the settlement answers `503 MODULE_DISABLED` naming the
+  module, with `Retry-After`. Nothing moves: the case keeps its status, no
+  `refunds` row is written, no corrective invoice is issued and no customer
+  e-mail goes out. Switching the module back on is the whole remedy. This is
+  distinct from a deployment that has **no** PSP refund integration at all,
+  which still settles as `pending_manual` for a person to pay out by hand —
+  there is nothing there to switch on.
+
+## Cross-module interfaces
+
+The module reads/affects other domains only through documented ports, never
+internal imports:
+
+- `OrderReturnContextPort` (orders) — paid-per-line amounts + completing-status time.
+- `PaymentRefundPort` (payments) — issue the refund, answer `pending_manual`
+  where no PSP integration exists, or refuse when the gateway that took the
+  payment is switched off.
+- `CorrectiveInvoicePort` (invoices) — create a `correction` invoice, or answer
+  that none is due because the order carries no invoice to correct.
+- `CreditTopupPort` (credit_limits) — credit the organization grant.
+- `ShipmentService` (shipments) — optional replacement outbound shipment.
+
+## Schema
+
+Migration `080_returns_init.ts` creates `return_cases`, `return_case_items`,
+`return_case_comments`, `return_statuses`, `return_status_transitions`,
+`return_reasons`, `return_delivery_methods`, `refunds`, `return_shipments`,
+`return_case_attachments`, `return_list_saved_views`, and the
+`return_cases_rma_seq` sequence.

package/i18n/en.json

@@ -0,0 +1,28 @@
+{
+  "settings.freeReturnDays.label": "Free-return window (days)",
+  "settings.rmaNumberPrefix.label": "RMA number prefix",
+  "settings.rmaNumberSuffix.label": "RMA number suffix",
+  "settings.defaultCostBearerOutsideWindow.label": "Return cost bearer outside the free-return window",
+  "actions.openReturns.label": "Open returns",
+  "actions.openReturns.description": "View and manage returns and complaints (RMA)",
+  "actions.returnStatusConfig.label": "Return statuses",
+  "actions.returnStatusConfig.description": "Configure the return/complaint status lifecycle and transitions",
+  "list.title": "Returns",
+  "list.search.placeholder": "Search by RMA number, order, customer",
+  "statusConfig.title": "Return status configuration",
+  "statusConfig.addStatus": "Add status",
+  "statusConfig.terminal": "Terminal status",
+  "statusConfig.initial": "Initial status",
+  "statusConfig.deleteInUse": "Cannot delete a status that cases currently use",
+  "statusConfig.cannotDeleteInitial": "The initial status cannot be deleted",
+  "comments.add": "Add comment",
+  "comments.internal": "Internal (admin only)",
+  "comments.customerVisible": "Visible to customer",
+  "comments.notifyCustomer": "Notify customer",
+  "comments.closedTerminal": "Commenting is closed for finished cases",
+  "settlement.refund": "Refund money",
+  "settlement.credit": "Credit toward future orders",
+  "settlement.replacement": "Replacement",
+  "settlement.repair": "Repair",
+  "nav.returns.label": "Returns"
+}

package/i18n/pl.json

@@ -0,0 +1,28 @@
+{
+  "settings.freeReturnDays.label": "Okno bezpłatnego zwrotu (dni)",
+  "settings.rmaNumberPrefix.label": "Prefiks numeru RMA",
+  "settings.rmaNumberSuffix.label": "Sufiks numeru RMA",
+  "settings.defaultCostBearerOutsideWindow.label": "Strona ponosząca koszt zwrotu po upływie okna",
+  "actions.openReturns.label": "Otwórz zwroty",
+  "actions.openReturns.description": "Przeglądaj i zarządzaj zwrotami i reklamacjami (RMA)",
+  "actions.returnStatusConfig.label": "Statusy zwrotów",
+  "actions.returnStatusConfig.description": "Konfiguruj cykl życia i przejścia statusów zwrotu/reklamacji",
+  "list.title": "Zwroty",
+  "list.search.placeholder": "Szukaj po numerze RMA, zamówieniu, kliencie",
+  "statusConfig.title": "Konfiguracja statusów zwrotu",
+  "statusConfig.addStatus": "Dodaj status",
+  "statusConfig.terminal": "Status końcowy",
+  "statusConfig.initial": "Status początkowy",
+  "statusConfig.deleteInUse": "Nie można usunąć statusu używanego przez sprawy",
+  "statusConfig.cannotDeleteInitial": "Nie można usunąć statusu początkowego",
+  "comments.add": "Dodaj komentarz",
+  "comments.internal": "Wewnętrzny (tylko admin)",
+  "comments.customerVisible": "Widoczny dla klienta",
+  "comments.notifyCustomer": "Powiadom klienta",
+  "comments.closedTerminal": "Komentowanie jest zamknięte dla zakończonych spraw",
+  "settlement.refund": "Zwrot pieniędzy",
+  "settlement.credit": "Zaliczenie na poczet przyszłych zamówień",
+  "settlement.replacement": "Wymiana",
+  "settlement.repair": "Naprawa",
+  "nav.returns.label": "Zwroty"
+}