ํ๋๊ทธ๋ฆฐํธ๋์ ๋ค์ค ํ๋งค์ฑ๋ ์ฌ๊ณ ๋ฅผ ํตํฉ ์กฐํํ๊ณ ์ํ ์ฌ๊ณ ์ AI ์คํ ์ ๋ต์ ๊ด๋ฆฌํ๊ธฐ ์ํ B2B ์ด์ ํ๋ซํผ์ ํ๋ก ํธ์๋ ๊ธฐ๋ฐ์ ๋๋ค.
- AI ์ ๋ต ์ฑ๊ณผ์ ์ํ์ฌ๊ณ ์ถ์ด๋ฅผ ์ค์ ํต๊ณ API์ ์ฐ๊ฒฐํ์ต๋๋ค.
- ๊ธฐ๊ฐยท์ฌ๊ณ ์์น ํํฐ์ ์ฑ๊ณผ ์งํยท์ถ์ด ์ฐจํธ๋ฅผ ์ ๊ณตํฉ๋๋ค.
ํตํฉ ์ฌ๊ณ ์กฐํ์ ๋ก์ปฌ feature ๋ฒ์๋ ๊ตฌํ๋์ด ์์ต๋๋ค. ์ฑ ์ ธ, ๋ผ์ฐํฐ, FSD-lite ํด๋ ๊ตฌ์กฐ, HTTP ํต์ ๊ฒฝ๊ณ, ๋์์ธ ํ ํฐ, ์ฌ์ฌ์ฉ UI, Storybook, ํ ์คํธ์ CI ๊ธฐ๋ฐ์ด ๊ตฌ์ฑ๋์ด ์์ผ๋ฉฐ, ์ค์ source syncยทOracle ๋ฐ์์ ๋ณ๋ ํ์ ๋ฒ์์ ๋๋ค.
ํตํฉ ์ฌ๊ณ ์ ๋ฌผ๋ฆฌ ์คํค๋ง๋ BackEnd Flyway V1~V16์ด ์ฐ์ ํฉ๋๋ค. ํ๋ฉด์์๋ on_hand_qty ์ง๊ณ๋ฅผ ๊ฐ์ฉ์ฌ๊ณ , reserved_qty ์ง๊ณ๋ฅผ ์์ฝ์ฌ๊ณ , ๋ ๊ฐ์ ํฉ์ธ total_qty๋ฅผ ์ด์ฌ๊ณ ๋ก ํ์ํ๋ฉฐ FrontEnd๊ฐ ์์ฝ์๋์ ๋ค์ ์ฐจ๊ฐํ์ง ์์ต๋๋ค. ์ธ๋ถ ์ ํฉ์ฑ ์์
์ workspace์ ../docs/integrated-inventory/SCHEMA-FLYWAY-WORKLIST.md๋ฅผ ๊ธฐ์ค์ผ๋ก ํฉ๋๋ค.
Spring Security ์ธ์ ๋ก๊ทธ์ธ๊ณผ ํ์ฌ ์ฌ์ฉ์ ์กฐํ ๊ณ์ฝ์ ์ฐ๊ฒฐํ์ผ๋ฉฐ, ์ธ๋ถ ๊ถํ ์ ์ฑ , ์ฌ๊ณ ์กฐํยทํ์ด์ง๋ค์ด์ ๊ณผ ๋ฐฐํฌ ํ๊ฒฝ์ ๊ธฐ๋ฅ ๋๋ ์ด์ ๋จ๊ณ์์ ํ์ ํฉ๋๋ค. ๊ณตํต ๊ฐ๋ฐ ํ๊ฒฝ, lintยทformat, ํ ์คํธ์ PR ์๋ ๊ฒ์ฆ์ ์ด ์ ์ฅ์์ ํฌํจ๋์ด ์์ต๋๋ค.
์ฒ์ ์ฐธ์ฌํ๋ ํ์์ ๋จผ์ docs/team-onboarding.md๋ฅผ ์์๋๋ก ์งํํฉ๋๋ค. ํ์์ด ์ดํดํ๊ธฐ ์ฝ๊ฒ ์ค๋ช
ํ ๋๋ docs/team-frontend-handbook.md๋ฅผ ์ฌ์ฉํ๊ณ , ํ ํฐยท์ปดํฌ๋ํธยทAPI์ ์์ธ ๊ธฐ์ค์ docs/frontend-foundation-team-guide.md์์ ํ์ธํฉ๋๋ค.
ํ์ ๋ฒ์ ์ Node.js 24 LTS์ pnpm 11.18.0์
๋๋ค. .nvmrc, package.json, CI๊ฐ ๋ชจ๋ ๊ฐ์ ๋ฒ์ ์ ๊ธฐ์ค์ผ๋ก ํฉ๋๋ค.
node --version
corepack enable
pnpm --version
pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm exec playwright install chromium
pnpm run check
pnpm run test:e2e
pnpm devnode --version:v24.xpnpm --version:11.18.0- ์ฑ:
http://localhost:5173 - Storybook:
pnpm storybook์คํ ํhttp://localhost:6006
Windows PowerShell์์๋ ํ๊ฒฝ ํ์ผ์ Copy-Item .env.example .env.local๋ก ๋ณต์ฌํฉ๋๋ค. ๋ชจ๋ ๊ฐ์ ๋ก์ปฌ ๊ธฐ๋ณธ๊ฐ์ด ์์ผ๋ฏ๋ก ์ฒซ ์คํ์์๋ .env.local์ ๊ฐ์ ๊ทธ๋๋ก ๋์ด๋ ๋ฉ๋๋ค.
PR ์ ํ์ ๊ฒ์ฆ:
pnpm run audit:prod
pnpm run check
pnpm run test:e2e
pnpm run build-storybook์ด์ ํ๋ก ํธ์๋๋ Jenkins๊ฐ main ๋ณ๊ฒฝ์ Poll SCM์ผ๋ก ํ์ธํ ๋ค dist/๋ฅผ
Amazon S3์ ๋๊ธฐํํ๊ณ CloudFront ์บ์๋ฅผ ๋ฌดํจํํฉ๋๋ค. Jenkins Job, EC2 IAM Role,
S3 ๋ฐ CloudFront ๊ฐ ์ค์ ์ ํ๋ก ํธ์๋ Jenkins ๋ฐฐํฌ ๊ฐ์ด๋๋ฅผ
์ฐธ๊ณ ํฉ๋๋ค.
pnpm run audit:prod๋ high ์ด์ ์ด์ ์์กด์ฑ ์ทจ์ฝ์ ์ ํ์ธํฉ๋๋ค. pnpm run check๋ ESLint, Prettier ๊ฒ์ฌ, Vitest, production build๋ฅผ ์์๋๋ก ์คํํฉ๋๋ค. GitHub์์๋ PR๋ง๋ค ๊ฐ์ ๊ฒ์ฌ์ Storybook build, Playwright๋ฅผ ์คํํฉ๋๋ค.
ํ๊ฒฝ๋ณ์๋ .env.example์ ๊ธฐ์ค์ผ๋ก .env.local์ ์์ฑํฉ๋๋ค. VITE_๊ฐ ๋ถ์ ๊ฐ์ ๋ธ๋ผ์ฐ์ ๋ฒ๋ค์ ๋
ธ์ถ๋๋ฏ๋ก ๋น๋ฐ๋ฒํธ, ์ธ์
๊ฐ, AWS ํค์ ๊ฐ์ secret์ ๋ฃ์ง ์์ต๋๋ค.
| ๊ฒฝ๋ก | ํ๋ฉด | ํ์ฌ ๋ฒ์ |
|---|---|---|
/login |
๋ก๊ทธ์ธ | CSRF ๋ฐ๊ธ, ์ธ์ ๋ก๊ทธ์ธ, ์ค๋ฅ ์ํ ์ฐ๊ฒฐ |
/dashboard |
๋์๋ณด๋ | ๊ธฐ๋ณธ ํ์ด์ง์ ์ฑ ์ ธ ์ฐ๊ฒฐ |
/inventory |
ํตํฉ ์ฌ๊ณ ์กฐํ | ๋ชฉ๋กยทํํฐยท์์ธยทLOTยท์์์์ธกยท์ํยท๊ฐ๊ฒฉยท๋ฏธํ ๋น ์ฌ๊ณ ๊ตฌํ, source sync๋ ์ค๋น ์ค |
/ai-strategy |
AI ์ ๋ต ๋ฐ ์๋ฎฌ๋ ์ด์ | ๊ธฐ๋ณธ ํ์ด์ง ์ฐ๊ฒฐ |
/execution |
AI ์ ๋ต ๊ธฐ๋ก & ์ฑ๊ณผ | ๊ธฐ๋ณธ ํ์ด์ง ์ฐ๊ฒฐ |
/statistics |
ํต๊ณ | ๊ธฐ๋ณธ ํ์ด์ง ์ฐ๊ฒฐ |
/heendi-loader |
๋ก๋ฉ ๋ชจ์ ํ์ธ | MP4 ๋ ํผ๋ฐ์ค์ Lottie ์คํผ๋ ๋น๊ต |
๋ก๊ทธ์ธํ์ง ์์ ์ฌ์ฉ์๊ฐ ๋ฃจํธ(/) ๋๋ ์
๋ฌด ๊ฒฝ๋ก์ ์ ๊ทผํ๋ฉด /login์ผ๋ก ์ด๋ํฉ๋๋ค. ๋ก๊ทธ์ธ ํ ๋ฃจํธ๋ /dashboard๋ก ์ด๋ํ๋ฉฐ, ์ฌ์ฉ์๊ฐ ๋จผ์ ์ ๊ทผํ ์
๋ฌด ๊ฒฝ๋ก๊ฐ ์์ผ๋ฉด ํด๋น ๊ฒฝ๋ก๋ก ๋์๊ฐ๋๋ค. ๋ผ์ฐํธ ์ ์๋ src/app/router/router.jsx, ๋ฉ๋ด์ ๋จ์ผ ์ถ์ฒ๋ src/widgets/app-shell/model/navigation.js์
๋๋ค.
| ์์ญ | ๋ผ์ด๋ธ๋ฌ๋ฆฌ | ์ญํ ๊ณผ ์ฌ์ฉ ๊ธฐ์ค | ํ์ฌ ์ํ |
|---|---|---|---|
| UI | React 19, JavaScript | ํจ์ ์ปดํฌ๋ํธ์ hooks ๊ธฐ๋ฐ UI | ๊ธฐ๋ฐ ์ฐ๊ฒฐ ์๋ฃ |
| ๋น๋ | Vite | ๊ฐ๋ฐ ์๋ฒ, ๋ฒ๋ค, @ โ src alias, ์ ํ์ /api proxy |
์๋ฃ |
| ํจํค์ง | pnpm | ์์กด์ฑ๊ณผ lockfile ๊ด๋ฆฌ | ์๋ฃ |
| ๋ผ์ฐํฐ | React Router DOM v7 | URL, ์ค์ฒฉ layout, ํ์ด์ง ์ด๋ | ์๋ฃ |
| ์๋ฒ ์ํ | TanStack Query v5 | ์๋ฒ ๋ฐ์ดํฐ ์บ์, ๋ก๋ฉยท์ค๋ฅ, ์ฌ์กฐํ, ๋ฌดํจํ | Provider์ query options ์์ ์๋ฃ |
| HTTP | Axios | base URL, timeout, ์ฟ ํค ์ ์ก, CSRF header, ์ค๋ฅ ์ ๊ทํ | ๊ณตํต client ์๋ฃ |
| ํด๋ผ์ด์ธํธ ์ํ | Zustand | ์ฌ๋ฌ ํ๋ฉด์ด ๊ณต์ ํ๋ UI ์ํ๋ง ๊ด๋ฆฌ | ์ค์น ์๋ฃ, ํ์ํ ๋ store ์์ฑ |
| ํผ | React Hook Form, Zod | ์ ๋ ฅ ์ํ, ๊ฒ์ฆ, ์ ์ถ ์ฒ๋ฆฌ | ๋ก๊ทธ์ธ ํผ ์ ์ฉ ์๋ฃ |
| ํ ์ด๋ธ | TanStack Table v8 | ์ปฌ๋ผยทํ ๋ชจ๋ธ๊ณผ ์ ๋ ฌ, ์ฌ์ฌ์ฉ ํ ์ด๋ธ ๊ป๋ฐ๊ธฐ | DataTable ์๋ฃ |
| ์ฐจํธ | Recharts | ์์์์ธก ๋ฐ ์ ๋ต ์ฑ๊ณผ ์๊ฐํ | ์์์์ธก ํญ ์ ์ฉ ์๋ฃ |
| ์คํ์ผ | Tailwind CSS v4 | layout๊ณผ token ๊ธฐ๋ฐ ์คํ์ผ๋ง | ์๋ฃ |
| UI ์์ค | shadcn/ui ๋ฐฉ์ | ์ฝ๋๋ฅผ ํ๋ก์ ํธ๊ฐ ์์ ํ๊ณ ๋์์ธ ํ ํฐ์ ๋ง์ถฐ ์์ | ์๋ฃ |
| ํด๋์ค ์กฐํฉ | cn, clsx, tailwind-merge |
์กฐ๊ฑด๋ถ class์ Tailwind ์ถฉ๋ ์ ๋ฆฌ | ์๋ฃ |
| variant | Class Variance Authority | Button, Badge์ฒ๋ผ ์๋ฏธ ์๋ variant ๊ด๋ฆฌ | ์๋ฃ |
| ์ ๊ทผ์ฑ primitive | Radix Slot, Tooltip | asChild, tooltip, ํค๋ณด๋ยทํฌ์ปค์ค ๊ธฐ๋ฐ |
์๋ฃ |
| ์์ด์ฝ | reicon-react |
์ฑ์์ ์ฌ์ฉํ๋ ์ ์ผํ ์์ด์ฝ ๋ผ์ด๋ธ๋ฌ๋ฆฌ | ์๋ฃ |
| ๋ชจ์ | lottie-web |
๊ณตํต Lottie ๋ก๋ฉ ์คํผ๋๋ฅผ ๋์ import๋ก ์ฌ์ | ์๋ฃ |
| UI ๋ฌธ์ | Storybook | ๋์์ธ ํ ํฐ๊ณผ ๊ณตํต ์ปดํฌ๋ํธ ์ํ ํ์ธ | ์๋ฃ |
| ๋จ์ ํ ์คํธ | Vitest | formatter, mapper, query key, ์ํ ๊ท์น ๊ฒ์ฆ | ๊ธฐ๋ฐ ์๋ฃ |
| E2E | Playwright | ๋ผ์ฐํ ๊ณผ ์ค์ ์ฌ์ฉ์ ํ๋ฆ ๊ฒ์ฆ | ๊ธฐ๋ฐ ์๋ฃ |
| ์ฝ๋ ํ์ง | ESLint, Prettier | ์ค๋ฅ ํ์ง์ ๊ณตํต ํฌ๋งท ๊ฒ์ฆ | ์๋ฃ |
| CI | GitHub Actions | PR๋ง๋ค lint, format, test, build, Storybook, E2E ๊ฒ์ฆ | ์๋ฃ |
@tanstack/react-virtual์ ์ค์นํ์ง ์์์ต๋๋ค. ์ด ์๋น์ค๋ ์๋ฒ ํ์ด์ง๋ค์ด์
์ ๊ธฐ๋ณธ์ผ๋ก ํ๋ฉฐ, ํ ํ์ด์ง์ ํ ์ ๋๋ฌธ์ ์ค์ ์ฑ๋ฅ ๋ฌธ์ ๊ฐ ํ์ธ๋ ๋๋ง ๋ณ๋๋ก ๋์
ํฉ๋๋ค. HTTP ํด๋ผ์ด์ธํธ๋ Axios๋ก ํต์ผํ๊ณ Ky ๊ด๋ จ ์ฝ๋๋ ์ฌ์ฉํ์ง ์์ต๋๋ค.
์ด ํ๋ก์ ํธ๋ Feature-Sliced Design์ ์ ๋ถ ์๊ฒฉํ๊ฒ ์ ์ฉํ์ง ์๊ณ , 4๋ช ์ ํ์คํ ํ์์ด ๋น ๋ฅด๊ฒ ์ดํดํ ์ ์๋ FSD-lite๋ก ์ฌ์ฉํฉ๋๋ค.
์ ์ฉํ๋ ์ด์ :
- ํ์ด์ง๊ฐ ๋์ด๋ UI, ๋๋ฉ์ธ ๊ท์น, ์ฌ์ฉ์ ํ๋, ์๋ฒ ํต์ ์ ์ฑ ์์ด ์์ด์ง ์๊ฒ ํฉ๋๋ค.
- ์ฌ๊ณ ์ํ, ํํฐ, ์์ธ Drawer์ฒ๋ผ ์ฌ๋ฌ ํ๋ฉด์์ ์ฌ์ฌ์ฉ๋๋ ๊ธฐ๋ฅ์ ์์น๋ฅผ ์์ธกํ ์ ์๊ฒ ํฉ๋๋ค.
- ํ ํ์ผ์ ํ์ด์ง ์ ์ฒด ๋ก์ง์ด ์์ด๋ ๊ฒ์ ๋ง๊ณ ํ์์ด ๋์์ ์์ ํ ๋ ์ถฉ๋ ๋ฒ์๋ฅผ ์ค์ ๋๋ค.
shared๊ฐ ์ฌ๊ณ ๋ ์ ๋ต ๊ฐ์ ๋๋ฉ์ธ์ ์์ง ๋ชปํ๊ฒ ํด ๊ณตํต ์ปดํฌ๋ํธ์ ์ฌ์ฌ์ฉ์ฑ์ ์ ์งํฉ๋๋ค.
์์กด์ฑ์ ์์์ ์๋ ๋ฐฉํฅ์ผ๋ก๋ง ํ๋ฆ ๋๋ค.
app โ pages โ widgets โ features โ entities โ shared
| ๊ณ์ธต | ์ญํ | ์ด ํ๋ก์ ํธ์ ์์ |
|---|---|---|
app |
์ฑ ์ ์ฒด ์๋ช ์ฃผ๊ธฐ์ ์กฐ๋ฆฝ | Provider, Router, AppLayout |
pages |
URL์ ๋์ํ๋ ์ต์ข ํ๋ฉด ์กฐํฉ | InventoryPage, DashboardPage |
widgets |
์ฌ๋ฌ featureยทentity๋ฅผ ๋ฌถ์ ๋ ๋ฆฝ ์ ๋ฌด ๋ธ๋ก | AppShell, InventoryTable, InventorySummary |
features |
์ฌ์ฉ์์ ํ ๊ฐ์ง ํ๋๊ณผ ๊ทธ ์ํ | inventory-filter, inventory-sync, inventory-detail |
entities |
๋๋ฉ์ธ ๋ฐ์ดํฐ, API, ํ์ ๊ท์น | inventory, product, sales-channel, strategy |
shared |
๋๋ฉ์ธ์ ๋ชจ๋ฅด๋ ๊ณตํต ๊ธฐ๋ฐ | UI primitive, Axios client, env, ์ ํธ๋ฆฌํฐ |
_template |
ํ์์ฉ ๊ตฌ์กฐ ์์ | ์ slice๋ฅผ ๋ง๋ค ๋ ์ฐธ๊ณ ํ๋ฉฐ ์ฑ์์ importํ์ง ์์ |
FSD๋ฅผ ์ต์ง๋ก ์ ์ฉํ์ง ์๋ ๊ธฐ์ค:
- ํ ํ์ด์ง์์๋ง ์ฐ๋ ์ฝ๋๋ ๋จผ์ ํด๋น
pages/<page>์์ ๋ก๋๋ค. - ๋ ๊ณณ ์ด์์์ ๊ฐ์ ์๋ฏธ์ ์ํ ๊ท์น์ผ๋ก ์ฌ์ฉ๋ ๋
widgets,features,entities๋ก ์ฌ๋ฆฝ๋๋ค. - ๋จ์ ๋ฐฐ์น๋ง ํ๋ ์ปดํฌ๋ํธ๋ฅผ ๋ฌด์กฐ๊ฑด widget์ผ๋ก ๋ง๋ค์ง ์์ต๋๋ค.
- ๋จ์ ํด๋ฆญ handler๋ฅผ ๋ฌด์กฐ๊ฑด feature๋ก ๋ง๋ค์ง ์์ต๋๋ค.
shared/ui์๋ ํ๋๊ทธ๋ฆฐํธ๋, ์ฌ๊ณ , LOT, ์ ๋ต ๊ฐ์ ๋๋ฉ์ธ ์ฉ์ด๋ฅผ ๋ฃ์ง ์์ต๋๋ค.- ๊ฐ slice ์ธ๋ถ์์๋ ๊ฐ๋ฅํ ํ
index.js๊ณต๊ฐ ์ง์ ์ ์ผ๋ก importํฉ๋๋ค.
src/
โโ app/
โ โโ providers/ # TanStack Query, Tooltip
โ โโ router/ # ์ ์ฒด route ์ ์
โ โโ layouts/ # ์ ์ญ widget๊ณผ Outlet ๋ฐฐ์น
โโ pages/
โ โโ dashboard/ # /dashboard
โ โโ inventory/ # /inventory
โ โโ ai-strategy/ # /ai-strategy
โ โโ execution/ # /execution
โ โโ statistics/ # /statistics
โโ widgets/
โ โโ app-shell/ # ์ค์ Header, Sidebar, navigation ์กฐํฉ
โ โโ inventory-summary/ # ์ฌ๊ณ ์์ฝ ์
๋ฌด ๋ธ๋ก
โ โโ inventory-table/ # ํํฐ์ ์ฌ๊ณ ํ
์ด๋ธ ์กฐํฉ
โ โโ inventory-detail-drawer/ # ๋น ๋ฅธ ์์ธ ํ์ธ ๋ธ๋ก
โ โโ strategy-performance/ # ์ ๋ต ์ฑ๊ณผ ๋ธ๋ก
โโ features/
โ โโ inventory-filter/ # ์ฌ๊ณ ํํฐ ํ๋
โ โโ inventory-sync/ # ์ฌ๊ณ ๋๊ธฐํ ํ๋
โ โโ inventory-detail/ # ์์ธ ์ด๊ธฐ ํ๋
โโ entities/
โ โโ inventory/
โ โ โโ api/ # API ํจ์, query key์ options
โ โ โโ model/ # ์ฌ๊ณ ํ์
ยท์ํยท๋๋ฉ์ธ ๊ท์น
โ โ โโ ui/ # ์ํ badge, ๋ฒ์ ์นด๋, LOT ํ
โ โโ product/
โ โโ sales-channel/
โ โโ strategy/
โโ shared/
โ โโ api/ # Axios, CSRF, ApiError, requestJson
โ โโ config/ # ํ๊ฒฝ๋ณ์ ์ ๊ทํ
โ โโ hooks/ # useMediaQuery ๋ฑ ๋ฒ์ฉ React hook
โ โโ lib/ # cn๊ณผ ์ซ์ยท๋ ์ง formatter
โ โโ ui/ # shadcn ๊ธฐ๋ฐ ๊ณตํต UI์ Storybook
โโ _template/ # FSD ์ฌ์ฉ ์์ ๋ฌธ์
โโ styles.css # ์ ์ญ ๋์์ธ ํ ํฐ๊ณผ ์์ ๊ถ๋ณ CSS
โโ main.jsx # ์ฑ ์ง์
์
์ฌ์ด๋๋ฐ์ ํค๋์ ๊ณตํต primitive๋ shared/ui, ์ค์ ๋ฉ๋ดยท์ฌ์ฉ์ยทํ์ฌ ๊ฒฝ๋ก๋ฅผ ๋ฌถ๋ ์กฐํฉ์ widgets/app-shell, ์ต์ข
๋ฐฐ์น๋ app/layouts/AppLayout.jsx๊ฐ ๋ด๋นํฉ๋๋ค. ๋ฐ๋ผ์ Layout ํ ํ์ผ์ ์ ์ฒด navigation JSX๋ฅผ ๋ฃ์ง ์์ต๋๋ค.
๊ตฌ์ฒด์ ์ธ ์ ๊ธฐ๋ฅ ๋ฐฐ์น ์์๋ src/_template/README.md๋ฅผ ํ์ธํฉ๋๋ค.
FSD ๊ณ์ธต ์์์๋ ๋ค์ segment ์ด๋ฆ์ ๊ฐ์ ์๋ฏธ๋ก ์ฌ์ฉํฉ๋๋ค.
| ์ด๋ฆ | ์ญํ | ์์ |
|---|---|---|
api |
endpoint ํจ์, query key, QueryยทMutation options | inventoryApi.js, inventoryQueries.js |
api/clients |
Axios์ฒ๋ผ ์ค์ HTTP ๋๊ตฌ์ ๊ณตํต instance | axiosClient.js |
model |
mapper, schema, constants, store์ ๋๋ฉ์ธ ์ํ ๊ท์น | inventoryMapper.js |
ui |
์ฌ์ฉ์์๊ฒ ๋ณด์ด๋ React ์ปดํฌ๋ํธ | InventoryScopeCard.jsx |
lib |
React์ ๋๋ฉ์ธ์ ์์กดํ์ง ์๋ ์์ ์ ํธ๋ฆฌํฐ | formatter, cn.js |
hooks |
์ฌ๋ฌ ๊ณณ์์ ์ฌ์ฌ์ฉํ๋ React hook | useMediaQuery.js |
config |
ํ๊ฒฝ๋ณ์์ ๋ณ๊ฒฝ๋์ง ์๋ ์ฑ ์ค์ | env.js |
providers |
์ฑ ์ ์ฒด Context์ ์ธ๋ถ Provider ์ฐ๊ฒฐ | AppProviders.jsx |
layouts |
์ ์ญ widget๊ณผ Router Outlet ๋ฐฐ์น | AppLayout.jsx |
router |
route, redirect, lazy route ๊ฒฝ๊ณ | router.jsx |
stories |
๊ณตํต UI์ ๋ ๋ฆฝ ์ํ ๋ฌธ์ | Button.stories.jsx |
lib์ React ์์ด ์
๋ ฅ์ ๊ฒฐ๊ณผ๋ก ๋ฐ๊พธ๋ ์์ ์ฝ๋, hooks๋ React lifecycle๊ณผ state๋ฅผ ์ฌ์ฉํ๋ ์ฝ๋์
๋๋ค. api๋ ํต์ , model์ ํต์ ๊ฒฐ๊ณผ๋ฅผ ํ๋ก ํธ ๋๋ฉ์ธ์ผ๋ก ํด์ํ๋ ์ญํ ์
๋๋ค.
ํ์ผ ์ด๋ฆ๋ ์ญํ ์ ๋๋ฌ๋ด๋๋ก ํต์ผํฉ๋๋ค.
| ํจํด | ์๋ฏธ |
|---|---|
*Api.js |
endpoint๋ณ HTTP ํจ์ |
*Queries.js |
query key์ Query options factory |
*Mutations.js |
mutation options์ ๋ฌดํจํ ๊ท์น |
*Mapper.js |
API DTO๋ฅผ ํ๋ก ํธ ๋ชจ๋ธ๋ก ๋ณํ |
*Schema.js |
Zod ๊ฒ์ฆ schema |
*Store.js |
Zustand ์ ์ญ UI store |
use*.js |
React hook |
*.test.js |
Vitest ํ ์คํธ |
*.stories.jsx |
Storybook ๋ฌธ์ |
index.js |
slice ์ธ๋ถ์ ๋ ธ์ถํ ๊ณต๊ฐ API |
๋ ์์ธํ ์์น ๊ฒฐ์ , ๋ช
๋ช
, ์ํ ์์ ๊ถ ๊ธฐ์ค์ docs/development-conventions.md๋ฅผ ํ์ธํฉ๋๋ค.
Axios์ TanStack Query๋ ๋์ฒด ๊ด๊ณ๊ฐ ์๋๋ผ ์๋ก ๋ค๋ฅธ ์ฑ ์์ ๊ฐ์ง๋๋ค.
Page / Widget
โ TanStack Query options
โ Entity API function
โ requestJson
โ axiosClient
โ Spring Boot API
- Axios๋ ์ค์ HTTP ์์ฒญ, timeout,
withCredentials, CSRF header, ๊ณตํต ์ค๋ฅ ๋ณํ์ ๋ด๋นํฉ๋๋ค. - TanStack Query๋ ์๋ฒ ์ํ ์บ์, ๋ก๋ฉยท์ค๋ฅ ์ํ, ์ฌ์กฐํ์ ๋ฌดํจํ๋ฅผ ๋ด๋นํฉ๋๋ค.
- ํ์ด์ง์ UI ์ปดํฌ๋ํธ์์ Axios๋ฅผ ์ง์ importํ์ง ์์ต๋๋ค.
- API ์๋ต์ Zustand์ ๋ณต์ฌํ์ง ์์ต๋๋ค.
- Query์
signal์ API ํจ์๊น์ง ์ ๋ฌํด ์ทจ์ ๊ฐ๋ฅํ ์์ฒญ์ ์ ์งํฉ๋๋ค. - query key๋ entity๋ณ key factory์์ ๊ด๋ฆฌํฉ๋๋ค.
shared/api๋getJson,postJson,putJson,patchJson,deleteJson,headJsonnamed helper๋ฅผ ์ ๊ณตํฉ๋๋ค.
์ฌ์ฉ ์์:
import { useQuery } from '@tanstack/react-query';
import { inventoryListQueryOptions } from '@/entities/inventory';
const query = useQuery(inventoryListQueryOptions(filters));๊ณตํต ํต์ ์ฝ๋๋ src/shared/api, ์ฌ๊ณ API ์์๋ src/entities/inventory/api์ ์์ต๋๋ค.
๋ณ๊ฒฝ ์์ฒญ์ด ์๊ธฐ๋ฉด ์ค์ ๋๋ฉ์ธ API์์ ๊ฐ์ options ๊ตฌ์กฐ๋ฅผ ์ฌ์ฉํฉ๋๋ค. ์์ง ๋ฐฑ์๋ ๊ณ์ฝ์ด ์๋ ์ฌ๊ณ ์์ ยท์ญ์ endpoint๋ฅผ ๋ฏธ๋ฆฌ ๋ง๋ค์ง๋ ์์ต๋๋ค.
import { postJson } from '@/shared/api';
export function syncInventory(body, signal) {
return postJson({
path: 'v1/inventory-sync',
body,
signal,
});
}์ธ์ ๋ก๊ทธ์ธ์ ๋ค์ Spring Security ๊ณ์ฝ์ ์ฌ์ฉํฉ๋๋ค.
GET /api/v1/auth/csrf -> CSRF cookie์ header ์ ๋ณด ๋ฐ๊ธ
POST /api/v1/auth/login -> loginId, password๋ก ์ธ์
๋ก๊ทธ์ธ
GET /api/v1/auth/me -> ํ์ฌ ์ธ์
์ฌ์ฉ์ ์กฐํ
POST /api/v1/auth/logout -> ์๋ฒ ์ธ์
๊ณผ ์ธ์ฆ cookie ์ ๊ฑฐ
์ฑ์ /me์ 401 AUTH-001์ ๋น๋ก๊ทธ์ธ ์ํ๋ก ํด์ํ๊ณ ๋ณดํธ๋ ์
๋ฌด ๊ฒฝ๋ก๋ฅผ /login์ผ๋ก ์ ํํฉ๋๋ค. ๋คํธ์ํฌ ์ค๋ฅ๋ ์๋ฒ ์ค๋ฅ๋ ๋ก๊ทธ์ธ ํ๋ฉด์ผ๋ก ์จ๊ธฐ์ง ์๊ณ ๋ค์ ์๋ํ ์ ์๋ ์ค๋ฅ ์ํ๋ก ํ์ํฉ๋๋ค. ์ธ์
ID๋ localStorage, sessionStorage ๋๋ Zustand์ ์ ์ฅํ์ง ์์ผ๋ฉฐ ๋ธ๋ผ์ฐ์ ์ HttpOnly cookie๊ฐ ๊ด๋ฆฌํฉ๋๋ค. ๋ก๊ทธ์์ ์ฑ๊ณต ์ ์ฌ์ฉ์๋ณ ์๋ฒ ์บ์๋ฅผ ์ ๊ฑฐํ๊ณ /login์ผ๋ก ์ด๋ํฉ๋๋ค. ์
๋ฌด API์ 401 AUTH-001์ ์ ์ญ ์ธ์
๋ง๋ฃ๋ก ์ฒ๋ฆฌํ์ฌ ์ ์ฒด ์๋ฒ ์บ์๋ฅผ ์ ๊ฑฐํ๊ณ ํ์ฌ URL์ ๋ณด์กดํ ๋ค ๋ก๊ทธ์ธ ํ๋ฉด์ผ๋ก ์ด๋ํฉ๋๋ค. ์ธ๋ถ 403 ๊ถํ ์ ์ฑ
์ ํ์ ๊ธฐ๋ฅ์์ ์ฐ๊ฒฐํฉ๋๋ค.
๊ณตํต ์ปดํฌ๋ํธ๋ src/shared/ui/index.js๋ฅผ ํตํด ๊ฐ์ ธ์ต๋๋ค.
import { Badge, Button, Card, DataTable, LottieLoader } from '@/shared/ui';ํ์ฌ ์ค๋น๋ ์ฃผ์ ์ปดํฌ๋ํธ:
- ํ๋:
Button,IconButton - ์
๋ ฅ:
Input,Select,Checkbox - ํ๋ฉด:
Card,MetricCard,DetailLayout,Drawer - ์ํ:
Badge,StatusDot,Alert,StateView,Skeleton - ๋ฐ์ดํฐ:
Table,DataTable,Tabs - ๋ณด์กฐ UI:
Avatar,Tooltip,Icon,Sidebar - ๋ชจ์
:
LoadingMedia,LottieLoader
์ฌ์ฉ ์์:
- ๋จผ์
shared/ui์ Storybook์์ ๊ธฐ์กด ์ปดํฌ๋ํธ๋ฅผ ํ์ธํฉ๋๋ค. - ๊ธฐ์กด ์ปดํฌ๋ํธ์
variant,size,tone,className์ผ๋ก ํด๊ฒฐํฉ๋๋ค. - ๋ฒ์ฉ ํํ๋ง
shared/ui์ ์ถ๊ฐํฉ๋๋ค. - ์ํ๋ฑ๊ธ, LOT, ์ฌ๊ณ ๋ฒ์์ฒ๋ผ ๋๋ฉ์ธ ์๋ฏธ๊ฐ ์์ผ๋ฉด
entities/inventory/ui์ ๋ก๋๋ค. - ๊ณตํต ์ปดํฌ๋ํธ๋ฅผ ์ถ๊ฐํ๊ฑฐ๋ variant๋ฅผ ๋ณ๊ฒฝํ๋ฉด Storybook๋ ํจ๊ป ๊ฐฑ์ ํฉ๋๋ค.
cn()์ ์กฐ๊ฑด๋ถ class ์กฐํฉ๊ณผ Tailwind ์ถฉ๋ ์ ๋ฆฌ์ ์ฌ์ฉํฉ๋๋ค. cva()๋ Button, Badge, Input์ฒ๋ผ ์๋ฏธ ์๋ variant๊ฐ ๋ฐ๋ณต๋ ๋ ์ฌ์ฉํฉ๋๋ค. ํ์ด์ง ์ ์ฉ layout์ cva๋ฅผ ๋ง๋ค๊ฑฐ๋ ํ๋ฉด๋ง๋ค ๋์ผํ HTMLยทCSS๋ฅผ ๋ค์ ์์ฑํ์ง ์์ต๋๋ค.
์ซ์, ๊ธ์ก, ํผ์ผํธ, ์๋, ๋ ์ง์ ์๋น๊ธฐํ ํ๊ธฐ๋ ๊ณตํต formatter๋ฅผ ์ฌ์ฉํฉ๋๋ค.
import {
formatCurrency,
formatDateTime,
formatDaysRemaining,
formatNumber,
formatPercent,
formatQuantity,
} from '@/shared/lib/format';๊ธฐ๋ณธ ํ๊ธฐ๋ 2,058, โฉ8,900, 14.3%, 205๊ฐ, 2026.08.08 09:05, D-43์ด๋ฉฐ ํ์ํ ์ ์๋ ๊ฐ์ -๋ก ํต์ผํฉ๋๋ค. ํ๋ฉด๋ง๋ค toLocaleString()์ด๋ ๋ ์ง ๋ฌธ์์ด ์กฐํฉ์ ๋ค์ ์์ฑํ์ง ์์ต๋๋ค.
๋์์ธ ๋ฐฉํฅ์ Mesh Forecast ์คํ์ผ๊ณผ Dashboard Filter Foundations ์ปฌ๋ฌ ์์คํ ์ ๋๋ค. ์ ๋ฌด์ฉ ํ๋ฉด์ด๋ฏ๋ก ์ฅ์๋ณด๋ค ํ, ํํฐ, ๊ฒ์๊ณผ ์ํ ๋น๊ต์ ๋ช ํ์ฑ์ ์ฐ์ ํฉ๋๋ค.
| ์ญํ | ์์ | ์ฌ์ฉ ๊ธฐ์ค |
|---|---|---|
| Main | #27B06E |
primary ํ๋, ํ์ฑ navigation, ์ํธ ์ํ |
| Sub Mint | #11C6AB |
๋ณด์กฐ ๊ฐ์กฐ |
| Sub Cyan | #00B0D7 |
์ ๋ณด, ๋ณดํต ์ํ |
| Sub Orange | #FDA643 |
์ฃผ์ ์ํ |
| Mint Soft | #DAF7E9 |
์ํธยทprimary soft ๋ฐฐ๊ฒฝ |
| Cyan Soft | #CFF4FC |
์ ๋ณด soft ๋ฐฐ๊ฒฝ |
| Orange Soft | #FFEC2C |
์ฃผ์ soft ๊ฐ์กฐ |
| Danger | #D92D20 |
์ํ๊ณผ ์คํจ ์ํ |
| Danger Soft | #FEE4E2 |
์ํ soft ๋ฐฐ๊ฒฝ |
| Gray 900 | #282828 |
์ ๋ชฉ๊ณผ ํต์ฌ ํ ์คํธ |
| Gray 700 | #747474 |
๋ณธ๋ฌธ ํ ์คํธ |
| Gray 500 | #8E8E8E |
์ค๋ช ๊ณผ placeholder |
| Gray 300/200/50 | #C1C1C1 / #DADADA / #F4F4F4 |
border์ ๋ฐฐ๊ฒฝ ๋จ๊ณ |
์ํ๋ฑ๊ธ์ ์์๋ง์ผ๋ก ๊ตฌ๋ถํ์ง ์๊ณ ํ ์คํธ์ Reicon ์์ด์ฝ์ ํจ๊ป ์ฌ์ฉํฉ๋๋ค. ์์ด ์๋ ๋ฒํผ์ ํฐ์ ๊ธ์, ํฐ์ ๋ฒํผ์ Gray 900 ๊ธ์๋ฅผ ๊ธฐ๋ณธ์ผ๋ก ํฉ๋๋ค.
Pretendard ๊ฐ๋ณ ํฐํธ ํ๋๋ง ์ฌ์ฉํ๋ฉฐ ํ์ผ์ public/fonts/PretendardVariable.woff2์ ํฌํจ๋์ด ์์ต๋๋ค.
| Token | ํฌ๊ธฐ | ๊ธฐ๋ณธ ๊ตต๊ธฐ | ์ฉ๋ |
|---|---|---|---|
headline1 |
1.375rem ยท 22px |
700 |
ํ์ด์ง ๋ํ ์ ๋ชฉ |
headline2 |
1.25rem ยท 20px |
700 |
ํฐ ์น์ ์ ๋ชฉ |
subtitle1 |
1rem ยท 16px |
600 |
์นด๋ยทํจ๋ ์ ๋ชฉ |
subtitle2 |
0.875rem ยท 14px |
600 |
๋ณด์กฐ ์ ๋ชฉ |
body1 |
0.875rem ยท 14px |
400 |
๊ธฐ๋ณธ ๋ณธ๋ฌธ |
body2 |
0.75rem ยท 12px |
500 |
์กฐ๋ฐํ ์ ๋ฌด UI ๋ณธ๋ฌธ |
description |
0.75rem ยท 12px |
400 |
์ค๋ช ๊ณผ metadata |
๊ธฐ๋ณธ ๊ตต๊ธฐ๋ --font-weight-regular(400), --font-weight-medium(500), --font-weight-semibold(600), --font-weight-bold(700), --font-weight-extrabold(800)์ผ๋ก ๊ด๋ฆฌํฉ๋๋ค. ์ปดํฌ๋ํธ์์๋ --font-weight-headline1, --font-weight-button, --font-weight-metric์ฒ๋ผ ์ญํ ๋ณ semantic token์ ์ฐ์ ์ฌ์ฉํฉ๋๋ค.
์ซ์๋ ๋น๊ต๊ฐ ์ฝ๋๋ก ์ ์ญ tabular-nums๋ฅผ ์ฌ์ฉํฉ๋๋ค. ์ปดํฌ๋ํธ์์ ์์ px ํฌ๊ธฐ๋ ์์์ ํ๋์ฝ๋ฉํ์ง ์๊ณ src/styles.css์ semantic token์ ์ฌ์ฉํฉ๋๋ค.
- ๊ฐ๊ฒฉ์ 4px ๊ธฐ๋ฐ์
--space-*primitive scale์ ์ฌ์ฉํฉ๋๋ค. - ์์ฃผ ์ฐ๋ semantic ๊ฐ๊ฒฉ์
--spacing-page-x,--spacing-section-gap,--spacing-card-padding,--spacing-table-cell-x/y๋ฅผ ์ฌ์ฉํฉ๋๋ค. - control height๋
--control-height-sm(32px),--control-height-default(40px),--control-height-lg(48px)๋ก ํต์ผํฉ๋๋ค. - control radius:
0.375remยท 6px - bar/card radius:
0.5remยท 8px - panel radius:
0.5remยท 8px - field gap:
0.5remยท 8px - bar gap:
0.75remยท 12px - ๋น ๋ฅธ motion:
160ms, ๊ธฐ๋ณธ motion:220ms - ๋ฐ์ Gray 50 ๋ฐฐ๊ฒฝ๊ณผ ํฐ์ ์์ ํ๋ฉด์ ๊ธฐ๋ณธ์ผ๋ก ์ฌ์ฉํฉ๋๋ค.
- Mesh ํจ๊ณผ๋ ํ์ด์ง ๋ฐฐ๊ฒฝ๊ณผ ์ค์ํ ์์ฝ ํ๋ฉด์๋ง ์ ํ์ ์ผ๋ก ์ฌ์ฉํฉ๋๋ค.
- ํ ์ด๋ธ๊ณผ ํํฐ๋ ๋ถํฌ๋ช ํ ์์ ํ๋ฉด์ผ๋ก ์ ์งํฉ๋๋ค.
- ์นด๋๋ฅผ ํ์ด์ง ๊ตฌํ์ฒ๋ผ ๋จ์ฉํ๊ฑฐ๋ ์นด๋ ์์ ์นด๋๋ฅผ ์ค์ฒฉํ์ง ์์ต๋๋ค.
- ์์ด์ฝ์
reicon-react๋ง ์ฌ์ฉํ๊ณ , ์์ด์ฝ ๋ฒํผ์๋ accessible label๊ณผ tooltip์ ์ ๊ณตํฉ๋๋ค. - ZONE๊ณผ KAN์ UI ๋ชจ๋ธ, ํํฐ, ํ ์ปฌ๋ผ, URL ํ๋ผ๋ฏธํฐ์ ํฌํจํ์ง ์์ต๋๋ค.
๋์์ธ ํ ํฐ๊ณผ ์ค์ ์ปดํฌ๋ํธ ์ํ๋ Storybook์ Foundations/Design tokens์ Shared UI ๊ทธ๋ฃน์์ ํ์ธํฉ๋๋ค. ๋์์ธ ๋ ํผ๋ฐ์ค์ AI ์์
์ฉ ๊ธฐ์ค์ docs/design-references/ui8-dashboard-style-reference.md์ ์์ต๋๋ค.
์๋ณธ ํฐ๋ MP4๋ public/animations/heendi-loader-reference.mp4์ ๋ ํผ๋ฐ์ค๋ก ๋ณด๊ดํฉ๋๋ค. ์์ ๊ณตํต ๋ก๋ฉ ์์ญ์์๋ public/projects/hg-inventory-loader/scene-1/lottie.json๊ณผ LottieLoader๋ฅผ ์ฌ์ฉํฉ๋๋ค.
- MP4: ์บ๋ฆญํฐ๊ฐ ํฌํจ๋ ํฐ ๋ก๋ฉ ํ๋ฉด ๋ ํผ๋ฐ์ค
- Lottie: ํฌ๋ช ๋ฐฐ๊ฒฝ, ์์ ์ฌ๋กฏ, ๋ฐ๋ณต ๊ฐ๋ฅํ ์์ ๊ณตํต ์คํผ๋
prefers-reduced-motion: ์๋ ์ฌ์์ ์ค์งํด ์ ๊ทผ์ฑ ์ค์ ์ ๋ฐ๋ฆ
์๋ฃ:
- ReactยทViteยทpnpm ์ฑ ๊ธฐ๋ฐ
- FSD-lite ํด๋ ๊ตฌ์กฐ์ ์์ slice
- ์ฑ ์ ธ, Header, Sidebar, ๊ธฐ๋ณธ ๋ผ์ฐํฐ
- Dashboard Filter Foundations ๋์์ธ ํ ํฐ๊ณผ Pretendard
- shadcn ๊ธฐ๋ฐ ์ฌ์ฌ์ฉ UI์ Storybook
- AxiosยทCSRFยทApiError ๊ณตํต ํต์ ๊ฒฝ๊ณ
- ์ธ์
๋ก๊ทธ์ธ,
/me์ธ์ฆ ๋ณต์๊ณผ ๋ณดํธ ๋ผ์ฐํฐ - ์ ๋ฌด API์ ์ ์ญ ์ธ์ ๋ง๋ฃ ๊ฐ์ง, ์บ์ ์ ๋ฆฌ์ ์๋ ๊ฒฝ๋ก ๋ณต๊ท
- React Hook FormยทZod ๊ธฐ๋ฐ ๋ก๊ทธ์ธ ํ๋ฉด
- TanStack Query Provider, inventory query key/options ์์
- TanStack Table ๊ธฐ๋ฐ ์ฌ์ฌ์ฉ DataTable
- MP4 ๋ ํผ๋ฐ์ค์ Lottie ๊ณตํต ๋ก๋
- Vitest์ Playwright ๊ธฐ๋ณธ ๊ฒ์ฆ
- ๊ณตํต ๋ฐ์ดํฐ formatter์ ๋จ์ ํ ์คํธ
- APIยทQueryยทmapperยทURL ์ํ ์ ์ฒด ํ๋ฆ ํ ํ๋ฆฟ
- ํด๋ยทํ์ผ ๋ช ๋ช ๊ท์น๊ณผ ๊ธฐ๋ฅ ๊ฐ๋ฐ ์ฒดํฌ๋ฆฌ์คํธ
- GitHub PR ํ ํ๋ฆฟ
- Node.js 24 LTS์ pnpm ๋ฒ์ ๊ณ ์
- ESLintยทPrettier ๊ณตํต ๊ฒ์ฌ
- GitHub Actions PR ์๋ ๊ฒ์ฆ
.env*๋น๋ฐ์ ๋ณด ๋ณดํธ ๊ท์น
๊ธฐ๋ฅ ๋๋ ์ด์ ๋จ๊ณ์์ ์งํ:
- ์ค์ Spring Boot API์ ์๋ต mapper ์ฐ๊ฒฐ
- Spring Security ์ธ๋ถ ์ญํ ยท๊ถํ ์ ์ฑ
- ์ค์ ์ฌ๊ณ ์กฐํ, ์๋ฒ ํ์ด์ง๋ค์ด์ , URL ํํฐ์ ์ ๋ ฌ
- ์ฌ๊ณ ์์ธ์ AI ์ ๋ต ์ ๋ฌด ๊ธฐ๋ฅ
- Zustand, React Hook Form, Zod, Recharts์ ์ค์ ๋๋ฉ์ธ ์ ์ฉ
- ๋ฐฐํฌ ์ํคํ ์ฒ์ ํ๊ฒฝ๋ณ ์ค์
- ์ ๊ท ํ์ ํ์ ์จ๋ณด๋ฉ
- ํ ์ค๋ช ์ฉ ํ๋ก ํธ์๋ ํธ๋๋ถ
- ํ๋ก ํธ์๋ ์ด๊ธฐ ์ธํ ํ ๊ฐ์ด๋
- ํ๋ก ํธ์๋ ๊ฐ๋ฐ ๊ท์น
- ๊ธฐ๋ฅ ๊ฐ๋ฐ ์ฒดํฌ๋ฆฌ์คํธ
- FSD-lite ๊ตฌ์กฐ ์์
- APIยทQueryยทmapper ์ ์ฒด ํ๋ฆ ์์
- GitHub PR ํ ํ๋ฆฟ
- ๋์์ธ ๋ ํผ๋ฐ์ค์ ๊ตฌํ ๊ท์น
- HTTP์ FSD ๊ฒฝ๊ณ ๊ฒฐ์
- ๋์์ธ ๋ฐฉํฅ ๊ฒฐ์