Files

T

james 9904696e76 feat: wave 2 migration (P3, P5, P7 openspec changes)

Implements, verifies, and archives the three remaining Wave 2 changes from
openspec/MIGRATION-PLAN.md.

- add-wallet-settlement (P3): demo recharge, guarded withdrawal freeze and
  one-time admin review, paginated own fund entries, idempotent per-shop
  weekly/monthly settlement statements with commission rate and one-time
  payout confirmation.
- add-merchant-onboarding (P5): personal/enterprise applications with one live
  application per user, guarded review with mandatory rejection reason, and
  transactional shop + owner provisioning returning one-time credentials;
  mall onboarding/status pages and an admin review console.
- add-membership-messaging (P7): platform member levels, append-only growth
  accrual on order completion with guarded one-way leveling, order/shipment/
  refund system messages with unread/read state and soft deletion, plus the
  mall header unread badge.

Backend: migrations 0019-0023, new wallet, settlement, merchant_onboarding,
membership and messaging modules, event hooks in order/fulfillment/aftersale,
and integration suites for each. Shared contract extended and all three
frontends updated; code indexes, domain docs, backend guidelines and the
migration tracker synced.

Verification: cargo test -p vmall-api green twice consecutively; mall, admin
and shop-admin builds pass; browser smoke on every new surface; openspec
validate --all --strict green (33 passed).

The three changes share the @vmall/shared contract, the mall mock adapter and
per-app locale/nav files, so they are committed together to keep every commit
buildable.

2026-09-25 15:25:29 +00:00

4.7 KiB

Raw Blame History

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/ 为归档后的能力规范）
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

演示账号：

角色	账号	密码	应用
平台管理员	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`

4.7 KiB Raw Blame History Unescape Escape