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

**Дата:** 2026-06-15

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

## Контекст

Документация проекта публикуется только из `apps/docs` через Docusaurus. Текущая структура уже
зафиксирована в `docs/superpowers/specs/2026-06-13-docusaurus-docs-design.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-паттерн

```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'`.

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

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

```bash
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.