# Agent Office 그리드 재설계 — Design Spec

**Date:** 2026-05-17
**Author:** CEO (with Claude)
**Target:** `web-ui` `/agent-office` 페이지

---

## 1. 배경 & 목적

현재 `/agent-office` 페이지는 픽셀 사무실 Canvas 위에서 5명의 에이전트 캐릭터가 무의미하게 걸어다니는 형태다. 시각적 즐거움은 있으나 정보 밀도가 낮고, 각 에이전트가 무슨 일을 하는지 한눈에 파악하기 어렵다.

이를 **3x3 그리드** 기반의 정보 중심 UI로 재설계한다. 왼편에 9개의 에이전트 이미지 카드를 배치하고, 카드 클릭 시 오른편 패널에서 해당 에이전트의 명령·태스크·토큰·로그를 확인한다.

---

## 2. 범위 (Scope)

### In scope
- `src/pages/agent-office/AgentOffice.jsx` 전면 재작성 (Canvas → Grid)
- 그리드 카드 컴포넌트 신규 작성
- `SidePanel.jsx` 헤더 부분 수정 (emoji → 이미지)
- `SidePanel.jsx`의 `AGENT_META`에서 `blog` 제거, `insta` 추가
- TopBar 단순화 (theme/zoom 컨트롤 제거)
- Canvas 관련 파일/디렉토리 전체 삭제
- 이미지 에셋 디렉토리 신설

### Out of scope
- 백엔드 변경 (현재 백엔드의 `insta` 에이전트는 이미 등록 완료, 추가 작업 불필요)
- 새 에이전트 추가 (4개 placeholder는 "준비 중" 표시만)
- 4탭 컨텐츠 (Commands/Tasks/Tokens/Logs) 로직 수정

---

## 3. 에이전트 구성

### 실제 작동 5명

| ID | 표시명 | 색상 | 역할 요약 |
|----|--------|------|-----------|
| `stock` | 주식 트레이더 | `#4488cc` | 주식 매매·뉴스 분석·포트폴리오 |
| `music` | 음악 프로듀서 | `#44aa88` | AI 음악 생성 |
| `insta` | 인스타 큐레이터 | `#d97706` | 매일 09:30 뉴스 수집 → 키워드 추출 → AI 카드 10장 생성 → 텔레그램 푸시 |
| `realestate` | 청약 애널리스트 | `#c026d3` | 부동산 청약 매칭·자치구 5티어 분석 |
| `lotto` | 로또 큐레이터 | `#ef4444` | 로또 번호 추천·브리핑 |

> `blog`는 `insta`로 대체됨. 기존 `SidePanel.jsx`의 `AGENT_META`에서 `blog` 항목 삭제 + `insta` 추가.

### Placeholder 4개

- ID 없음 (그리드 슬롯 인덱스 6/7/8/9로만 식별)
- 모두 동일하게 `agent_undetermined.png` + "준비 중" 라벨
- 클릭 시 정적 안내 패널 노출

---

## 4. 디렉토리 & 파일 구조

### 신설 디렉토리

```
src/pages/agent-office/assets/agents/
├── agent_stock.png          (사용자 제공)
├── agent_music.png          (사용자 제공)
├── agent_insta.png          (사용자 제공)
├── agent_realestate.png     (사용자 제공)
├── agent_lotto.png          (사용자 제공)
└── agent_undetermined.png   (사용자 제공, 4 placeholder 공유)
```

### 파일명 규칙
`agent_{id}.png` 형식. `{id}`는 백엔드의 agent_id와 일치 (소문자, underscore).

### 권장 이미지 사양
- 정사각형 (예: 512x512)
- PNG (투명 배경 허용)
- 카드 표시 시 `object-fit: cover`로 정사각 크롭

### 삭제 대상

```
src/pages/agent-office/
├── canvas/                  ← 전체 삭제
│   ├── themes.js
│   ├── FurnitureRenderer.js
│   ├── ProceduralSprite.js
│   ├── AgentSprite.js
│   ├── SpriteLoader.js
│   ├── OverlayRenderer.js
│   ├── Pathfinder.js
│   ├── OfficeRenderer.js
│   └── TileMap.js
├── hooks/
│   └── useOfficeCanvas.js   ← 삭제
└── assets/
    └── office-map.json      ← 삭제
```

### 유지 대상

```
src/pages/agent-office/
├── AgentOffice.jsx               ← 재작성
├── AgentOffice.css               ← 재작성
├── hooks/
│   └── useAgentManager.js        ← 그대로 (WebSocket 로직)
└── components/
    ├── TopBar.jsx                ← 단순화 (theme/zoom 제거)
    ├── SidePanel.jsx             ← 헤더 수정 + AGENT_META 갱신
    ├── CommandTab.jsx            ← 그대로
    ├── TaskTab.jsx               ← 그대로
    ├── TokenTab.jsx              ← 그대로
    └── LogTab.jsx                ← 그대로
```

### 신규 컴포넌트

```
src/pages/agent-office/components/
├── AgentGrid.jsx           ← 3x3 그리드 래퍼
├── AgentCard.jsx           ← 카드 1개 (image + state dot + badge + name)
├── PlaceholderCard.jsx     ← "준비 중" 카드
└── EmptyDetailPanel.jsx    ← 초기 안내 / placeholder 클릭 시 안내
```

---

## 5. 레이아웃

### 전체 화면 구조

```
┌─────────────────────────────────────────────────────────────┐
│  TopBar (connected status only)                              │
├──────────────────────────────────┬──────────────────────────┤
│                                  │                          │
│  AgentGrid (3x3)                 │  Right Panel              │
│  ┌──────┬──────┬──────┐          │                          │
│  │stock │music │insta │          │  ┌─ active 선택 시 ─┐    │
│  ├──────┼──────┼──────┤          │  │ SidePanel        │    │
│  │realE │lotto │  ??  │          │  │ - 헤더(이미지+이름)│    │
│  ├──────┼──────┼──────┤          │  │ - 4 tabs         │    │
│  │  ??  │  ??  │  ??  │          │  └──────────────────┘    │
│  └──────┴──────┴──────┘          │                          │
│                                  │  ┌─ placeholder 선택 ─┐  │
│                                  │  │ "준비 중인 에이전트"│  │
│                                  │  └────────────────────┘  │
│                                  │                          │
│                                  │  ┌─ 초기(미선택) ──────┐ │
│                                  │  │ "에이전트를 선택…"  │ │
│                                  │  └────────────────────┘ │
└──────────────────────────────────┴──────────────────────────┘
```

### 그리드 슬롯 순서 (좌→우, 위→아래)

| Index | Slot |
|-------|------|
| 1 (행1·열1) | `stock` |
| 2 (행1·열2) | `music` |
| 3 (행1·열3) | `insta` |
| 4 (행2·열1) | `realestate` |
| 5 (행2·열2) | `lotto` |
| 6 (행2·열3) | placeholder |
| 7 (행3·열1) | placeholder |
| 8 (행3·열2) | placeholder |
| 9 (행3·열3) | placeholder |

### AgentCard 시각 구조

```
┌─────────────────────┐
│ ● state    [③]      │ ← 상태 dot(좌상, image 약간 위) + 알림 뱃지(우상)
│  ┌───────────────┐  │
│  │               │  │
│  │  agent_xxx    │  │ ← 정사각 이미지 (object-fit: cover)
│  │     .png      │  │
│  │               │  │
│  └───────────────┘  │
│   주식 트레이더      │ ← display_name
└─────────────────────┘
```

#### 상태 dot

| state | color | 동작 |
|-------|-------|------|
| `idle` | `#6b7280` (회색) | 정적 |
| `working` | `#22c55e` (초록) | pulse 애니메이션 |
| `error` | `#ef4444` (빨강) | 정적 |
| `waiting_approval` | `#f59e0b` (주황) | pulse |
| `break` | `#94a3b8` (밝은 회색) | 정적 |

상태 dot은 카드의 좌상단, 이미지보다 약간 위쪽에 위치 (이미지 영역 바깥 또는 모서리 살짝 걸침).

#### 알림 뱃지

- `notifications[agentId] > 0`일 때만 우상단에 표시
- 빨강 배경에 흰 숫자 (count > 9면 "9+")
- 카드 클릭 시 자동으로 0으로 리셋 (`clearNotifications` 호출 — 기존 로직 재사용)

---

## 6. 데이터 플로우

```
useAgentManager (그대로 유지)
   ├── WebSocket /api/agent-office/ws
   ├── agents: { [id]: { state, detail, task_id } }
   ├── notifications: { [id]: count }
   ├── pendingTasks: [...]
   ├── connected: bool
   └── refreshTrigger: number

AgentOffice.jsx
   ├── agents → AgentGrid에 전달 → 각 AgentCard가 state로 dot 색상 결정
   ├── notifications → 각 AgentCard가 badge 표시
   ├── selectedAgent (local state): string | null | "placeholder"
   └── 카드 클릭 시 setSelectedAgent + clearNotifications

Right Panel 분기
   ├── selectedAgent === null         → EmptyDetailPanel (초기 안내)
   ├── selectedAgent === "placeholder"→ EmptyDetailPanel ("준비 중" 메시지)
   └── selectedAgent ∈ active 5명     → SidePanel (4탭, 기존 로직)
```

---

## 7. SidePanel 수정 사항

### AGENT_META 갱신

```js
// src/pages/agent-office/components/SidePanel.jsx
import stockImg from '../assets/agents/agent_stock.png';
import musicImg from '../assets/agents/agent_music.png';
import instaImg from '../assets/agents/agent_insta.png';
import realestateImg from '../assets/agents/agent_realestate.png';
import lottoImg from '../assets/agents/agent_lotto.png';

const AGENT_META = {
  stock:      { displayName: '주식 트레이더',  image: stockImg,      color: '#4488cc' },
  music:      { displayName: '음악 프로듀서',  image: musicImg,      color: '#44aa88' },
  insta:      { displayName: '인스타 큐레이터', image: instaImg,      color: '#d97706' },
  realestate: { displayName: '청약 애널리스트', image: realestateImg, color: '#c026d3' },
  lotto:      { displayName: '로또 큐레이터',  image: lottoImg,      color: '#ef4444' }
};
// blog 항목 삭제
```

### 헤더 시각 변경

```jsx
// 변경 전: emoji icon
<div className="ao-sidepanel-icon" style={{ background: meta.color }}>
  {meta.emoji}
</div>

// 변경 후: 이미지
<div className="ao-sidepanel-icon" style={{ borderColor: meta.color }}>
  <img src={meta.image} alt={meta.displayName} />
</div>
```

4탭(Commands/Tasks/Tokens/Logs) 본체 로직은 손대지 않음.

---

## 8. CSS 토큰 (제안)

```css
:root {
  --ao-bg: #0f172a;
  --ao-card-bg: #1e293b;
  --ao-card-border: #334155;
  --ao-card-border-active: #60a5fa;
  --ao-text: #e2e8f0;
  --ao-text-muted: #94a3b8;
  --ao-grid-gap: 16px;
  --ao-card-radius: 12px;
}

.ao-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: var(--ao-grid-gap);
}

.ao-card {
  aspect-ratio: 1 / 1.15;  /* 이미지 정사각 + 이름줄 */
  background: var(--ao-card-bg);
  border: 1px solid var(--ao-card-border);
  border-radius: var(--ao-card-radius);
  cursor: pointer;
  transition: transform 120ms ease, border-color 120ms ease;
}

.ao-card:hover { transform: translateY(-2px); }
.ao-card.active { border-color: var(--ao-card-border-active); }
.ao-card.placeholder { opacity: 0.55; cursor: pointer; }
```

반응형: 모바일에서는 `grid-template-columns: repeat(2, 1fr)` 또는 `repeat(1, 1fr)`로 축소.

---

## 9. 에러 처리 / Edge Cases

| 상황 | 동작 |
|------|------|
| 이미지 로드 실패 | `<img onError>`로 단색 배경 + 첫 글자 fallback |
| WebSocket 끊김 | TopBar에 disconnected 표시. 카드는 마지막 상태 유지 (회색 처리 안 함 — 기존 동작 유지) |
| `agents[id]` 미존재 | dot 회색(`idle`), 정상 표시 |
| placeholder 클릭 | 우측 패널만 변경, WebSocket 호출/clearNotifications 호출 없음 |

---

## 10. 테스트 계획

- [ ] 6개 이미지 파일이 디렉토리에 존재할 때 그리드 정상 렌더링
- [ ] 이미지 누락 시 fallback 표시
- [ ] WebSocket으로 `agent_state` 수신 시 dot 색상 변경
- [ ] `notification` 수신 시 뱃지 표시, 카드 클릭 시 0으로 리셋
- [ ] active 5명 클릭 → SidePanel 4탭 표시 (기존 동작 유지)
- [ ] placeholder 4슬롯 클릭 → "준비 중" 패널
- [ ] TopBar의 connected/disconnected 표시 정상
- [ ] Canvas 잔재(파일 import 누락 등) 없음 — `npm run build` 통과
- [ ] 모바일 뷰(<768px) 그리드 축소 정상

---

## 11. 이행 절차 (사용자 작업 포함)

1. **사용자**: `src/pages/agent-office/assets/agents/` 디렉토리에 6개 PNG 파일 배치
2. **Claude (구현 단계)**: writing-plans 스킬로 단계별 작업 계획 작성
3. 구현·삭제·테스트 후 commit
4. NAS 배포는 별도 (`npm run release:nas`)

---

## 12. 향후 확장

- 9번째 active 에이전트 채용 시: 이미지 추가 + `AGENT_META` 갱신 + 슬롯 인덱스 매핑 변경
- 그리드 자동 정렬(상태별/우선순위별 sort) — 현재는 정적 배치
- 카드 hover 시 미니 프리뷰 (최근 활동 1줄 요약) — 추후 검토
