feat(api): add customer accounts with live summary and append-only ledger

One balance row per (user, kind, currency): available and frozen carry the
platform base currency, points carries none. Monetary and points rows use
separate partial unique indexes because a plain UNIQUE lets NULL repeat.

Balance changes go through transactional primitives that debits guard with a
conditional update, credits add atomically, and freeze/release move both sides
in one transaction after locking rows by primary key. Every change appends an
immutable entry holding its resulting balance. Registration and a migration
backfill create the zero rows; GET /api/me/stats is the only public surface and
no endpoint mutates a balance.

The mall buyer center and points page drop the USER_STATS fixture for the
shared contract; the fixture stays exported so the fixed-data adapter can still
serve the account domain as a rollback path.

Implements openspec change add-customer-accounts.

apps/mall/mock/api.ts

@@ -4,6 +4,7 @@
 
 import { ApiError } from "@vmall/shared";
 import type {
+  AccountSummary,
   Address,
   AddressBookEntry,
   AddressInput,
@@ -30,6 +31,7 @@ import {
   MOCK_QUICK_LINKS,
   MOCK_STORES,
   MOCK_USER,
+  USER_STATS,
   MOCK_ADDRESSES,
   defaultAddress,
   mockConvertMinor,
@@ -179,6 +181,13 @@ export function createMockApi(): ApiClient {
     register: () => Promise.resolve(tokens()),
     login: () => Promise.resolve(tokens()),
     me: (): Promise<User> => Promise.resolve(MOCK_USER),
+    getAccountSummary: (): Promise<AccountSummary> =>
+      Promise.resolve({
+        balance_minor: USER_STATS.balanceMinor,
+        frozen_minor: USER_STATS.frozenMinor,
+        currency: BASE_CURRENCY,
+        points: USER_STATS.points,
+      }),
 
     listProducts: (q = {}) =>
       Promise.resolve(

apps/mall/nuxt.config.ts

@@ -9,7 +9,7 @@ export default defineNuxtConfig({
       // Domains served by the live backend; every other domain stays on the
       // fixed-data adapter. Override with NUXT_PUBLIC_LIVE_DOMAINS='["catalog"]'.
       // See openspec/changes/replace-mock-api-wave-1/design.md and waves 2-3.
-      liveDomains: ["catalog", "currency", "content", "shops", "brands", "auth", "cart", "orders", "shipments", "invoices", "addresses"],
+      liveDomains: ["catalog", "currency", "content", "shops", "brands", "auth", "account", "cart", "orders", "shipments", "invoices", "addresses"],
       appName: "mall",
     },
   },

apps/mall/pages/integral.vue

@@ -1,11 +1,28 @@
 <script setup lang="ts">
+import type { AccountSummary } from "@vmall/shared";
 import { t as pick } from "@vmall/shared";
-import { INTEGRAL_PRODUCTS, USER_STATS } from "~/mock/data";
+// The catalog stays on fixtures until the points-mall change lands; the points
+// balance itself is live.
+import { INTEGRAL_PRODUCTS } from "~/mock/data";
 
 const { locale, t } = useI18n();
+const { $api } = useNuxtApp();
 const session = useSessionStore();
+const stats = ref<AccountSummary | null>(null);
 const redeemed = ref<Set<string>>(new Set());
 
+async function loadStats(): Promise<void> {
+  if (!session.isLoggedIn) {
+    stats.value = null;
+    return;
+  }
+  try {
+    stats.value = await $api.getAccountSummary();
+  } catch {
+    stats.value = null;
+  }
+}
+
 const breadcrumb = computed(() => [
   { label: t("stores.breadcrumbHome"), to: "/" },
   { label: t("marketing.integralBreadcrumb") },
@@ -19,7 +36,10 @@ function isRedeemed(id: string): boolean {
   return redeemed.value.has(id);
 }
 
-onMounted(() => session.hydrate());
+onMounted(() => {
+  session.hydrate();
+  void loadStats();
+});
 </script>
 
 <template>
@@ -35,7 +55,7 @@ onMounted(() => session.hydrate());
             <div>
               <p class="account-name">{{ session.user?.display_name }}</p>
               <p class="points-label">{{ t("marketing.pointsBalance") }}</p>
-              <strong class="account-points">{{ USER_STATS.points }}</strong>
+              <strong class="account-points">{{ stats ? stats.points : t("common.loading") }}</strong>
             </div>
           </template>
           <template v-else>

apps/mall/pages/user/index.vue

@@ -1,13 +1,14 @@
 <script setup lang="ts">
-import type { Order, Product } from "@vmall/shared";
+import type { AccountSummary, Order, Product } from "@vmall/shared";
 import { t as pick } from "@vmall/shared";
-import { MOCK_FAVORITES, USER_STATS, lowestSku, productById } from "~/mock/data";
+import { MOCK_FAVORITES, lowestSku, productById } from "~/mock/data";
 
 definePageMeta({ middleware: "auth" });
 
 const { locale, t } = useI18n();
 const { $api } = useNuxtApp();
 const orders = ref<Order[]>([]);
+const stats = ref<AccountSummary | null>(null);
 const loading = ref(true);
 
 async function loadOrders(): Promise<void> {
@@ -20,8 +21,18 @@ async function loadOrders(): Promise<void> {
   }
 }
 
+// Live balances; shows a placeholder rather than a fixture if the call fails.
+async function loadStats(): Promise<void> {
+  try {
+    stats.value = await $api.getAccountSummary();
+  } catch {
+    stats.value = null;
+  }
+}
+
 onMounted(() => {
   void loadOrders();
+  void loadStats();
 });
 
 const counts = computed(() => ({
@@ -62,15 +73,17 @@ const favoriteProducts = computed(() =>
       <div class="stats-grid">
         <div class="stat-card">
           <span>{{ t("user.statsBalance") }}</span>
-          <strong><PriceText :amount-minor="USER_STATS.balanceMinor" currency="USD" /></strong>
+          <strong v-if="stats"><PriceText :amount-minor="stats.balance_minor" :currency="stats.currency" /></strong>
+          <strong v-else>{{ t("common.loading") }}</strong>
         </div>
         <div class="stat-card">
           <span>{{ t("user.statsPoints") }}</span>
-          <strong>{{ USER_STATS.points }}</strong>
+          <strong>{{ stats ? stats.points : t("common.loading") }}</strong>
         </div>
         <div class="stat-card">
           <span>{{ t("user.statsFrozen") }}</span>
-          <strong><PriceText :amount-minor="USER_STATS.frozenMinor" currency="USD" /></strong>
+          <strong v-if="stats"><PriceText :amount-minor="stats.frozen_minor" :currency="stats.currency" /></strong>
+          <strong v-else>{{ t("common.loading") }}</strong>
         </div>
       </div>
       <div class="status-links">

apps/mall/plugins/api.ts

@@ -9,6 +9,7 @@ import { createMockApi } from "~/mock/api";
  */
 type LiveDomain =
   | "auth"
+  | "account"
   | "catalog"
   | "currency"
   | "content"
@@ -27,6 +28,7 @@ type LiveDomain =
  */
 const LIVE_PICKS = {
   auth: (a: ApiClient) => ({ register: a.register, login: a.login, me: a.me }),
+  account: (a: ApiClient) => ({ getAccountSummary: a.getAccountSummary }),
   catalog: (a: ApiClient) => ({
     listProducts: a.listProducts,
     getProduct: a.getProduct,
@@ -76,6 +78,7 @@ const DEFAULT_LIVE_DOMAINS: LiveDomain[] = [
   "shops",
   "brands",
   "auth",
+  "account",
   "cart",
   "orders",
   "shipments",