작업 이력 — 2026-05-28

요약

malgn-helper-pms(PMS 애드온) 정의 추가 → 4개 GitHub repo 연결 → Cloudflare Workers/Pages 보일러플레이트 셋업 → Pages 프로젝트 생성 → 다중 계정 대응(account_id 명시)까지 완료. 4개 워크스페이스가 모두 즉시 배포 가능한 상태.

작업 내역

1. `malgn-helper-pms` 정의 추가

CLAUDE.md: 프로젝트 구성 3개 → 4개로 확장. PMS 애드온 항목 추가
데이터 흐름 다이어그램에 PMS 상담사 화면 → malgn-helper-pms 진입 경로 추가
작업 규칙: malgn-helper-pms는 DB·LLM 직접 접근 금지, 반드시 malgn-helper-api 경유

2. GitHub 연결 (4개 repo)

각 디렉토리에 git init -b main + git remote add origin <URL>:

디렉토리	원격
`malgn-helper`	https://github.com/malgnsoft/malgn-helper.git
`malgn-helper-admin`	https://github.com/malgnsoft/malgn-helper-admin.git
`malgn-helper-api`	https://github.com/malgnsoft/malgn-helper-api.git
`malgn-helper-pms`	https://github.com/malgnsoft/malgn-helper-pms.git

3. 첫 커밋 + 푸시

malgn-helper: CLAUDE.md + README.md + .gitignore + doc/ (총 11 파일, 2344 줄)
나머지 3 repo: README.md + .gitignore

4. Cloudflare 보일러플레이트

Repo	스택	추가 파일
`malgn-helper`	Nuxt 3 / Pages	`package.json`, `nuxt.config.ts`, `app.vue`
`malgn-helper-admin`	Nuxt 3 / Pages	`package.json`, `nuxt.config.ts`, `app.vue`
`malgn-helper-api`	Hono / Workers	`package.json`, `wrangler.jsonc`, `src/index.ts`, `tsconfig.json`
`malgn-helper-pms`	Nuxt 3 / Pages	`package.json`, `nuxt.config.ts`, `app.vue`, `wrangler.toml` (재구성 — §9 참조)

pnpm install 4개 repo 모두 완료. README에 개발·배포 명령 추가.

5. Cloudflare Pages 프로젝트 생성

wrangler pages project create malgn-helper --production-branch main
wrangler pages project create malgn-helper-admin --production-branch main
계정: Info@malgnsoft.com (d2b8c5524b7259214fa302f1fecb4ad6)
배포 URL (첫 deploy 후 활성화):
- https://malgn-helper.pages.dev/
- https://malgn-helper-admin.pages.dev/

Workers 2개(-api, -pms)는 첫 wrangler deploy 시점에 자동 생성.

6. 다중 계정 대응 — `account_id` 명시

다중 계정 환경에서 매번 CLOUDFLARE_ACCOUNT_ID 환경변수를 지정해야 하던 문제 제거:

Workers (-api, -pms): wrangler.jsonc에 "account_id" 추가
Pages (helper, -admin): wrangler.toml 신규 (name + account_id + compatibility_date + pages_build_output_dir)
Pages 2개의 package.json deploy 스크립트 간소화 → nuxt build && wrangler pages deploy

커밋 요약

Repo	오늘 커밋 (시간순)
`malgn-helper`	`1e612b8` 초기 문서 → `d1c7b4a` Nuxt 보일러플레이트 → `065e6ff` Pages config
`malgn-helper-admin`	`d92f689` README → `9dfc2c5` Nuxt 보일러플레이트 → `5052765` Pages config
`malgn-helper-api`	`1416518` README → `f21e53c` Hono 보일러플레이트 → `8ea04c5` account_id
`malgn-helper-pms`	`1dd81d4` README → `5207784` Hono 보일러플레이트 → `4728faf` account_id

외부 리소스 변경

시스템	변경
GitHub	4개 repo에 main 브랜치 생성 + 초기 커밋 푸시
Cloudflare (Info@malgnsoft.com)	Pages 프로젝트 2개 생성 (`malgn-helper`, `malgn-helper-admin`)

다음 단계 후보

첫 Workers/Pages 배포 시도 — ./scripts/deploy.sh <repo> "<msg>"
WBS.md P1-1.4 Aurora MySQL + Hyperdrive 바인딩 — Aurora 프로비저닝 후 wrangler.jsonc에 HYPERDRIVE 바인딩 추가
P1-1.6 R2 버킷 생성 — wrangler r2 bucket create malgn-helper-files + 바인딩
P1-1.7 OpenSearch 도메인 프로비저닝
P1-1.8 AI Gateway 설정 + Anthropic API 키 secret 등록 (wrangler secret put ANTHROPIC_API_KEY)
doc/ROADMAP.md Phase 1 M1 인프라 Ready 게이트 점검

추가 작업 (이력 시스템·배포 자동화)

7. 일단위 작업 이력 도입

doc/history/history.20260528.md (본 파일) 신규 — 오늘 작업 6건 정리
메모리에 규칙 저장: doc/history/history.yyyyMMdd.md에 매일 누적 기록 (덮어쓰기 X)
CLAUDE.md 직접 변경은 없음. 메모리·MEMORY.md 인덱스 갱신

8. 배포 일괄 처리 스크립트

scripts/deploy.sh 신규 — 4단계 일괄 처리:
1. git commit -m <msg> (변경 없으면 skip)
2. git push
3. pnpm deploy (Workers/Pages 자동 분기 — wrangler.toml 존재 여부로)
4. doc/history/history.{yyyyMMdd}.md의 ## 배포 섹션에 항목 append
사용법: ./scripts/deploy.sh <repo> "<commit message>"
CLAUDE.md에 ## 배포 절차 섹션 추가 — 일괄 스크립트 사용법 + 수동 절차 + 규칙
배포 실패·secret 변경·account_id 규칙 모두 문서화

9. `malgn-helper-pms` 스택 전환 — Workers → Pages

사용자 결정 변경에 따라 PMS 애드온 스택을 Hono Workers에서 Nuxt 3 / Pages로 전환.

제거: src/index.ts, wrangler.jsonc, tsconfig.json (Hono Worker 보일러플레이트)
추가: nuxt.config.ts, app.vue, wrangler.toml (Pages config, account_id 포함)
package.json 의존성 교체: hono → nuxt. deploy 스크립트 wrangler pages deploy로 변경
README.md 스택 섹션 갱신 (Hono on Workers → Nuxt 3 / Pages, iframe·위젯 임베드 명시)
Cloudflare Pages 프로젝트 생성: wrangler pages project create malgn-helper-pms → https://malgn-helper-pms.pages.dev/
CLAUDE.md 데이터 흐름 다이어그램에서 pms 라벨을 (Nuxt 3 / Pages, PMS 임베드)로 명시
본 history 파일 §4 표의 pms 행 갱신 (Workers → Pages)

10. 첫 Cloudflare 배포 + 배포 환경 이슈 수정

4개 repo 전체를 Cloudflare에 최초 배포. 진행 중 세 가지 이슈 발견·수정.

발견된 이슈

#	증상	원인
1	`ERR_PNPM_CANNOT_DEPLOY A deploy is only possible from inside a workspace`	`pnpm deploy`는 pnpm 워크스페이스 예약어. 스크립트 호출은 `pnpm run deploy`여야 함
2	`Configuration file for Pages projects does not support "account_id"`	Pages용 `wrangler.toml`은 `account_id` 필드 미지원 (Workers만 지원)
3	Nuxt 빌드 산출물이 `dist/`인데 `wrangler.toml`은 `.output/public`로 설정	Nuxt 3 cloudflare-pages preset의 실제 출력은 `dist/`

수정 사항

scripts/deploy.sh: pnpm deploy → pnpm run deploy 로 변경. Pages용으로 CLOUDFLARE_ACCOUNT_ID env 변수 export 추가
malgn-helper / -admin / -pms의 wrangler.toml: account_id 제거 + pages_build_output_dir = "dist"
CLAUDE.md ## 배포 절차의 account_id 안내 갱신 (Workers와 Pages 차이, pnpm run deploy 명시, 출력 디렉토리 dist/ 명시)

배포 결과

Repo	Production URL	커밋
`malgn-helper-api`	https://malgn-helper-api.malgnsoft.workers.dev	`8ea04c5`
`malgn-helper-pms`	https://malgn-helper-pms.pages.dev/	`676724d`
`malgn-helper`	https://malgn-helper.pages.dev/	`cf1e931`
`malgn-helper-admin`	https://malgn-helper-admin.pages.dev/	`a613e64`

scripts/deploy.sh가 4건 모두 자동 처리 (commit-skip 또는 fix 커밋 → push → build·deploy → 이력 append).

11. 브리핑 카드 예시 저장

doc/examples/현대엔지비.md 신규 — # 현대엔지비 LMS 프로젝트 브리핑 카드 예시
같은 폴더의 안전보건진흥원.md는 풀 평가(케이스 스터디), 본 파일은 customer-briefing.md 프롬프트로 만든 짧은 카드

12. 현대엔지비 브리핑에서 비교 섹션 제거

사용자 피드백: 단일 고객사 브리핑에 다른 업체와의 비교는 불필요
삭제: §3 "안전보건진흥원과 비교" 표·관계 진단 단락 전체
본문 내 인라인 비교 언급 제거 (카드의 "안전보건진흥원 5h 대비 12배", §2의 "안전보건진흥원의 1인 단독과 정반대")
Cross-link의 "풀 평가 양식 예시: 안전보건진흥원.md"는 포맷 참조이므로 유지

13. malgn-helper-pms에 브리핑 카드 디자인 통합

design_handoff_briefing_card/ 핸드오프 패키지를 malgn-helper-pms에 통합.

복사한 파일 (source/ → repo root):

app.config.ts (ui.primary = sky, ui.gray = neutral)
types/briefing.ts · data/briefing.example.ts
composables/useBriefingClipboard.ts
components/BriefingCard.vue (메인 모달)
pages/projects/[id].vue (사용 예시)

환경 설정:

pnpm add @nuxt/ui (4.8.0 설치됨)
assets/css/fonts.css 신규 — Pretendard Variable CDN 임포트
nuxt.config.ts에 modules: ['@nuxt/ui'] + css: ['~/assets/css/fonts.css'] 추가
app.vue → 페이지 슬롯 (<NuxtPage />)로 변경
pages/index.vue 신규 — 예시 페이지 링크 안내 (/projects/1162 → 현대엔지비 데모)

검증: pnpm run build 성공. dist/ 산출 정상 (560 kB / 182 kB gzip).

핸드오프 시안의 "디자인 사양 100% 재현" 목표는 컴포넌트 자체에서 처리. 실제 API 연결(/api/projects/:id/briefing)은 추후 malgn-helper-api 엔드포인트 구현 시 연결.

14. malgn-helper-pms 예시 화면 구성

브리핑 카드를 실제 운영 맥락에서 보여주기 위한 데모 화면 두 개 추가.

/ (pages/index.vue) — 고객사 목록

PMS 배지·헤더·안내 문구
프로젝트 카드 1개(현대엔지비 LMS) — 클릭 시 /projects/1162로 이동
분류 규칙(@malgnsoft.com) 풋터 안내

/projects/1162 (pages/projects/[id].vue) — 상세 페이지

브레드크럼: 고객사 목록 → #1162
헤더: 활성 점·프로젝트명·부제·우상단 브리핑 카드 버튼
라벨 필터 chips (briefing.hotLabels 기반)
가짜 게시글 테이블 7건 — tb_post 스타일 (ID·라벨·제목·작성자·댓글·등록일·상태)
- 라벨/상태별 색상 ring (rose/amber/neutral/primary/emerald)
- 첫 행(post 92843)은 미응답으로 표시 — 브리핑 알림과 정합
푸터: 데모 데이터임 명시

검증: 빌드 성공 (576 kB / 186 kB gzip). 배포 후 https://malgn-helper-pms.pages.dev/ 에서 두 페이지 확인 가능.

실제 운영 시 pages/index.vue의 카드와 pages/projects/[id].vue의 게시글 테이블은 malgn-helper-api 엔드포인트 응답으로 채워질 예정.

15. `@nuxt/ui` v4 → v3 다운그레이드 (시안 호환성)

증상: 브리핑 카드 모달이 핸드오프 시안과 다르게 렌더링됨.

원인: 핸드오프 README는 @nuxt/ui v2 또는 v3 기준으로 작성됐고, source/components/BriefingCard.vue도 v3 API에 맞춰져 있음. 그러나 pnpm add @nuxt/ui로 설치되는 latest는 v4.8.0으로 메이저 변경(컴포넌트 API·슬롯·prop 이름 등)이 있어 호환 문제가 발생.

조치:

pnpm remove @nuxt/ui → pnpm add @nuxt/ui@^3 (3.3.7 설치됨)
빌드 확인 후 재배포

결과: 모달이 핸드오프 시안 의도대로 렌더링되어야 함. 사용자 확인 필요.

Lesson: 외부 디자인 시스템·컴포넌트 패키지를 통합할 때 README가 명시한 버전 범위를 반드시 준수. latest로 설치하지 말 것.

16. Tailwind CSS v4 스캔 누락 수정

증상: 브리핑 카드 모달이 스타일 없이 plain HTML로 렌더링됨 (스크린샷 확인). v3 다운그레이드만으로 해결되지 않은 별도 이슈.

원인: @nuxt/ui v3은 Tailwind v4 기반인데, Tailwind v4는 CSS 파일이 위치한 디렉토리(assets/css/)부터만 스캔. 우리의 Vue 컴포넌트(components/, pages/)는 스캔 범위 밖이라 사용된 utility 클래스가 컴파일되지 않음.

조치:

assets/css/main.css 신규(기존 fonts.css 통합):

@import "tailwindcss";
@import "@nuxt/ui";
@source "../..";

@source "../.."로 프로젝트 전체를 Tailwind 스캔 범위에 포함
nuxt.config.ts에 @tailwindcss/vite 플러그인 명시 등록 (자동 등록이 안 됨)

검증: 빌드 후 entry-styles에 max-w-[960px], hover:bg-neutral-50, backdrop-blur 등 컴포넌트 사용 클래스 모두 포함됨.

Lesson: Tailwind v4는 CSS 파일 위치 기준으로 스캔. 프로젝트 구조에 따라 @source 디렉티브로 명시적 스캔 범위 지정이 필요.

17. 단일 Q&A 요약·평가 예시 추가

doc/examples/qa-94227-사용자매뉴얼.md 신규 — post 94227 (에듀야 "사용자 매뉴얼" 문의) 케이스
5축 평가: 답변 정확성·완결성 / 응대 시간·턴 효율성 / 톤·친절도 / 표준답변화 가능성 / 챗봇 자동화 적합성·가시성
종합 ★ 4.5/5 — 답변 내용은 1순위 표준답변 후보지만 비공개 처리라 챗봇용 공개판 별도 작성 필요
표준답변 템플릿(공개판) 초안 포함 + 후속 조치 5건
안전보건진흥원·현대엔지비 예시와 함께 examples/에 누적 — 풀 평가/브리핑/Q&A 세 양식 비교 가능

18. Q&A 평가 프롬프트 정의

doc/prompts/qa-evaluation.md 신규 — 단일 Q&A에 대한 요약·평가 보고서를 AI에게 생성시키는 재사용 프롬프트
입력 변수: POST_ID, EVAL_DATE (선택: COMMENT_ID)
데이터 수집 쿼리 4개: 게시글 메타·본문 / 댓글 시간순 / 타이밍(FRT·첫 직원 응답·TTR) / 첨부
5축 평가 프레임(정확성·시간·톤·표준답변화·챗봇 적합성) + 측정 항목 표
출력 양식·작성 규칙·품질 체크리스트 명문화
산출물 저장 경로 표준화: doc/examples/qa-{POST_ID}-{슬러그}.md
이로써 prompts/는 3종 완성 — cs-evaluation.md(프로젝트 풀평가) / customer-briefing.md(프로젝트 브리핑) / qa-evaluation.md(단일 Q&A)

19. malgn-helper-pms에 Q&A 평가 카드 통합

design_handoff_qa_eval_card/ 핸드오프 패키지를 malgn-helper-pms에 통합. 브리핑 카드 통합과 동일한 패턴.

복사한 파일 (source/ → repo):

types/qa-eval.ts · data/qa-eval.example.ts (post #94227 데이터 내장)
composables/useQaEvalClipboard.ts
components/QaEvalCard.vue (메인 모달) + components/qa/QaAxisCard.vue + components/qa/QaScoreSummary.vue
pages/posts/[id]/eval.vue (사용 예시)

적용한 패턴 수정 (브리핑 카드에서 학습한 lesson 재적용):

QaEvalCard.vue의 <UModal> → Teleport + 자체 백드랍 으로 교체 (Nuxt UI v3 UModal 슬롯 호환 X)
ESC·백드랍 클릭 닫기, body 스크롤 잠금, fade Transition 동일 적용
pages/posts/[id]/eval.vue: 모달 자동 오픈 + 닫힘 시 window.close() + parent postMessage({type:'malgn-helper:qa-eval:close'})