chore: snapshot local state before dev merge

docs/make-dev-vite-hmr-policy.md

@@ -0,0 +1,78 @@
+# make dev Vite HMR Policy
+
+`make dev`는 로컬 개발 중 소스 변경이 즉시 화면에 반영되는 환경이어야 합니다. `adminfront`, `devfront`, `orgfront`는 `make dev`에서 production `dist`를 정적 서빙하지 않고 Vite dev server로 실행합니다.
+
+## Policy
+
+- `make dev`로 실행되는 React frontends는 Vite HMR 모드여야 합니다.
+- 대상 서비스는 `adminfront`, `devfront`, `orgfront`입니다.
+- 각 서비스는 Docker Compose에서 해당 Dockerfile의 `dev` target으로 빌드해야 합니다.
+- 각 서비스의 working directory는 bind-mounted source path인 `/workspace/<app>`이어야 합니다.
+- 각 서비스 command는 `npm run dev -- --host 0.0.0.0 --port <port>` 형태여야 합니다.
+- Docker bind mount 환경에서 파일 변경 감지가 누락되지 않도록 `DEV_SERVER_WATCH_POLLING=true`가 기본값이어야 합니다.
+- production image는 기존처럼 `production` target에서 build output `dist`를 `serve_frontend_prod.mjs`로 정적 서빙할 수 있습니다. 이 정책은 `make dev` runtime에만 적용합니다.
+
+## Current Ports
+
+- AdminFront: `http://localhost:5173`
+- DevFront: `http://localhost:5174`
+- OrgFront: `http://localhost:5175`
+
+## Required Structure
+
+Each React frontend Dockerfile must keep these stages:
+
+- `deps`: install workspace dependencies.
+- `dev`: run Vite dev server from `/workspace/<app>`.
+- `build`: run production build.
+- `production`: serve built `dist` with the static server.
+
+`docker-compose.yaml` must select `target: dev` for the three React frontends. This prevents `make dev` from accidentally serving stale `/app/dist` output.
+
+## Regression Guard
+
+The policy is checked by:
+
+```sh
+test/frontend_dev_bind_mount_policy_test.sh
+test/playwright_frontend_runtime_policy_test.sh
+```
+
+The test verifies that:
+
+- source directories are bind-mounted into `/workspace/<app>`;
+- `node_modules` stays in container volumes;
+- each React frontend uses `target: dev`;
+- each React frontend runs `npm run dev`;
+- each React frontend enables polling watch by default;
+- `serve_frontend_prod.mjs` is not used by the Compose dev service;
+- Dockerfiles keep separate `dev`, `build`, and `production` stages.
+
+If this test fails, do not work around it by refreshing the browser or rebuilding manually. Fix the Compose/Dockerfile runtime so `make dev` remains a true HMR development mode.
+
+## Playwright Runtime Policy
+
+Local Playwright tests should use Vite dev servers by default. This keeps local E2E feedback aligned with `make dev` and avoids testing stale production `dist` output while actively editing frontend code.
+
+Gitea Actions and other CI runs should use build output through Vite preview. This validates production bundle behavior before merge.
+
+Required behavior:
+
+- Local default:
+  - AdminFront uses Vite dev server on port `5173`.
+  - DevFront uses Vite dev server on port `5174`.
+  - OrgFront uses Vite dev server on port `5175`.
+- CI or explicit preview mode:
+  - `CI=true` or `PLAYWRIGHT_USE_PREVIEW=true` switches React frontend Playwright web servers to `build` + `preview`.
+- Existing running server mode:
+  - `BASE_URL` can be used for AdminFront and OrgFront.
+  - `PLAYWRIGHT_BASE_URL` or `BASE_URL` can be used for DevFront.
+  - `PLAYWRIGHT_SKIP_WEBSERVER=true` disables DevFront's managed web server.
+
+Use explicit preview locally only when testing production bundle behavior:
+
+```sh
+PLAYWRIGHT_USE_PREVIEW=true npm --prefix adminfront test
+PLAYWRIGHT_USE_PREVIEW=true npm --prefix devfront test
+PLAYWRIGHT_USE_PREVIEW=true npm --prefix orgfront test
+```