213 lines
15 KiB
Markdown
213 lines
15 KiB
Markdown
# Русификация документации и исправление архитектурных схем — 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-паттерн
|
||
|
||
```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.
|