Перейти к основному содержимому

Документация PIN

Единый набор документации PIN — платформы недвижимости. Здесь методологический слой: правила, шаблоны, backend-SDK, архитектура. Документация конкретных сервисов (docs/06-services/*) пишется по этим шаблонам и правилам отдельно.

Исходные требования — ТехЗадание.md (корень репозитория). Рабочие правила для агентов — CLAUDE.md и AGENTS.md.

Разделы​

РазделЧто внутри
00-overview/Обзор, гид по навыкам, реестры (registries/).
01-engineering-rules/Правила документирования и кода: CQRS, entity, event, api, strict-typed, algorithm, DDD, frontend, code-quality, git.
02-architecture/Архитектура и ADR (adr/).
07-frontends/Фронтенды PIN: pin-admin, pin.developers.
08-devops/CI/CD, git-workflow, quality gates, incident management.
11-backend-sdk/Реальные building blocks Talent.Common.* (SDK, на котором строятся сервисы).
99-templates/Канонические шаблоны документов (entity, api-method, command-query, consumer, event-contract, saga, use-case, service-readme, …).

Ключевые принципы​

  • Один дом на концепт + ссылки (не дублировать таблицы полей между документами).
  • Строгая типизация документации: все модели/сущности/события/jsonb/value objects — явно и полностью, без generic object/json/payload.
  • Каждый метод (endpoint/consumer/producer) — по CQRS с явным алгоритмом и диаграммой.
  • Реализация — поверх реального SDK Talent.Common.* (см. 11-backend-sdk/).

Документы обзора​

ДокументНазначение
technical-assignment.mdНормализованное ТЗ: 16 контекстов, принятые решения, расхождения источников, traceability
glossary.mdГлоссарий терминов PIN (роли, каталог, CRM, аналитика)
service-boundaries.mdContext map, владение данными, интеграционные потоки
prototype-mapping.mdПривязка «прототип ↔ контекст ↔ UC/US ↔ API/модель»
skills-guide.mdКогда/как/какие skills использовать

Навыки и команды​

Когда/как/какие skills использовать — skills-guide.md.

Реестры​

registries/ — сквозные индексы: api-index, entities-index, events-index, invariants-index, use-cases-index.