# 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 |