sdrplk/finance-audit

Finance Audit — Personal CFO 보고서

원시 명세서 파일 폴더를 Personal CFO 보고서로 변환합니다: 검증된 데이터와 함께 *무슨 일이 일어났는가? 왜? 다음에 무엇을 해야 하는가?*에 답하는 서술 레이어를 제공합니다.

정확성 우선: 금액은 그대로 읽히고 실행 잔액과 대조됩니다 — 어떤 것도 조작되지 않습니다.

은행 종속 없음. 거래 목록이 주어지면 모든 은행 또는 계좌 내보내기와 호환됩니다. 컬럼, 헤더 행 및 날짜 순서(DMY/MDY/YMD)는 파일별로 자동 감지됩니다; 거래처/상대방 정리기는 결제 수단(UPI, POS, ACH, SEPA, 카드, 송금 등)에 구애받지 않습니다. 특정 은행에 하드코딩되지 않았습니다 — 자동 감지된 매핑을 확인하고 카테고리 키워드를 조정하면 됩니다.

파이프라인 (5단계)

수집  ->  구문 분석  ->  분류 (>=99%까지 반복)  ->  분석  ->  보고 (서빙 + 핫 리로드)

스크립트는 이 스킬에 있습니다. 사용자의 감사 폴더(명세서 파일이 있는 폴더)에서 실행하세요. 먼저 두 변수를 설정합니다:

SKILL="<이 스킬 디렉토리의 절대 경로>"   # 이 SKILL.md가 포함된 폴더
ROOT="<감사 폴더의 절대 경로>"        # 명세서 파일이 있는 위치

프라이버시 — 실제 데이터를 절대 커밋하지 마세요

모든 명세서 파일, 잔액, 내역 및 생성된 출력물은 ROOT/ 내에 로컬로 유지됩니다. 스킬 저장소는 템플릿, 예제 설정 및 더미 픽스처(assets/fixtures/sample_analysis.json)만 제공합니다.

Git 무시 (절대 푸시 금지): output/ (report.html, analysis.json, audit.db 포함), 명세서 파일, 및 실시간 config/mapping.json / 오버라이드.

config/mapping.json의 선택적 레이블: 사이드바 푸터용 account_label 또는 account_last4 (기본값은 "Primary account"). config/business.json의 비즈니스 표시 이름 → display_name (기본값은 "Business").

명세서 파일이 이미 ROOT에 다운로드되어 있다고 가정합니다 (PDF / XLSX / XLS / CSV / TXT).

런타임을 선택하세요 (사용자는 Node.js를 선호합니다):

• Node 사용: node를 사용할 수 있고 입력에 PDF가 없는 경우.
• Python 사용: 입력에 PDF가 있거나 (Node 경로는 PDF를 구문 분석할 수 없음) node를 사용할 수 없는 경우.

의존성을 감지하고 설치합니다:

# Node 경로 (선호)
command -v node && node --version            # Node >= 22 필요 (내장 sqlite)
( cd "$ROOT" && npm install xlsx )           # .xls/.xlsx에만 해당; CSV/TXT는 필요 없음

# Python 경로 (대체 / PDF에 필요)
python3 --version
pip install openpyxl "xlrd==2.0.1" pdfplumber pandas  # + 분석 단계용 pandas

단계를 호출하는 방법을 정의합니다 ($STAGE = ingest|parse|categorize|analyze|report):

# Node:    node   "$SKILL/scripts/node/$STAGE.mjs" --root "$ROOT" [인자]
# Python:  python3 "$SKILL/scripts/python/$STAGE.py" --root "$ROOT" [인자]

1단계 — 수집 및 감지

node "$SKILL/scripts/node/ingest.mjs" --root "$ROOT"      # 또는 python3 .../ingest.py --root "$ROOT"

모든 파일을 미리 보고 자동 감지된 헤더 행, 컬럼 역할 및 명시적 date_format을 사용하여 config/mapping.json을 작성합니다. 미리 보기를 읽고 mapping.json을 확인하세요 — 은행마다 다릅니다. 항목에 _date_note가 있는 경우 날짜 순서가 모호합니다 (예: 03/04/2024); 사용자와 date_format을 확인하세요. 각 파일 항목에는 header_row, data_start_row, date_format (strptime 패턴: %d/%m/%Y 또는 auto), columns (역할 → 0 기반 인덱스), 및 amount_mode가 필요합니다:

• debit_credit — 별도의 출금 + 입금 컬럼 (가장 일반적)
• signed — 부호가 방향을 나타내는 하나의 amount 컬럼
• amount_type — amount 컬럼과 DR/CR을 보유한 type 컬럼

구문 분석 전에 잘못된 인덱스를 수정하세요.

2단계 — 구문 분석, 정규화, 중복 제거, 검증

node "$SKILL/scripts/node/parse.mjs" --root "$ROOT"       # 또는 .../parse.py

output/audit.db (SQLite)를 작성합니다. 차변/대변 분할은 부호 있는 금액에서 파생되므로 항상 잔액 체인과 일치합니다 (음수 출금으로 인코딩된 환불을 올바르게 처리). 무결성 검사가 통과해야 합니다 (또는 잔액 컬럼이 없으면 n/a). 실패하면:

• mapping.json의 컬럼 / data_start_row / date_format을 다시 확인하세요.
• 수집 stdout 미리 보기를 다시 읽고 (필요시 수집 재실행), 헤더/푸터 행을 포함하지 않았는지 확인하세요.
• 파일별 chain_issues > 0은 잘못 구문 분석된 정확한 행을 가리킵니다.

구문 분석이 조정될 때까지 분류로 진행하지 마세요.

3단계 — 분류 (값 기준 >= 99%까지 반복)

cp "$SKILL/config/categories.example.json" "$ROOT/config/categories.json"   # 첫 실행에만
# 비즈니스/프리랜서 계정의 경우:
cp "$SKILL/config/business.example.json"   "$ROOT/config/business.json"     # 그런 다음 편집
node "$SKILL/scripts/node/categorize.mjs" --root "$ROOT"   # 또는 .../categorize.py

규칙 우선순위: overrides.json > business.json > categories.json; 가장 높은 priority가 우선합니다. 분류는 스크립트 우선입니다; 다음과 같이 99%에 도달하세요:

1. 분류를 실행합니다. 커버리지 요약과 output/uncategorized.csv (값이 큰 순서로 그룹화된 거래처)를 읽습니다.
2. 내역에서 거래처의 정체가 명확한 경우, 직접 config/overrides.json에 규칙을 추가합니다 (아래 형식 참조) — 물어볼 필요가 없습니다.
3. 모호한 거래처 (누구인지, 또는 개인인지 비즈니스인지 불분명)의 경우, 사용자에게 간결한 질문을 한 다음 규칙을 추가합니다.
4. 분류를 다시 실행합니다. **값 커버리지 ≥ 99%**에 도달할 때까지 반복합니다.

config/overrides.json 형식:

{ "rules": [
  { "keywords": ["ACME", "ACME CORP"], "primary": "수입", "sub": "Acme 리테이너", "when": "credit" },
  { "keywords": ["BIGRENT"], "primary": "주거", "sub": "월세", "is_business": 0 }
] }

모든 거래가 primary_cat과 sub_cat을 가지도록 목표합니다. 사실상의 P2P-상대방 대체는 이체를 레이블링하지만 "검토 필요"로 계산됩니다 — 중요한 것들을 실제 규칙으로 변환하세요.

4단계 — 분석 (output/analysis.json 빌드)

python3 "$SKILL/scripts/python/analyze.py" --root "$ROOT"

output/audit.db에서 FY 슬라이스, 카테고리 보고서, CFO 서술, 수입 엔진, 지출 요약, 문제 영역 및 비즈니스 사후 분석을 계산합니다. output/analysis.json을 작성합니다 (선택적으로 findings.md를 로컬에 작성합니다 — 절대 커밋하지 마세요).

pandas가 필요합니다. config/business.json → display_name을 조정하여 비즈니스 섹션 레이블을 설정합니다 (기본값 "Business").

5단계 — 보고서 생성 (서빙 + 핫 리로드 + 자동 열기)

python3 "$SKILL/scripts/python/report.py" --root "$ROOT" --serve

analysis.json + 인라인으로 포함된 원장 행에서 **output/report.html**을 빌드합니다. --serve를 사용하면 http://127.0.0.1:8765/를 열고 db/config가 변경될 때 핫 리로드합니다 (분석 재실행 + 다시 렌더링). --refresh-analysis를 사용하면 일회성 빌드에서 강제로 재분석합니다.

보고서 UI (output/report.html) — Money.Audit 하이브리드 대시보드

쉘: 둥근 앱 프레임, FY 목록 + 섹션 탐색 (스크롤 스파이)이 있는 가벼운 사이드바, 전체 너비 메인 컬럼. 제목: 당신의 돈에 대해 중요한 것.

룩: Fraunces 세리프 + Spline Sans UI; 따뜻한 크림 쉘 (#f7f6f3), 골드 액센트. 일반적인 회색 SaaS가 아닙니다.

섹션 (사이드바): 스냅샷, 수입 엔진, 월별 지출, 문제 영역, 비즈니스 사후 분석, 현금 및 움직임, 행동 계획, 모든 카테고리, 원장 (검색 + 필터).

데이터 포함: const ANALYSIS = … 및 const LEDGER = … — 외부 가져오기 없음. 사이드바 푸터는 매핑의 account_label을 표시합니다 (템플릿에 계좌 번호를 하드코딩하지 마세요).

모션: emil-design-eng — :active scale(0.98), 막대 너비 전환, 축소 모션 안전. 스타일 가이드: references/ui_style_guide.md.

템플릿: assets/report_template.html. 문서용 더미 픽스처: assets/fixtures/sample_analysis.json.

보고서 UI를 변경할 때: 템플릿 + 스타일 가이드를 편집하고, 실제 output/report.html을 절대 커밋하지 마세요. 분석 → 보고를 통해 로컬에서 다시 생성하세요.

보고서 내용

1. 스냅샷 — 건강 점수, 메트릭, 세 가지 CFO 인용문.
2. 수입 / 지출 / 문제 — 카테고리로 드릴다운할 수 있는 결정 우선 섹션.
3. 비즈니스 검토 — config/business.json이 있을 때.
4. 원장 — 검색 가능한 거래 증거 (처음 350개 일치 표시).

플래그: --port N, --no-open, --refresh-analysis. --serve 없이 output/report.html을 한 번 작성합니다 (먼저 analysis.json이 없으면 분석 실행).

방법론: references/financial_frameworks.md.

참고: 하이브리드 Money.Audit UI는 Python 분석 + 보고 경로를 사용합니다. Node report.mjs는 기본 감사에 대해 레거시 CFO 템플릿을 계속 렌더링합니다.

감사 폴더에 생성된 레이아웃

ROOT/
├── <명세서 파일>              # 입력 (PDF/XLSX/XLS/CSV/TXT)
├── config/
│   ├── mapping.json          # 컬럼 매핑 (수집 후 확인)
│   ├── categories.json       # 카테고리 규칙 (예제에서)
│   ├── business.json         # 선택: 비즈니스 수입/급여/인프라
│   └── overrides.json        # 루프 중에 추가한 레이블
└── output/
    ├── audit.db              # SQLite 진실 공급원
    ├── analysis.json         # 분석 단계 (로컬 전용 — PII)
    ├── uncategorized.csv     # 검토 대기열 (분류 실행 시마다 재생성)
    └── report.html           # Money.Audit 대시보드 (로컬 전용 — PII)

스킬은 필요한 것만 작성합니다: 편집 가능한 설정, 각 단계 간 상태를 전달하는 SQLite db, 검토 대기열, 최종 보고서. 중간 덤프 (수집 미리 보기, 보고서 JSON)는 인쇄/포함되며, 추가 파일로 작성되지 않습니다. 각 단계가 별도의 프로세스로 실행되므로 mapping.json과 audit.db는 디스크에 유지되어야 합니다.

참고 사항

• 동일한 mapping.json / config / SQLite 스키마가 두 런타임에서 모두 작동합니다; 감사 중간에 런타임을 전환할 수 있습니다.
• 원시 명세서 파일을 버전 관리에서 제외하세요 (PII 포함).
• 전체 스키마, 검증 수학 및 설정 참조는 reference.md를 참조하세요.
• 분석 프레임워크 (저축률, 50/30/20, 벤치마크, 추천 로직)는 references/financial_frameworks.md를 참조하세요.

이 스킬이 처리하는 일반적인 요청

• "내 은행 명세서를 감사/분류하고 보고서를 만들어 줘" — 전체 파이프라인.
• "2024-25 회계연도에 대한 내 Personal CFO 보고서는 무엇인가요?" — 보고서 후 기간 선택기 사용.
• "내 저축률은 얼마이고 어떻게 개선할 수 있나요?" — 경영진 요약 + 행동 계획.
• "내가 어디에 과소비하고 있나요?" — 지출 인텔리전스 + 반사실 분석.
• "무엇을 중단/시작/계속해야 하나요?" — 행동 계획 섹션.
• "내 CFO에게 운영 자금/부채/투자에 대해 물어봐" — 에이전트와 함께 CFO에게 질문 프롬프트 사용.
• "보고서 UI 개선/전체 너비로 만들기/레이아웃 수정" — references/ui_style_guide.md에 따라 assets/report_template.html 편집; 분석 → 보고로 로컬에서 재생성. 절대 output/report.html을 커밋하지 마세요.