Документация FinGuide¶
Документация backend/API для FinGuide / «Финансовый капитал».
FinGuide строится как contract-first продукт: frontend редактирует входные данные финансового плана, backend владеет хранением, безопасностью и расчётами. Текущий этап — переход от mock/localStorage прототипа к real Spring Boot backend с persisted demo state и Keycloak/OIDC boundary.
Быстрые ссылки¶
- Frontend demo: http://66.42.121.18/fg/
- Real API base: http://66.42.121.18/finguide-api/api/v1
- Swagger UI real backend: http://66.42.121.18/finguide-api/swagger-ui.html
- OpenAPI JSON real backend: http://66.42.121.18/finguide-api/v3/api-docs
- Keycloak realm: http://66.42.121.18/auth/realms/finguide
- Backend repository: https://github.com/svoronkov-les13/finguide-be
- Web repository: https://github.com/svoronkov-les13/finguide-web
- GitHub Project: https://github.com/orgs/svoronkov-les13/projects/5/views/1
Legacy mock Swagger: http://66.42.121.18/finguide-mock/ — только для переходного сравнения.
Что читать первым¶
- Текущее состояние реализации — что реально работает сейчас.
- Roadmap — готовые и будущие задачи.
- База данных — фактическая H2 schema и ограничения demo persistence.
- Контракт API — целевой договор backend ↔ frontend.
- Аналитическая Excel-модель — канонические расчёты из исходной модели.
- Архитектура бэкенда и Keycloak — целевое устройство backend/auth.
- Модули бэкенда — пакетная структура и границы модулей.
Текущий статус коротко¶
Реализовано в real backend:
- API index;
GET /me;GET /plans/current;- dashboard/health/cashflow/scenarios read;
- CRUD incomes/expenses/goals;
- goals reorder;
- Keycloak JWT Resource Server boundary;
- user-owned current plan после логина;
- защита authenticated users от чтения/мутации чужих планов;
- frontend session restore без demo/default profile flash.
Открытые guardrails:
- #16 — real Springdoc coverage vs checked-in OpenAPI;
- #26 — запрет мутации общего anonymous demo seed plan.
Главная договорённость¶
Frontend не должен дублировать финансовую математику. Backend принимает persisted PlanState и ModelAssumptions, затем строит производные данные:
PlanState + ModelAssumptions
-> годовой денежный поток
-> сбережения и накопленный капитал
-> пенсионная проекция
-> dashboard, health score, scenarios
Канонический расчётный endpoint: