tt-entities 0.0.56 → 0.1.0

package/src/database/migrations/20260615103000-add-edit-order-feature.js

@@ -0,0 +1,283 @@
+'use strict';
+
+/**
+ * Edit Order — schema migration.
+ *
+ * FK columns and new table PKs use Sequelize.INTEGER to match the existing
+ * Orders.id / OrderItems.id (Sequelize default PK type is signed INTEGER,
+ * not BIGINT UNSIGNED).
+ */
+
+module.exports = {
+  up: async (queryInterface, Sequelize) => {
+    // ── 1. Orders.hasEverNeededVendor ──────────────────────────────────────
+    await queryInterface.sequelize.query(`
+      ALTER TABLE \`Orders\`
+      ADD COLUMN \`hasEverNeededVendor\` TINYINT(1) NOT NULL DEFAULT 0
+        COMMENT 'Set once at placement: true if any OrderItem ever started as awaiting_stock. Used by the Edit Order eligibility check (rule 5) — an awaiting_fulfillment order that ever needed vendor sourcing cannot be edited.'
+        AFTER \`refundStatus\`
+    `);
+
+    // ── 2. Refunds.source ────────────────────────────────────────────────
+    await queryInterface.sequelize.query(`
+      ALTER TABLE \`Refunds\`
+      ADD COLUMN \`source\` ENUM('cancellation', 'order_edit') NOT NULL DEFAULT 'cancellation'
+        COMMENT 'Where this refund originated. order_edit refunds are created when an edit lowers the order total (rule 3b).'
+        AFTER \`notes\`
+    `);
+
+    // ── 3. Refunds.editLogId + index ────────────────────────────────────────
+    await queryInterface.sequelize.query(`
+      ALTER TABLE \`Refunds\`
+      ADD COLUMN \`editLogId\` INT NULL
+        COMMENT 'FK -> OrderItemChangeLogs.id. Set when source = order_edit; links this refund to the specific edit that produced it.'
+        AFTER \`source\`
+    `);
+    await queryInterface.addIndex('Refunds', ['editLogId'], {
+      name: 'refunds_edit_log_id_index',
+    });
+
+    // ── 4. OrderItemChangeLogs — rule 2: one row per confirmed edit ──────────
+    await queryInterface.createTable('OrderItemChangeLogs', {
+      id: { type: Sequelize.INTEGER, autoIncrement: true, primaryKey: true },
+      orderId: {
+        type: Sequelize.INTEGER,
+        allowNull: false,
+        references: { model: 'Orders', key: 'id' },
+        onDelete: 'CASCADE',
+        onUpdate: 'CASCADE',
+      },
+      editNumber: {
+        type: Sequelize.INTEGER,
+        allowNull: false,
+        comment:
+          'Sequential per order: 1, 2, 3... — the Nth confirmed edit on this order.',
+      },
+      beforeItemsJson: {
+        type: Sequelize.JSON,
+        allowNull: false,
+        comment:
+          'Snapshot of the basket immediately before this edit was applied.',
+      },
+      afterItemsJson: {
+        type: Sequelize.JSON,
+        allowNull: false,
+        comment:
+          'Snapshot of the basket immediately after this edit was applied.',
+      },
+      summary: {
+        type: Sequelize.TEXT,
+        allowNull: false,
+        comment:
+          'Pre-rendered human-readable diff, e.g. "Invictus: 2 -> 1, Champion: 0 -> 1 (+1)". Computed once at confirm-time.',
+      },
+      priceDelta: {
+        type: Sequelize.DECIMAL(10, 3),
+        allowNull: false,
+        defaultValue: 0,
+        comment:
+          'newTotal - oldTotal. Positive = customer owes more, negative = refund issued, zero = no payment change.',
+      },
+      scenario: {
+        type: Sequelize.ENUM('same', 'refund', 'additional_payment'),
+        allowNull: false,
+      },
+      changedBy: {
+        type: Sequelize.STRING(64),
+        allowNull: false,
+        comment: 'e.g. admin:42',
+      },
+      createdAt: { type: Sequelize.DATE, allowNull: false },
+      updatedAt: { type: Sequelize.DATE, allowNull: false },
+    });
+    await queryInterface.addIndex('OrderItemChangeLogs', ['orderId'], {
+      name: 'order_item_change_logs_order_id_index',
+    });
+    await queryInterface.addIndex(
+      'OrderItemChangeLogs',
+      ['orderId', 'editNumber'],
+      {
+        name: 'order_item_change_logs_order_id_edit_number_index',
+      },
+    );
+
+    // ── 5. Refunds.editLogId -> OrderItemChangeLogs FK (now that table exists) ──
+    await queryInterface.addConstraint('Refunds', {
+      fields: ['editLogId'],
+      type: 'foreign key',
+      name: 'refunds_edit_log_id_foreign',
+      references: { table: 'OrderItemChangeLogs', field: 'id' },
+      onDelete: 'SET NULL',
+      onUpdate: 'CASCADE',
+    });
+
+    // ── 6. OrderEditSessions — in-progress edit lock ─────────────────────────
+    await queryInterface.createTable('OrderEditSessions', {
+      id: { type: Sequelize.INTEGER, autoIncrement: true, primaryKey: true },
+      orderId: {
+        type: Sequelize.INTEGER,
+        allowNull: false,
+        references: { model: 'Orders', key: 'id' },
+        onDelete: 'CASCADE',
+        onUpdate: 'CASCADE',
+      },
+      createdBy: {
+        type: Sequelize.STRING(64),
+        allowNull: false,
+        comment: 'e.g. admin:42',
+      },
+      expiresAt: {
+        type: Sequelize.DATE,
+        allowNull: false,
+        comment:
+          'createdAt + 2 hours. Expired sessions are treated as gone and can be silently replaced.',
+      },
+      createdAt: { type: Sequelize.DATE, allowNull: false },
+      updatedAt: { type: Sequelize.DATE, allowNull: false },
+    });
+    await queryInterface.addIndex('OrderEditSessions', ['orderId'], {
+      name: 'order_edit_sessions_order_id_index',
+    });
+    await queryInterface.addIndex('OrderEditSessions', ['expiresAt'], {
+      name: 'order_edit_sessions_expires_at_index',
+    });
+
+    // ── 7. OrderEditItems — working-copy basket for a session ───────────────
+    await queryInterface.createTable('OrderEditItems', {
+      id: { type: Sequelize.INTEGER, autoIncrement: true, primaryKey: true },
+      sessionId: {
+        type: Sequelize.INTEGER,
+        allowNull: false,
+        references: { model: 'OrderEditSessions', key: 'id' },
+        onDelete: 'CASCADE',
+        onUpdate: 'CASCADE',
+      },
+      itemType: {
+        type: Sequelize.ENUM('product', 'bundle'),
+        allowNull: false,
+        defaultValue: 'product',
+      },
+      productId: { type: Sequelize.INTEGER, allowNull: true },
+      productVariantId: { type: Sequelize.INTEGER, allowNull: true },
+      bundleId: { type: Sequelize.INTEGER, allowNull: true },
+      composedSku: { type: Sequelize.STRING(255), allowNull: true },
+      quantity: { type: Sequelize.INTEGER, allowNull: false, defaultValue: 1 },
+      unitPrice: { type: Sequelize.DECIMAL(10, 3), allowNull: false },
+      lineTotal: { type: Sequelize.DECIMAL(10, 3), allowNull: false },
+      sourceOrderItemId: {
+        type: Sequelize.INTEGER,
+        allowNull: true,
+        references: { model: 'OrderItems', key: 'id' },
+        onDelete: 'SET NULL',
+        onUpdate: 'CASCADE',
+        comment:
+          'NULL if this line was newly added during this edit; set if it corresponds to an existing OrderItem (possibly with a changed quantity).',
+      },
+      bundleSelectionsJson: {
+        type: Sequelize.JSON,
+        allowNull: true,
+        comment:
+          'For itemType=bundle: array of {productId, productVariantId, productNameEn, productNameAr, variantLabelEn, variantLabelAr, sortOrder} — same shape as OrderItemBundleSelections.',
+      },
+      createdAt: { type: Sequelize.DATE, allowNull: false },
+      updatedAt: { type: Sequelize.DATE, allowNull: false },
+    });
+    await queryInterface.addIndex('OrderEditItems', ['sessionId'], {
+      name: 'order_edit_items_session_id_index',
+    });
+    await queryInterface.addIndex('OrderEditItems', ['sourceOrderItemId'], {
+      name: 'order_edit_items_source_order_item_id_index',
+    });
+
+    // ── 8. OrderPayments — additional payments, N per order ──────────────────
+    await queryInterface.createTable('OrderPayments', {
+      id: { type: Sequelize.INTEGER, autoIncrement: true, primaryKey: true },
+      orderId: {
+        type: Sequelize.INTEGER,
+        allowNull: false,
+        references: { model: 'Orders', key: 'id' },
+        onDelete: 'CASCADE',
+        onUpdate: 'CASCADE',
+      },
+      editLogId: {
+        type: Sequelize.INTEGER,
+        allowNull: true,
+        references: { model: 'OrderItemChangeLogs', key: 'id' },
+        onDelete: 'SET NULL',
+        onUpdate: 'CASCADE',
+        comment: 'The edit that created this top-up requirement.',
+      },
+      sequence: {
+        type: Sequelize.INTEGER,
+        allowNull: false,
+        comment:
+          '1, 2, 3... per order — the Nth additional payment. Used as the {sequence} path segment in the unified payment-result URL and as the -P{sequence} suffix sent to payment gateways.',
+      },
+      amount: { type: Sequelize.DECIMAL(10, 3), allowNull: false },
+      currency: { type: Sequelize.STRING(8), allowNull: false },
+      paymentMethodSlug: { type: Sequelize.STRING(64), allowNull: false },
+      type: { type: Sequelize.ENUM('online', 'offline'), allowNull: false },
+      status: {
+        type: Sequelize.ENUM('pending', 'paid', 'failed', 'cancelled'),
+        allowNull: false,
+        defaultValue: 'pending',
+      },
+      paymentReference: {
+        type: Sequelize.STRING(255),
+        allowNull: true,
+        comment:
+          'Gateway transaction ID (online) or manual reference (offline).',
+      },
+      paymentLinkToken: {
+        type: Sequelize.STRING(255),
+        allowNull: true,
+        comment:
+          'Token used in the unified payment-result URL for this top-up.',
+      },
+      paidAt: { type: Sequelize.DATE, allowNull: true },
+      createdAt: { type: Sequelize.DATE, allowNull: false },
+      updatedAt: { type: Sequelize.DATE, allowNull: false },
+    });
+    await queryInterface.addConstraint('OrderPayments', {
+      fields: ['orderId', 'sequence'],
+      type: 'unique',
+      name: 'order_payments_order_id_sequence_unique',
+    });
+    await queryInterface.addIndex('OrderPayments', ['editLogId'], {
+      name: 'order_payments_edit_log_id_index',
+    });
+    await queryInterface.addIndex('OrderPayments', ['status'], {
+      name: 'order_payments_status_index',
+    });
+
+    // ── Backfill: Orders.hasEverNeededVendor for existing orders ──────────────
+    await queryInterface.sequelize.query(`
+      UPDATE \`Orders\` o
+         SET o.\`hasEverNeededVendor\` = 1
+       WHERE EXISTS (
+           SELECT 1 FROM \`OrderStatusHistories\` h
+            WHERE h.\`orderId\` = o.\`id\`
+              AND h.\`toStatus\` = 'pending_vendor'
+       )
+         AND o.\`hasEverNeededVendor\` = 0
+    `);
+  },
+
+  down: async (queryInterface, Sequelize) => {
+    await queryInterface.dropTable('OrderPayments');
+    await queryInterface.dropTable('OrderEditItems');
+    await queryInterface.dropTable('OrderEditSessions');
+
+    await queryInterface.removeConstraint(
+      'Refunds',
+      'refunds_edit_log_id_foreign',
+    );
+    await queryInterface.removeIndex('Refunds', 'refunds_edit_log_id_index');
+    await queryInterface.removeColumn('Refunds', 'editLogId');
+    await queryInterface.removeColumn('Refunds', 'source');
+
+    await queryInterface.dropTable('OrderItemChangeLogs');
+
+    await queryInterface.removeColumn('Orders', 'hasEverNeededVendor');
+  },
+};