docs: architecture, guidelines, domain designs, progressive code index

AGENTS.md

@@ -2,6 +2,12 @@
 
 本仓库是 VMall B2B2C 商城 MVP（pnpm + Cargo 双 workspace）。改动前先读本文件与 `README.md`；功能变更须同步 OpenSpec。
 
+## 文档与代码索引（docs/）
+
+- **定位代码先用 `docs/code_index/index.md`**：按业务域渐进披露到具体文件；新增/删除/重命名文件时**必须同步更新对应域的索引文件**。
+- 总体架构 `docs/architecture.md`；后端规范 `docs/backend-guidelines.md`；前端规范 `docs/frontend-guidelines.md`；领域设计 `docs/domains/`；开发/部署排障 `docs/development.md`。
+- 规范性的行为契约仍以 `openspec/specs/` 为准；docs 是实现地图，不是需求来源。
+
 ## 布局与所有权
 
 - `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。