docs: план проекта + промпты задач PR-1..PR-6 для Claude Code на ВМ

- docs/architecture/plan.md — полный план проекта (архитектура, стек, SLA, регуляторика, Реестр ПО, roadmap M1–M5, открытые вопросы и решения). - docs/tasks/README.md — индекс задач и инструкция запуска для Claude Code на dev-ВМ. - docs/tasks/PR-1-go-models-m2m.md — Go-модели M2M, парсер windows-1251, NSDDateTime, round-trip тесты на эталонах. - docs/tasks/PR-2-fansy-ddl.md — DDL принимающей БД для команды Fansy (контракт данных, ETL-требования, словарь полей, тестовые данные). - docs/tasks/PR-3-lk-openapi.md — OpenAPI контракт lk-gateway по ESIA Finance API V1, для синхронизации с командой ЛК. - docs/tasks/PR-4-m2m-core-skeleton.md — FSM сделки, репозиторий, идемпотентность по GUID, метрики SLA. - docs/tasks/PR-5-nsd-adapter-skeleton.md — REST-клиент ИШ НРД, маршрутизация типов пакетов (M2MTR/M2MTD/M2MER/SUBBR/SUBER/SUB16). - docs/tasks/PR-6-crypto-service-skeleton.md — gRPC-каркас Java-сервиса криптографии (КриптоПро JCP, UDS, Provider-абстракция). С этого коммита дальнейшая разработка идёт на dev-ВМ через запущенный там Claude Code. Промпты PR-1..PR-3 готовы к параллельному запуску; PR-4 после PR-1; PR-5 и PR-6 ждут поставку артефактов (ИШ НРД, сертификаты, КриптоПро JCP). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 22:48:21 +03:00
parent d5b5597c67
commit 3fdc526031
8 changed files with 1651 additions and 0 deletions
@@ -0,0 +1,148 @@
+# PR-2: DDL принимающей БД для команды Fansy
+
+## Цель
+
+Спроектировать DDL принимающей БД `fansy-store` под требования
+документации НРД к данным M2M и передать его команде Fansy как
+контракт для их ETL.
+
+ETL **делает команда Fansy** в автоматизированном режиме. Наша
+ответственность — схема таблиц, индексы, миграции, типизированный
+Go-репозиторий чтения и контракт данных.
+
+## Источники правды
+
+- `DOC/M2MSchemas_260408/*.xsd` — какие поля и типы нужны для
+  формирования M2M-сообщений.
+- `DOC/Справочник пользователей.pdf` — перечень контрагентов
+  (БКС 5406121446, Ренессанс Брокер 7709258228, Альфа-банк 7728168971).
+- `docs/architecture/plan.md` — контракт с командой Fansy (раздел
+  «Контракт с командой Fansy — что мы передаём»).
+
+## Состав PR
+
+### 1. `docs/fansy-contract/v1/ddl/` — SQL-миграции
+
+PostgreSQL 16 / PostgreSQL Pro Certified. Используй `goose` или
+просто пронумерованные файлы `001__init.sql`, `002__staging.sql` и т. д.
+
+Схема разделена на две:
+- `fansy_staging` — куда пишет команда Fansy (только их роль может
+  делать INSERT/UPDATE);
+- `fansy` — рабочая, куда переливаются актуальные данные триггерами
+  или процедурами после валидации.
+
+Минимальный набор таблиц (повторяй структуру и в staging, и в
+рабочей):
+
+- `clients` — депоненты/инвесторы:
+  - `id` (uuid), `inn` (для юрлиц), `last_name`, `first_name`,
+    `middle_name`, `birth_date`, `created_at`, `updated_at`.
+- `client_documents` — документы инвестора:
+  - `id`, `client_id (FK)`, `document_type` (enum по
+    `IdentityDocumentCode`), `series`, `number`, `issued_at`,
+    `issuer`.
+- `iia_contracts` — ИИС-договоры:
+  - `id`, `client_id (FK)`, `agreement_type` (`T12` | `T03`),
+    `agreement_number`, `agreement_date`, `broker_inn`.
+- `depo_accounts` — депо-счета и разделы:
+  - `id`, `client_id (FK)`, `deponent_code`, `account_id`,
+    `section_id`, `depository_inn`, `is_active`, `is_trading`.
+- `settlement_requisites` — реквизиты расчётов:
+  - `id`, `inn`, `display_name`, `created_at`.
+- `portfolios` — портфели/остатки ЦБ:
+  - `id`, `client_id (FK)`, `depo_account_id (FK)`, `security_code`,
+    `isin`, `quantity_whole` (numeric), `quantity_fractional`
+    (numeric(38,16)), `isolation_status` (`SGDN`), `valued_at`.
+- `securities` — справочник ЦБ:
+  - `id`, `security_code` (PK), `isin`, `classification`
+    (`BOND`|`SHAR`|`MFUN`), `category` (`ORDN`|`PREF`|`UKWN`),
+    `security_type`, `security_series`, `reg_number`,
+    `fund_class`, `display_name`.
+- `participants` — контрагенты-участники сервиса MOST:
+  - `id`, `inn` (PK), `ogrn`, `full_name_rus`, `short_name_rus`,
+    `display_name_rus`, `full_name_eng`, `short_name_eng`,
+    `display_name_eng`, `depository_participant_code`,
+    `broker_participant_code`, `is_available_for_m2m`, `comment`.
+  - Предзаполни записями из `Справочник пользователей.pdf`.
+
+Дополнительно:
+- `etl_errors` — таблица для ошибок выгрузки Fansy (id, source_table,
+  source_pk, payload jsonb, error_message, created_at).
+- В `_staging`-таблицах поле `loaded_at timestamptz default now()`.
+
+**Индексы.** Минимум: PK, FK, индекс по `inn` и `deponent_code` в
+основных таблицах, индекс по `valued_at` в `portfolios`.
+
+**Роль `fansy_etl`.** В отдельном `000__roles.sql`:
+- роль `fansy_etl` с правами INSERT/UPDATE/SELECT на схему
+  `fansy_staging`;
+- роль `bj_reader` с SELECT на схему `fansy` — для нашего
+  `m2m-core`/`lk-gateway`;
+- DDL-права (CREATE/ALTER/DROP) — только у миграционной роли,
+  не у Fansy-ETL.
+
+### 2. `docs/fansy-contract/v1/data-dictionary.md`
+
+Таблица: «поле → семантика → источник в Fansy (если известен) →
+nullable → пример». На каждую колонку каждой таблицы.
+
+### 3. `docs/fansy-contract/v1/etl-requirements.md`
+
+Технические требования к процессу выгрузки от команды Fansy:
+
+- Подключение: PostgreSQL, роль `fansy_etl`, отдельная учётная запись.
+- Тип load: **инкрементный UPSERT в staging-таблицы** по бизнес-ключу;
+  полная перезаливка — только для справочников (`securities`,
+  `participants`), не чаще раза в сутки.
+- SLA свежести данных:
+  - `portfolios` — не позднее 1 минуты после изменения в Fansy;
+  - `clients`, `depo_accounts`, `client_documents`, `iia_contracts`
+    — не позднее 5 минут;
+  - `securities`, `participants` — раз в сутки или по событию.
+- Формат timestamp — UTC с явной зоной (`timestamptz`).
+- Обработка ошибок: запись в `etl_errors`.
+- Окно простоя для регламентных работ — согласовать.
+
+### 4. `docs/fansy-contract/v1/examples/`
+
+- `example-claim.md` — какие поля из БД нужны `m2m-core` для одной
+  типовой M2M-заявки (с конкретными SQL-запросами).
+- `seed-data.sql` — 5–10 тестовых клиентов, портфелей, заявок для
+  совместного приёмочного теста.
+
+### 5. `migrations/fansy-store/`
+
+Скопировать `*.sql` из `docs/fansy-contract/v1/ddl/` — отсюда будут
+исполняться миграциями в нашем сервисе.
+
+### 6. Обновить `docs/fansy-contract/v1/README.md`
+
+Описать состав каталога и порядок согласования с командой Fansy.
+
+## Требования к коду
+
+- Все DDL-файлы — на одной кодировке UTF-8.
+- Имена таблиц и колонок — `snake_case` английский.
+- Комментарии в DDL (`COMMENT ON COLUMN ... IS '...'`) — на русском.
+- Без эмодзи.
+
+## Коммит
+
+```
+feat(fansy-store): DDL принимающей БД + контракт данных для команды Fansy
+
+- docs/fansy-contract/v1/ddl/ — миграции PostgreSQL
+- docs/fansy-contract/v1/data-dictionary.md — словарь данных
+- docs/fansy-contract/v1/etl-requirements.md — требования к ETL
+- docs/fansy-contract/v1/examples/ — пример заявки + seed-data
+- migrations/fansy-store/ — рабочие копии миграций
+- предзаполнен справочник контрагентов из DOC/Справочник пользователей.pdf
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+
+## После коммита
+
+1. Обновить `docs/tasks/README.md`: PR-2 — «выполнено».
+2. Сообщить заказчику, что DDL готов и можно отправлять команде Fansy.