feat(mall): read the store directory from the API

Wave 5: the store directory, store home and product-page store card stop reading
MOCK_STORES, and the payment and order surfaces name their shop.

- a `shop_profiles` table beside `shops`, so the identity model both consoles
  consume is untouched, with a public `GET /api/shops` and `GET /api/shops/{slug}`
  and an admin `PUT /api/admin/shops/{id}/profile`
- a shop with no profile is still listed, with the fields absent rather than
  invented; the pages guard every block, and a missing logo renders an
  initial-letter placeholder
- `scripts/seed-demo.mjs` upserts a profile per demo shop, since profiles hang
  off shops that script creates
- payment and order pages resolve shop ids to names from one cached shop read,
  retiring the generic "Shop" label
- three things went rather than being faked, following the wave-1 precedent:
  `distanceKm` and its sort (no geo model), the store home's sales/comments
  sorts, and its "best sellers" rail (no sales model)
- `lowestSku` moved out of the fixed-data module into `apps/mall/utils/product.ts`
  and re-exported, so live pages stop importing the mock module for a pure
  helper

Verified: 28 backend tests green including five new shop tests; all three
frontends build; the directory, store home, store card and order cards all render
real data with no distance or sales claims; the fixed-data rollback still renders
the store surfaces with the backend stopped.

Note: `nuxt build` does not typecheck in this repo (no `typescript.typeCheck`,
no `vue-tsc`), which AGENTS.md implies it does. A re-export used here created no
local binding and broke internal callers at runtime while the build stayed green;
`docs/TBD-migrate-wave.md` records the gap.

OpenSpec change: openspec/changes/replace-mock-api-wave-5

apps/mall/pages/checkout/pay.vue

@@ -9,6 +9,13 @@ const { locale, t } = useI18n();
 const { currency } = usePrefs();
 const router = useRouter();
 const pendingOrderIds = useState<string[]>("checkout-orders", () => []);
+// Shared with the store directory; orders carry only a shop id.
+const { data: shops } = await useAsyncData("shops", () => $api.listShops(), { default: () => [] });
+
+function shopName(shopId: string): string {
+  const shop = shops.value.find((entry) => entry.id === shopId);
+  return shop ? pick(shop.name, locale.value) : t("checkout.shop");
+}
 
 const orders = ref<Order[]>([]);
 const paymentMethod = ref("balance");
@@ -85,8 +92,7 @@ onMounted(() => void loadOrders());
           <article v-for="order in orders" :key="order.id" class="mpanel order-card">
             <header class="order-heading">
               <span>{{ t("checkout.orderNo") }}: {{ order.order_no }}</span>
-              <!-- Store names need the public store read; see docs/TBD-migrate-wave.md. -->
-              <span class="shop-name">{{ t("checkout.shop") }}</span>
+              <span class="shop-name">{{ shopName(order.shop_id) }}</span>
             </header>
             <div v-for="item in order.items" :key="item.id" class="order-item">
               <img :src="imageFor(item.image)" :alt="pick(item.product_name, locale)" />

apps/mall/pages/goods/[id].vue

@@ -2,15 +2,8 @@
 import { t as pick } from "@vmall/shared";
 import { ApiError } from "@vmall/shared";
 import type { Category, Product, Sku } from "@vmall/shared";
-import {
-  MOCK_COUPONS,
-  MOCK_STORES,
-  commentStats,
-  commentsFor,
-  lowestSku,
-  salesOf,
-  storeById,
-} from "~/mock/data";
+import { MOCK_COUPONS, commentStats, commentsFor, salesOf } from "~/mock/data";
+import { lowestSku } from "~/utils/product";
 import { useCartStore } from "~/stores/cart";
 
 type AttributeGroup = { key: string; values: string[] };
@@ -51,12 +44,16 @@ const { data: pageData } = await useAsyncData(
 const product = computed(() => pageData.value?.product ?? null);
 const related = computed<Product[]>(() => pageData.value?.related ?? []);
 
+// Shared with the store directory and the order surfaces.
+const { data: shops } = await useAsyncData("shops", () => $api.listShops(), { default: () => [] });
+
 const detail = computed(() => {
   const current = product.value;
   if (!current) return null;
   return {
     product: current,
-    store: storeById(current.shop_id) ?? MOCK_STORES[0],
+    // Null when the shop has no public profile; the card is then not rendered.
+    store: shops.value.find((shop) => shop.id === current.shop_id) ?? null,
     comments: commentsFor(current.id),
     commentStats: commentStats(current.id),
     coupons: MOCK_COUPONS,
@@ -183,14 +180,19 @@ const tabs = computed(() => [
   { key: "service", label: t("product.tabsAfterSale") },
 ]);
 
+/** Only the scores the platform actually set; nothing is defaulted. */
 const rateRows = computed(() => {
-  const rate = store.value?.rate;
-  return [
-    { key: "overall", value: rate?.score ?? 0, label: t("product.overall") },
-    { key: "service", value: rate?.service ?? 0, label: t("product.service") },
-    { key: "delivery", value: rate?.speed ?? 0, label: t("product.delivery") },
-    { key: "agree", value: rate?.agree ?? 0, label: t("product.quality") },
+  const profile = store.value;
+  if (!profile) return [];
+  const rows = [
+    { key: "overall", value: profile.score_rating, label: t("product.overall") },
+    { key: "service", value: profile.score_service, label: t("product.service") },
+    { key: "delivery", value: profile.score_speed, label: t("product.delivery") },
+    { key: "agree", value: profile.score_agreement, label: t("product.quality") },
   ];
+  return rows.filter(
+    (row): row is { key: string; value: number; label: string } => typeof row.value === "number",
+  );
 });
 
 const detailImages = computed(() => product.value?.images ?? []);
@@ -283,20 +285,22 @@ const detailImages = computed(() => product.value?.images ?? []);
 
       <section class="below-grid">
         <aside class="left-rail">
-          <div class="store-card mpanel">
+          <div v-if="detail.store" class="store-card mpanel">
             <h2>{{ t("product.store") }}</h2>
             <div class="store-heading">
-              <img :src="detail.store.logo" :alt="pick(detail.store.name, locale)" />
+              <img v-if="detail.store.logo" :src="detail.store.logo" :alt="pick(detail.store.name, locale)" />
               <strong>{{ pick(detail.store.name, locale) }}</strong>
             </div>
             <dl>
-              <div><dt>{{ t("product.company") }}</dt><dd>{{ detail.store.company }}</dd></div>
-              <div><dt>{{ t("product.region") }}</dt><dd>{{ detail.store.region }}</dd></div>
+              <div v-if="detail.store.company"><dt>{{ t("product.company") }}</dt><dd>{{ detail.store.company }}</dd></div>
+              <div v-if="detail.store.region"><dt>{{ t("product.region") }}</dt><dd>{{ detail.store.region }}</dd></div>
             </dl>
-            <h3>{{ t("product.rates") }}</h3>
-            <div v-for="row in rateRows" :key="row.key" class="rate-row">
-              <span>{{ row.label }}</span><UiRatingStars :value="row.value" :size="13" />
-            </div>
+            <template v-if="rateRows.length">
+              <h3>{{ t("product.rates") }}</h3>
+              <div v-for="row in rateRows" :key="row.key" class="rate-row">
+                <span>{{ row.label }}</span><UiRatingStars :value="row.value" :size="13" />
+              </div>
+            </template>
             <div class="store-actions">
               <NuxtLink class="store-button" :to="`/stores/${detail.store.slug}`">{{ t("product.enterStore") }}</NuxtLink>
               <button type="button" class="store-button" disabled>{{ t("product.contact") }}</button>
@@ -336,7 +340,7 @@ const detailImages = computed(() => product.value?.images ?? []);
               </div>
               <div v-else class="service-content">
                 <h2>{{ t("product.tabsAfterSale") }}</h2>
-                <p>{{ pick(detail.store.afterSale, locale) }}</p>
+                <p v-if="detail.store?.after_sale">{{ pick(detail.store.after_sale, locale) }}</p>
               </div>
             </template>
           </UiTabs>

apps/mall/pages/stores/[id].vue

@@ -1,31 +1,48 @@
 <script setup lang="ts">
 import { t as pick } from "@vmall/shared";
-import { lowestSku, salesOf, searchMockProducts, storeDetail } from "~/mock/data";
+import type { Paged, Product } from "@vmall/shared";
+import { lowestSku } from "~/utils/product";
 
 const route = useRoute();
 const { locale, t } = useI18n();
-const storeId = computed(() => {
+const { $api } = useNuxtApp();
+
+const slug = computed(() => {
   const raw = route.params.id;
   return typeof raw === "string" ? raw : raw?.[0] ?? "";
 });
-const detail = computed(() => storeDetail(storeId.value));
-const store = computed(() => detail.value?.store ?? null);
+
+// A rejected read (unknown or suspended slug) leaves this null, which renders
+// the "unknown store" branch rather than an invented profile.
+const { data: shop } = await useAsyncData("shop-profile", () => $api.getShop(slug.value), {
+  watch: [slug],
+  default: () => null,
+});
+const store = computed(() => shop.value);
+
 const favorite = ref(false);
-const sortMode = ref<"default" | "price" | "sales" | "comments">("default");
+// Only sorts the catalog model can answer; sales and comments have no model.
+const sortMode = ref<"default" | "price">("default");
 const sortOrder = ref<"asc" | "desc">("desc");
 const page = ref(1);
 const perPage = 12;
+const emptyPage: Paged<Product> = { items: [], total: 0, page: 1, per_page: perPage };
 
-const productResult = computed(() => {
-  if (!store.value) return { items: [], total: 0, page: 1, per_page: perPage };
-  return searchMockProducts({
-    shopId: store.value.id,
-    sort: sortMode.value,
-    order: sortOrder.value,
-    page: page.value,
-    perPage,
-  });
-});
+const { data: productResult } = await useAsyncData(
+  "shop-products",
+  () => {
+    const current = store.value;
+    if (!current) return Promise.resolve(emptyPage);
+    return $api.listProducts({
+      shop_id: current.id,
+      sort: sortMode.value === "price" ? "price" : undefined,
+      order: sortMode.value === "price" ? sortOrder.value : undefined,
+      page: page.value,
+      per_page: perPage,
+    });
+  },
+  { watch: [store, sortMode, sortOrder, page], default: () => emptyPage },
+);
 
 const breadcrumb = computed(() => [
   { label: t("stores.breadcrumbHome"), to: "/" },
@@ -33,26 +50,28 @@ const breadcrumb = computed(() => [
   { label: store.value ? pick(store.value.name, locale.value) : t("stores.unknownStore") },
 ]);
 
+/** Only the scores the platform actually set; nothing is defaulted. */
 const rateRows = computed(() => {
-  if (!store.value) return [];
-  return [
-    { label: t("stores.score"), value: store.value.rate.score },
-    { label: t("stores.agreement"), value: store.value.rate.agree },
-    { label: t("stores.service"), value: store.value.rate.service },
-    { label: t("stores.speed"), value: store.value.rate.speed },
+  const current = store.value;
+  if (!current) return [];
+  const rows = [
+    { label: t("stores.score"), value: current.score_rating },
+    { label: t("stores.agreement"), value: current.score_agreement },
+    { label: t("stores.service"), value: current.score_service },
+    { label: t("stores.speed"), value: current.score_speed },
   ];
+  return rows.filter((row): row is { label: string; value: number } => typeof row.value === "number");
 });
 
-function priceMinorOf(product: Parameters<typeof lowestSku>[0]): number {
+function priceMinorOf(product: Product): number {
   return lowestSku(product)?.price_minor ?? 0;
 }
 
-function currencyOf(product: Parameters<typeof lowestSku>[0]): string {
+function currencyOf(product: Product): string {
   return lowestSku(product)?.currency ?? "USD";
 }
-const salesRank = computed(() => detail.value?.salesRank ?? []);
 
-function chooseSort(mode: "default" | "price" | "sales" | "comments"): void {
+function chooseSort(mode: "default" | "price"): void {
   if (sortMode.value === mode && mode !== "default") {
     sortOrder.value = sortOrder.value === "asc" ? "desc" : "asc";
   } else {
@@ -67,20 +86,21 @@ function chooseSort(mode: "default" | "price" | "sales" | "comments"): void {
   <div class="store-page">
     <UiBreadcrumb :items="breadcrumb" />
     <template v-if="store">
-      <div class="w1200 store-banner">
+      <div v-if="store.banner" class="w1200 store-banner">
         <img :src="store.banner" :alt="pick(store.name, locale)" />
       </div>
       <div class="w1200 store-layout">
         <aside class="store-rail">
           <section class="mpanel store-card">
             <div class="store-heading">
-              <img :src="store.logo" :alt="pick(store.name, locale)" />
+              <img v-if="store.logo" :src="store.logo" :alt="pick(store.name, locale)" />
+              <span v-else class="store-logo-placeholder" aria-hidden="true">{{ pick(store.name, locale).slice(0, 1) }}</span>
               <div>
                 <h1>{{ pick(store.name, locale) }}</h1>
                 <p>{{ t("stores.positiveRate") }}</p>
               </div>
             </div>
-            <div class="rate-list">
+            <div v-if="rateRows.length" class="rate-list">
               <div v-for="row in rateRows" :key="row.label" class="rate-row">
                 <span>{{ row.label }}</span>
                 <UiRatingStars :value="row.value" :size="13" />
@@ -88,26 +108,24 @@ function chooseSort(mode: "default" | "price" | "sales" | "comments"): void {
               </div>
             </div>
             <dl class="store-info">
-              <div><dt>{{ t("stores.company") }}</dt><dd>{{ store.company }}</dd></div>
-              <div><dt>{{ t("stores.region") }}</dt><dd>{{ store.region }}</dd></div>
-              <div><dt>{{ t("stores.address") }}</dt><dd>{{ pick(store.address, locale) }}</dd></div>
+              <div v-if="store.company"><dt>{{ t("stores.company") }}</dt><dd>{{ store.company }}</dd></div>
+              <div v-if="store.region"><dt>{{ t("stores.region") }}</dt><dd>{{ store.region }}</dd></div>
+              <div v-if="store.address"><dt>{{ t("stores.address") }}</dt><dd>{{ pick(store.address, locale) }}</dd></div>
             </dl>
             <button type="button" class="mbtn favorite-button" :class="{ selected: favorite }" @click="favorite = !favorite">
               {{ favorite ? t("stores.favorited") : t("stores.favorite") }}
             </button>
           </section>
 
-          <section class="mpanel sales-card">
-            <h2 class="rail-title">{{ t("stores.salesRank") }}</h2>
-            <NuxtLink v-for="(product, index) in salesRank" :key="product.id" :to="`/goods/${product.slug}`" class="rank-item">
-              <span class="rank-number">{{ index + 1 }}</span>
-              <img :src="product.images[0]" :alt="pick(product.name, locale)" loading="lazy" />
-              <span class="rank-copy">
-                <span class="rank-name">{{ pick(product.name, locale) }}</span>
-                <span class="rank-sales">{{ t("product.salesCount", { n: salesOf(product) }) }}</span>
-              </span>
-              <span class="rank-price"><PriceText :amount-minor="priceMinorOf(product)" :currency="currencyOf(product)" /></span>
-            </NuxtLink>
+          <section v-if="store.notice || store.after_sale" class="mpanel notice-card">
+            <template v-if="store.notice">
+              <h2 class="rail-title">{{ t("stores.notice") }}</h2>
+              <p>{{ pick(store.notice, locale) }}</p>
+            </template>
+            <template v-if="store.after_sale">
+              <h2 class="rail-title">{{ t("stores.afterSale") }}</h2>
+              <p>{{ pick(store.after_sale, locale) }}</p>
+            </template>
           </section>
         </aside>
 
@@ -117,8 +135,6 @@ function chooseSort(mode: "default" | "price" | "sales" | "comments"): void {
             <div class="product-sorts" role="tablist">
               <button type="button" :class="{ active: sortMode === 'default' }" @click="chooseSort('default')">{{ t("stores.sortDefault") }}</button>
               <button type="button" :class="{ active: sortMode === 'price' }" @click="chooseSort('price')">{{ t("stores.sortPrice") }}</button>
-              <button type="button" :class="{ active: sortMode === 'sales' }" @click="chooseSort('sales')">{{ t("stores.sortSales") }}</button>
-              <button type="button" :class="{ active: sortMode === 'comments' }" @click="chooseSort('comments')">{{ t("stores.sortComments") }}</button>
             </div>
           </header>
           <div v-if="productResult.items.length" class="product-grid">

apps/mall/pages/stores/index.vue

@@ -1,15 +1,12 @@
 <script setup lang="ts">
 import { t as pick } from "@vmall/shared";
-import { MOCK_STORES } from "~/mock/data";
 
 const { locale, t } = useI18n();
-const sortMode = ref<"default" | "distance">("default");
+const { $api } = useNuxtApp();
 
-const stores = computed(() => {
-  const list = [...MOCK_STORES];
-  if (sortMode.value === "distance") list.sort((a, b) => a.distanceKm - b.distanceKm);
-  return list;
-});
+// Shared with the order surfaces, which resolve shop ids to names from it.
+const { data: shops } = await useAsyncData("shops", () => $api.listShops(), { default: () => [] });
+const stores = computed(() => shops.value);
 
 const breadcrumb = computed(() => [
   { label: t("stores.breadcrumbHome"), to: "/" },
@@ -23,40 +20,24 @@ const breadcrumb = computed(() => [
     <section class="w1200 store-directory">
       <header class="sort-row">
         <h1>{{ t("stores.directory") }}</h1>
-        <div class="sort-options" role="tablist">
-          <button
-            type="button"
-            :class="{ active: sortMode === 'default' }"
-            role="tab"
-            :aria-selected="sortMode === 'default'"
-            @click="sortMode = 'default'"
-          >{{ t("stores.sortDefault") }}</button>
-          <button
-            type="button"
-            :class="{ active: sortMode === 'distance' }"
-            role="tab"
-            :aria-selected="sortMode === 'distance'"
-            @click="sortMode = 'distance'"
-          >{{ t("stores.sortDistance") }}</button>
-        </div>
       </header>
 
       <div v-if="stores.length" class="store-list">
         <article v-for="store in stores" :key="store.id" class="store-row hover-lift">
           <NuxtLink :to="`/stores/${store.slug}`" class="store-logo-link">
-            <img class="store-logo" :src="store.logo" :alt="pick(store.name, locale)" loading="lazy" />
+            <img v-if="store.logo" class="store-logo" :src="store.logo" :alt="pick(store.name, locale)" loading="lazy" />
+            <span v-else class="store-logo store-logo-placeholder" aria-hidden="true">{{ pick(store.name, locale).slice(0, 1) }}</span>
           </NuxtLink>
           <div class="store-main">
             <NuxtLink :to="`/stores/${store.slug}`" class="store-name">{{ pick(store.name, locale) }}</NuxtLink>
-            <p class="store-company">{{ store.company }}</p>
-            <p class="store-location">
-              <span>{{ t("stores.region") }}：{{ store.region }}</span>
-              <span>{{ t("stores.address") }}：{{ pick(store.address, locale) }}</span>
+            <p v-if="store.company" class="store-company">{{ store.company }}</p>
+            <p v-if="store.region || store.address" class="store-location">
+              <span v-if="store.region">{{ t("stores.region") }}：{{ store.region }}</span>
+              <span v-if="store.address">{{ t("stores.address") }}：{{ pick(store.address, locale) }}</span>
             </p>
           </div>
           <div class="store-rating">{{ t("stores.positiveRate") }}</div>
           <div class="store-actions">
-            <span class="distance">{{ t("stores.distance", { n: store.distanceKm.toFixed(1) }) }}</span>
             <NuxtLink :to="`/stores/${store.slug}`" class="mbtn red">{{ t("stores.visitStore") }}</NuxtLink>
           </div>
         </article>
@@ -138,6 +119,17 @@ h1 {
   height: 72px;
   object-fit: contain;
 }
+/* A shop with no profile still needs a mark, without inventing a logo. */
+.store-logo-placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--mall-line);
+  color: var(--mall-muted);
+  font-size: 28px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
 .store-main {
   min-width: 0;
   flex: 1;

apps/mall/pages/user/orders/index.vue

@@ -8,8 +8,15 @@ const { locale, t } = useI18n();
 const { $api } = useNuxtApp();
 const route = useRoute();
 
-const activeFilter = ref("all");
-const orders = ref<Order[]>([]);
+// Shared with the store directory; orders carry only a shop id.
+const { data: shops } = await useAsyncData("shops", () => $api.listShops(), { default: () => [] });
+
+function shopName(shopId: string): string {
+  const shop = shops.value.find((entry) => entry.id === shopId);
+  return shop ? pick(shop.name, locale.value) : t("user.shop");
+}
+
+const activeFilter = ref("all");const orders = ref<Order[]>([]);
 const page = ref(1);
 const total = ref(0);
 const perPage = ref(10);
@@ -105,8 +112,7 @@ onMounted(() => {
           <article v-for="order in filteredOrders" :key="order.id" class="order-card">
             <header class="order-header">
               <div>
-                <!-- Store names need the public store read; see docs/TBD-migrate-wave.md. -->
-                <strong>{{ t("user.shop") }}</strong>
+                <strong>{{ shopName(order.shop_id) }}</strong>
                 <span>{{ t("user.orderNo") }} {{ order.order_no }}</span>
                 <span>{{ t("user.createdAt") }} {{ order.created_at.slice(0, 10) }}</span>
               </div>