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

2026-09-24 16:59:32 +08:00
parent c532f87b03
commit a968327b12
19 changed files with 728 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Development Guide
+
+## Prerequisites
+
+- Postgres: `docker exec pg18 psql -U postgres` (postgres/postgres; databases
+  `vmall` for dev, `vmall_test` for tests). Redis: container `rdb8`.
+- Rust stable + pnpm.
+
+## Run the stack
+
+```bash
+cargo run -p vmall-api            # API on :8080, migrations auto-apply on boot
+pnpm --filter @vmall/mall dev     # storefront :3000
+pnpm --filter @vmall/shop-admin dev
+pnpm --filter @vmall/admin dev
+pnpm dev                          # all frontends at once
+```
+
+Demo credentials (`scripts/seed-demo.mjs`, idempotent):
+`admin@vmall.local / admin1234` (platform), `shop@vmall.local / shop12345`
+(demo merchant), `customer@vmall.local / customer123` (shopper).
+
+## Test
+
+```bash
+cargo test -p vmall-api           # integration tests against vmall_test + Redis
+```
+
+Rules: run the suite **twice** before archiving a change (the shared test DB is
+never truncated; a single green run can be luck). Use `set -o pipefail` when
+piping to grep, or `FAILED` lines get swallowed by grep's exit code.
+
+Test DB migration drift (you edited an already-applied local migration):
+`docker exec pg18 psql -U postgres -d vmall_test -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"` — migrations rebuild it on next run.
+
+## Build
+
+```bash
+pnpm --filter @vmall/<app> build  # per app; required for every app when
+                                  # packages/shared changed
+```
+
+## OpenSpec flow
+
+1. New capability → `openspec/changes/<name>/` with proposal + tasks + spec
+   deltas; `openspec validate <name> --strict` must pass.
+2. Implement; check tasks as you go.
+3. Verify (tests ×2, builds, browser smoke), then `openspec archive <name> --yes`.
+4. `openspec validate --all --strict` stays green.
+
+The tigshop migration wave is tracked in `openspec/MIGRATION-PLAN.md`
+(temporary; deleted when all eight changes are archived).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Failed to resolve import "#app-manifest"` | `rm -rf apps/<app>/.nuxt`, restart dev |
+| Page stuck on loading after dev restart | stale tab holds dead chunk hashes — fresh tab |
+| curl to `127.0.0.1:3000` refused | dev binds IPv6; use `localhost` |
+| cargo test green locally but list test flaky | shared DB; assert only on own fixtures |