From 5b9d7f3a27b4e511bb4b498acd1d6695b5a65a63 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Thu, 18 Jun 2026 22:04:09 +0300 Subject: [PATCH] docs: fix historical files to new structure and update --- README.md | 5 +++- docs/features/auth-system/plan.md | 2 +- docs/features/docusaurus-docs/spec.md | 2 +- docs/features/moex-vibe/plan.md | 17 ++++++------ docs/features/moex-vibe/spec.md | 16 +++++------ docs/features/portfolio-analytics/spec.md | 2 +- .../portfolio-enricher-optimization/plan.md | 2 +- docs/features/portfolio/spec.md | 2 +- .../quality-gate-contract-docs/plan.md | 27 ++++++------------- .../quality-gate-contract-docs/spec.md | 10 +++---- .../spec.md | 4 +-- docs/features/security-screener/spec.md | 2 +- 12 files changed, 42 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 25d485d..e457e53 100644 --- a/README.md +++ b/README.md @@ -54,5 +54,8 @@ apps/ frontend/ — React SPA with Vite docs/ — Docusaurus documentation site docs/ - superpowers/specs/ — accepted SDD specifications + features/ — SDD feature specifications and implementation plans + epics/ — product epics + inbox.md — captured ideas and follow-ups + roadmap.md — planned epics and features ``` diff --git a/docs/features/auth-system/plan.md b/docs/features/auth-system/plan.md index c6100e4..d5f0814 100644 --- a/docs/features/auth-system/plan.md +++ b/docs/features/auth-system/plan.md @@ -1183,4 +1183,4 @@ Let me plan this properly in the implementation.<｜end▁of▁thinking｜> <｜｜DSML｜｜tool_calls> <｜｜DSML｜｜invoke name="todowrite"> -<｜｜DSML｜｜parameter name="todos" string="false">[{"priority":"high","content":"Save implementation plan to docs/superpowers/plans/","status":"completed"},{"priority":"high","content":"Install backend dependencies (Prisma, JWT, bcrypt, cookie-parser)","status":"in_progress"},{"priority":"high","content":"Set up Prisma schema + PrismaService + PrismaModule","status":"pending"},{"priority":"high","content":"Build AuthService (register, login, refresh, logout) with TDD","status":"pending"},{"priority":"high","content":"Build Auth guards, decorators, DTOs, controller","status":"pending"},{"priority":"high","content":"Integrate AuthModule into app.module, main.ts, configuration","status":"pending"},{"priority":"high","content":"Frontend: refactor client.ts + add auth types","status":"pending"},{"priority":"high","content":"Frontend: AuthContext + useAuth hook","status":"pending"},{"priority":"high","content":"Frontend: Login, Register, Profile pages + ProtectedRoute","status":"pending"},{"priority":"high","content":"Frontend: Layout + routing changes","status":"pending"},{"priority":"high","content":"Documentation (backend auth.md, database.md, ADR, api.md, architecture.md)","status":"pending"},{"priority":"high","content":"Verification: run tests, lint, build","status":"pending"}] +<｜｜DSML｜｜parameter name="todos" string="false">[{"priority":"high","content":"Save implementation plan to docs/features/auth-system/plan.md","status":"completed"},{"priority":"high","content":"Install backend dependencies (Prisma, JWT, bcrypt, cookie-parser)","status":"in_progress"},{"priority":"high","content":"Set up Prisma schema + PrismaService + PrismaModule","status":"pending"},{"priority":"high","content":"Build AuthService (register, login, refresh, logout) with TDD","status":"pending"},{"priority":"high","content":"Build Auth guards, decorators, DTOs, controller","status":"pending"},{"priority":"high","content":"Integrate AuthModule into app.module, main.ts, configuration","status":"pending"},{"priority":"high","content":"Frontend: refactor client.ts + add auth types","status":"pending"},{"priority":"high","content":"Frontend: AuthContext + useAuth hook","status":"pending"},{"priority":"high","content":"Frontend: Login, Register, Profile pages + ProtectedRoute","status":"pending"},{"priority":"high","content":"Frontend: Layout + routing changes","status":"pending"},{"priority":"high","content":"Documentation (backend auth.md, database.md, ADR, api.md, architecture.md)","status":"pending"},{"priority":"high","content":"Verification: run tests, lint, build","status":"pending"}] diff --git a/docs/features/docusaurus-docs/spec.md b/docs/features/docusaurus-docs/spec.md index 622896e..910c124 100644 --- a/docs/features/docusaurus-docs/spec.md +++ b/docs/features/docusaurus-docs/spec.md @@ -19,7 +19,7 @@ - `docker/Dockerfile.*`, `docker/nginx.conf` → инфраструктура - `docker-compose.yml` → сервисы, порты - `.gitea/workflows/ci.yml` → CI pipeline -- `docs/architecture/adr/*` → копия существующих ADR +- `apps/docs/docs/adr/*` → опубликованные ADR проекта - `.prettierrc`, `tsconfig.base.json` → конфиги ## Pages diff --git a/docs/features/moex-vibe/plan.md b/docs/features/moex-vibe/plan.md index b801a60..1386889 100644 --- a/docs/features/moex-vibe/plan.md +++ b/docs/features/moex-vibe/plan.md @@ -128,9 +128,10 @@ moex-vibe/ │ └── nginx.conf ├── docker-compose.yml └── docs/ - ├── architecture/adr/ - ├── openapi/openapi.yaml - └── superpowers/specs/2026-06-13-moex-vibe-design.md + ├── epics/ + ├── features/ + ├── inbox.md + └── roadmap.md ``` --- @@ -3280,18 +3281,18 @@ git commit -m "feat: add StockPage and BondPage with charts and details" - [ ] **Verify OpenAPI spec** — start backend, check Swagger UI at `/api/docs`. Ensure all endpoints, schemas, and examples are present. -- [ ] **Sync `docs/openapi/openapi.yaml`** with the generated spec if any changes were made during development. +- [ ] **Sync backend Swagger JSON (`/api/docs-json`) and regenerate `apps/frontend/src/api/types.ts`** if any contract changes were made during development. - [ ] **Commit** ```bash -git add docs/openapi/openapi.yaml +git add apps/frontend/src/api/types.ts git commit -m "docs: finalize OpenAPI specification" ``` ### Task 6.2: ADR documentation -- [ ] **Ensure all ADR files exist** in `docs/architecture/adr/` (created during design phase, adjust if needed). +- [ ] **Ensure all ADR files exist** in `apps/docs/docs/adr/` (created during design phase, adjust if needed). - [ ] **Add architecture overview diagram** (ASCII sequence diagram or Mermaid): @@ -3399,7 +3400,7 @@ server { services: backend: build: - context: ../../superpowers/plans + context: . dockerfile: docker/Dockerfile.backend ports: - "3000:3000" @@ -3410,7 +3411,7 @@ services: frontend: build: - context: ../../superpowers/plans + context: . dockerfile: docker/Dockerfile.frontend ports: - "80:80" diff --git a/docs/features/moex-vibe/spec.md b/docs/features/moex-vibe/spec.md index d19a920..7b4bb91 100644 --- a/docs/features/moex-vibe/spec.md +++ b/docs/features/moex-vibe/spec.md @@ -260,14 +260,14 @@ moex-vibe/ │ │ └── main.tsx │ └── package.json ├── docs/ -│ ├── superpowers/specs/ -│ ├── architecture/ -│ │ ├── adr/ -│ │ ├── diagrams/ -│ │ └── domain-model.md -│ ├── openapi/ -│ │ └── openapi.yaml -│ └── website/ (Docusaurus — post-MVP) +│ ├── epics/ +│ ├── features/ +│ ├── inbox.md +│ └── roadmap.md +├── apps/ +│ └── docs/ +│ └── docs/ +│ └── adr/ ├── package.json ├── tsconfig.base.json └── .gitignore diff --git a/docs/features/portfolio-analytics/spec.md b/docs/features/portfolio-analytics/spec.md index c753da5..ebaae99 100644 --- a/docs/features/portfolio-analytics/spec.md +++ b/docs/features/portfolio-analytics/spec.md @@ -368,7 +368,7 @@ model Position { ## 10. OpenAPI Specification -Дополнения к существующему `docs/openapi/openapi.yaml`: +Дополнения к текущему backend OpenAPI-контракту по `/api/docs-json`: - Обновить схему `PositionResponse` — добавить `buyPrice`, `buyDate` - Создать схему `PortfolioAnalytics` со всеми полями diff --git a/docs/features/portfolio-enricher-optimization/plan.md b/docs/features/portfolio-enricher-optimization/plan.md index 8944b8f..319740a 100644 --- a/docs/features/portfolio-enricher-optimization/plan.md +++ b/docs/features/portfolio-enricher-optimization/plan.md @@ -359,7 +359,7 @@ npm run format - [ ] **Step 1: Write ADR or performance note in docs** -Add to `docs/superpowers/adr/2026-06-14-portfolio-enricher-optimization.md` documenting: +Add to `apps/docs/docs/adr/` as a new ADR documenting: - Problem: 298 API calls → 29s - Changes made: merged bond calls, removed redundant securityDescription, batch by market - Result: 2 API calls → ~0.3s (97% reduction) diff --git a/docs/features/portfolio/spec.md b/docs/features/portfolio/spec.md index 9db687c..43b911e 100644 --- a/docs/features/portfolio/spec.md +++ b/docs/features/portfolio/spec.md @@ -392,7 +392,7 @@ Phase 1 не требует событийной шины. События док ## 10. OpenAPI Specification -Дополнение к существующему `docs/openapi/openapi.yaml` — новые эндпоинты и схемы для Portfolio и Position. +Дополнение к текущему backend OpenAPI-контракту по `/api/docs-json` — новые эндпоинты и схемы для Portfolio и Position. --- diff --git a/docs/features/quality-gate-contract-docs/plan.md b/docs/features/quality-gate-contract-docs/plan.md index f010472..4e4f004 100644 --- a/docs/features/quality-gate-contract-docs/plan.md +++ b/docs/features/quality-gate-contract-docs/plan.md @@ -4,7 +4,7 @@ **Goal:** Сделать стандартные проверки MoexVibe детерминированными, синхронизировать OpenAPI-артефакты и обновить документацию под фактическое состояние репозитория. -**Architecture:** Разделяем offline unit tests и opt-in live MOEX integration tests. Машинный API-контракт берём из NestJS Swagger JSON, затем синхронизируем `docs/openapi/openapi.yaml` и `apps/frontend/src/api/types.ts`. README, AGENTS и Docusaurus остаются onboarding-документацией и описывают текущий код, а не исторические планы. +**Architecture:** Разделяем offline unit tests и opt-in live MOEX integration tests. Машинный API-контракт берём из NestJS Swagger JSON по `/api/docs-json`, затем синхронизируем `apps/frontend/src/api/types.ts`. README, AGENTS и Docusaurus остаются onboarding-документацией и описывают текущий код, а не исторические планы. **Tech Stack:** npm workspaces, NestJS 10, Vitest 1 для backend, Vitest 4 для frontend, Docusaurus 3, Swagger/OpenAPI, openapi-typescript. @@ -15,7 +15,7 @@ ### Создать - `apps/backend/src/modules/moex-client/moex-client.service.integration.spec.ts` — opt-in live MOEX smoke tests. -- `apps/backend/src/openapi-artifacts.spec.ts` — offline проверка, что checked-in OpenAPI artifacts содержат актуальные paths. +- `apps/backend/src/openapi-artifacts.spec.ts` — offline проверка, что generated frontend OpenAPI types содержат актуальные paths. ### Изменить @@ -27,7 +27,6 @@ - `apps/backend/src/modules/bonds/bonds.service.spec.ts` — заменить live MOEX calls на mocked dependencies. - `apps/backend/src/modules/securities/screener.service.spec.ts` — убрать неиспользуемый `moexClient` или начать явно проверять его вызовы. - `apps/frontend/src/api/types.ts` — перегенерировать из текущего Swagger JSON. -- `docs/openapi/openapi.yaml` — обновить snapshot из текущего Swagger JSON. - `README.md` — актуализировать scripts, tests и docs workspace. - `AGENTS.md` — актуализировать workspace, команды, frontend tests, Husky и CI. - `apps/docs/docs/intro.md` — сделать Docusaurus docs home на `/`. @@ -955,9 +954,8 @@ git commit -m "test: make backend service specs deterministic" - Create: `apps/backend/src/openapi-artifacts.spec.ts` - Modify later in Task 4: `apps/frontend/src/api/types.ts` -- Modify later in Task 4: `docs/openapi/openapi.yaml` -- [ ] **Step 1: Написать failing test для checked-in OpenAPI artifacts** +- [ ] **Step 1: Написать failing test для generated frontend OpenAPI types** Создать `apps/backend/src/openapi-artifacts.spec.ts`: @@ -968,7 +966,6 @@ import { join, resolve } from 'node:path'; describe('checked-in OpenAPI artifacts', () => { const rootDir = resolve(process.cwd(), '../..'); const frontendTypes = readFileSync(join(rootDir, 'apps/frontend/src/api/types.ts'), 'utf8'); - const openapiYaml = readFileSync(join(rootDir, 'docs/openapi/openapi.yaml'), 'utf8'); const requiredPaths = [ '/api/v1/auth/register', @@ -989,12 +986,6 @@ describe('checked-in OpenAPI artifacts', () => { expect(frontendTypes).toContain(`'${path}'`); } }); - - it('static OpenAPI YAML snapshot includes current protected domains', () => { - for (const path of requiredPaths) { - expect(openapiYaml).toContain(`${path}:`); - } - }); }); ``` @@ -1017,12 +1008,11 @@ git commit -m "test: cover checked-in openapi artifacts" --- -## Task 4: Синхронизировать Swagger JSON, frontend types и static OpenAPI YAML +## Task 4: Синхронизировать Swagger JSON и frontend types **Files:** - Modify: `apps/frontend/src/api/types.ts` -- Modify: `docs/openapi/openapi.yaml` - Optional Modify: backend controller DTO metadata if `src/openapi-artifacts.spec.ts` still fails after regeneration. - [ ] **Step 1: Запустить backend для codegen** @@ -1076,16 +1066,15 @@ npm run codegen -w apps/frontend Expected: `apps/frontend/src/api/types.ts` changes and includes auth, screener and portfolio paths. -- [ ] **Step 5: Перегенерировать static YAML snapshot** +- [ ] **Step 5: Повторно проверить live Swagger JSON после codegen** Run: ```bash -node -e "fetch('http://localhost:3000/api/docs-json').then(r => r.json()).then(j => require('node:fs').writeFileSync('/tmp/moex-vibe-openapi.json', JSON.stringify(j, null, 2)))" -node -e "const fs = require('node:fs'); const yaml = require('js-yaml'); const json = JSON.parse(fs.readFileSync('/tmp/moex-vibe-openapi.json', 'utf8')); fs.writeFileSync('docs/openapi/openapi.yaml', yaml.dump(json, { lineWidth: 120, noRefs: true }));" +node -e "fetch('http://localhost:3000/api/docs-json').then(r => r.json()).then(j => { const paths = Object.keys(j.paths); for (const p of ['/api/v1/auth/register','/api/v1/securities/screener','/api/v1/portfolios']) { if (!paths.includes(p)) throw new Error('Missing path ' + p); } console.log('Swagger paths still OK'); })" ``` -Expected: `docs/openapi/openapi.yaml` changes and includes `/api/v1/auth/register`, `/api/v1/securities/screener`, `/api/v1/portfolios`. +Expected: prints `Swagger paths still OK`. - [ ] **Step 6: Проверить artifact test теперь зелёный** @@ -1111,7 +1100,7 @@ Expected: both commands exit 0. - [ ] **Step 8: Commit** ```bash -git add apps/frontend/src/api/types.ts docs/openapi/openapi.yaml apps/backend/src/openapi-artifacts.spec.ts apps/backend/src/modules +git add apps/frontend/src/api/types.ts apps/backend/src/openapi-artifacts.spec.ts apps/backend/src/modules git commit -m "docs: refresh openapi contract artifacts" ``` diff --git a/docs/features/quality-gate-contract-docs/spec.md b/docs/features/quality-gate-contract-docs/spec.md index 97c01e8..2d7e7ee 100644 --- a/docs/features/quality-gate-contract-docs/spec.md +++ b/docs/features/quality-gate-contract-docs/spec.md @@ -17,7 +17,7 @@ настоящий `MoexClientService`. - Ошибки live MOEX-запросов проявляются как Vitest `DataCloneError`, потому что `AxiosError` содержит функции в конфигурации запроса, которые нельзя клонировать между worker'ами. -- `docs/openapi/openapi.yaml` и `apps/frontend/src/api/types.ts` не содержат актуальные эндпоинты +- backend Swagger JSON по `/api/docs-json` и `apps/frontend/src/api/types.ts` не отражают актуальные эндпоинты `auth`, `portfolios` и `securities/screener`. - README, AGENTS и страницы Docusaurus местами описывают старое состояние репозитория. - `npm run build:docs` успешно генерирует статические файлы, но выводит предупреждения Docusaurus о @@ -78,7 +78,7 @@ - `apps/docs/docs/backend/api.md` не содержит portfolio и screener endpoints. - `apps/docs/docs/backend/portfolio.md` документирует `PATCH /api/v1/portfolios/:id/patch`, хотя controller реализует `PATCH /api/v1/portfolios/:id`. -- `docs/openapi/openapi.yaml` и `apps/frontend/src/api/types.ts` содержат только ранние paths для +- backend Swagger JSON по `/api/docs-json` и `apps/frontend/src/api/types.ts` содержат только ранние paths для health, search, shares, bonds и candles. ## Доменная модель @@ -110,7 +110,7 @@ decorators по `/api/docs-json`. Сгенерированные или синхронизированные артефакты: -- `docs/openapi/openapi.yaml`: checked-in человекочитаемый snapshot. +- `/api/docs-json`: live Swagger JSON, канонический machine-readable contract. - `apps/frontend/src/api/types.ts`: сгенерированные TypeScript path и schema types. - Docusaurus API pages: поясняющая документация, но не канонический machine contract. @@ -276,7 +276,7 @@ broken links на `/`. Отдельное update-check warning про permission 1. Добавить или завершить Swagger metadata для актуальных routes. 2. Перегенерировать `apps/frontend/src/api/types.ts`. -3. Синхронизировать `docs/openapi/openapi.yaml` с текущим contract. +3. Проверить `/api/docs-json` и синхронизировать `apps/frontend/src/api/types.ts` с текущим contract. 4. Проверить, что generated paths включают auth, screener и portfolio routes. ### Этап 3: обновить документацию @@ -311,7 +311,7 @@ npm run format:check `/`. - `npm run format:check` завершается с exit code 0. - `apps/frontend/src/api/types.ts` содержит актуальные auth, screener и portfolio paths. -- `docs/openapi/openapi.yaml` содержит актуальные auth, screener и portfolio paths. +- `/api/docs-json` содержит актуальные auth, screener и portfolio paths. - README, AGENTS и Docusaurus docs больше не утверждают, что frontend tests отсутствуют. - Portfolio docs используют `PATCH /api/v1/portfolios/:id`, что соответствует controller. diff --git a/docs/features/russian-docs-and-architecture-diagrams/spec.md b/docs/features/russian-docs-and-architecture-diagrams/spec.md index ea299df..97d61c6 100644 --- a/docs/features/russian-docs-and-architecture-diagrams/spec.md +++ b/docs/features/russian-docs-and-architecture-diagrams/spec.md @@ -7,8 +7,8 @@ ## Контекст Документация проекта публикуется только из `apps/docs` через Docusaurus. Текущая структура уже -зафиксирована в `docs/superpowers/specs/2026-06-13-docusaurus-docs-design.md`: страницы лежат в -`apps/docs/docs`, навигация описана в `apps/docs/sidebars.ts`, Mermaid включён через +зафиксирована в `docs/features/docusaurus-docs/spec.md`: страницы лежат в `apps/docs/docs`, +навигация описана в `apps/docs/sidebars.ts`, Mermaid включён через `@docusaurus/theme-mermaid`. Сейчас большая часть человекочитаемого текста в опубликованной документации написана на английском: diff --git a/docs/features/security-screener/spec.md b/docs/features/security-screener/spec.md index 921cf96..985de71 100644 --- a/docs/features/security-screener/spec.md +++ b/docs/features/security-screener/spec.md @@ -455,7 +455,7 @@ Phase 1 не требует событий. Для будущих фаз: ## 10. OpenAPI Specification -Дополнение к существующему `docs/openapi/openapi.yaml`: +Дополнение к текущему backend OpenAPI-контракту по `/api/docs-json`: ```yaml paths: