Шаблоны Документации
Назначение
docs/99-templates содержит единый набор enterprise-шаблонов для документации Pin. Шаблоны должны работать как повторяемый стандарт для разных сервисов, доменов и проектов на общем технологическом стеке компании.
Общие Требования Ко Всем Шаблонам
Любой документ, созданный по шаблону, должен:
- быть написан на русском языке в UTF-8;
- соответствовать Общим Требованиям К Документам;
- быть достаточно строгим для review, implementation, release и audit.
Обязательные Сквозные Блоки
Типовые cross-cutting блоки и правила их заполнения определены в Общих Требованиях К Документам. Шаблоны ниже добавляют только document-type-specific секции.
Все документы-постановки пишутся на уровне аналитика (analyst altitude) — см. Уровень изложения ТЗ. Ключевые принципы:
- Уровень изложения — постановка, а не код. Документ описывает, что система делает, кто имеет право, какую сущность по каким условиям получить, что при успехе и при каждом отказе, как это проверить. Имена классов/хендлеров/валидаторов, вызовы репозиториев, монада результата, транзакции и конверты сообщений в ТЗ не пишутся. Система описывается как строящаяся с нуля (greenfield): без прототипов, Node-BFF и «as-is».
- Опускаем неприменимые блоки. Включай раздел, только когда ему есть что сказать; пустой блок = удалённый блок. Никаких строк «не применяется», «нет/none» и целых секций-заглушек; лишние блоки не добавляются.
- Без SDK-имён и мета-ссылок в спеках. Не ссылайся на
Talent.Common.*-типы и на правила авторинга внутри самого документа — спек ссылается на контракты (сущности, события, соседние операции), а не на то, «как это в коде». - Диаграммы опциональны. Mermaid добавляют, только когда он проясняет нетривиальный поток; участники — бизнес/доменные роли (актор, сервис, витрина, внешняя система), а не инфраструктурные типы. Для тривиального CRUD диаграмму не рисуют.
Индекс Шаблонов
| Шаблон | Когда Использовать |
|---|---|
| adr-template.md | Архитектурное решение, влияющее на подход, стандарты, контракты, данные или эксплуатацию. |
| api-method-template.md | Один HTTP endpoint: актор и доступ, контракт запроса/ответа, алгоритм и failure modes. |
| background-job-template.md | Scheduler job, reconciliation job, batch worker или service maintenance task. |
| clickhouse-fact-template.md | Аналитическая fact/aggregate row model. |
| command-query-template.md | Правило CQRS (на него ссылаются api-method/consumer) + чисто-внутренние операции (background job, SignalR, domain-triggered). |
| consumer-template.md | Kafka consumer: маппинг «событие → эффект», идемпотентность, retry/DLQ; ссылка на event-contract. |
| dashboard-template.md | Dashboard, operational view, SLI/SLO surface. |
| data-lineage-template.md | Source-of-truth, projection, export, index или report lineage. |
| domain-invariant-template.md | Инвариант, state transition rule или guardrail. |
| entity-template.md | Entity, aggregate root, replica или snapshot-backed record. |
| event-contract-template.md | Versioned integration event contract. |
| feature-slice-template.md | Реализация feature slice на уровне application/backend/frontend work package. |
| frontend-component-template.md | Один UI компонент (atom/molecule/organism) во frontend-приложении. |
| frontend-feature-slice-template.md | FSD feature slice во frontend-приложении (UI + mutation/query + zod schema). |
| frontend-page-template.md | Страница или route в рабочем приложении. |
| frontend-store-template.md | Zustand store в frontend-приложении. |
| glossary-term-template.md | Описание одного термина, статуса или понятия domain vocabulary. |
| integration-test-template.md | Integration/component test specification. |
| jsonb-document-template.md | Typed JSONB model с versioning и compatibility rules. |
| migration-template.md | Data, schema, contract или rollout migration. |
| model-template.md | Reusable request/response/view/settings/snapshot model. |
| openapi-client-template.md | Generated or typed HTTP client. |
| policy-decision-record-template.md | Decision snapshot для policy engine или rules execution. |
| policy-permission-template.md | Policy, permission, guard, approval requirement. |
| provider-adapter-template.md | Anti-corruption adapter для внешней системы. |
| report-export-template.md | Export/report contract, file format, generation flow. |
| runbook-template.md | Incident, maintenance или manual recovery procedure. |
| saga-template.md | Cross-service process без distributed transaction. |
| search-document-template.md | Search index document/projection. |
| service-readiness-template.md | Production readiness checklist сервиса. |
| service-readme-template.md | Главный обзор сервиса. |
| system-scenario-template.md | Cross-service end-to-end scenario, policy flow или business capability. |
| task-specification-template.md | Полная постановка задачи для реализации. |
| use-case-template.md | Use case / сценарий использования с уникальным ID UC-<префикс>-<номер>, актором, потоками, ошибками, событиями, AC. |
Минимальная Проверка Перед Использованием Шаблона
- выбран подходящий тип документа;
- неприменимые разделы опущены, лишние блоки не добавлены;
- placeholders
<...>удалены; - нет локального ad hoc формата, не отраженного в шаблонах;
- спек не ссылается на правила авторинга и SDK-типы (уровень изложения — по spec-authoring-altitude-rules.md).