# 12 — UNIT-ECONOMICS (экономика, прайсинг, wallet, metering, COGS)

> Цельная карта unit-econ подсистемы. Активная + горячая по безопасности зона (money-mint класс). Снимок 2026-07-05.
> Источники: `board/specs/UNIT-ECONOMICS-EPIC/{02-RESEARCH,decisions-accepted}.md`, текущий код, SEC-ECON тикеты.

## 1. Модель прайсинга (HYBRID)

Три компонента (02-RESEARCH §4.2, [ГИПОТЕЗА где помечено]):
1. **Platform-fee (seat/workspace)** — фикс-база за доступ (RAG, интеграции, meeting-rooms). Цель >$250/мес/команду (NRR 85% дорогих vs 32% дешёвых). **Per-member.**
2. **Voice-минуты (metered)** — per-min SIP/PSTN + realtime. Пул в tier + overage PAYG. Markup к $0.13-0.20 COGS. **Пул на команду.**
3. **Usage-кредиты (мультимодал)** — vision/OCR/видео/подкаст/большие RAG. **Пул на команду.**

**Tier-черновик** [цифры-плейсхолдеры, калибровать beta-замером]:
| Tier | Платформа | Голос | Сегмент |
|---|---|---|---|
| Free/Beta (invite) | $0 | 0-10 мин | активация/воронка |
| Starter | $29-49 | ~60 мин, overage $0.30-0.50 | solo |
| Pro | $99-199 | ~300 мин | активные voice+knowledge |
| Team/Business | $250+/seat ИЛИ платформа | ~1000 мин пул | команды (NRR-зона) |
| Overage (все) | — | PAYG $/мин | защита маржи |

## 2. Принятые решения (decisions-accepted #1-9)
1. Beta SLIM (Free без PSTN) · 2. Realtime=Studio+ · 3. Allowlist IE/UK/US/CA · 4. Overage turn $0.30/realtime $0.70 · 5. Daily vendor-import gate · 6. First-sentence AI-disclosure (EU AI Act) · 7. Promo НЕ для PSTN · 8. Business invite-only $299+ · **9. billing-tenant: usage (голос-мин+кредиты+model-spend) = ОБЩИЙ командный бюджет для команд-планов; личный кошелёк = дефолт (Subscription сейчас пер-юзерный).**

## 3. Экономи код-карта (§07-детализация для экономики)

**Credit-пути (начисление coins/XP/gems):**
- `src/app/api/economy/earn/route.ts` — COINS. earnFromClientRequest → resolveClientEarnings.
- `src/app/api/game/xp/add/route.ts` + `gamification/action`+`status` — XP (handleServerVerifiedXpPost → awardXP, amount server-derived).
- arcade `src/lib/arcade/{engine.ts(v1),v2/{engine,serverScore}.ts}` — v2 server-recompute из ArcadeRun; **v1 legacy = client-amount (см §5 дыра)**.
- `src/app/bossActions.ts` (finishBossFight→outcomeCredit), decks/session, quests, retention (`retentionService.claimDailyReward`).

**Guard:** `src/lib/gamification/rewardGuard.ts` — SERVER_VERIFIED_ONLY: {boss_fight_win/won, daily_login, achievement_unlock, deck_complete} → 403 EVENT_REQUIRES_SERVER_VERIFICATION. Все EARNING_RULES-sources в наборе (клиентский rule-путь мёртв).

**Policy:** `src/lib/economy/{economyService,earnPolicy,earningRules}.ts`. `earnCurrency` (trusts client currency+amount) НЕ route-reachable — только outcomeCredit (server {source}) + retention (server-computed). `earnFromClientRequest` = policy-derived.

**Wallet (write-слой):** `src/lib/billing/walletService.ts` — preauthHold/settleHold/releaseHold/idempotentDebit. Модели: UserBalance (@@unique tenantId,userId; buckets cash/grant/promo/reserved), LedgerEntry (append, idempotencyKey), BalanceHold (active|settled|released|expired), UsageCall (per-call spend, callId link-by-convention). Idempotency: Transaction @@unique[userId,reference]. ⚠️ walletService 0 внешних callers = не enforce (WALLET-WIRING pending).

**Billing-tenant:** `src/lib/billing/billingTenant.ts` — resolveBillingTenant (decision #9: billingTeamId→team:id; дефолт→user:userId).

**Metering:** `src/lib/unitecon/{devBurnLedger,turnBasedVoiceMetering,spanTraceCost}.ts`. devBurnLedger=dev-swarm (отдельный ledger, не грязнит прод-маржу). ProviderRate=серв-COGS (см §4).

## 4. COGS / rate-card
- **ProviderRate** (prisma) — 72 ставки на serving-DB (noteclone-pgvector:55432): telnyx(58)/twilio(11)/google(1)/signal(2), 6 service-types, 22 страны. Reader `providerRateProvider.ts` (getProviderRateCents/getTelcoPerMinuteUsd) → graceful fallback RATE_MAP.
- **Model-rates** (RATE_MAP, per-1M-token): Opus $5/$25, Sonnet, Haiku $1/$5, DeepSeek $0.27/$1.10 (commodity). Роутинг дешёвое→Haiku/DeepSeek, тяжёлое→Sonnet/Opus = рычаг COGS.
- **Профили usage** [замер]: text ~$0.5-2/мес, voice-heavy ~$70-120/мес.

## 5. Money-mint security-posture (2 независимых ревью, 2026-07-05)

**ЗАКРЫТО на LIVE** (фиксы = ancestors serving-SHA, drift-verified):
- forge client source/amount/currency → route не читает body.currency ✓
- server-verified sources (daily/achievement/deck/boss) → 403 ✓
- idempotency (operationId обязателен + Transaction @@unique) → replay no-op ✓
- v2 arcade (arcade_pack_win) → server-recompute из ArcadeRun ✓
- gem-mint → нет client-reachable gem-пути ✓
- XP-amount → server ACTION_XP table (client amount дропнут) ✓
Тикеты green: SEC-BOSSFIGHT-1115, SEC-ECONOMY-P0-EARN-SERVER-AUTH, P1-XP-CONSOLIDATE, ARCADE-AMOUNT(v2), WIRE-BOSS-ARCADE-DECK-RESOLVE.

**ОТКРЫТО (тикеты):**
- 🟡 **SEC-ECON1** arcade_win **v1-legacy** — client-trusted coin-mint, per-op cap 100 но **aggregate-unbounded** (нет rate-limit/daily-cap, client-chosen reference). Medium (coins-only, gems/деньги недостижимы). *В работе.*
- **SEC-ECON2** v2 recompute доверяет client `correct`-флагам (скорит ложь, bounded 100/run).
- **SEC-ECON3** /api/economy/earn нет rate-limit (усилитель).
- **SEC-ECON5** retention `day-${cyclic}` reference → daily-награды прекращаются после цикла 1 (under-credit баг).
- **SEC-ECON6** 4 client-XP-действия без idempotency → XP/level-инфляция (Low, не coins).

**Инвариант:** любой credit-путь должен быть server-authoritative (награда из server-verified записи/policy, не client-строки) + idempotent + rate-limited. Проверять НА serving-SHA (git show), не board-статус.

## 6. Wallet-enforce статус (owner ОК enforce, decision #9)
Prereq'ы: ✅ resolveBillingTenant (в проде), 🔄 UsageCall-модель (деплой), ⏸️ WALLET-WIRING (ждёт prereq → подключить app-side callers idempotentDebit+preauthHold с resolveBillingTenant). Voice-callers (preauthHold звонка) = Codex-зона.

---
*Обновлять: при изменении credit-путей / прайсинга / money-mint posture. Связь: §04 (модели), §06 (security), §07 (файлы). Тикеты: SEC-ECON*, UNITECON-*.*