148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
# OpenSpec Change: enterprise-gaming-api-plugin-bank
|
|
|
|
- **Change ID**: enterprise-gaming-api-plugin-bank
|
|
- **Package**: `@suaveplan/api-plugin-bank`
|
|
- **Category**: gaming/server
|
|
- **Target path**: `gaming/server/api-plugin-bank`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-bank.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-bank` on the genesis branch from scratch at enterprise quality. The package is a game-oriented virtual-currency bank built on top of `@suaveplan/economy`. It adds per-account-type interest accrual (`savingsInterestRate` vs. `currentInterestRate`), configurable currency code (default `"GOLD"`), transfer support, and deposit/withdrawal tracking with a full transaction audit trail. Four Hono route groups expose HTTP endpoints: `/accounts`, `/interest`, `/transactions`, `/config`. A `GameBankService` and `InterestService` are registered as plugin services. Genesis adds Zod request/response schemas, structured errors, OTel route instrumentation, and 100% coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis yet — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `BankError`; `BANK.*` codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `Clock` |
|
|
| `@suaveplan/economy` (`workspace:^`) | `Wallet` for balance management |
|
|
| `@suaveplan/events` (`workspace:^`) | `bank:deposit`, `bank:withdrawal`, `bank:transfer`, `bank:interest` events |
|
|
| `zod` (`catalog:forms`) | Request/response schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Route span instrumentation |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
type AccountType = 'current' | 'savings'
|
|
|
|
interface BankAccount {
|
|
id: string
|
|
playerId: string
|
|
type: AccountType
|
|
balance: number
|
|
currency: string
|
|
createdAt: number
|
|
lastInterestAt: number
|
|
}
|
|
|
|
interface BankTransaction {
|
|
id: string
|
|
accountId: string
|
|
type: 'deposit' | 'withdrawal' | 'transfer' | 'interest'
|
|
amount: number
|
|
currency: string
|
|
description?: string
|
|
timestamp: number
|
|
}
|
|
|
|
function createGameBankService(options: BankServiceOptions): GameBankService
|
|
|
|
interface BankServiceOptions {
|
|
currency?: string
|
|
savingsInterestRate?: number // per day, e.g. 0.005
|
|
currentInterestRate?: number
|
|
clock?: Clock
|
|
}
|
|
|
|
interface GameBankService {
|
|
openAccount(playerId: string, type: AccountType): BankAccount
|
|
getAccount(accountId: string): BankAccount | undefined
|
|
listAccounts(playerId: string): BankAccount[]
|
|
deposit(accountId: string, amount: number, description?: string): BankTransaction
|
|
withdraw(accountId: string, amount: number, description?: string): BankTransaction
|
|
transfer(fromId: string, toId: string, amount: number): [BankTransaction, BankTransaction]
|
|
listTransactions(accountId: string, limit?: number): BankTransaction[]
|
|
}
|
|
|
|
function createInterestService(bank: GameBankService, clock?: Clock): InterestService
|
|
interface InterestService {
|
|
accrueAll(): void
|
|
tick(dt: number): void // daily accrual on interval
|
|
}
|
|
|
|
// Hono plugin
|
|
function bankPlugin(options: BankPluginOptions): HonoPlugin
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type BankErrorCode =
|
|
| 'BANK_ACCOUNT_NOT_FOUND'
|
|
| 'BANK_INSUFFICIENT_FUNDS'
|
|
| 'BANK_ACCOUNT_LIMIT'
|
|
| 'BANK_INVALID_AMOUNT'
|
|
| 'BANK_TRANSFER_FAILED'
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
gaming/server/api-plugin-bank/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/common.ts
|
|
types/common.md
|
|
services/
|
|
game-bank-service/
|
|
game-bank-service.ts
|
|
game-bank-service.md
|
|
game-bank-service.types.ts
|
|
game-bank-service.test.ts
|
|
index.ts
|
|
interest-service/
|
|
interest-service.ts
|
|
interest-service.md
|
|
interest-service.types.ts
|
|
interest-service.test.ts
|
|
index.ts
|
|
routes/
|
|
accounts.ts
|
|
accounts.md
|
|
interest.ts
|
|
transactions.ts
|
|
config.ts
|
|
plugin.ts
|
|
plugin.md
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: `@suaveplan/react-bank` and `@suaveplan/api-plugin-virtual-currency` build on this. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/economy`, `@suaveplan/events`.
|