Архитектура ядра биллинга ЖКХ: Лицевые счета и начисления

1. Проверка связи Лицевой счёт ↔ Собственник

Связь реализована и проверена:

• PersonalAccount (Лицевой счёт) имеет поле OwnerID *uint → связь с Owner (Собственник)
• Owner имеет обратную связь PersonalAccounts []PersonalAccount
• Ответственный собственник — тот, на кого открыт лицевой счёт

PersonalAccount ──OwnerID──> Owner
       │
       └──RoomID──> Room (Помещение)

2. Сущности и связи

2.1 Помещение (Room)

• Назначение: Квартира, нежилое помещение, машиноместо, кладовая, апартамент
• Справочники: RoomPurpose (жилое/нежилое), RoomKind (квартира/коммунальная/общежитие)
• Связи: House (дом), PersonalAccounts, RoomOwners

2.2 Собственник (Owner)

• Типы: Физлицо, ИП, Юрлицо (через OwnershipForm)
• Поля: ФИО, ИНН, ОГРН/ОГРНИП, контакты
• Связи: PersonalAccounts, RoomOwners

2.3 Связь Собственников с Помещениями (RoomOwner)

Новая сущность для долевой собственности:

Поле	Тип	Описание
room_id	uint	Помещение
owner_id	uint	Собственник
share_numerator	int	Числитель доли (1)
share_denominator	int	Знаменатель доли (2 для 1/2)
is_responsible	bool	Ответственный (на кого открыт ЛС)
valid_from, valid_to	*time	Период действия (история)

Пример: Двое собственников квартиры по 1/2:

• RoomOwner(room_id=1, owner_id=1, 1, 2, true)
• RoomOwner(room_id=1, owner_id=2, 1, 2, false)

2.4 Лицевой счёт (PersonalAccount)

• Обязательно: RoomID (помещение)
• Опционально: OwnerID (ответственный собственник)
• Номер: AccountNumber (уникальный)
• Период: OpeningDate, ClosingDate

2.5 Счетчики

Тип	OwnerType	OwnerID	Описание
ИПУ (индивидуальный)	"account"	PersonalAccount.ID	Привязан к ЛС/помещению
ОДПУ (общедомовой)	"house"	House.ID	Привязан к дому

Структура Meter:

• MeterType — тип (вода, отопление, электроэнергия и т.д.)
• OwnerType + OwnerID — полиморфная связь
• MeterPeriod — период действия (замена, демонтаж)
• MeterReading — показания (PeriodMonth, PeriodYear, Value1/2/3)

3. Диаграмма связей

                    ┌─────────────┐
                    │   House     │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐  ┌─────────┐  ┌─────────┐
        │   Room   │  │  Meter  │  │HouseSvc  │
        │(Помещение)│  │ (ОДПУ)  │  └─────────┘
        └────┬─────┘  └─────────┘
             │
    ┌────────┼────────┐
    │        │        │
    ▼        ▼        ▼
┌────────┐ ┌────────────┐ ┌──────────────┐
│RoomOwner│ │PersonalAcct│ │    Meter     │
│(доля)   │ │  (ЛС)     │ │   (ИПУ)      │
└────┬────┘ └─────┬──────┘ └──────┬───────┘
     │           │               │
     └───────────┼───────────────┘
                 │
                 ▼
           ┌──────────┐
           │  Owner   │
           │(Собствен.)│
           └──────────┘

4. Golden Test

4.1 Данные

• Файл: golden_test_jkh_12months.xlsx
• Период: 12 месяцев (2025)
• ЛС: 10 штук (LS01–LS10) с разными кейсами

4.2 Кейсы

ЛС	Описание
LS01	Идеальный (все показания поданы)
LS02	Забывчивый (март–июнь без показаний: среднее, норматив)
LS03	Должник (не платит)
LS04	Переплата (июль: 3×, август: 0)
LS05	Недоплата (50%)
LS06	Задержка (оплата 25-го, пеня 15 дней)
LS07	Изменение услуг (Парковка до 15 июля)
LS08	Отопление по ОДПУ (формула 3(3))
LS09	Сломанный ИПУ (сентябрь: норматив×1.5)
LS10	Отрицательный ОДН (ΣИПУ > ОДПУ)

4.3 Seed

API:

POST /api/test-data/seed-golden
Content-Type: application/json

{"organizationId": 1, "houseId": 0}

Результат:

• 1 дом (или использование существующего при houseId > 0)
• 10 помещений с площадями из golden test
• 10 собственников
• 10 записей room_owners (доля 1/1)
• 10 лицевых счетов (LS01–LS10)
• 10 ИПУ воды + 2 ОДПУ (вода, отопление)
• 120 показаний (12 месяцев × 10 ЛС)

5. Правила финансового учёта

• Двойная запись: Будущая реализация через JournalEntry (дебет/кредит)
• Неизменяемость истории: Показания и начисления не редактируются, только корректирующие проводки
• Аудит: created_at, updated_at на всех сущностях

6. Файлы

Файл	Назначение
models/room_owner.go	Модель RoomOwner
models/room.go	Связь RoomOwners
models/owner.go	Связь RoomOwners
database/migrate.go	AutoMigrate RoomOwner
database/seed_golden.go	Seed для golden test
handlers/test_data.go	API seed-golden
migrations/001_room_owners.sql	SQL миграция room_owners
scripts/seed_golden_test.sql	Документация SQL seed