james
ce3e8db5b1
Wave 6, the last substantive piece of the mock-API migration. Wave 1 removed the brand facet and the sales/comments sorts for want of a model; sales turn out to be derivable from order_items and a brand model is a table plus a column. - a `brands` table with a nullable `products.brand_id` and an ordered admin replace, mirroring categories and storefront content; a public `GET /api/brands` and a `brand_id` filter on the catalog, which the search page's facet uses - `sold_count` per product, computed from `order_items` joined to orders that reached payment, so an abandoned or cancelled checkout cannot count as a sale. It is computed per read rather than stored, so it cannot drift from the orders that produced it - `sort=sales` alongside `sort=price`; anything else is still a 400 - merchants can set a product's brand through the existing product upsert - the review UI is gone: the card's review figure and the product detail page's reviews tab, summary and replies. There is no reviews model, and the mall attributed invented comments to named shoppers and showed a "good rate". The now-unreferenced fabrication helpers went with it (`salesOf`, `commentCountOf`, `commentsFor`, `commentStats`, `salesRankFor`, `productDetail`, `storeDetail`) Two bugs found by checking rather than trusting: the fixed-data `listProducts` had silently ignored `brand_id`, `sort` and `order`, so the restored facet rendered but filtered nothing until the rollback check caught it; and the seed's brand lookup read back through the shared `r` variable the product loop reassigns, working once and then throwing. Verified: 29 backend tests green including a new brand-and-sales case; all three frontends build; searching filters by brand (24 to 6) and sorts by sales with counts matching the API; a product page offers detail and after-sale tabs only, with a real sold count; the fixed-data rollback filters by brand too. OpenSpec change: openspec/changes/replace-mock-api-wave-6
VMall — B2B2C 商城 MVP
前后端分离的多商户（B2B2C）商城。一个 Rust 后端，三个 Nuxt 前端，Postgres + Redis（本地 Docker 提供），OpenSpec 驱动开发。
架构
apps/
api/ Rust 后端（axum 0.8 + sqlx + redis） http://localhost:8080/api
mall/ Nuxt 3 顾客商城 http://localhost:3000
shop-admin/ Nuxt 3 商户后台 http://localhost:3001
admin/ Nuxt 3 平台后台 http://localhost:3002
packages/
shared/ @vmall/shared：TS 类型、API client、en/zh 语言包、共享样式
openspec/ OpenSpec 规范（specs/ 为归档后的能力规范）
scripts/
seed-demo.mjs 演示数据脚本
技术要点：
- 金额：整数最小单位（minor units）+ ISO 币种码存储，禁止浮点。
rate_to_base表示"1 基准币 = N 本币"，换算四舍五入（half-up）。 - 多语言：商品/店铺/分类/币种内容以 JSONB
{"en","zh"}存储；UI 文案在@vmall/sharedlocales + 各应用locales-extra.ts。 - RBAC：
platform_admin、shop_owner、shop_staff（带 shop_id 作用域）、customer；JWT（24h）。 - 下单：Redis 购物车 → 单事务结算，按店铺拆单，价格快照 + 扣库存；缺货整单 409 回滚；取消恢复库存。
- 发货单：支持部分发货（校验剩余量），状态联动 fulfilling → shipped → completed。
- 发票：每单最多一张有效发票；企业发票必填税号；商户开具生成发票号。
快速开始
前置：Docker 中的 Postgres（容器 pg18，postgres/postgres）与 Redis（容器 rdb8）已运行；Rust 1.98+、Node 22+、pnpm 10+。
# 1. 数据库（只需一次）
docker exec pg18 psql -U postgres -c "CREATE DATABASE vmall;" -c "CREATE DATABASE vmall_test;"
# 2. 安装依赖
pnpm install
# 3. 启动后端（自动执行 sqlx 迁移并播种平台管理员）
cargo run -p vmall-api
# 4. 播种演示数据（店铺、店主、4 个双语商品）
node scripts/seed-demo.mjs
# 5. 启动前端（另开终端）
pnpm dev:mall # :3000
pnpm dev:shop-admin # :3001
pnpm dev:admin # :3002
演示账号：
| 角色 | 账号 | 密码 | 应用 |
|---|---|---|---|
| 平台管理员 | admin@vmall.local | admin1234 | admin :3002 |
| 店主 | shop@vmall.local | shop12345 | shop-admin :3001 |
| 顾客 | customer@vmall.local | customer123 | mall :3000 |
测试与校验
cargo test -p vmall-api # 16 个集成测试（vmall_test + Redis）
pnpm --filter @vmall/mall build # 各前端构建即类型校验
pnpm --filter @vmall/shop-admin build
pnpm --filter @vmall/admin build
openspec validate --all --strict # 规范校验
环境变量（后端）
| 变量 | 默认值 |
|---|---|
DATABASE_URL |
postgres://postgres:postgres@127.0.0.1:5432/vmall |
REDIS_URL |
redis://127.0.0.1:6379/ |
JWT_SECRET |
vmall-dev-secret-change-me |
PORT |
8080 |
JWT_TTL_SECS |
86400 |