# Дизайн: эпик «Финансы» — наполнение разделов карты C6 + C7 (finance-tooling)

**Дата:** 2026-05-20
**Статус:** утверждён заказчиком (brainstorming, 20.05.2026)
**Ветка исполнения:** `worktree-finance-tooling-c6-c7` (worktree от origin/main `7df4786`)
**Связанные ADR:** ADR-012 (новый — граница finance-tooling)
**Режим:** экономия 5%

---

## 1. Цель

Закрыть (наполнить) два пустых раздела карты dev-автоматики (`docs/automation-graph.html` / `docs/automation-graph-data.js`):

- **C6** «Финансы — биллинг и тарификация»
- **C7** «Финансы — бухгалтерия и налоги»

По решению заказчика **разделы объединяются в один комплексный эпик «Финансы»** и решаются вместе. Карта — это «мозг»-маршрутизатор: на задачу «X в финансовом домене» она должна указывать инструмент «Y». Сейчас на оба раздела не указывает ни один узел `NODE_SECTION` (они в списке «пустых разделов — будущих доменов мозга»).

Требование заказчика: **полное покрытие** — каждая реальная потребность домена сопоставлена с узлом (а не 1–2 точечных инструмента).

## 2. Контекст

### 2.1. Что уже есть в коде (объект домена)

Биллинг-подсистема Лидерры (Plan 4) — подтверждённые файлы:

- `app/app/Services/Billing/PricingTierResolver.php` — 7-ступенчатая тарификация (pure).
- `app/app/Services/Billing/LedgerService.php` — двойной баланс prepaid→₽ через `bcmath`.
- `app/app/Services/Billing/BillingTopupService.php`, `ChargeResult.php`.
- `app/app/Models/PricingTier.php`, `LeadCharge.php`; `app/app/Repositories/PricingTierRepository.php`.
- `app/app/Http/Controllers/Api/{AdminPricingTiersController,AdminBillingController,BillingController,TenantChargesController}.php`.
- `app/app/Jobs/Supplier/CsvReconcileJob.php` — hourly сверка, алерт при дрейфе >5%.
- `app/app/Services/Reports/Providers/BillingSummaryProvider.php` — отчётность.
- `app/app/Mail/TopupSuccessNotification.php`, `ZeroBalancePausedMail` (auto-pause при нуле).

C6 = «как Лидерра берёт деньги с клиентов за лиды» (тарифы, списания, баланс, сверка, авто-пауза). C7 = «учёт и налоги компании» (бухгалтерия, НДС/УСН, отчётность). Бухгалтерия компании в основном вне dev-репо (1С/аутсорс) — поэтому C7 dev-tooling скуднее C6.

### 2.2. Нормативная поверхность маршрутизации (актуальная на 20.05.2026)

С iter9 (ADR-011, brain governance) маршрутизация описана явно:

- `docs/router-procedure.md` v1.0 — 5-шаговая процедура «task → node(s)»; **читает** 9-атрибутный реестр Tooling §4.X (generic, перечень узлов не хардкодит).
- `docs/routing-off-phase.md` v1.1 — таблица «триггер → off-phase узел» (§4.11–§4.35) + 12 канонических связок L1–L12.
- Наблюдатель (observer): 9-атрибутные блоки на каждый узел реестра (Tooling §0.1 шаблон) + контролёры lefthook (C1 l1-watcher name@source, C2 cross-ref-checker).

**Следствие:** новые узлы обязаны попасть в routing-таблицу (роутер) и получить 9-атрибутные блоки + пройти контролёров (наблюдатель). Это расширяет нормативную правку сверх классических 4 файлов.

## 3. Решение по объёму

**Гибрид с полным покрытием:** reuse-классификация существующих узлов в C6/C7 + установка релевантного marketplace-плагина + два своих проектных скила под реальные gap'ы + честная регистрация неприменимого как not-applicable/DEFERRED.

## 4. Архитектура решения — слои

| Слой | Содержание |
|---|---|
| **Установка (1 узел)** | `finance` plugin (knowledge-work-plugins, Anthropic) — enable в `~/.claude/settings.json` (marketplace уже добавлен; механика как operations/product-management). |
| **Свои скилы (2 узла)** | `.claude/skills/billing-audit/` (C6) + `.claude/skills/ru-tax-accounting/` (C7). |
| **Reuse-классификация** | ~11 существующих узлов → C6/C7 через `NODE_SECTION_SECONDARY` (основная привязка `NODE_SECTION` 1:1 не трогается). |
| **DEFERRED / not-applicable** | warehouse-MCP плагина (Snowflake/Databricks/BigQuery) — не наш стек; SOX-скилы — нет SOX у частной РФ-компании. |
| **Нормативка** | Tooling Прил.Н, PSR_v1, Pravila, CLAUDE.md, routing-off-phase.md, router-procedure.md, ADR-012. |
| **Карта** | +3 узла + рёбра + secondary-классификация + META/версии. |

## 5. Новые узлы

### 5.1. #61 — `finance` plugin (knowledge-work-plugins)

- **Тип:** plugin (enable), Anthropic Verified, тот же marketplace, что operations #51 / product-management #42.
- **Состав:** 9 скилов — `reconciliation`, `variance-analysis`, `financial-statements`, `close-management`, `journal-entry`, `journal-entry-prep`, `sox-testing`, `audit-support`, плюс MCP-серверы (snowflake/databricks/bigquery/slack/ms365 — http).
- **Домашний раздел:** **C7** (primary) — плагин на ~80% бухгалтерский.
- **Применимость к РФ-контексту (честно):**
  - ✅ применимо: `reconciliation` (сверка ledger↔банк/субледжер — cross-ref в C6 под `CsvReconcileJob`), `variance-analysis` (план/факт выручки — C6/C7).
  - ⚠️ частично (US-GAAP, у нас РСБУ): `financial-statements`, `close-management`, `journal-entry`, `journal-entry-prep` — концепция применима для внутренней управленческой отчётности; форма/план счетов отличаются.
  - ❌ not-applicable РФ: `sox-testing`, `audit-support` (SOX 404 — США; у частной РФ-компании SOX отсутствует).
- **MCP-серверы:** **DEFERRED / не используем** — Snowflake/Databricks/BigQuery не в стеке (PG 16 + Redis); ms365/slack — не подключены. Фиксируем как not-applicable (аналог Figma MCP #44 deferred-pending).
- **Smoke:** после enable — скилы `finance:*` доступны в списке скилов сессии.

### 5.2. #62 — `billing-audit` (свой проектный скил, C6)

- **Тип:** self-authored project skill (`.claude/skills/billing-audit/`), как `process-analysis`, `audit-portal`, `regression` — не вендоренный, линтуется.
- **Зачем:** generic-инструменты не кодируют **денежные инварианты именно Лидерры**.
- **Scope (чек-лист + процедура аудита при правке/ревью биллинг-кода):**
  1. сохранение суммы prepaid→₽ через `bcmath` без утечек/потери копеек;
  2. идемпотентность списания (один лид = одно списание; повтор/ретрай не дублирует);
  3. корректность резолюции 7 ступеней `PricingTierResolver`;
  4. интерпретация дрейфа `CsvReconcileJob` (порог >5%) — что значит, куда смотреть;
  5. провенанс `charge_source` (откуда возникло списание).
- **Границы (FIN5):** ≠ `process-modeling`/`process-analysis` (#52/#53 — *поток/процесс*, billing-audit — *денежная корректность реализации*); ≠ D3 audit-security/audit-portal (#39/#40 — *безопасность/портал целиком*, billing-audit — *деньги*). Объект анализа иной.
- **Состав:** `SKILL.md` + `references/` (инварианты, ссылки на файлы биллинга) + `evals/evals.json` (триггер-eval).

### 5.3. #63 — `ru-tax-accounting` (свой проектный скил, C7)

- **Тип:** self-authored project skill (`.claude/skills/ru-tax-accounting/`).
- **Зачем:** `finance`-плагин — US-GAAP/SOX; РФ-специфика (РСБУ + НК РФ) им не покрывается. Закрывает налогово-учётный gap C7 явно (по решению заказчика — вместо DEFERRED).
- **Scope:** контекст РСБУ vs управленческий учёт; налоговые режимы (НДС / УСН доходы/доходы-расходы) применительно к SaaS-выручке за лиды; маппинг billing-выручки (`lead_charges`, `LedgerService`) → налоговая база; подготовка выгрузок/документов для бухгалтера; что является налогооблагаемым событием (списание / пополнение / возврат).
- **Границы (FIN6):** ≠ `finance` plugin #61 (тот — generic/US-механика учёта + reconciliation/variance; ru-tax — РФ РСБУ/НК специфика); ≠ D1 «Юриспруденция/договорная» (договоры/право, не налоги); ≠ D2 «Защита ПДн» (персональные данные, не налоги).
- **Состав:** `SKILL.md` + `references/` (РСБУ/НК РФ заметки, налоговые режимы) + `evals/evals.json`.

## 6. Reuse-классификация (существующие узлы → C6/C7)

Через `NODE_SECTION_SECONDARY` (узел остаётся в своём primary `NODE_SECTION`, добавляется вторичная привязка).

**→ C6 (биллинг/тарификация):**

| Потребность | Узел |
|---|---|
| Биллинг-модели (LedgerService/PricingTierResolver/lead_charges/tenants) | Boost #10 |
| Тесты денежной логики (ступени, ledger, идемпотентность, гонка lockForUpdate) | Pest #18 + pest-parallel-debugger |
| Money-precision статанализ (bcmath, без float) | Larastan #12 |
| Runtime-ошибки списаний / auto-pause | Sentry MCP #34 |
| Очередь `CsvReconcileJob` / кэш баланса | Redis MCP #35 |
| Метрики выручки/тарифов (MRR, tier-распределение) | product-management metrics-review #42 |
| Прогноз/моделирование выручки | data-scientist #49 |
| Себестоимость поставщика (`supplier_lead_costs`) | operations vendor-review #51 |
| Финансовый риск / дрейф сверки | operations risk-assessment #51 |
| State-машина charge-lifecycle / discovery | process-modeling #52 / process-analysis #53 |
| Доки bcmath / money-lib | context7 #60 |
| Сверка ledger↔субледжер | finance `reconciliation` #61 (cross-ref) |
| Анализ отклонений выручки | finance `variance-analysis` #61 (cross-ref) |

**→ C7 (бухгалтерия/налоги):**

| Потребность | Узел |
|---|---|
| Управленческая отчётность / финмодели | data-scientist #49 |
| Выгрузка billing→учёт (данные) | Boost #10 / Pest #18 |
| Финансовый риск / комплаенс-трекинг | operations risk-assessment / compliance-tracking #51 |
| Сверка / отклонения / отчётность (US-механика) | finance plugin #61 (primary) |
| РФ РСБУ / НК РФ / НДС-УСН | ru-tax-accounting #63 |

> `BillingSummaryProvider.php` — это код-объект (отчётный провайдер), не узел тулчейна; упоминается как объект, на который указывают узлы, не получает номер.

## 7. Граница C6 ↔ C7 (FIN7)

- **C6 биллинг/тарификация** = начисление денег клиенту за лиды: тарифные ступени, списания, баланс, top-up, сверка поставки, авто-пауза.
- **C7 бухгалтерия/налоги** = учёт и налоги компании: РСБУ, НДС/УСН, отчётность, налоговая база, закрытие периода.
- Точка стыка: billing-выручка (`lead_charges`/`LedgerService`) — это **выход C6** и **вход C7** (источник налоговой базы). Скилы не пересекаются: billing-audit проверяет корректность *начисления*; ru-tax-accounting переводит выручку в *налоговый/учётный* контекст.

Фиксируется в **ADR-012**.

## 8. Нормативная поверхность (8 артефактов)

1. **Tooling Прил.Н** — §4.36 finance plugin / §4.37 billing-audit / §4.38 ru-tax-accounting (каждый: 9-атрибутный блок наблюдателя + проза); §0 счётчик **+3** (база сверяется из Tooling §0 «КАНОН СЧЁТЧИКОВ» на этапе нормативки — ожидаемо 60→**63**) + новая off-phase подкатегория `finance-tooling`; header bump.
2. **PSR_v1** — R10.1 +3 строки (finance plugin в блок плагинов; 2 скила — блок скилов/note). Не UI → вне R6.0/R6.1/R14. Version bump.
3. **Pravila** — §13.2 +абзац «Off-phase finance-tooling». Version bump.
4. **CLAUDE.md** — §3.3 +#61/#62/#63 (однострочный индекс, пин на Tooling §4.36–§4.38); §0 cross-refs bump; §6 +абзац; §9 +entry; шапка bump. Прямой Edit (worktree-эксцепшн §5 п.10).
5. **routing-off-phase.md** (роутер) — +3 строки routing-таблицы (триггеры → #61/#62/#63); +каноническая связка **L13** (finance-цепочка); scope-диапазон §4.11→§4.38; version v1.1→v1.2.
6. **router-procedure.md** (роутер) — changelog-touch (узлы появляются в реестре §4.X, который процедура читает; перечень generic — структурных правок не требует).
7. **ADR-012** — `docs/adr/012-finance-tooling.md`: граница C6↔C7; applicability finance plugin (US-GAAP/SOX vs РФ); billing-audit vs process-*/D3; ru-tax vs finance/D1/D2; DEFERRED warehouse-MCP.
8. **Наблюдатель** — 9-атрибутные блоки (п.1) + прогон контролёров **C1 l1-watcher** (name@source consistency) + **C2 cross-ref-checker** → GREEN/WARN-only на новых узлах (контролёры warn-only `|| true`, но дрейф по новым узлам не вносим).

## 9. Карта (`automation-graph-data.js` + `automation-graph.html`)

- **+3 узла** в `NODES`: `finance_plugin` (group plugins/skills_proj), `billing_audit` (skill), `ru_tax` (skill).
- **NODE_SECTION:** `finance_plugin: 'C7'`, `billing_audit: 'C6'`, `ru_tax: 'C7'`.
- **NODE_SECTION_SECONDARY:** `finance_plugin: ['C6']` + reuse-привязки из §6 (Boost/Pest/Larastan/Sentry/Redis/PM/data-scientist/operations/process-*/context7 → добавить 'C6' и/или 'C7').
- **EDGES:** связи новых узлов с соседями (billing_audit → Pest/Boost; finance_plugin → operations/PM; ru_tax → finance_plugin).
- **NODE_DETAILS** в `automation-graph.html`: описания/`together`/`boundaries` для 3 узлов.
- **META/версии-метки:** обновить счётчики узлов/рёбер и версию-метку узла `claude_md` (актуальная версия определяется на этапе нормативки) после нормативки.

## 10. Конфликт-аудит (для плана)

| Код | Риск | Резолюция |
|---|---|---|
| FIN1 | warehouse-MCP finance не под стек | DEFERRED / not-applicable, не подключаем |
| FIN2 | SOX-скилы (sox-testing/audit-support) | not-applicable РФ (нет SOX) |
| FIN3 | finance vs operations (vendor-review/risk) | finance = учёт/сверка/отчётность; operations = операционные процессы/риск |
| FIN4 | finance `reconciliation` vs `CsvReconcileJob` | инструмент (скил) vs код (наш джоб) — не конфликт, скил помогает анализировать джоб |
| FIN5 | billing-audit vs process-*/audit-portal/D3 | объект иной (деньги vs поток vs безопасность) |
| FIN6 | ru-tax vs finance plugin vs D1/D2 | ru-tax = РФ РСБУ/НК; finance = US-механика; D1 = право; D2 = ПДн |
| FIN7 | граница C6↔C7 | ADR-012: начисление клиенту vs учёт/налоги компании |
| FIN8 | lint вендоренного/enabled | self-authored скилы линтуются; finance-плагин — в plugin-cache, не в репо |

## 11. Изоляция и исполнение

- **Worktree** от origin/main `7df4786` (= текущий main, superset iter9), ветка `worktree-finance-tooling-c6-c7`. Свежий worktree без gitignored-файлов — node_modules/vendor через junction, bin/.env скопированы.
- **Коммиты явными путями** (`git commit -- <пути>`) — параллельные сессии активны (memory `feedback_git_commit_explicit_paths`).
- **Субагенты + git** — только Sonnet/Opus (Pravila §15.1), верификация commit-базы после каждого.
- **Pre-flight sync** (Pravila §15.2) перед правкой каждого из 8 нормативных файлов: `git fetch && git log HEAD..origin/main --oneline`.

**Фазы (один план):**

1. **Фаза 1 — C6:** скил `billing-audit` (TDD: triggers-eval first) + reuse-классификация C6 в карте.
2. **Фаза 2 — C7:** enable finance plugin (+smoke) + скил `ru-tax-accounting` (TDD) + reuse-классификация C7.
3. **Фаза 3 — нормативка + роутер + наблюдатель + карта + ADR:** Tooling/PSR_v1/Pravila/CLAUDE.md + routing-off-phase.md/router-procedure.md + ADR-012 + automation-graph + 9-атрибутные блоки + прогон C1/C2.

## 12. Тестирование / верификация

- Скилы: триггер-eval (как discovery-interview 20/20) — `evals.json` на оба скила; near-miss к соседним узлам (process-analysis/D3/finance plugin/D1) уходят корректно.
- Нормативка: markdownlint + cspell (lefthook) GREEN; lychee на изменённых .md (pre-push).
- Карта: JS-smoke (узлы парсятся, NODE_SECTION покрывает все узлы, рёбра валидны) — как iter8/iter9.
- Контролёры: C1 l1-watcher + C2 cross-ref-checker без новых drift по добавленным узлам.
- Перед коммитом — pre-commit (docs-only коммиты: markdownlint/cspell/gitleaks; PHP-коммиты скила-evals при наличии PHP — pint/larastan/pest).
- Регрессия `/regression quick` перед закрытием; full — по необходимости.

## 13. Out of scope (YAGNI)

- Реальная интеграция платёжного провайдера (карты) — Б-1 blocked, отдельный ADR.
- Подключение warehouse-MCP (Snowflake/Databricks/BigQuery) — не наш стек.
- SOX-процедуры — неприменимо РФ.
- Автоматизация бухгалтерии в 1С — вне dev-репо.
- UI/функциональные правки биллинг-подсистемы — это эпик тулчейна/карты, не продукта.

## 14. Критерий готовности

- Разделы C6 и C7 карты непустые (есть узлы); 3 новых узла формализованы во всех 8 нормативных артефактах согласованно; роутер знает новые узлы; наблюдатель имеет 9-атрибутные блоки; ADR-012 фиксирует границы; регрессия GREEN; запушено `origin <ветка>:main`.
