@devx-retailos/cms 0.0.1 → 0.0.2

package/src/modules/cms/migrations/Migration20260626000000.ts

@@ -0,0 +1,17 @@
+import { Migration } from "@medusajs/framework/mikro-orm/migrations"
+
+export class Migration20260626000000 extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(
+      `alter table if exists "retailos_cms_handover" add column if not exists "opening_balance" numeric null;`
+    )
+    this.addSql(
+      `alter table if exists "retailos_cms_handover" add column if not exists "closing_balance" numeric null;`
+    )
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table if exists "retailos_cms_handover" drop column if exists "opening_balance";`)
+    this.addSql(`alter table if exists "retailos_cms_handover" drop column if exists "closing_balance";`)
+  }
+}

package/src/modules/cms/models/cms-handover.ts

@@ -7,6 +7,8 @@ const CmsHandover = model.define("retailos_cms_handover", {
   handover_id: model.text().nullable(), // free-text correlation field: the brand can pass their own ID (e.g. a bank slip number, a vault reference, a POS transaction ID) so they can cross-reference this handover record with their own external system.
   handover_amount: model.number().nullable(),
   total_cash: model.number().nullable(),
+  opening_balance: model.number().nullable(),
+  closing_balance: model.number().nullable(),
   type: model.text().nullable(),
   image_url: model.text().nullable(),
   remark: model.text().nullable(),

package/src/modules/cms/permissions.ts

@@ -31,4 +31,9 @@ export const CMS_PERMISSIONS: PermissionRegistration[] = [
     description: "View current cash accumulation for a store",
     registered_by: "cms",
   },
+  {
+    key: "cms.reconciliation.read",
+    description: "View daily cash reconciliation report with variance analysis",
+    registered_by: "cms",
+  },
 ]

package/src/modules/cms/services/cms-module-service.ts

@@ -59,11 +59,37 @@ export interface ShiftLogFilters {
   limit?: number
 }
 
+export interface ReconciliationInput {
+  store_id: string
+  /** Calendar date in YYYY-MM-DD format (treated as UTC). */
+  date: string
+  /** Net cash collected from orders for the day. Defaults to 0 when not provided. */
+  net_cash_sales?: number
+}
+
+export interface ReconciliationReport {
+  date: string
+  store_id: string
+  opening_balance: number
+  net_cash_sales: number
+  total_handovers_in: number
+  total_handovers_out: number
+  petty_cash_in: number
+  petty_cash_out: number
+  expected_closing_balance: number
+  closing_balance: number | null
+  cms_balance: number | null
+  variance: number | null
+  is_balanced: boolean | null
+  handovers: unknown[]
+  shift_logs: unknown[]
+}
+
 class CmsModuleService extends MedusaService({
-  CmsHandover,
-  CmsAccumulation,
-  PettyCash,
-  PettyCashTransaction,
+  RetailosCmsHandover: CmsHandover,
+  RetailosCmsAccumulation: CmsAccumulation,
+  RetailosPettyCash: PettyCash,
+  RetailosPettyCashTransaction: PettyCashTransaction,
 }) {
   protected logger_: Logger
 
@@ -80,14 +106,14 @@ class CmsModuleService extends MedusaService({
       throw new Error("[retailos/cms] opening_amount must be >= 0")
     }
 
-    const existing = await this.listCmsAccumulations({ store_id: [store_id] })
+    const existing = await this.listRetailosCmsAccumulations({ store_id: [store_id] })
     if (existing.length === 0) {
-      await this.createCmsAccumulations([{ store_id, cash_in_store: opening_amount }])
+      await this.createRetailosCmsAccumulations([{ store_id, cash_in_store: opening_amount }])
     } else {
-      await this.updateCmsAccumulations([{ id: (existing[0] as any).id, cash_in_store: opening_amount }])
+      await this.updateRetailosCmsAccumulations([{ id: (existing[0] as any).id, cash_in_store: opening_amount }])
     }
 
-    await this.createPettyCashTransactions([{
+    await this.createRetailosPettyCashTransactions([{
       store_id,
       employee_id,
       transaction_type: "open" as TransactionType,
@@ -115,11 +141,11 @@ class CmsModuleService extends MedusaService({
       throw new Error("[retailos/cms] closing_amount must be >= 0")
     }
 
-    const accumulations = await this.listCmsAccumulations({ store_id: [store_id] })
+    const accumulations = await this.listRetailosCmsAccumulations({ store_id: [store_id] })
     const current_cash = accumulations[0] ? (accumulations[0] as any).cash_in_store : 0
     const difference = closing_amount - current_cash
 
-    await this.createPettyCashTransactions([{
+    await this.createRetailosPettyCashTransactions([{
       store_id,
       employee_id,
       transaction_type: "close" as TransactionType,
@@ -147,39 +173,48 @@ class CmsModuleService extends MedusaService({
       throw new Error("[retailos/cms] handover_amount must be >= 0")
     }
 
-    const [created] = await this.createCmsHandovers([{
+    const accumulations = await this.listRetailosCmsAccumulations({ store_id: [store_id] })
+    if (accumulations.length === 0) {
+      throw new Error("[retailos/cms] Day Start must be completed before creating a handover")
+    }
+
+    const opening_balance = (accumulations[0] as any).cash_in_store as number
+
+    let closing_balance = opening_balance
+    if (type === "CR") {
+      closing_balance = opening_balance + handover_amount
+    } else if (type === "DB") {
+      if (handover_amount > opening_balance) {
+        throw new Error(
+          `[retailos/cms] Insufficient cash in store: cannot debit ${handover_amount}, current balance is ${opening_balance}`
+        )
+      }
+      closing_balance = opening_balance - handover_amount
+    }
+
+    const [created] = await this.createRetailosCmsHandovers([{
       store_id,
       employee_id: input.employee_id,
       handover_id: input.handover_id ?? null,
       handover_amount,
-      total_cash: input.total_cash ?? null,
+      total_cash: closing_balance,
+      opening_balance,
+      closing_balance,
       type: type ?? null,
       image_url: input.image_url ?? null,
       remark: input.remark ?? null,
       metadata: input.metadata ?? null,
     }])
 
-    const accumulations = await this.listCmsAccumulations({ store_id: [store_id] })
-    const current = accumulations[0] ? (accumulations[0] as any).cash_in_store : 0
-
-    let updated_cash = current
-    if (type === "CR") {
-      updated_cash = current + handover_amount
-    } else if (type === "DB") {
-      updated_cash = current - handover_amount
-    }
-
-    if (accumulations.length === 0) {
-      await this.createCmsAccumulations([{ store_id, cash_in_store: updated_cash }])
-    } else {
-      await this.updateCmsAccumulations([{ id: (accumulations[0] as any).id, cash_in_store: updated_cash }])
-    }
+    await this.updateRetailosCmsAccumulations([{ id: (accumulations[0] as any).id, cash_in_store: closing_balance }])
 
     this.logger_.info("[retailos/cms] handover created", {
       id: (created as any)?.id,
       store_id,
       handover_amount,
       type,
+      opening_balance,
+      closing_balance,
     })
 
     return created
@@ -191,17 +226,34 @@ class CmsModuleService extends MedusaService({
       throw new Error("[retailos/cms] amount must be > 0")
     }
 
-    const existing = await this.listPettyCashes({ store_id: [store_id] })
+    const existing = await this.listRetailosPettyCashes({ store_id: [store_id] })
     const current_balance = existing[0] ? (existing[0] as any).balance : 0
     const new_balance = current_balance + amount
 
     if (existing.length === 0) {
-      await this.createPettyCashes([{ store_id, balance: new_balance }])
+      await this.createRetailosPettyCashes([{ store_id, balance: new_balance }])
     } else {
-      await this.updatePettyCashes([{ id: (existing[0] as any).id, balance: new_balance }])
+      await this.updateRetailosPettyCashes([{ id: (existing[0] as any).id, balance: new_balance }])
+    }
+
+    // When funded from store cash, deduct the amount from cms_accumulation
+    if (source === "from_petty_cash") {
+      const accumulations = await this.listRetailosCmsAccumulations({ store_id: [store_id] })
+      const current_store_cash = accumulations[0] ? (accumulations[0] as any).cash_in_store : 0
+      const new_store_cash = current_store_cash - amount
+
+      if (accumulations.length === 0) {
+        await this.createRetailosCmsAccumulations([{ store_id, cash_in_store: new_store_cash }])
+      } else {
+        await this.updateRetailosCmsAccumulations([{ id: (accumulations[0] as any).id, cash_in_store: new_store_cash }])
+      }
+
+      this.logger_.info("[retailos/cms] store cash deducted for petty cash transfer", {
+        store_id, amount, new_store_cash,
+      })
     }
 
-    const [tx] = await this.createPettyCashTransactions([{
+    const [tx] = await this.createRetailosPettyCashTransactions([{
       store_id,
       employee_id,
       transaction_type: "petty_cash" as TransactionType,
@@ -230,17 +282,17 @@ class CmsModuleService extends MedusaService({
       throw new Error("[retailos/cms] expense amount must be > 0")
     }
 
-    const existing = await this.listPettyCashes({ store_id: [store_id] })
+    const existing = await this.listRetailosPettyCashes({ store_id: [store_id] })
     const current_balance = existing[0] ? (existing[0] as any).balance : 0
     const new_balance = current_balance - amount
 
     if (existing.length === 0) {
-      await this.createPettyCashes([{ store_id, balance: new_balance }])
+      await this.createRetailosPettyCashes([{ store_id, balance: new_balance }])
     } else {
-      await this.updatePettyCashes([{ id: (existing[0] as any).id, balance: new_balance }])
+      await this.updateRetailosPettyCashes([{ id: (existing[0] as any).id, balance: new_balance }])
     }
 
-    const [tx] = await this.createPettyCashTransactions([{
+    const [tx] = await this.createRetailosPettyCashTransactions([{
       store_id,
       employee_id,
       transaction_type: "petty_cash" as TransactionType,
@@ -264,16 +316,90 @@ class CmsModuleService extends MedusaService({
   }
 
   async getAccumulation(store_id: string) {
-    const rows = await this.listCmsAccumulations({ store_id: [store_id] })
+    const rows = await this.listRetailosCmsAccumulations({ store_id: [store_id] })
     return rows[0] ?? null
   }
 
+  async getReconciliationReport(input: ReconciliationInput): Promise<ReconciliationReport> {
+    const { store_id, date, net_cash_sales = 0 } = input
+
+    const start = new Date(`${date}T00:00:00.000Z`)
+    const end = new Date(`${date}T23:59:59.999Z`)
+    const dateFilter = { $gte: start, $lte: end }
+
+    const txns = await this.listRetailosPettyCashTransactions(
+      { store_id: [store_id], created_at: dateFilter },
+      { take: 1000, order: { created_at: "ASC" } as any }
+    )
+
+    const handovers = await this.listRetailosCmsHandovers(
+      { store_id: [store_id], created_at: dateFilter },
+      { take: 1000, order: { created_at: "ASC" } as any }
+    )
+
+    const accumulation = await this.getAccumulation(store_id)
+
+    const txnList = txns as any[]
+    const handoverList = handovers as any[]
+
+    const openTx = txnList.find((t) => t.transaction_type === "open")
+    const closeTx = txnList.find((t) => t.transaction_type === "close")
+
+    const opening_balance: number = openTx ? openTx.amount : 0
+    const closing_balance: number | null = closeTx ? closeTx.amount : null
+
+    const pettyCashTxns = txnList.filter((t) => t.transaction_type === "petty_cash")
+    const petty_cash_in = pettyCashTxns
+      .filter((t) => t.entry_type === "CR")
+      .reduce((sum: number, t: any) => sum + t.amount, 0)
+    const petty_cash_out = pettyCashTxns
+      .filter((t) => t.entry_type === "DB")
+      .reduce((sum: number, t: any) => sum + t.amount, 0)
+
+    const total_handovers_in = handoverList
+      .filter((h) => h.type === "CR")
+      .reduce((sum: number, h: any) => sum + h.handover_amount, 0)
+    const total_handovers_out = handoverList
+      .filter((h) => h.type === "DB")
+      .reduce((sum: number, h: any) => sum + h.handover_amount, 0)
+
+    const expected_closing_balance =
+      opening_balance + net_cash_sales + petty_cash_in - petty_cash_out + total_handovers_in - total_handovers_out
+
+    const variance = closing_balance !== null ? closing_balance - expected_closing_balance : null
+    const is_balanced = variance !== null ? variance === 0 : null
+
+    const shift_logs = txnList.filter(
+      (t) => t.transaction_type === "open" || t.transaction_type === "close"
+    )
+
+    this.logger_.info("[retailos/cms] reconciliation report generated", { store_id, date })
+
+    return {
+      date,
+      store_id,
+      opening_balance,
+      net_cash_sales,
+      total_handovers_in,
+      total_handovers_out,
+      petty_cash_in,
+      petty_cash_out,
+      expected_closing_balance,
+      closing_balance,
+      cms_balance: accumulation ? (accumulation as any).cash_in_store : null,
+      variance,
+      is_balanced,
+      handovers: handoverList,
+      shift_logs,
+    }
+  }
+
   async getShiftLogs(filters: ShiftLogFilters) {
     const dbFilters: Record<string, unknown> = {}
     if (filters.store_id) dbFilters.store_id = [filters.store_id]
     dbFilters.transaction_type = ["open", "close"]
 
-    const rows = await this.listPettyCashTransactions(dbFilters, {
+    const rows = await this.listRetailosPettyCashTransactions(dbFilters, {
       take: filters.limit ?? 100,
       order: { created_at: "DESC" } as any,
     })