moex-vibe/docs/features/russian-docs-and-architecture-diagrams/spec.md

Русификация документации и исправление архитектурных схем — SDD-спецификация

Дата: 2026-06-15

Статус: черновик для ревью

Контекст

Документация проекта публикуется только из apps/docs через Docusaurus. Текущая структура уже зафиксирована в docs/features/docusaurus-docs/spec.md: страницы лежат в apps/docs/docs, навигация описана в apps/docs/sidebars.ts, Mermaid включён через @docusaurus/theme-mermaid.

Сейчас большая часть человекочитаемого текста в опубликованной документации написана на английском: заголовки, подписи таблиц, описания endpoint'ов, ADR summary, названия разделов sidebar. Проект ведётся на русском, поэтому документация должна быть русскоязычной, оставляя на английском только технические названия, идентификаторы и общепринятые инженерные термины.

На странице apps/docs/docs/architecture.md первая Mermaid-схема System Architecture смешивает в одном graph TD внешний контур приложения и внутреннее устройство backend. Из-за этого Docusaurus рендерит слишком широкую и высокую схему: блоки и подписи стрелок визуально накладываются друг на друга, особенно вокруг Backend (NestJS), Browser (React SPA), NestJS API, cache, MOEX и SQLite.

Цели

1. Перевести опубликованную человекочитаемую документацию в apps/docs на русский язык.
2. Оставить без перевода технические названия и идентификаторы, которые должны совпадать с кодом, API, библиотеками или файлами.
3. Исправить читаемость Mermaid-схем в apps/docs/docs/architecture.md, убрав наложение блоков и подписей.
4. Сохранить текущую структуру Docusaurus и URL/slugs, чтобы не ломать существующие ссылки.
5. Задать проверяемые критерии приёмки для последующей реализации.

Не цели

• Не менять backend, frontend, OpenAPI contract, runtime-конфигурацию или Docker-инфраструктуру.
• Не переименовывать файлы документации, ADR-файлы, route slugs и ссылки между страницами, если это не требуется для исправления битой ссылки.
• Не внедрять i18n с несколькими локалями: сайт остаётся одноязычным с defaultLocale: 'ru'.
• Не переписывать архитектурные решения по сути. ADR переводятся как документация, но их смысл, статус и последствия сохраняются.
• Не менять визуальную тему Docusaurus сверх минимальной поддержки читаемых Mermaid-схем.

Область изменений

Опубликованная документация

Перевод и редактура затрагивают:

• apps/docs/docusaurus.config.ts
• apps/docs/sidebars.ts
• apps/docs/docs/intro.md
• apps/docs/docs/getting-started.md
• apps/docs/docs/architecture.md
• apps/docs/docs/backend/*.md
• apps/docs/docs/frontend/*.md
• apps/docs/docs/development/*.md
• apps/docs/docs/infrastructure/*.md
• apps/docs/docs/adr/*.md

Стили

apps/docs/src/css/custom.css можно менять только если после разбиения Mermaid-схем остаются проблемы с шириной, переносами или горизонтальной прокруткой. CSS не должен быть основным способом исправления сломанной схемы.

Правила русификации

Переводить

• Заголовки страниц и разделов: Architecture -> Архитектура, Getting Started -> Быстрый старт.
• Sidebar labels: Infrastructure -> Инфраструктура, Development -> Разработка, Architecture Decisions (ADR) -> Архитектурные решения (ADR).
• Описания таблиц и колонок: Description -> Описание, Required -> Обязателен, Default -> По умолчанию.
• Поясняющий текст, инструкции, списки, summaries, примечания к flow/sequence diagrams.
• Подписи Mermaid-стрелок, если они не являются точным API, cookie/header или именем метода: fetches -> запрашивает, uses -> использует, raw data -> сырые данные.
• Ошибочные или неактуальные формулировки, найденные при переводе, если их можно исправить по текущему коду или уже существующим SDD/ADR.

Не переводить

• Названия технологий и библиотек: NestJS, React, Vite, TanStack Query, Prisma, SQLite, Docusaurus, Docker, Nginx, Vitest, MSW, Swagger, OpenAPI, lightweight-charts, openapi-fetch.
• Архитектурные технические существительные, уже используемые в проекте как термины: backend, frontend, middleware, endpoint, request, response, cache, cookie, access token, refresh token, rate limiter, circuit breaker, codegen, workspace, build, lint.
• Имена модулей, классов, DTO, методов, env vars, scripts, файлов и директорий: AuthModule, MoexClientService, CACHE_MARKET_DATA_TTL, npm run dev:backend, apps/backend/src/modules/auth.
• HTTP methods, URL paths, JSON keys, TypeScript/Prisma identifiers, enum values и code blocks.
• ADR file names and IDs: ADR-001-backend-single-point-of-access.md, ADR-010, etc.

Стиль русского текста

• Писать для разработчика проекта, без маркетингового тона.
• Использовать короткие предложения и конкретные глаголы.
• Сохранять технические термины в одном написании по всему сайту.
• Не переводить термин, если перевод ухудшает связь с кодом или общепринятой практикой.

План исправления architecture.md

Текущую первую схему нужно заменить набором меньших схем:

1. Архитектура системы — внешний контур: Browser/React SPA, NestJS API, SQLite, cache, MOEX ISS API. Направление лучше сделать flowchart LR, чтобы схема читалась слева направо.
2. Внутренние модули backend — отдельная схема только для NestJS feature/global modules: AuthModule, SharesModule, BondsModule, CandlesModule, SecuritiesModule, PortfolioModule, HealthModule, MoexClientModule, CacheModule/CacheService, PrismaModule/PrismaService.
3. Поток авторизованного запроса — существующий sequenceDiagram оставить как отдельный сценарий, но перевести человекочитаемые подписи и сверить путь запроса с актуальными docs/API.

Для первой схемы недопустимо помещать большой subgraph Backend_Internal внутрь графа внешней архитектуры. Если нужно показать, что NestJS API состоит из модулей, это должно быть ссылкой текстом или отдельной диаграммой ниже.

Рекомендуемый Mermaid-паттерн

flowchart LR
    Browser["Browser<br/>(React SPA)"]
    API["NestJS API<br/>:3000"]
    Cache["In-memory cache<br/>(cache-manager)"]
    MOEX["MOEX ISS API<br/>iss.moex.com"]
    DB[("SQLite<br/>(Prisma)")]

    Browser -->|"/api/v1/*"| API
    Browser -->|"Authorization: Bearer"| API
    Browser -->|"Cookie: refreshToken"| API
    API -->|"getOrFetch()"| Cache
    API -->|"GET /iss/*.json"| MOEX
    API -->|"Prisma ORM"| DB
    Cache -->|"данные"| API
    MOEX -->|"сырые данные"| API
    DB -->|"пользователи и портфели"| API

В реализации можно менять конкретное расположение узлов, если итоговая схема проходит визуальную проверку и остаётся семантически эквивалентной.

План реализации

1. Создать отдельную ветку codex/russian-docs-architecture-diagrams, если текущая ветка не предназначена для этой работы.
2. Пройти по navigation/config files: apps/docs/docusaurus.config.ts и apps/docs/sidebars.ts.
3. Перевести overview-страницы: intro.md, getting-started.md, architecture.md.
4. В architecture.md заменить первую Mermaid-схему на две небольшие схемы и перевести человекочитаемые подписи в sequenceDiagram.
5. Перевести backend-раздел, сохраняя имена модулей, endpoints, DTO, env vars и code examples.
6. Перевести frontend-раздел, сохраняя названия React/Vite/TanStack Query и имена hooks/components.
7. Перевести infrastructure/development-разделы, сохраняя команды, scripts, имена workflow jobs, Dockerfile paths и package names.
8. Перевести ADR index и ADR pages без изменения сути решений, статусов и ссылок.
9. Проверить Markdown-ссылки, таблицы и fenced code blocks.
10. Запустить npm run build:docs.
11. Если build проходит, открыть локальный Docusaurus и визуально проверить architecture.md: нет наложения блоков, подписи стрелок читаемы, схема не уезжает за viewport на desktop.

Критерии приёмки

• Все опубликованные страницы в apps/docs/docs/**/*.md имеют русские заголовки и русский человекочитаемый текст, кроме разрешённых технических названий.
• apps/docs/sidebars.ts показывает русские labels для всех человекочитаемых категорий.
• apps/docs/docusaurus.config.ts содержит русскую tagline или нейтральную русскоязычную фразу.
• Имена файлов, route slugs, ADR IDs, endpoint paths, env vars, code blocks и API examples не переименованы ради перевода.
• apps/docs/docs/architecture.md не содержит одной большой Mermaid-схемы, которая одновременно показывает внешний контур и внутренние backend modules.
• Mermaid-схемы на странице architecture.md рендерятся без наложения узлов и подписей.
• npm run build:docs завершается успешно.
• После сборки нет новых broken links или broken Markdown links сверх текущей политики onBrokenLinks: 'warn', onBrokenMarkdownLinks: 'warn'.

Проверка качества

Автоматическая

npm run build:docs

Ожидаемый результат: Docusaurus build завершается без ошибки.

Ручная

1. Запустить npm run dev:docs.
2. Открыть страницу /architecture.
3. Проверить, что первая схема помещается в контентную область на desktop без наложения.
4. Проверить, что sequence diagram читается и подписи на русском там, где они не являются техническими идентификаторами.
5. Выборочно открыть по одной странице из разделов Backend, Frontend, Инфраструктура, Разработка и ADR, чтобы подтвердить единый стиль перевода.

Риски и решения

Риск	Решение
Чрезмерный перевод ломает связь с кодом	Следовать списку "Не переводить" и оставлять code/API terms как есть
Mermaid всё ещё строит слишком широкую схему	Делить диаграмму ещё мельче, а не пытаться лечить layout только CSS
ADR после перевода могут звучать как новые решения	Сохранять ID, статус, контекст, consequences и не менять смысл
Перевод таблиц может сломать Markdown	После каждой группы страниц запускать build или локально просматривать diff

Решение для ревью

Рекомендуемый путь: сначала выполнить русификацию и разбиение схем без изменения информационной архитектуры сайта. После этого отдельно оценить, нужно ли делать полноценную редакторскую нормализацию терминов или добавлять глоссарий. Для текущей задачи глоссарий в отдельной странице не нужен: достаточно единых правил в этой спецификации и аккуратного применения по docs.