hanarang/hanarang-dashboard
5
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: plan sprint-014 hermes renewal

Browse Source
This commit is contained in:
하랑이
2026-04-05 15:00:46 +09:00
parent fb6b5f8b49
commit 49f075ae7c
15 changed files with 496 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
.plans/OVERVIEW.md
View File

@@ -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`

40
.plans/deploy/main-release-flow.md Normal file
View File

@@ -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 진행

23
.plans/design/index.md Normal file
View File

@@ -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 반영

77
.plans/design/ui/dashboard-design.md
View File

@@ -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 우선, 활동 피드는 그 아래
- 하단 탭에서 프로젝트가 두 번째 탭으로 보여야 함

102
.plans/design/ui/project-detail-design.md
View File

@@ -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`는 실제 상태 기반으로 색이 바뀌어야 하며, 무조건 초록 고정이면 안 돼

43
.plans/design/ui/projects-page-design.md Normal file
View File

@@ -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 문구를 공유해야 해

9
.plans/hotfix/README.md Normal file
View File

@@ -0,0 +1,9 @@
# Hotfix Plans
신규 Hotfix 문서는 이 디렉터리에 둬.
## 규칙
- 파일명: `HOTFIX-XXX.md`
- 긴급 수정이어도 문서 선작성/선push 유지
- 구현 후 다랑 QA 결과는 `.plans/qa/`에 작성
- backend/frontend는 이행 기간 동안 기존 `.plans/sprints/HOTFIX-xxx.md`도 fallback으로 읽어야 해

14
.plans/qa/README.md Normal file
View File

@@ -0,0 +1,14 @@
# QA Results
다랑이 QA 결과 문서는 이 디렉터리를 기준으로 관리해.
## 권장 파일명
- `SPRINT-014-review-1.md`
- `HOTFIX-006-review-1.md`
## 필수 항목
- 검증일시
- 검증자
- 결과 (`✅ PASSED` / `❌ FAILED`)
- blocker / error 목록
- 재검증 필요 여부

72
.plans/sprints/SPRINT-014.md Normal file
View File

@@ -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 필수

85
ARCHITECTURE.md Normal file
View File

@@ -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에 일관되게 반영

77
README.md
View File

@@ -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`

15
docs/QUALITY_SCORE.md Normal file
View File

@@ -0,0 +1,15 @@
# QUALITY SCORE
## 현재 기준
- 문서 선작성/선push: 필수
- 나랑 구현 브랜치 분리: 필수
- 다랑 QA 문서화: 필수
- 검증 후 main merge: 필수
- main 배포 가능 상태 유지: 필수
## Sprint 014 집중 항목
- Hermes 경로 반영 정확도
- 프로젝트 진행률 계산 정확도
- 모바일 프로젝트/자매 페이지 가독성
- 아바타 fallback 안정성
- 배포 플로우 표현 일관성

24
docs/product-specs/project-information-architecture.md Normal file
View File

@@ -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에 가깝게 유지

20
docs/references/repo-structure.md Normal file
View File

@@ -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/...` 기반이야.
이번 작업에서는 기존 데이터를 읽을 수 있게 유지하면서 신규 입력은 새 구조로 정렬하는 걸 기본 원칙으로 둬.

14
docs/tech-debt-tracker.md Normal file
View File

@@ -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 흐름 명문화