From 997c312cda350d14e8d7586750fc37b775505070 Mon Sep 17 00:00:00 2001 From: Chengdong Zhang Date: Thu, 17 Sep 2026 13:52:20 +0800 Subject: [PATCH] docs: add README and AGENTS guide --- AGENTS.md | 41 +++++++++++++++++++++++++++++ README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 AGENTS.md create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2ccc3a8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md — 给编码代理的指引 + +本仓库是 VMall B2B2C 商城 MVP（pnpm + Cargo 双 workspace）。改动前先读本文件与 `README.md`；功能变更须同步 OpenSpec。 + +## 布局与所有权 + +- `apps/api` — Rust 后端（crate `vmall-api`）。迁移在 `apps/api/migrations/`（sqlx，启动时自动执行，只增不改）。 +- `apps/mall` / `apps/shop-admin` / `apps/admin` — 三个 Nuxt 3 应用。端口固定 3000/3001/3002。 +- `packages/shared` — `@vmall/shared`：**唯一** API 契约（`src/types.ts` + `src/api.ts`）、en/zh 语言包、共享样式 `ui.css`。前端禁止自建 API 封装；契约变更只在这里改，且三个前端都要过构建。 +- `openspec/` — 规范。`specs/` 是已归档能力规范（auth, rbac, catalog, currency, cart, order, shipment, invoice, frontend-*）。 +- `scripts/seed-demo.mjs` — 幂等演示数据。 + +## 硬性约定 + +- **金额**：`i64`/`number` 最小单位 + 币种码；换算走后端 `/api/currencies/convert` 或共享 `formatMoney(minor, code, exponent, locale)`。**禁止浮点金额运算**，禁止在前端硬编码 exponent=2（JPY 是 0）——用币种表里的 exponent。 +- **i18n 内容**：凡是面向用户的内容字段都是 `{"en","zh"}` JSONB；UI 文案一律 `$t()`，缺键加到本应用的 `locales-extra.ts`，**不要**从应用代理改 `packages/shared` 语言包以外的文件（共享包改动属契约变更，需谨慎并跑齐三个构建）。 +- **TS 纪律**：禁止 `any`/`as any`/`@ts-ignore`；外部数据用类型守卫或 schema 校验；客户端方法类型在 `@vmall/shared` 命名导出。 +- **Rust 纪律**：错误统一 `ApiError`（`{"error":{"code","message"}}`）；SQL 用 `sqlx::query*` + 显式 bind；状态迁移必须校验前置状态（参考 orders/shipments 的 `UPDATE ... WHERE status = ...` 模式）。 +- **RBAC**：受保护路由声明角色（`auth.require(&[...])`）；店铺资源必须过 `auth.own_shop()` 作用域，跨店返回 404。 + +## 开发流程（OpenSpec） + +1. 新能力/行为变更：在 `openspec/changes//` 建 `proposal.md` + `tasks.md` + `specs//spec.md`（`## ADDED Requirements` / `### Requirement:` / `#### Scenario:` 格式），`openspec change validate --strict` 必须通过。 +2. 按 tasks 实现；完成后勾选并 `openspec archive --yes`；归档后 `openspec validate --all --strict` 保持全绿。 +3. 只改文档/样式/重构可不建 change。 + +## 验证（交付前必跑） + +```bash +cargo test -p vmall-api # 集成测试连 docker 的 vmall_test + Redis，须全绿且可重复运行（测试夹具 slug 已唯一化，勿改回固定 slug） +pnpm --filter @vmall/<改动过的前端> build +``` + +- 修 bug：先复现，修完确认复现不再触发；有价值的场景补成集成测试（放 `apps/api/tests/`，复用 `tests/common/mod.rs` 夹具）。 +- UI 变更：起 dev server 用浏览器实际点一遍改动路径，视觉确认才算完成。 +- 不要跑与改动无关的全仓命令（`pnpm -r build`、lint 全仓等）。 + +## 环境 + +- Postgres：`docker exec pg18 psql -U postgres`（postgres/postgres；库 `vmall`/`vmall_test`）。Redis：容器 `rdb8`。 +- 后端环境变量见 README；测试库连接串写死在 `apps/api/tests/common/mod.rs`。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..2d0d6d1 --- /dev/null +++ b/README.md @@ -0,0 +1,78 @@ +# 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/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+。 + +```bash +# 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 | + +## 测试与校验 + +```bash +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` |