사용자 매뉴얼·번호알기·gov-portal 대시보드와 메뉴 동선·수불 리포트를 보강한다.

- 사용자 매뉴얼: league/commonmark 기반 bag/manual(로그인 전용), ManualRenderer + Config\Manual manifest, 콘텐츠 8종, E2E - 번호알기(봉투번호확인): bag/number-lookup, BagNumberLookup, E2E - gov-portal 대시보드 시안(기본/strip)·기본코드관리 화면 - 메뉴 관리: 등록·수정 후 메뉴 화면 유지, 수정 버튼 클릭 시 상단 스크롤 - 수불/분석 리포트(LOT 수불·반품/파기·수급계획·추이) 표시 보강 - .gitignore: docs/ → /docs/ 앵커링(최상위 개발문서만 제외, app/Docs는 추적) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 00:46:51 +09:00
parent 0f1d414f37
commit 8763876f19
77 changed files with 6139 additions and 182 deletions
--- a/app/Docs/manual/00_overview.md
+++ b/app/Docs/manual/00_overview.md
@@ -0,0 +1,49 @@
+# 시작하기 · 시스템 개요
+
+종량제 쓰레기봉투 물류 시스템 사용자 매뉴얼입니다. 이 문서는 실제 업무를 처리하는 담당자(지자체 관리자·지정판매소)를 위한 **빠른 시작 안내서**입니다.
+
+## 1. 시스템은 무엇을 하나요?
+
+지자체 종량제 쓰레기봉투의 **발주 → 입고 → 재고 → 판매/불출 → 정산·통계** 전 과정을 관리합니다.
+
+- 봉투를 제작업체에 **발주**하고, 들어온 물량을 **입고** 처리합니다.
+- 현재 **재고**를 확인하고, 실사로 실제 수량과 맞춥니다.
+- 지정판매소에 **판매**하거나 무료 대상자에게 **불출**합니다.
+- 일계표·기간별·연간 등 **판매현황**과 **수불·통계**를 조회합니다.
+
+## 2. 로그인과 화면 구성
+
+1. 발급받은 아이디·비밀번호로 로그인합니다.
+2. 관리자(지자체/슈퍼)는 보안을 위해 **2차 인증(OTP)** 이 적용될 수 있습니다.
+3. 로그인하면 상단에 **대메뉴**가 보이고, 각 대메뉴에 마우스를 올리면 **소메뉴**가 펼쳐집니다.
+4. 화면 상단의 제목 바에 현재 보고 있는 화면 이름이 표시됩니다.
+
+> 슈퍼 관리자는 작업할 **지자체를 먼저 선택**해야 업무 화면이 열립니다.
+
+## 3. 사용자 역할(권한)
+
+시스템은 4단계 역할로 접근 권한을 구분합니다.
+
+| 레벨 | 역할 | 할 수 있는 일 |
+|---|---|---|
+| 1 | 일반 사용자 | 기본 조회 |
+| 2 | 지정판매소 | 봉투 판매·반품, 자기 판매 현황 조회 |
+| 3 | 지자체 관리자 | 소속 지자체의 발주·입고·재고·불출·판매·리포트 전반 |
+| 4 | 슈퍼 관리자 | 전체 시스템 관리 + 기본코드 등 마스터 관리 (지자체 선택 후 작업) |
+
+### 역할별 접근 한눈에 보기
+
+| 기능군 | 일반 | 판매소 | 지자체관리자 | 슈퍼 |
+|---|:--:|:--:|:--:|:--:|
+| 기본정보 조회(코드·단가·포장) | △ | ○ | ○ | ○ |
+| 기본코드·마스터 편집 | ✕ | ✕ | △(지자체분) | ○ |
+| 발주·입고·재고·불출 | ✕ | ✕ | ○ | ○ |
+| 판매·반품 등록 | ✕ | ○ | ○ | ○ |
+| 판매현황·수불·통계 | ✕ | △(자기분) | ○ | ○ |
+
+(○ 사용 가능 · △ 제한적 · ✕ 불가)
+
+## 4. 다음 단계
+
+- 전체 업무가 어떻게 이어지는지 먼저 보려면 **[핵심 업무 흐름]** 으로 이동하세요.
+- 특정 작업 방법은 좌측 목차에서 해당 항목(발주·입고 / 재고·실사 / 판매·불출 / 판매현황·수불·통계)을 선택하세요.
--- a/app/Docs/manual/10_workflow.md
+++ b/app/Docs/manual/10_workflow.md
@@ -0,0 +1,36 @@
+# 핵심 업무 흐름
+
+봉투 한 묶음이 시스템에서 거치는 전체 흐름입니다. 처음 사용하신다면 이 순서대로 익히는 것을 권장합니다.
+
+## 전체 흐름
+
+```
+발주 ─→ 입고 ─→ 재고(실사) ─→ 판매 / 불출 ─→ 판매현황 · 수불 · 통계
+```
+
+| 단계 | 무엇을 하나 | 주요 메뉴 |
+|---|---|---|
+| ① 발주 | 봉투 종류·수량을 제작업체에 주문 | 발주 입고 관리 › 발주 등록 |
+| ② 입고 | 도착한 물량을 시스템에 등록(스캐너/일괄) | 발주 입고 관리 › 입고 |
+| ③ 재고 | 현재 보유 수량 확인, 실사로 실수량 보정 | 재고 관리 |
+| ④ 판매 | 지정판매소에 판매·반품 처리 | 판매 관리 |
+| ④ 불출 | 무료 대상자에게 무상 지급 | 불출 관리 |
+| ⑤ 현황 | 일·기간·연간 판매 및 수불·통계 조회 | 판매 현황 / 봉투 수불 / 통계 분석 |
+
+## 각 단계 한 줄 요약
+
+1. **발주** — 봉투 품목·수량·납기를 입력해 발주서를 만들면 추적용 **LOT 번호**가 부여됩니다.
+2. **입고** — 발주분이 도착하면 입고로 등록합니다. 이때 박스·팩·낱장 단위의 **바코드**가 생성됩니다.
+3. **재고** — 품목별 현재 재고를 조회하고, 정기적으로 **실사**(선별 → 등록 → 적용)로 실제 수량과 맞춥니다.
+4. **판매/불출** — 지정판매소 판매·반품, 또는 무료 대상자 불출로 재고가 감소합니다.
+5. **현황·통계** — 일계표·기간별·연간 판매와 봉투 수불, 전년대비/월별/계절 추이를 확인합니다.
+
+## 봉투 추적 단위
+
+봉투는 다음 계층으로 추적됩니다. 자세한 코드 규칙은 **[봉투·LOT·바코드 코드체계]** 문서를 참고하세요.
+
+```
+LOT(발주 묶음) ─→ 박스(B) ─→ 팩(P) ─→ 낱장(S, 봉투 한 장)
+```
+
+> 코드 한 건이 어떤 바코드·인쇄숫자·인식번호인지 확인하려면 **도움말 › 번호알기** 화면을 사용하세요.
--- a/app/Docs/manual/20_order_receiving.md
+++ b/app/Docs/manual/20_order_receiving.md
@@ -0,0 +1,41 @@
+# 발주 · 입고
+
+제작업체에 봉투를 주문(발주)하고, 도착한 물량을 시스템에 등록(입고)하는 단계입니다. **지자체 관리자** 이상이 사용합니다.
+
+## 발주
+
+### 발주 등록
+
+**발주 입고 관리 › 발주 등록**
+
+1. 봉투 **품목**(종류·용량)과 **수량**, 납품 관련 정보를 입력합니다.
+2. 박스/낱장 수량과 금액·총계가 자동으로 계산됩니다.
+3. 저장하면 발주 건이 생성되고, 추적용 **LOT 번호**가 자동 부여됩니다.
+
+> 발주 내용은 무결성 보호를 위해 버전·해시로 관리됩니다. 수정(재발주) 시 기존 LOT는 유지됩니다.
+
+### 발주 변경 · 현황
+
+| 작업 | 메뉴 | 설명 |
+|---|---|---|
+| 발주 변경 | 발주 변경 | 기존 발주 수정·재발주 |
+| 발주 현황 | 발주 현황 | 발주 목록을 기간·상태로 조회, 엑셀 내보내기 |
+| 발주 상세 | (현황에서 행 선택) | 개별 발주 상세 확인, 취소 처리 |
+
+## 입고
+
+발주분이 실제 도착하면 입고로 등록합니다. 입고 시 **박스·팩·낱장 바코드**가 생성되어 재고에 반영됩니다.
+
+| 방식 | 메뉴 | 언제 사용 |
+|---|---|---|
+| 스캐너 입고 | 발주 입고[스캐너] | 바코드를 스캔하며 입고 |
+| 일괄 입고 | 일괄입고 | 다량을 한 번에 입고 |
+| 입고 현황 | 입고 현황 | 입고 기록 조회, 엑셀 내보내기 |
+
+### 입고 처리 순서
+
+1. 입고할 발주 건(LOT)을 선택합니다.
+2. 도착 수량(박스/낱장)을 확인·입력합니다.
+3. 저장하면 재고가 증가하고, 단위별 바코드가 부여됩니다.
+
+> 입고가 끝나면 **재고 관리**에서 수량이 정상 반영됐는지 확인하세요.
--- a/app/Docs/manual/30_inventory.md
+++ b/app/Docs/manual/30_inventory.md
@@ -0,0 +1,39 @@
+# 재고 · 실사
+
+현재 보유 봉투 수량을 확인하고, 정기적으로 실사를 통해 실제 수량과 맞추는 단계입니다.
+
+## 재고 현황
+
+**재고 관리 › 재고 현황**
+
+- 품목별·상태별 현재 재고를 조회합니다.
+- 지자체·봉투 종류 등으로 필터링할 수 있습니다.
+- **엑셀 내보내기**로 목록을 저장할 수 있습니다.
+
+| 항목 | 설명 |
+|---|---|
+| 품목 | 봉투 종류·용량 |
+| 재고 수량 | 입고 − (판매 + 불출 + 파기) |
+| 상태 | 재고/판매 등 단위별 상태 |
+
+## 실사 (재고 조사)
+
+장부상 재고와 실제 창고 수량을 맞추는 작업입니다. 다음 순서로 진행합니다.
+
+```
+실사 선별 ─→ 실사 등록(작업) ─→ 적용
+```
+
+| 단계 | 메뉴 | 하는 일 |
+|---|---|---|
+| ① 선별 | 실사 선별 조회 | 실사 대상 범위를 골라 선별 |
+| ② 작업 | 실사 선별 관리 | 실제 수량을 입력·기록 |
+| ③ 상세·적용 | 실사 상세 | 실사 결과를 확인하고 재고에 **적용** |
+
+### 실사 진행 순서
+
+1. **선별**: 실사할 품목·구간을 선택해 실사 건을 만듭니다.
+2. **등록**: 실제 센 수량을 입력합니다. 장부 수량과의 차이가 표시됩니다.
+3. **적용**: 검토 후 적용하면 차이가 재고에 반영됩니다.
+
+> 적용 전까지는 재고에 영향을 주지 않으므로, 입력 도중 중단해도 안전합니다.
--- a/app/Docs/manual/40_sales_issue.md
+++ b/app/Docs/manual/40_sales_issue.md
@@ -0,0 +1,46 @@
+# 판매 · 불출
+
+재고를 외부로 내보내는 두 가지 경로입니다. **판매**는 지정판매소 대상 유상 거래, **불출**은 무료 대상자에 대한 무상 지급입니다.
+
+## 판매 (지정판매소)
+
+**판매 관리** 메뉴에서 처리합니다.
+
+| 작업 | 메뉴 | 설명 |
+|---|---|---|
+| 판매 등록 | 지정 판매소 판매 | 판매소를 선택해 판매 거래 기록 |
+| 스캔 판매 | 지정 판매소 판매[스캔] | 바코드를 스캔하며 판매(판매소 현장용) |
+| 판매 취소 | 지정 판매소 판매 취소 | 기존 판매 거래 취소 |
+| 반품 | 지정 판매소 반품 | 판매분 반품 등록 |
+| 반품 취소 | 지정 판매소 반품 취소 | 반품 취소 처리 |
+
+### 판매 등록 순서
+
+1. 판매할 **지정판매소**를 선택합니다.
+2. 봉투 **품목·수량**을 입력(또는 바코드 스캔)합니다.
+3. 저장하면 재고가 감소하고 판매 내역이 기록됩니다.
+
+### 전화 접수(주문)
+
+| 작업 | 메뉴 |
+|---|---|
+| 전화 접수(신규) | 전화 접수 |
+| 전화 접수 관리 | 전화 접수 관리(수정·취소) |
+
+## 불출 (무료 대상자)
+
+**불출 관리** 메뉴에서 무료 대상자에게 봉투를 무상 지급합니다.
+
+| 작업 | 메뉴 | 설명 |
+|---|---|---|
+| 불출 처리 | 무료용 불출 처리 | 무료 배분 등록(재고 감소) |
+| 불출 취소 | 무료용 불출 취소 | 불출 취소(재고 복원) |
+| 불출 현황 | 무료 불출 현황 | 기간별 불출 기록 조회 |
+
+### 불출 처리 순서
+
+1. 무료 **대상처**와 봉투 **품목·수량**을 선택합니다.
+2. 저장하면 재고가 감소하고 불출 내역이 기록됩니다.
+3. 잘못 처리한 경우 **무료용 불출 취소**로 되돌리면 재고가 복원됩니다.
+
+> 판매·불출 모두 재고를 감소시키므로, 처리 후 **재고 현황**에서 반영 결과를 확인하세요.
--- a/app/Docs/manual/50_reports.md
+++ b/app/Docs/manual/50_reports.md
@@ -0,0 +1,42 @@
+# 판매현황 · 수불 · 통계
+
+판매·재고 흐름을 집계해 보여주는 조회·리포트 화면 모음입니다. 대부분 **기간을 지정해 조회**하고 인쇄·엑셀로 내보낼 수 있습니다.
+
+## 판매 현황
+
+| 메뉴 | 내용 |
+|---|---|
+| 지정 판매소 일/기간 판매대장 | 판매소별 일자·기간 거래 장부 |
+| 일계표 | 하루 전체 판매 요약(일계 + 월 누계) |
+| 기간별 판매현황 | 지정 기간의 판매 집계(일집계/기간집계) |
+| 년 판매 현황 | 연간 판매 통계(월별/분기별) |
+| 지정 판매소별 판매현황 | 판매소별 수량·금액 비교 |
+| 홈텍스 처리 | 세금계산서용 데이터(엑셀) 생성 |
+
+## 봉투 수불 관리
+
+입고·판매·불출·반품·파기를 한데 모아 **수불(수입·불출)** 흐름을 봅니다.
+
+| 메뉴 | 내용 |
+|---|---|
+| 기간별 봉투 수불 현황 | 기간 내 재고/입고/판매/불출 종합(엑셀 가능) |
+| 기타 입출고 | 손상·기증·폐기 등 기타 입출고 등록·조회 |
+| 반품/파기 현황 | 반품 및 파기 내역 |
+| LOT 수불 조회 | 봉투번호(바코드)·LOT 단위 이력 추적 |
+| 쓰레기 봉투 수급 계획 | 공급·수요 계획 |
+
+### LOT 수불 조회 사용법
+
+1. **봉투번호(바코드)** 또는 LOT 번호를 입력합니다.
+2. 조회하면 해당 단위의 입고·판매·반품 이력이 표시됩니다.
+3. 입력할 코드 형식이 헷갈리면 **도움말 › 번호알기**로 먼저 확인하세요.
+
+## 통계 분석
+
+| 메뉴 | 내용 |
+|---|---|
+| 전년 대비 판매 분석 | 작년 동기 대비 비교(차트) |
+| 월별 판매 추이 분석 | 월별 추이 시각화 |
+| 계절별 판매 추이 분석 | 계절 패턴 분석 |
+
+> 리포트 화면은 조회 조건(기간·품목·판매소)을 바꿔가며 반복 조회할 수 있습니다. 결과는 인쇄 버튼 또는 엑셀 내보내기로 저장하세요.
--- a/app/Docs/manual/90_code_system.md
+++ b/app/Docs/manual/90_code_system.md
@@ -0,0 +1,57 @@
+# 봉투 · LOT · 바코드 코드체계
+
+봉투번호(바코드)·LOT 번호·품목코드가 무엇을 뜻하는지 정리한 안내입니다. LOT 수불 조회나 번호알기 화면에서 코드를 입력할 때 참고하세요.
+
+## 추적 단위 계층
+
+```
+LOT(발주 묶음) ─→ 박스(B) ─→ 팩(P) ─→ 낱장(S, 봉투 한 장)
+```
+
+| 단위 | 예시 | 용도 |
+|---|---|---|
+| LOT | `OQXCKH` | 발주 단위, LOT 수불·시드 |
+| 박스 | `OQXCKH-000008-B001` | 박스 단위 입출고 |
+| 팩 | `OQXCKH-000008-P299` | 팩 단위(스캔 가능) |
+| 낱장 | `OQXCKH-000008-P299-S00125` | 봉투 한 장 단위 판매·반품 |
+
+> `000008`은 "8번째 봉투"가 아니라 **입고 건 번호를 6자리로 채운 값**입니다.
+
+## 바코드 형식 읽는 법
+
+`OQXCKH-000008-P299-S00125` 를 예로 들면:
+
+| 구간 | 값 | 의미 |
+|---|---|---|
+| 접두 | `OQXCKH` | 발주 LOT 번호 |
+| 입고번호 | `000008` | 입고 건 번호(6자리) |
+| 팩 | `P299` | 그 입고 건의 299번째 팩 |
+| 낱장 | `S00125` | 그 팩의 125번째 낱장(봉투 한 장) |
+
+- 박스는 `B001`, 팩은 `P299` 처럼 접두 문자로 구분합니다.
+- LOT 번호는 발주 시 자동 부여되는 영문·숫자 6자리입니다.
+
+## 품목코드 (봉투 종류)
+
+품목코드는 봉투의 **종류·용량**을 식별하는 마스터 코드로, 바코드와는 별개입니다.
+
+| 자리 | 의미 | 예 |
+|---|---|---|
+| 앞 2자리 | 봉투 구분(10 일반, 20 공공, 30 무료 …) | `10` |
+| 다음 2자리 | 용량 | `15` |
+| 마지막 1자리 | 재질 등 | `2` |
+
+**예:** `10152` = 일반용 20L. 같은 품목이라도 발주·입고 건마다 바코드(LOT) 접두는 달라집니다.
+
+## 번호알기로 확인하기
+
+코드 한 건이 어떤 바코드·인쇄숫자·인식번호인지 확인하려면 **도움말 › 번호알기(봉투번호확인)** 화면에 코드를 입력하세요.
+
+입력 가능한 형식:
+
+| 단위 | 입력 형식 | 예시 |
+|---|---|---|
+| 낱장 | `{LOT}-{입고번호}-P{팩}-S{낱장}` | `OQXCKH-000008-P299-S00125` |
+| 팩 | `{LOT}-{입고번호}-P{팩}` | `OQXCKH-000008-P299` |
+| 박스 | `{LOT}-{입고번호}-B{박스}` | `OQXCKH-000008-B001` |
+| LOT | 영문·숫자 4~8자리 | `OQXCKH` |
--- a/app/Docs/manual/99_faq.md
+++ b/app/Docs/manual/99_faq.md
@@ -0,0 +1,29 @@
+# 자주 묻는 질문 · 문의
+
+## 자주 묻는 질문
+
+### Q. 로그인 후 업무 화면이 안 열려요.
+슈퍼 관리자는 **작업할 지자체를 먼저 선택**해야 합니다. 상단 안내에 따라 지자체를 선택하세요. 일반/판매소 계정은 권한 범위 내 메뉴만 보입니다.
+
+### Q. 메뉴가 안 보여요.
+역할(권한)에 따라 노출 메뉴가 다릅니다. **시작하기 › 역할별 접근 한눈에 보기** 표를 확인하세요. 그래도 필요한 메뉴가 없으면 관리자에게 문의하세요.
+
+### Q. 입고했는데 재고에 안 보여요.
+입고가 정상 저장됐는지 **발주 입고 관리 › 입고 현황**에서 확인하고, **재고 관리 › 재고 현황**에서 품목·지자체 필터를 점검하세요.
+
+### Q. 판매/불출을 잘못 처리했어요.
+- 판매: **지정 판매소 판매 취소** 또는 **반품**으로 되돌립니다.
+- 불출: **무료용 불출 취소**로 되돌리면 재고가 복원됩니다.
+
+### Q. 봉투 코드(바코드)가 무슨 뜻인지 모르겠어요.
+**도움말 › 번호알기(봉투번호확인)** 에 코드를 입력하면 바코드·인쇄숫자·인식번호로 분해해 보여줍니다. 형식은 **봉투·LOT·바코드 코드체계** 문서를 참고하세요.
+
+### Q. 비밀번호를 바꾸고 싶어요.
+**기본정보관리 › PASSWORD 변경** 에서 변경할 수 있습니다.
+
+### Q. 리포트를 엑셀/인쇄로 저장할 수 있나요?
+대부분의 현황·리포트 화면에 **엑셀 내보내기**와 **인쇄** 기능이 있습니다. 이 매뉴얼 화면도 우측 상단 **인쇄** 버튼으로 출력할 수 있습니다.
+
+## 문의
+
+시스템 사용 중 문제가 있으면 시스템 운영 담당자 또는 소속 지자체 관리자에게 문의하세요.