@mohasinac/appkit 4.43.0 → 4.44.0

package/dist/features/products/repository/products.repository.d.ts

@@ -45,8 +45,123 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
      * (Root Cause #6/#18) — a raw collection read has neither problem.
      */
     private deriveTaxonomy;
+    /**
+     * Resolve the GST rate floor, and gross up an ex-tax price if the seller
+     * authors that way.
+     *
+     * ## The rate resolution order, in full
+     *
+     *  1. the product's own `gstRate`, if a human set one — including `0`, a
+     *     deliberate exemption;
+     *  2. the CATEGORY's rate via `taxCodeId` → `taxCodes`, applied just above
+     *     by `applyCategoryDefaults`. **This is the mechanism**, and the ~330-node
+     *     forest carries a tax code on every listing branch, so it answers for
+     *     effectively the whole catalogue;
+     *  3. `DEFAULT_GST_RATE` — a floor, warned about, never a feature.
+     *
+     * 🛑 Step 3 fires only when steps 1 and 2 both came up empty, which means
+     * the category has no tax code — and THAT is the defect to fix. The measure
+     * of success is that this warning never appears. It exists because the
+     * alternative fails asymmetrically: with prices tax-inclusive, treating an
+     * unrated item as 0% hands the seller the full amount and leaves us owing
+     * tax on money already paid out, which is C0's bug in miniature.
+     *
+     * ## The gross-up
+     *
+     * A store with `pricesIncludeGst: false` types EX-TAX prices, so the typed
+     * number is converted ONCE here and stored tax-inclusive like every other
+     * price. No money path branches on the flag; see `taxableFromInclusive`.
+     *
+     * Gated on the write actually carrying a price, so a stock decrement or a
+     * status flip pays nothing for this — the same discipline `update` already
+     * applies to the taxonomy derivation itself.
+     */
+    private applyInclusivePricing;
+    /**
+     * Hand down what the category declares: the tax code, the spec rows, the
+     * in-the-box list, the inherited features and the SEO templates.
+     *
+     * ## 🛑 Why this is server-side and not a form default
+     *
+     * GST is tax CORRECTNESS. A client-side default is bypassable by all ~14
+     * write paths, and the defect this closes is recorded in our own source:
+     * *"0 of 40 live orders had a `gstAmount`, and the order page's Tax row had
+     * never rendered."* The rate has to be applied where every path funnels, and
+     * that is here.
+     *
+     * ## 🛑 The three behaviours are different, and the difference is the design
+     *
+     *   WRITTEN     tax, specifications, inTheBox, features — written when the
+     *               product omits them.
+     *   FILL-BLANK  seo* — fills only an empty field, never overwrites a
+     *               seller's own words.
+     *   ADVISORY    priceGuidance — NEVER touched here. It renders as a hint
+     *               beside the price input and nothing else. Writing a suggested
+     *               price onto `price` would be the platform setting a seller's
+     *               price, which is not a default, it is a decision.
+     *
+     * ## 🛑 Resolution is PER FIELD across the ancestor chain
+     *
+     * Not "the nearest category that declares a `productDefaults` object wins".
+     * B5's named-model leaves carry `defaultFeatures` (the blader, the battle
+     * type, the spin) while the tax code, the spec rows and the price band live
+     * on the tier-3 LINE above them. An object-level "nearest wins" would hand a
+     * Dragoon G its blader and NO TAX CODE — silently deriving no GST, which is
+     * the quiet under-charging failure the whole tax-code indirection exists to
+     * prevent.
+     *
+     * ## Cost
+     *
+     * One `getAll` over at most four ancestors, fired only when the leaf leaves
+     * something unresolved, plus one read for the tax code. With the leaf+brand
+     * read that is three round trips worst case against Rule #6's ~3 budget —
+     * and `update` only re-derives when a write names a taxonomy field, so a
+     * stock decrement or a status flip pays none of it.
+     */
+    private applyCategoryDefaults;
     /** The keys whose presence means a write could change the product's taxonomy. */
     private static readonly TAXONOMY_KEYS;
+    /**
+     * Keep `availableQuantity` in step when a seller edits `stockQuantity`.
+     *
+     * 🛑 THE BUG THIS CLOSES: A SELLER COULD NOT RESTOCK.
+     *
+     * There are two stock numbers. `stockQuantity` is seller-authored and is the
+     * only one any of the three product forms exposes. `availableQuantity` is
+     * system-owned, seeded from `stockQuantity` **once, at create**, and
+     * thereafter driven by checkout decrements and timeout restores.
+     *
+     * Nothing re-synced them. `updateProduct` is a bare spread, and grep for
+     * `availableQuantity` across `src/app/api/store/products/**` and
+     * `seller-actions.ts` returns ZERO. So: a product sells out
+     * (`availableQuantity: 0`), the seller edits `stockQuantity` 0 → 10, and the
+     * product STAYS UNBUYABLE — purchasability gates on `availableQuantity > 0`
+     * in three independent places (`service.ts`, the cart route, and the public
+     * list filter). The only field the seller can reach is the one that does not
+     * control availability.
+     *
+     * With 76–93% of competitor catalogues sold out, restock is the main
+     * lifecycle event, not an edge case.
+     *
+     * WHY A DELTA AND NOT `availableQuantity = stockQuantity`: the difference
+     * between the two IS the outstanding reservation — units held by placed-but-
+     * unpaid orders. Overwriting would hand those units back to the shelf and
+     * oversell them. So carry the reservation forward:
+     *
+     *     reserved = prevStock - prevAvailable        (clamped at 0)
+     *     available = nextStock - reserved            (clamped at 0)
+     *
+     * Examples: 10 stock / 10 available, edit to 12 → 12. 10 stock / 7 available
+     * (3 reserved), edit to 12 → 9. Sold out at 0/0, edit to 10 → 10.
+     *
+     * 🛑 Returns `{}` — not a value — whenever the write does not name
+     * `stockQuantity`, or names `availableQuantity` explicitly. The second case
+     * is what keeps the checkout decrement, the stock-restore job and
+     * `updateAvailableQuantity` authoritative: they write `availableQuantity`
+     * directly and must never have it recomputed from a stale `stockQuantity`
+     * underneath them.
+     */
+    private static resyncAvailableQuantity;
     update(id: string, data: Partial<ProductDocument>): Promise<ProductDocument>;
     create(input: ProductCreateInput): Promise<ProductDocument>;
     findByStore(storeId: string): Promise<ProductDocument[]>;
@@ -403,7 +518,6 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
         categoriesIn?: string[];
         brandName?: string;
     }): Promise<Record<string, number | undefined>>;
-    incrementViewCount(productId: string): Promise<void>;
     /**
      * Cloud Functions: find published auctions whose end date has already passed.
      * Used by the auction settlement job to finalize expired auctions.