62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# 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 |
|