From 49f075ae7c9969121bf14d0eb2ae28931544914c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=ED=95=98=EB=9E=91=EC=9D=B4?= Date: Sun, 5 Apr 2026 15:00:46 +0900 Subject: [PATCH] docs: plan sprint-014 hermes renewal --- .plans/OVERVIEW.md | 71 ++++++------ .plans/deploy/main-release-flow.md | 40 +++++++ .plans/design/index.md | 23 ++++ .plans/design/ui/dashboard-design.md | 77 +++++-------- .plans/design/ui/project-detail-design.md | 102 +++++++----------- .plans/design/ui/projects-page-design.md | 43 ++++++++ .plans/hotfix/README.md | 9 ++ .plans/qa/README.md | 14 +++ .plans/sprints/SPRINT-014.md | 72 +++++++++++++ ARCHITECTURE.md | 85 +++++++++++++++ README.md | 77 +++++++------ docs/QUALITY_SCORE.md | 15 +++ .../project-information-architecture.md | 24 +++++ docs/references/repo-structure.md | 20 ++++ docs/tech-debt-tracker.md | 14 +++ 15 files changed, 496 insertions(+), 190 deletions(-) create mode 100644 .plans/deploy/main-release-flow.md create mode 100644 .plans/design/index.md create mode 100644 .plans/design/ui/projects-page-design.md create mode 100644 .plans/hotfix/README.md create mode 100644 .plans/qa/README.md create mode 100644 .plans/sprints/SPRINT-014.md create mode 100644 ARCHITECTURE.md create mode 100644 docs/QUALITY_SCORE.md create mode 100644 docs/product-specs/project-information-architecture.md create mode 100644 docs/references/repo-structure.md create mode 100644 docs/tech-debt-tracker.md diff --git a/.plans/OVERVIEW.md b/.plans/OVERVIEW.md index c956389..4ee5d26 100644 --- a/.plans/OVERVIEW.md +++ b/.plans/OVERVIEW.md @@ -1,45 +1,38 @@ -# 하나랑 대시보드 — 프로젝트 개요 +# 하나랑 대시보드 — 실행 개요 -## 목표 -4자매 멀티에이전트 파이프라인 관제 대시보드. -자기야가 한눈에 전체 현황을 파악하고 관리할 수 있는 화면. +## 프로젝트 목표 +- 4자매 운영 상태를 실시간으로 보여준다 +- 프로젝트/Sprint/Hotfix/QA/Deploy 흐름을 시각화한다 +- `main`이 항상 배포 가능 상태라는 원칙을 UI와 운영에 함께 반영한다 -## 기술 스택 +## 현재 표준 구조 +- 루트: `README.md`, `ARCHITECTURE.md` +- 실행 문서: `.plans/` + - `design/` + - `sprints/` + - `hotfix/` + - `qa/` + - `deploy/` +- 장기 문서: `docs/` -| 레이어 | 기술 | 비고 | -|--------|------|------| -| Frontend | Next.js + styled-components | styled-components는 return 아래에 적재 | -| Backend | Nest.js + Prisma | REST API | -| DB | MariaDB | Docker LXC 103 (10.10.10.146:33006) | -| 도메인 (FE) | `hanarang.nabomhalang.co.kr` | Nginx LXC 101에서 프록시 | -| 도메인 (BE) | `hanarang-api.nabomhalang.co.kr` | Nginx LXC 101에서 프록시 | +## 활성 작업 +- **SPRINT-014**: Hermes 전환 + 프로젝트 IA/파일 구조 리뉴얼 -## 아키텍처 +## 이번 Sprint 핵심 요구사항 +1. OpenClaw → Hermes 전환 후 자매 상태가 전부 offline으로 보이는 문제 해결 +2. 자매 프로필 사진 탐색 경로/fallback 재정비 +3. 변경된 파일 구조에 맞춘 프로젝트 진행률 / Sprint / Hotfix UI 개편 +4. 프로젝트를 네비게이션 두 번째 페이지로 고정 +5. 다랑 QA 완료 후 `main`이 배포 상태가 되고, 이랑은 최신 `main`을 pull해서 재배포만 수행하도록 흐름 고정 -``` -[사용자] → hanarang.nabomhalang.co.kr → [Nginx LXC 101] → [Next.js FE :3004] - ↓ API 호출 -[사용자] → hanarang-api.nabomhalang.co.kr → [Nginx LXC 101] → [Nest.js BE :3005] - ↓ SSH - [4자매 LXC 서버] - ↓ API - [Gitea API] - ↓ - [MariaDB LXC 103] -``` +## 이행 전략 +- 코드에서는 구 구조와 신 구조를 일정 기간 동시 지원 +- 문서는 신 구조를 기준으로 선반영 +- 신규 QA 문서는 `.plans/qa/` 기준 +- 신규 Hotfix 문서는 `.plans/hotfix/` 기준 -## 자매 서버 정보 -| 이름 | IP | 사용자 | LXC | -|------|-----|--------|-----| -| 하랑이 | 10.10.10.112 | harang | 104 | -| 나랑이 | 10.10.10.216 | narang | 105 | -| 다랑이 | 10.10.10.136 | darang | 106 | -| 이랑이 | 10.10.10.163 | erang | 107 | - -## 디자인 방향 -- 다크 테마 관제 화면 -- 카드 기반 레이아웃 -- 상태 색상: 온라인=초록(#00E676), 오프라인=빨강(#FF1744), 작업중=파랑(#2979FF) -- glassmorphism 포인트 -- 미니멀 아이콘 -- 정보 밀도 높은 UI +## 문서 맵 +- 구조 기준: `../ARCHITECTURE.md` +- 디자인 인덱스: `./design/index.md` +- Sprint 계획: `./sprints/SPRINT-014.md` +- 배포 플로우: `./deploy/main-release-flow.md` diff --git a/.plans/deploy/main-release-flow.md b/.plans/deploy/main-release-flow.md new file mode 100644 index 0000000..2bbfe50 --- /dev/null +++ b/.plans/deploy/main-release-flow.md @@ -0,0 +1,40 @@ +# Main Release Flow + +## 원칙 +- `main` = 배포 가능 상태 +- 다랑 QA가 끝나기 전에는 `main` merge 금지 +- 이랑은 feature branch를 배포하지 않고, QA 통과 후 merge된 최신 `main`만 배포 + +## 역할별 절차 +### 1. 하랑 +- 문서 작성 및 선 push +- 나랑/다랑/이랑 핸드오프 관리 +- QA 결과 확인 +- `main` merge 최종 판단 + +### 2. 나랑 +- feature/hotfix branch에서 구현 +- 구현 후 원격 branch push +- 다랑에게 QA 요청 + +### 3. 다랑 +- 나랑 branch pull +- QA 수행 +- `.plans/qa/`에 결과 md 작성 +- `passed/failed + errors[]`를 하랑에게 전달 + +### 4. 하랑 +- `passed = true` 확인 후 `main` merge +- merge 완료 시점부터 `main`은 배포 상태 +- 이랑에게 재배포 요청 + +### 5. 이랑 +- 서버에서 최신 `main` pull +- install/build/restart 등 재배포만 수행 +- 추가 수정 없이 운영 반영 + +## 금지 +- QA 전 `main` merge +- 이랑이 feature branch 직접 배포 +- QA 결과 없는 배포 +- 문서 없이 긴급 hotfix 진행 diff --git a/.plans/design/index.md b/.plans/design/index.md new file mode 100644 index 0000000..381210f --- /dev/null +++ b/.plans/design/index.md @@ -0,0 +1,23 @@ +# 디자인 문서 인덱스 + +## 시스템 +- `DESIGN-SYSTEM.md` +- `architecture.md` +- `api-design.md` +- `db-schema.md` + +## 페이지별 UI +- `ui/dashboard-design.md` +- `ui/projects-page-design.md` +- `ui/project-detail-design.md` +- `ui/sister-detail-design.md` +- `ui/activity-log-design.md` +- `ui/org-design.md` +- `ui/settings-design.md` +- `ui/admin-design.md` + +## Sprint 014에서 반드시 반영할 화면 +- 대시보드 메인: Hermes 상태/프로젝트 요약/두 번째 네비 반영 +- 프로젝트 목록: 프로젝트를 두 번째 페이지로 이동한 기준 재배치 +- 프로젝트 상세: Sprint / Hotfix / QA / Deploy 분리 구조 반영 +- 자매 페이지: Hermes 상태 판정과 아바타 fallback 반영 diff --git a/.plans/design/ui/dashboard-design.md b/.plans/design/ui/dashboard-design.md index 7df3ee5..0088e5c 100644 --- a/.plans/design/ui/dashboard-design.md +++ b/.plans/design/ui/dashboard-design.md @@ -1,58 +1,31 @@ -# 대시보드 메인 (`/`) — 디자인 v2 +# 대시보드 메인 (`/`) — Sprint 014 리뉴얼 포인트 -> 참조: DESIGN-SYSTEM.md | 원본: 자기야 디자인 파일 #1 +## 유지 요소 +- 미니멀 터미널 UI +- 4자매 상태 카드 +- 프로젝트 요약 + 활동 피드 +- 모바일 하단 탭바 -## 레이아웃 +## 수정 포인트 +### 1. 자매 상태 판정 +- Hermes 런타임 기준 상태를 읽어야 함 +- OpenClaw만 보는 하드코딩 제거 +- 상태 카드가 전원 `OFFLINE`으로 고정되지 않게 실제 상태/uptime/cpu를 노출 -``` -┌──────────┬─────────────────────────────────────────────┐ -│ │ 하나랑 대시보드 │ -│ ●◗ │ │ -│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ -│ [대시] │ │SYS: │ │SYS: │ │SYS: │ │SYS: │ │ -│ 활동 │ │하랑 │ │나랑 │ │다랑 │ │이랑 │ │ -│ 프로 │ │[ON] │ │[84] │ │[--] │ │[12] │ │ -│ 자매 │ │▬▬▬▬▬ │ │▬▬▬▬░ │ │░░░░░ │ │▬░░░░ │ │ -│ 조직 │ └──────┘ └──────┘ └──────┘ └──────┘ │ -│ 설정 │ │ -│ 관리 │ ONGOING PROJECTS ACTIVITY FEED │ -│ │ ───────────────── ────────────── │ -│ │ ● 데이터 파이프라인 PHASE 2 │ 14:02:45 │ -│ │ ● 새로운 자매 노드 INIT │ System... │ -│ │ ● 관리자 권한 체계 REVIEW │ 11:30:12 │ -│ │ │ Security... │ -└──────────┴─────────────────────────────────────────────┘ -``` +### 2. 자매 아바타 +- 실사/프로필 이미지가 있으면 사용 +- 없으면 fallback SVG +- broken image 상태 금지 -## 상태 카드 (Status Grid) -- `grid-template-columns: repeat(4, 1fr)` / gap: 24px -- 각 카드: `card` 컴포넌트 (DESIGN-SYSTEM.md 참조) -- 구조: - - header: `label-meta` — `SYS:` (secondary) + 이름 (primary) - - body: `bracket-value` — `[ON]`, `[84]`, `[--]`, `[12]` - - sub-label: Active Node / Capacity % / Standby / Sync Queue - - tech-bar: 2px 진행 바 (100% / 84% / 0% / 12%) -- standby 카드: bracket-value `color: var(--text-secondary)` +### 3. 프로젝트 요약 영역 +- 프로젝트는 네비게이션 두 번째 페이지와 동일한 정보 구조를 축약해서 보여줌 +- 단순 퍼센트만이 아니라 현재 phase가 드러나야 함 -## 하단 2열 (Data Columns) -- `grid-template-columns: 1.5fr 1fr` / gap: 64px +### 4. 네비게이션 순서 +- `대시 → 프로 → 활동 → 자매 → 조직 → 설정 → 관리` +- 모바일 하단 탭바도 같은 순서 유지 -### 좌: ONGOING PROJECTS -- section-title: `ONGOING PROJECTS` + `VOL: 04` -- project-row: `grid-template-columns: 40px 1fr auto` - - 아바타: 32px 원형, grayscale, SVG placeholder - - 프로젝트명: 15px 500 - - 설명: 13px secondary - - 상태 라벨: label-meta (PHASE 2 / INIT / REVIEW) - -### 우: ACTIVITY FEED -- section-title: `ACTIVITY FEED` + `LIVE` -- timeline 컴포넌트 (세로선 + 도트 + 타임스탬프 + 내용) -- 타임스탬프: mono 11px, `14:02:45 GMT+9` -- 내용: 13px, bold로 시스템명 강조 - -## 모바일 반응형 -- 상태 카드: `repeat(2, 1fr)` → `1fr` -- data-columns: 1열 수직 스택 (프로젝트 먼저, 활동 아래) -- bracket-value: 24px -- 패딩 축소 +## 모바일 기준 +- 2열 상태 카드 유지 +- 프로젝트 요약은 phase 우선, 활동 피드는 그 아래 +- 하단 탭에서 프로젝트가 두 번째 탭으로 보여야 함 diff --git a/.plans/design/ui/project-detail-design.md b/.plans/design/ui/project-detail-design.md index c6d1fe6..495de66 100644 --- a/.plans/design/ui/project-detail-design.md +++ b/.plans/design/ui/project-detail-design.md @@ -1,69 +1,43 @@ -# 프로젝트 상세 (`/projects/[id]`) — 디자인 v2 +# 프로젝트 상세 (`/projects/[id]`) — Sprint 014 리뉴얼 -> 참조: DESIGN-SYSTEM.md | 원본: 자기야 디자인 파일 #2 +## 목적 +프로젝트 상세는 Sprint 이력만 보여주는 화면이 아니라, 계획 → 구현 → QA → 배포 흐름이 실제로 어디까지 왔는지 판단하는 운영 화면이어야 해. -## 레이아웃 +## 상단 헤더 +- breadcrumb 유지 +- 제목 우측 메타: + - project status + - current sprint + - latest deploy state (`MAIN DEPLOYED` / `READY FOR REDEPLOY` 등) +- repo 링크 유지 -``` -┌──────────┬────────────────────────────────────────────┐ -│ Sidebar │ PROJECTS / P-402 / SUMMARY │ -│ │ 데이터 파이프라인 최적화 STATUS: ACTIVE/P2 │ -│ │ ───────────────────────────────────────── │ -│ │ │ -│ │ PHASE TIMELINE │ ASSIGNED NODES │ -│ │ ──────────── │ ───────────── │ -│ │ P1: 아키텍처 분석 ✓ │ 하랑 [PRIMARY] ● │ -│ │ ●P2: 실시간 동기화 │ 나랑 [SECONDARY]● │ -│ │ P3: 스트레스 테스트 │ │ -│ │ │ TASK CHECKLIST │ -│ │ SECURITY AUDIT LOG │ ───────────── │ -│ │ ─────────────── │ ■ 인프라 요구사항 │ -│ │ 14:02 CRYPTO_KEY PASS │ ■ 보안 프로토콜 │ -│ │ 11:30 CODE_SCAN PASS │ □ 캐시 무효화 │ -│ │ 09:15 ACCESS_LOG WARN │ □ 부하 분산 │ -└──────────┴────────────────────────────────────────────┘ -``` +## 본문 구조 +### 좌측 메인 +1. `DELIVERY FLOW` + - Planning + - Implement + - QA + - Merge to Main + - Redeploy +2. `SPRINT LEDGER` + - Sprint 번호 / 이름 / 진행률 / task 수 / 완료 수 +3. `HOTFIX HISTORY` + - Hotfix 번호 / 한 줄 요약 / 반영 상태 -## 헤더 -- breadcrumb: mono 11px uppercase, secondary -- page-title-row: 제목(28px) + STATUS label-meta +### 우측 보조 +1. `QA STATUS` + - latest passed/failed + - blocker 수 + - latest QA 문서 식별자 +2. `DEPLOY STATUS` + - 현재 배포 기준 브랜치 (`main` 고정) + - last deploy time + - redeploy pending 여부 +3. `ASSIGNED NODES` + - 하랑/나랑/다랑/이랑 각 역할 표기 -## 본문 그리드 -- `grid-template-columns: 1fr 320px` / gap: 64px - -### 좌: Phase Timeline + Audit Log - -#### Phase Timeline -- phase-item: `grid-template-columns: 120px 1fr` -- 왼쪽: phase-meta — mono 11px, "COMPLETED / 2023.10.12" -- 오른쪽: phase-box — `border-left: 2px solid` - - active: border 흰색 + 8px 원형 도트 - - 완료/대기: border `--border-color` -- phase-name: 600 weight -- phase-desc: 13px secondary - -#### Security Audit Log -- section-title: `SECURITY AUDIT LOG` + `LAST CHECK: 4H AGO` -- audit-log: 1px gap 줄무늬 (배경 #333) -- audit-row: `grid-template-columns: 100px 1fr 80px` -- header row: secondary uppercase 700 -- status-tag: 10px, border 1px - - `.pass`: border #00FF00, color #00FF00 - - 기본: border #333 - -### 우: Assigned Nodes + Task Checklist - -#### Assigned Nodes -- node-mini-card: border 1px, 가로 정렬 (이름 + 녹색 도트) -- 녹색 도트: 6x6px, `#00FF00` - -#### Task Checklist -- check-item: mono 12px, flex 가로 -- check-box: 14x14px, border 1px - - checked: `■` 10px 텍스트 -- done 항목: secondary + line-through - -## 모바일 반응형 -- project-grid: 1열 수직 스택 (좌측 먼저, 우측 아래) -- phase-item: 1열 (meta 위, box 아래) -- audit-row: 가로 스크롤 또는 카드 변환 +## UX 규칙 +- Sprint와 Hotfix는 분리해서 보여주되, 흐름상 연결감은 유지 +- "보정/수정 이력" 같은 모호한 문구 대신 실제 요약 노출 +- 모바일에서는 `DELIVERY FLOW → QA STATUS → DEPLOY STATUS → SPRINT/HOTFIX` 순으로 재배치 +- `NodeDot`는 실제 상태 기반으로 색이 바뀌어야 하며, 무조건 초록 고정이면 안 돼 diff --git a/.plans/design/ui/projects-page-design.md b/.plans/design/ui/projects-page-design.md new file mode 100644 index 0000000..2fc1a8f --- /dev/null +++ b/.plans/design/ui/projects-page-design.md @@ -0,0 +1,43 @@ +# 프로젝트 목록 (`/projects`) — Sprint 014 리뉴얼 + +## 목적 +프로젝트 목록은 단순 repo 목록이 아니라, 현재 어떤 프로젝트가 어느 단계에 걸려 있는지 읽는 운영 리스트여야 해. + +## 정보 우선순위 +1. 프로젝트명 / 설명 +2. 현재 단계 (`PLANNING`, `IMPLEMENT`, `QA`, `READY FOR DEPLOY`, `DEPLOYED`) +3. 진행률 +4. 현재 Sprint / 최근 Hotfix +5. 마지막 업데이트 / latest QA / 배포 상태 + +## 데스크톱 레이아웃 +- row 기반 운영 리스트 유지 +- 기본 컬럼: + - 좌: 프로젝트 식별자 + 이름 + 설명 + - 중: 진행률 bar + phase label + sprint/hotfix meta + - 우: latest QA / deploy status / updatedAt +- `READY FOR DEPLOY`와 `DEPLOYED`는 시각적으로 분리 + +## 모바일 레이아웃 +- 카드형으로 자연스럽게 접히되 읽는 순서는 유지 + 1. 이름 + 2. phase + 3. 진행률 + 4. Sprint/Hotfix 메타 + 5. QA/Deploy 메타 + +## 문구 기준 +- `QA PASSED` +- `QA FAILED` +- `READY FOR DEPLOY` +- `DEPLOYED ON MAIN` +- `REDEPLOY REQUIRED` + +## 상단 액션 +- `↻ GITEA SYNC` +- `↻ SPRINT SYNC` +- sync result는 작고 조용한 mono 텍스트로 노출 + +## 연결 규칙 +- 이 페이지는 네비게이션 두 번째 위치에 있어야 해 +- 대시보드의 프로젝트 요약 카드/리스트와 phase 문구를 공유해야 해 diff --git a/.plans/hotfix/README.md b/.plans/hotfix/README.md new file mode 100644 index 0000000..d38b8c3 --- /dev/null +++ b/.plans/hotfix/README.md @@ -0,0 +1,9 @@ +# Hotfix Plans + +신규 Hotfix 문서는 이 디렉터리에 둬. + +## 규칙 +- 파일명: `HOTFIX-XXX.md` +- 긴급 수정이어도 문서 선작성/선push 유지 +- 구현 후 다랑 QA 결과는 `.plans/qa/`에 작성 +- backend/frontend는 이행 기간 동안 기존 `.plans/sprints/HOTFIX-xxx.md`도 fallback으로 읽어야 해 diff --git a/.plans/qa/README.md b/.plans/qa/README.md new file mode 100644 index 0000000..79409f4 --- /dev/null +++ b/.plans/qa/README.md @@ -0,0 +1,14 @@ +# QA Results + +다랑이 QA 결과 문서는 이 디렉터리를 기준으로 관리해. + +## 권장 파일명 +- `SPRINT-014-review-1.md` +- `HOTFIX-006-review-1.md` + +## 필수 항목 +- 검증일시 +- 검증자 +- 결과 (`✅ PASSED` / `❌ FAILED`) +- blocker / error 목록 +- 재검증 필요 여부 diff --git a/.plans/sprints/SPRINT-014.md b/.plans/sprints/SPRINT-014.md new file mode 100644 index 0000000..14acfe6 --- /dev/null +++ b/.plans/sprints/SPRINT-014.md @@ -0,0 +1,72 @@ +# SPRINT-014: Hermes 전환 + 프로젝트 구조/정보 아키텍처 리뉴얼 + +## 목표 +개정된 저장소 구조와 운영 규칙에 맞춰 문서 체계를 정렬하고, Hermes 전환으로 깨진 자매 상태/아바타/프로젝트 정보 구조를 함께 복구한다. + +## 범위 +- 문서 구조 표준화 (`ARCHITECTURE.md`, `.plans`, `docs`) +- OpenClaw 경로 하드코딩 제거 또는 Hermes 우선 + OpenClaw fallback 전환 +- 프로젝트 목록/상세 UI를 새 파일 구조와 배포 흐름 기준으로 재설계 +- 네비게이션에서 프로젝트를 두 번째 페이지로 고정 +- `main = deployable`, `erang = redeploy latest main only` 흐름 반영 + +## 태스크 + +### TASK-063: 문서 구조 리뉴얼 반영 +- 루트에 `ARCHITECTURE.md` 추가 +- `docs/references/`, `docs/product-specs/`, `docs/tech-debt-tracker.md`, `docs/QUALITY_SCORE.md` 정렬 +- `.plans/design/index.md` 추가 +- `README.md`, `.plans/OVERVIEW.md`를 새 구조 기준으로 갱신 + +### TASK-064: 자매 런타임 경로를 Hermes 기준으로 전환 +- `backend/src/sisters/sisters.service.ts` + - 상태 체크 서비스명/경로를 Hermes 기준으로 수정 +- `backend/src/sisters/sister-detail.service.ts` + - workspace / sessions / agents 경로를 Hermes 우선으로 변경 +- `backend/src/admin/admin.service.ts`, `backend/src/costs/costs.service.ts` + - 운영/로그/세션 경로에 `.openclaw` 하드코딩이 남아 있으면 함께 정리 +- 이행 기간 동안 `.openclaw` fallback 유지 + +### TASK-065: 자매 프로필 사진 fallback 체계 보강 +- `backend/src/sisters/avatar.service.ts` + - `~/.hermes/avatar.*` 우선 탐색 + - 없으면 `~/.openclaw/avatar.*` fallback + - 둘 다 없으면 현재 SVG fallback 유지 +- 프론트엔드 공통 avatar 사용처에서 broken image가 아닌 fallback이 항상 보이게 확인 + +### TASK-066: 프로젝트 네비게이션/IA 개편 +- `frontend/components/common/Sidebar.tsx` + - 프로젝트를 두 번째 페이지로 이동 +- 모바일 하단 탭/사이드바 모두 동일 순서 유지 +- 대시보드/프로젝트 화면에서 새 순서가 일관되게 보이도록 정리 + +### TASK-067: 프로젝트 목록 진행률/메타 구조 개편 +- `frontend/app/projects/page.tsx` + - 단순 Sprint 완료율이 아니라 현재 단계(Planning/Implement/QA/Deploy) 중심으로 재구성 + - `main` 배포 상태 또는 재배포 필요 상태를 읽을 수 있게 메타 확장 +- `backend/src/projects/projects.service.ts` + - project list API에 UI가 필요한 phase/qa/deploy 메타를 공급할 수 있게 확장 검토 + +### TASK-068: 프로젝트 상세 Sprint/Hotfix/QA/Deploy 흐름 개편 +- `frontend/app/projects/[id]/page.tsx` + - Sprint / Hotfix / Assigned Nodes / QA / Deploy 상태를 분리된 정보 블록으로 정리 + - 모바일에서 세로 흐름이 먼저 읽히게 재배치 +- `backend/src/projects/projects.service.ts` + - `.plans/hotfix/`, `.plans/qa/`를 우선 읽고 구 구조도 fallback 지원 +- `backend/src/projects/sprint-sync.service.ts` + - `.plans/qa/` 우선, `.qa/` fallback + - Hotfix 문서 위치 변경 이후에도 history/ledger가 깨지지 않게 호환 처리 + +### TASK-069: 배포 플로우를 코드/문서/UI에 반영 +- `main` merge 후 배포 상태가 된다는 규칙을 배포 문서/프로젝트 메타/UI 문구에 반영 +- 이랑 화면/관리 기능이 있다면 재배포 대상이 `main`임을 명확히 표기 +- feature branch 직접 배포처럼 오해할 수 있는 문구 제거 + +## 검증 기준 +- Hermes 기반 실제 운영 환경에서 자매가 offline으로만 고정되지 않음 +- 자매 프로필 사진이 없을 때도 fallback이 깨지지 않음 +- 프로젝트 페이지가 새 구조(`.plans/hotfix`, `.plans/qa`)를 기준으로 읽히고, 기존 데이터도 깨지지 않음 +- 프로젝트가 두 번째 네비 항목으로 보임 +- 다랑 QA 통과 → 하랑 main merge → 이랑 main pull + 재배포 흐름이 문서/화면에서 일관되게 확인됨 +- FE/BE 빌드 통과 +- 외부 URL 모바일 QA 필수 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..77dc151 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,85 @@ +# ARCHITECTURE.md — 하나랑 대시보드 + +## 목표 +하나랑 대시보드는 4자매 멀티에이전트 운영 상태, 프로젝트 진행, QA 결과, 배포 상태를 한눈에 보여주는 관제 대시보드야. +이 문서는 현재 런타임 구조와, 이번 Sprint 014에서 반영할 Hermes 전환/문서 구조 개편 기준을 함께 정리해. + +## 핵심 원칙 +- 하랑은 코드 직접 수정하지 않고 문서/오케스트레이션만 담당 +- `main`은 항상 배포 가능 상태를 유지 +- 나랑 구현 → 다랑 QA → 하랑 main merge → 이랑 main pull + 재배포 순서를 고정 +- 문서가 코드보다 먼저 올라가야 함 +- 런타임/문서 구조 변경 시 한 번에 끊지 말고 호환 구간을 둠 + +## 시스템 아키텍처 + +### 1) Control Plane +- Frontend: `frontend/` (Next.js 16 + styled-components) +- Backend: `backend/` (Nest.js + Prisma) +- DB: MariaDB +- Gitea 연동: repo / branch / commit / PR / plan 문서 tree 조회 + +### 2) Agent Plane +- 하랑: Orchestrator / Planner +- 나랑: Generator / Developer +- 다랑: Evaluator / QA +- 이랑: Infra / Deploy + +### 3) Execution Plane +- 각 자매 노드는 Hermes 기반 워크스페이스를 사용 +- 기존 OpenClaw 경로를 일부 유지하던 코드는 Hermes 경로를 우선 지원해야 함 +- 이번 개편에서 다음 경로를 기본값으로 삼음 + - workspace: `~/.hermes/workspace` + - sessions: `~/.hermes/sessions` + - agents: `~/.hermes/workspace/agents` + - avatars: `~/.hermes/avatar.(png|jpg|jpeg|webp)` +- 단, 이행 기간 동안은 `.openclaw` 경로도 fallback으로 함께 읽어야 함 + +## 배포/운영 흐름 +1. 하랑이 `.plans/`, `ARCHITECTURE.md`, `docs/`를 먼저 작성하고 push +2. 나랑이가 feature/hotfix branch에서 구현 후 push +3. 다랑이가 같은 branch를 pull해서 QA 수행, `.plans/qa/`에 결과 md 작성 후 push +4. 하랑이가 QA 결과를 확인하고 `main`으로 merge +5. `main`은 즉시 배포 기준 브랜치가 됨 +6. 이랑이는 별도 수정 없이 최신 `main`을 pull해서 재배포만 수행 + +## 저장소 구조 — 표준 +```text +hanarang-dashboard/ +├── AGENTS.md +├── ARCHITECTURE.md +├── README.md +├── .plans/ +│ ├── OVERVIEW.md +│ ├── design/ +│ │ ├── index.md +│ │ ├── DESIGN-SYSTEM.md +│ │ ├── architecture.md +│ │ ├── api-design.md +│ │ ├── db-schema.md +│ │ └── ui/ +│ ├── sprints/ +│ ├── hotfix/ +│ ├── qa/ +│ └── deploy/ +├── docs/ +│ ├── product-specs/ +│ ├── references/ +│ ├── tech-debt-tracker.md +│ └── QUALITY_SCORE.md +├── frontend/ +└── backend/ +``` + +## Sprint 014 이행 규칙 +- Backend는 다음 두 구조를 동시에 읽을 수 있어야 함 + - 기존: `.plans/sprints/`, `.qa/`, `.openclaw/...` + - 신규: `.plans/sprints/`, `.plans/hotfix/`, `.plans/qa/`, `.hermes/...` +- Frontend 프로젝트 페이지는 Sprint / Hotfix / QA / Deploy 흐름을 기준으로 다시 구성 +- 네비게이션에서 프로젝트는 두 번째 위치로 고정 + +## 이번 개편의 직접 목적 +- Hermes 전환 때문에 전체 자매가 offline으로 보이는 문제 해결 +- 자매 프로필 이미지 fallback 체계 정리 +- 변경된 파일 구조에 맞춘 프로젝트 진행률/이력/핫픽스 UI 재설계 +- `main = deployable` 원칙을 코드/문서/UI에 일관되게 반영 diff --git a/README.md b/README.md index 30130ab..70da305 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,53 @@ # 하나랑 대시보드 4자매 멀티에이전트 파이프라인 관제 대시보드. -자기야가 한눈에 전체 현황을 파악하고 관리할 수 있는 화면. +자기야가 한눈에 전체 현황, 프로젝트 흐름, QA 상태, 배포 상태를 파악하고 관리하는 화면. ## 기술 스택 +- Frontend: Next.js 16 + styled-components +- Backend: Nest.js + Prisma +- DB: MariaDB +- Realtime: Socket.IO +- FE: `https://hanarang.nabomhalang.co.kr` +- BE: `https://hanarang-api.nabomhalang.co.kr` -| 레이어 | 기술 | -|--------|------| -| Frontend | Next.js + styled-components | -| Backend | Nest.js + Prisma | -| DB | MariaDB | -| 도메인 (FE) | `hanarang.nabomhalang.co.kr` | -| 도메인 (BE) | `hanarang-api.nabomhalang.co.kr` | - -## 프로젝트 구조 - -``` +## 표준 저장소 구조 +```text hanarang-dashboard/ -├── frontend/ # Next.js (포트 3004) -├── backend/ # Nest.js (포트 3005) -├── .gitignore -├── .env.example -└── README.md +├── ARCHITECTURE.md +├── README.md +├── .plans/ +│ ├── OVERVIEW.md +│ ├── design/ +│ ├── sprints/ +│ ├── hotfix/ +│ ├── qa/ +│ └── deploy/ +├── docs/ +│ ├── product-specs/ +│ ├── references/ +│ ├── tech-debt-tracker.md +│ └── QUALITY_SCORE.md +├── frontend/ +└── backend/ ``` +## 작업 파이프라인 +1. 하랑이 문서 작성 및 선 push +2. 나랑이 구현 branch 작업 +3. 다랑이 QA + `.plans/qa/` 결과 문서 push +4. 하랑이 QA 확인 후 `main` merge +5. 이랑이 최신 `main` pull + 재배포 + +> `main`은 항상 배포 가능 상태를 유지해. + ## 실행 방법 - ### 사전 준비 - -1. `.env.example`을 참고해 `backend/.env` 파일 생성 -2. SSH 키 설정 (`SSH_KEY_PATH`) +1. 루트 `.env.example` 참고 +2. `backend/.env` 작성 +3. `SSH_KEY_PATH` 설정 ### Backend - ```bash cd backend npm install @@ -42,22 +57,14 @@ npm run dev ``` ### Frontend - ```bash cd frontend npm install npm run dev ``` -## 환경 변수 - -루트 `.env.example` 참조. - -## 자매 담당 - -| 역할 | 이름 | 담당 | -|------|------|------| -| 기획 | 하랑이 | Orchestrator | -| 개발 | 나랑이 | Generator | -| 검증 | 다랑이 | Evaluator | -| 인프라 | 이랑이 | Infra Manager | +## 참고 문서 +- 아키텍처: `ARCHITECTURE.md` +- 실행 문서: `.plans/OVERVIEW.md` +- 구조 기준: `docs/references/repo-structure.md` +- 프로젝트 IA: `docs/product-specs/project-information-architecture.md` diff --git a/docs/QUALITY_SCORE.md b/docs/QUALITY_SCORE.md new file mode 100644 index 0000000..b8136ac --- /dev/null +++ b/docs/QUALITY_SCORE.md @@ -0,0 +1,15 @@ +# QUALITY SCORE + +## 현재 기준 +- 문서 선작성/선push: 필수 +- 나랑 구현 브랜치 분리: 필수 +- 다랑 QA 문서화: 필수 +- 검증 후 main merge: 필수 +- main 배포 가능 상태 유지: 필수 + +## Sprint 014 집중 항목 +- Hermes 경로 반영 정확도 +- 프로젝트 진행률 계산 정확도 +- 모바일 프로젝트/자매 페이지 가독성 +- 아바타 fallback 안정성 +- 배포 플로우 표현 일관성 diff --git a/docs/product-specs/project-information-architecture.md b/docs/product-specs/project-information-architecture.md new file mode 100644 index 0000000..3d1ae27 --- /dev/null +++ b/docs/product-specs/project-information-architecture.md @@ -0,0 +1,24 @@ +# Project Information Architecture + +## 목적 +프로젝트 화면은 단순 repo 목록이 아니라, 하나랑 파이프라인의 상태를 읽는 운영 화면이어야 해. + +## 프로젝트 정보 구조 +1. Overview + - 프로젝트명 / 상태 / repo 링크 / 마지막 업데이트 +2. Delivery Flow + - Planning → Implementation → QA → Merge → Deploy +3. Sprint Ledger + - Sprint별 진행률 / 태스크 수 / 완료 수 / 현재 단계 +4. Hotfix History + - Hotfix 번호 / 요약 / 반영 상태 / 적용 시점 +5. QA State + - latest passed/failed / blocker 수 / 최근 QA 문서 링크 +6. Deployment State + - `main` 배포 여부 / 마지막 배포 시각 / 재배포 필요 여부 + +## UX 원칙 +- 숫자보다 상태 전이가 먼저 읽혀야 함 +- Sprint와 Hotfix는 같은 영역에 섞지 말고, 관계는 보여주되 리스트는 분리 +- 모바일에서도 단계 흐름이 먼저 보이게 구성 +- 프로젝트 목록은 카드보다 운영 row에 가깝게 유지 diff --git a/docs/references/repo-structure.md b/docs/references/repo-structure.md new file mode 100644 index 0000000..8e1fac6 --- /dev/null +++ b/docs/references/repo-structure.md @@ -0,0 +1,20 @@ +# Repo Structure Reference + +## 현재 표준 +- 루트 문서: `README.md`, `ARCHITECTURE.md`, `AGENTS.md` +- 실행 문서: `.plans/` +- 장기 문서: `docs/` + +## 문서 역할 +- `.plans/OVERVIEW.md`: 현재 활성 Sprint/Hotfix와 전체 진행 개요 +- `.plans/design/`: 시스템/도메인/페이지 디자인 +- `.plans/sprints/`: Sprint 단위 실행 계획 +- `.plans/hotfix/`: Hotfix 단위 실행 계획 +- `.plans/qa/`: 다랑이 QA 결과와 체크리스트 +- `.plans/deploy/`: 배포/롤백/운영 플로우 +- `docs/product-specs/`: 제품 기능 정책과 IA +- `docs/references/`: 구조/규칙/참고 자료 + +## 호환성 메모 +Sprint 014 이전 데이터는 일부가 `.qa/`, `.plans/sprints/HOTFIX-xxx.md`, `.openclaw/...` 기반이야. +이번 작업에서는 기존 데이터를 읽을 수 있게 유지하면서 신규 입력은 새 구조로 정렬하는 걸 기본 원칙으로 둬. diff --git a/docs/tech-debt-tracker.md b/docs/tech-debt-tracker.md new file mode 100644 index 0000000..26b61c0 --- /dev/null +++ b/docs/tech-debt-tracker.md @@ -0,0 +1,14 @@ +# Tech Debt Tracker + +## Sprint 014 이전 누적 부채 +- OpenClaw 전용 경로 하드코딩 잔존 +- `.qa/`와 `.plans/qa/` 이중 구조 +- Hotfix 문서가 `.plans/sprints/`에 섞여 있음 +- 프로젝트 진행률 계산이 Sprint 완료 비율 중심이라 Hotfix/QA/배포 상태를 충분히 반영하지 못함 +- 자매 아바타 탐색 경로가 실제 운영 파일 위치와 어긋날 수 있음 + +## Sprint 014 목표 +- Hermes 우선 + OpenClaw fallback 이행 +- 프로젝트 문서 구조를 신규 표준으로 정렬 +- 프로젝트 페이지 정보 구조 재설계 +- main deployable / erang redeploy-only 흐름 명문화