feat(wallet): add wallet management API and migration (!10) · Merge Requests · ThinhNC / finwise-miniapp-be

feat(wallet): add wallet management API and migration

Summary

Add authenticated wallet management APIs following the project layer structure: route → validation → controller → service → repository.
Enforce wallet ownership using the authenticated user ID.
Support wallet listing, creation, retrieval, updates, default selection, archiving, and restoration.
Preserve monetary precision by handling wallet balances as decimal strings.
Add serializable transactions with retry handling for default-wallet consistency.
Add a Wallet-specific Prisma migration and regenerate Prisma Client types.
Document all Wallet endpoints and schemas in Swagger.
Update agent guidelines to require migration-history and generated-client verification after Prisma changes.

API Changes

GET /api/v1/wallets
POST /api/v1/wallets
GET /api/v1/wallets/:id
PUT /api/v1/wallets/:id
PATCH /api/v1/wallets/:id/default
PATCH /api/v1/wallets/:id/restore
DELETE /api/v1/wallets/:id

DELETE archives the wallet instead of deleting it permanently. A default wallet must be replaced before it can be archived.

Database Changes

Add Wallet metadata fields: currency, icon, color, and description.
Add is_default and is_archived state fields.
Change wallet balance to DECIMAL(18, 2).
Add an index on wallets.user_id.
Change the transaction-wallet foreign key to ON DELETE RESTRICT.

Verification

pnpm run prisma:generate
pnpm exec prisma validate
pnpm build
Applied the complete migration chain successfully to a temporary PostgreSQL database.
git diff --check

Notes

The primary development database was not reset or migrated during implementation.
Older migration history still has unrelated Auth, Category, and Budget schema debt. Those changes were intentionally excluded because the full diff contains destructive operations outside this feature's scope.

## Summary

- Add authenticated wallet management APIs following the project layer structure:
  `route → validation → controller → service → repository`.
- Enforce wallet ownership using the authenticated user ID.
- Support wallet listing, creation, retrieval, updates, default selection, archiving, and restoration.
- Preserve monetary precision by handling wallet balances as decimal strings.
- Add serializable transactions with retry handling for default-wallet consistency.
- Add a Wallet-specific Prisma migration and regenerate Prisma Client types.
- Document all Wallet endpoints and schemas in Swagger.
- Update agent guidelines to require migration-history and generated-client verification after Prisma changes.

## API Changes

- `GET /api/v1/wallets`
- `POST /api/v1/wallets`
- `GET /api/v1/wallets/:id`
- `PUT /api/v1/wallets/:id`
- `PATCH /api/v1/wallets/:id/default`
- `PATCH /api/v1/wallets/:id/restore`
- `DELETE /api/v1/wallets/:id`

`DELETE` archives the wallet instead of deleting it permanently. A default wallet must be replaced before it can be archived.

## Database Changes

- Add Wallet metadata fields: `currency`, `icon`, `color`, and `description`.
- Add `is_default` and `is_archived` state fields.
- Change wallet balance to `DECIMAL(18, 2)`.
- Add an index on `wallets.user_id`.
- Change the transaction-wallet foreign key to `ON DELETE RESTRICT`.

## Verification

- `pnpm run prisma:generate`
- `pnpm exec prisma validate`
- `pnpm build`
- Applied the complete migration chain successfully to a temporary PostgreSQL database.
- `git diff --check`

## Notes

- The primary development database was not reset or migrated during implementation.
- Older migration history still has unrelated Auth, Category, and Budget schema debt. Those changes were intentionally excluded because the full diff contains destructive operations outside this feature's scope.