tango-app-api-payment-subscription 3.5.28 → 3.5.30

package/docs/superpowers/specs/2026-07-09-quarterly-invoices-449-design.md

@@ -0,0 +1,108 @@
+# Quarterly Invoice Creation Script — clientId 449 (Apr/May/Jun 2025)
+
+**Date:** 2026-07-09
+**File to create:** `scripts/create-quarterly-invoices-449.js`
+
+## Goal
+
+Create **3 invoices** for clientId `449`, one per billing group, each covering the
+**Apr–Jun 2025 quarter (FY 25-26)** as three per-month line-item blocks. This is a
+one-off backfill of quarterly billing.
+
+Target groups (all confirmed to exist on clientId 449, all INR, all GST prefix `33`):
+
+| Group name                    | _id                        | GST             | stores |
+|-------------------------------|----------------------------|-----------------|--------|
+| LILLE BY CHALLANI             | `6a4f37925d8071b6ae34d1a2` | 33AALCC7452J1ZF | 6      |
+| FEDHA JEWELS PRIVATE LIMITED  | `6a4f37298b8646bec2a1f630` | 33AAFCF8793V1ZL | 7      |
+| CHALLANI JEWELLERY MART       | `6a4f32644cde0c2869be2e52` | 33AAIFC5600Q1ZC | 2      |
+
+Client 449: `priceType: standard`, `status: active`.
+
+## Invoice series & shape
+
+- **Series: `INV-`** (normal series), NOT TINV-. Number format `INV-25-26-NNNNN`,
+  continuing the highest `invoiceIndex` for `^INV-25-26-` (matches controller logic).
+- `advanceInvoice: false`, `advancePeriod` omitted.
+- **One invoice document per group** whose `products` array contains three month-blocks
+  (Apr 2025, May 2025, Jun 2025), each line tagged `month: 'MMM YYYY'`.
+- `advanceMonths: 3` recorded for reference (bundled quarter), but the invoice is a normal
+  INV- invoice — the quarterly nature lives in the line items, not the advance flag.
+- No `storeDetails` block (that is TINV-only in the controller).
+
+## Pricing — actual per-month snapshots, prorated
+
+Client 449 is `priceType: standard`, so we replicate the **standard-price** path from
+`createInvoice` → `standardPrice()`. For each group, for each of Apr/May/Jun 2025:
+
+1. **Snapshot selection:** pick the latest daily-pricing doc with
+   `dateISO <= end-of-month`, sorted `dateISO: -1`, `limit 1` — the actual snapshot for
+   that month (differs from the controller, which always takes the newest snapshot).
+2. **Days basis:** `daysInMonth` of that month (Apr=30, May=31, Jun=30).
+3. **Basepricing doc:** resolved via the same rule as `resolveBasePricingScope` —
+   group-wise doc when `client.billingGroupWisePricing` is on AND a group doc exists,
+   else the brand-level doc (`groupId` unset). Read `negotiatePrice` from `standard[]`.
+4. **overallStore products:** filter to `group.stores`, keep `workingdays > 0`, group by
+   (product, workingdays), sum store counts. Prorate:
+   `workingdays >= daysInMonth` → `price * count` (full month);
+   else `(price / daysInMonth) * workingdays * count`. `proRata: 'flat'` on the group
+   forces full-month working days.
+5. **billingType** perZone / perCamera for `tangoZone` / `tangoTraffic`: multiply by zone
+   / camera counts exactly as the controller does.
+6. **billingMethod `eachStore`** products: emit one line per store (per-store proration),
+   as in the controller.
+7. Tag every produced line with `month: 'MMM YYYY'` for that month.
+
+The three months' line arrays are concatenated into the single `products` array.
+
+**Empty-month handling:** if a month has no snapshot `<=` its end, or the group has no
+running stores that month, that month contributes zero lines. The script logs this
+**loudly** (WARN per group/month) so a short invoice is never produced silently.
+
+## Invoice document fields (mirrors controller `data`)
+
+- `invoice: INV-25-26-NNNNN`, `invoiceIndex`
+- `groupId`, `groupName`, `clientId: '449'`
+- `companyName` = uppercased `registeredCompanyName`; `companyAddress` built from group
+  address fields (`addressLineOne+addressLineTwo+city,state,country -pinCode`), matching
+  the controller
+- `GSTNumber` = group.gst, `PlaceOfSupply` = group.placeOfSupply
+- `products` = concatenated month-blocks
+- `amount` = Σ line amounts (roundAmount, inr); `tax` = CGST 9% + SGST 9% (GST prefix `33`);
+  `totalAmount` = roundAmount(amount + tax)
+- `currency: 'inr'`, `stores` = running-store count from the latest snapshot within Jun 2025
+- `billingDate` = today (creation date, per controller convention), `monthOfbilling: '04'`
+- `dueDate` = billingDate + (group.paymentTerm || 30) days
+- `status: 'pendingCsm'`, `paymentStatus: 'unpaid'`, `paymentMethod: 'Online'`
+- `advanceInvoice: false`, `advanceMonths: 3`
+
+## Number allocation across the 3 invoices
+
+Compute the starting index once (max `invoiceIndex` for `^INV-25-26-`), then increment
+locally per group so the three invoices get consecutive numbers within one run. In
+dry-run, the numbers shown are provisional (no write, so the counter is not advanced).
+
+## Safety & idempotency
+
+- **Dry-run by default.** Prints, per group: invoice number, per-month per-product
+  breakdown (product, storeCount, price, working-days/period, amount), subtotal, CGST,
+  SGST, total, and any empty-month WARNs. Writes nothing.
+- **`--apply`** performs the inserts via `invoiceModel.create`.
+- **Duplicate guard:** before creating a group's invoice, check for an existing
+  `INV-`-series invoice for that `groupId` already carrying a `products.month = 'Apr 2025'`
+  line. If found, SKIP that group with a warning (prevents double-billing on re-run).
+- **No side effects:** no PDF, no email, no OpenSearch activity log, no PO mapping.
+- **Connection:** reuse `getConnection()` from `config/database/database.js` (or
+  `MONGO_URI` override), and the `tango-api-schema` models — same as existing scripts.
+
+## Flags
+
+- `node scripts/create-quarterly-invoices-449.js` → DRY RUN
+- `node scripts/create-quarterly-invoices-449.js --apply` → write
+- `--clientId=449` (default 449), `--year=2025` (Q1 = Apr/May/Jun of this calendar year;
+  FY label derived as `YY-(YY+1)`)
+
+## Out of scope
+
+TINV/advance series, multi-client support, PDF/email generation, non-standard (step)
+pricing beyond what `standardPrice` covers for this client.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.28",
+    "version": "3.5.30",
     "description": "paymentSubscription",
     "main": "index.js",
     "type": "module",
@@ -29,7 +29,7 @@
         "nodemon": "^3.1.0",
         "puppeteer": "^24.41.0",
         "swagger-ui-express": "^5.0.0",
-        "tango-api-schema": "^2.6.43",
+        "tango-api-schema": "^2.6.46",
         "tango-app-api-middleware": "^3.6.18",
         "winston": "^3.12.0",
         "winston-daily-rotate-file": "^5.0.0",

package/src/controllers/brandsBilling.controller.js

@@ -641,6 +641,13 @@ export async function brandInvoiceList( req, res ) {
       if ( inv.paymentStatus === 'paid' ) {
         continue;
       }
+      // Only invoices with a real (generated) invoice number count toward the
+      // Outstanding / Overdue / Pending Payment cards. Pre-finance drafts carry
+      // a temporary DRAFT- number and must be excluded until the real INV/TINV
+      // number is minted at finance approval.
+      if ( String( inv.invoice || '' ).startsWith( 'DRAFT-' ) ) {
+        continue;
+      }
       const excl = toInr( inv, inv.amount );
       const incl = toInr( inv, inv.totalAmount || inv.amount );
       cards.outstandingExclAmount += excl;
@@ -2042,6 +2049,14 @@ export async function billingSummary( req, res ) {
       { $match: {
         status: 'approved',
         paymentStatus: { $in: [ 'unpaid', 'partial', 'due' ] },
+        // Outstanding aging counts only regular invoices. Advance invoices use
+        // the separate TINV- series (quarterly/half-yearly/yearly) and must be
+        // excluded so their balances don't inflate the aging buckets/outstanding
+        // total. Matches the invoice-list 'all' filter idiom. A missing invoice
+        // # is treated as a regular invoice.
+        $expr: { $not: { $regexMatch: {
+          input: { $ifNull: [ '$invoice', '' ] }, regex: '^TINV-',
+        } } },
       } },
       { $addFields: {
         dueDateD: { $cond: [