docs(frontend): add infrastructure hardening plan
This commit is contained in:
parent
3e054ee6c4
commit
5b8bf1c4b4
120
docs/features/frontend-infrastructure-hardening/plan.md
Normal file
120
docs/features/frontend-infrastructure-hardening/plan.md
Normal file
@ -0,0 +1,120 @@
|
||||
# Frontend Infrastructure Hardening Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Stabilize frontend infrastructure and tooling so local development, contract freshness, and mock-based workflows are deterministic and do not rely on temporary compatibility layers.
|
||||
|
||||
**Architecture:** This feature is a small set of related infrastructure follow-ups executed in a controlled order: mock-mode docs and wiring, env validation, tooling consistency, and contract freshness. Each step should leave the project in a working state and avoid changing user-facing runtime behavior except where the infrastructure itself must be activated.
|
||||
|
||||
**Tech Stack:** Vite, MSW, Zod, Biome/ESLint, OpenAPI-generated types, existing frontend tooling scripts.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Browser mock mode wiring
|
||||
|
||||
**Files:**
|
||||
- Create/Modify: `apps/frontend/mocks/browser.ts`
|
||||
- Modify: `apps/frontend/public/mockServiceWorker.js`
|
||||
- Modify: `apps/frontend/src/main.tsx`
|
||||
- Modify: `apps/frontend/src/shared/config/env.ts`
|
||||
- Modify: `apps/docs/docs/development/commands.md`
|
||||
- Modify: `apps/docs/docs/frontend/overview.md`
|
||||
|
||||
- [ ] **Step 1: Add a browser MSW entry that reuses existing handlers**
|
||||
|
||||
Ensure the browser worker uses the existing `apps/frontend/mocks/handlers.ts` instead of duplicating request logic.
|
||||
|
||||
- [ ] **Step 2: Gate worker startup behind `VITE_API_MOCK`**
|
||||
|
||||
Hook the browser mock startup into `main.tsx` so it activates only when the env flag explicitly asks for it.
|
||||
|
||||
- [ ] **Step 3: Document the mock mode behavior**
|
||||
|
||||
Document the developer-facing rule: mock mode is opt-in, backend-free dev is supported, and the default path still uses the real API.
|
||||
|
||||
### Task 2: Env validation
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/frontend/src/shared/config/env.ts`
|
||||
- Modify: `apps/frontend/src/main.tsx`
|
||||
- Test: any existing frontend startup/env tests, if present
|
||||
|
||||
- [ ] **Step 1: Define the runtime env schema**
|
||||
|
||||
Add a Zod schema for required `VITE_*` variables and keep optional values explicit.
|
||||
|
||||
- [ ] **Step 2: Fail fast on invalid env**
|
||||
|
||||
Call validation before app render so invalid configuration is visible at startup instead of failing later in a component or query path.
|
||||
|
||||
- [ ] **Step 3: Verify startup messaging**
|
||||
|
||||
Make sure the error path explains what is missing or invalid without leaking secrets.
|
||||
|
||||
### Task 3: Tooling consistency
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/frontend/package.json`
|
||||
- Modify: `apps/frontend/.eslintrc.cjs` or `apps/frontend/biome.json` if the project already has a replacement config
|
||||
- Modify: `.gitea/workflows/ci.yml` only if the current tooling commands need to be aligned
|
||||
- Modify: `apps/docs/docs/development/commands.md`
|
||||
|
||||
- [ ] **Step 1: Verify the command set matches the current toolchain**
|
||||
|
||||
Keep `lint`, `test`, `build`, and `codegen` aligned with the real frontend structure and remove stale command references.
|
||||
|
||||
- [ ] **Step 2: Align lint/format docs with reality**
|
||||
|
||||
Update documentation so it describes the actual commands developers run today, not an earlier migration stage.
|
||||
|
||||
- [ ] **Step 3: Confirm no stale tooling references remain**
|
||||
|
||||
Remove or rewrite mentions of dead scripts, obsolete shims, or incorrect setup instructions.
|
||||
|
||||
### Task 4: Contract freshness
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/frontend/src/shared/api/index.ts`
|
||||
- Modify: `apps/frontend/src/shared/api/types.ts` only through codegen, not manual edits
|
||||
- Modify: the specific frontend entity API files that still depend on stale wrapper assumptions
|
||||
- Modify: `apps/docs/docs/frontend/api-client.md`
|
||||
- Modify: `apps/docs/docs/frontend/overview.md`
|
||||
|
||||
- [ ] **Step 1: Reconcile the frontend contract entrypoints**
|
||||
|
||||
Ensure the shared API surface points to the actual generated contract types and current public API entrypoints.
|
||||
|
||||
- [ ] **Step 2: Remove stale contract wording from docs**
|
||||
|
||||
Document the current source of truth for API types and avoid references to temporary compatibility layers.
|
||||
|
||||
- [ ] **Step 3: Verify generated types are treated as generated**
|
||||
|
||||
Make sure the plan keeps `types.ts` as generated output and avoids manual editing patterns.
|
||||
|
||||
### Task 5: Verification
|
||||
|
||||
**Files:**
|
||||
- Read: changed docs and frontend tooling files
|
||||
|
||||
- [ ] **Step 1: Run the targeted frontend checks**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
npm run lint -w apps/frontend
|
||||
npm run test -w apps/frontend
|
||||
npm run build -w apps/frontend
|
||||
```
|
||||
|
||||
Expected: all three commands pass after the infra hardening changes land.
|
||||
|
||||
- [ ] **Step 2: Check mock mode manually**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
VITE_API_MOCK=true npm run dev -w apps/frontend
|
||||
```
|
||||
|
||||
Expected: frontend starts with browser MSW available and does not require the backend for the basic local flow.
|
||||
34
docs/features/frontend-infrastructure-hardening/tasks.md
Normal file
34
docs/features/frontend-infrastructure-hardening/tasks.md
Normal file
@ -0,0 +1,34 @@
|
||||
# Frontend Infrastructure Hardening — tasks
|
||||
|
||||
Статус: pending
|
||||
|
||||
## 1. Включить browser mock mode
|
||||
|
||||
- [ ] Добавить `apps/frontend/mocks/browser.ts` с `setupWorker`
|
||||
- [ ] Подключить worker в `apps/frontend/src/main.tsx` через `VITE_API_MOCK`
|
||||
- [ ] Обновить frontend docs, чтобы явно описать mock-free vs mock-enabled dev flow
|
||||
|
||||
## 2. Валидация env
|
||||
|
||||
- [ ] Описать обязательные `VITE_*` переменные в `apps/frontend/src/shared/config/env.ts`
|
||||
- [ ] Провалить старт приложения на невалидной конфигурации до рендера
|
||||
- [ ] Проверить, что сообщение об ошибке не раскрывает секреты
|
||||
|
||||
## 3. Tooling consistency
|
||||
|
||||
- [ ] Проверить `apps/frontend/package.json` и синхронизировать скрипты с текущим состоянием проекта
|
||||
- [ ] Обновить docs, где перечислены команды разработки, lint и build
|
||||
- [ ] Удалить или переписать устаревшие упоминания старых миграционных шагов
|
||||
|
||||
## 4. Contract freshness
|
||||
|
||||
- [ ] Привести frontend API docs к текущему source of truth
|
||||
- [ ] Проверить, что generated types остаются generated, а не редактируются вручную
|
||||
- [ ] Убедиться, что frontend shared API entrypoints не ссылаются на устаревшие слойные соглашения
|
||||
|
||||
## 5. Финальная проверка
|
||||
|
||||
- [ ] Запустить `npm run lint -w apps/frontend`
|
||||
- [ ] Запустить `npm run test -w apps/frontend`
|
||||
- [ ] Запустить `npm run build -w apps/frontend`
|
||||
- [ ] Проверить `VITE_API_MOCK=true npm run dev -w apps/frontend` на локальном старте без backend
|
||||
Loading…
x
Reference in New Issue
Block a user