# AGENTS.md — 给编码代理的指引

本仓库是 VMall B2B2C 商城 MVP（pnpm + Cargo 双 workspace）。改动前先读本文件与 `README.md`；功能变更须同步 OpenSpec。

## 布局与所有权

- `apps/api` — Rust 后端（crate `vmall-api`）。迁移在 `apps/api/migrations/`（sqlx，启动时自动执行，只增不改）。分层约定见英文：`docs/adr/`、`docs/tech-specs/rust-api.md`、`openspec/specs/api-architecture/spec.md`。代码按限界上下文放在 `src/modules/<ctx>/`（handler → service → repo）；HTTP 抽取器在 `src/http/`。新功能写进对应模块，不要把 SQL 堆回 handler。简单 CRUD 允许 handler 直接调 repo。Service 返回 `ApiResult<Dto>`，不依赖 `Json`/`StatusCode`。Repo 接受 `&mut PgConnection` / `&mut Transaction` 以便组合事务。不引入泛型 Repository trait。
- `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 语言包、共享 Tailwind v4 主题 `theme.css`（`@theme` tokens + `html[data-accent]` 预设）。前端禁止自建 API 封装；契约变更只在这里改，且三个前端都要过构建。共享 Vue 组件在 `packages/ui`（`@vmall/ui`：`VBtn`/`VBadge`/`VField`/`VInput`/`VCard`/`VPanel`/`VTable`/`VPage`/`VAccentSwatch` + `useAccent()`，以 Nuxt 模块自动注册）。布局用 Tailwind utilities，禁止 `<style scoped>`。
- `openspec/` — 规范。`specs/` 是已归档能力规范（auth, rbac, catalog, currency, cart, order, shipment, invoice, api-architecture, 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 = ...` 模式）。**并发计数扣减**（目前只有 `skus.stock`）：多行 `FOR UPDATE` 必须先 `ORDER BY` 主键；扣减必须 `SET col = col - $qty WHERE id = $1 AND col >= $qty`，`rows_affected = 0` → `Conflict`。禁止无条件 `SET col = col - n`。回补用 `col = col + n`，不要用读出的绝对值写回。商家覆盖赋值（`SET stock = $n`）不是扣减，不走此模式。
- **RBAC**：受保护路由声明角色（`auth.require(&[...])`）；店铺资源必须过 `auth.own_shop()` 作用域，跨店返回 404。

## 开发流程（OpenSpec）

1. 新能力/行为变更：在 `openspec/changes/<name>/` 建 `proposal.md` + `tasks.md` + `specs/<capability>/spec.md`（`## ADDED Requirements` / `### Requirement:` / `#### Scenario:` 格式），`openspec change validate <name> --strict` 必须通过。
2. 按 tasks 实现；完成后勾选并 `openspec archive <name> --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` 夹具）。
- 测试隔离：测试库不截断，夹具靠唯一 slug/email。**断言不要假设全局集合为空或恰好 N**——只对自己创建的 id 过滤后断言。新增列表/发现类接口时，`cargo test -p vmall-api` 需**连跑两次**都全绿（单次可能只是库恰好干净）。
- 管道跑测试时注意退出码：`cargo test | grep` 返回的是 grep 的状态，用 `set -o pipefail` 或显式取 `$?`，否则会漏掉 `FAILED`。
- 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`。