vmall/README.md

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
  mobile/       Nuxt 3 移动 H5 商城                      http://localhost:3003
packages/
  shared/       @vmall/shared：TS 类型、API client、en/zh 语言包、共享样式
openspec/       OpenSpec 规范（specs/ 为归档后的能力规范）
docs/adr/       Architecture Decision Records（英文）
docs/tech-specs/ 内部技术规格（英文）
scripts/
  seed-demo.mjs 演示数据脚本

技术要点：

• 金额：整数最小单位（minor units）+ ISO 币种码存储，禁止浮点。rate_to_base 表示"1 基准币 = N 本币"，换算四舍五入（half-up）。
• 多语言：商品/店铺/分类/币种内容以 JSONB {"en","zh"} 存储；UI 文案在 @vmall/shared locales + 各应用 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
pnpm --filter @vmall/mobile dev   # :3003

演示账号：

角色	账号	密码	应用
平台管理员	admin@vmall.local	admin1234	admin :3002
店主	shop@vmall.local	shop12345	shop-admin :3001
顾客	customer@vmall.local	customer123	mall :3000

测试与校验

cargo test -p vmall-api        # 29 个集成测试（vmall_test + Redis）
pnpm --filter @vmall/mall build       # 打包；注意：并不做类型校验
pnpm --filter @vmall/shop-admin build
pnpm --filter @vmall/admin build
openspec validate --all --strict      # 规范校验

nuxt build 不做类型校验：nuxt.config.ts 未开启 typescript.typeCheck，也未安装 vue-tsc。构建通过只说明能打包。要补上这道关：加 vue-tsc + typescript 依赖、设 typescript: { typeCheck: true }，首次运行会暴露一批既有错误。在那之前，能证明页面可用的是浏览器实测，而不是构建。

商城的 mock 边界

apps/mall 通过 apps/mall/plugins/api.ts 的 liveDomains 按域选择适配器。当前真实后端域包括 catalog、currency、content、brands、shops、auth、account、cart、orders、shipments、invoices、 addresses、coupons、points、flashSales、groupBuying、favorites、aftersales、reviews、wallet、 merchantOnboarding、membership、messaging。

merchantOnboarding 是商家入驻域：只有 submitMerchantApplication 与 getMyMerchantApplications 两个方法走真实后端（admin 侧审核方法由 apps/admin 直接调用， mall 不使用）；把该域从 liveDomains 移除即回落到 apps/mall/mock/api.ts 的确定性 fixture。 membership（getMembership/listGrowthLogs）与 messaging（消息列表、已读、全部已读、删除、 未读数）同理各自独立可回滚；messaging 的未读数由页头徽标消费。

仍由页面直接读取 ~/mock/data 的能力记录在 docs/TBD-marketing.md。营销 fixture 仍由 fixed-data 适配器使用，作为每个已迁移域的回滚实现。

• fixed-data 适配器本身:Mock API adapter 规范要求它仍能服务每个域，因此它是回滚路径，删除它会破坏回滚。

环境变量（后端）

变量	默认值
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
VMALL_PAYMENT_ENVIRONMENT	demo（demo/sandbox/live，部署期固定，API 不可改）
VMALL_PAYMENT_MALL_ORIGIN / VMALL_PAYMENT_MOBILE_ORIGIN	无；Stripe 跳转回流的商城/移动端源，仅允许配置值，钱包支付不需要
VMALL_PAYMENT_STRIPE_API_VERSION	2025-08-27.basil
VMALL_PAYMENT_STRIPE_API_BASE	Stripe 固定主机；非 live 仅允许 loopback 覆盖（测试 fixture）
VMALL_PAYMENT_WORKER_ENABLED / VMALL_PAYMENT_WORKER_POLL_MS	true / 默认轮询间隔
VMALL_PAYMENT_*（其余）	支付渠道密钥引用白名单：渠道只存引用名，密钥本体只从匹配 VMALL_PAYMENT_[A-Z0-9_]* 的环境变量解析，永不入库或出现在审计中

支付要点：demo 环境启用演示充值并拒绝外部渠道；sandbox/live 需要独立的空数据库且无任何 demo 账务历史，否则启动拒绝。Stripe Webhook 端点为 POST /api/payments/webhooks/stripe/{channel_id}（原始请求体验签）。