docs(refactor): 기능 모듈 구조 컨벤션 + Subscription 분해 설계·계획
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHXzpsZQxKG9hQmNRfZjRS
This commit is contained in:
@@ -0,0 +1,552 @@
|
|||||||
|
# FE 모듈 구조 컨벤션 + Subscription 분해 Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** `Subscription.jsx`(1647줄)를 기능 모듈 구조(shell + components/ + utils)로 **동작 보존 분해**하고, 컨벤션을 CLAUDE.md/README에 기록한다.
|
||||||
|
|
||||||
|
**Architecture:** 순수 추출(코드 이동)만. 상수·순수헬퍼→`subscriptionUtils.js`, 각 sub-component→`components/*.jsx`, `Subscription.jsx`는 shell로 축소. 각 Task는 코드를 옮기고 import를 배선한 뒤 build+전체 테스트 green으로 동작 보존을 확인. 로직/JSX/스타일 한 줄도 바꾸지 않음.
|
||||||
|
|
||||||
|
**Tech Stack:** React 18 + Vite, Vitest + @testing-library/react.
|
||||||
|
|
||||||
|
## Global Constraints
|
||||||
|
|
||||||
|
- **Behavior-preserving 순수 추출**: 옮기는 컴포넌트/헬퍼의 본문(JSX·로직)은 **verbatim(그대로)**. import 배선만 추가/변경. 동작·스타일·클래스명 불변.
|
||||||
|
- 경로: `Subscription.jsx`(`src/pages/subscription/`)는 api를 `'../../api'`로 import. `components/*.jsx`는 `'../../../api'`, utils는 `'../subscriptionUtils'`. shell은 CSS `'./Subscription.css'` import 유지.
|
||||||
|
- 각 Task 완료 조건: `npm run build` 성공 + `npm run test:run` 전체 green(회귀 0) + `npm run lint` 신규/수정 파일 0 에러.
|
||||||
|
- 테스트: Vitest `import { describe, it, expect } from 'vitest'`, jest-dom 전역(테스트 파일 import 불필요), `*.test.js(x)` 동일 디렉토리.
|
||||||
|
- `/realestate/listings` 교차링크(shell의 `<Link>`)와 `PullToRefresh`/`FAB`/탭 동작 유지.
|
||||||
|
- 커밋은 web-ui 경로, 변경 파일만 `git add`. 커밋 trailer:
|
||||||
|
```
|
||||||
|
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
||||||
|
Claude-Session: https://claude.ai/code/session_01UHXzpsZQxKG9hQmNRfZjRS
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 1: `subscriptionUtils.js` — 상수·순수헬퍼 추출 + 테스트
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `src/pages/subscription/subscriptionUtils.js`
|
||||||
|
- Test: `src/pages/subscription/subscriptionUtils.test.js`
|
||||||
|
- Modify: `src/pages/subscription/Subscription.jsx` (해당 정의 제거 + import 추가)
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Produces: `STATUS_CONFIG`, `HOUSE_TYPE_LABELS`, `TABS`, `STATUS_FILTERS`, `DEFAULT_PROFILE`, `extractTier(reasons)`, `fmt(d)`, `fmtFull(d)`, `getDDays(d)`, `getDDayColor(d)`, `fmtDateTime(d)`, `apiPatch(path,body)`, `fmtPrice(v)`.
|
||||||
|
|
||||||
|
- [ ] **Step 1: Write the failing test** — Create `src/pages/subscription/subscriptionUtils.test.js`:
|
||||||
|
|
||||||
|
```js
|
||||||
|
import { describe, it, expect } from 'vitest';
|
||||||
|
import { extractTier, getDDays, getDDayColor, fmtPrice } from './subscriptionUtils.js';
|
||||||
|
|
||||||
|
describe('extractTier', () => {
|
||||||
|
it('자치구 티어 문자열에서 등급 추출', () => {
|
||||||
|
expect(extractTier(['자치구 S티어: 강남구 (+25)'])).toBe('S');
|
||||||
|
expect(extractTier(['면적 +10', '자치구 B티어: 노원구 (+15)'])).toBe('B');
|
||||||
|
});
|
||||||
|
it('미매치/빈 입력 → null', () => {
|
||||||
|
expect(extractTier(['면적 적합'])).toBe(null);
|
||||||
|
expect(extractTier(null)).toBe(null);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getDDays / getDDayColor (오늘 기준 경계)', () => {
|
||||||
|
const iso = (offsetDays) => {
|
||||||
|
const d = new Date(); d.setHours(0,0,0,0); d.setDate(d.getDate() + offsetDays);
|
||||||
|
const p = (n) => String(n).padStart(2, '0');
|
||||||
|
return `${d.getFullYear()}-${p(d.getMonth()+1)}-${p(d.getDate())}`;
|
||||||
|
};
|
||||||
|
it('오늘=D-Day, 미래=D-N, 과거=D+N', () => {
|
||||||
|
expect(getDDays(iso(0))).toBe('D-Day');
|
||||||
|
expect(getDDays(iso(5))).toBe('D-5');
|
||||||
|
expect(getDDays(iso(-3))).toBe('D+3');
|
||||||
|
expect(getDDays(null)).toBe(null);
|
||||||
|
});
|
||||||
|
it('색 임계: 지남=빨강, ≤3=주황, ≤7=파랑, 그 외=dim', () => {
|
||||||
|
expect(getDDayColor(iso(-1))).toBe('#f87171');
|
||||||
|
expect(getDDayColor(iso(2))).toBe('#f59e0b');
|
||||||
|
expect(getDDayColor(iso(6))).toBe('#00d4ff');
|
||||||
|
expect(getDDayColor(iso(30))).toBe('var(--text-dim)');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('fmtPrice (현 구현 동작 고정)', () => {
|
||||||
|
it('억/만 변환', () => {
|
||||||
|
expect(fmtPrice(10000)).toBe('1억');
|
||||||
|
expect(fmtPrice(15000)).toBe('1.5억');
|
||||||
|
expect(fmtPrice(9999)).toBe('9,999만');
|
||||||
|
expect(fmtPrice(null)).toBe(null);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Run test to verify it fails**
|
||||||
|
|
||||||
|
Run: `npm run test:run -- src/pages/subscription/subscriptionUtils.test.js`
|
||||||
|
Expected: FAIL — `Failed to resolve import "./subscriptionUtils.js"`.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Create subscriptionUtils.js** (아래 내용 — `Subscription.jsx` 현재 상수/헬퍼를 그대로 옮김; `_diffDays`는 내부 유지·미export):
|
||||||
|
|
||||||
|
```js
|
||||||
|
/* 청약(Subscription) 모듈 상수·순수 헬퍼 */
|
||||||
|
|
||||||
|
export const STATUS_CONFIG = {
|
||||||
|
'청약예정': { color: '#00d4ff', bg: 'rgba(0,212,255,0.1)' },
|
||||||
|
'청약중': { color: '#8b5cf6', bg: 'rgba(139,92,246,0.1)' },
|
||||||
|
'결과발표': { color: '#f59e0b', bg: 'rgba(245,158,11,0.1)' },
|
||||||
|
'완료': { color: '#34d399', bg: 'rgba(52,211,153,0.12)' },
|
||||||
|
};
|
||||||
|
|
||||||
|
export const HOUSE_TYPE_LABELS = {
|
||||||
|
'01': '국민주택',
|
||||||
|
'02': '민영주택',
|
||||||
|
'03': '도시형생활주택',
|
||||||
|
};
|
||||||
|
|
||||||
|
export const TABS = ['대시보드', '공고 목록', '매칭 결과', '내 프로필'];
|
||||||
|
|
||||||
|
export const STATUS_FILTERS = ['전체', '청약예정', '청약중', '결과발표', '완료'];
|
||||||
|
|
||||||
|
export const DEFAULT_PROFILE = {
|
||||||
|
name: '', age: '', is_homeless: false, is_householder: false,
|
||||||
|
subscription_months: '', subscription_amount: '',
|
||||||
|
family_members: '', has_dependents: false, children_count: '',
|
||||||
|
is_newlywed: false, marriage_months: '',
|
||||||
|
has_newborn: false, is_first_home: false, income_level: '',
|
||||||
|
preferred_regions: '', preferred_types: '',
|
||||||
|
min_area: '', max_area: '', max_price: '',
|
||||||
|
preferred_districts: {},
|
||||||
|
min_match_score: 70,
|
||||||
|
notify_enabled: true,
|
||||||
|
};
|
||||||
|
|
||||||
|
export function extractTier(reasons) {
|
||||||
|
for (const r of reasons || []) {
|
||||||
|
const m = r.match(/자치구 ([SABCD])티어/);
|
||||||
|
if (m) return m[1];
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
export const fmt = (d) => {
|
||||||
|
if (!d) return '-';
|
||||||
|
return new Date(d).toLocaleDateString('ko-KR', { month: 'short', day: 'numeric' });
|
||||||
|
};
|
||||||
|
|
||||||
|
export const fmtFull = (d) => {
|
||||||
|
if (!d) return '-';
|
||||||
|
return new Date(d).toLocaleDateString('ko-KR', { year: 'numeric', month: 'long', day: 'numeric' });
|
||||||
|
};
|
||||||
|
|
||||||
|
const _diffDays = (d) => {
|
||||||
|
if (!d) return null;
|
||||||
|
const [y, m, day] = d.split('-').map(Number);
|
||||||
|
const target = new Date(y, m - 1, day);
|
||||||
|
const today = new Date();
|
||||||
|
today.setHours(0, 0, 0, 0);
|
||||||
|
return Math.round((target - today) / 86400000);
|
||||||
|
};
|
||||||
|
|
||||||
|
export const getDDays = (d) => {
|
||||||
|
const diff = _diffDays(d);
|
||||||
|
if (diff === null) return null;
|
||||||
|
if (diff === 0) return 'D-Day';
|
||||||
|
return diff > 0 ? `D-${diff}` : `D+${Math.abs(diff)}`;
|
||||||
|
};
|
||||||
|
|
||||||
|
export const getDDayColor = (d) => {
|
||||||
|
const diff = _diffDays(d);
|
||||||
|
if (diff === null) return 'var(--text-dim)';
|
||||||
|
if (diff <= 0) return '#f87171';
|
||||||
|
if (diff <= 3) return '#f59e0b';
|
||||||
|
if (diff <= 7) return '#00d4ff';
|
||||||
|
return 'var(--text-dim)';
|
||||||
|
};
|
||||||
|
|
||||||
|
export const fmtDateTime = (d) => {
|
||||||
|
if (!d) return '-';
|
||||||
|
return new Date(d).toLocaleString('ko-KR', {
|
||||||
|
year: 'numeric', month: '2-digit', day: '2-digit',
|
||||||
|
hour: '2-digit', minute: '2-digit',
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
export async function apiPatch(path, body) {
|
||||||
|
const opts = {
|
||||||
|
method: 'PATCH',
|
||||||
|
headers: { 'Accept': 'application/json' },
|
||||||
|
};
|
||||||
|
if (body !== undefined) {
|
||||||
|
opts.headers['Content-Type'] = 'application/json';
|
||||||
|
opts.body = JSON.stringify(body);
|
||||||
|
}
|
||||||
|
const res = await fetch(path, opts);
|
||||||
|
if (!res.ok) {
|
||||||
|
const text = await res.text().catch(() => '');
|
||||||
|
throw new Error(`HTTP ${res.status} ${res.statusText}: ${text}`);
|
||||||
|
}
|
||||||
|
return res.json();
|
||||||
|
}
|
||||||
|
|
||||||
|
export const fmtPrice = (v) => {
|
||||||
|
if (v == null) return null;
|
||||||
|
if (v >= 10000) return `${(v / 10000).toFixed(v % 10000 === 0 ? 0 : 1)}억`;
|
||||||
|
return `${v.toLocaleString()}만`;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 4: Wire Subscription.jsx** — `src/pages/subscription/Subscription.jsx`에서: 위 상수/헬퍼의 **기존 정의(현 파일 상단 STATUS_CONFIG~fmtPrice, 로컬 apiPatch 포함)를 삭제**하고, 최상단 import 블록에 추가:
|
||||||
|
|
||||||
|
```js
|
||||||
|
import {
|
||||||
|
STATUS_CONFIG, HOUSE_TYPE_LABELS, TABS, STATUS_FILTERS, DEFAULT_PROFILE,
|
||||||
|
extractTier, fmt, fmtFull, getDDays, getDDayColor, fmtDateTime, apiPatch, fmtPrice,
|
||||||
|
} from './subscriptionUtils';
|
||||||
|
```
|
||||||
|
(이 시점엔 컴포넌트들이 아직 Subscription.jsx 내부에 있으므로 import한 심볼을 그대로 사용. 나머지 컴포넌트 정의는 유지.)
|
||||||
|
|
||||||
|
- [ ] **Step 5: Run tests + build**
|
||||||
|
|
||||||
|
Run: `npm run test:run -- src/pages/subscription/subscriptionUtils.test.js` → PASS.
|
||||||
|
Run: `npm run test:run` → 전체 green.
|
||||||
|
Run: `npm run build` → `✓ built` (Subscription 동작 보존).
|
||||||
|
|
||||||
|
- [ ] **Step 6: Commit**
|
||||||
|
```bash
|
||||||
|
git add src/pages/subscription/subscriptionUtils.js src/pages/subscription/subscriptionUtils.test.js src/pages/subscription/Subscription.jsx
|
||||||
|
git commit -m "refactor(subscription): 상수·순수헬퍼를 subscriptionUtils로 추출 + 테스트"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 2: `StatusBadge` 컴포넌트 추출 + 스모크
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `src/pages/subscription/components/StatusBadge.jsx`
|
||||||
|
- Test: `src/pages/subscription/components/StatusBadge.test.jsx`
|
||||||
|
- Modify: `src/pages/subscription/Subscription.jsx`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes (Task 1): `STATUS_CONFIG`.
|
||||||
|
- Produces: `StatusBadge` 기본 export — `({ status, size })`.
|
||||||
|
|
||||||
|
- [ ] **Step 1: Write the failing smoke test** — Create `src/pages/subscription/components/StatusBadge.test.jsx`:
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
import { describe, it, expect } from 'vitest';
|
||||||
|
import { render, screen } from '@testing-library/react';
|
||||||
|
import StatusBadge from './StatusBadge.jsx';
|
||||||
|
|
||||||
|
describe('StatusBadge', () => {
|
||||||
|
it('status 라벨 렌더', () => {
|
||||||
|
render(<StatusBadge status="청약중" />);
|
||||||
|
expect(screen.getByText('청약중')).toBeInTheDocument();
|
||||||
|
});
|
||||||
|
it('미정의 status → "알 수 없음" 폴백', () => {
|
||||||
|
render(<StatusBadge status={null} />);
|
||||||
|
expect(screen.getByText('알 수 없음')).toBeInTheDocument();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Run test to verify it fails**
|
||||||
|
|
||||||
|
Run: `npm run test:run -- src/pages/subscription/components/StatusBadge.test.jsx`
|
||||||
|
Expected: FAIL — `Failed to resolve import "./StatusBadge.jsx"`.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Create StatusBadge.jsx** (현 `Subscription.jsx`의 StatusBadge 정의를 그대로 옮기고 상단 import 추가):
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
import React from 'react';
|
||||||
|
import { STATUS_CONFIG } from '../subscriptionUtils';
|
||||||
|
|
||||||
|
function StatusBadge({ status, size }) {
|
||||||
|
const cfg = STATUS_CONFIG[status] || { color: '#94a3b8', bg: 'rgba(148,163,184,0.1)' };
|
||||||
|
const cls = size === 'lg' ? 'sub-badge sub-badge--lg' : 'sub-badge';
|
||||||
|
return (
|
||||||
|
<span className={cls} style={{ color: cfg.color, background: cfg.bg }}>
|
||||||
|
{status || '알 수 없음'}
|
||||||
|
</span>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
export default StatusBadge;
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 4: Wire Subscription.jsx** — StatusBadge 정의 삭제 + import 추가:
|
||||||
|
```js
|
||||||
|
import StatusBadge from './components/StatusBadge';
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 5: Run tests + build**
|
||||||
|
|
||||||
|
Run: `npm run test:run -- src/pages/subscription/components/StatusBadge.test.jsx` → PASS.
|
||||||
|
Run: `npm run test:run` → green. `npm run build` → `✓ built`.
|
||||||
|
|
||||||
|
- [ ] **Step 6: Commit**
|
||||||
|
```bash
|
||||||
|
git add src/pages/subscription/components/StatusBadge.jsx src/pages/subscription/components/StatusBadge.test.jsx src/pages/subscription/Subscription.jsx
|
||||||
|
git commit -m "refactor(subscription): StatusBadge 컴포넌트 추출 + 스모크"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 3: 표현 컴포넌트 추출 (AnnouncementCard / AnnouncementDetail / CalendarView)
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `src/pages/subscription/components/AnnouncementCard.jsx`
|
||||||
|
- Create: `src/pages/subscription/components/AnnouncementDetail.jsx`
|
||||||
|
- Create: `src/pages/subscription/components/CalendarView.jsx`
|
||||||
|
- Modify: `src/pages/subscription/Subscription.jsx`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes (Task 1/2): utils 헬퍼, `StatusBadge`.
|
||||||
|
- Produces: 각 기본 export — `AnnouncementCard({item,isSelected,onClick,onBookmark})`, `AnnouncementDetail({item,onBookmark})`, `CalendarView({items,onDaySelect})`.
|
||||||
|
|
||||||
|
- [ ] **Step 1: Create the three components (본문은 현 Subscription.jsx 정의 verbatim, 상단 import만 추가)**
|
||||||
|
|
||||||
|
`AnnouncementCard.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React from 'react';
|
||||||
|
import { STATUS_CONFIG, HOUSE_TYPE_LABELS, extractTier, fmt, getDDays, getDDayColor, fmtPrice } from '../subscriptionUtils';
|
||||||
|
import StatusBadge from './StatusBadge';
|
||||||
|
```
|
||||||
|
이어서 현 `Subscription.jsx`의 `function AnnouncementCard(...) { ... }` 본문을 그대로 붙이고 파일 끝에 `export default AnnouncementCard;`.
|
||||||
|
|
||||||
|
`AnnouncementDetail.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React, { useState } from 'react';
|
||||||
|
import { HOUSE_TYPE_LABELS, fmt, fmtFull, getDDays, getDDayColor, fmtPrice } from '../subscriptionUtils';
|
||||||
|
import StatusBadge from './StatusBadge';
|
||||||
|
```
|
||||||
|
이어서 현 `AnnouncementDetail(...)` 본문 verbatim + `export default AnnouncementDetail;`. (내부 `useState`(detailTab) 사용하므로 useState import 포함.)
|
||||||
|
|
||||||
|
`CalendarView.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React, { useState, useMemo } from 'react';
|
||||||
|
import { STATUS_CONFIG } from '../subscriptionUtils';
|
||||||
|
```
|
||||||
|
이어서 현 `CalendarView(...)` 본문 verbatim + `export default CalendarView;`. (내부 `useState`/`useMemo` 사용.)
|
||||||
|
|
||||||
|
> 각 컴포넌트가 실제로 참조하는 심볼만 import에 포함되어야 함(빌드가 미사용/누락을 검출). 위 목록은 현 코드 사용 기준.
|
||||||
|
|
||||||
|
- [ ] **Step 2: Wire Subscription.jsx** — 세 컴포넌트 정의 삭제 + import 추가:
|
||||||
|
```js
|
||||||
|
import AnnouncementCard from './components/AnnouncementCard';
|
||||||
|
import AnnouncementDetail from './components/AnnouncementDetail';
|
||||||
|
import CalendarView from './components/CalendarView';
|
||||||
|
```
|
||||||
|
(AnnouncementsTab이 아직 Subscription.jsx 내부에 있으므로 import한 세 컴포넌트를 그대로 사용.)
|
||||||
|
|
||||||
|
- [ ] **Step 3: Run tests + build**
|
||||||
|
|
||||||
|
Run: `npm run test:run` → 전체 green(회귀 0). Run: `npm run build` → `✓ built`. Run: `npm run lint` → 신규 3파일 0 에러.
|
||||||
|
|
||||||
|
- [ ] **Step 4: Commit**
|
||||||
|
```bash
|
||||||
|
git add src/pages/subscription/components/AnnouncementCard.jsx src/pages/subscription/components/AnnouncementDetail.jsx src/pages/subscription/components/CalendarView.jsx src/pages/subscription/Subscription.jsx
|
||||||
|
git commit -m "refactor(subscription): 공고 카드/상세/캘린더 컴포넌트 추출"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 4: 4개 탭 컴포넌트 추출 → Subscription을 shell로 축소
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `src/pages/subscription/components/DashboardTab.jsx`
|
||||||
|
- Create: `src/pages/subscription/components/AnnouncementsTab.jsx`
|
||||||
|
- Create: `src/pages/subscription/components/MatchesTab.jsx`
|
||||||
|
- Create: `src/pages/subscription/components/ProfileTab.jsx`
|
||||||
|
- Modify: `src/pages/subscription/Subscription.jsx` (shell로 축소)
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: utils 헬퍼, StatusBadge, AnnouncementCard/AnnouncementDetail/CalendarView, 기존 `DistrictTierEditor`/`NotificationSettings`.
|
||||||
|
- Produces: 각 기본 export (자립형, props 없음).
|
||||||
|
|
||||||
|
- [ ] **Step 1: Create the four tab components (본문 verbatim + 상단 import)**
|
||||||
|
|
||||||
|
`DashboardTab.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React, { useState, useEffect } from 'react';
|
||||||
|
import { apiGet, apiPost } from '../../../api';
|
||||||
|
import { fmtFull, fmtDateTime, fmtPrice, getDDays, getDDayColor } from '../subscriptionUtils';
|
||||||
|
import StatusBadge from './StatusBadge';
|
||||||
|
```
|
||||||
|
현 `DashboardTab()` 본문 verbatim + `export default DashboardTab;`.
|
||||||
|
|
||||||
|
`AnnouncementsTab.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React, { useState, useEffect } from 'react';
|
||||||
|
import { apiGet, apiDelete } from '../../../api';
|
||||||
|
import { STATUS_FILTERS, apiPatch } from '../subscriptionUtils';
|
||||||
|
import AnnouncementCard from './AnnouncementCard';
|
||||||
|
import AnnouncementDetail from './AnnouncementDetail';
|
||||||
|
import CalendarView from './CalendarView';
|
||||||
|
```
|
||||||
|
현 `AnnouncementsTab()` 본문 verbatim + `export default AnnouncementsTab;`.
|
||||||
|
|
||||||
|
`MatchesTab.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React, { useState, useEffect } from 'react';
|
||||||
|
import { apiGet, apiPost } from '../../../api';
|
||||||
|
import { extractTier, fmt, getDDays, getDDayColor, apiPatch } from '../subscriptionUtils';
|
||||||
|
import StatusBadge from './StatusBadge';
|
||||||
|
```
|
||||||
|
현 `MatchesTab()` 본문 verbatim + `export default MatchesTab;`.
|
||||||
|
|
||||||
|
`ProfileTab.jsx` — 상단:
|
||||||
|
```jsx
|
||||||
|
import React, { useState, useEffect } from 'react';
|
||||||
|
import { apiGet, apiPut } from '../../../api';
|
||||||
|
import { DEFAULT_PROFILE } from '../subscriptionUtils';
|
||||||
|
import DistrictTierEditor from './DistrictTierEditor';
|
||||||
|
import NotificationSettings from './NotificationSettings';
|
||||||
|
```
|
||||||
|
현 `ProfileTab()` 본문 verbatim + `export default ProfileTab;`.
|
||||||
|
|
||||||
|
> import 심볼은 각 탭이 실제 사용하는 것 기준(위 목록). 빌드가 누락/미사용 검출.
|
||||||
|
|
||||||
|
- [ ] **Step 2: Reduce Subscription.jsx to the shell** — 4개 탭 정의 삭제. 파일을 아래로 정리(현 shell 본문 verbatim 유지, import만 재구성):
|
||||||
|
|
||||||
|
```jsx
|
||||||
|
import React, { useState, useCallback } from 'react';
|
||||||
|
import { Link } from 'react-router-dom';
|
||||||
|
import PullToRefresh from '../../components/PullToRefresh';
|
||||||
|
import FAB from '../../components/FAB';
|
||||||
|
import { TABS } from './subscriptionUtils';
|
||||||
|
import DashboardTab from './components/DashboardTab';
|
||||||
|
import AnnouncementsTab from './components/AnnouncementsTab';
|
||||||
|
import MatchesTab from './components/MatchesTab';
|
||||||
|
import ProfileTab from './components/ProfileTab';
|
||||||
|
import './Subscription.css';
|
||||||
|
|
||||||
|
// ── Subscription (Main) ──
|
||||||
|
function Subscription() {
|
||||||
|
const [activeTab, setActiveTab] = useState(0);
|
||||||
|
const [refreshKey, setRefreshKey] = useState(0);
|
||||||
|
|
||||||
|
const handleRefresh = useCallback(async () => {
|
||||||
|
setRefreshKey(k => k + 1);
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
const handleFABClick = useCallback(() => {
|
||||||
|
setActiveTab(1);
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<PullToRefresh onRefresh={handleRefresh}>
|
||||||
|
<div className="sub">
|
||||||
|
<div style={{ display: 'flex', justifyContent: 'flex-end', marginBottom: 8 }}>
|
||||||
|
<Link to="/realestate/listings" style={{ fontSize: 12, color: '#f43f5e', textDecoration: 'none' }}>
|
||||||
|
실매물 · 안전마진 →
|
||||||
|
</Link>
|
||||||
|
</div>
|
||||||
|
<div className="sub-header">
|
||||||
|
<div>
|
||||||
|
<p className="sub-kicker">Real Estate</p>
|
||||||
|
<h1>청약 관리</h1>
|
||||||
|
<p className="sub-desc">
|
||||||
|
공공데이터 기반 청약 공고 자동 수집, 내 조건 매칭, 일정 관리를 한곳에서.
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div className="sub-tabs-bar">
|
||||||
|
<div className="sub-tabs">
|
||||||
|
{TABS.map((tab, i) => (
|
||||||
|
<button
|
||||||
|
key={tab}
|
||||||
|
className={`sub-tab${activeTab === i ? ' is-active' : ''}`}
|
||||||
|
onClick={() => setActiveTab(i)}
|
||||||
|
>
|
||||||
|
{tab}
|
||||||
|
</button>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div className="sub-body">
|
||||||
|
{activeTab === 0 && <DashboardTab key={`dash-${refreshKey}`} />}
|
||||||
|
{activeTab === 1 && <AnnouncementsTab key={`ann-${refreshKey}`} />}
|
||||||
|
{activeTab === 2 && <MatchesTab key={`match-${refreshKey}`} />}
|
||||||
|
{activeTab === 3 && <ProfileTab key={`prof-${refreshKey}`} />}
|
||||||
|
</div>
|
||||||
|
<FAB onClick={handleFABClick} label="공고 목록" />
|
||||||
|
</div>
|
||||||
|
</PullToRefresh>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
export default Subscription;
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 3: Run full suite + lint + build**
|
||||||
|
|
||||||
|
Run: `npm run test:run` → 전체 green(회귀 0). Run: `npm run lint` → 신규 파일 0 에러. Run: `npm run build` → `✓ built`. `Subscription.jsx`가 ~70줄 shell로 축소됐는지 확인(`wc -l`).
|
||||||
|
|
||||||
|
- [ ] **Step 4: Commit**
|
||||||
|
```bash
|
||||||
|
git add src/pages/subscription/components/DashboardTab.jsx src/pages/subscription/components/AnnouncementsTab.jsx src/pages/subscription/components/MatchesTab.jsx src/pages/subscription/components/ProfileTab.jsx src/pages/subscription/Subscription.jsx
|
||||||
|
git commit -m "refactor(subscription): 4개 탭 컴포넌트 추출 → Subscription을 shell로 축소"
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 5: Manual verification (dev server)**
|
||||||
|
|
||||||
|
`npm run dev` → `http://localhost:3007/realestate` 접속. 4탭(대시보드/공고 목록/매칭 결과/내 프로필) 전환, 공고 카드 선택→상세, 캘린더 뷰, 즐겨찾기 토글, 프로필 저장이 리팩토링 전과 **동일 동작**인지 확인. 실매물 교차링크 동작 확인.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 5: Part A — 기능 모듈 구조 컨벤션 문서화 (CLAUDE.md + README)
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `CLAUDE.md` (web-ui 루트)
|
||||||
|
- Modify: `README.md`
|
||||||
|
|
||||||
|
- [ ] **Step 1: web-ui/CLAUDE.md — "기능 모듈 구조" 섹션 추가** (문서 상단 "주요 파일 위치" 또는 페이지 구조 근처):
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## 기능 모듈 구조 (컨벤션)
|
||||||
|
|
||||||
|
대형 기능 페이지는 단일 파일이 아니라 아래 모듈 구조로 분해한다 (레퍼런스: `src/pages/listings/`, `src/pages/subscription/`).
|
||||||
|
|
||||||
|
```
|
||||||
|
src/pages/<feature>/
|
||||||
|
├── <Feature>.jsx # 페이지 shell — 라우팅 진입, 탭바/헤더/레이아웃, 하위 조합만
|
||||||
|
├── <Feature>.css # 스타일 (shell에서 1회 import)
|
||||||
|
├── components/ # 표현 단위(카드/탭/상세/리스트) 각 단일 책임
|
||||||
|
├── hooks/ # 상태·API·부수효과 훅 (선택)
|
||||||
|
└── <feature>Utils.js # 순수 헬퍼(포맷/매핑/계산) + <feature>Utils.test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
규칙: 파일당 단일 책임·권장 ≤300줄; 순수 로직은 `*Utils.js`로 추출 + 유닛 테스트; shell은 데이터 페칭/비즈니스 로직을 직접 갖지 않고 조합만; 컴포넌트는 props/훅 인터페이스로만 통신.
|
||||||
|
```
|
||||||
|
그리고 페이지 구조 표의 `/realestate` 행 설명에 "(모듈 분해: shell + components/8 + subscriptionUtils)" 취지 반영.
|
||||||
|
|
||||||
|
- [ ] **Step 2: README.md — 컨벤션 문단 추가** (프로젝트 통계/구조 근처):
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
### 기능 모듈 구조
|
||||||
|
|
||||||
|
대형 기능 페이지는 `src/pages/<feature>/` 아래 **shell(`<Feature>.jsx`) + `components/` + `hooks/` + `<feature>Utils.js`(+테스트)** 로 책임을 분해합니다. 파일당 단일 책임·권장 ≤300줄, 순수 로직은 유틸로 뽑아 유닛 테스트합니다. (레퍼런스: `listings`, `subscription`)
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 3: Commit**
|
||||||
|
```bash
|
||||||
|
git add CLAUDE.md README.md
|
||||||
|
git commit -m "docs: 기능 모듈 구조 컨벤션 하네스(CLAUDE.md)·README 기록"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Self-Review 결과
|
||||||
|
|
||||||
|
**Spec coverage** (설계 §1–§7):
|
||||||
|
- Part A 컨벤션+문서 → Task 5 ✅
|
||||||
|
- Part B file map(utils/StatusBadge/카드3/탭4/shell) → Task 1/2/3/4 ✅
|
||||||
|
- §3 subscriptionUtils 이동 항목 → Task 1 ✅ (local apiPatch 이동 포함)
|
||||||
|
- §4 테스트(utils 유닛 + StatusBadge 스모크 + build/lint/수동) → Task 1/2 + 각 Task build/lint + Task 4 수동 ✅
|
||||||
|
- §6 완료기준 → 각 Task 검증 + Task 5 ✅
|
||||||
|
|
||||||
|
**Placeholder scan:** 신규 코드(utils/StatusBadge/테스트/shell/docs)는 전체 코드 명시. 대형 컴포넌트는 "현 정의 verbatim 이동 + 명시된 import"로 지정(플레이스홀더 아님 — 옮길 원본이 파일에 존재, import 심볼 목록 명시). ✅
|
||||||
|
|
||||||
|
**Type consistency:** utils export 심볼(Task1) ↔ Task2/3/4 import 일치. 컴포넌트 기본 export ↔ shell import 일치. api 경로(shell `../../api`, components `../../../api`, utils `../subscriptionUtils`) 일치. ✅
|
||||||
|
|
||||||
|
**참고:** 각 Task는 이전 Task 산출물(utils→StatusBadge→카드→탭→shell)에 순차 의존. 순서 준수 필수. 리팩토링이라 RED는 "신규 파일 미존재(import 실패)"로 성립, GREEN은 추출 후 통과 + 전체 회귀 0.
|
||||||
@@ -0,0 +1,125 @@
|
|||||||
|
# FE 기능 모듈 구조 컨벤션 + Subscription 분해 리팩토링 — 설계
|
||||||
|
|
||||||
|
- **작성일**: 2026-07-09
|
||||||
|
- **역할/저장소**: FE (`web-ui`)
|
||||||
|
- **범위**: FE 대형 컴포넌트 책임 분해 리팩토링의 **1번째 서브프로젝트**. (전체 분해: Subscription→RealEstate→PortfolioTab→InstaCards→MusicStudio 순차, 각 별도 spec/plan.)
|
||||||
|
- **성격**: **behavior-preserving(동작 보존) 순수 추출**. 로직 재작성 금지, UI/동작 변경 없음.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 배경 & 목표
|
||||||
|
|
||||||
|
기능이 늘며 일부 페이지 컴포넌트가 단일 파일에 과도한 책임을 담게 됨(예: `Subscription.jsx` 1647줄에 4탭+카드+상세+캘린더+헬퍼 전부). 하네스 엔지니어링 원칙(단일 책임·명확한 경계·CLAUDE.md 계층 문서화)에 맞춰 **기능 모듈 구조**로 분해하고, 그 컨벤션을 하네스(web-ui/CLAUDE.md)와 README에 기록한다.
|
||||||
|
|
||||||
|
이 스펙은 두 부분:
|
||||||
|
- **Part A (공통 컨벤션 + 문서화)**: "기능 모듈 구조" 표준 정의 → 이후 모든 서브프로젝트가 참조. web-ui/CLAUDE.md + README 기록.
|
||||||
|
- **Part B (Subscription 분해)**: 컨벤션을 `Subscription.jsx`에 첫 적용.
|
||||||
|
|
||||||
|
비목표: 동작/스타일 변경, 신규 기능, api.js 중복(local apiPatch) 정리 외 무관 리팩토링.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Part A — 기능 모듈 구조 컨벤션 (하네스 기록)
|
||||||
|
|
||||||
|
**표준 디렉토리 형태** (레퍼런스: `src/pages/listings/`):
|
||||||
|
```
|
||||||
|
src/pages/<feature>/
|
||||||
|
├── <Feature>.jsx # 페이지 shell — 라우팅 진입, 탭바/헤더/레이아웃, 하위 조합만
|
||||||
|
├── <Feature>.css # 스타일 (shell에서 1회 import → 전역 클래스 하위 공유)
|
||||||
|
├── components/ # 표현 단위 (카드/탭/상세/리스트…) 각 단일 책임
|
||||||
|
├── hooks/ # 상태·API·부수효과 훅 (선택)
|
||||||
|
└── <feature>Utils.js # 순수 헬퍼(포맷/매핑/계산) + <feature>Utils.test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
**규칙:**
|
||||||
|
- 파일당 **단일 책임**, 권장 상한 **~300줄**(초과 시 분할 신호).
|
||||||
|
- 순수 로직(포맷/매핑/계산)은 `*Utils.js`로 뽑고 **유닛 테스트 필수**.
|
||||||
|
- 상태+API가 얽힌 로직은 `hooks/` 또는 자립형 탭 컴포넌트로.
|
||||||
|
- shell은 "조합"만: 데이터 페칭·비즈니스 로직을 직접 갖지 않음.
|
||||||
|
- 컴포넌트는 서로 잘 정의된 props/훅 인터페이스로만 통신.
|
||||||
|
|
||||||
|
**문서화 대상:**
|
||||||
|
- `web-ui/CLAUDE.md`: "기능 모듈 구조" 섹션 신설(위 형태·규칙), 페이지 구조 표에 리팩토링 반영.
|
||||||
|
- `README.md`: 프로젝트 통계/구조 설명에 모듈 구조 컨벤션 1문단 추가.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Part B — Subscription.jsx 분해 (file map)
|
||||||
|
|
||||||
|
현 `src/pages/subscription/Subscription.jsx`(1647줄)를 아래로 분해. **코드 이동만**(내용 동일), import 배선만 추가.
|
||||||
|
|
||||||
|
```
|
||||||
|
src/pages/subscription/
|
||||||
|
├── Subscription.jsx # shell: PullToRefresh + 헤더 + 탭바 + FAB + activeTab/refreshKey. 4탭 조합. (~70줄)
|
||||||
|
├── Subscription.css # (변경 없음, shell에서 import 유지)
|
||||||
|
├── subscriptionUtils.js # 상수·순수헬퍼 이동
|
||||||
|
├── subscriptionUtils.test.js # 순수헬퍼 유닛 테스트 (신규)
|
||||||
|
└── components/
|
||||||
|
├── StatusBadge.jsx # (기존 컴포넌트 이동)
|
||||||
|
├── DashboardTab.jsx # 자립형(self-fetch)
|
||||||
|
├── AnnouncementCard.jsx
|
||||||
|
├── AnnouncementDetail.jsx # detailTab 상태 + 정보/일정/주택형/매칭분석
|
||||||
|
├── CalendarView.jsx
|
||||||
|
├── AnnouncementsTab.jsx # AnnouncementCard/AnnouncementDetail/CalendarView 조합
|
||||||
|
├── MatchesTab.jsx
|
||||||
|
├── ProfileTab.jsx # DistrictTierEditor/NotificationSettings(기존) 사용
|
||||||
|
├── DistrictTierEditor.jsx # (기존 유지)
|
||||||
|
└── NotificationSettings.jsx # (기존 유지)
|
||||||
|
```
|
||||||
|
|
||||||
|
**`subscriptionUtils.js`로 이동할 항목:**
|
||||||
|
- 상수: `STATUS_CONFIG`, `HOUSE_TYPE_LABELS`, `TABS`, `STATUS_FILTERS`, `DEFAULT_PROFILE`
|
||||||
|
- 순수 헬퍼: `extractTier`, `fmt`, `fmtFull`, `_diffDays`, `getDDays`, `getDDayColor`, `fmtDateTime`, `fmtPrice`
|
||||||
|
- `apiPatch`(현재 Subscription 로컬 정의) — 이동. (⚠️ `src/api.js`에 동일 기능 `apiPatch` 이미 존재 — 이번엔 **로컬 것을 utils로 그대로 이동**(동작 보존), api.js와의 dedupe는 후속 follow-up으로 기록.)
|
||||||
|
|
||||||
|
**의존 관계(이동 시 import 배선):**
|
||||||
|
- `DashboardTab` → apiGet/apiPost, STATUS_CONFIG, fmt류, getDDays/getDDayColor, fmtDateTime, fmtPrice, StatusBadge
|
||||||
|
- `AnnouncementCard`/`AnnouncementDetail` → STATUS_CONFIG, HOUSE_TYPE_LABELS, extractTier, fmt/fmtFull, getDDays/getDDayColor, fmtPrice, StatusBadge
|
||||||
|
- `AnnouncementsTab` → apiGet/apiDelete/apiPatch, STATUS_FILTERS, AnnouncementCard/AnnouncementDetail/CalendarView
|
||||||
|
- `MatchesTab` → apiGet/apiPost/apiPatch, extractTier, fmt/getDDays/getDDayColor, StatusBadge
|
||||||
|
- `ProfileTab` → apiGet/apiPut, DEFAULT_PROFILE, DistrictTierEditor/NotificationSettings
|
||||||
|
- `Subscription`(shell) → TABS, 4탭 컴포넌트, PullToRefresh/FAB/Link
|
||||||
|
|
||||||
|
**주의:** `/realestate/listings` 교차링크(현 shell의 Link)는 그대로 유지.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 테스트 (안전망 — 현재 Subscription은 테스트 0)
|
||||||
|
|
||||||
|
behavior-preserving라 기존 동작 유지가 핵심. 안전망:
|
||||||
|
1. **`subscriptionUtils.test.js` (신규, 필수)** — 순수 헬퍼 유닛:
|
||||||
|
- `extractTier`: "자치구 S티어: 강남구 (+25)" → "S"; 미매치 → null.
|
||||||
|
- `getDDays`/`getDDayColor`: D-day 경계(오늘=D-Day, 미래 D-N, 과거 D+N; 색 임계 0/3/7).
|
||||||
|
- `fmtPrice`(현 구현 동작 고정): 10000→"1억", 15000→"1.5억", 9999→"9,999만", null→null.
|
||||||
|
- `_diffDays`: 로컬 타임존 파싱 경계.
|
||||||
|
2. **`StatusBadge.test.jsx` (신규, 스모크)** — status→색/라벨, 미정의 status 폴백.
|
||||||
|
3. 각 탭 컴포넌트는 자립형(api 페치) → 이번 범위는 **스모크 최소화**(추출 검증은 build+lint+수동). 탭 스모크(vi.mock api)는 권장이나 필수 아님(후속).
|
||||||
|
|
||||||
|
**검증 게이트(품질 게이트):** `npm run test:run`(신규 유닛 포함 전체 green) + `npm run lint`(신규 파일 0 에러) + `npm run build`(성공) + 개발서버 `/realestate` 4탭 수동 확인(공고 목록/상세/캘린더/매칭/프로필 저장 동작 동일).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 컴포넌트 구조 (분해 후 검증 관점)
|
||||||
|
|
||||||
|
각 파일이 "무엇을 하는가 / 어떻게 쓰는가 / 무엇에 의존하는가"로 독립 이해 가능해야 함:
|
||||||
|
- `AnnouncementDetail`(현 272줄) → 여전히 큰 편이나 단일 책임(공고 상세). 내부 detailTab 3섹션은 한 컴포넌트 응집. 300줄 근처 → 필요 시 후속 분할 여지 기록.
|
||||||
|
- `ProfileTab`(현 390줄) → 폼이 커서 300줄 초과. 이번엔 파일 추출까지만, 폼 섹션(기본/자격/선호) 하위 분할은 후속 follow-up으로 기록(과분해 회피, YAGNI).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 완료 기준 (Acceptance)
|
||||||
|
|
||||||
|
- [ ] Part A: web-ui/CLAUDE.md "기능 모듈 구조" 섹션 + README 컨벤션 문단 기록.
|
||||||
|
- [ ] Part B: Subscription.jsx가 shell(~70줄) + components/8 + subscriptionUtils(+test)로 분해, 동작/스타일 불변.
|
||||||
|
- [ ] `subscriptionUtils.test.js`·`StatusBadge.test.jsx` 통과, 전체 `npm run test:run` green.
|
||||||
|
- [ ] `npm run lint`·`npm run build` 통과.
|
||||||
|
- [ ] `/realestate` 4탭 수동 검증 동일 동작.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 리스크 / 오픈 이슈
|
||||||
|
|
||||||
|
- **테스트 부재 컴포넌트의 리팩토링**: 순수 추출로 위험 최소화 + build/lint/유닛테스트/수동검증. 로직 한 줄도 바꾸지 않음.
|
||||||
|
- **거대 import 배선 실수 가능**: 추출 시 각 파일의 사용 심볼을 정확히 import해야 함(누락 시 build 실패로 즉시 검출).
|
||||||
|
- **후속 follow-up(문서화, 이번 미적용)**: ProfileTab 폼 섹션 분할; local apiPatch ↔ api.js apiPatch dedupe; AnnouncementDetail 추가 분할.
|
||||||
|
- **다음 서브프로젝트**: RealEstate(909)→PortfolioTab(671)→InstaCards(1013)→MusicStudio(1936), 각 동일 컨벤션 별도 spec/plan.
|
||||||
Reference in New Issue
Block a user