46 lines
9.3 KiB
Markdown
46 lines
9.3 KiB
Markdown
## Generated Next.js Repository Rules
|
|
|
|
- This frontend application was generated by `@kri/create-next-app`.
|
|
- Keep the generated Next.js routing, server/client boundary, authentication, environment, state, query, and application-shell conventions unless an approved task changes them.
|
|
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
|
|
- Do not create new TypeScript type or interface names ending in `Dto` or `DTO`.
|
|
- Consume shared frontend behavior from `@kri/common` and the KRI UI Registry instead of copying provider implementations into this repository.
|
|
- `AGENTS.md` and `CLAUDE.md` are central-harness generated outputs. Never edit them directly; update `.agent/profile.yml` or `.agent/project.md` and recompose.
|
|
- Run `npm run typecheck` and `npm run build` after relevant source or configuration changes.
|
|
|
|
|
|
## KART basic frontend wiring
|
|
|
|
- New backend only; development front 4014/backend 4015/api/v1. Use published @kri/common HTTP and persistent hydratedAtom plus TanStack Query; do not add axios or duplicate common storage/auth helpers. Repository package.json and lockfile are authoritative for versions. Add dependencies only after user approval; preserve existing chart, drag-and-drop and registry integrations.
|
|
- Next stores the 24-hour token in an HttpOnly cookie and returns validated LoginUser only. Secure for ENV prod/production. Backend logout/session endpoints do not exist: Next logout clears its cookie, client auth and query cache. BFF accepts only fixed implemented project reads and whitelisted query fields; never trust browser role/id headers or send API keys to the browser.
|
|
- Basic routes are /, /login, /logout and project pages without query parameters (/Report/Current, /Report/Quota, /Report/Tabulation, /Report/Crosstab, /Management/Derived, /Management/Exim). The selected project {projectType, pkey} lives in the user-scoped persistent atom `useSelectedProject` (localStorage, like legacy ptokenState); home, login and logout clear it. Address parameters never select a project: old `?projectType=0|1&pkey=rawKey` links are ignored, and sharing is only through generated Page Copy/URL Copy links. This is not access control; server project scope is authoritative. Preserve pkey case and use projectType+pkey in query keys and BFF paths, with current user id/role/team in query keys. Runtime-validate data, use existing UI components, retain raw server count/LOI semantics and display-only padded date cleanup. Keep loading/error/empty/retry states.
|
|
- Basic progress uses type/loi/day/screen; date filters affect type/loi/screen, never day, matching the server. Logging is a best-effort /log/visit call with server cookie identity, no /log/site HTTP.
|
|
- The second migration phase is closed. Until the user explicitly announces launch, this application is unlaunched and old External token compatibility is unnecessary. The user performs every operation that writes to the shared database (live login, bookmark/derived saves, imports, share issuance and External login) and live Excel generation checks. No shared DB calls in local validation. Phase closure does not certify unexecuted live checks.
|
|
- ReportMember/URL Copy/Page Copy roles are 9001/9002/9003. External login replaces the prior identity; validate the server-returned user and link together. Keep the link's project and page scope, disable project-list/summary reads, and use the link title. Page Copy has no GNB menus; URL Copy has only the four report menus. Hide logo navigation, Logout, project selection, Copy and bookmark writes. Bookmark reads and aggregate/Quota Excel remain allowed; server scope enforcement is authoritative.
|
|
- Export/Import APIs intentionally have no ordinary-user role restriction. Their menu restriction (userRole === 1001 || userTeam === "R701") is temporary UX policy. Do not ask the server to add a role restriction; External access remains blocked by its interceptor.
|
|
|
|
## KART report streaming UI
|
|
|
|
- Tabulation/Crosstab use published common streamPost and TanStack Query. Disable global loading for long report mutations and retain inline progress/cancel. Forward NDJSON without buffering; validate ordered positions, per-item errors and terminal counts. Preserve partial results on cancellation or failure.
|
|
- Ordinary tabulation retains the legacy separate TABULATION_0 characteristic request, then one selected-index batch. Keep backend filter/banner/options contracts; the screen shows the legacy default display (percent cells, N on the base line) with no N/% toggle. Render server merge metadata and statistic/word results without reaggregation. Preserve project/user scope during navigation and abort old requests on scope changes.
|
|
|
|
## KART UI and data compatibility
|
|
|
|
- Preserve existing KART UI, colors and workflows; simple CSS is acceptable when the rendered result matches. Do not add controls or features absent from the original without approval. Legacy source is `../KART_FRONT/Report_React`; current backend contracts come from `../kart-server` controller, DTO and service sources, not historical migration notes or mocks.
|
|
- Reuse project components before adding primitives. Do not overwrite locally edited registry copies or upgrade KriUiRegistry without approval. Use self-hosted Noto Sans/Noto Sans KR (`src/app/fonts.css`, `public/fonts`) and existing `globals.css` tokens; charts and word clouds wait for `useChartFont` readiness. Mobile mode uses `(hover: none) and (pointer: coarse), (max-width: 767px)` (touch device at any width, or any window ≤767px): Cross Tab shows bookmarks only, Tabulation/Derived/Exim show PcOnlyNotice, Quota/Current stay normal. Do not port legacy width-only hiding (media.css ≤1300/≤1050); mouse/trackpad windows wider than 767px keep full editing.
|
|
- Preserve empty/loading/error/retry states. Global loading uses `LoadingOverlayAdapter`; long statistics streams and Quota queries use inline loading with `meta.ignoreGlobalLoading`. Keep dnd-kit `DragOverlay` dropAnimation=null.
|
|
- Display server count/percent/statistic strings without browser reaggregation or rounding. The legacy default shows percent in ordinary cells and N on the base line (TOTAL row, or TOTAL column when transposed). Preserve the empty top-left result cell and server merge metadata; do not fill it with the result title.
|
|
- Excel must preserve the existing workbook layout, cell types, merges, sheet ordering, links and images. Send `percentExact`/`statisticExact` for numeric cells, count strings for N, and the hidden TABULATION_0 table first. Use existing `report-excel.ts`, `download-name.ts` and download BFF helpers. Error responses must not become downloaded files. Use FormData/postForm without manually setting multipart boundaries.
|
|
- BOOKMARK_JSON is shared with legacy KART. Keep INDEX, BANNER, FILTER_CONDITION, REAL_FILTER_CONDITION, FILTER_ARRAY and OPTION semantics; `lib/bookmark-json.ts` owns the conversion. Preserve untouched filter strings and existing option keys. Tabulation bookmark application clears results without running; Crosstab reaggregates. Saving a bookmark preserves current results. Bookmark update/delete ownership remains server-enforced.
|
|
- Derived variables use single|multi|scale|num and preserve DERIVEDJSON field semantics. Do not expose recalculation BFF routes. Save responses are text and use expectText=true; invalidate question metadata after writes. Preserve the server role/team checks.
|
|
|
|
## Validation and local safety
|
|
|
|
- Do not start or stop the user's frontend 4014 or backend 4015. Migration test files and their npm scripts were removed at the user's request. Do not invoke retired test commands or substitute real backend calls. If runtime validation needs a new mock harness, discuss its scope first; always stop owned validation processes afterwards.
|
|
- For relevant source changes run `npm run typecheck`, changed-file `npx eslint <files>`, and `npm run build`. Do not format the entire repository. Known whole-project lint errors in unchanged KriEditorWysiwyg.tsx must be distinguished from new failures.
|
|
- Verify visible UI with Playwright and the installed Chrome (`channel: "chrome"`), normally at 1920x1080, plus relevant smaller widths. Check bounding boxes and visibility, not DOM existence alone. HTTP tests do not prove visual equivalence or real-data correctness.
|
|
- Keep temporary scripts, screenshots and extracted Excel comparisons outside the repository in the OS temporary directory; remove them when finished. Do not capture real free-text responses. Never retain credentials or real data in reports or source control.
|
|
- Preserve encoding, BOM and line endings. Read Korean text explicitly as UTF-8 in PowerShell; verify bytes before treating terminal mojibake as file corruption. After edits check UTF-8 validity, BOM, line endings, U+FFFD and unrelated changes. Run `.agent/tools/check-encoding.ps1` when present.
|
|
- `useSearchParams` consumers require Suspense. Common HTTP parses JSON content types; use expectText=true for text responses. Do not remove `.next/dev/types` while the user's dev server is running; investigate stale generated route references without disrupting that server.
|
|
- Harness project ID is `kart-front-next`. Use the workspace AgentHarnessBase `scripts/agent-harness.cmd`: plan, compose, then verify --project kart-front-next after routing or composed-source changes. For reference-only changes with unchanged routing, verify is sufficient. Never edit AGENTS.md or CLAUDE.md directly.
|