refactor: promote 8081 design system and served app structure

2026-04-01 14:50:08 +09:00
parent 637b390024
commit d0e055973e
50 changed files with 24157 additions and 820 deletions
--- a/docs/architecture/8081_SERVING_MAP.md
+++ b/docs/architecture/8081_SERVING_MAP.md
@@ -0,0 +1,112 @@
+# 8081 Serving Map
+
+## Purpose
+
+이 문서는 `8081` 작업용에서 어떤 URL이 어떤 파일을 실제로 읽는지 고정하기 위한 책임 맵이다.
+이번 1차 정리의 목표는 기능 변경이 아니라 `실제 서빙 파일`, `공통 기본 스타일`, `8081 전용 오버라이드`, `참고 원본 자산`의 경계를 분명히 하는 것이다.
+
+## Runtime Entry Points
+
+- 허브 엔트리: `/`
+  - 파일: `frontend/public/index.html`
+- 허브 공통 스크립트:
+  - 파일: `frontend/public/app.js`
+- 허브 공통 기본 스타일:
+  - 파일: `frontend/public/styles.css`
+- 허브 8081 전용 디자인 오버라이드:
+  - 파일: `frontend/public/styles-8081-design.css`
+
+## Login Rules
+
+- 로그인 화면 기본 구조와 스타일은 `8080` 공통 기준을 따른다.
+- 로그인 기본 스타일은 `frontend/public/styles.css`에서만 정의한다.
+- `frontend/public/styles-8081-design.css`에는 로그인 관련 셀렉터를 넣지 않는다.
+
+## Legacy Organization
+
+- URL: `/legacy/organization`
+- HTML 파일:
+  - `DashBoard-organization.html`
+- 정적 자산:
+  - `legacy/static/common.css`
+  - `legacy/static/organization.css`
+  - `legacy/static/organization.js`
+
+## Integration Screens
+
+- URL: `/integrations/payment`
+  - 현재 실제 서빙 파일: `incoming-files/served/payment.html`
+  - 앱 소스 기준: `frontend/apps/payment/index.html`
+  - publish 규칙: `scripts/publish_payment_app.sh`
+- URL: `/integrations/ledger`
+  - 현재 실제 서빙 파일: `incoming-files/served/ledger/index.html`
+  - 현재 실제 runtime asset 경로: `incoming-files/served/ledger/*`
+  - 앱 소스 기준: `frontend/apps/ledger/*`
+  - publish 규칙: `frontend/apps/ledger/index.html` placeholder를 `scripts/publish_ledger_app.sh`가 runtime asset 경로로 치환
+- URL: `/integrations/mh`
+  - 현재 실제 서빙 파일: `incoming-files/served/mh.html`
+  - 앱 소스 기준: `frontend/apps/team/index.html`
+  - publish 규칙: `scripts/publish_team_app.sh`
+
+정리 원칙:
+
+- `incoming-files` 아래에서는 `served/`를 실제 서빙 자산용으로 사용한다.
+- `reference/`는 원본 참고 파일, 복구 참고 파일, 비교용 자산만 둔다.
+- 1차 정리에서는 기존 실제 서빙 파일을 `served/`에 복사하고, backend 서빙 경로를 먼저 `served/`로 갱신한다.
+- `사업관리대장`은 `#21`부터 wrapper decode 방식 대신 `served/ledger/index.html`과 `served/ledger/*`를 직접 서빙한다.
+- `사업관리대장` 수정 원본은 `#21` 다음 단계부터 `frontend/apps/ledger/*`를 먼저 보고, `scripts/publish_ledger_app.sh`로 runtime served 파일에 반영한다.
+- 기존 루트 `incoming-files/payment.html`, `incoming-files/mh.html`는 안전한 비교/복구를 위해 당분간 남겨둔다.
+
+## Seat Map
+
+- 허브 화면 구성:
+  - `frontend/public/index.html`
+  - `frontend/public/app.js`
+  - `frontend/public/styles.css`
+  - `frontend/public/styles-8081-design.css`
+- API / viewer:
+  - `backend/app/main.py`
+  - `backend/app/db.py`
+  - `backend/app/center_chair_viewer_template.html`
+
+## Incoming Files Classification
+
+### Served
+
+- 실제 URL에서 직접 읽는 파일
+- 예:
+  - `served/payment.html`
+  - `served/mh.html`
+
+### Reference
+
+- 원본 HTML/CSS/XLSX/CSV
+- 복구 비교용 자산
+- 직접 서빙하지 않는 참고 파일
+- 필요 시 다음 차수에서 `reference/` 하위로 단계적 재배치한다.
+
+예:
+
+- `260320.html`
+- `sample style.css`
+- `opayment.html`
+- `omh.html`
+- `reference/ledger/MH 통합 대시보드_260320.html`
+- `reference/ledger/MH 통합 대시보드_260320.css`
+- 원본 xlsx/csv
+
+## Out Of Scope For Phase 1
+
+- DB 스키마 의미 변경
+- 계산식 변경
+- 권한 로직 변경
+- 신규 기능 추가
+- backend 라우터 대분해
+
+## Phase 1 Success Criteria
+
+- 수정 대상 파일을 화면별로 즉시 찾을 수 있다.
+- 로그인은 `styles.css`만 본다.
+- 허브 8081 디자인은 `styles-8081-design.css`만 본다.
+- `/integrations/payment`, `/integrations/mh`의 실제 서빙 파일 위치가 문서와 코드에서 일치한다.
+- 기존 참고 자산을 지우지 않고도 실제 서빙 경로와 참고 경로를 구분할 수 있다.
--- a/docs/architecture/DESIGN_SSOT.md
+++ b/docs/architecture/DESIGN_SSOT.md
@@ -0,0 +1,129 @@
+# Design SSOT
+
+## Source of truth
+
+- Primary visual source: [incoming-files/sample style.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/sample%20style.css)
+- Runtime token file: [design-tokens.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-tokens.css)
+- Runtime pattern file: [design-patterns.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-patterns.css)
+
+`sample style.css` defines the intended MH visual language. `design-tokens.css` is the token-level SSOT, and `design-patterns.css` is the component-level SSOT that packages those tokens into reusable runtime patterns.
+
+## Rules
+
+- New UI must use `design-tokens.css` variables first.
+- New UI must use `design-patterns.css` patterns before adding page-local variants.
+- Direct hex values are exceptions, not defaults.
+- Page files may define layout and composition, but color, panel, border, radius, and shadow values must come from tokens.
+- Shared aliases in `legacy/static/common.css` and `frontend/public/styles.css` exist only to bridge older code to the SSOT.
+- Reference files under `incoming-files/*` are not visual authority. Runtime visuals must follow `design-tokens.css` and `design-patterns.css`.
+
+## Fixed vs Flexible
+
+SSOT is not a pixel-locked screenshot spec. It is a design rule system with two layers.
+
+### Fixed rules
+
+These should be treated as stable defaults across screens.
+
+- Brand color family and accent family
+- Surface, border, text, and shadow tokens
+- Radius scale
+- Button, tab, input, panel, and card visual language
+- Typography tone and hierarchy
+- Background atmosphere and overall contrast direction
+
+### Flexible rules
+
+These must be interpreted per screen based on content density and interaction needs.
+
+- KPI card width and number of columns
+- Sidebar/content split ratios
+- Table column widths
+- Search/filter placement
+- Card stacking and wrap behavior
+- Desktop/mobile breakpoint behavior
+
+Example:
+
+- Wrong SSOT: `KPI width is 100px`
+- Correct SSOT: `KPI cards use the shared panel, radius, spacing, and text hierarchy tokens, and their width adapts to content without collapsing readability`
+
+## When SSOT does not define a component
+
+If a screen needs a pattern that SSOT does not explicitly define yet, do not fall back to arbitrary legacy styling.
+
+Use this order:
+
+1. Reuse existing tokens and the nearest shared pattern
+2. Design the missing component in the same visual grammar
+3. If the pattern is likely to repeat, document and promote it into SSOT
+
+This applies to examples such as:
+
+- A table pattern that does not exist in the current SSOT
+- A KPI strip that needs a different density than the sample
+- A new modal layout for a data-heavy screen
+
+## Candidate and deprecated styles
+
+Not every style already visible in the product is automatically part of SSOT.
+
+- `SSOT`
+  - Approved and repeatable patterns
+  - Token-backed visual rules
+- `candidate`
+  - Screen-local styles that look usable but do not yet have a documented basis
+  - Can be promoted later if they prove reusable
+- `deprecated`
+  - Old blue/slate/indigo defaults
+  - Temporary hardcoded fixes
+  - Styles that conflict with the sample-based MH visual language
+
+When a screen has a design with no clear basis, classify it as `candidate` first. Promote it only after it has been checked for reuse and consistency.
+
+## Token groups
+
+- Surface: `--ds-bg`, `--ds-panel`, `--ds-panel-soft`, `--ds-panel-strong`
+- Text: `--ds-ink`, `--ds-text-soft`, `--ds-text-muted`
+- Brand: `--ds-brand`, `--ds-brand-deep`, `--ds-brand-soft`, `--ds-accent`, `--ds-accent-soft`, `--ds-mint`
+- Borders and shadows: `--ds-line`, `--ds-line-soft`, `--ds-shadow-*`
+- Layout primitives: `--ds-radius-*`, `--ds-space-*`, `--ds-page-max-width`
+
+## Promoted runtime patterns
+
+These are now the official reusable patterns for current screens.
+
+- Panels and heads: `.ds-panel`, `.ds-panel-head`
+- KPI cards: `.ds-kpi-card`, `.ds-kpi-people`, `.ds-kpi-inverse`
+- Filter surfaces and toggles: `.ds-filter-surface`, `.ds-filter-toggle`, `.ds-reset-button`
+- Tables: `.ds-table-head`, `.ds-table-head-row`, `.ds-table-row`, `.ds-axis-cell`, `.ds-axis-cell-idle`, `.ds-axis-cell-active`
+- Value emphasis: `.ds-project-cell`, `.ds-income`, `.ds-expense`, `.ds-subhead`, `.ds-empty`, `.ds-strong`, `.ds-muted`
+- Breakdown/detail UI: `.ds-progress-track*`, `.ds-mode-chip`, `.ds-name-chip`, `.ds-mini-table-*`, `.ds-group-title`
+- Position chips: `.ds-position-*` via `position-*` compatibility classes
+- Business ledger popup/detail blocks: `.popup-*`, `.inline-card`, `.project-head-*`, `.summary-*`, `.ledger-*`, `.badge`, `.project-link`
+- Organization modal forms/buttons: `.member-form-*`, `.modal-btn*`
+- Seatmap action visibility: `.seatmap-actions .ghost-button`
+
+These patterns may still have compatibility selectors for existing screen classes, but they should now be treated as the official design layer.
+
+## Migration order
+
+1. Token file and common aliases
+2. Hub shell and shared controls
+3. Team/Personal analysis and Organization
+4. Project analysis
+5. Business ledger detail cleanup
+
+## Implementation guidance
+
+- Prefer tokenized ranges over hardcoded single values when layout depends on data volume
+- Prefer `design-patterns.css` component rules over one-off inline colors
+- If a new pattern is introduced during implementation, update this document once the pattern is stable
+- If a screen needs an exception, keep the exception local and explain why it cannot follow the shared pattern
+
+## Anti-patterns
+
+- Adding new `#4f46e5`, `#4338ca`, `bg-slate-*`, `text-indigo-*` style defaults
+- Reintroducing separate page-level color systems
+- Hardcoding “quick fix” brand colors in JS templates when a token/class can carry the same intent
+- Letting reference/original files override runtime pattern files