init2222

README.md

@@ -15,7 +15,8 @@ vault kv put dev-secrets/crypto/master key=$(openssl rand -hex 32)
 # 2. CSRF secret в Vault
 vault kv put dev-secrets/csrf secret_key=$(openssl rand -hex 32) salt=csrf-salt digest=sha256
 
-# 3. DB schema (миграция идемпотентна — безопасно прогонять на existing БД)
+# 3. DB schema — APPEND-ONLY / NON-DESTRUCTIVE
+#    Безопасно прогонять на existing БД. См. ниже "Schema is non-destructive".
 psql -h <db-host> -U postgres_user -d postgres -f cryptowallet-schema.sql
 
 # 4. bitok public key в Vault (для kid из JWT header)
@@ -93,9 +94,33 @@ ssh server@<host> -p 2222 'cd cryptowallet && docker compose up -d --build'
 - **Relay proxy** whitelist method+path — `/quote` (POST), `/intents/status/v3` (GET), `/execute/{swap|bridge}` (POST). Никаких freeform action'ов
 - **Bridge UI dropdown** ETH/BSC/SOL only (TRX через Relay убран — плохая ликвидность)
 
+## Schema is non-destructive
+
+`cryptowallet-schema.sql` **append-only**. Re-run на боксе с уже настроенной БД = **zero DDL changes**. Если оператор добавил кастомные таблицы / индексы / constraints вручную — они **никогда** не будут перезаписаны или удалены.
+
+Что делает script:
+- `CREATE TABLE IF NOT EXISTS users` / `wallets`
+- `ALTER TABLE users ADD COLUMN <X>` (только если колонки нет — `encrypted_mnemonic`, `erc20`, `passport_data`)
+- `CREATE UNIQUE INDEX users_email_lower_unique` (если индекса нет)
+- `CREATE INDEX idx_users_active` / `idx_wallets_*` (если индексов нет)
+- `ADD CONSTRAINT` × 4 (только если данного constraint name нет)
+
+Что script **НЕ делает**:
+- ❌ Никогда не `DROP TABLE`
+- ❌ Никогда не `DROP CONSTRAINT`
+- ❌ Никогда не `DROP COLUMN`
+- ❌ Никогда не перезаписывает существующие constraints / indexes
+
+Legacy cleanup (audit_log, idempotency_keys, sessions от старых версий) — **manual one-time** операторская задача, не часть этого script'а:
+```bash
+psql ... -c "DROP TABLE IF EXISTS audit_log CASCADE;"
+psql ... -c "DROP TABLE IF EXISTS idempotency_keys CASCADE;"
+psql ... -c "DROP TABLE IF EXISTS sessions CASCADE;"
+```
+
 ## Logs
 
-Файловых логов **нет**. Всё в stdout, подбирается Docker log driver:
+Файловых логов **нет**. Весь код пишет в `process.stdout` (см. `apps/api/src/lib/logger.ts` и `lib/audit-log.ts`). Docker подбирает stdout через json-file driver и показывает через `docker compose logs`:
 
 ```bash
 docker compose logs -f api                          # все логи (structured JSON)