From 3ef10618dcb353ff49b326da4ad565e896cf752e Mon Sep 17 00:00:00 2001 From: oqyude Date: Thu, 8 Oct 2026 16:57:50 +0300 Subject: [PATCH] T7: Final validation + README update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pytest: 67/67 pass - Manual CLI test: init, forecast, scenario, whatif, compare, info, analyze all work; Excel round-trip (export → init → import) preserves data - README.md: обновлён под новую архитектуру domain/application/infrastructure с описанием слоёв, pydantic, Decimal, Repository, DI, schema versioning и расширенным списком команд (config sub-typer с account/transaction/etc) Tests: 67/67 pass. Project: refactor complete — все 5 направлений реализованы. --- README.md | 138 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 99 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index c38d2cb..a721e91 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # CashFlow Forecast -Личная финансовая модель с прогнозом денежных потоков, сценарным анализом и AI-ассистентом. +Личная финансовая модель с прогнозом денежных потоков, сценарным анализом. -Python + JSON + Excel + AI. +Python + Pydantic + JSON + Excel. ## Установка @@ -35,12 +35,17 @@ cf whatif --income 1.2 --expense 0.9 --growth 1.0 --months 12 # Сравнение всех сценариев cf compare --months 12 -# Импорт/экспорт Excel -cf import data.xlsx -cf export exports/report.xlsx +# Сводка модели +cf info -# AI-анализ (заглушка, генерация промпта) -cf analyze +# Редактирование модели +cf config account-add --name "Main" --balance 5000 +cf config transaction-add --account Main --amount -1200 --category rent +cf config rate-set USD RUB 80.0 + +# Импорт/экспорт Excel +cf import-xlsx data.xlsx +cf export-xlsx exports/report.xlsx ``` ### Пример: создание тестовых данных @@ -48,44 +53,87 @@ cf analyze Подготовьте Excel-файл с листами: `Accounts`, `Transactions`, `Recurring`, `Assets`, `Liabilities`. Заголовки колонок соответствуют полям моделей. Затем импортируйте: ```bash -cf import my_finances.xlsx +cf import-xlsx my_finances.xlsx cf forecast --months 12 ``` +## Архитектура + +Проект разделён на три слоя по принципам Clean Architecture: + +``` +┌─────────────────────────────────────────────┐ +│ domain/ — бизнес-модели │ +│ Account, Transaction, Asset, Liability, │ +│ Recurring, Scenario, FinancialModel, │ +│ ExchangeRate, CurrencyConverter │ +│ (pydantic.BaseModel, Decimal) │ +└──────────────────┬──────────────────────────┘ + │ +┌──────────────────▼──────────────────────────┐ +│ application/ — прикладные сервисы │ +│ ForecastService, ScenarioService, │ +│ ModelRepository (Protocol) │ +└──────────────────┬──────────────────────────┘ + │ +┌──────────────────▼──────────────────────────┐ +│ infrastructure/ — внешний мир │ +│ cli/ (Typer), ai/ (Assistant), │ +│ repositories/ (JsonFile, Excel) │ +└─────────────────────────────────────────────┘ +``` + ## Структура проекта ``` -├── cashflow_model/ # Модели данных (dataclass + JSON) -│ ├── account.py # Account -│ ├── transaction.py # Transaction -│ ├── recurring.py # RecurringCashflow -│ ├── asset.py # Asset -│ ├── liability.py # Liability -│ ├── scenario.py # ForecastScenario -│ └── model.py # FinancialModel (корень, save/load JSON) -├── engine/ # Вычислительное ядро -│ ├── forecast.py # ForecastService — прогноз -│ └── scenarios.py # ScenarioService — сценарии + what-if -├── sync/ # Синхронизация с Excel -│ └── excel_sync.py # ExcelSync — import/export .xlsx -├── ai/ # AI-ассистент -│ ├── prompts.py # Шаблоны промптов -│ └── assistant.py # AssistantService (заглушка) -├── cli/ # CLI (Typer) -│ └── main.py # Команды: cf init/forecast/scenario/... -├── tests/ # Тесты pytest -│ ├── conftest.py # Фикстуры +cashflow-forecast/ +├── domain/ # Бизнес-модели (pydantic + Decimal) +│ ├── account.py # Account +│ ├── transaction.py # Transaction +│ ├── recurring.py # RecurringCashflow +│ ├── asset.py # Asset +│ ├── liability.py # Liability +│ ├── scenario.py # ForecastScenario +│ ├── currency.py # ExchangeRate + CurrencyConverter +│ └── model.py # FinancialModel (корень) +│ +├── application/ # Прикладные сервисы +│ ├── forecast.py # ForecastService — прогноз +│ ├── scenarios.py # ScenarioService — сценарии + what-if +│ └── repositories/ +│ └── model_repository.py # ModelRepository Protocol +│ +├── infrastructure/ # Адаптеры к внешнему миру +│ ├── cli/ # Typer CLI (cf ...) +│ │ ├── app.py # Entry point +│ │ ├── commands/ # 9 файлов команд + config sub-typer +│ │ ├── paths.py # DATA_DIR, MODEL_PATH +│ │ ├── services.py # Composition root + helpers +│ │ └── i18n.py # ru/en переводы +│ ├── ai/ # AI-ассистент (заглушка) +│ │ ├── prompts.py +│ │ └── assistant.py # AssistantService +│ └── repositories/ # Реализации ModelRepository +│ ├── json_file_repository.py +│ └── excel_repository.py +│ +├── tests/ # pytest, 67 тестов +│ ├── conftest.py │ ├── test_model.py │ ├── test_forecast.py │ ├── test_scenarios.py -│ ├── test_excel_sync.py +│ ├── test_currency.py │ ├── test_ai.py -│ └── test_cli.py -├── data/ # JSON-модели -├── exports/ # Экспортированные .xlsx -├── .agent/ # Артефакты MetaAgent (планирование) -├── pyproject.toml # Зависимости и конфигурация -└── README.arch.md # Оригинальная архитектурная концепция +│ ├── test_cli.py +│ ├── test_excel_sync.py # Тесты ExcelRepository +│ ├── test_i18n.py +│ └── test_repositories.py # Тесты репозиториев +│ +├── data/ # JSON-модели (runtime, версионируется SCHEMA_VERSION=1) +├── exports/ # Экспортированные .xlsx +├── .agent/ # Артефакты MetaAgent v3.0 +├── pyproject.toml # Зависимости + entry point `cf` +└── README.arch.md # Оригинальная архитектурная концепция ``` ## Разработка @@ -94,7 +142,7 @@ cf forecast --months 12 # Тесты pytest -# Линтер +# Линтер (если доступен ruff) ruff check . # Автоформат @@ -107,12 +155,24 @@ ruff format . - openpyxl — работа с Excel - typer — CLI - rich — форматирование вывода +- pydantic >= 2.0 — валидация моделей - pytest — тесты -- ruff — линтер +- ruff — линтер (опционально) + +## Архитектурные решения + +- **Слои**: `domain/` (модели), `application/` (сервисы), `infrastructure/` (адаптеры). +- **Pydantic v2**: все модели — `pydantic.BaseModel` с валидацией (balance >= 0, amount != 0, и т.п.). +- **Decimal**: все денежные поля — `Decimal`, арифметика без потери точности. +- **Repository pattern**: `ModelRepository` Protocol, реализации `JsonFileRepository` и `ExcelRepository`. +- **DI**: Composition root в `infrastructure/cli/services.py:build_services()`. +- **Schema versioning**: `FinancialModel.to_dict()` пишет `version: 1`; `from_dict()` поддерживает legacy v0. +- **i18n**: `infrastructure/cli/i18n.py`, ru (default) + en (fallback). ## Известные ограничения (MVP) -- **AI-ассистент** — заглушка. Промпты готовы, но не подключены к API. -- **База данных** — JSON-файлы (не подходит для многопользовательской работы). +- **AI-ассистент** — заглушка (`ai_response: None`). Промпты готовы, но не подключены к API. +- **Хранилище** — JSON-файлы (не подходит для многопользовательской работы). - **Excel** — только `.xlsx` через openpyxl. - **Лицензия** — не выбрана. +- **CI/CD** — не настроен.