feat(performance): 실적(쇼핑몰 통합 매출) 모듈 1단계 — 대시보드·설정·보안·어댑터 구조

- 네 영역 분리: ① 수집(adapters/ 쇼핑몰 10곳 + sync.py) ② 보안(security/ + credentials.py)
  ③ 계산·저장(calc.py + db.py) ④ 화면(dashboard.py, router.py, templates, performance.css/js)
- 대시보드: 기간(오늘/이번주/이번달/올해/직접선택, 이전·다음), 쇼핑몰 필터, KPI 5개(진행 중 기간은
  직전 기간 같은 경과일 대비), 일자×쇼핑몰 표(주간합계, 총매출/수수료/차감매출 전환), 일별 추이·
  쇼핑몰 비중(SVG), 월 누적(비중)·연간 누적, 금액 클릭 → 주문 상세
- 설정(관리자): 사용/매출 집계, 수수료율 이력(적용 시작일), 쇼핑몰별 API 인증정보 입력·연결 테스트·
  연결 상태, 마스터 키 상태·재암호화, 테스트(모의) 데이터 생성/삭제
- 인증정보: 설정 화면 입력 → AES-256-GCM(키 버전, AAD=쇼핑몰+항목) 암호화 저장, secret 원문은
  화면으로 다시 보내지 않음, 오류·로그·raw 는 비밀값 가린 뒤 저장. 마스터 키는 APP_ENCRYPTION_KEY(.env)
- 매출 기준일: 결제=결제일, 취소·반품=발생일. 금액 원 단위 정수, 수수료 반올림은 calc.commission 한 곳
- 동기화: 같은 쇼핑몰 동시 실행 차단(running 부분 유니크), 쇼핑몰별 실패 격리, 중복 방지 UNIQUE+UPSERT
- 카페24 어댑터는 기존 app/integrations/cafe24 OAuth 토큰 재사용, 나머지는 입력칸만(수집은 다음 단계)
- performance_db 초기화 스크립트, 권한키 performance(설정은 is_admin), 문서·.env.example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-29 16:07:46 +09:00
parent b95206dcf4
commit aa669553db
41 changed files with 4326 additions and 1 deletions
@@ -0,0 +1,7 @@
{# 실적 모듈 탭 — 설정 탭은 관리자에게만(서버도 관리자만 허용). #}
<nav class="perf-tabs" aria-label="실적 메뉴">
<a class="perf-tab{% if active_tab == 'dashboard' %} is-active{% endif %}" href="/performance/">실적</a>
{% if is_admin %}
<a class="perf-tab{% if active_tab == 'settings' %} is-active{% endif %}" href="/performance/settings">설정</a>
{% endif %}
</nav>
@@ -0,0 +1,238 @@
{% extends "erp_base.html" %}
{% block head_extra %}<link rel="stylesheet" href="/static/performance.css?v=20260929a" />{% endblock %}
{%- macro won(v) -%}
{%- if v is none -%}<span class="perf-na"></span>
{%- elif v == 0 -%}<span class="perf-zero">–</span>
{%- else -%}{{ "{:,}".format(v) }}{%- endif -%}
{%- endmacro -%}
{#- 한 칸에 총매출/수수료/차감매출 세 값을 넣고, 보기 전환은 CSS(data-metric)로. -#}
{%- macro m3(m) -%}
<span class="v v-gross">{{ won(m.gross) }}</span><span class="v v-commission">{{ won(m.commission) }}</span><span class="v v-net">{{ won(m.net) }}</span>
{%- endmacro -%}
{% block content %}
<section class="perf" id="perf-dash" data-metric="{{ metric }}">
{% include "performance/_tabs.html" %}
<!-- ── 기간 · 필터 · 업데이트 ── -->
<div class="perf-toolbar">
<div class="perf-quick" role="group" aria-label="기간 선택">
{% for q in nav.quick %}
<a class="perf-seg{% if q.active %} is-active{% endif %}" href="{{ q.url }}">{{ q.label }}</a>
{% endfor %}
<button type="button" class="perf-seg{% if period_kind == 'custom' %} is-active{% endif %}" id="perf-custom-btn">직접선택</button>
</div>
<div class="perf-nav">
<a class="perf-nav-btn" href="{{ nav.prev }}" title="{{ period.prev_label }}">‹ {{ period.prev_label }}</a>
<span class="perf-nav-label">{{ period.label }}</span>
<a class="perf-nav-btn" href="{{ nav.next }}" title="{{ period.next_label }}">{{ period.next_label }} ›</a>
</div>
<form class="perf-custom" id="perf-custom" method="get" action="/performance/"{% if period_kind != 'custom' %} hidden{% endif %}>
<input type="hidden" name="period" value="custom" />
<input class="erp-input perf-date" type="date" name="from" value="{{ period.start.isoformat() }}" required />
<span class="perf-muted">~</span>
<input class="erp-input perf-date" type="date" name="to" value="{{ period.end.isoformat() }}" required />
{% for c in codes %}{% if not selected_all %}<input type="hidden" name="m" value="{{ c }}" />{% endif %}{% endfor %}
<button class="erp-btn erp-btn-outline" type="submit">조회</button>
</form>
<details class="perf-filter" id="perf-filter">
<summary class="erp-btn erp-btn-outline">쇼핑몰: {% if selected_all %}전체{% else %}{{ codes | length }}곳{% endif %}</summary>
<form class="perf-filter-pop" method="get" action="/performance/">
<input type="hidden" name="period" value="{{ period_kind }}" />
{% if period_kind == 'custom' %}
<input type="hidden" name="from" value="{{ period.start.isoformat() }}" />
<input type="hidden" name="to" value="{{ period.end.isoformat() }}" />
{% else %}
<input type="hidden" name="d" value="{{ period.anchor.isoformat() }}" />
{% endif %}
{% for c in all_codes %}
<label class="perf-check"><input type="checkbox" name="m" value="{{ c }}"{% if c in codes %} checked{% endif %} /> {{ names[c] }}</label>
{% endfor %}
<div class="perf-filter-act">
<button type="button" class="erp-btn erp-btn-ghost" data-perf-check-all>전체</button>
<button type="submit" class="erp-btn erp-btn-primary">적용</button>
</div>
</form>
</details>
<div class="perf-update">
<span class="perf-muted" id="perf-last-update">마지막 업데이트
<b>{{ (last_update_at or '')[:16] | replace('T', ' ') or '—' }}</b></span>
<button type="button" class="erp-btn erp-btn-primary" id="perf-sync-btn"{% if running %} disabled{% endif %}>
{% if running %}업데이트 중…{% else %}매출 업데이트{% endif %}
</button>
</div>
</div>
{% if no_marketplaces %}
<div class="perf-notice">매출에 포함된 쇼핑몰이 없습니다. {% if is_admin %}<a href="/performance/settings">실적 설정</a>에서 쇼핑몰 사용을 켜세요.{% endif %}</div>
{% endif %}
{% if problems %}
<div class="perf-notice is-warn" id="perf-problems">
<b>연결 오류</b>
{% for p in problems %}<span class="perf-problem" title="{{ p.error }}">{{ p.name }} · {{ p.label }}</span>{% endfor %}
<span class="perf-muted">— 해당 쇼핑몰은 마지막 정상 수집분까지만 반영됩니다. 나머지는 정상입니다.</span>
</div>
{% endif %}
<div class="perf-notice" id="perf-sync-result" hidden></div>
<!-- ── KPI ── -->
<div class="perf-kpis">
{% for k in kpis %}
<div class="perf-kpi{% if k.primary %} is-primary{% endif %}">
<div class="perf-kpi-label">{{ k.label }}</div>
<div class="perf-kpi-value">₩{{ "{:,}".format(k.value) }}</div>
<div class="perf-kpi-delta">
{% if k.delta is none %}<span class="perf-muted">{{ k.cmp }} 비교 없음</span>
{% else %}
{% set up = k.delta > 0 %}
<span class="perf-delta {% if k.delta == 0 %}is-flat{% elif up != (k.invert or false) %}is-up{% else %}is-down{% endif %}">
{% if k.delta > 0 %}▲{% elif k.delta < 0 %}▼{% else %}–{% endif %} {{ "%.1f" | format(k.delta | abs) }}%</span>
<span class="perf-muted">{{ k.cmp }} 대비</span>
{% endif %}
</div>
</div>
{% endfor %}
</div>
<!-- ── 일자 × 쇼핑몰 ── -->
<div class="erp-card perf-card">
<div class="perf-card-head">
<h2 class="perf-h">{% if period_kind == 'year' %}월별 × 쇼핑몰{% else %}일자별 × 쇼핑몰{% endif %}</h2>
<div class="perf-metric" role="group" aria-label="표시 기준">
<button type="button" class="perf-seg" data-metric="gross">총매출</button>
<button type="button" class="perf-seg" data-metric="commission">수수료</button>
<button type="button" class="perf-seg" data-metric="net">수수료 차감 매출</button>
</div>
</div>
<div class="erp-table-wrap perf-table-wrap">
<table class="perf-table perf-main">
<thead>
<tr>
<th class="perf-th-label">{% if period_kind == 'year' %}월{% else %}날짜{% endif %}</th>
{% for c in codes %}<th title="{{ names[c] }}">{{ short_names[c] }}</th>{% endfor %}
<th class="perf-th-total">{% if period_kind == 'year' %}월 합계{% else %}일 합계{% endif %}</th>
</tr>
</thead>
<tbody>
{% for r in table %}
<tr class="perf-row-{{ r.kind }}{% if r.weekday == 5 %} is-sat{% endif %}{% if r.weekday == 6 or r.holiday %} is-sun{% endif %}{% if r.today %} is-today{% endif %}{% if r.future %} is-future{% endif %}">
<th class="perf-td-label" scope="row"{% if r.holiday %} title="{{ r.holiday }}"{% endif %}>
{{ r.label }}{% if r.holiday %}<small class="perf-hol">{{ r.holiday }}</small>{% endif %}
</th>
{% for c in codes %}
{% set m = r.cells[c] %}
<td class="perf-num{% if r['from'] and (m.gross or m.commission) %} is-link{% endif %}"
{% if r['from'] %}data-code="{{ c }}" data-from="{{ r['from'] }}" data-to="{{ r['to'] }}"{% endif %}>{{ m3(m) }}</td>
{% endfor %}
<td class="perf-num perf-td-total">{{ m3(r.total) }}</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
</div>
<!-- ── 그래프 ── -->
<div class="perf-grid2">
<div class="erp-card perf-card">
<div class="perf-card-head"><h2 class="perf-h">{% if period_kind == 'year' %}월별{% else %}일별{% endif %} 매출 추이</h2>
<span class="perf-muted perf-metric-name"></span></div>
<div class="perf-chart" id="perf-chart-daily"></div>
</div>
<div class="erp-card perf-card">
<div class="perf-card-head"><h2 class="perf-h">쇼핑몰별 비중</h2>
<span class="perf-muted">{{ period.label }}</span></div>
<div class="perf-chart" id="perf-chart-share"></div>
</div>
</div>
<!-- ── 월 누적 · 연간 누적 ── -->
<div class="perf-grid2">
<div class="erp-card perf-card">
<div class="perf-card-head"><h2 class="perf-h">{{ month.label }} 쇼핑몰별 누적 실적</h2></div>
<div class="erp-table-wrap">
<table class="perf-table">
<thead><tr><th class="perf-th-label">쇼핑몰</th><th>총매출</th><th>수수료</th><th>수수료 차감 매출</th><th>매출 비중</th></tr></thead>
<tbody>
{% for r in month.rows %}
<tr>
<th class="perf-td-label" scope="row">{{ names[r.code] }}</th>
<td class="perf-num">{{ won(r.gross) }}</td>
<td class="perf-num">{{ won(r.commission) }}</td>
<td class="perf-num">{{ won(r.net) }}</td>
<td class="perf-num perf-share">
{% if r.share is not none %}<span class="perf-bar" style="--w: {{ [r.share, 0] | max }}%"></span>{{ "%.1f" | format(r.share) }}%{% else %}<span class="perf-zero">–</span>{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
<tfoot>
<tr class="perf-row-total">
<th class="perf-td-label" scope="row">합계</th>
<td class="perf-num">{{ won(month.total.gross) }}</td>
<td class="perf-num">{{ won(month.total.commission) }}</td>
<td class="perf-num">{{ won(month.total.net) }}</td>
<td class="perf-num">{% if month.total.share is not none %}100%{% else %}<span class="perf-zero">–</span>{% endif %}</td>
</tr>
</tfoot>
</table>
</div>
</div>
<div class="erp-card perf-card">
<div class="perf-card-head"><h2 class="perf-h">{{ year.year }}년 누적</h2></div>
<div class="perf-year-sum">
<div><span>총매출</span><b>₩{{ "{:,}".format(year.total.gross) }}</b></div>
<div><span>수수료</span><b>₩{{ "{:,}".format(year.total.commission) }}</b></div>
<div><span>수수료 차감 매출</span><b>₩{{ "{:,}".format(year.total.net) }}</b></div>
</div>
<div class="erp-table-wrap">
<table class="perf-table perf-year">
<thead><tr><th class="perf-th-label">월</th><th>총매출</th><th>수수료</th><th>수수료 차감 매출</th></tr></thead>
<tbody>
{% for r in year.rows %}
<tr class="{% if r.future %}is-future{% endif %}">
<th class="perf-td-label" scope="row">{{ r.label }}</th>
<td class="perf-num">{{ won(r.gross) }}</td>
<td class="perf-num">{{ won(r.commission) }}</td>
<td class="perf-num">{{ won(r.net) }}</td>
</tr>
{% endfor %}
</tbody>
<tfoot>
<tr class="perf-row-total">
<th class="perf-td-label" scope="row">합계</th>
<td class="perf-num">{{ won(year.total.gross) }}</td>
<td class="perf-num">{{ won(year.total.commission) }}</td>
<td class="perf-num">{{ won(year.total.net) }}</td>
</tr>
</tfoot>
</table>
</div>
</div>
</div>
<p class="perf-foot perf-muted">
매출 기준: 결제는 결제일, 취소·반품은 발생일에 반영(음수). 수수료는 그날 적용되는 쇼핑몰 수수료율로 계산하며
일·쇼핑몰 단위로 원 미만 반올림합니다. 금액을 누르면 주문 목록을 볼 수 있습니다.
</p>
</section>
<script type="application/json" id="perf-data">{{ {
"names": names,
"codes": codes,
"daily": chart_daily,
"share": chart_share,
"period_kind": period_kind
} | tojson }}</script>
{% endblock %}
{% block scripts %}<script src="/static/performance.js?v=20260929a" defer></script>{% endblock %}
@@ -0,0 +1,121 @@
{% extends "erp_base.html" %}
{% block head_extra %}<link rel="stylesheet" href="/static/performance.css?v=20260929a" />{% endblock %}
{%- macro when(v) -%}{{ (v or '')[:16] | replace('T', ' ') or '—' }}{%- endmacro -%}
{% block content %}
<section class="perf perf-settings" id="perf-settings">
{% include "performance/_tabs.html" %}
{% if not key_info.ok %}
<div class="perf-notice is-warn">
<b>암호화 마스터 키가 없습니다.</b> {{ key_info.message }}
— 키가 없으면 API 인증정보를 저장할 수 없습니다(수수료 설정·대시보드는 사용 가능).
</div>
{% endif %}
<div class="erp-card perf-card">
<div class="perf-card-head">
<h2 class="perf-h">쇼핑몰 설정</h2>
<span class="perf-muted">사용 · 매출 집계 · 수수료율은 바로 저장됩니다. API 인증정보는 [설정]에서 입력합니다.</span>
</div>
<div class="erp-table-wrap">
<table class="perf-table perf-set-table">
<thead>
<tr>
<th class="perf-th-label">쇼핑몰</th>
<th>사용</th>
<th>매출 집계</th>
<th>수수료율</th>
<th>API 설정</th>
<th>연결 상태</th>
<th>마지막 동기화</th>
<th></th>
</tr>
</thead>
<tbody>
{% for r in rows %}
<tr data-code="{{ r.code }}" data-name="{{ r.name }}">
<th class="perf-td-label" scope="row">{{ r.name }}</th>
<td class="perf-center">
<label class="perf-switch" title="사용 여부">
<input type="checkbox" data-field="enabled"{% if r.enabled %} checked{% endif %} /><span></span>
</label>
</td>
<td class="perf-center">
<label class="perf-switch" title="매출 집계에 포함">
<input type="checkbox" data-field="include_in_sales"{% if r.include_in_sales %} checked{% endif %} /><span></span>
</label>
</td>
<td class="perf-rate-cell">
<span class="perf-rate">{% if r.rate %}{{ r.rate }}%{% else %}<span class="perf-muted">미설정</span>{% endif %}</span>
<button type="button" class="erp-btn erp-btn-ghost erp-btn-sm" data-act="rate"
data-has-history="{{ 1 if r.rate_history else 0 }}">변경{% if r.rate_history > 1 %} · 이력 {{ r.rate_history }}{% endif %}</button>
</td>
<td>
{% if r.shared %}<span class="perf-pill">공통 연동</span>
{% elif r.configured %}<span class="perf-pill is-ok">설정완료</span>
{% else %}<span class="perf-pill">미설정</span>{% endif %}
</td>
<td>
<span class="perf-status st-{{ r.status }}"
title="마지막 연결 테스트: {{ when(r.last_test_at) }}{% if r.last_error %}&#10;최근 오류({{ when(r.last_error_at) }}): {{ r.last_error }}{% endif %}">
<i></i>{{ r.status_label }}</span>
{% if r.last_error and r.status not in ('ok', 'disabled') %}<div class="perf-err">{{ r.last_error }}</div>{% endif %}
</td>
<td class="perf-muted perf-nowrap" title="마지막 시도: {{ when(r.last_sync_at) }}">{{ when(r.last_success_sync_at) }}</td>
<td class="perf-nowrap">
<button type="button" class="erp-btn erp-btn-outline erp-btn-sm" data-act="creds">설정</button>
<button type="button" class="erp-btn erp-btn-outline erp-btn-sm" data-act="test">연결 테스트</button>
</td>
</tr>
{% endfor %}
</tbody>
</table>
</div>
<p class="perf-foot perf-muted">
수수료율은 <b>적용 시작일</b>부터 반영되고, 그 전 실적은 예전 요율로 계산됩니다(과거 실적이 바뀌지 않음).
상태에 마우스를 올리면 마지막 연결 테스트 시각과 최근 오류를 볼 수 있습니다.
</p>
</div>
<div class="perf-grid2">
<div class="erp-card perf-card">
<div class="perf-card-head"><h2 class="perf-h">인증정보 암호화</h2></div>
<dl class="perf-dl">
<dt>마스터 키</dt>
<dd>{% if key_info.ok %}<span class="perf-pill is-ok">설정됨 · 현재 v{{ key_info.current_version }}</span>
{% set olds = key_info.versions | reject('equalto', key_info.current_version) | list %}
{% if olds %}<span class="perf-muted">(예전 키 v{{ olds | join(', v') }} 보관 중)</span>{% endif %}
{% else %}<span class="perf-pill is-bad">미설정</span>{% endif %}</dd>
<dt>저장된 항목</dt>
<dd>{% for v, n in key_versions_in_use.items() %}v{{ v }}: {{ n }}개{% if not loop.last %}, {% endif %}{% else %}<span class="perf-muted">없음</span>{% endfor %}</dd>
</dl>
{% if stale_key_rows %}
<p class="perf-notice is-warn">예전 키로 암호화된 항목이 {{ stale_key_rows }}개 있습니다.
<button type="button" class="erp-btn erp-btn-outline erp-btn-sm" id="perf-rekey">현재 키로 다시 암호화</button></p>
{% endif %}
<p class="perf-foot perf-muted">
API 인증정보는 서버에서 AES-256-GCM 으로 암호화해 DB 에 저장합니다. 마스터 키(APP_ENCRYPTION_KEY)는 DB 가 아닌
서버 환경변수에만 있으며, 키를 잃으면 저장된 인증정보를 복구할 수 없으니 별도로 안전하게 보관하세요.
</p>
</div>
<div class="erp-card perf-card">
<div class="perf-card-head"><h2 class="perf-h">테스트 데이터</h2>
<span class="perf-muted">현재 {{ "{:,}".format(sample_count) }}건</span></div>
<p class="perf-muted">실제 API 연동 전 화면 확인용 모의 매출입니다(사용 중인 쇼핑몰 대상). 실제 데이터와 구분되어 한 번에 지울 수 있습니다.</p>
<div class="perf-sample-form">
<input class="erp-input perf-date" type="date" id="perf-sample-from" value="{{ default_sample_from }}" />
<span class="perf-muted">~</span>
<input class="erp-input perf-date" type="date" id="perf-sample-to" value="{{ default_sample_to }}" />
<button type="button" class="erp-btn erp-btn-outline" id="perf-sample-gen">생성</button>
<button type="button" class="erp-btn erp-btn-danger" id="perf-sample-del"{% if not sample_count %} disabled{% endif %}>모두 삭제</button>
</div>
</div>
</div>
</section>
{% endblock %}
{% block scripts %}<script src="/static/performance.js?v=20260929a" defer></script>{% endblock %}