pws-user-manual

PWS MES 사용자 메뉴얼 작성

피플웍스(Peopleworks) Arizona 신공장 MES 사용자 메뉴얼을 기존 06.PWS__사용자메뉴얼_REPORT_V1.0.pptx와 동일한 표준 양식으로 작성·수정하기 위한 스킬이다. 메뉴 화면 캡처에 번호 콜아웃을 달고, 하단에 번호별 기능 설명을 적는 일관된 레이아웃을 따른다.

준비물

• 양식 파일: assets/PWS_사용자메뉴얼_양식_TEMPLATE.pptx (이 스킬 폴더 내)
  • 4개 표준 슬라이드 포함: ① 표지 ② 개정 이력 ③ 메뉴 설명 표준 양식 ④ 표 포함형 메뉴 설명
• PPTX 처리 도구: pptx 스킬의 스크립트 사용
  • 경로: C:\Users\MICUBE\.claude\skills\pptx\ (scripts/rearrange.py, scripts/inventory.py, scripts/replace.py, ooxml/scripts/unpack.py, ooxml/scripts/pack.py, ooxml/scripts/validate.py)
• 모든 파일은 UTF-8, 슬라이드 크기는 16:9 (13.33" × 7.5", 12192000 × 6858000 EMU)

문서 표준 (반드시 지킬 것)

슬라이드 1 — 표지

항목	값 예시
제목	Report 사용자 메뉴얼
부제	피플웍스 Arizona 신공장 MES 구축
문서번호	PWS_MES-User_Manual_<도메인>_V<버전> (예: ..._Report_V1.0)

슬라이드 2 — 개정 이력

표 컬럼: Ver | 날짜 | 항목 | 내용 | 작성자 | 검토자

• 최초 작성은 1.0 | YY.MM.DD | - | 제정 | MICUBE | 형식
• 날짜는 표지/이력은 YY.MM.DD, 메뉴 페이지는 YYYY-MM-DD

슬라이드 3+ — 메뉴 설명 표준 양식 (핵심, 레이아웃명 1_MICUBE_Body)

하나의 MES 화면 = 하나의 슬라이드. 구성:

┌──────────────────────────────────────────────────────────────┐
│ [경로]  …………………… [메뉴명]              [작성자]          │  ← 헤더
│ [한 줄 설명]                              [작성일]          │
│                                                                │
│        ┌──────── 화면 캡처(스크린샷) ────────┐  ①②③…       │  ← 본문(이미지+번호콜아웃)
│        │   동작 지점마다 ①②③… 번호 원 배치  │              │
│        └──────────────────────────────────────┘              │
│                                                                │
│ ┌─ 기능 설명 박스 ─┐   ① 버튼/기능 설명     ⑥ 버튼/기능 설명 │  ← 하단 설명 + 번호 범례(2열)
│ │ - 화면 개요       │   ② …                  ⑦ …            │
│ │ - 조회 안내       │   ③ …                  ⑧ …            │
│ │ - 기능 요약       │   ④ …                  ⑨ …            │
│ └──────────────────┘   ⑤ …                  ⑩ …            │
└──────────────────────────────────────────────────────────────┘

헤더 필드 위치 (inch 기준, slide 인벤토리 shape 번호 — 양식 파일 slide-2 기준)

필드	위치	shape	내용
메뉴 경로	(2.0, 0.4)	shape-0	기준정보 > 공정 형식 (대분류 > 메뉴)
한 줄 설명	(2.0, 0.7)	shape-1	화면의 목적 한 문장
메뉴명	(6.7, 0.4)	shape-2	화면 제목 (예: 라인 관리)
작성자	(11.2, 0.4)	shape-3	예: 김세훈
작성일	(11.2, 0.7)	shape-4	YYYY-MM-DD

하단 좌측 기능 설명 박스: shape-14 (0.4, 5.9) — 여러 줄. 보통 4줄 구성:

1. 화면 기능 개요 (예: 라인 정보를 조회 및 …를 등록, 수정 합니다.)
2. 공통 조회 안내 (조회버튼을 클릭하여 데이터를 확인합니다. (공장은 로그인 시 선택한 공장 고정입니다.)) 3~4. 조회/저장 등 세부 기능 요약

번호 범례 (하단 2열, 1~10): 좌열 15 / 우열 610

• 번호 원: shape-15(①)~ … 좌열 7.2", 우열 10.1"
• 설명 텍스트: 좌열 7.6", 우열 10.5" (예: 조회 조건 확인 버튼, 저장버튼( 수정한 정보를 저장))
• 번호 콜아웃 ↔ 범례 번호는 1:1로 일치시킨다. 스크린샷 위 번호 원과 하단 범례 번호가 같은 동작을 가리켜야 한다.

슬라이드 (표 포함형) — 양식 파일 slide 4

배치/인터페이스 등 표가 필요한 메뉴는 표준 양식 헤더는 동일하게 두고, 본문에 표(전송 항목 | 배치 Rule | 관련 쿼리 및 프로시저 | 설명 등)를 배치한다. 양식 파일 4번째 슬라이드를 복제해 사용.

작업 워크플로우

작업 시작 전 항상 pptx 스킬을 먼저 호출해 PPTX 처리 규칙을 로드한다.

A. 새 매뉴얼 문서 시작

1. 양식 파일을 작업 폴더로 복사 → 새 이름 (예: 06.PWS__사용자메뉴얼_<도메인>_V1.0.pptx)
2. 표지·개정이력 텍스트 수정 (아래 "텍스트 수정" 방식)
3. 메뉴 수만큼 메뉴 설명 슬라이드 복제 (아래 B)

B. 메뉴(화면) 페이지 추가/복제

양식 3번째 슬라이드(표준 양식, 0-index 2) 또는 4번째(표 포함형, index 3)를 복제한다.

# 예) 표준 양식 슬라이드(index 2)를 3번 복제해 4페이지 메뉴 문서 만들기
python <pptx스킬>/scripts/rearrange.py 양식.pptx 작업.pptx 0,1,2,2,2,3
#   index: 0=표지 1=개정이력 2=표준양식 3=표포함형 (같은 index 반복=복제)

복제 후 각 슬라이드의 텍스트를 수정(C)하고 스크린샷 이미지를 교체(D)한다.

C. 텍스트 수정 — 두 가지 방법

방법 1: replace.py (권장, 정형 치환)

python <pptx스킬>/scripts/inventory.py 작업.pptx inv.json   # shape 번호 확인
# inv.json을 보고 replacement.json 작성 (수정할 shape에만 paragraphs 지정)
python <pptx스킬>/scripts/replace.py 작업.pptx replacement.json 결과.pptx

• ⚠️ replace.py는 인벤토리의 모든 텍스트 shape를 비운 뒤 paragraphs를 지정한 shape에만 다시 채운다. 따라서 유지할 텍스트도 모두 replacement.json에 포함해야 한다. 한 슬라이드 일부만 바꿀 땐 방법 2가 안전하다.
• 헤더/범례 shape 매핑은 위 "헤더 필드 위치" 표 참조.

방법 2: unpack → XML 편집 → pack (부분 수정에 안전)

python <pptx스킬>/ooxml/scripts/unpack.py 작업.pptx unpacked
# unpacked/ppt/slides/slideN.xml 에서 <a:t>…</a:t> 텍스트만 교체 (Edit 도구)
python <pptx스킬>/ooxml/scripts/validate.py unpacked --original 작업.pptx   # 편집마다 검증
python <pptx스킬>/ooxml/scripts/pack.py unpacked 결과.pptx

• 한글은 XML에서 &#xxxxx; 숫자 엔티티로 저장돼 있을 수 있다. grep으로 위치를 찾기 어려우면 markitdown으로 먼저 슬라이드 텍스트를 확인하고, python -c로 엔티티를 디코드해 대상 문자열을 특정한다.

D. 스크린샷 이미지 교체

1. 화면 캡처 PNG를 준비한다.
2. unpack 후 unpacked/ppt/media/의 해당 imageN.png를 같은 파일명으로 덮어쓰기하면 위치·크기 유지된 채 교체된다.
   • 어떤 image가 어느 슬라이드인지: unpacked/ppt/slides/_rels/slideN.xml.rels에서 Target="../media/imageN.png" 확인.
3. 이미지 크기가 많이 다르면 슬라이드 XML의 <a:off>/<a:ext>로 위치·크기 조정.
4. 캡처 위 번호 콜아웃(번호 원)은 별도 도형이므로, 캡처 내 버튼 위치가 바뀌면 번호 원 <a:off> 좌표도 함께 옮긴다.

E. 검증 (필수)

python <pptx스킬>/ooxml/scripts/validate.py unpacked --original 원본.pptx   # 편집 시
python -m markitdown 결과.pptx | head -60                                  # 텍스트 육안 확인

LibreOffice가 있으면 soffice --headless --convert-to pdf 결과.pptx로 PDF 변환해 레이아웃을 눈으로 확인. 없으면 markitdown 텍스트 + shape 인벤토리로 검토.

컨벤션 체크리스트

• 문서번호 형식 PWS_MES-User_Manual_<도메인>_V<버전>
• 메뉴 경로 대분류 > 메뉴 형식 (예: 기준정보 > 공정, 생산관리 > 생산 현황, QMS > 품질 현황, 시스템관리 > 일반)
• 한 화면 = 한 슬라이드, 헤더 5필드(경로/설명/메뉴명/작성자/작성일) 모두 채움
• 스크린샷 번호 콜아웃과 하단 범례 번호 1:1 일치
• 공통 조회 안내 문구 포함 (조회버튼을 클릭하여 … 공장은 로그인 시 선택한 공장 고정입니다.)
• 개정 이력에 버전 행 추가
• UTF-8 인코딩 / 16:9 슬라이드 크기 유지
• 편집 후 validate.py 통과

참고

• 원본 문서: c:\Users\MICUBE\Downloads\06.PWS__사용자메뉴얼_REPORT_V1.0.pptx
• 양식 사본(사용자 보관용): c:\Users\MICUBE\Downloads\PWS_사용자메뉴얼_양식_TEMPLATE.pptx
• 도메인 예: Report(생산일보), 라인관리·시간가동률(생산관리), 수율/직행률/OEE(QMS), 배치/인터페이스(시스템관리)