From 2ef20d7d48fffafeba8cdffd7cd794f8b9877fcd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Wed, 20 May 2026 09:11:07 +0300 Subject: [PATCH] docs(finance): C6+C7 finance-tooling epic design spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Объединённый эпик «Финансы»: наполнение разделов карты C6 (биллинг/тарификация) + C7 (бухгалтерия/налоги). 3 новых узла (#61 finance plugin, #62 billing-audit, #63 ru-tax-accounting) + reuse-классификация + расширенная нормативка (роутер routing-off-phase.md + наблюдатель 9-атрибутные блоки) + ADR-012. +9 терминов в cspell-words.txt. Co-Authored-By: Claude Opus 4.7 (1M context) --- cspell-words.txt | 11 + ...2026-05-20-finance-tooling-c6-c7-design.md | 206 ++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-20-finance-tooling-c6-c7-design.md diff --git a/cspell-words.txt b/cspell-words.txt index 3821b339..475138c3 100644 --- a/cspell-words.txt +++ b/cspell-words.txt @@ -1498,3 +1498,14 @@ srcrt srcbl srcmt симв + +# finance-tooling C6+C7 epic — design spec (2026-05-20) +GAAP +РСБУ +вендоренного +джоб +линтуется +парсятся +ретрай +субледжер +хардкодит diff --git a/docs/superpowers/specs/2026-05-20-finance-tooling-c6-c7-design.md b/docs/superpowers/specs/2026-05-20-finance-tooling-c6-c7-design.md new file mode 100644 index 00000000..0320c6bb --- /dev/null +++ b/docs/superpowers/specs/2026-05-20-finance-tooling-c6-c7-design.md @@ -0,0 +1,206 @@ +# Дизайн: эпик «Финансы» — наполнение разделов карты 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`.