nomadcode/agent-ops/rules/project/domain/web/rules.md

domain	last_rule_review_commit	last_rule_updated_at
web	e3b5dae725	2026-05-21

web

목적 / 책임

NomadCode의 이전 React/Vite 브라우저 운영 콘솔 scaffold 도메인이다. Flutter-first 전환 이후 장기 제품 UI 경로에서는 제외하며, 이 도메인의 작업은 제거, 격리, 또는 legacy 상태 보존에 한정한다.

포함 경로

• apps/web/src/app/ — React app과 router 조립.
• apps/web/src/routes/ — 페이지 단위 route.
• apps/web/src/layout/ — shell, navigation, sidebar.
• apps/web/src/components/ — agent, project, settings, common UI components.
• apps/web/src/stores/ — Zustand 기반 client state.
• apps/web/src/api/ — backend API client.
• apps/web/src/styles/ — global style.
• apps/web/index.html, apps/web/.env.example — Vite HTML entry와 환경 변수 예시.
• apps/web/package.json, apps/web/package-lock.json, apps/web/vite.config.ts, apps/web/tsconfig.json — web build/tooling.

제외 경로

• services/core/ — API implementation과 persistence는 core 도메인이다.
• apps/mobile/ — Flutter 제품 UI source of truth는 mobile 도메인이다.
• packages/contracts/ — shared schema/source-of-truth는 contracts 도메인이다.

주요 구성 요소

• src/app/App.tsx — QueryClient와 router provider 조립.
• src/app/router.tsx — web route 구성.
• src/layout/AppShell.tsx — 전체 shell.
• src/layout/AgentSidebar.tsx — agent context/sidebar 영역.
• src/routes/AgentPage.tsx — agent workspace page.
• src/routes/ProjectsPage.tsx — project workspace page.
• src/routes/SettingsPage.tsx — integration settings page.
• src/stores/agentStore.ts — agent interaction state.
• src/stores/layoutStore.ts — shell navigation/sidebar state.
• src/stores/projectStore.ts — project workspace state.
• src/api/client.ts — API 호출 공통 client.
• src/components/settings/IntegrationStatus.tsx — integration 상태 표시와 테스트 액션 UI.

유지할 패턴

• 새 제품 기능을 React web에 추가하지 않는다.
• 제거 전 legacy 유지가 필요한 경우 기존 src/routes, src/layout, src/components, src/api, src/stores 구조를 유지한다.
• API 호출 형태가 바뀌면 Flutter 앱과 contracts/core 경계를 우선 확인하고, legacy web 변경은 필요한 최소 범위로 제한한다.
• legacy scaffold를 직접 수정할 때는 npm run check가 통과하도록 TypeScript type을 유지한다.

다른 도메인과의 경계

• core: web은 core의 HTTP/API surface만 사용한다.
• contracts: 반복되는 request/response shape는 contracts 후보로 올린다.
• mobile: Flutter 앱이 제품 UI source of truth이며, web은 제품 UI 구현을 복제하지 않는다.
• workspace-ops: root bin/*나 monorepo 문서는 web 변경과 분리한다.

금지 사항

• core 내부 구조를 web 컴포넌트에 하드코딩하지 않는다.
• 새 제품 화면을 React web에 추가하지 않는다.
• API mock과 실제 API shape를 장기간 다르게 유지하지 않는다.
• 공통 UI component에 page-specific side effect를 넣지 않는다.
• 대규모 visual/style 변경과 API behavior 변경을 한 커밋에 섞지 않는다.