From 13a5a56146883632f181be29e2f98f5156e757e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Tue, 10 Mar 2026 09:28:07 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B0=9C=EB=B0=9C=EC=84=9C=EB=B2=84=20?= =?UTF-8?q?sam-docs=20=ED=8F=B4=EB=8D=94=EC=97=90=EC=84=9C=20=EB=88=84?= =?UTF-8?q?=EB=9D=BD=20=EB=AC=B8=EC=84=9C=205=EA=B1=B4=20=EB=B3=B5?= =?UTF-8?q?=EA=B5=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - guides/project-launch-roadmap.md - plans/SAM_ERP_Storyboard_D1.4.md - plans/SAM_ERP_회계관리_Storyboard_D1.6.md - plans/integrated-master-plan.md - plans/production-deployment-plan.md --- guides/project-launch-roadmap.md | 639 ++++++++++ plans/SAM_ERP_Storyboard_D1.4.md | 1150 ++++++++++++++++++ plans/SAM_ERP_회계관리_Storyboard_D1.6.md | 1288 +++++++++++++++++++++ plans/integrated-master-plan.md | 382 ++++++ plans/production-deployment-plan.md | 1099 ++++++++++++++++++ 5 files changed, 4558 insertions(+) create mode 100644 guides/project-launch-roadmap.md create mode 100644 plans/SAM_ERP_Storyboard_D1.4.md create mode 100644 plans/SAM_ERP_회계관리_Storyboard_D1.6.md create mode 100644 plans/integrated-master-plan.md create mode 100644 plans/production-deployment-plan.md diff --git a/guides/project-launch-roadmap.md b/guides/project-launch-roadmap.md new file mode 100644 index 0000000..c3459fe --- /dev/null +++ b/guides/project-launch-roadmap.md @@ -0,0 +1,639 @@ +# SAM 프로젝트 런칭 로드맵 + +**작성일**: 2025-11-24 +**최종 수정**: 2025-12-02 +**목적**: 프로젝트 전체 방향성 관리 및 런칭 준비 현황 추적 +**대상**: 프로젝트 관리 및 의사결정용 + +--- + +## 1. 프로젝트 현황 개요 + +### 전체 시스템 구성 +``` +SAM (Smart Application Management) +├── api/ - Laravel 12 REST API (독립 모델) +├── mng/ - Plain Laravel 관리자 패널 (독립 모델, 운영 주력) +├── react/ - Next.js 15 사용자 프론트엔드 +├── docs/ - 기술 문서 +├── design/ - 디자인 시스템 (Storybook) +├── planning/ - 기획 문서 +└── docker/ - Docker 개발 환경 +``` + +### 프로젝트 구분 + +| 구분 | 대상 | 설명 | 담당 | +|------|------|------|------| +| **MES (경동기업)** | 경동기업 | 메인 프로젝트, 디자인 시스템 기준 | 디자이너 (기획+디자인) | +| **MES (주일기업)** | 주일기업 | 경동기업 디자인 기반 커스터마이징 | 기획자 | +| **ERP** | SAM 공통 | 공통 모듈 (인사, 회계, 결재 등) | 기획자 | + +### MVP 범위 정의 + +| 구분 | 범위 | 설명 | +|------|------|------| +| **코어 MVP** | MES 핵심 기능 | 견적 → 수주 → 생산 → 출하 흐름 | +| **1차 MVP** | 코어 MVP + 추가 기능 | 품질, 자재, 단가, 회계 등 확장 | + +### 각 시스템 역할 +- **api**: 모든 비즈니스 로직과 데이터 처리의 중심 +- **mng**: Pure Blade + Tailwind 관리자 패널 (운영 환경 주력) +- **react**: 최종 사용자용 인터페이스 +- **design**: 디자인 시스템 및 컴포넌트 문서 + +### 현재 개발 완료율 +- **백엔드 (API)**: 약 70% 완료 + - ✅ 인증/권한, 멀티테넌트, 기준정보 + - ✅ 제품/BOM, 견적/수주, 자재입고/검사 + - 🔄 공정/생산, 단가/원가, 재고관리 + +- **프론트엔드**: 약 50% 완료 + - ✅ Admin 패널 27개 Resources + - 🔄 React 사용자 포털 개발 중 + +--- + +## 2. 팀 구성 및 역할 + +### 팀 역할 분담 + +| 역할 | 담당자 | 주요 업무 | 비고 | +|------|--------|----------|------| +| **디자이너** | 재웅 정 | MES(경동기업) 기획 + 디자인 | 디자인 시스템 기준 | +| **기획자** | 이태화 | ERP 스토리보드, MES(주일기업) 기획, 운영, QA | 기획 완료 시 MES 합류 | +| **Frontend** | - | React 개발 | MES(경동) 우선 | +| **Backend** | hso be | API 서포트, mng 개발, 인프라, 정책/운영 | 전체 기술 지원 | + +### 작업 우선순위 + +**Frontend 우선순위:** +1. **MES (경동기업)** - 디자이너 결과물 즉시 개발 +2. **ERP + MES (주일기업)** - MES 짬/대기 시 병행 + +**Backend 역할:** +- Frontend API 서포트 +- mng (운영 관리자 패널) 개발 +- 인프라 셋팅 +- 정책/운영 관련 일정 체크 + +--- + +## 3. 주요 마일스톤 개요 + +### 📅 마일스톤 타임라인 + +``` +2025년 12월 2026년 1월 2026년 2월 2026년 3월 + | | | | + MS1 MS2 MS3 MS4 +코어 MVP 완료 1차 MVP + 베타 정식 런칭 안정화 완료 +(단위테스트) (통합테스트) +``` + +### 마일스톤 요약 + +| 마일스톤 | 목표 | 기한 | 주요 내용 | +|---------|------|------|----------| +| **MS1** | 코어 MVP 개발 완료 | 2025-12-31 | MES 핵심 기능 + 단위테스트 | +| **MS2** | 1차 MVP + 베타 오픈 | 2026-01-31 | 통합테스트 + 베타 서비스 오픈 | +| **MS3** | 정식 런칭 | 2026-02-28 | 운영 서버 오픈 | +| **MS4** | 안정화 완료 | 2026-03-31 | 고객 성공 사례 확보 | + +--- + +## 4. 기획 및 디자인 일정 + +### 4.1 MES (경동기업) - 디자이너 일정 +**기간**: 2025-11-26 ~ 2025-12-26 (약 21일) + +#### Phase 1: 견적 (11/27 ~ 11/28) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| S2 | 견적 리스트 | LIST | 0.25 | 11-27(목) | 11-27(목) | +| S2-1 | 견적 등록 | FORM | 0.5 | 11-27(목) | 11-27(목) | +| S2-2 | 견적 수정 | FORM | 0.25 | 11-27(목) | 11-28(금) | +| S2-3 | 견적 상세+탭 | DETAIL | 0.5 | 11-28(금) | 11-28(금) | +| S2-4 | 견적서 출력 | PRINT | 0.25 | 11-28(금) | 11-28(금) | + +#### Phase 2: 기준-수식 (11/28 ~ 12/01) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| M12 | 견적수식 리스트 | LIST | 0.1 | 11-28(금) | 11-28(금) | +| M12-1 | 견적수식 등록 | FORM | 0.2 | 12-01(월) | 12-01(월) | + +#### Phase 3: 수주 (12/01 ~ 12/04) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| S3-1 | 수주 리스트 | LIST | 0.25 | 12-01(월) | 12-01(월) | +| S3-2 | 수주 등록 | FORM | 0.5 | 12-01(월) | 12-02(화) | +| S4-3 | 수주 수정 | FORM | 1 | 12-02(화) | 12-03(수) | +| S4-4 | 수주 상세+탭 | DETAIL | 1 | 12-03(수) | 12-04(목) | +| S4-5 | 수주서 발송 | PRINT | 0.5 | 12-04(목) | 12-04(목) | + +#### Phase 4: 생산 (12/04 ~ 12/08) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| P1-3-3 | 작업지시 리스트 | LIST | 0.25 | 12-04(목) | 12-05(금) | +| P1-3-4 | 작업지시 등록 | FORM | 0.5 | 12-05(금) | 12-05(금) | +| P1-3-5 | 작업지시 수정 | FORM | 0.2 | 12-05(금) | 12-05(금) | +| P1-3-6 | 작업지시 상세 | DETAIL | 0.25 | 12-05(금) | 12-08(월) | +| P1-3-7 | 작업실적 입력 | FORM | 0.5 | 12-08(월) | 12-08(월) | +| P1-3-8 | 작업실적 조회 | DETAIL | 0.25 | 12-08(월) | 12-08(월) | + +#### Phase 5: 기준-공정 (12/08 ~ 12/10) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| M5 | 공정 리스트 | LIST | 0.25 | 12-08(월) | 12-08(월) | +| M5-1 | 공정 등록 | FORM | 0.5 | 12-09(화) | 12-09(화) | +| M5-2 | 공정 수정 | FORM | 0.2 | 12-09(화) | 12-09(화) | +| M5-3 | 공정 상세 | DETAIL | 0.5 | 12-10(수) | 12-10(수) | + +#### Phase 6: 출하 (12/10 ~ 12/12) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| S4 | 출하 리스트 | LIST | 0.25 | 12-10(수) | 12-10(수) | +| S4-1 | 출하 등록 | FORM | 0.5 | 12-10(수) | 12-11(목) | +| S4-2 | 배송 조율/관리 | FORM | 0.5 | 12-11(목) | 12-11(목) | +| S4-3 | 상차 체크리스트 | FORM | 0.5 | 12-11(목) | 12-12(금) | +| S4-4 | 출하 수정+탭 | FORM | 0.5 | 12-12(금) | 12-12(금) | + +#### Phase 7: 거래처 (12/15 ~ 12/16) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| S1-1 | 거래처 리스트 | LIST | 0.25 | 12-15(월) | 12-15(월) | +| S1-1 | 거래처 등록 | FORM | 0.5 | 12-15(월) | 12-15(월) | +| S1-2 | 거래처 수정 | FORM | 0.1 | 12-15(월) | 12-16(화) | +| S1-3 | 거래처 상세+탭 | DETAIL | 0.25 | 12-16(화) | 12-16(화) | + +#### Phase 8: 품질 (12/16 ~ 12/19) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| M9 | 검사기준 리스트 | LIST | 0.5 | 12-16(화) | 12-16(화) | +| M9-1 | 검사기준 등록 | FORM | 1 | 12-17(수) | 12-17(수) | +| Q1 | 검사관리 리스트 | LIST | 0.5 | 12-18(목) | 12-18(목) | +| Q1-1 | 검사관리 등록 | FORM | 1 | 12-18(목) | 12-19(금) | +| Q1-2 | 검사관리 상세 | DETAIL | 0.5 | 12-19(금) | 12-19(금) | + +#### Phase 9: 자재 (12/19 ~ 12/24) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| I1 | 재고현황 리스트 | LIST | 0.5 | 12-19(금) | 12-22(월) | +| I1-1 | 재고 상세+탭 | DETAIL | 1 | 12-22(월) | 12-23(화) | +| I2 | 입고 리스트 | LIST | 0.5 | 12-23(화) | 12-23(화) | +| I2-1 | 입고 등록 | FORM | 0.8 | 12-23(화) | 12-24(수) | +| I2-3 | 입고 상세+탭 | DETAIL | 0.5 | 12-24(수) | 12-24(수) | + +#### Phase 10: 단가 (12/24) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| S6 | 단가 리스트 | LIST | 0.25 | 12-24(수) | 12-24(수) | +| S6-1 | 단가 등록 | FORM | 0.25 | 12-24(수) | 12-24(수) | +| S6-2 | 단가 수정 | FORM | 0.25 | 12-24(수) | 12-24(수) | +| S6-3 | 단가 상세+탭 | DETAIL | 0.25 | 12-24(수) | 12-24(수) | + +#### Phase 11: 회계 (12/26) +| 화면ID | 화면명 | 유형 | 공수 | 시작일 | 종료일 | +|--------|--------|------|------|--------|--------| +| A1 | 판매조회 리스트 | LIST | 0.5 | 12-26(금) | 12-26(금) | +| A4 | 수금 리스트 3탭 | LIST | 0.25 | 12-26(금) | 12-26(금) | +| A4-1 | 수금 등록 | FORM | 0.25 | 12-26(금) | 12-26(금) | + +### 4.2 기획자 일정 (ERP + 운영) + +#### 기획 (이태화) +| 구분 | 업무 | 기간 | 일수 | 대상 | +|------|------|------|------|------| +| 스토리보드 | 공통, ERP | 11/26 ~ 12/12 | 13 | SAM | +| 가입 및 로그인 | 스토리보드 | 11/27 | 1 | SAM | +| 인사관리, 전자결재 | 스토리보드 | 11/28 ~ 12/01 | 4 | SAM | +| 회계, 보고서 | 스토리보드 | 12/02 ~ 12/09 | 6 | SAM | +| 고객센터, 게시판 | 스토리보드 | 12/10 ~ 12/12 | 3 | SAM | +| 주일기업 요구사항 정리 | 요구사항 | 12/02 ~ 12/12 | 9 | 주일기업 | +| 스토리보드 - 주일기업 MES | 기획 | 12/15 ~ 12/30 | 12 | 주일기업 | +| 스토리보드 - ERP 2차 | 기획 | 12/31 ~ 01/13 | 12 | SAM | +| 스토리보드 - MES 2차 | 기획 | 01/14 ~ 01/27 | 12 | SAM | + +#### 운영 (hso be) +| 구분 | 업무 | 기간 | 일수 | 대상 | +|------|------|------|------|------| +| 보고서 지표 검토 | 운영 | 11/27 ~ 11/28 | 2 | SAM | +| 주일기업 자료 정리 및 취합 | 운영 | 11/26 ~ 11/28 | 3 | 주일기업 | +| 주일기업 업무 프로세스 인터뷰 | 운영 | 12/01 ~ 12/05 | 5 | 주일기업 | +| 법률 및 정책 검토 | 운영 | 12/08 ~ 12/19 | 10 | SAM | + +--- + +## 5. MS1: 코어 MVP 개발 완료 (2025-12-31) + +**목표**: MES 핵심 기능 개발 완료 + 단위테스트 통과 + +### 코어 MVP 범위 +- **핵심 흐름**: 견적 → 수주 → 생산(작업지시/실적) → 출하 +- **기준정보**: 거래처, 공정, 견적수식 +- **단위테스트**: 커버리지 60% 이상 + +### 완료 기준 +- ✅ 코어 MVP 기능 100% 구현 +- ✅ 단위테스트 커버리지 60% 이상 +- ✅ Swagger 문서화 (코어 MVP 범위) +- ✅ Critical/High 버그 0건 +- ✅ API 평균 응답 속도 < 500ms + +### 주요 산출물 +- [ ] 코어 MVP 소스코드 (api, react) +- [ ] API 문서 (Swagger) +- [ ] 단위테스트 보고서 + +### Week별 작업 + +**Week 1 (12/02-12/08)** +| 팀 | 작업 내용 | +|----|----------| +| 📋 기획 | 회계/보고서 스토리보드 | +| 📋 운영 | 주일기업 업무 프로세스 인터뷰 | +| 🎨 디자인 | 생산, 기준-공정 화면 | +| 🔧 Backend | 공정/단가 체계 완성 | +| 💻 Frontend | React 개발 시작 (12/08~) | + +**Week 2 (12/09-12/15)** +| 팀 | 작업 내용 | +|----|----------| +| 📋 기획 | 고객센터/게시판 스토리보드, 주일기업 MES 스토리보드 시작 | +| 📋 운영 | 법률 및 정책 검토 시작 | +| 🎨 디자인 | 출하, 거래처 화면 | +| 🔧 Backend | 견적서 PDF, 재고 트랜잭션 | +| 💻 Frontend | 견적/수주 화면 개발 | +| 🧪 QA | 단위테스트 시작 (12/10~) | + +**Week 3 (12/16-12/22)** +| 팀 | 작업 내용 | +|----|----------| +| 📋 기획 | 주일기업 MES 스토리보드 진행 | +| 🎨 디자인 | 품질, 자재 화면 | +| 🔧 Backend | API 안정화, 버그 수정 | +| 💻 Frontend | 생산/출하 화면 개발 | +| 🧪 QA | 단위테스트 진행 | + +**Week 4 (12/23-12/31)** +| 팀 | 작업 내용 | +|----|----------| +| 🎨 디자인 | 단가, 회계 화면 (완료) | +| 🔧 Backend | 코어 MVP 마무리 | +| 💻 Frontend | 코어 MVP 화면 완료 | +| 🧪 QA | 단위테스트 완료 | + +### 체크포인트 +- 12/15: 개발 70% 완료, 단위테스트 시작 +- 12/22: 개발 90% 완료 +- 12/29: 코어 MVP 개발 완료 +- 12/31: **MS1 완료** - 단위테스트 통과 + +--- + +## 6. MS2: 1차 MVP + 베타 오픈 (2026-01-31) + +**목표**: 통합테스트 완료 + 1차 MVP 완료 + 베타 서비스 오픈 + +### 1차 MVP 범위 (추가 예정) +- **확장 기능**: 품질, 자재, 단가, 회계 +- **추가 기능**: (1차 MVP 일정에서 별도 정의) + +### 완료 기준 +- ✅ 통합테스트 통과 +- ✅ 베타 서버 구축 완료 +- ✅ 파일럿 고객 온보딩 완료 +- ✅ 주요 시나리오 실전 테스트 완료 + +### 주요 산출물 +- [ ] 1차 MVP 소스코드 +- [ ] 통합테스트 보고서 +- [ ] 베타 서버 환경 + +### Week별 작업 + +**Week 1 (01/01-01/05)** +| 팀 | 작업 내용 | +|----|----------| +| 🧪 QA | 통합테스트 시작 | +| 🔧 Backend | 베타 서버 구축, 도메인/SSL 설정 | +| 📋 기획 | ERP 2차 스토리보드 진행 | + +**Week 2 (01/06-01/12)** +| 팀 | 작업 내용 | +|----|----------| +| 🧪 QA | 통합테스트 진행 | +| 🔧 Backend | 파일럿 고객 데이터 준비 | +| 💻 Frontend | 버그 수정, UI 개선 | +| 📋 기획 | ERP 2차 스토리보드 완료 (01/13) | + +**Week 3 (01/13-01/19)** +| 팀 | 작업 내용 | +|----|----------| +| 🧪 QA | 통합테스트 완료 | +| 운영 | 파일럿 고객 온보딩 (1차) | +| 📋 기획 | MES 2차 스토리보드 시작 (01/14) | + +**Week 4 (01/20-01/31)** +| 팀 | 작업 내용 | +|----|----------| +| 전체 | 실전 테스트, 피드백 수집 | +| 🔧 Backend | 긴급 버그 수정 | +| 📋 기획 | MES 2차 스토리보드 진행 | + +### 베타 고객 프로필 +| 고객사 | 업종 | 주요 사용 기능 | 기대 효과 | +|--------|------|----------------|----------| +| 경동기업 | 제조 | 견적/수주/BOM/생산 | MES 전체 검증 | +| 주일기업 | 제조 | MES 커스터마이징 | 확장성 검증 | + +### 체크포인트 +- 01/05: 베타 서버 오픈 +- 01/13: 통합테스트 완료 +- 01/20: 파일럿 고객 온보딩 완료 +- 01/31: **MS2 완료** - 베타 서비스 오픈 + +--- + +## 7. MS3: 정식 런칭 (2026-02-28) + +**목표**: 운영 서버 오픈 및 본격적인 서비스 시작 + +### 완료 기준 +- ✅ 운영 서버 구축 완료 (이중화) +- ✅ 베타 피드백 반영 완료 +- ✅ 보안 감사 통과 +- ✅ 법적 문서 완비 + +### 주요 산출물 +- [ ] 운영 서버 환경 +- [ ] 보안 감사 보고서 +- [ ] 마케팅 자료 + +### Week별 작업 + +**Week 1-2 (02/01-02/14): 운영 준비** +| 작업 | 내용 | +|------|------| +| 베타 피드백 반영 | UI/UX 개선, 성능 최적화 | +| 운영 서버 구축 | 이중화, 모니터링, 백업 | +| 보안 감사 | 취약점 점검 및 수정 | +| 📋 기획 | MES 2차 스토리보드 완료 (01/27) | + +**Week 3-4 (02/15-02/28): 런칭** +| 작업 | 내용 | +|------|------| +| 정식 오픈 | 운영 서버 오픈 | +| 고객 온보딩 | 초기 고객 온보딩 시작 | + +### 체크포인트 +- 02/14: 운영 준비 완료 +- 02/28: **MS3 완료** - 정식 런칭 + +--- + +## 8. MS4: 안정화 완료 (2026-03-31) + +**목표**: 서비스 안정화 및 초기 고객 성공 사례 확보 + +### 완료 기준 +- ✅ 시스템 가용성 99.5% 이상 +- ✅ 고객 만족도 4.0/5.0 이상 +- ✅ 성공 사례 3건 이상 확보 + +### 주요 작업 +- 런칭 후 긴급 이슈 대응 +- 모니터링 강화 +- 고객 피드백 수집 및 반영 +- 성능 최적화 +- 고객 성공 사례 수집 +- Q2 로드맵 수립 + +### 체크포인트 +- 03/15: 초기 안정화 완료 +- 03/31: **MS4 완료** - 안정화 완료 + +--- + +## 9. 개발 방향성 + +### 기술 아키텍처 방향 +- **Backend**: Laravel 12 + PHP 8.4+ +- **Frontend**: Next.js 15 + React 18 +- **Database**: MySQL 8.0 (멀티테넌트 구조) +- **Auth**: Laravel Sanctum +- **API**: RESTful + Swagger 문서화 +- **Deployment**: Docker + Docker Compose + +### 핵심 개발 원칙 +1. **Service-First**: 모든 비즈니스 로직은 Service 클래스에 +2. **Multi-tenancy**: BelongsToTenant 스코프 필수 적용 +3. **FormRequest**: Controller에서 직접 검증 금지 +4. **API-First**: Backend 완성 후 Frontend 연동 +5. **문서화**: Swagger 100% 완성 목표 + +### 디자인 시스템 전략 +- **MES (경동기업)** 기준으로 디자인 시스템 구성 +- **ERP**는 경동기업 디자인 시스템 기반으로 Frontend가 직접 개발 +- **MES (주일기업)**은 경동기업 디자인 기반 커스터마이징 + +### 품질 기준 +- API Rules 100% 준수 +- Swagger 문서화 완성도 100% +- 테스트 커버리지 60% 이상 +- Pint 코드 포맷팅 통과 +- i18n 메시지 키 사용 + +--- + +## 10. 개발 작업 현황 + +### ✅ 백엔드 완료 항목 + +#### API 공통 기반 +- [x] Exception Handler +- [x] Swagger 설정 (l5-swagger v1) +- [x] API Key 인증 +- [x] Rate Limit, CORS +- [x] 권한 체크 미들웨어 + +#### 인증/보안 +- [x] API Key 모델 및 인증 +- [x] Role-Permission 시스템 +- [x] 멀티테넌트 권한 구조 +- [x] 권한 오버라이드 시스템 + +#### 테넌트 관리 +- [x] BelongsToTenant 글로벌 스코프 +- [x] TenantBootstrap 서비스 +- [x] 테넌트 컨텍스트 주입 +- [x] 테넌트 옵션/설정 관리 + +#### 기준정보/코드 관리 +- [x] Category (3단계 트리) +- [x] CategoryField (동적 필드) +- [x] CategoryTemplate +- [x] Classification (공통 코드) +- [x] CommonCode 관리 + +#### 제품/부품/자재 도메인 +- [x] Product 모델 (67개 모델) +- [x] Part 관리 +- [x] Material 관리 +- [x] ProductComponent (BOM 연결) +- [x] PriceHistory (단가 이력) + +#### BOM (Bill of Materials) +- [x] BomTemplate 관리 +- [x] BomTemplateItem CRUD +- [x] BomCalculationService (가격 계산) +- [x] ModelVersion (버전 관리) +- [x] 재귀 BOM 구조 + +#### 영업 흐름 +- [x] Estimate (견적) - 기본 CRUD +- [x] EstimateItem (견적 라인) +- [x] Order (수주) - 5개 모델 +- [x] OrderItem, OrderHistory +- [x] OrderItemComponent + +#### 자재입고/수입검사 +- [x] MaterialReceipt (자재입고) +- [x] MaterialInspection (수입검사) +- [x] MaterialInspectionItem (검사 항목) + +#### 파일/로그 시스템 +- [x] FileService, FileStorageService +- [x] AuditLogger, AuditLogService +- [x] File 모델 (Polymorphic) + +### 🔄 백엔드 진행 중 (코어 MVP) + +#### 공정/생산 계획 +- [ ] Process Routing (공정 라우팅) +- [ ] Work Order (작업지시) +- [ ] Production Record (생산실적) + +#### 견적서 출력 +- [ ] 견적서 HTML 템플릿 +- [ ] PDF 생성 (DomPDF/Snappy) +- [ ] 견적서 미리보기 API + +### ⏳ 백엔드 예정 (1차 MVP) + +#### 품질/자재/단가/회계 +- [ ] 검사기준, 검사관리 +- [ ] 재고현황, 입고 관리 +- [ ] 단가 정책 로직 +- [ ] 회계 조회/수금 + +### ✅ 프론트엔드 완료 항목 + +#### MNG 패널 (Pure Blade + Tailwind) +- [x] 주요 관리 화면 구현 +- [x] Product, BOM, Material +- [x] Category, Role, Permission +- [x] Department, User, Tenant +- [x] Client, File 관리 + +### 🔄 프론트엔드 진행 중 + +#### React 사용자 포털 +- [ ] 공통 레이아웃 최종 정리 +- [ ] 견적/수주 화면 +- [ ] 생산/출하 화면 +- [ ] 기준정보 관리 UI + +--- + +## 11. 리스크 관리 + +### High Risk +| 리스크 | 영향도 | 완화 방안 | 담당 | +|--------|--------|-----------|------| +| 개발 일정 지연 | High | 주간 진행률 체크, 우선순위 조정 | PM | +| 디자인-개발 병목 | High | Frontend 버퍼 확보, ERP 병행 | Frontend | +| 단가 계산 로직 복잡도 | High | 전문가 리뷰, Week 1 집중 | Backend | + +### Medium Risk +| 리스크 | 영향도 | 완화 방안 | 담당 | +|--------|--------|-----------|------| +| 기획-개발 동기화 | Medium | 주간 싱크업, 스토리보드 우선 리뷰 | PM | +| 통합 테스트 시간 부족 | Medium | 자동화 테스트 확대 | QA | + +--- + +## 12. 핵심 성공 지표 (KPI) + +### 기술 지표 +- [ ] 코어 MVP API 엔드포인트 구현 +- [ ] Swagger 문서 100% 완성 (MVP 범위) +- [ ] 테스트 커버리지 60% 이상 +- [ ] API 평균 응답 속도 < 500ms +- [ ] Critical/High 버그 0건 + +### 품질 지표 +- [ ] Service-First 아키텍처 100% 준수 +- [ ] FormRequest 검증 100% 적용 +- [ ] BelongsToTenant 스코프 100% 적용 +- [ ] Pint 코드 포맷팅 100% 통과 + +### 비즈니스 지표 +- [ ] 베타 고객 2개사 확보 +- [ ] 정식 고객 확보 (런칭 후) +- [ ] 고객 만족도 4.0/5.0 이상 + +--- + +## 13. 담당자 및 연락처 + +| 역할 | 담당자 | 주요 업무 | 비고 | +|------|--------|----------|------| +| 프로젝트 관리 | - | 전체 일정 및 방향성 관리 | PM | +| 디자이너 | 재웅 정 | MES(경동기업) 기획 + 디자인 | 디자인 시스템 기준 | +| 기획자 | 이태화 | ERP/MES 스토리보드, 운영, QA | 기획 완료 시 MES 합류 | +| 백엔드 개발 | hso be | API/mng/인프라/정책 | 기술 총괄 | +| 프론트엔드 개발 | - | React 개발 | MES(경동) 우선 | +| QA | - | 테스트 | 단위/통합 테스트 | + +--- + +## 14. 작업 추적 및 관리 + +### 진행 상황 업데이트 +- **매일**: 각 저장소별 CURRENT_WORKS.md 업데이트 +- **매주**: 주차별 로드맵 진행률 체크 +- **매 2주**: 전체 로드맵 리뷰 및 조정 + +### 관련 문서 +- **개발 세부 계획**: `/claudedocs/SAM_DECEMBER_ROADMAP.md` +- **MES 프로젝트**: `/claudedocs/mes/MES_PROJECT_ROADMAP.md` +- **프로젝트 가이드**: `/CLAUDE.md` +- **빠른 참조**: `/SAM_QUICK_REFERENCE.md` + +--- + +## 15. 다음 단계 (1차 MVP 이후) + +### 1차 MVP 추가 기능 (별도 일정) +- 품질 관리 (검사기준/검사관리) +- 자재 관리 (재고현황/입고) +- 단가 관리 +- 회계 (판매조회/수금) + +### Phase 2: 프론트엔드 고도화 +- React Admin 패널 완전 재구축 +- 사용자 포털 (고객 견적 요청) +- 모바일 대응 +- 실시간 대시보드 + +### Phase 3: 고급 기능 +- 실시간 생산 모니터링 +- IoT 센서 연동 +- AI 기반 수요 예측 + +--- + +**작성**: Claude Code +**최종 업데이트**: 2025-12-02 +**다음 리뷰**: 2025-12-09 (주간 체크) \ No newline at end of file diff --git a/plans/SAM_ERP_Storyboard_D1.4.md b/plans/SAM_ERP_Storyboard_D1.4.md new file mode 100644 index 0000000..8b8f4d7 --- /dev/null +++ b/plans/SAM_ERP_Storyboard_D1.4.md @@ -0,0 +1,1150 @@ +# SAM ERP 스토리보드 D1.4 + +> **작성일**: 2026-01-16 +> **버전**: D1.4 +> **상태**: 프론트 작성 +> **문서 ID**: SAM_ERP +> **원본**: `SAM_ERP_Storyboard_D1.4_260116.pdf` (167페이지) + +--- + +## 1. 문서 이력 (Document History) + +| 날짜 | 버전 | 주요 내용 | 상세 내용 | +|------|------|----------|----------| +| 2025-12-01 | D0.6 | 프론트 초안 | PC ERP - 인사관리 & 전자결재 작성 | +| 2025-12-01 | D0.7 | 프론트 작성 | PC ERP - 인사관리 & 전자결재 피드백 반영 | +| 2025-12-16 | D0.8 | 프론트 작성 | PC ERP - 회계 & 보고서 작성. 목록화면 기간 설정 영역 추가, GPS 출퇴근 추가, 급여관리/상세 삭제, 회계관리 추가, 출퇴근관리 추가, 카드/계좌관리 및 보고서 추가 | +| 2025-12-18 | D1.0 | 프론트 작성 | PC ERP - 구독 & 고객센터 작성. 게시판 추가, 악성채권 추심관리 상세 추가, 팝업관리/게시판관리/알림설정 추가, 계정정보/회사정보/구독관리/결제내역/고객센터 추가 | +| 2025-12-22 | D1.1 | 프론트 작성 | 카드 내역 관리 수정 | +| 2025-12-31 | D1.2 | 프론트 작성 | 알림 소리 설정 추가, 접대비 현황 수정 | +| 2026-01-07 | D1.3 | 프론트 작성 | 보고서 정보를 대시보드로 이동, SAM AI 채팅 버튼 추가, 화면 추가 다수, 항목 설정 버튼 추가 | +| 2026-01-16 | D1.4 | 프론트 작성 | 오늘의 이슈/현황판 화면 수정, 현황판 영역 및 3번 추가, 계정과목명 변경 (p99,100,104,106,108,123) | + +--- + +## 2. 메뉴 구조 (Menu Structure) + +``` +SAM +├── 로그인 / 회원가입 +├── 대시보드 +├── MES +│ ├── 판매관리 +│ ├── 구매관리 +│ ├── 발주관리 +│ ├── 공사관리 +│ ├── 생산관리 +│ ├── 품질관리 +│ ├── 자재관리 +│ ├── 장비관리 +│ └── 차량관리 +├── ERP +│ ├── 인사관리 +│ │ ├── 부서관리 +│ │ ├── 사원관리 +│ │ ├── 근태관리 +│ │ └── 휴가관리 +│ ├── 전자결재 +│ │ ├── 기안함 +│ │ ├── 결재함 +│ │ └── 참조함 +│ ├── 게시판 +│ ├── 회계관리 +│ │ ├── 거래처관리 +│ │ ├── 매출관리 +│ │ ├── 매입관리 +│ │ ├── 입금관리 +│ │ ├── 출금관리 +│ │ ├── 어음관리 +│ │ ├── 거래처원장 +│ │ ├── 일일 일보 +│ │ ├── 지출 예상 내역서 +│ │ ├── 미수금 현황 +│ │ ├── 악성채권 추심관리 +│ │ ├── 입출금 계좌 조회 +│ │ └── 카드 내역 관리 +│ ├── 기준정보 +│ │ ├── 직급관리 +│ │ ├── 직책관리 +│ │ ├── 권한관리 +│ │ ├── 근무관리 +│ │ ├── 출퇴근관리 +│ │ ├── 휴가관리 +│ │ ├── 카드관리 +│ │ ├── 계좌관리 +│ │ ├── 팝업관리 +│ │ ├── 게시판관리 +│ │ └── 알림설정 +│ └── 보고서 및 분석 +├── 계정정보 +├── 회사정보 +├── 구독관리 +├── 결제내역 +└── 고객센터 + ├── 공지사항 + ├── 이벤트 + ├── FAQ + └── 1:1 문의 +``` + +--- + +## 3. 공통 요소 + +### 3.1 제스처/인터랙션 + +| Type | 설명 | 적용 | +|------|------|------| +| Tap | 일정영역을 사용자가 터치 | Yes | +| Touch & Hold | 화면을 터치한 후 계속 누르고 있는 상태 | No | +| Double Tap | 일정영역을 두 번 터치 | No | +| Drag & Drop | 터치 혹은 홀드 상태에서 오브젝트를 이동하여 원하는 위치에 배치 | Yes | +| Scroll Up/Down | 위/아래로 스크롤 | Yes | +| Swipe Left/Right | 좌/우로 스와이프 | Yes | +| Pinch Zoom in/out | 오브젝트 또는 화면을 확대/축소 | Yes | + +### 3.2 반응형 웹 브레이크 포인트 + +| 구분 | 크기 | +|------|------| +| 모바일 | < 640px (기본) | +| 태블릿 | 768px ~ 1023px (md) | +| 데스크탑 | 1024px+ (lg) | +| 대형 모니터 | 1280px+ (xl) | + +### 3.3 화면 템플릿 + +- **A**: Status bar - 안테나, 통화, 배터리 등 시스템 OS 관리 영역 +- **B**: Browser 영역 - 브라우저 기능 영역 +- **C**: Title 영역 - 텍스트 또는 기능 버튼, 기본 가운데 정렬 +- **D**: Content 영역 - 컨텐츠 내용 표시, 길어질 경우 스크롤 +- **E**: Browser bar 영역 - 브라우저 유틸 바 영역 +- **F**: Keypad 영역 - 키보드 입력할 때 활성화 + +### 3.4 메시지 유형 + +| Type | 설명 | +|------|------| +| 알림 Alert | 사용자에게 상황을 알려주기 위한 팝업 (확인 버튼) | +| 확인 Alert | 사용자에게 확인이 필요할 경우 제공 (취소/확인 버튼) | +| 토스트 메시지 | 단순 Notify, 2~3초 후 Fade out | + +### 3.5 셀렉트 박스 + +- **기본**: 클릭 시 하단에 종류 목록 표시, 목록 중 하나만 선택 +- **다중 선택**: 복수 선택 가능, 전체 선택/해제 토글, 첫번째 항목명 + 추가 수 표시 +- **검색**: 검색어 입력 후 엔터 또는 검색 아이콘 클릭 시 검색 결과 표시 +- **검색 & 다중 선택**: 검색 + 복수 선택 기능 결합 + +### 3.6 가이드 메시지 + +- 긍정일 경우: 녹색 +- 부정일 경우: 붉은색 +- 입력 필드 하단 또는 Alert에 표시 + +### 3.7 공지 팝업 + +- 대상: 전체 또는 설정 부서 +- 설정 기간동안 대상에게 팝업 표시 +- "1일간 이 창을 열지 않음" 체크박스 (자정 기준) + +--- + +## 4. GNB, LNB, 푸터 (p9) + +### 4.1 GNB (Global Navigation Bar) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 알림 버튼 | 클릭 시 알림 팝업 표시 | +| 2 | 개인 정보 버튼 | 디폴트 이미지, 이름, 직급 표시. 클릭 시 마이페이지 팝업 | +| 3 | 회사 로고 | 회사정보 화면에서 등록한 로고 표시, 회사 변경 시 해당 로고 변경 | +| 4 | 메뉴 영역 | 하위 메뉴 있을 경우 하단에 표시, 없을 경우 해당 화면으로 이동 | +| 5 | MES 메뉴 영역 | 영업관리, 판매관리, 구매관리 등 MES 메뉴 영역 | +| 6 | 푸터 영역 | 모든 화면 하단 공통 표시 | +| 7 | SAM AI 채팅 버튼 | 클릭 시 SAM AI 채팅 팝업 표시 | + +### 4.2 알림 팝업 (p10) + +- 각 디폴트 썸네일, 종류(공지사항, 안내), 제목/내용, 전송일시 표시 +- 클릭 시 해당 상세 화면으로 이동 +- 최신순 10개까지 표시 +- New 아이콘: 새 알림일 경우 표시, 클릭 시 사라짐 +- 붉은 점 아이콘: 새 알림이 있을 경우 표시, 모두 클릭 시 사라짐 + +### 4.3 마이페이지 팝업 (p11) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 계정 아이디 | 이메일 표시 | +| 2 | 회사 셀렉트 박스 | 해당 계정이 생성한 회사(테넌트) 목록 표시, 등록순 정렬, 한 회사만 소유 시 숨김 | +| 3 | 로그아웃 버튼 | "정말 로그아웃하시겠습니까?" 확인 Alert | + +--- + +## 5. 운영 (영업) + +### 5.1 가입 및 로그인 플로우 + +``` +영업사원 → 사업자등록번호 입력 → 조회 + ├── 미등록 → 회사정보 등록 → 가입 신청 완료 + └── 등록됨 → 알림 Alert + +관리자(매니저) → 승인/거절 + ├── 승인 → 이메일로 URL 발송 → 약관 동의 → 비밀번호 설정 → SAM 로그인 + └── 거절 → 거절 알림 +``` + +### 5.2 운영 로그인 (p17) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 아이디 인풋박스 | 테넌트 생성자: 이메일, 사용자: 이메일 또는 아이디 | +| 2 | 비밀번호 인풋박스 | 마지막 글자 제외 마스킹 처리 | +| 2-2 | 열람 버튼 | 열람/숨김 토글, 디폴트 숨김 | +| 3 | 자동 로그인 체크박스 | 체크 시 로그아웃 전까지 세션 유지 | +| 4 | 로그인 버튼 | 유효할 경우 사업자등록번호 조회 화면으로 이동 | + +**아이디 가이드 메시지:** + +| 상황 | 메시지 | +|------|--------| +| 필수 정보 미입력 | "필수 정보입니다." | +| 4글자 미만 | "이메일은 4자 이상 가능합니다." | +| 이메일 형식 유효하지 않음 | "이메일 주소를 다시 확인해주세요." | + +**비밀번호 가이드 메시지:** + +| 상황 | 메시지 | +|------|--------| +| 필수 정보 미입력 | "필수 정보입니다." | +| 8자 미만 | "8자 이상으로 만들어주세요." | +| 영문+숫자+특수문자 조합 아님 | "영문, 숫자, 특수문자를 모두 조합하여 구성해주세요. 단, `' ; -- < ( ) \ /` 보안상 사용 불가" | + +### 5.3 사업자등록번호 조회 (p18) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 제조 데모 | 클릭 시 제조 데모 화면으로 이동 | +| 2 | 시공 데모 | 클릭 시 시공 데모 화면으로 이동 | +| 3 | 사업자등록번호 인풋박스 | 숫자만 가능, 10자리 | +| 4 | 다음 버튼 | 바로빌 조회 후: 휴폐업 시 알림, 사용가능+등록됨 시 알림, 사용가능+미등록 시 회사정보 등록 이동 | + +### 5.4 회사정보 등록 (p19) + +**회사(테넌트) 상태:** + +| 상태 | 설명 | +|------|------| +| 신청 | 신청 완료 상태 | +| 승인 | 계약 완료 및 계약금 50% 입금, 이메일로 URL 발송, 최초 로그인 시 ERP만 표시 | +| 거절 | 영업사원이 직접 거절 내용 전달 | +| 운영 | 프로그램 설정 완료, 잔금 50% 입금 및 인도, 당월 말일까지 무료, 익월부터 구독료 청구 | +| 만료 | 기간 종료, 종료일~3일동안 연장 결제 없음, 영업사원에게 알림, 서비스에 경고 배너 | +| 해지 대기 | 90일 대기 단계 | +| 해지 | 서비스 해지, 복구 불가 | +| 제재 | 서비스 이용 불가 | +| 탈퇴 | 로그인 불가, 복구 불가 | + +**등록 필드:** +- 회사 로고 (750x250px, 10MB 이하 PNG/JPEG/GIF) +- 회사명, 대표자명, 업태, 업종 +- 주소 (우편번호 찾기) +- 이메일(아이디), 세금계산서 이메일 +- 담당자명, 담당자 연락처 +- 사업자등록증 (파일 첨부) + +### 5.5 가입 신청 완료 (p20) + +- 가입 신청 완료 안내 문구 표시 +- 가입 신청 취소 버튼: "가입 신청 취소 시 등록한 모든 정보가 삭제됩니다." 확인 Alert + +### 5.6 가입 신청 승인 이메일 (p21) + +- 계정 활성화 버튼: 약관 동의 화면으로 이동 +- 지원, 블로그 버튼: 운영 노션 링크로 이동 + +### 5.7 약관 동의 (p22) + +- 필수 약관: 서비스 이용약관, 개인정보 취급방침, 기타 약관 +- 선택 약관: 마케팅 정보 수신 동의 (이메일, SMS) +- "약관에 동의합니다" 버튼: 모든 필수 약관 동의 시 활성화 → 비밀번호 설정 화면 이동 +- "전체 약관에 동의합니다" 버튼: 모든 필수+선택 약관 동의 처리 → 비밀번호 설정 화면 이동 + +### 5.8 비밀번호 설정 (p23) + +- 최소 8자 이상 영문+숫자+특수문자 조합 +- 비밀번호 확인 +- 계정 활성화 버튼: 로그인 화면으로 이동 + +--- + +## 6. GPS 출퇴근 + +### 6.1 출퇴근하기 (p25) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 출퇴근 버튼 | GPS 출퇴근 사용 시에만 표시, 모바일일 경우에만 활성화 | +| 2 | 출퇴근 허용 반경 | 기준 좌표로부터의 허용 반경을 원형으로 표시 | +| 3 | 현재 위치 버튼 | 현재 위치를 지도 중심으로 표시 | +| 4-6 | 지도 컨트롤 | 확대(+), 축소(-), 슬라이드바 | +| 7 | 개인 정보 영역 | 프로필 이미지, 이름, 부서명, 직급명 | +| 8 | 현재 시각 | HH:MM:SS | +| 9 | 출근하기 버튼 | 위치 미설정 시 알림, 반경 초과 시 알림, 반경 이내 시 출근 기록 저장 | + +### 6.2 출근/퇴근 완료 (p26-27) + +- 출근/퇴근 완료 아이콘 이미지 표시 +- 완료 정보: 시:분:초, 일자(요일) +- 출근/퇴근 좌표의 본사/현장명 표시 +- 확인 버튼: 대시보드로 이동 + +### 6.3 현장등록 - 위치 정보 설정 (p28) + +- 위도/경도 입력 +- 주소 또는 경위도 값으로 설정 +- 각 현장의 GPS 중심값으로 설정 + +--- + +## 7. 대시보드 + +### 7.1 로그인 (p30) + +- 운영 로그인과 동일 구조 +- 로그인 버튼 클릭 시 대시보드 화면으로 이동 + +### 7.2 대시보드 메인 (p31-36) + +#### 7.2.1 오늘의 이슈 (p31) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 항목 설정 버튼 | 항목 설정_대시보드 팝업 표시 | +| 2 | 오늘의 이슈 영역 | 당일 이슈 발생 시 알림, 즉시 승인/보류 처리 가능 | +| 3 | 필터 셀렉트 박스 | 전체, 수주 성공, 추심 이슈, 적정 재고, 결재 요청, 세금 신고, 신규 업체 등록, 근태, 발주 완료 | +| 4 | 이슈 목록 | 클릭 시 해당 상세 화면으로 이동, 화면 가로 길이에 따라 4/3/2/1열 표시 | +| 5 | 승인/반려 버튼 | 해당 건에 대해 즉시 승인/반려 처리 | +| 6 | 일일 일보 정보 | 현금성 자산 합계, 외국환(USD) 합계, 입금 합계, 출금 합계 | +| 7 | AI 리포트 | 핵심 키워드 강조 표시 (빨간색: 경고, 주황: 주의, 녹색: 긍정, 파랑: 양호) | + +**이슈 케이스:** +- 신규 업체 등록 +- 결근 등 근태 이벤트 +- 재고 미달 알림 +- 채권 추심 등록, 상태 변경 +- 발주, 수주 등록 +- 지출결의서 등 전자결재 상신 +- 세금 신고 알림 + +#### 7.2.2 현황판 (p32) + +- 수주, 채권 추심, 안전 재고, 세금 신고, 신규 업체 등록, 연차, 발주, 결재 요청 +- 경고 상태일 경우 해당 영역에 색상 하이라이트 +- 클릭 시 해당 상세 화면으로 이동 + +#### 7.2.3 당월 예상 지출 내역 (p32-33) + +- 매입, 카드, 발행어음, 총 예상 지출 합계 (전월 대비 %) +- AI 분석 메시지 (예상 지출 증감 원인 분석) + +#### 7.2.4 카드/가지급금 관리 (p33) + +**가지급금 정의:** +- 법인카드(지출결의서) 미정리 +- 접대비 불인정 +- 증빙미비 +- 업무관련성 소명 불가 (주말/심야 카드 사용, 불인정 가맹점) +- 대표자 개인 대여 +- 가지급금 인정이자 4.6% + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 매입 정보 | 클릭 시 당월 매입 상세 팝업 | +| 2 | 카드 정보 | 클릭 시 당월 카드 상세 팝업 | +| 3 | 발행어음 정보 | 클릭 시 당월 발행어음 상세 팝업 | +| 4 | 총 예상 지출 합계 | 클릭 시 당월 지출 예상 상세 팝업 | +| 5 | 가지급금 | 클릭 시 가지급금 상세 팝업 | +| 6 | 법인세 예상 가중 | 클릭 시 법인세 예상 가중 상세 팝업 | +| 7 | 대표자 종합세 예상 가중 | 클릭 시 대표자 종합소득세 예상 가중 상세 팝업 | + +#### 7.2.5 접대비 현황 (p33-34) + +- 매출, 접대비 총 한도, 접대비 잔여한도, 접대비 사용금액 +- AI 분석 메시지 (한도 대비 사용률, 초과 경고, 거래처 정보 누락 등) + +#### 7.2.6 복리후생비 현황 (p34) + +- 당해년도 한도, 기간별 한도/잔여/사용금액 +- AI 분석 (1인당 월 복리후생비, 식대 비과세 한도 초과 등) + +#### 7.2.7 미수금 현황 (p34) + +- 누적 미수금, 당월 미수금 +- 미수금 상위 회사 1, 2위 표시 +- AI 분석 (장기 미수금 경고, 리스크 분산 필요 등) + +#### 7.2.8 채권추심 현황 (p35) + +- 누적 악성채권, 추심중, 법적조치, 회수완료 +- 세금계산서 미발행 건수 +- AI 분석 (지급명령 신청 상태, 대손 처리 검토 등) + +#### 7.2.9 부가세 현황 (p35-36) + +- 매출세액, 매입세액, 예상 납부세액 +- AI 분석 (예상 환급세액/납부세액, 전기 대비 증감 분석) + +#### 7.2.10 캘린더 (p36) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 이번주 + 좌우 화살표 | 이전월/다음월 스케줄 표시 | +| 2 | 캘린더 탭 | 주, 월 (디폴트: 월) | +| 3 | 부서 필터 | 전체, 부서, 개인 | +| 4 | 업무 필터 (다중선택) | 전체, 일정, 발주, 시공, 수주 성공, 추심 이슈 등 | +| 5 | 일정 영역 | [부서/이름] 제목 형태, 클릭 시 상세 이동 | +| 5-1 | 이슈 영역 | [구분] 제목 형태, 클릭 시 상세 이동 | +| 6 | 일자 영역 | 당일 외곽선 하이라이트, 지난 일자 색상 구분 | +| 7 | +N 버튼 | 해당 일자에 스케줄 2건 초과 시 초과건 숫자 표시 | +| 8 | 일정 목록 영역 | 선택된 일자의 일정 목록 | +| 9 | 일정 등록 버튼 | 일정 상세 팝업 표시 | + +### 7.3 일정 상세 팝업 (p37) + +- 부서 셀렉트 박스 (검색) +- 기간 영역: 기간 설정 달력 팝업 +- 시간 체크박스: 미설정 시 종일, 설정 시 시간 범위 활성화 +- 색상 선택 + +### 7.4 항목 설정_대시보드 팝업 (p38-39) + +**ON/OFF 설정 항목:** +- 오늘의 이슈: 수주, 채권 추심, 안전 재고, 세금 신고, 신규 업체 등록, 연차, 지각, 결근, 발주, 결재 요청 +- 현황판 (오늘의 이슈 항목 정보와 연동) +- 당월 예상 지출 내역, 카드/가지급금 관리, 일일 일보 +- 접대비 현황, 복리후생비 현황, 미수금 현황, 미수금 상위 회사 현황 +- 채권추심 현황, 부가세 현황, 캘린더 + +**접대비 한도 관리:** +- 기간 구분: 연간, 반기, 분기, 월 (총 한도를 분할 계산) +- 기업 구분: 일반법인, 중소기업 + +**복리후생비 한도 관리:** +- 계산 방식: 직원당 정액 금액 방식 / 연봉 총액 X 비율 방식 + +**중소기업 판단 기준표:** + +| 조건 | 기준 | 충족 요건 | +|------|------|----------| +| 매출액 | 업종별 상이 | 업종별 기준 금액 이하 | +| 자산총액 | 5,000억원 | 미만 | +| 독립성 | 소유/경영 | 대기업 계열 아님 | + +**접대비 기본한도:** + +| 판정 | 조건 | 접대비 기본한도 | +|------|------|---------------| +| 중소기업 | 3가지 모두 충족 | 3,600만원 | +| 일반법인 | 하나라도 미충족 | 1,200만원 | + +### 7.5 당월 매입 상세 팝업 (p40) + +- 자재 유형별 구매 비율 차트 (원자재/부자재/포장재) +- 월별 매입 추이 차트 +- 일별 매입 내역 테이블: 매입일, 거래처, 매입금액, 매입유형 +- 필터: 매입유형 (원재료매입, 부재료매입, 상품매입, 외주가공비, 소모품비 등) +- 정렬: 최신순, 등록순, 금액순 + +### 7.6 당월 카드 상세 팝업 (p41) + +- 사용자별 카드 사용 비율 차트 +- 월별 카드 사용 추이 차트 +- 일별 카드 사용 내역: 카드명, 사용자, 사용일시, 가맹점명, 사용금액, 사용유형 +- 미정리 건수 표시 + +### 7.7 당월 발행어음 상세 팝업 (p42) + +- 월별 발행어음 추이 차트 +- 당월 거래처별 발행어음 차트 +- 상태: 보관중, 만기임박(만기일 7일 전), 만기 경과, 결제완료, 부도 + +### 7.8 당월 지출 예상 상세 팝업 (p43) + +- 당월 지출 예상 금액, 전월 대비, 총 계좌 잔액 +- 당월 지출 승인 내역서: 예상 지급일, 항목, 지출금액, 거래처, 계좌 +- 지출 합계, 계좌 잔액, 최종 차액 + +### 7.9 가지급금 상세 팝업 (p44) + +- 가지급금, 인정이자 4.6%, 미설정 건수 +- 내역: 발생일시, 대상, 구분(카드/계좌), 금액, 상태, 내용 +- AI 분류 기준: 미정리, 불인정 가맹점, 접대비 불인정, 주말/심야 카드 사용 + +### 7.10 법인세 예상 가중 상세 팝업 (p45) + +**법인세 과세표준 (2024년 기준):** + +| 과세표준 | 세율 | 누진공제 | +|---------|------|---------| +| 2억원 이하 | 9% | - | +| 2억 초과 ~ 200억 이하 | 19% | 2,000만원 | +| 200억 초과 ~ 3,000억 이하 | 21% | 42,000만원 | +| 3,000억 초과 | 24% | 942,000만원 | + +- 접대비 초과 금액 + 가지급금 인정이자 반영/미반영 비교 +- 과세표준 계산: 당기순이익 + 손금불산입 - 손금산입 + +### 7.11 대표자 종합소득세 예상 가중 상세 팝업 (p46) + +**종합소득세 과세표준 (2024년 기준):** + +| 과세표준 | 세율 | 누진공제 | +|---------|------|---------| +| 1,400만원 이하 | 6% | - | +| 1,400만 초과 ~ 5,000만 이하 | 15% | 126만원 | +| 5,000만 초과 ~ 8,800만 이하 | 24% | 576만원 | +| 8,800만 초과 ~ 1.5억 이하 | 35% | 1,544만원 | +| 1.5억 초과 ~ 3억 이하 | 38% | 1,994만원 | +| 3억 초과 ~ 5억 이하 | 40% | 2,594만원 | +| 5억 초과 ~ 10억 이하 | 42% | 3,594만원 | +| 10억 초과 | 45% | 6,594만원 | + +- 인정이자가 상여로 처리, 종합소득세/지방소득세/4대보험 차액 표시 + +### 7.12 당해 매출 상세 팝업 (p47) + +- 월별 매출 추이 차트, 당해년도 거래처별 매출 차트 +- 매출유형: 제품 매출, 상품 매출, 부품 매출, 용역 매출, 공사 매출, 임대 수익, 기타 매출 + +### 7.13 접대비 상세 팝업 (p48-49) + +**접대비 손금한도 계산:** + +| 법인 유형 | 연간 기본한도 | 월 환산 | +|----------|-------------|--------| +| 일반법인 | 12,000,000원 | 1,000,000원 | +| 중소기업 | 36,000,000원 | 3,000,000원 | + +**수입금액별 추가한도:** + +| 수입금액 구간 | 추가한도 계산식 | +|-------------|--------------| +| 100억원 이하 | 수입금액 x 0.2% | +| 100억 초과 ~ 500억 이하 | 2,000만원 + (수입금액 - 100억) x 0.1% | +| 500억원 초과 | 6,000만원 + (수입금액 - 500억) x 0.03% | + +### 7.14 복리후생비 상세 팝업 (p50-51) + +- 항목별 사용 비율 차트 (식대, 건강검진 등) +- 계산 방식: 직원당 정액 금액 / 연봉 총액 비율 + +**법정 외 복리후생비 예시:** + +| 항목 | 금액(원) | 비고 | +|------|---------|------| +| 식대 (비과세) | 200,000 | 1인당 월 20만원 | +| 교통비/차량유지비 | 100,000 | 1인당 월 10만원 | +| 경조사비 | 50,000 | 1인당 월 5만원 적립 | +| 건강검진비 | 30,000 | 연 1회 기준 월 환산 | +| 교육훈련비 | 80,000 | 1인당 월 8만원 | +| 복지포인트/기타 | 100,000 | 1인당 월 10만원 | + +### 7.15 예상 납부세액 상세 팝업 (p52) + +- 매출세액, 매입세액, 경감/공제세액 +- 세금계산서 미발행/미수취 내역 + +### 7.16 가지급금 인정이자 계산 (p54) + +**계산 공식 (법인세법 기준):** +- 경과일수 = 정산일 - 지급일 +- 일이자율 = 연이자율 / 365 +- 인정이자 = 가지급금 x 일이자율 x 경과일수 +- 정산차액 = 가지급금 총액 - 실사용 총액 + +**계산 예시 (2024년 기준, 인정이자율 4.6%):** + +| 항목 | 금액 | 계산식 | +|------|------|--------| +| 가지급금 잔액 | 15,200,000원 | - | +| 인정이자 | 699,200원 | 잔액 x 0.046 | +| 법인세 추가 (19%) | 132,848원 | 인정이자 x 0.19 | +| 대표자 소득세 추가 (35%) | 244,720원 | 인정이자 x 0.35 | +| 대표자 지방소득세 (10%) | 24,472원 | - | +| 총 세금 부담 | 402,040원 | - | + +--- + +## 8. 인사관리 + +### 8.1 부서관리 (p57-58) + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 전체 선택 체크박스 | 전체 선택/해제 토글 | +| 3 | 추가 버튼 | 선택한 부서의 하위 부서 일괄 생성 (관리 권한 필요) | +| 4 | 삭제 버튼 | 삭제된 부서의 인원은 회사(기본) 인원으로 변경 | +| 5/6 | 축소/확대 버튼 | 하위 부서 숨김/표시 토글 | +| 7 | 추가 버튼 | 부서 추가 팝업 표시 | +| 8 | 수정 버튼 | 부서 수정 팝업 표시 | +| 9 | 삭제 버튼 | 개별 부서 삭제 | + +### 8.2 사원관리 (p59) + +**상단 정보:** +- 재직 인원, 휴직 인원, 퇴직 인원, 평균근속년수 + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 기간 설정 | 입사일 기준, 당해년도/전전월/전월/당월/어제/오늘 | +| 2 | CSV 일괄 등록 | CSV 일괄 등록 화면으로 이동 | +| 3 | 사원 등록 | 사원 상세 화면으로 이동 | +| 4 | 사용자 초대 | 사용자 초대 팝업 표시 | +| 5 | 필터 | 전체, 사용자 아이디 보유/미보유, 재직, 휴직, 퇴직 | +| 6 | 정렬 | 직급순, 입사일순, 부서순, 이름순 | + +**목록 항목:** 사원코드, 부서, 직책, 이름, 직급, 휴대폰, 이메일, 입사일, 상태, 사용자 아이디, 권한 + +### 8.3 사원 상세 (p60-63) + +**사원 정보 (필수):** +- 주민등록번호, 이름, 휴대폰, 이메일 +- 급여계좌 (은행, 계좌, 예금주), 연봉 + +**사용자 정보 (필수):** +- 아이디 (이메일 또는 아이디), 비밀번호 +- 권한 (권한관리 목록), 상태 (정상, 제재, 중지) + +**사원 상세 (선택 - 항목 설정으로 관리):** +- 프로필 사진, 사원코드, 성별, 주소 + +**인사 정보 (선택):** +- 고용 형태: 정규직, 계약직, 파견직, 용역직, 시간제 근로자 +- 직급: 사원, 대리, 과장, 차장, 부장, 이사, 상무, 전무, 부사장, 사장, 회장 +- 상태: 재직, 병가휴직, 육아휴직, 개인사정휴직, 무급휴직, 퇴사, 해고, 권고사직, 계약만료, 정년퇴직 +- 부서 (검색), 직책 +- 출근 위치, 퇴근 위치 (본사, 현장 목록 중 선택) +- 퇴사일, 퇴사 사유 + +### 8.4 사용자 초대 팝업 (p64-65) + +**초대 프로세스:** +1. 초대 이메일 발송 +2. 약관 동의 (아이디를 이메일로 사용) +3. 비밀번호 설정 +4. 로그인 + +- 이메일 주소 기준 사원 정보가 있을 경우 매핑하여 사용자 등록 +- 사용자 아이디는 다른 테넌트와 중복 가능 + +### 8.5 CSV 일괄 등록 (p66-67) + +- 양식 다운로드 → 파일 선택 (CSV 50MB 이하) → 파일 변환 → 정보 등록 영역에 표시 → 체크 항목 등록 + +### 8.6 근태관리 (p68-69) + +- 관리 권한이 있으면 모든 사원 편집 가능, 없으면 본인만 +- 근태관리 자동 설정 시: 모든 사원 정시 출퇴근 기록, 예외사항만 작성 + +**상단 정보:** 정시 출근, 지각, 결근, 휴가 + +**근태 정보 팝업:** +- 사원 (검색 & 다중 선택), 기준일 (다중 선택 가능) +- 출근/퇴근 시간, 야간 연장 시간, 주말 연장 시간 + +### 8.7 휴가관리 (p70-73) + +**탭:** 휴가 사용 현황, 휴가 부여 현황, 휴가 신청 현황 + +**상단 정보:** 휴가 승인 대기, 연차 인원, 경조사 인원, 연간 연차 사용률 + +**휴가 유형:** 연차, 보상, 경조, 보건, 병가, 반차, 회수(차감) + +**휴가 신청:** +- 잔여 일시 >= 신청 일시: 휴가 신청 완료 +- 잔여 일시 < 신청 일시: "휴가 잔여 일시를 초과했습니다." 알림 + +--- + +## 9. 전자결재 + +### 9.1 기안함 (p75) + +**문서 상태:** +- 임시저장: 문서 작성 중 임시저장 +- 진행: 상신 및 결재자 중 일부 승인 +- 완료: 모든 승인 완료 +- 반려: 결재자 중 한 명이 반려 + +| 번호 | 요소 | 설명 | +|------|------|------| +| 1 | 문서 작성 | 문서 작성 화면으로 이동 | +| 2 | 상신 버튼 | 임시저장 상태만 상신 가능 | +| 3 | 삭제 버튼 | 임시저장 상태만 삭제 가능 | + +### 9.2 문서 작성 (p76-81) + +**문서 유형:** + +#### 9.2.1 품의서 (p76-77) + +- 기본 정보: 작성일, 기안자, 문서유형, 문서번호 +- 결재선: 부서/직책/이름 (검색 & 다중 선택) +- 참조: 부서/직책/이름 (검색 & 다중 선택) +- 품의서 정보: 구매처, 구매처 결제일, 제목, 품의 내역, 품의 사유, 예상 비용 +- 녹음 버튼: 음성 인식 → 텍스트 변환 → 인풋박스에 표시 +- 참고 이미지 첨부 + +#### 9.2.2 지출결의서 (p78-79) + +- 기본 정보: 품의서와 동일 +- 지출 정보: 결제일, 지출 요청일 +- 결제 정보: 카드 (등록된 카드 목록), 총 비용 +- 지출결의서 정보: 적요, 금액, 비고 (행 추가 가능) +- 참고 이미지 첨부 + +#### 9.2.3 지출 예상 내역서 (p80-81) + +- 기본 정보: 품의서와 동일 +- 지출 예상 내역서 정보: 제목 +- 목록: 예상 지급일, 항목, 지출금액, 거래처, 계좌 +- 월별 소계, 지출 합계, 계좌 잔액, 최종 차액 + +### 9.3 결재함 (p82) + +**상태:** +- 결재요청: 결재 요청을 받은 상태 +- 예정: 결재 순번에 의한 대기 +- 완료: 승인 완료 +- 반려: 반려 완료 + +### 9.4 문서 상세 팝업 (p83-85) + +**공통 기능:** 복제(새글), 수정(결재선 누구나 가능), 반려/승인(결재선만), 공유(PDF/이메일/팩스/카카오톡), 인쇄 +- 품의서: 구매처 정보, 품의 내역/사유, 예상 비용 +- 지출결의서: 지출 요청일/결제일, 적요/금액/비고, 법인카드, 총 비용 +- 지출예상내역서: 예상 지급일별 항목/지출금액/거래처/계좌 + +### 9.5 참조함 (p86) + +- 열람/미열람 상태 관리 +- 열람 버튼: 일괄 열람 처리 +- 미열람 버튼: 일괄 미열람 처리 + +--- + +## 10. 게시판 + +### 10.1 게시판 목록 (p88) + +- 게시판 탭: 공지사항, 게시판명, ..., 나의 게시글 +- 기준정보 > 게시판관리에서 설정한 게시판 목록 +- 대상(전사, 부서, 팀)에 따라 소속에 맞는 게시판만 표시 +- 게시글: 번호(상단 노출 아이콘 또는 번호), 제목, 작성자, 등록일, 조회수 + +### 10.2 게시글 상세 (p89-91) + +**등록:** +- 게시판 선택, 상단 노출 (최대 5개, 최신순), 댓글 사용/미사용 +- 제목, 내용, 첨부파일 + +**조회:** +- 본인 작성글만 수정/삭제 버튼 표시 +- 댓글 등록/수정/삭제 (본인 댓글만) + +--- + +## 11. 회계관리 + +### 11.1 회계 관리 플로우 + +``` +매출 흐름: + 거래처 선택 → 매출 등록 → 세금계산서 발행 → 입금 등록 + ├── 전액 입금? → 거래처원장 + └── 미입금 → 미수금 현황 → 연체? → 악성 추심 + +매입 흐름: + 거래처 선택 → 매입 등록 → 세금계산서 수취 → 출금 등록 + ├── 전액 출금? → 거래처원장 + └── 미출금 → 미지급 알림 +``` + +### 11.2 거래처관리 (p94-97) + +**목록 필터:** +- 구분: 전체, 매출, 매입, 매입매출 +- 신용등급: AAA ~ D +- 거래등급: A(우수), B(양호), C(보통), D(주의), E(위험) +- 악성채권: 전체, 악성채권, 정상 + +**거래처 상세:** +- 기본 정보: 거래처명, 거래처 코드, 사업자등록번호, 대표자명, 거래처 유형, 업태, 업종, 주소 +- 연락처: 전화번호, 모바일, 팩스, 이메일 +- 담당자 정보: 시스템 관리자, 담당자명, 담당자 전화 +- 회사 정보: 회사 로고 +- 결제일: 매입 결제일(1~31일/말일), 매출 결제일(1~31일/말일) +- 추가 정보: 신용등급, 거래등급, 세금계산서 이메일, 입금계좌 +- 미수금 표시 (읽기 전용) +- 연체 토글 (ON/OFF, 연체일수 표시) +- 미지급 표시 (읽기 전용) +- 악성채권 토글 (ON/OFF) +- 메모 (일시, 작성자, 내용) + +### 11.3 매출관리 (p99-102) + +**매출 등록:** +- 수주 확정 시 자동 등록 (삭제 불가) +- 별도 매출 시 직접 등록 (삭제 가능) + +**매출유형:** 미설정, 제품 매출, 상품 매출, 부품 매출, 용역 매출, 공사 매출, 임대 수익, 기타 매출 + +**매출 상세:** +- 기본 정보: 거래처명, 매출일, 매출번호, 매출유형 +- 품목 정보: 품목명, 수량, 단가, 공급가액, 부가세, 합계, 적요 +- 세금계산서: 발행 토글 (미발행/발행완료) +- 거래명세서: 발행 토글, 조회 버튼, 발행하기 버튼 (거래처 이메일로 자동 발송) + +### 11.4 매입/출금 플로우 (p103) + +``` +직원: 품의서 작성 → 전자결재 상신 → 승인? + ├── 승인 → 지출예상내역서 → 지급일 가능? + │ ├── Yes → 지출결의서 작성 → 전자결재 상신 → 승인? + │ │ ├── 승인 → 매입 자동 등록 → 출금 상세 등록 + │ │ └── 반려 + │ └── No → 예상 지급일 수정 + └── 반려 +``` + +### 11.5 매입관리 (p104-105) + +**매입 등록:** 지출예상내역서 승인 완료 시 자동 등록 (삭제 불가) + +**매입유형:** 미설정, 원재료매입, 부재료매입, 상품매입, 외주가공비, 소모품비, 수선비, 운반비, 사무용품비, 임차료, 수도광열비, 통신비, 차량유지비, 접대비, 보험료, 기타용역비 + +**매입 상세:** +- 근거 문서(품의서/지출결의서), 예상 비용 표시 +- 매입번호: 문서번호 + 넘버링 조합 +- 출금계좌, 거래처, 매입유형 +- 세금계산서 수취 토글 + +### 11.6 입금관리 (p106-107) + +- 기준정보 > 계좌관리에 등록된 계좌의 자동 입금 내역 수집 +- 바로빌 API 연동 시 실시간 조회 + +**입금유형:** 미설정, 매출대금, 선수금, 가수금, 임대수익, 이자수익, 보증금 반환, 차입금, 자본금, 부가세 환급, 기타 + +### 11.7 출금관리 (p108-109) + +- 기준정보 > 계좌관리에 등록된 계좌의 자동 출금 내역 수집 + +**출금유형:** 미설정, 매입대금, 선급금, 가지급금, 임대료, 이자비용, 보증금 지급, 차입금 상환, 배당금 지급, 부가세 납부, 급여, 4대보험, 세금, 공과금, 경비, 기타 + +### 11.8 어음관리 (p110-111) + +**구분:** 수취, 발행 + +**발행 어음 상태:** 보관중, 만기임박(만기일 7일 전), 만기 경과, 결제완료, 부도 +**수취 어음 상태:** 보관중, 만기임박(만기일 7일 전), 추심의뢰, 추심완료, 추심중, 부도 + +**수취 어음:** +- 거래처원장 상세, 일일 일보, 미수금 현황에 반영 +- 미수금에 대한 약정으로만 표시 +- 추심완료되어 입금 시에만 회계에 반영 + +**발행 어음:** +- 지출예상내역서에 반영 +- 지출에 대한 약정으로만 표시 +- 결제완료되어 출금 시에만 회계에 반영 + +**차수 관리:** 총 금액에 대한 차수로 상환 계획 작성 + +### 11.9 거래처원장 (p112-113) + +- 거래처별 기간별 합계 금액 표시 +- 목록: 거래처명, 이월잔액, 매출, 수금, 잔액, 결제일 + +**거래처원장 상세:** +- 이월잔액, 수취 어음 정보, 거래명세서 정보 +- 하위 전체 품목별 판매금액 표시 +- 세금계산서 미발행 시 붉은색 하이라이트 +- 누계 금액 표시 + +### 11.10 일일 일보 (p114) + +- 어음 및 외상매출채권 현황: 수취어음 거래처명, 금액, 발행일, 만기일 +- 현금성 자산: 계좌별 전월 이월, 수입, 지출, 잔액 +- 외국환(USD) 합계, 현금성 자산 합계 + +### 11.11 지출 예상 내역서 (p115-116) + +- 카드 및 승인/반려 확정 목록은 삭제 불가 +- 예상 지급일: 매입 거래처 등록 시 자동 입력 +- 품의서/지출결의서/발행어음 목록 (클릭 시 상세 이동) +- 거래처 월 지출 목록 (클릭 시 거래처원장 상세 이동) +- 전자결재 버튼: 문서 작성_지출 예상 내역서 화면으로 이동 +- 예상 지급일 변경 팝업 + +### 11.12 미수금 현황 (p117) + +- 거래처별 월별 미수금 현황 (매출/입금/어음/누적 미수금) +- 메모 저장 기능 +- 연체 토글 (거래처 상세와 연동) +- 확대/축소 토글 + +### 11.13 악성채권 추심관리 (p118-121) + +**상태:** 추심중, 법적조치, 회수완료, 대손처리 + +**상세:** +- 기본 정보: 거래처 기본 정보 표시 +- 악성채권 등록 ON/OFF +- 담당자 정보, 연락처 정보 +- 필요 서류: 사업자등록증, 세금계산서, 추가 서류 (파일 첨부) +- 악성 채권 정보: 미수금, 상태, 악성채권 발생일/종료일, 연체일수, 본사 담당자, 메모 +- 수취 어음 현황 (어음관리 화면으로 이동) +- 거래처 미수금 현황 (미수금 현황 화면으로 이동) + +### 11.14 입출금 계좌 조회 (p122) + +- 기준정보 > 계좌관리에 등록된 계좌의 자동 입출금 내역 수집 +- 바로빌 API 연동 시 실시간 조회 +- 목록: 은행명, 계좌명, 거래일시, 구분, 적요, 거래처, 입금자/수취인, 입금, 출금, 잔액, 입출금 유형 + +### 11.15 카드 내역 관리 (p123-124) + +- 기준정보 > 카드관리에 등록된 카드의 자동 사용 내역 수집 +- 사용자는 본인 내역 조회 및 사용유형/적요 작성 가능 + +**사용유형:** 미설정, 복리후생비, 접대비, 여비교통비, 차량유지비, 소모품비, 운반비, 통신비, 도서인쇄비, 교육훈련비, 보험료, 광고선전비, 회비, 지급수수료, 세금과공과, 수선비, 임차료, 잡비 + +--- + +## 12. 기준정보 + +### 12.1 직급관리 (p126) + +- 디폴트: 사원, 대리, 과장, 차장, 부장, 이사, 상무, 전무, 부사장, 사장, 회장 +- 추가, 순서 변경 (드래그 & 드랍), 수정, 삭제 +- 사원 설정된 직급은 모두 변경 후 삭제 가능 + +### 12.2 직책관리 (p127) + +- 디폴트: 없음(기본), 팀장, 파트장, 실장, 부서장, 본부장, 센터장, 매니저, 리더 +- 추가, 순서 변경, 수정, 삭제 + +### 12.3 권한관리 (p129-130) + +- 권한 등록/삭제 +- 권한 상세: 권한명, 상태(공개/숨김) +- 메뉴별 권한 설정: 조회, 생성, 수정, 삭제, 승인, 내보내기, 관리 + +### 12.4 근무관리 (p131) + +- 고용 형태: 정규직, 계약직, 파견직, 용역직, 시간제 근로자 +- 주간 근무일: 월~일 체크박스 +- 출근/퇴근 시간 설정 +- 법정 주당 기준 근로시간 (40시간), 주당 연장 근로시간 (12시간) +- 휴게 시작/종료 시간 설정 + +### 12.5 출퇴근관리 (p132) + +**GPS 출퇴근:** +- 사용/미사용 설정 +- 연동 부서 (검색 & 다중 선택) +- 출퇴근 허용 반경: 50M, 100M, 300M, 500M + +**자동 출퇴근:** +- 사용/미사용 설정 +- 연동 부서 + +### 12.6 휴가관리 (p133) + +- 기준: 회계연도 / 입사일 +- 기준일: 월/일 설정 (회계연도 선택 시) + +**기본 연차 설정:** +- 1년간 출근율 80% 이상: 15일 +- 3년 이상 근속 시 2년에 1일 추가 (최대 25일) +- 1년 미만 또는 출근율 80% 미만: 1개월 개근 시 1일씩 (최대 11일) + +### 12.7 카드관리 (p134-135) + +- 카드사 코드, 카드 인증 정보, 비밀번호를 바로빌 API에 전달하여 자동 수집 +- 카드 상세: 카드번호, 카드사, 카드명, 카드 비밀번호 앞 2자리, 유효기간 +- 사용자 정보: 부서/이름/직책 +- 상태: 사용, 정지 (정지 시 자동 조회 중단) + +### 12.8 계좌관리 (p136-138) + +- 계좌 인증 정보, 비밀번호를 바로빌 API에 전달하여 자동 수집 +- 해당 테넌트는 은행에서 빠른 조회 서비스 사전 등록 필수 +- 계좌 상세: 계좌번호, 은행, 계좌명, 계좌 비밀번호, 예금주 +- 상태: 사용, 정지 (정지 시 자동 조회 중지) + +### 12.9 팝업관리 (p139-140) + +- 목록: 대상, 제목, 상태, 작성자, 등록일, 기간 +- 팝업 상세: 대상(전사/부서), 제목, 내용, 기간, 상태(사용함/사용안함) +- 사용함이어도 기간이 아닐 경우 팝업 미노출 + +### 12.10 게시판관리 (p141-142) + +- 모든 테넌트 디폴트: 공지사항, 나의 게시글 (수정/삭제 불가) +- 게시판 등록: 대상(전사/부서), 게시판명, 상태(사용함/사용안함) + +### 12.11 알림설정 (p143-149) + +**전체/개별 ON/OFF 토글** + +**알림 소리 선택:** 기본 알림음, SAM 보이스, ..., 무음 (관리자 등록 음원 목록) +**추가 알림:** 이메일 체크박스 + +**알림 유형:** + +| 카테고리 | 알림 항목 | +|---------|----------| +| 공지 알림 | 공지사항 알림, 이벤트 알림 | +| 거래처 알림 | 일정 알림, 부가세 신고 알림, 종합소득세 신고 알림, 신규 업체 등록 알림, 신용등급 등록 알림 | +| 근태 알림 | 연차 알림, 출근 알림, 지각 알림, 결근 알림 | +| 수주/발주 알림 | 수주 알림, 발주 알림 | +| 전자결재 알림 | 결재요청 알림, 기안>승인 알림, 기안>반려 알림, 기안>완료 알림 | +| 생산 알림 | 안전재고 알림, 생산완료 알림 | + +**항목 설정_알림 팝업:** 개별 알림 ON/OFF 토글 + +--- + +## 13. 보고서 및 분석 (p150-151) + +- TBD (추후 확정) +- 업체별 신용평가 및 보고서 검색 +- 업체별 보고서 및 분석 상세 제공 + +--- + +## 14. 계정정보/회사정보/구독관리/결제내역/고객센터 + +### 14.1 계정정보 (p153) + +- 아이디(이메일), 권한, 상태 +- 비밀번호 변경 버튼 +- 프로필 사진 (250x250px) +- 약관 동의 정보 (동의일시, 철회일시) +- 탈퇴 버튼: 테넌트 마스터가 아닐 경우에만 (모든 테넌트 + SAM 탈퇴) +- 사용중지 버튼: 테넌트 마스터가 아닐 경우에만 (해당 테넌트 사용중지) + +### 14.2 회사정보 (p154-155) + +- 테넌트 마스터에게만 표시 +- 회사 추가 버튼 +- 회사 정보: 운영(영업)에서 입력된 정보 표시, 수정 가능 +- 결제 계좌 정보: SAM 관리자가 등록 (효성 CMS 실물 계약서 기반) + +### 14.3 회사 추가 팝업 (p156) + +- 사업자등록번호 입력 (숫자 10자리) +- 바로빌 조회: 휴폐업 → 알림, 등록됨 → 알림, 미등록 → 매니저에게 알림 발송 + +### 14.4 구독관리 (p157) + +- 테넌트 마스터에게만 표시 +- 구독 정보: 플랜명, 최근/다음 결제일시, 구독금액 +- 사용량: 사용자 수, 저장 공간, AI API 호출 +- 자료 내보내기 버튼 +- 서비스 해지 버튼: "모든 데이터가 삭제되며 복구할 수 없습니다." 확인 Alert + +### 14.5 결제내역 (p158) + +- 테넌트 마스터에게만 표시 +- 목록: 결제일, 구독명, 결제 수단, 구독 기간, 금액, 거래명세서 + +### 14.6 고객센터 - 공지사항 (p159-160) + +- SAM 공지사항 +- 목록: 번호, 제목, 작성자, 등록일, 조회수 +- 상세: 제목, 작성자, 등록일시, 내용, 첨부파일 + +### 14.7 고객센터 - 이벤트 (p161-162) + +- 탭: 진행중인 이벤트, 종료된 이벤트 +- 목록: 번호, 제목, 작성자, 기간, 조회수 + +### 14.8 고객센터 - FAQ (p163) + +- 탭: 전체, 카테고리별 +- 질문 클릭 시 답변 영역 열림/닫힘 토글 + +### 14.9 고객센터 - 1:1 문의 (p164-167) + +- 문의 등록: 상담분류(문의하기/신고하기/건의사항/서비스 오류), 제목, 내용, 첨부파일 +- 문의 상세: 문의 내용 + 답변 내용 +- 수정 버튼: 답변완료 후 비활성화 +- 댓글 등록/조회 + +--- + +## 15. 참조 테이블 + +### 15.1 매출유형 목록 + +| 코드 | 매출유형명 | +|------|----------| +| - | 미설정 | +| 1 | 제품 매출 | +| 2 | 상품 매출 | +| 3 | 부품 매출 | +| 4 | 용역 매출 | +| 5 | 공사 매출 | +| 6 | 임대 수익 | +| 7 | 기타 매출 | + +### 15.2 매입유형 목록 + +| 코드 | 매입유형명 | +|------|----------| +| - | 미설정 | +| 1 | 원재료매입 | +| 2 | 부재료매입 | +| 3 | 상품매입 | +| 4 | 외주가공비 | +| 5 | 소모품비 | +| 6 | 수선비 | +| 7 | 운반비 | +| 8 | 사무용품비 | +| 9 | 임차료 | +| 10 | 수도광열비 | +| 11 | 통신비 | +| 12 | 차량유지비 | +| 13 | 접대비 | +| 14 | 보험료 | +| 15 | 기타용역비 | + +### 15.3 입금유형 목록 + +매출대금, 선수금, 가수금, 임대수익, 이자수익, 보증금 반환, 차입금, 자본금, 부가세 환급, 기타, 미설정 + +### 15.4 출금유형 목록 + +매입대금, 선급금, 가지급금, 임대료, 이자비용, 보증금 지급, 차입금 상환, 배당금 지급, 부가세 납부, 급여, 4대보험, 세금, 공과금, 경비, 기타, 미설정 + +### 15.5 카드 사용유형 목록 + +미설정, 복리후생비, 접대비, 여비교통비, 차량유지비, 소모품비, 운반비, 통신비, 도서인쇄비, 교육훈련비, 보험료, 광고선전비, 회비, 지급수수료, 세금과공과, 수선비, 임차료, 잡비 + +--- + +## 관련 문서 + +- SAM 프로젝트 개요: `/home/aweso/sam/docs/SAM_PROJECT_OVERVIEW_FOR_AI.md` +- 원본 PDF: `/home/aweso/sam/docs/plans/SAM_ERP_Storyboard_D1.4_260116.pdf` + +--- + +**최종 업데이트**: 2026-01-16 (D1.4) diff --git a/plans/SAM_ERP_회계관리_Storyboard_D1.6.md b/plans/SAM_ERP_회계관리_Storyboard_D1.6.md new file mode 100644 index 0000000..1ab7db7 --- /dev/null +++ b/plans/SAM_ERP_회계관리_Storyboard_D1.6.md @@ -0,0 +1,1288 @@ +# SAM ERP 회계관리 스토리보드 D1.6 + +> **작성일**: 2026-02-20 +> **버전**: D1.6 +> **상태**: 프론트 작성 +> **원본**: `SAM_ERP_회계관리_Storyboard_D1.6_260220.pdf` (65페이지) + +--- + +## 문서 이력 + +| 날짜 | 버전 | 주요 내용 | 상세 | +|------|------|----------|------| +| 2026-02-13 | D1.5 | 프론트 작성 | 세금계산서 관리, 계좌 입출금 내역, 계좌 관리, 상품권 관리, 바로빌 연동 수정 및 추가 | +| 2026-02-20 | D1.6 | 프론트 작성 | 거래처 관리(사업자등록증 OCR), 일일일보, 대시보드(생산, 시공), 이관 기초자료, 달력 관리, 즐겨찾기, 신용평가 수정 및 추가 | + +--- + +## 메뉴 구조 + +``` +SAM ERP +├── 로그인 +├── 회원가입 +├── 대시보드 +├── MES +│ ├── 판매관리 +│ ├── 구매관리 +│ ├── 발주관리 +│ ├── 공사관리 +│ ├── 생산관리 +│ ├── 품질관리 +│ ├── 자재관리 +│ ├── 장비관리 +│ └── 차량관리 +├── 인사관리 +├── 전자결재 +├── 게시판 +├── 회계관리 ★ (본 문서 범위) +│ ├── 거래처 관리 +│ ├── 세금계산서 발행 +│ ├── 세금계산서 관리 +│ ├── 계좌 입출금 내역 +│ ├── 카드 사용 내역 +│ ├── 상품권 관리 +│ ├── 일반 전표 입력 +│ └── 일일일보 +├── 기준정보 ★ (본 문서 범위) +│ ├── 바로빌 연동 관리 +│ ├── 계좌 관리 +│ ├── 카드 관리 +│ ├── 달력 관리 +│ └── 이관 기초자료 +├── 보고서 및 분석 +└── 운영 + ├── 회사정보 + ├── 계정정보 + ├── 구독관리 + ├── 결제내역 + └── 고객센터 +``` + +--- + +## 화면 목록 (페이지 인덱스) + +| 페이지 | 경로 | 화면명 | +|--------|------|--------| +| 4 | 공통 | 섹션 구분 | +| 5 | 공통 | 즐겨찾기 | +| 6 | 대시보드 | 섹션 구분 | +| 7 | 대시보드 | 대시보드 (자금 현황, 오늘의 이슈, AI 리포트) | +| 8 | 대시보드 | 대시보드 (매출 현황) | +| 9 | 대시보드 | 대시보드 (매입 현황) | +| 10 | 대시보드 | 대시보드 (생산 현황) | +| 11 | 대시보드 | 대시보드 (시공 현황, 미출고 내역) | +| 12 | 대시보드 | 대시보드 (근태 현황) | +| 13-14 | 대시보드 > 항목 설정 팝업 | 항목 설정_대시보드 팝업 | +| 15 | 회계관리 | 섹션 구분 | +| 16 | 회계관리 > 거래처 관리 | 거래처 관리 (목록) | +| 17-18 | 회계관리 > 거래처 관리 > 거래처 상세 | 거래처 상세 (등록/수정) | +| 19 | 회계관리 > 거래처 관리 > 거래처 상세 | 신용분석 리포트 팝업 | +| 20 | 회계관리 > 세금계산서 발행 | 세금계산서 발행 (목록) | +| 21-22 | 회계관리 > 세금계산서 발행 | 세금계산서 발행_확장 (발행 입력) | +| 23 | 회계관리 > 세금계산서 발행 | 공급자 기초정보 설정 팝업 | +| 24 | 회계관리 > 세금계산서 발행 | 거래처 검색 팝업 | +| 25 | 회계관리 > 세금계산서 관리 | 세금계산서 관리 (매출) | +| 26 | 회계관리 > 세금계산서 관리 | 세금계산서 관리 (매입) | +| 27 | 회계관리 > 세금계산서 관리 | 세금계산서 수기 입력 팝업 | +| 28 | 회계관리 > 세금계산서 관리 | 카드 내역 불러오기 팝업 | +| 29 | 회계관리 > 세금계산서 관리 | 분개 수정 팝업 | +| 30 | 회계관리 > 계좌 입출금 내역 | 계좌 입출금 내역 (목록) | +| 31 | 회계관리 > 계좌 입출금 내역 | 입출금 수기 입력 팝업 | +| 32 | 회계관리 > 카드 사용 내역 | 카드 사용 내역 (목록) | +| 33 | 회계관리 > 카드 사용 내역 | 카드사용 수기 입력 팝업 | +| 34 | 회계관리 > 카드 사용 내역 | 거래 분개 팝업 | +| 35 | 회계관리 > 상품권 관리 | 상품권 관리 (목록) | +| 36 | 회계관리 > 상품권 관리 > 상품권 상세 | 상품권 상세 (등록/수정) | +| 37 | 회계관리 > 일반 전표 입력 | 일반 전표 입력 (목록) | +| 38 | 회계관리 > 일반 전표 입력 | 계정과목 설정 팝업 | +| 39 | 회계관리 > 일반 전표 입력 | 수기 전표 입력 팝업 | +| 40 | 회계관리 > 일반 전표 입력 | 분개 수정 팝업 | +| 41 | 기준정보 | 섹션 구분 | +| 42 | 기준정보 > 바로빌 연동 관리 | 바로빌 연동 관리 | +| 43 | 기준정보 > 바로빌 연동 관리 | 바로빌 로그인 정보 등록 팝업 | +| 44 | 기준정보 > 바로빌 연동 관리 | 바로빌 회원가입 정보 등록 팝업 | +| 45 | 기준정보 > 바로빌 연동 관리 | 은행 빠른조회 서비스 등록 팝업 | +| 46 | 기준정보 > 계좌 관리 | 계좌 관리 (목록) | +| 47 | 기준정보 > 계좌 관리 > 계좌 상세 | 계좌 상세_은행 | +| 48 | 기준정보 > 계좌 관리 > 계좌 상세 | 계좌 상세_대출 | +| 49 | 기준정보 > 계좌 관리 > 계좌 상세 | 계좌 상세_증권 | +| 50 | 기준정보 > 계좌 관리 > 계좌 상세 | 계좌 상세_보험_단체보험 | +| 51 | 기준정보 > 계좌 관리 > 계좌 상세 | 계좌 상세_보험_화재보험 | +| 52 | 기준정보 > 계좌 관리 > 계좌 상세 | 계좌 상세_보험_CEO보험 | +| 53 | 기준정보 > 카드 관리 | 카드 관리 (목록) | +| 54 | 기준정보 > 카드 관리 > 카드 상세 | 카드 상세 | +| 55 | 기준정보 > 달력 관리 | 달력 관리 (달력 뷰) | +| 56 | 기준정보 > 달력 관리 | 달력 관리 (목록 뷰) | +| 57 | 기준정보 > 달력 관리 | 달력 상세 팝업 | +| 58 | 기준정보 > 달력 관리 | 대량 등록 팝업 | +| 59-60 | 기준정보 > 이관 기초자료 | 이관 기초자료 (거래처 탭) | +| 61 | 기준정보 > 이관 기초자료 | 이관 기초자료_거래처 CSV 스펙 | +| 62 | 기준정보 > 이관 기초자료 | 이관 기초자료_거래 내역 CSV 스펙 | +| 63 | 기준정보 > 이관 기초자료 | 이관 기초자료_계좌 내역 CSV 스펙 | +| 64 | 기준정보 > 이관 기초자료 | 이관 기초자료_세금계산서 내역 CSV 스펙 | +| 65 | 기준정보 > 이관 기초자료 | 이관 기초자료_업로드 이력 | + +--- + +## 1. 공통 + +### 1.1 즐겨찾기 (P5) + +**경로**: 공통 (사이드바) + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 즐겨찾기 버튼 | 메뉴명에 마우스 롤 오버 시 표시. 즐겨찾기 설정 상태일 경우 상시 표시. 클릭: 즐겨찾기 설정/해제 토글. 디폴트: 해제 상태 | +| 2 | 즐겨찾기 폴더 버튼 | 클릭: 즐겨찾기 설정 목록 표시 | + +**사이드바 메뉴 구조** (회계관리 하위): +- 거래처관리 +- 세금계산서발행 +- 세금계산서관리 +- 계좌입출금내역 +- 카드사용내역 +- 상품권관리 +- 일반전표입력 +- 일일일보 + +--- + +## 2. 대시보드 + +### 2.1 대시보드 - 메인 (P7) + +**경로**: 대시보드 +**설명**: 종합 정보를 조회합니다 + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 항목 설정 버튼 | 클릭: 항목 설정_대시보드 팝업 표시 | +| 2 | 오늘의 이슈 영역 | 당일 이슈 발생 시 알림 처리. 목록 길 경우 영역 내 페이지네이션. 알림 상태에서 즉시 승인/보류 처리 가능 | +| 3 | 필터 셀렉트 박스 | 종류: 전체, 수주 성공, 추심 이슈, 적정 재고, 결재 요청, 세금 신고, 신규 업체 등록, 근태, 발주 완료. 디폴트: 전체. 숫자도 함께 표시 | +| 4 | 이슈 목록 | 클릭: 해당 상세 화면으로 이동. 화면 가로 길이에 따라 4, 3, 2, 1열로 반응형 표시 | +| 5 | 일일일보 영역 | 현금성 자산합계 표시. 클릭: 일일일보 화면으로 이동 | +| 6 | 매출채권 잔액 영역 | 미수금 잔액 합계 표시. 클릭: 미수금 현황 화면으로 이동 | +| 7 | 매입채무 잔액 영역 | = 세금계산서 매입 합계 - 거래처별 일반전표 출금 합계 (또는 거래처별 미지급금 합계) | +| 8 | AI 리포트 | 핵심 키워드 강조 표시 (빨간색: 경고, 주황: 주의, 녹색: 긍정, 파랑: 양호) | + +**이슈 케이스**: +- 신규 업체 등록 +- 재고 미달 알림 +- 채권 추심 등록, 상태 변경 +- 발주, 수주 등록 +- 지출결의서 등 전자결재 상신 +- 세금 신고 알림 등 + +**자금 현황 카드** (예시 데이터): +- 일일일보: 30.5억원 +- 매출채권 잔액: 30.5억원 +- 매입채무 잔액: 30.5억원 +- 운영자금 잔여: 6.2개월 + +**AI 리포트 예시**: +- "어제 3.5억원 출금했습니다. 최근 7일 평균 대비 2배 이상으로 점검이 필요합니다." +- "10.2억원이 입금되었습니다. 대한건설 선수금 입금이 주요 원인입니다." +- "총 현금성 자산이 300.2억원입니다. 월 운영비용 대비 18개월분이 확보되어 안정적입니다." + +--- + +### 2.2 대시보드 - 매출 현황 (P8) + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 거래처 필터 셀렉트 박스 | 검색 & 다중 선택. 종류: 전체, 매출 거래처명. 디폴트: 전체 | +| 2 | 정렬 셀렉트 박스 | 종류: 최신순, 등록순, 금액 높은순, 금액 낮은순. 디폴트: 최신순 | + +**표시 정보**: +- 누적 매출 금액 +- 목표 대비 달성률 (%) +- 전년 동기 대비 증감률 (%) +- 당월 매출 금액 +- 거래처별 매출 (차트) +- 월별 매출 추이 (1~7월 차트) +- 당월 매출 내역 테이블: No., 매출일, 거래처, 매출금액 + +--- + +### 2.3 대시보드 - 매입 현황 (P9) + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 거래처 필터 셀렉트 박스 | 검색 & 다중 선택. 종류: 전체, 매입 거래처명. 디폴트: 전체 | +| 2 | 정렬 셀렉트 박스 | 종류: 최신순, 등록순, 금액 높은순, 금액 낮은순. 디폴트: 최신순 | + +**표시 정보**: +- 누적 매입 금액 +- 미결제 금액 +- 전년 동기 대비 증감률 (%) +- 자재 유형별 구매 비율 (파이 차트: 원자재 55%, 부자재 35%, 소모품 10%) +- 월별 매입 추이 차트 +- 당월 매입 내역 테이블: No., 매출일, 거래처, 매입금액 + +--- + +### 2.4 대시보드 - 생산 현황 (P10) + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 생산 현황 탭 | 종류: 스크린 공정, 슬랫 공정, 절곡 공정. 디폴트: 스크린 공정 | +| 2 | 요약 정보 | 선택한 공정별 요약 정보 표시 (전체 작업, 할일, 작업중, 완료) | +| 3 | 수주 목록 | 클릭: 작업자 화면으로 이동 (해당 수주 작업 선택 상태). 긴급/우선/일반 구분 | +| 4 | 작업자 현황 목록 | 작업자별 당일 생산 현황 표시 (작업중/작업대기 상태, 완료 건수) | +| 5 | 출고 현황 정보 | 클릭: 출고 목록 화면으로 이동 (해당 기간 설정 상태). 예상 출고 7일/30일 이내, 건수 표시 | + +--- + +### 2.5 대시보드 - 시공 현황 (P11) + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 거래처 필터 셀렉트 박스 | 검색 & 다중 선택. 종류: 전체, 매출 거래처명. 디폴트: 전체 | +| 2 | 정렬 셀렉트 박스 | 종류: 납기일 가까운순, 납기일 먼순, 잔량 많은순, 잔량 적은순. 디폴트: 납기일 가까운순 | +| 3 | 시공 현황별 요약 정보 | 시공 진행(7일 이내), 시공 완료(7일 이내) 건수. 클릭: 시공관리 화면으로 이동 | +| 4 | 시공 상세 목록 | 클릭: 해당 시공 상세 화면으로 이동. 컬럼: No., 로트번호, 현장명, 수주처, 잔량, 납기일(D-N) | + +**미출고 내역 테이블**: 시공진행 상태의 현장명, 로트번호 목록 + +--- + +### 2.6 대시보드 - 근태 현황 (P12) + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 근태 현황별 요약 정보 | 오늘 출근, 오늘 휴가, 어제 지각, 어제 결근 인원. 클릭: 근태관리 화면으로 이동 | +| 2 | 상태 필터 셀렉트 박스 | 종류: 전체, 출근, 휴가. 디폴트: 전체 | + +**근태 목록 테이블**: No., 부서, 직급, 이름, 상태(출근/휴가) + +--- + +### 2.7 항목 설정_대시보드 팝업 (P13-14) + +**경로**: 대시보드 > 항목 설정_대시보드 팝업 + +#### 2.7.1 접대비 한도 관리 + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 접대비 한도 관리 셀렉트 박스 | 종류: 연간, 반기, 분기, 월. 디폴트: 연간. 선택 값으로 총 한도를 분할 계산 | +| 1-1 | 기업 구분 셀렉트 박스 | 종류: 일반법인, 중소기업. 디폴트: 일반법인 | +| 1-2 | 기업 구분 방법 영역 | 클릭: 확대/축소 토글. 디폴트: 축소 상태 | + +**중소기업 판단 기준표**: + +| 조건 | 기준 | 충족 요건 | +|------|------|----------| +| 매출액 | 업종별 상이 | 업종별 기준 금액 이하 | +| 자산총액 | 5,000억원 | 미만 | +| 독립성 | 소유/경영 | 대기업 계열 아님 | + +> 3가지 조건 모두 충족 시 중소기업 + +**업종별 매출액 기준** (최근 3개년 평균): + +| 업종 분류 | 기준 매출액 | +|-----------|------------| +| 제조업 | 1,500억원 이하 | +| 건설업 | 1,000억원 이하 | +| 운수업 | 1,000억원 이하 | +| 도매업 | 1,000억원 이하 | +| 소매업 | 600억원 이하 | +| 정보통신업 | 600억원 이하 | +| 전문서비스업 | 600억원 이하 | +| 숙박/음식점업 | 400억원 이하 | +| 기타 서비스업 | 400억원 이하 | + +**접대비 기본한도 판정**: + +| 판정 | 조건 | 접대비 기본한도 | +|------|------|----------------| +| 중소기업 | 3가지 모두 충족 | 3,600만원 | +| 일반법인 | 하나라도 미충족 | 1,200만원 | + +#### 2.7.2 복리후생비 한도 관리 + +| # | 요소 | 설명 | +|---|------|------| +| 2 | 복리후생비 한도 관리 셀렉트 박스 | 종류: 연간, 반기, 분기, 월. 디폴트: 연간. 선택 값으로 총 한도를 분할 계산 | +| 3 | 계산 방식 셀렉트 박스 | 종류: 직원당 정액 금액 방식, 연봉 총액 X 비율 방식. 디폴트: 직원당 정액 금액 방식 | +| 4 | 직원당 정액 금액/월 인풋박스 | 직원당 정액 금액 방식일 경우에만 표시 | +| 5 | 비율 인풋박스 | 연봉 총액 X 비율 방식일 경우에만 표시 | +| 6 | 연간 복리후생비 | 계산된 연간 복리후생비 표시 | + +#### 2.7.3 설정 항목 ON/OFF 목록 (P14) + +| 항목 | 기본값 | +|------|--------| +| 접대비 현황 | ON | +| 카드/가지급금 관리 | ON | +| 복리후생비 현황 | ON | +| 미수금 상위 회사 현황 | ON | +| 미수금 현황 | ON | +| 채권추심 현황 | ON | +| 부가세 현황 | ON | +| 캘린더 | ON | +| 매출 현황 | ON | +| 일별 매출 내역 | ON | +| 매입 현황 | ON | +| 일별 매입 현황 | ON | +| 생산 현황 | ON | +| 출고 현황 | ON | +| 미출고 내역 | ON | +| 시공 현황 | ON | +| 근태 현황 | ON | + +--- + +## 3. 회계관리 + +### 3.1 거래처 관리 (P16) + +**경로**: 회계관리 > 거래처 관리 +**설명**: 거래처 정보 및 신용등급을 관리합니다 + +**기능 설명**: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 거래처 등록 버튼 | 클릭: 거래처 상세_등록 화면으로 이동 | +| 2 | 구분 필터 셀렉트 박스 | 종류: 전체, 매출, 매입, 매입매출. 디폴트: 전체 | +| 3 | 사용 필터 셀렉트 박스 | 종류: 전체, 사용, 미사용. 디폴트: 전체 | +| 4 | 정렬 셀렉트 박스 | 종류: 최신순, 등록순. 디폴트: 최신순 | + +**기간 필터**: 전전월, 어제, 오늘, 전월, 당월, 당해년도 + +**목록 테이블 컬럼**: + +| 컬럼 | 설명 | +|------|------| +| No. | 순번 | +| 구분 | 매출, 매입, 매입매출 | +| 거래처명 | 회사명 | +| 매입 결제일 | 예: 10일 | +| 매출 결제일 | 예: 15일 | +| 신용등급 | 외부 신용평가 (AAA~D) | +| 거래등급 | 자사 기준 (A(우수)~E(위험)) | +| 미수금 | 금액 | +| 악성채권 | 악성채권 여부 | +| 상태 | 사용/미사용 | + +--- + +### 3.2 거래처 상세 (P17-18) + +**경로**: 회계관리 > 거래처 관리 > 거래처 상세 +**설명**: 거래처 상세 정보 및 신용등급을 관리합니다 + +#### 3.2.1 기본 정보 (P17) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 파일 등록 영역 (사업자등록증 OCR) | 클릭: 파일탐색기 팝업 표시. 사업자등록증 파일 등록 시 관련 정보 자동 입력 처리 | +| 2 | 구분 셀렉트 박스 | 종류: 매출, 매입, 매입매출 | +| 3 | 사용 셀렉트 박스 | 종류: 사용, 미사용 | + +**기본 정보 필드**: + +| 필드 | 설명 | +|------|------| +| 사업자등록증 | 파일 업로드 → OCR 자동 인식 | +| 거래처 코드 | 자동 생성 | +| 사업자등록번호 | OCR 또는 수기 입력 | +| 거래처명 | 회사명 | +| 대표자명 | 대표이사 | +| 업태 | 사업자등록증 업태 | +| 업종 | 사업자등록증 업종 | +| 거래처 유형 | 매출/매입/매입매출 | +| 상태 | 사용/미사용 | + +**연락처 정보 필드**: 주소(우편번호 찾기), 모바일, 전화번호, 팩스, 이메일 + +**담당자 정보 필드**: 담당자명, 담당자 전화 + +#### 3.2.2 신용/거래 정보 (P18) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 신용정보 보기 버튼 | 클릭: 신용분석 리포트 팝업표시 | +| 2 | 매입 결제일 셀렉트 박스 | 종류: 1일~31일, 말일. 디폴트: 10일. 거래처 유형이 매입 또는 매입매출일 경우 표시 | +| 3 | 매출 결제일 셀렉트 박스 | 종류: 1일~31일, 말일. 디폴트: 15일. 거래처 유형이 매출 또는 매입매출일 경우 표시 | +| 4 | 신용등급 인풋박스 | 외부 신용평가 등급. 예: AAA, AA, A, BBB, BB, B, CCC, CC, C, D | +| 5 | 거래등급 셀렉트 박스 | 종류: A(우수), B(양호), C(보통), D(주의), E(위험). 디폴트: A(우수). 자사 기준 거래처 평가 | +| 6 | 미수금 표시 영역 | 해당 거래처의 현재 미수금 합계 표시. 읽기 전용 | +| 7 | 연체 토글 | ON: 연체 상태, 연체일수 표시. OFF: 정상 상태. 미수금 현황에서 연체 설정과 연동 | +| 8 | 악성채권 토글 | ON: 악성채권으로 등록, 추심관리 목록에 표시. OFF: 정상. 디폴트: OFF | +| 9 | 미지급 표시 영역 | 해당 거래처에 대한 미지급금 합계 표시. 읽기 전용 | + +**추가 필드**: 입금계좌 은행, 계좌, 예금주, 세금계산서 이메일, 메모 + +--- + +### 3.3 신용분석 리포트 팝업 (P19) + +**경로**: 회계관리 > 거래처 관리 > 거래처 상세 > 신용분석 리포트 팝업 +**설명**: 현행화 (기존 화면 유지) + +--- + +### 3.4 세금계산서 발행 (P20-24) + +**경로**: 회계관리 > 세금계산서 발행 +**설명**: 바로빌 API를 통하여 전자세금계산서를 발행하고 관리합니다 + +#### 3.4.1 목록 화면 (P20) + +**상단 요약 카드**: 발행건수, 총 합계금액, 총 공급가액, 총 세액, 발행/전송 건수 + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 공급자 설정 버튼 | 클릭: 공급자 설정 팝업 표시 | +| 2 | 새로 발행 버튼 | 클릭: 전자세금계산서 발행 세부 입력 영역 표시 | +| 3 | 일자 셀렉트 박스 | 종류: 작성일자, 전송일자. 디폴트: 작성일자 | +| 4 | 상태 셀렉트 박스 | 종류: 전체, 작성중, 발행완료, 국세청 전송완료, 취소됨 | +| 5 | 정렬 셀렉트 박스 | 종류: 작성일자, 전송일자, 공급받는자, 합계금액. 디폴트: 작성일자 | +| 6 | 정렬2 셀렉트 박스 | 종류: 내림차순, 오름차순. 디폴트: 내림차순 | +| 7 | 조회 버튼 | 클릭: 조회 결과 표시 | + +**기간 필터**: 1주일, 1개월, 3개월, 날짜 범위 직접 선택 + +**거래처 검색**: 사업자 번호 또는 사업자명 + +**목록 테이블 컬럼**: 발행번호, 공급받는 자, 작성일자, 전송일자, 공급가액, 세액, 합계금액, 상태, 작업 + +#### 3.4.2 발행 세부 입력 (P21-22) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 검색 버튼 | 클릭: 거래처 검색 팝업표시, 선택 시 공급받는자 목록에 자동 입력 | +| 2 | 품목 추가 버튼 | 클릭: 품목 행 추가 | +| 3 | 전자세금계산서 발행 세부 입력 영역 | - | + +**공급자 영역 필드**: 등록번호, 종사업장, 상호, 대표자, 사업장주소, 업태, 종목, 담당자, 연락처, 이메일 + +**공급받는자 영역 필드**: 등록번호, 종사업장, 상호, 대표자, 사업장주소, 업태, 종목, 담당자, 연락처, 이메일, 세금계산서 수신 이메일 + +**품목 정보 테이블**: 월, 일, 품목, 수량, 단가, 공급가액, 세액, 합계, 과세유형(과세) + +**기타 필드**: 작성일자, 비고, 추가 메모사항 + +#### 3.4.3 공급자 기초정보 설정 팝업 (P23) + +| 필드 | 설명 | +|------|------| +| 사업자번호 | 회사정보 기본값 | +| 상호명 * | 필수 | +| 대표자명 * | 필수 | +| 업태 | - | +| 종목 | - | +| 주소 | - | +| 담당자명 | - | +| 연락처 | - | +| 이메일 | - | + +#### 3.4.4 거래처 검색 팝업 (P24) + +- 거래처명, 사업자번호, 담당자명으로 검색 +- 목록 표시: 거래처명, 사업자번호 + +--- + +### 3.5 세금계산서 관리 (P25-29) + +**경로**: 회계관리 > 세금계산서 관리 +**설명**: 홈택스에 신고된 세금계산서 매입/매출 내역을 조회하고 관리합니다 + +#### 3.5.1 매출 탭 (P25) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 일자 셀렉트 박스 | 종류: 작성일자, 전송일자. 디폴트: 작성일자 | +| 2 | 세금계산서 관리 탭 | 종류: 매출+수, 매입+수. 디폴트: 매출+수 | +| 3 | 수기 입력 버튼 | 클릭: 세금계산서 수기 입력 팝업표시 | + +**기간 필터**: 1분기, 2분기, 3분기, 4분기, 날짜 범위 직접 선택 + +**상단 요약 카드**: 매출 공급가액, 매출 세액, 매입 과세 공급가액, 매입 면세 공급가액, 매입 세액 + +**기간 요약**: 매출 합계(공급가액 + 세액), 매입 합계(공급가액 + 세액), 예상 부가세 + +**구분 표시**: 수기 세금계산서(색상 표시), 홈택스 연동 세금계산서(색상 표시) + +**목록 테이블 컬럼**: 작성일자, 발급일자, 거래처, 사업자번호(주민번호), 과세형태, 품목, 공급가액, 세액, 합계, 영수청구, 문서형태, 발급형태, 상태, 분개 + +**엑셀 다운로드** 기능 제공 + +#### 3.5.2 매입 탭 (P26) + +매출 탭과 동일 구조. 추가 기능: + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 분개 버튼 | 클릭: 분개 수정 팝업표시. 분개 저장 시 [분개 완료] 버튼으로 변경 | + +#### 3.5.3 세금계산서 수기 입력 팝업 (P27) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 구분 셀렉트 박스 | 종류: 매출, 매입. 디폴트: 매출 | +| 2 | 카드 내역 불러오기 버튼 | 클릭: 카드 내역 불러오기 팝업 표시. 선택 시 공급자 정보 및 금액 자동 입력, 수정 가능 | +| 3 | 과세유형 셀렉트 박스 | 종류: 과세, 영세, 면세. 디폴트: 과세 | + +**입력 필드**: 구분, 작성일자, 공급자명, 사업자 번호, 품목, 과세유형, 공급가액, 세액, 합계, 비고 + +#### 3.5.4 카드 내역 불러오기 팝업 (P28) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 카드 내역 목록 표시 | 기간 검색 후 목록 표시 | +| 2 | 선택 버튼 | 클릭: 세금계산서 수기 입력 팝업에 공급자 정보 및 금액 자동 입력 | + +**검색**: 가맹점/승인번호, 기간 검색 + +**목록 컬럼**: 날짜, 가맹점, 금액, 승인번호, 선택 + +#### 3.5.5 분개 수정 팝업 (P29) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 구분 영역 | 클릭: 차변/대변 토글 | +| 2 | 계정과목 셀렉트 박스 | 검색 가능. 종류: 계정과목 목록 | + +**세금계산서 정보**: 구분(매입/매출), 공급가액, 거래처, 세액 + +**분개 내역**: 구분(차변/대변), 계정과목, 금액, 합계 + +**버튼**: 분개 수정, 취소, 분개 삭제 + +--- + +### 3.6 계좌 입출금 내역 (P30-31) + +**경로**: 회계관리 > 계좌 입출금 내역 +**설명**: 계좌 입출금 내역을 조회하고 관리합니다 + +#### 3.6.1 목록 화면 (P30) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 저장 버튼 | 클릭: 인풋박스 영역의 변경값 저장 | +| 2 | 입출금 수기 입력 버튼 | 클릭: 입출금 수기 입력_등록 팝업 표시 | +| 3 | 계좌 입출금 내역 목록 | 클릭: 입출금 수기 입력 팝업 표시 | +| 4 | 수정 영역 | 수정된 영역에 하이라이트 표시 | +| 5 | 구분 셀렉트 박스 | 종류: 전체, 은행계좌, 대출계좌, 증권계좌, 보험계좌. 디폴트: 전체 | +| 6 | 금융기관 셀렉트 박스 | 종류: 전체, 금융기관명 목록. 디폴트: 전체 | + +**기간 필터**: 지난달, D-5월, D-4월, D-3월, D-2월, 이번달 + +**상단 요약 카드**: 입금, 출금, 잔액, 계좌 수, 거래 건수 + +**구분 표시**: 수기 계좌(색상 표시), 연동 계좌(색상 표시) + +**목록 테이블 컬럼**: No., 거래일시, 구분, 계좌정보(금융기관+계좌번호), 적요/내용, 입금, 출금, 잔액, 취급점, 상대계좌 예금주명 + +**엑셀 다운로드** 기능 제공 + +#### 3.6.2 입출금 수기 입력 팝업 (P31) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 계좌 셀렉트 박스 | 종류: 설정된 계좌 목록 | +| 2 | 수정 스티커 | 수정되었을 경우에만 표시 | +| 3 | 원본으로 복원 버튼 | 클릭: 원본 데이터로 변경, 수정 스티커 삭제 | + +**입력 필드**: + +| 필드 | 필수 | 설명 | +|------|------|------| +| 계좌 | * | 계좌 선택 | +| 거래일 | * | 날짜 선택 | +| 거래시간 | - | HH:MM:SS | +| 거래유형 | * | 입금/출금 | +| 금액 | * | 금액 입력 | +| 잔액 | - | 자동계산 | +| 적요 | - | 내용 | +| 상대계좌 예금주명 | - | - | +| 메모 | - | - | +| 취급점 | - | - | + +--- + +### 3.7 카드 사용 내역 (P32-34) + +**경로**: 회계관리 > 카드 사용 내역 +**설명**: 카드 사용 내역을 조회하고 관리합니다 + +#### 3.7.1 목록 화면 (P32) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 숨김 데이터 보기 버튼 | 클릭: 숨김 처리된 거래 영역 표시/숨김 토글. 디폴트: 숨김 | +| 2 | 저장 버튼 | 표 수정 사항 저장 처리 | +| 3 | 카드사용 수기 입력 버튼 | 클릭: 카드사용 수기 입력 팝업표시 | +| 4 | 카드사 셀렉트 박스 | 종류: 전체, 카드사명 목록. 디폴트: 전체 | +| 5 | 공제 셀렉트 박스 (필터) | 종류: 전체, 공제, 불공제. 디폴트: 전체 | +| 6 | 공제 셀렉트 박스 (행 내) | 종류: 공제, 불공제. 디폴트: 공제 | +| 7 | 텍스트 인풋박스 영역 | 인라인 수정 가능 | +| 8 | 숫자 인풋박스 영역 | 인라인 수정 가능 | +| 9 | 계정과목 셀렉트 박스 | 검색 가능. 종류: 계정과목 목록 | +| 10 | 분개 버튼 | 클릭: 거래 분개 팝업표시 | +| 11 | 숨김 버튼 | 클릭: 숨김 데이터 영역에 추가 | +| 12 | 복원 버튼 | 클릭: 원래 위치로 복원 | + +**기간 필터**: 지난달, D-5월, D-4월, D-3월, D-2월, 이번달 + +**상단 요약 카드**: 사용금액, 공제, 불공제, 등록된 카드 수 + +**구분 표시**: 수기 카드(색상 표시), 연동 카드(색상 표시) + +**목록 테이블 컬럼**: No., 사용일시, 카드사, 카드번호, 카드명, 공제, 사업자번호, 가맹점명/증빙/판매자상호, 내역, 합계금액, 공급가액, 세액, 계정과목, 분개, 숨김 + +**숨김 처리된 거래 영역** (별도 테이블): No., 사용일시, 카드사, 카드번호, 카드명, 사업자번호, 가맹점명, 합계금액, 숨김일시, 복원 + +**엑셀 다운로드** 기능 제공 + +#### 3.7.2 카드사용 수기 입력 팝업 (P33) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 카드 셀렉트 박스 | 종류: 설정된 카드 목록 (예: 신한카드 123123 카드명) | +| 2 | 공제 셀렉트 박스 | 종류: 공제, 불공제. 디폴트: 공제 | +| 3 | 계정과목 셀렉트 박스 | 검색 가능. 종류: 계정과목 목록 | + +**입력 필드**: + +| 필드 | 필수 | 설명 | +|------|------|------| +| 카드 선택 | * | 카드 셀렉트 | +| 사용일 | * | 날짜 | +| 사용시간 | - | HH:MM:SS | +| 승인유형 | * | 승인/취소 | +| 승인번호 | - | - | +| 가맹점명 | - | - | +| 사업자번호 | - | - | +| 공제여부 | * | 공제/불공제 | +| 계정과목 | - | 선택 | +| 증빙/판매자상호 | - | - | +| 내역 | - | - | +| 공급가액 | * | 금액 | +| 세액 | * | 금액 | +| 메모 | - | - | + +**합계 금액** = 공급가액 + 세액 (자동 계산 표시) + +#### 3.7.3 거래 분개 팝업 (P34) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 계정과목 셀렉트 박스 | 검색 가능. 종류: 계정과목 목록 | +| 2 | 공제 셀렉트 박스 | 종류: 공제, 불공제. 디폴트: 공제 | +| 3 | 분개 항목 추가 버튼 | 클릭: 분개 항목 영역 추가 | +| 4 | 삭제 버튼 | 클릭: 해당 분개 항목영역 삭제. 1개만 있을 경우 버튼 비활성화 | + +**거래 정보**: 가맹점, 사용일시, 공급가액, 세액, 합계금액 + +**분개 항목 필드**: 계정과목, 공제, 내역, 증빙/판매자상호, 공급가액, 세액, 합계금액, 내역, 메모 + +**분개 합계** 표시 + +--- + +### 3.8 상품권 관리 (P35-36) + +**경로**: 회계관리 > 상품권 관리 +**설명**: 상품권을 등록하고 관리합니다 + +> **상품권 접대비 기준**: +> 1. 50만원 미만: 일반 복리후생비/판촉비. 일반 경비로 처리 가능 +> 2. 50만원 이상: 접대비로 자동 분류. 사용처/수령인 기록 필수. 세법상 접대비 한도 관리 대상 + +#### 3.8.1 목록 화면 (P35) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 상품권 등록 버튼 | 클릭: 상품권 상세화면으로 이동 | +| 2 | 접대비 셀렉트 박스 | 종류: 전체, 해당, 해당없음. 디폴트: 전체 | +| 3 | 상태 셀렉트 박스 | 종류: 전체, 보유, 사용, 폐기. 디폴트: 전체 | + +**기간 필터**: 지난달, D-5월, D-4월, D-3월, D-2월, 이번달 + +**상단 요약 카드**: 전체 상품권 건수, 보유 상품권(건수/금액), 사용 상품권(건수/금액), 접대비 해당(건수/금액) + +**목록 테이블 컬럼**: No., 일련번호, 상품권명, 액면가, 구입일, 사용일, 접대비, 상태 + +#### 3.8.2 상품권 상세 (P36) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 액면가 인풋박스 | 50만원 이상 입력 시 필수 정보 표시 (사용처/수령인 등) | +| 2 | 구입처 셀렉트 박스 | 종류: 매입 거래처명 목록 | +| 3 | 구입목적 셀렉트 박스 | 종류: 판촉, 선물, 접대, 기타 | +| 4 | 상태 셀렉트 박스 | 종류: 보유, 사용, 폐기 | + +**기본 정보 필드**: 상품권명, 일련번호, 액면가, 구입처, 구입목적, 구입일, 접대비(해당/해당없음) + +**상품권 정보** (액면가 50만원 이상 필수): + +| 필드 | 설명 | +|------|------| +| 사용처/용도 | 내용 | +| 수령인 | 이름 | +| 수령인 소속 | 회사명 | +| 사용일 | 날짜 | +| 상태 | 보유/사용/폐기 | +| 비고 | - | + +--- + +### 3.9 일반 전표 입력 (P37-40) + +**경로**: 회계관리 > 일반 전표 입력 +**설명**: 계좌입출금내역을 기반으로 분개 전표를 생성합니다 + +#### 3.9.1 목록 화면 (P37) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 계정과목 설정 버튼 | 클릭: 계정과목 설정 팝업표시 | +| 2 | 수기 전표 입력 버튼 | 클릭: 수기 전표 입력 팝업표시 | +| 3 | 분개 버튼 | 클릭: 분개 수정 팝업표시 | + +**기간 필터**: 지난달, D-5월, D-4월, D-3월, D-2월, 이번달 + +**상단 요약 카드**: 전체 건수, 입금, 출금, 분개완료 건수, 미분개 건수 + +**구분 표시**: 수기 전표(색상 표시), 연동 전표(색상 표시) + +**목록 테이블 컬럼**: 날짜, 적요, 입금, 출금, 잔액, 분개 내역(차변/대변), 분개(차변 합계/대변 합계), 분개 버튼 + +**분개 내역 예시**: +``` +차 현금 6,000 + 대 외상매출금 6,000 + +차 현금 3,000 +차 복리후생비 3,000 + 대 외상매출금 6,000 +``` + +#### 3.9.2 계정과목 설정 팝업 (P38) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 분류 셀렉트 박스 (추가) | 종류: 자산, 부채, 자본, 수익, 비용. 디폴트: 자산 | +| 2 | 추가 버튼 | 클릭: 계정과목 행 추가 | +| 3 | 분류 셀렉트 박스 (필터) | 종류: 전체, 자산, 부채, 자본, 수익, 비용. 디폴트: 전체 | +| 4 | 상태 버튼 | 클릭: 사용중/미사용 토글 | +| 5 | 삭제 버튼 | 클릭: 해당 계정과목 삭제 처리 | + +**계정과목 추가 필드**: 코드(예: 101), 분류(자산/부채/자본/수익/비용), 계정과목명(예: 현금) + +**목록 테이블 컬럼**: 코드, 계정과목명, 분류, 상태, 작업(삭제) + +**검색**: 코드 또는 이름 검색 + +#### 3.9.3 수기 전표 입력 팝업 (P39) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 구분 영역 | 클릭: 차변/대변 토글 | +| 2 | 계정과목 셀렉트 박스 | 검색 가능. 종류: 계정과목 목록 | +| 3 | 거래처 셀렉트 박스 | 검색 가능. 종류: 거래처 목록 | +| 4 | 행 추가 버튼 | 클릭: 아래 위치에 행 추가 | + +**거래 정보 필드**: 전표일자 *, 적요, 전표번호(자동생성, 예: JE-20260213-002) + +**분개 내역 필드** (행 단위): 구분(차변/대변), 계정과목, 금액, 거래처, 적요 + +**합계**: 차변 합계, 대변 합계 + +#### 3.9.4 분개 수정 팝업 (P40) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 차변 합계 표시 | - | +| 2 | 대변 합계 표시 | - | +| 3 | 균형 표시 | 차변=대변이면 "대차 균형", 다르면 "차이: {금액}" 표시 | + +**거래 정보**: 날짜, 금액, 구분(입금/출금), 적요, 계좌, 전표 적요 + +**분개 내역 필드** (행 단위): 구분(차변/대변), 계정과목, 금액, 거래처, 적요 + +**버튼**: 분개 수정, 취소, 분개 삭제, 행추가 + +--- + +## 4. 기준정보 + +### 4.1 바로빌 연동 관리 (P42-45) + +**경로**: 기준정보 > 바로빌 연동 관리 +**설명**: 바로빌 연동 정보를 관리합니다 + +#### 4.1.1 메인 화면 (P42) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 바로빌 로그인 정보 등록 버튼 | 클릭: 바로빌 로그인 정보 등록 팝업 표시 | +| 2 | 바로빌 회원가입 정보 등록 버튼 | 클릭: 바로빌 회원가입 정보 등록 팝업 표시 | +| 3 | 은행 빠른조회 서비스 등록 버튼 | 클릭: 은행 빠른조회 서비스 등록 팝업 표시 | +| 4 | 계좌 연동 등록 버튼 | 바로빌 연동 정보 없으면 Alert, 있으면 바로빌 계좌 등록 팝업 표시 | +| 5 | 카드 연동 등록 버튼 | 바로빌 연동 정보 없으면 Alert, 있으면 바로빌 카드 등록 팝업 표시 | +| 6 | 공인인증서 등록 버튼 | 바로빌 연동 정보 없으면 Alert, 있으면 바로빌 공인인증서 등록 팝업 표시 | + +**연동 플로우**: + +``` +바로빌 연동 +├── 바로빌 회원인 경우 → 로그인 정보 등록 +├── 바로빌 비회원인 경우 → 회원가입 정보 등록 +├── 계좌 연동 (2단계) +│ ├── 1단계: 각 은행 인터넷뱅킹 접속 → 빠른조회/간편서비스 → 계좌 등록 +│ └── 2단계: 바로빌 연동 계좌 정보 등록 → 은행/계좌번호/비밀번호 → 조회 주기 설정 +├── 카드 연동 → 카드사/아이디/비밀번호 입력 +└── 공인인증서 등록 → 홈택스 세금계산서 연동용 +``` + +#### 4.1.2 바로빌 로그인 정보 등록 팝업 (P43) + +| 필드 | 필수 | 설명 | +|------|------|------| +| 바로빌 아이디 | * | Barobill_id | +| 비밀번호 | * | - | + +**버튼**: 등록하기 (바로빌 로그인 처리), 취소 + +#### 4.1.3 바로빌 회원가입 정보 등록 팝업 (P44) + +| 필드 | 필수 | 설명 | +|------|------|------| +| 사업자등록번호 | * | 123-12-12345 | +| 상호명 | * | 회사명 | +| 대표자명 | * | 홍길동 | +| 업태 | - | - | +| 업종 | - | - | +| 주소 | - | - | +| 바로빌 아이디 | * | Barobill_id | +| 비밀번호 | * | - | +| 담당자명 | - | - | +| 담당자 연락처 | - | - | +| 담당자 이메일 | - | - | + +**버튼**: 등록하기 (바로빌 회원가입 처리), 취소 + +#### 4.1.4 은행 빠른조회 서비스 등록 팝업 (P45) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 은행 셀렉트 박스 | 종류: 은행 목록. 디폴트: 첫번째 은행 | +| 2 | 구분 셀렉트 박스 | 종류: 기업, 개인. 디폴트: 기업 | +| 3 | 바로가기 버튼 | 클릭: 선택한 은행+구분에 해당하는 URL로 링크 | + +--- + +### 4.2 계좌 관리 (P46-52) + +**경로**: 기준정보 > 계좌 관리 +**설명**: 연동 계좌 및 수기 계좌를 등록하고 관리합니다 + +#### 4.2.1 목록 화면 (P46) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 수기 계좌 등록 버튼 | 클릭: 계좌 상세_등록 화면으로 이동 | +| 2 | 구분 셀렉트 박스 | 종류: 전체, 은행계좌, 대출계좌, 증권계좌, 보험계좌. 디폴트: 전체 | +| 3 | 금융기관 셀렉트 박스 | 종류: 전체, 금융기관명 목록. 디폴트: 전체 | + +**상단 요약 카드**: 전체 계좌, 국내/외환 계좌, 대출 계좌, 증권 계좌, 보험 계좌 (각 개수) + +**구분 표시**: 수기 계좌(색상 표시), 연동 계좌(색상 표시) + +**목록 테이블 컬럼**: No., 구분, 유형, 금융기관, 계좌번호, 계좌명, 상태(사용/중지) + +#### 4.2.2 계좌 상세_은행 (P47) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 구분 셀렉트 박스 | 종류: 은행계좌, 대출계좌, 증권계좌, 보험계좌 | +| 2 | 유형 셀렉트 박스 | 은행: 보통예금, 정기예금, 정기적금, 외화예금, 기타 | +| 3 | 사용 셀렉트 박스 | 종류: 사용, 중지 | +| 4 | 계좌 정보 영역 | 은행 계좌일 경우에만 표시 | + +**기본 정보 필드**: 계좌번호, 구분, 유형, 금융기관, 예금주, 계좌명(상품명), 상태 + +**계좌 정보 필드** (은행 전용): 시작일, 만기일, 이율, 계약금액, 이월잔액, 비고 + +#### 4.2.3 계좌 상세_대출 (P48) + +**기본 정보**: 은행과 동일 구조 +**유형**: 시설자금, 운영자금, 기타 + +**대출 정보 필드** (대출 전용): + +| 필드 | 설명 | +|------|------| +| 시작일 | 대출 시작일 | +| 만기일 | 대출 만기일 | +| 이율 | 이자율 (%) | +| 대출금액 | 총 대출 금액 | +| 대출잔액 | 현재 남은 잔액 | +| 상환 방식 | 원리금균등 등 | +| 이자 납입 주기 | 매월 등 | +| 거치 기간 | 개월 수 | +| 월 상환액 | 월 상환 금액 | +| 담보물 | 내용 | +| 비고 | - | + +#### 4.2.4 계좌 상세_증권 (P49) + +**유형**: 직접투자, 펀드, 신탁, 기타 + +**증권 정보 필드** (증권 전용): + +| 필드 | 설명 | +|------|------| +| 시작일 | 투자 시작일 | +| 만기일 | - | +| 수익율 | % | +| 투자금액 | 총 투자 금액 | +| 평가액 | 현재 평가 금액 | +| 비고 | - | + +#### 4.2.5 계좌 상세_보험_단체보험 (P50) + +**유형**: 단체보험 + +**보험 정보 필드**: + +| 필드 | 설명 | +|------|------| +| 시작일 | 계약 시작일 | +| 만기일 | 계약 만기일 | +| 이율 | - | +| 계약금액 | 총 계약 금액 | +| 해약환급금 | 현재 환급금 | +| 납입 주기 | 월납, 분기납, 반기납, 연납, 일시납 | +| 증권번호 | - | +| 가입 인원 | 명 | +| 1인당 보험료 | 금액 | +| 납입 주기당 보험료 | 금액 | +| 비고 | - | + +#### 4.2.6 계좌 상세_보험_화재보험 (P51) + +**유형**: 화재보험 + +**보험 정보 필드**: 단체보험과 유사. 추가 필드: + +| 필드 | 설명 | +|------|------| +| 보험 대상물 | 내용 | +| 대상물 주소 | 주소 | + +#### 4.2.7 계좌 상세_보험_CEO보험 (P52) + +**유형**: CEO 보험 + +**보험 정보 필드**: 단체보험과 유사. 추가 필드: + +| 필드 | 설명 | +|------|------| +| 피보험자 | 이름 (기본정보의 예금주 대신) | +| 수익자 | 이름 | + +--- + +### 4.3 카드 관리 (P53-54) + +**경로**: 기준정보 > 카드 관리 +**설명**: 연동 카드 및 수기 카드를 등록하고 관리합니다 + +#### 4.3.1 목록 화면 (P53) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 수기 카드 등록 버튼 | 클릭: 카드 상세_등록 화면으로 이동 | +| 2 | 카드사 셀렉트 박스 | 종류: 전체, 카드사명 목록. 디폴트: 전체 | +| 3 | 상태 셀렉트 박스 | 종류: 전체, 사용, 중지. 디폴트: 전체 | + +**상단 요약 카드**: 전체 카드 수, 총 한도, 사용금액, 잔여한도 + +**구분 표시**: 수기 카드(색상 표시), 연동 카드(색상 표시) + +**목록 테이블 컬럼**: No., 카드사, 카드번호, 카드명, 부서, 사용자, 사용현황(금액 + 사용률 %), 상태(사용/중지) + +#### 4.3.2 카드 상세 (P54) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 카드사 셀렉트 박스 | 종류: 카드사명 목록 | +| 2 | 종류 셀렉트 박스 | 종류: 신용카드, 체크카드 | +| 3 | 결제일 셀렉트 박스 | 종류: 매월 1일, 5일, 10일, 14일, 15일, 20일, 25일, 27일 | +| 4 | 상태 셀렉트 박스 | 종류: 사용, 중지 | +| 5 | 부서 셀렉트 박스 | 검색 가능. 종류: 부서 목록 | +| 6 | 사용자 셀렉트 박스 | 검색 가능. 종류: 선택 부서 사원 목록 | +| 7 | 품의서 작성 버튼 | 클릭: 문서 작성_품의서 화면으로 이동 (품의 사유에 현재 카드사, 카드번호, 카드명 표시) | + +> **선결제 신청 플로우**: 품의서 작성 → 결재선 승인 → 출금 처리 → 장표 등록 → 연동카드일 경우 잔여한도 반영 + +**기본 정보 필드**: 카드명, 종류, 카드사, 카드번호, 유효기간(년도/월), 카드 명의자, CSV + +**사용자 정보 필드**: 부서, 사용자, 직책 + +**한도 정보**: 총 한도, 사용 금액, 잔여한도, 결제일 + +**기타**: 메모, 상태, 선결제 신청, 품의서 작성 안내 + +--- + +### 4.4 달력 관리 (P55-58) + +**경로**: 기준정보 > 달력 관리 +**설명**: 달력을 관리합니다 + +#### 4.4.1 달력 뷰 (P55) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 달력 탭 | 종류: 달력, 목록. 디폴트: 달력 | +| 2 | 대량 등록 버튼 | 클릭: 대량 등록팝업 표시 | +| 3 | 달력 일정 등록 버튼 | 클릭: 달력 상세_등록팝업 표시 | +| 4 | 월별 달력 영역 | 클릭: 달력 상세 팝업 표시. 연간 달력 표시 (1~12월) | + +**상단 요약**: 등록 건수, 총 휴일 일수, 공휴일 건수 + +#### 4.4.2 목록 뷰 (P56) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 유형 필터 셀렉트 박스 | 종류: 전체, 공휴일, 임시휴일, 대체휴일, 세무일, 회사일정. 디폴트: 전체 | +| 2 | 달력 목록 | 클릭: 달력 상세 팝업 표시 | + +**목록 테이블 컬럼**: No., 유형, 일정명, 시작일, 종료일, 일수, 반복, 메모 + +#### 4.4.3 달력 상세 팝업 (P57) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 유형 셀렉트 박스 | 종류: 공휴일, 임시휴일, 대체휴일, 세무일, 회사일정 | +| 2 | 매년 반복 체크박스 | 클릭: 체크 설정/해제 토글. 디폴트: 해제. 체크 설정 시 매년 등록 | + +**입력 필드**: 일정명 *, 유형 *, 기간 *, 메모, 매년 반복 + +**버튼**: 수정, 삭제 + +#### 4.4.4 대량 등록 팝업 (P58) + +**입력 형식**: +- `YYYY-MM-DD 일정명` - 단일 일자 +- `YYYY-MM-DD~YYYY-MM-DD 일정명` - 기간 (일정) +- `YYYY-MM-DD 일정명 [유형]` - 유형 지정 (공휴일/세무일정/회사지정/대체휴일/임시휴일) + +**예시 입력**: +``` +2026-01-01 신정 +2026-01-28~2026-01-30 설날연휴 +2026-03-01 삼일절 +2026-05-05 어린이날 +2026-05-15 부처님오신날 +2026-06-06 현충일 +2026-08-15 광복절 +2026-10-03 개천절 +2026-10-05~2026-10-07 추석연휴 +2026-10-09 한글날 +2026-12-25 크리스마스 +``` + +**버튼**: {N건} 등록, 취소 + +--- + +### 4.5 이관 기초자료 (P59-65) + +**경로**: 기준정보 > 이관 기초자료 +**설명**: 이관 기초자료를 관리합니다 + +#### 4.5.1 메인 화면 (P59-60) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 이관 기초자료 탭 | 종류: 거래처, 거래 내역, 계좌 내역, 세금계산서 내역, 업로드 이력. 디폴트: 거래처 | +| 2 | 양식 다운로드 버튼 | 클릭: 등록된 양식 CSV 다운로드 | +| 3 | 파일 선택 버튼 | 클릭: 파일 탐색기 팝업. CSV 1개만 등록. 50MB 이하 | +| 4 | 파일 변환 버튼 | 클릭: CSV 데이터를 정보 등록 영역에 변환값 표시 | + +**파일 변환 후 상태** (P60): + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 파일명 버튼 | 클릭: 파일 다운로드 처리 | +| 2 | 전체/개별 체크박스 | 클릭: 체크 설정/해제 토글. 디폴트: 전체 설정 | +| 3 | 등록 버튼 | 파일변환 완료 & 체크 항목 있을 경우만 활성화. 클릭: 확인 Alert → 등록 처리 | +| 4 | 오류 하이라이트 | 오류 사항 색상 표시. 마우스 롤 오버 시 문구 표시 | + +#### 4.5.2 거래처 CSV 스펙 (P61) + +| 컬럼명 | 필수 | 타입 | 최대길이 | 입력형식/규칙 | 예시 | 검증 | +|--------|------|------|----------|--------------|------|------| +| 사업자등록번호 | O | 텍스트 | 12자 | NNN-NN-NNNNN (하이픈유무무관) | 123-45-67890 | 10자리숫자, 하이픈자동처리, 중복검사 | +| 거래처명 | O | 텍스트 | 100자 | 법인명 또는 상호명 | (주)한국건설 | 빈값불가, 앞뒤공백 자동 trim | +| 대표자명 | - | 텍스트 | 50자 | 대표이사 성명 | 김대표 | - | +| 거래처유형 | O | 텍스트 | 10자 | 매출처/매입처/기타 | 매출 | 3가지 값만 허용 (대소문자 무관) | +| 업태 | - | 텍스트 | 50자 | 사업자등록증 업태 | 건설업 | - | +| 업종 | - | 텍스트 | 50자 | 사업자등록증 종목 | 시설공사, 토목공사 | - | +| 우편번호 | - | 텍스트 | 5자 | 5자리 숫자 | 06134 | 숫자 5자리 | +| 주소 | - | 텍스트 | 200자 | 도로명 또는 지번 주소 | 서울시 강남구 테헤란로 123 | - | +| 상세주소 | - | 텍스트 | 100자 | 건물명, 층, 호 | 삼성빌딩 5층 501호 | - | +| 대표전화번호 | - | 텍스트 | 20자 | NNN-NNNN-NNNN | 02-1234-5678 | 하이픈 자동 포맷 | +| 팩스번호 | - | 텍스트 | 20자 | NNN-NNNN-NNNN | 02-1234-5679 | 하이픈 자동 포맷 | +| 담당자명 | - | 텍스트 | 50자 | 실무 담당자 이름 | 홍길동 | - | +| 담당자연락처 | - | 텍스트 | 20자 | 휴대폰 또는 직통번호 | 010-1234-5678 | 하이픈 자동 포맷 | +| 이메일 | - | 텍스트 | 100자 | name@domain.com | hk@hancon.co.kr | 이메일 형식 검증 | + +> 사업자등록번호 중복 상태일 경우 마우스 롤오버 시: "기존 거래처정보가 업데이트됩니다." 문구 표시 + +#### 4.5.3 거래 내역 CSV 스펙 (P62) + +| 컬럼명 | 필수 | 타입 | 최대길이 | 입력형식/규칙 | 예시 | 검증 | +|--------|------|------|----------|--------------|------|------| +| 거래유형 | O | 텍스트 | 10자 | 매출/매입 | 매출 | 2가지 값만 허용 | +| 일자 | O | 날짜 | - | YYYY-MM-DD (엑셀 날짜셀 가능) | 2025-12-31 | - | +| 거래처명 | O | 텍스트 | 100자 | 거래처에 등록된 이름과 매칭 | (주)한국건설 | 미등록 → 오류 | +| 사업자등록번호 | O | 텍스트 | 12자 | 등록된 거래처 자동 매칭 | 123-45-67890 | 미등록 → 오류 | +| 품목명N | - | 텍스트 | 100자 | 품목명 | 품목명 | - | +| 공급가액 | O | 숫자 | - | 양의정수 (콤마/원기호 자동 제거) | 10000000 | 0 이하 불가, 콤마 허용 | +| 부가세 | - | 숫자 | - | 미입력 시 공급가액 x 10% 자동계산 | 1000000 | 음수 불가, 빈값 = 자동계산 | +| 적요 | - | 텍스트 | 200자 | 거래 내용 설명 | 12월 기성금 청구 | - | + +> - 거래처 관리에 해당 거래처 등록 필수 +> - 부가세 미입력 시 자동계산 (공급가액 x 10%), 직접 입력 시 자동계산 무시 +> - 품목명~적요까지 추가 입력 가능 +> - 거래처 유효하지 않을 경우: "등록되지 않은 거래처입니다." 문구 표시 +> - 공급가액/부가세 양수 아닐 경우: "금액은 0보다 커야합니다." 문구 표시 + +#### 4.5.4 계좌 내역 CSV 스펙 (P63) + +| 컬럼명 | 필수 | 타입 | 최대길이 | 입력형식/규칙 | 예시 | 검증 | +|--------|------|------|----------|--------------|------|------| +| 거래일시 | O | 날짜 | - | YYYY-MM-DD HH:MM:SS | 2025-12-31 12:21:12 | - | +| 금융기관명 | O | 텍스트 | 30자 | 정식 은행명 (약어 자동 매칭) | 우리은행 | 등록된 은행 목록과 매칭 | +| 계좌번호 | O | 텍스트 | 30자 | 계좌번호 (하이픈 포함/제외 모두 가능) | 1005-301-123456 | 등록된 계좌와 매칭 | +| 적요 | - | 텍스트 | 200자 | 거래 내용 설명 | 기성금 입금 | - | +| 입금 | - | 숫자 | - | 양의정수 (콤마 자동 제거) | 5000000 | 0 이하 불가 | +| 출금 | - | 숫자 | - | 양의정수 (콤마 자동 제거) | 5000000 | 0 이하 불가 | +| 잔액 | O | 숫자 | - | 해당 거래 후 계좌 잔액 | 25000000 | 잔액 정합성 검증용 | +| 취급점 | - | 텍스트 | 100자 | 증미점 | 증미점 | - | +| 상대계좌예금주명 | - | 텍스트 | 20자 | 예금주명 | (주)한국건설 | - | + +> - 계좌 관리에 해당 계좌 등록 필수 +> - 금융기관명/계좌번호 유효하지 않을 경우: "등록되지 않은 계좌입니다." 문구 표시 +> - 잔액 정합성 유효하지 않을 경우: "잔액이 입출금 누적과 불일치합니다." 문구 표시 +> - 금액 양수 아닐 경우: "금액은 0보다 커야합니다." 문구 표시 + +#### 4.5.5 세금계산서 내역 CSV 스펙 (P64) + +| 컬럼명 | 필수 | 타입 | 최대길이 | 입력형식/규칙 | 예시 | 검증 | +|--------|------|------|----------|--------------|------|------| +| 발행유형 | O | 텍스트 | 10자 | 매출/매입 | 매출 | 2가지 값만 허용 | +| 작성일자 | O | 날짜 | - | 세금계산서 작성일 (발행일과 다를 수 있음) | 2025-12-31 | - | +| 발급일자 | O | 날짜 | - | YYYY-MM-DD | 2025-12-31 | - | +| 거래처 | O | 텍스트 | 100자 | 거래처에 등록된 이름과 매칭 | (주)한국건설 | 미등록 → 오류 | +| 사업자번호 | O | 텍스트 | 12자 | 등록된 거래처 자동 매칭 | 123-45-67890 | 미등록 → 오류 | +| 과세형태 | - | 텍스트 | 10자 | 과세/면세 | 과세 | 미입력 시 "과세" 기본값 | +| 품목 | - | 텍스트 | 200자 | 대표 품목/서비스명 | 시설공사 | - | +| 공급가액 | O | 숫자 | - | 양의정수 | 50000000 | 0 이하 불가 | +| 세액 | - | 숫자 | - | 미입력 시 공급가액 x 10% 자동 | 5000000 | - | +| 합계 | - | 숫자 | - | 합계 | 55000000 | 공급가액 + 세액 검증 | +| 영수청구 | - | 텍스트 | 10자 | 영수/청구 | 청구 | 미입력 시 "청구" 기본값 | + +> - 거래처 유효하지 않을 경우: "등록되지 않은 거래처입니다." 문구 표시 +> - 공급가액/부가세 양수 아닐 경우: "금액은 0보다 커야합니다." 문구 표시 + +#### 4.5.6 업로드 이력 (P65) + +| # | 요소 | 설명 | +|---|------|------| +| 1 | 이관 유형 필터 셀렉트 박스 | 종류: 전체, 거래처, 거래 내역, 계좌 내역, 세금계산서 내역. 디폴트: 전체 | +| 2 | 파일명 버튼 | 클릭: 파일 다운로드 처리 | + +**기간 필터**: 지난달, D-5월, D-4월, D-3월, D-2월, 이번달 + +**목록 테이블 컬럼**: No., 업로드 일시, 이관 유형, 전체(건수), 성공(건수), 파일명, 등록자 + +--- + +## 공통 UI 패턴 정리 + +### 기간 필터 유형 + +| 유형 | 사용 화면 | +|------|----------| +| 전전월/어제/오늘/전월/당월/당해년도 | 거래처 관리 | +| 1주일/1개월/3개월 + 날짜범위 | 세금계산서 발행 | +| 1분기/2분기/3분기/4분기 + 날짜범위 | 세금계산서 관리 | +| 지난달/D-5월~D-2월/이번달 | 계좌 입출금, 카드 사용, 상품권, 일반전표, 계좌관리, 카드관리, 이관기초자료 | + +### 데이터 구분 표시 (색상) + +모든 연동 가능한 화면에서 수기 데이터와 연동 데이터를 색상으로 구분: +- 수기 데이터 (한 색상) +- 연동 데이터 (다른 색상) + +### 엑셀 다운로드 + +다음 화면에서 엑셀 다운로드 기능 제공: +- 세금계산서 관리 +- 계좌 입출금 내역 +- 카드 사용 내역 + +### 분개 관련 + +분개 기능이 있는 화면: +- 세금계산서 관리 (매입) +- 카드 사용 내역 +- 일반 전표 입력 + +분개 공통 요소: +- 차변/대변 토글 +- 계정과목 셀렉트 박스 (검색 가능) +- 대차 균형 표시 +- 분개 수정/삭제 + +--- + +## 외부 연동 + +### 바로빌 API + +| 연동 항목 | 용도 | +|-----------|------| +| 전자세금계산서 발행 | 세금계산서 발행 화면에서 바로빌 API를 통한 발행 | +| 홈택스 세금계산서 조회 | 세금계산서 관리에서 홈택스 신고 내역 조회 | +| 계좌 연동 | 은행 빠른조회 서비스를 통한 실시간 계좌 조회 | +| 카드 연동 | 카드사 연동을 통한 카드 사용 내역 자동 수집 | +| 공인인증서 | 홈택스 세금계산서 연동용 인증서 등록 | + +### 사업자등록증 OCR + +거래처 등록 시 사업자등록증 파일 업로드 → OCR 자동 인식 → 거래처 정보 자동 입력 + +--- + +**최종 업데이트**: 2026-02-23 diff --git a/plans/integrated-master-plan.md b/plans/integrated-master-plan.md new file mode 100644 index 0000000..7490860 --- /dev/null +++ b/plans/integrated-master-plan.md @@ -0,0 +1,382 @@ +# 통합 개선 계획 — 제품코드 추적성 + 검사 단위 구조 정비 + +> **작성일**: 2026-02-27 +> **목적**: 두 개선 계획(제품코드 추적성, 검사 단위 구조)을 하나의 순차적 실행 계획으로 통합 +> **상태**: 🔄 Phase 0~3 완료, Phase 4 이후 대기 +> **원본 문서**: +> - [`product-code-traceability-plan.md`](./product-code-traceability-plan.md) (아카이브 참조) +> - [`document-system-improvement-plan.md`](./document-system-improvement-plan.md) (아카이브 참조) +> - [`document-system-improvement-review.md`](./document-system-improvement-review.md) (정책 결정 16건) +> **테스트**: [`integrated-test-scenarios.md`](./integrated-test-scenarios.md) (기능 단위 11개 FU) + +--- + +## 📍 현재 진행 상태 + +| 항목 | 내용 | +|------|------| +| **마지막 완료 작업** | Phase 3 - 절곡 검사 동적 구현 (inspection-config API + 트랜잭션 보강) | +| **다음 작업** | Phase 4 (절곡 재공품 + 결재 워크플로우) — 후순위 | +| **진행률** | 5/7 Phase (Phase 0+1+2A+2B+3 완료) | +| **마지막 업데이트** | 2026-02-27 | + +--- + +## 1. 왜 통합이 필요한가 + +두 계획은 **의존성이 교차**한다: + +- 검사 단위 구조 정비(절곡 동적화)는 `work_order_items.options`에 `product_code`가 있어야 동작 +- `product_code` 전파 버그를 먼저 수정하지 않으면 검사 API(`inspection-config`)가 불완전 +- 별도로 작업하면 순서 혼선, 중복 작업, 회귀 위험 발생 + +**통합 효과**: +- 의존성 순서를 강제하여 작업 꼬임 방지 +- 병렬 가능 작업 식별으로 효율 극대화 +- 진행 상태를 한 곳에서 관리 + +--- + +## 2. 통합 Phase 총괄 + +| Phase | 명칭 | 원본 | 의존성 | 상태 | 상세 | +|:-----:|------|------|--------|:----:|------| +| **0** | 사전 데이터 조사 | product-code P0 | 없음 | ✅ | [Phase 0-1 상세](./integrated-phase-0-1.md) | +| **1** | product_code 전파 버그 수정 | product-code P1 | Phase 0 | ✅ | [Phase 0-1 상세](./integrated-phase-0-1.md) | +| **2A** | 절곡 검사 분석/설계 | document-system P1 | 없음 (**Phase 1과 병렬**) | ✅ | [Phase 2 상세](./integrated-phase-2.md) | +| **2B** | 견적/수주 정합성 + 품질 FK | product-code P2+P3 | Phase 1 | ✅ | [Phase 2 상세](./integrated-phase-2.md) | +| **3** | 절곡 검사 동적 구현 | document-system P2 | Phase 1 + 2A | ✅ | [Phase 3 상세](./integrated-phase-3.md) | +| **4** | 절곡 재공품 + 결재 워크플로우 | document-system P3 | Phase 3 | ⏭️ | 마스터 요약만 | +| **5** | 완제품 마스터 + 출하 연결 | product-code P4 | Phase 2B | ⏭️ | 마스터 요약만 | +| **6** | 3관점 검사 + 수주별 뷰 | document-system P4 | Phase 3 + 기획자 | ⏭️ | 마스터 요약만 | + +--- + +## 3. 의존성 다이어그램 + +``` + ┌─────────────────────────────────────────────┐ + │ 실행 타임라인 │ + └─────────────────────────────────────────────┘ + +Phase 0 ─── Phase 1 ──┬── Phase 2B ──── Phase 5 + (조사) (P/C 수정) │ (견적/품질) (FG 마스터) + │ +Phase 2A ──────────────┼── Phase 3 ──── Phase 4 ──── Phase 6 + (절곡 분석) │ (절곡 구현) (재공품) (3관점) + │ + ※ Phase 1 + 2A 병렬 가능 + ※ Phase 2B + 3 준비 부분 병렬 가능 + ※ Phase 4 + 5 독립 (부분 병렬 가능) + +크리티컬 패스: Phase 0 → 1 → 3 → 4 → 6 +``` + +### 병렬 실행 가능 조합 + +| 조합 | 설명 | 조건 | +|------|------|------| +| Phase 1 + 2A | product_code 수정 + 절곡 분석 동시 진행 | 2A는 코드 변경 없음 (분석만) | +| Phase 2B + 3 시작 | 견적/품질 + 절곡 구현 | Phase 1 완료 필수 | +| Phase 4 + 5 | 절곡 재공품 + FG 마스터 | 각각 Phase 3, 2B 완료 | + +--- + +## 4. 공통 원칙 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 🎯 통합 핵심 원칙 │ +├─────────────────────────────────────────────────────────────────┤ +│ 1. 컬럼 추가 정책: FK/조인키만 컬럼, 나머지는 options JSON │ +│ 2. 기존 데이터 보존: 파괴적 변경 없이 점진적 개선 │ +│ 3. 역추적 가능: 어떤 단계에서든 원래 제품코드로 돌아갈 수 있어야 함│ +│ 4. 네이밍 통일: Backend JSON=snake_case, Frontend=camelCase │ +│ 5. 기존 동작 보존: 스크린/슬랫/조인트바 검사는 건드리지 않음 │ +│ 6. TemplateInspectionContent 통합: 신규 개발은 여기서 (C3) │ +│ 7. BendingInspectionContent 레거시 동결: 유지만, 신규 기능 X │ +│ 8. row_index = 개소 통일: 구성품은 field_key 인코딩 (C1) │ +│ 9. EAV + options 병행: 두 데이터 경로 독립 운용 (C2) │ +│ 10. 롤백 = 템플릿 유무: document_template_id NULL → 레거시 (I4) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 변경 승인 정책 + +| 분류 | 예시 | 승인 | +|------|------|------| +| ✅ 즉시 가능 | options JSON 필드 추가, React 컴포넌트 내부 리팩토링, 프론트 표시 변경 | 불필요 | +| ⚠️ 컨펌 필요 | 서비스 로직 변경, 마이그레이션, API 엔드포인트 추가, 양식 시더 수정 | **필수** | +| 🔴 금지 | 기존 테이블 컬럼 삭제, 기존 스크린/슬랫 검사 로직 변경 | 별도 협의 | + +--- + +## 5. 핵심 데이터 흐름 (통합 TO-BE) + +``` +견적(quotes) + └─ product_code 컬럼 ✅ (Phase 2B) + └─ calculation_inputs → items[].productCode + │ + ▼ (createFromQuote) +수주(orders) + └─ order_nodes.options → ✅ product_code, product_name + │ + ▼ (createProductionOrder) +작업지시(work_orders) + ├─ work_order_items.options → ✅ product_code (Phase 1 수정) + ├─ inspection-config API → ✅ 공정 자동 판별 + BOM 기반 구성품 (Phase 3) + ├─ TemplateInspectionContent → ✅ 동적 절곡 검사 (Phase 3) + └─ document_data EAV → ✅ C1 field_key 인코딩 + │ + ▼ +품질검사(inspections) + └─ ✅ work_order_id FK (Phase 2B) + │ + ▼ +출하(shipments) + └─ ✅ product_code 포함 (Phase 5) +``` + +--- + +## 6. Phase별 요약 + +### Phase 0: 사전 데이터 조사 ⏳ + +**목표**: 마이그레이션 영향 범위 파악 (읽기 전용, 위험 없음) + +- SQL 4개 실행: order_nodes product_code 보유율, work_order_items source 비율, soft delete 건수, lot_no 중복 +- 결과에 따라 Phase 1 보정 전략 조정 + +→ [상세: integrated-phase-0-1.md](./integrated-phase-0-1.md) + +--- + +### Phase 1: product_code 전파 버그 수정 ⏳ + +**목표**: 모든 work_order_items 생성/수정 경로에서 product_code, product_name 전달 + +- 백엔드 5개 코드 경로 수정 (OrderService, WorkOrderService) +- 기존 데이터 보정 마이그레이션 (스냅샷 백업 후) +- 프론트 WorkerScreen/ProductionDashboard에 제품코드 표시 +- **배포 순서**: 백엔드 → 마이그레이션 → 프론트 + +→ [상세: integrated-phase-0-1.md](./integrated-phase-0-1.md) + +--- + +### Phase 2A: 절곡 검사 분석/설계 ⏳ (**Phase 1과 병렬 가능**) + +**목표**: 절곡 구성품(검사 항목) 정보를 API에서 제공하는 구조 설계 + +- items/BOM 테이블에서 KWE01/KSS01/KSS02 구성품 확인 +- 마감유형(S1/S2/S3)별 차이 분석 +- DEFAULT_GAP_PROFILES 기준치 5130 대조 +- inspection-config 범용 API 설계 + +→ [상세: integrated-phase-2.md](./integrated-phase-2.md) + +--- + +### Phase 2B: 견적/수주 정합성 + 품질 FK ⏳ + +**목표**: quotes.product_code 활용 + inspections ↔ work_orders FK 연결 + +- 견적 저장 시 quotes.product_code 저장 +- inspections 테이블에 work_order_id FK 마이그레이션 +- 기존 데이터 보정 (lot_no 기반 역추적) +- **Phase 2B 내부에서 견적/품질 작업은 병렬 가능** (독립 경로) + +→ [상세: integrated-phase-2.md](./integrated-phase-2.md) + +--- + +### Phase 3: 절곡 검사 동적 구현 ✅ + +**목표**: API 기반 동적 구성품 로딩으로 고정 로직 대체 + +- inspection-config API 구현 (BelongsToTenant 필수) +- TemplateInspectionContent buildBendingProducts → API 연동 +- document_data EAV 저장/복원 검증 (C1 field_key) +- createInspectionDocument 트랜잭션 보강 (I2) +- 레거시(Path A) + 신규(Path B) 독립 동작 확인 + +→ [상세: integrated-phase-3.md](./integrated-phase-3.md) + +--- + +### Phase 4: 절곡 재공품 + 결재 워크플로우 ⏭️ + +**목표**: BendingWip 양식 추가 + 결재 프론트 연동 + +| # | 작업 항목 | 비고 | +|---|----------|------| +| 4.1 | 절곡 재공품 mng 양식 시더 추가 | BendingWipInspectionContent 대응 | +| 4.2 | 결재 워크플로우 프론트 연동 | 작성→검토→승인 3단계 | +| 4.3 | React 기존 하드코딩 컴포넌트 전환 결정 | 프론트 담당자 협의 | + +> 실행 시점에 상세 문서 별도 작성 + +--- + +### Phase 5: 완제품 마스터 + 출하 연결 ⏭️ + +**목표**: FG 품목 등록 + 출하 시 제품코드 포함 + orders.item_id + +| # | 작업 항목 | 비고 | +|---|----------|------| +| 5.1 | 완제품(FG) 품목 자동 등록 방안 설계 | 견적 확정 시 or 수주 확정 시 | +| 5.2 | orders.item_id 설정 | FG 품목 등록 후 가능 | +| 5.3 | shipment_items에 product_code 포함 | 부분 출하 시 개소별 매핑 고려 | +| 5.4 | work_order_items.product_code 컬럼 승격 검토 | 통계 쿼리 성능용 | +| 5.5 | E2E 추적 검증 | 견적→출하→품질 전 구간 | + +> 실행 시점에 상세 문서 별도 작성 + +--- + +### Phase 6: 3관점 검사 + 수주별 뷰 ⏭️ + +**목표**: 구성품별/개소별/수주별 3관점 검사 구조 + 수주별 읽기 전용 뷰 + +| # | 작업 항목 | 비고 | +|---|----------|------| +| 6.1 | 기획자와 3관점 화면 설계 협의 (I3) | 화면 구성·데이터 매핑·UI 설계 | +| 6.2 | 수주별 읽기 전용 뷰 구현 (I7) | 입력=개소별, 출력=수주별 | +| 6.3 | 개소별↔구성품별↔수주별 데이터 매핑 | | +| 6.4 | 5130 recordscreen JSON → EAV 변환 | 이관 설계 | + +> 기획자 협의 후 상세 문서 별도 작성 + +--- + +## 7. 통합 성공 기준 + +### Phase 0-1 (product_code) + +| 기준 | 수치 목표 | +|------|----------| +| WorkerScreen 제품코드 표시 | 100% | +| 신규 작업지시 product_code 포함 | NOT NULL | +| 기존 데이터 보정율 (source_order_item_id 있는 건) | 90% 이상 | +| 기존 기능 회귀 | 에러 0건 | +| API 성능 영향 | 5% 미만 | + +### Phase 2A-2B (분석/견적/품질) + +| 기준 | 수치 목표 | +|------|----------| +| KWE01/KSS01/KSS02 구성품 분석 완료 | 3종 이상 | +| DEFAULT_GAP_PROFILES 5130 대조 | 완료 | +| quotes.product_code 저장 | 정상 동작 | +| inspections.work_order_id FK 보정 정확도 | 95% 이상 | + +### Phase 3 (절곡 동적 구현) + +| 기준 | 수치 목표 | +|------|----------| +| 제품코드별 다른 구성품 표시 | 3종 이상 지원 | +| 마감유형별 구성품 변경 | 정상 동작 | +| 기존 절곡 데이터 호환 (Path A + B) | 100% | +| inspection-config API 응답 시간 | < 200ms | +| 스크린/슬랫 회귀 | 에러 0건 | +| document_data 저장 정합성 | 100% | + +--- + +## 8. 통합 컨펌 대기 목록 + +| # | Phase | 항목 | 변경 내용 | 상태 | +|---|:-----:|------|----------|:----:| +| 1 | 0 | 사전 조사 실행 | SQL 4개 (읽기 전용) | ⚠️ 대기 | +| 2 | 1 | product_code 전파 수정 | 5개 코드 경로 options 복사 변경 | ⚠️ 대기 | +| 3 | 1 | 데이터 보정 마이그레이션 | 기존 work_order_items 역추적 보정 | ⚠️ 대기 | +| 4 | 2A | inspection-config API 설계 | 범용 API 엔드포인트 추가 | ⚠️ 대기 | +| 5 | 2B | inspections.work_order_id FK | 마이그레이션 + 로직 수정 | ⚠️ 대기 | +| 6 | 3 | inspection-config API 구현 | 공정 자동 판별 + BOM 구성품 | ⚠️ 대기 | +| 7 | 5 | 완제품 마스터 자동 등록 | items 테이블에 FG 품목 생성 | ⚠️ 대기 | +| 8 | 6 | 3관점 검사 화면 설계 | 기획자 협의 필요 | ⏭️ | + +--- + +## 9. 롤백 전략 (통합) + +| Phase | 위험도 | 롤백 방법 | +|:-----:|:------:|----------| +| 0 | 없음 | 읽기 전용 | +| 1 (options 추가) | 낮음 | options에서 `product_code`, `product_name` 키 제거 스크립트 | +| 1 (데이터 보정) | 중간 | `work_order_items_backup_product_code` 백업 테이블에서 복원 | +| 2B (inspections FK) | 중간 | `work_order_id` 컬럼 drop 마이그레이션 (down 메서드) | +| 3 (절곡 동적화) | 낮음 | document_template_id NULL → 레거시 컴포넌트 자동 복귀 (I4) | +| 5 (FG 품목) | 높음 | `auto_generated` 플래그 기반 식별 후 삭제 | + +--- + +## 10. 참고 파일 (통합) + +### 백엔드 + +| 파일 | 역할 | 관련 Phase | +|------|------|:----------:| +| `api/app/Services/OrderService.php` | 수주→작업지시 변환 (L1410) | 1 | +| `api/app/Services/WorkOrderService.php` | 작업지시 서비스 (L287, L311, L416) | 1, 3 | +| `api/app/Services/Quote/QuoteService.php` | 견적 서비스 | 2B | +| `api/app/Services/InspectionService.php` | 품질검사 서비스 | 2B | +| `api/app/Services/DocumentService.php` | 문서 CRUD | 3 | + +### 프론트엔드 + +| 파일 | 역할 | 관련 Phase | +|------|------|:----------:| +| `react/.../WorkerScreen/actions.ts` | 작업자 화면 서버 액션 | 1 | +| `react/.../WorkerScreen/index.tsx` | 작업자 화면 메인 | 1 | +| `react/.../documents/TemplateInspectionContent.tsx` | 양식 기반 동적 렌더링 (**통합 방향**) | 3 | +| `react/.../documents/BendingInspectionContent.tsx` | 절곡 레거시 (**동결**) | — | +| `react/.../documents/InspectionReportModal.tsx` | 검사 모달 래퍼 | 3 | + +### 참고 문서 + +| 문서 | 경로 | 용도 | +|------|------|------| +| 원본: 제품코드 추적성 | `docs/plans/product-code-traceability-plan.md` | 상세 코드/쿼리 참조 | +| 원본: 검사 단위 구조 | `docs/plans/document-system-improvement-plan.md` | 상세 설계/정책 참조 | +| 리뷰 정책 결정 | `docs/plans/document-system-improvement-review.md` | 16건 정책 결정 | +| 문서 시스템 마스터 | `docs/plans/document-system-master.md` | 전체 Phase 관리 | +| API 규칙 | `API_RULES.md` | Service-First, FormRequest | +| DB 스키마 | `docs/specs/database-schema.md` | 테이블 구조 | + +--- + +## 11. 변경 이력 + +| 날짜 | 항목 | 변경 내용 | +|------|------|----------| +| 2026-02-27 | 통합 문서 작성 | product-code + document-system 2개 계획을 7 Phase 통합 계획으로 병합 | +| 2026-02-27 | Phase 2A 완료 | 절곡 검사 분석/설계 완료. dynamic_bom 발견, 5130 대조 완료, inspection-config API 재설계 | +| 2026-02-27 | Phase 2B 완료 | 견적 product_code 자동추출, inspections.work_order_id FK, 데이터 보정 25건 | +| 2026-02-27 | Phase 3 완료 | inspection-config API(3.1), TemplateInspectionContent API 연동(3.2), EAV 호환 확인(3.3+3.4), 트랜잭션 보강(3.5) | + +--- + +## 12. 세션 관리 정책 + +### 세션 시작 시 +``` +1. 이 문서(integrated-master-plan.md) 읽기 +2. 진행 상태 테이블 확인 → 마지막 완료 작업 파악 +3. 해당 Phase 상세 문서 읽기 +4. 다음 작업 시작 +``` + +### 작업 중 관리 +- Phase 완료 시 이 문서의 진행 상태 테이블 업데이트 +- 해당 Phase 상세 문서도 업데이트 +- 컨펌 필요 사항 발생 시 컨펌 대기 목록에 추가 + +### 세션 종료 시 +- 변경 이력 섹션에 최종 업데이트 기록 + +--- + +*이 문서는 `product-code-traceability-plan.md`와 `document-system-improvement-plan.md`를 통합한 마스터 계획입니다.* \ No newline at end of file diff --git a/plans/production-deployment-plan.md b/plans/production-deployment-plan.md new file mode 100644 index 0000000..bbcde30 --- /dev/null +++ b/plans/production-deployment-plan.md @@ -0,0 +1,1099 @@ +# SAM 운영 환경 배포 계획서 + +> **작성일**: 2026-02-22 +> **상태**: 계획 수립 +> **대상**: MS3 정식 런칭 (2026-02-28) +> **작성자**: 개발팀 + +--- + +## 1. 개요 + +### 1.1 목적 + +SAM 프로젝트의 MS3(정식 런칭, 2026-02-28)을 위해 개발 환경(`dev.codebridge-x.com`)에서 운영 환경(`codebridge-x.com`)으로의 전환을 체계적으로 수행한다. 수동 배포 방식에서 Jenkins CI/CD 기반 자동화 배포로 전환하여 안정적인 운영 체계를 구축한다. + +### 1.2 핵심 원칙 + +- 🔴 **무중단 전환**: 개발 환경 서비스에 영향 없이 운영 환경을 구축한다 +- 🔴 **롤백 가능**: 모든 배포는 즉시 롤백 가능해야 한다 +- 🔴 **자동화 우선**: 반복 작업은 Jenkins 파이프라인으로 자동화한다 +- 🟡 **점진적 전환**: 한 번에 전환하지 않고 Phase별로 검증한다 + +### 1.3 현재 환경 vs 목표 환경 + +| 항목 | 현재 (개발) | 목표 (운영) | +|------|------------|------------| +| **서버** | 114.203.209.83 (2코어/3.8GB) | 신규 서버 (4코어/8GB 이상) | +| **도메인** | `dev.codebridge-x.com` | `codebridge-x.com` | +| **배포 방식** | 수동 (git pull + SSH) | Jenkins CI/CD 자동화 | +| **SSL** | 자체 서명 인증서 | Let's Encrypt | +| **DB** | `samdb` (개발/운영 공용) | `sam_prod` (운영 전용) | +| **모니터링** | 없음 | 헬스체크 + Slack 알림 | +| **백업** | 수동 | 자동 일일 백업 | + +### 1.4 관련 문서 + +| 문서 | 경로 | +|------|------| +| 런칭 로드맵 | `guides/project-launch-roadmap.md` | +| .env 동기화 | `guides/production-env-sync.md` | +| Docker 환경 스펙 | `specs/docker-setup.md` | +| 보안 정책 | `architecture/security-policy.md` | + +--- + +## 2. 환경 전략 + +### 2.1 3-Tier 환경 분리 + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ 로컬 (WSL) │ │ 개발 서버 │ │ 운영 서버 │ +│ Docker 기반 │ │ Bare-metal │ │ Bare-metal │ +│ │ │ │ │ │ +│ dev.sam.kr │────→│ dev.codebridge │────→│ codebridge-x │ +│ (hosts 매핑) │ │ -x.com │ │ .com │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + 개발/테스트 스테이징/CI/CD 정식 서비스 +``` + +### 2.2 도메인 매핑 + +| 서비스 | 로컬 (WSL Docker) | 개발 서버 | 운영 서버 | +|--------|-------------------|----------|----------| +| **React (사용자)** | `dev.sam.kr` | `dev.codebridge-x.com` | `codebridge-x.com` | +| **API** | `api.sam.kr` | `api.dev.codebridge-x.com` | `api.codebridge-x.com` | +| **MNG (관리자)** | `mng.sam.kr` | `mng.dev.codebridge-x.com` | `mng.codebridge-x.com` | +| **Sales** | `sales.sam.kr` | `sales.dev.codebridge-x.com` | `sales.codebridge-x.com` | +| **5130 (레거시)** | `5130.sam.kr` | - | - | +| **Gitea** | - | `114.203.209.83:3000` | - | + +### 2.3 .env 분기 전략 + +> 상세 동기화 절차는 `guides/production-env-sync.md` 참조 + +| 환경 변수 | 로컬 (Docker) | 개발 서버 | 운영 서버 | +|-----------|--------------|----------|----------| +| `APP_ENV` | `local` | `development` | `production` | +| `APP_DEBUG` | `true` | `true` | `false` | +| `APP_URL` | `https://api.sam.kr` | `https://api.dev.codebridge-x.com` | `https://api.codebridge-x.com` | +| `DB_HOST` | `sam-mysql-1` | `localhost` | `localhost` | +| `DB_DATABASE` | `samdb` | `samdb` | `sam_prod` | +| `LOG_CHANNEL` | `stack` | `stack` | `stack` | +| `LOG_LEVEL` | `debug` | `debug` | `warning` | +| `BAROBILL_TEST_MODE` | `true` | `true` | `false` | + +--- + +## 3. 운영 서버 아키텍처 + +### 3.1 서버 스펙 권장 + +| 항목 | 최소 사양 | 권장 사양 | 사유 | +|------|----------|----------|------| +| **CPU** | 4코어 | 8코어 | PHP-FPM 3풀 + Node.js 동시 운영 | +| **RAM** | 8GB | 16GB | PHP-FPM 풀당 ~1.5GB + MySQL ~2GB | +| **디스크** | 100GB SSD | 200GB SSD | DB + 로그 + 파일 스토리지 | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | 장기 지원 | + +> **경고: 현재 개발 서버(2코어/3.8GB)에서는 React 빌드 시 메모리 부족으로 실패한다. 운영 서버는 최소 8GB를 확보해야 한다.** + +### 3.2 Bare-metal 운영 결정 + +운영 서버는 Docker를 사용하지 않고 Bare-metal로 구성한다 (현재 개발 서버와 동일 방식). + +| 항목 | Docker | Bare-metal (선택) | +|------|--------|------------------| +| 리소스 오버헤드 | 15~20% | 없음 | +| 서버 스펙 요구 | 높음 | 낮음 | +| 운영 복잡도 | 중간 | 낮음 | +| 현재 개발 서버 | - | 이미 이 방식 사용 중 | + +### 3.3 서비스 레이아웃 + +``` +┌────────────────────────────────────────────────────────────┐ +│ 운영 서버 │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ Nginx (Reverse Proxy + Static Files) │ │ +│ │ :80 → HTTPS redirect │ │ +│ │ :443 → PHP-FPM / Node.js │ │ +│ └──────────┬──────────┬──────────┬────────────────────┘ │ +│ │ │ │ │ +│ ┌──────────┴┐ ┌──────┴──────┐ ┌┴───────────┐ │ +│ │ PHP-FPM │ │ PHP-FPM │ │ PHP-FPM │ │ +│ │ pool: api │ │ pool: mng │ │ pool: sales│ │ +│ │ :9001 │ │ :9002 │ │ :9003 │ │ +│ └───────────┘ └─────────────┘ └────────────┘ │ +│ │ +│ ┌──────────────┐ ┌──────────────────────────────┐ │ +│ │ Node.js │ │ Supervisor │ │ +│ │ (React SSR) │ │ - API Queue Worker (x1) │ │ +│ │ :3000 │ │ - MNG Queue Worker (x2) │ │ +│ └──────────────┘ │ - API Scheduler │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ MySQL 8.0 (sam_prod) │ │ +│ │ :3306 (localhost only) │ │ +│ └──────────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────────┘ +``` + +### 3.4 PHP-FPM 풀 설정 + +현재 Docker Supervisor 설정 기반으로 운영 서버 PHP-FPM 풀을 구성한다. + +**API 풀** (`/etc/php/8.4/fpm/pool.d/api.conf`): + +```ini +[api] +user = www-data +group = www-data +listen = /run/php/php8.4-fpm-api.sock +pm = dynamic +pm.max_children = 10 +pm.start_servers = 3 +pm.min_spare_servers = 2 +pm.max_spare_servers = 5 +pm.max_requests = 500 +request_terminate_timeout = 300 +chdir = /home/webservice/api +``` + +**MNG 풀** (`/etc/php/8.4/fpm/pool.d/mng.conf`): + +```ini +[mng] +user = www-data +group = www-data +listen = /run/php/php8.4-fpm-mng.sock +pm = dynamic +pm.max_children = 15 +pm.start_servers = 5 +pm.min_spare_servers = 3 +pm.max_spare_servers = 8 +pm.max_requests = 500 +request_terminate_timeout = 300 +chdir = /home/webservice/mng +``` + +**Sales 풀** (`/etc/php/8.4/fpm/pool.d/sales.conf`): + +```ini +[sales] +user = www-data +group = www-data +listen = /run/php/php8.4-fpm-sales.sock +pm = dynamic +pm.max_children = 5 +pm.start_servers = 2 +pm.min_spare_servers = 1 +pm.max_spare_servers = 3 +pm.max_requests = 500 +chdir = /home/webservice/sales +``` + +### 3.5 Supervisor 프로세스 설정 + +현재 Docker 컨테이너의 `supervisord.conf`를 운영 서버용으로 변환한다. + +**API Queue Worker** (`/etc/supervisor/conf.d/sam-api-worker.conf`): + +```ini +[program:sam-api-worker] +command=php /home/webservice/api/artisan queue:work database --queue=api,default --sleep=3 --tries=3 --timeout=1800 --max-jobs=100 --max-time=3600 +process_name=%(program_name)s_%(process_num)02d +numprocs=1 +directory=/home/webservice/api +autostart=true +autorestart=true +startsecs=5 +startretries=3 +stopwaitsecs=1830 +user=www-data +stdout_logfile=/var/log/sam/api-queue-worker.log +stdout_logfile_maxbytes=5MB +stderr_logfile=/var/log/sam/api-queue-worker-error.log +stderr_logfile_maxbytes=5MB +``` + +**MNG Queue Worker** (`/etc/supervisor/conf.d/sam-mng-worker.conf`): + +```ini +[program:sam-mng-worker] +command=php /home/webservice/mng/artisan queue:work database --queue=mng,default --sleep=3 --tries=1 --timeout=1800 --max-jobs=10 --max-time=3600 +process_name=%(program_name)s_%(process_num)02d +numprocs=2 +directory=/home/webservice/mng +autostart=true +autorestart=true +startsecs=5 +startretries=3 +stopwaitsecs=1830 +user=www-data +stdout_logfile=/var/log/sam/mng-queue-worker.log +stdout_logfile_maxbytes=5MB +stderr_logfile=/var/log/sam/mng-queue-worker-error.log +stderr_logfile_maxbytes=5MB +``` + +**API Scheduler** (`/etc/supervisor/conf.d/sam-api-scheduler.conf`): + +```ini +[program:sam-api-scheduler] +command=bash -c "while true; do php /home/webservice/api/artisan schedule:run --no-interaction; sleep 60; done" +process_name=%(program_name)s +numprocs=1 +directory=/home/webservice/api +autostart=true +autorestart=true +startsecs=0 +user=www-data +stdout_logfile=/var/log/sam/api-scheduler.log +stdout_logfile_maxbytes=5MB +stderr_logfile=/var/log/sam/api-scheduler-error.log +stderr_logfile_maxbytes=5MB +``` + +### 3.6 필수 패키지 설치 + +현재 Docker Dockerfile 기반으로 운영 서버에 설치할 패키지 목록: + +```bash +# PHP 8.4 + 확장 모듈 (API + MNG 공통) +apt install php8.4-fpm php8.4-mysql php8.4-zip php8.4-intl \ + php8.4-xml php8.4-soap php8.4-mbstring php8.4-curl + +# MNG 전용 (GD + LibreOffice + FFmpeg) +apt install php8.4-gd libreoffice-writer-nogui \ + fonts-nanum fonts-nanum-extra ffmpeg + +# Node.js 20 LTS (React SSR) +curl -fsSL https://deb.nodesource.com/setup_20.x | bash - +apt install nodejs + +# 기타 +apt install nginx mysql-server supervisor git unzip +``` + +--- + +## 4. Jenkins CI/CD 파이프라인 + +### 4.1 Jenkins 설치 위치 + +Jenkins는 **개발 서버(114.203.209.83)**에 설치한다. 서버 메모리 한계를 고려하여 Swap을 추가한다. + +```bash +# Swap 4GB 추가 +sudo fallocate -l 4G /swapfile +sudo chmod 600 /swapfile +sudo mkswap /swapfile +sudo swapon /swapfile +echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab + +# Jenkins 설치 +wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo apt-key add - +echo "deb https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list +sudo apt update && sudo apt install jenkins +``` + +### 4.2 Gitea Webhook 연동 + +각 저장소에서 Push 이벤트 발생 시 Jenkins 빌드가 자동 트리거된다. + +| 저장소 | Gitea URL | Jenkins Job | +|--------|-----------|-------------| +| sam-api | `http://114.203.209.83:3000/SamProject/sam-api.git` | `sam-api-deploy` | +| sam-manage | `http://114.203.209.83:3000/SamProject/sam-manage.git` | `sam-mng-deploy` | +| sam-react-prod | `http://114.203.209.83:3000/SamProject/sam-react-prod.git` | `sam-react-deploy` | +| sam-sales | `http://114.203.209.83:3000/SamProject/sam-sales.git` | `sam-sales-deploy` | +| sam-docs | `http://114.203.209.83:3000/SamProject/sam-docs.git` | - (배포 없음) | + +### 4.3 브랜치 전략 + +``` +feature/* ──→ develop ──→ main/master + (자동배포) (승인 후 배포) + ↓ ↓ + 개발 서버 운영 서버 +``` + +| 브랜치 | 배포 대상 | 트리거 | 승인 | +|--------|----------|--------|------| +| `develop` | 개발 서버 | Push 자동 | 불필요 | +| `main`/`master` | 운영 서버 | PR 머지 | 팀장 승인 필수 | + +### 4.4 저장소별 Jenkinsfile + +#### sam-api 파이프라인 + +```groovy +pipeline { + agent any + + environment { + DEPLOY_SERVER = credentials('prod-server-ssh') + DEPLOY_PATH = '/home/webservice/api' + } + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Lint') { + steps { + sh 'composer install --no-interaction' + sh './vendor/bin/pint --test' + } + } + + stage('Test') { + steps { + sh 'php artisan test --parallel' + } + } + + stage('Deploy') { + when { + branch 'main' + } + steps { + sshagent(['prod-server-ssh']) { + sh """ + ssh -o StrictHostKeyChecking=no ${DEPLOY_SERVER} ' + cd ${DEPLOY_PATH} && + git pull origin main && + composer install --no-dev --optimize-autoloader && + php artisan migrate --force && + php artisan config:clear && + php artisan cache:clear && + php artisan route:cache && + php artisan view:cache && + sudo supervisorctl restart sam-api-worker:* + ' + """ + } + } + } + } + + post { + success { + slackSend channel: '#sam-deploy', + message: "API 배포 성공: ${env.BUILD_URL}" + } + failure { + slackSend channel: '#sam-alerts', + message: "API 배포 실패: ${env.BUILD_URL}" + } + } +} +``` + +#### sam-manage 파이프라인 + +```groovy +pipeline { + agent any + + environment { + DEPLOY_SERVER = credentials('prod-server-ssh') + DEPLOY_PATH = '/home/webservice/mng' + } + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Lint') { + steps { + sh 'composer install --no-interaction' + sh './vendor/bin/pint --test' + } + } + + stage('Build Assets') { + steps { + sh 'npm ci && npx tailwindcss -o public/css/app.css --minify' + } + } + + stage('Deploy') { + when { + branch 'master' + } + steps { + sshagent(['prod-server-ssh']) { + sh """ + ssh -o StrictHostKeyChecking=no ${DEPLOY_SERVER} ' + cd ${DEPLOY_PATH} && + git pull origin master && + composer install --no-dev --optimize-autoloader && + php artisan config:clear && + php artisan cache:clear && + php artisan view:cache && + sudo supervisorctl restart sam-mng-worker:* + ' + """ + } + } + } + } + + post { + success { + slackSend channel: '#sam-deploy', + message: "MNG 배포 성공: ${env.BUILD_URL}" + } + failure { + slackSend channel: '#sam-alerts', + message: "MNG 배포 실패: ${env.BUILD_URL}" + } + } +} +``` + +> **참고**: MNG는 마이그레이션을 실행하지 않는다. 모든 마이그레이션은 API에서만 실행한다. + +#### sam-react-prod 파이프라인 + +```groovy +pipeline { + agent any + + environment { + DEPLOY_SERVER = credentials('prod-server-ssh') + DEPLOY_PATH = '/home/webservice/react' + BUILD_FILE = 'next-standalone.tar.gz' + } + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Install') { + steps { + sh 'npm ci' + } + } + + stage('Lint') { + steps { + sh 'npm run lint' + } + } + + stage('Build') { + steps { + sh ''' + # .env.local 백업 (.env.production 으로 빌드) + [ -f .env.local ] && mv .env.local .env.local.bak + + npm run build + + # .env.local 복원 + [ -f .env.local.bak ] && mv .env.local.bak .env.local + + # standalone 빌드 확인 + test -f .next/standalone/server.js + ''' + } + } + + stage('Package') { + steps { + sh """ + rm -f ${BUILD_FILE} + COPYFILE_DISABLE=1 tar -czf ${BUILD_FILE} \ + .next/standalone \ + .next/static \ + public + """ + } + } + + stage('Deploy') { + when { + branch 'master' + } + steps { + sshagent(['prod-server-ssh']) { + sh """ + scp ${BUILD_FILE} ${DEPLOY_SERVER}:${DEPLOY_PATH}/ + ssh -o StrictHostKeyChecking=no ${DEPLOY_SERVER} ' + cd ${DEPLOY_PATH} && + lsof -ti:3000 | xargs kill 2>/dev/null || true && + sleep 2 && + rm -rf .next.bak && + mv .next .next.bak 2>/dev/null || true && + tar xzf ${BUILD_FILE} && + cp -r .next/static .next/standalone/.next/static && + cp -r public .next/standalone/public && + cp .env.production .next/standalone/.env.production 2>/dev/null || true && + cd .next/standalone && + PORT=3000 HOSTNAME=0.0.0.0 nohup node server.js > /tmp/sam-react.log 2>&1 & && + sleep 3 && + cd ${DEPLOY_PATH} && + rm -f ${BUILD_FILE} && + rm -rf .next.bak + ' + """ + } + } + } + } + + post { + success { + slackSend channel: '#sam-deploy', + message: "React 배포 성공: ${env.BUILD_URL}" + } + failure { + slackSend channel: '#sam-alerts', + message: "React 배포 실패: ${env.BUILD_URL}" + } + } +} +``` + +> **경고: React 빌드는 Jenkins 서버(Swap 추가 후)에서 수행한다. Jenkins 서버에서도 메모리 부족 시 로컬(WSL)에서 빌드 후 `deploy.sh`로 배포한다.** + +#### sam-sales 파이프라인 (간소화) + +```groovy +pipeline { + agent any + + stages { + stage('Deploy') { + when { + branch 'main' + } + steps { + sshagent(['prod-server-ssh']) { + sh """ + ssh -o StrictHostKeyChecking=no ${DEPLOY_SERVER} ' + cd /home/webservice/sales && + git pull origin main && + composer install --no-dev --optimize-autoloader && + php artisan config:clear && + php artisan cache:clear + ' + """ + } + } + } + } +} +``` + +--- + +## 5. 데이터베이스 전략 + +### 5.1 개발/운영 DB 물리 분리 + +| 항목 | 개발 DB | 운영 DB | +|------|---------|---------| +| **DB명** | `samdb` | `sam_prod` | +| **위치** | 개발 서버 (114.203.209.83) | 운영 서버 | +| **접속** | `samuser`/`sampass` | 별도 운영 계정 | +| **용도** | 개발/테스트 | 정식 서비스 | + +### 5.2 마이그레이션 규칙 + +> **경고: 모든 마이그레이션은 API 프로젝트(`/home/webservice/api`)에서만 실행한다. MNG에서 마이그레이션 실행 금지.** + +```bash +# 운영 서버 마이그레이션 (API에서만) +cd /home/webservice/api +php artisan migrate --force +``` + +### 5.3 초기 데이터 마이그레이션 절차 + +```bash +# 1. 개발 DB 덤프 (구조 + 필수 데이터) +mysqldump -u samuser -p samdb \ + --single-transaction \ + --routines \ + --triggers \ + --add-drop-table \ + > sam_initial_dump.sql + +# 2. 운영 서버로 전송 +scp sam_initial_dump.sql user@prod-server:/tmp/ + +# 3. 운영 DB에 복원 +mysql -u sam_prod_user -p sam_prod < /tmp/sam_initial_dump.sql + +# 4. 운영 전용 설정 적용 +mysql -u sam_prod_user -p sam_prod << 'EOF' +-- 바로빌 운영 모드 전환 +UPDATE barobill_configs SET is_active = 0 WHERE environment = 'test'; +UPDATE barobill_configs SET is_active = 1 WHERE environment = 'production'; +UPDATE barobill_members SET server_mode = 'production'; + +-- 테스트 데이터 정리 (필요 시) +-- DELETE FROM ... WHERE is_test = 1; +EOF +``` + +### 5.4 백업 체계 + +| 항목 | 주기 | 보관 기간 | 방법 | +|------|------|----------|------| +| **전체 백업** | 매일 03:00 | 30일 | `mysqldump --single-transaction` | +| **증분 백업** | 매 6시간 | 7일 | `mysqlbinlog` | +| **배포 전 스냅샷** | 배포 시 | 다음 배포까지 | Jenkins 파이프라인 내 자동 실행 | + +**자동 백업 스크립트** (`/etc/cron.d/sam-backup`): + +```bash +# 매일 03:00 전체 백업 +0 3 * * * root /home/webservice/scripts/db-backup.sh >> /var/log/sam/backup.log 2>&1 +``` + +```bash +#!/bin/bash +# /home/webservice/scripts/db-backup.sh +BACKUP_DIR="/home/webservice/backups/db" +DATE=$(date +%Y%m%d_%H%M%S) +KEEP_DAYS=30 + +mkdir -p ${BACKUP_DIR} + +mysqldump -u sam_prod_user --single-transaction --routines --triggers sam_prod \ + | gzip > ${BACKUP_DIR}/sam_prod_${DATE}.sql.gz + +# 30일 이상 된 백업 삭제 +find ${BACKUP_DIR} -name "*.sql.gz" -mtime +${KEEP_DAYS} -delete + +# Slack 알림 +curl -X POST -H 'Content-type: application/json' \ + --data "{\"text\":\"DB 백업 완료: sam_prod_${DATE}.sql.gz\"}" \ + ${SLACK_WEBHOOK_URL} +``` + +--- + +## 6. SSL/도메인 설정 + +### 6.1 Let's Encrypt 인증서 발급 + +```bash +# Certbot 설치 +apt install certbot python3-certbot-nginx + +# 인증서 발급 (4개 도메인) +certbot --nginx -d codebridge-x.com \ + -d api.codebridge-x.com \ + -d mng.codebridge-x.com \ + -d sales.codebridge-x.com + +# 자동 갱신 확인 +certbot renew --dry-run + +# 자동 갱신 cron (이미 certbot이 자동 설정) +# /etc/cron.d/certbot +``` + +### 6.2 Nginx 운영 설정 + +현재 Docker Nginx 설정(`docker/nginx/nginx.conf`)을 기반으로 운영 서버용으로 변환한다. + +핵심 변경 사항: + +| 항목 | 개발 (Docker) | 운영 (Bare-metal) | +|------|--------------|------------------| +| upstream | `proxy_pass http://react:3000` | `proxy_pass http://127.0.0.1:3000` | +| PHP-FPM | `fastcgi_pass api:9000` | `fastcgi_pass unix:/run/php/php8.4-fpm-api.sock` | +| SSL | 자체 서명 | Let's Encrypt | +| 도메인 | `*.sam.kr` | `*.codebridge-x.com` | + +**보안 헤더** (개발 서버 Sales 설정 기반): + +```nginx +# 공통 보안 헤더 +add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; +add_header X-Frame-Options "SAMEORIGIN" always; +add_header X-Content-Type-Options "nosniff" always; +add_header X-XSS-Protection "1; mode=block" always; + +# 보안: 악의적 경로 패턴 차단 +if ($request_uri ~* "(\.\.\/|\.\.\\|etc\/passwd|\.env|\.git|\.htaccess|\.sql|@fs\/)") { + return 403; +} + +# 보안: 의심스러운 User-Agent 차단 +if ($http_user_agent ~* "(sqlmap|nikto|nmap|masscan|metasploit|nessus)") { + return 403; +} +``` + +--- + +## 7. 모니터링 및 로깅 + +### 7.1 로그 집중화 + +``` +/var/log/sam/ +├── api-laravel.log # API Laravel 로그 (심볼릭 링크) +├── mng-laravel.log # MNG Laravel 로그 (심볼릭 링크) +├── api-queue-worker.log # API Queue Worker +├── api-queue-worker-error.log +├── mng-queue-worker.log # MNG Queue Worker +├── mng-queue-worker-error.log +├── api-scheduler.log # API Scheduler +├── react.log # React SSR 로그 +├── backup.log # DB 백업 로그 +└── healthcheck.log # 헬스체크 로그 +``` + +```bash +# 심볼릭 링크 설정 +ln -sf /home/webservice/api/storage/logs/laravel.log /var/log/sam/api-laravel.log +ln -sf /home/webservice/mng/storage/logs/laravel.log /var/log/sam/mng-laravel.log +``` + +### 7.2 헬스체크 스크립트 + +**5분 주기 실행** (`/etc/cron.d/sam-healthcheck`): + +```bash +*/5 * * * * root /home/webservice/scripts/healthcheck.sh >> /var/log/sam/healthcheck.log 2>&1 +``` + +```bash +#!/bin/bash +# /home/webservice/scripts/healthcheck.sh + +SLACK_WEBHOOK="${SLACK_WEBHOOK_URL}" +SERVICES=( + "https://codebridge-x.com|React" + "https://api.codebridge-x.com/up|API" + "https://mng.codebridge-x.com|MNG" + "https://sales.codebridge-x.com|Sales" +) + +for service in "${SERVICES[@]}"; do + IFS='|' read -r url name <<< "$service" + HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$url") + + if [ "$HTTP_CODE" -ne 200 ] && [ "$HTTP_CODE" -ne 302 ]; then + echo "[$(date)] ALERT: ${name} DOWN (HTTP ${HTTP_CODE})" + curl -X POST -H 'Content-type: application/json' \ + --data "{\"text\":\"${name} 서비스 다운! HTTP ${HTTP_CODE} - ${url}\"}" \ + "$SLACK_WEBHOOK" + fi +done + +# MySQL 체크 +if ! mysqladmin ping -u sam_prod_user --silent 2>/dev/null; then + echo "[$(date)] ALERT: MySQL DOWN" + curl -X POST -H 'Content-type: application/json' \ + --data '{"text":"MySQL 서비스 다운!"}' \ + "$SLACK_WEBHOOK" +fi + +# 디스크 사용량 체크 (90% 이상 경고) +DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | tr -d '%') +if [ "$DISK_USAGE" -ge 90 ]; then + curl -X POST -H 'Content-type: application/json' \ + --data "{\"text\":\"디스크 사용량 경고: ${DISK_USAGE}%\"}" \ + "$SLACK_WEBHOOK" +fi +``` + +### 7.3 Slack 채널 구성 + +| 채널 | 용도 | 알림 내용 | +|------|------|----------| +| `#sam-deploy` | 배포 알림 | 배포 성공/실패 결과 | +| `#sam-alerts` | 장애 알림 | 서비스 다운, 디스크 부족, DB 연결 실패 | +| `#sam-errors` | 에러 로그 | Laravel 500 에러, Queue 실패 | + +--- + +## 8. 롤백 전략 + +### 8.1 API/MNG 롤백 + +```bash +# 1. 이전 커밋으로 코드 복원 +cd /home/webservice/api +git log --oneline -5 # 이전 커밋 확인 +git checkout <이전_커밋_해시> + +# 2. 의존성 복원 +composer install --no-dev --optimize-autoloader + +# 3. 캐시 초기화 +php artisan config:clear +php artisan cache:clear +php artisan route:cache + +# 4. Queue Worker 재시작 +sudo supervisorctl restart sam-api-worker:* +``` + +### 8.2 React 롤백 + +```bash +# .next.bak 이 남아있는 경우 (배포 직후) +cd /home/webservice/react +lsof -ti:3000 | xargs kill 2>/dev/null || true +rm -rf .next +mv .next.bak .next +cd .next/standalone +PORT=3000 HOSTNAME=0.0.0.0 nohup node server.js > /tmp/sam-react.log 2>&1 & +``` + +### 8.3 DB 롤백 + +| 우선순위 | 방법 | 설명 | +|---------|------|------| +| **1순위** | 코드 롤백 | 마이그레이션 문제가 아니면 코드만 롤백 | +| **2순위** | `migrate:rollback` | 마지막 마이그레이션 배치 되돌리기 | +| **3순위** | 스냅샷 복원 | 배포 전 자동 스냅샷에서 복원 | + +```bash +# 마이그레이션 롤백 +cd /home/webservice/api +php artisan migrate:rollback --step=1 + +# 스냅샷 복원 (최후의 수단) +mysql -u sam_prod_user -p sam_prod < /home/webservice/backups/db/pre-deploy-snapshot.sql.gz +``` + +--- + +## 9. 보안 강화 + +### 9.1 방화벽 (UFW) + +```bash +# 기본 정책 +ufw default deny incoming +ufw default allow outgoing + +# 허용 포트 +ufw allow 22/tcp # SSH +ufw allow 80/tcp # HTTP +ufw allow 443/tcp # HTTPS + +# MySQL은 localhost만 (외부 차단) +# 기본 deny에 의해 자동 차단됨 + +# 활성화 +ufw enable +``` + +### 9.2 SSH 보안 + +```bash +# /etc/ssh/sshd_config +PermitRootLogin no +PasswordAuthentication no +PubkeyAuthentication yes +MaxAuthTries 3 +AllowUsers deploy +``` + +### 9.3 fail2ban + +```bash +apt install fail2ban + +# /etc/fail2ban/jail.local +[sshd] +enabled = true +port = 22 +maxretry = 5 +bantime = 3600 + +[nginx-http-auth] +enabled = true + +[nginx-limit-req] +enabled = true +``` + +### 9.4 운영 .env 관리 규칙 + +``` +❌ .env 파일을 Git에 커밋 금지 +❌ .env 파일을 Slack/메신저로 공유 금지 +✅ 서버에서 직접 편집 (vi /home/webservice/api/.env) +✅ 변경 시 팀 채널에 "어떤 키를 변경했는지"만 공유 +``` + +### 9.5 보안 체크리스트 + +| # | 항목 | 확인 | +|---|------|------| +| 1 | `APP_DEBUG=false` | [ ] | +| 2 | `APP_ENV=production` | [ ] | +| 3 | `APP_KEY` 운영 전용 키 생성 | [ ] | +| 4 | DB 비밀번호 강력한 값으로 변경 | [ ] | +| 5 | MySQL 외부 접속 차단 (bind-address=127.0.0.1) | [ ] | +| 6 | UFW 방화벽 활성화 | [ ] | +| 7 | SSH 키 인증만 허용 (비밀번호 금지) | [ ] | +| 8 | fail2ban 설치 및 활성화 | [ ] | +| 9 | Nginx 보안 헤더 적용 (HSTS, X-Frame 등) | [ ] | +| 10 | Nginx 악의적 경로/UA 차단 규칙 적용 | [ ] | +| 11 | SSL 인증서 발급 및 자동 갱신 설정 | [ ] | +| 12 | `.env` 파일 권한 600 설정 | [ ] | +| 13 | `storage/`, `bootstrap/cache/` 권한 확인 | [ ] | +| 14 | phpMyAdmin 운영 서버에 설치하지 않음 | [ ] | +| 15 | Sanctum 토큰 만료 시간 설정 확인 | [ ] | +| 16 | `LOG_SLACK_WEBHOOK_URL` 설정 (에러 알림) | [ ] | + +--- + +## 10. 단계별 마이그레이션 체크리스트 + +### 10.1 Phase 1: 인프라 구축 (1주) + +| # | 작업 | 담당 | 확인 | +|---|------|------|------| +| 1 | 운영 서버 호스팅 계약 및 OS 설치 | 팀장 | [ ] | +| 2 | 기본 패키지 설치 (Nginx, PHP 8.4, MySQL 8.0, Node.js 20) | 팀장 | [ ] | +| 3 | PHP 확장 모듈 설치 (zip, intl, xml, soap, gd 등) | 팀장 | [ ] | +| 4 | LibreOffice, FFmpeg 설치 (MNG용) | 팀장 | [ ] | +| 5 | Supervisor 설치 및 설정 | 팀장 | [ ] | +| 6 | MySQL `sam_prod` 데이터베이스 생성 | 팀장 | [ ] | +| 7 | MySQL 운영 계정 생성 (외부 접속 차단) | 팀장 | [ ] | +| 8 | UFW 방화벽 설정 (22, 80, 443만 허용) | 팀장 | [ ] | +| 9 | SSH 키 인증 설정 (비밀번호 로그인 차단) | 팀장 | [ ] | +| 10 | fail2ban 설치 | 팀장 | [ ] | +| 11 | DNS 레코드 추가 (A 레코드 4개) | 팀장 | [ ] | +| 12 | Let's Encrypt SSL 인증서 발급 | 팀장 | [ ] | +| 13 | Nginx 운영 설정 배포 (4개 도메인) | 팀장 | [ ] | +| 14 | PHP-FPM 3개 풀 설정 (api, mng, sales) | 팀장 | [ ] | +| 15 | 로그 디렉토리 생성 (`/var/log/sam/`) | 팀장 | [ ] | +| 16 | 백업 스크립트 설치 및 cron 등록 | 팀장 | [ ] | + +### 10.2 Phase 2: CI/CD 파이프라인 구축 (1주) + +| # | 작업 | 담당 | 확인 | +|---|------|------|------| +| 1 | 개발 서버 Swap 4GB 추가 | 팀장 | [ ] | +| 2 | Jenkins 설치 및 초기 설정 | 팀장 | [ ] | +| 3 | Gitea → Jenkins Webhook 연동 (4개 저장소) | 팀장 | [ ] | +| 4 | Jenkins SSH Credential 등록 (운영 서버) | 팀장 | [ ] | +| 5 | sam-api Jenkinsfile 작성 및 테스트 | 팀장 | [ ] | +| 6 | sam-manage Jenkinsfile 작성 및 테스트 | 팀장 | [ ] | +| 7 | sam-react-prod Jenkinsfile 작성 및 테스트 | 팀장 | [ ] | +| 8 | sam-sales Jenkinsfile 작성 및 테스트 | 팀장 | [ ] | +| 9 | Slack Webhook 연동 (배포/장애 알림) | 팀장 | [ ] | +| 10 | 헬스체크 스크립트 설치 및 cron 등록 | 팀장 | [ ] | +| 11 | develop → 개발 서버 자동 배포 테스트 | 팀장 | [ ] | + +### 10.3 Phase 3: 스테이징 배포 (3일) + +| # | 작업 | 담당 | 확인 | +|---|------|------|------| +| 1 | 프로젝트 소스 코드 클론 (4개 저장소) | 팀장 | [ ] | +| 2 | 운영 `.env` 파일 생성 (API, MNG, Sales, React) | 팀장 | [ ] | +| 3 | `composer install` (API, MNG, Sales) | 팀장 | [ ] | +| 4 | 개발 DB → 운영 DB 데이터 마이그레이션 | 팀장 | [ ] | +| 5 | `php artisan migrate --force` (API에서만) | 팀장 | [ ] | +| 6 | 바로빌 운영 설정 전환 (DB + .env) | 팀장 | [ ] | +| 7 | Google 서비스 어카운트 파일 배치 | 팀장 | [ ] | +| 8 | React 빌드 및 배포 (standalone) | 팀장 | [ ] | +| 9 | Supervisor 프로세스 시작 | 팀장 | [ ] | +| 10 | 전체 서비스 기동 확인 | 전원 | [ ] | +| 11 | 기능 테스트 (로그인, 견적, 세금계산서 등) | 전원 | [ ] | +| 12 | 외부 서비스 연동 확인 (바로빌, FCM, Gemini) | 전원 | [ ] | +| 13 | 성능 기본 테스트 (응답 속도 < 500ms) | 팀장 | [ ] | + +### 10.4 Phase 4: 운영 전환 (1일) + +| # | 작업 | 담당 | 확인 | +|---|------|------|------| +| 1 | 전환 일시 공지 (사용자/팀) | 팀장 | [ ] | +| 2 | 개발 DB 최종 덤프 → 운영 DB 동기화 | 팀장 | [ ] | +| 3 | DNS 최종 전환 (운영 서버 IP로 변경) | 팀장 | [ ] | +| 4 | SSL 인증서 최종 확인 | 팀장 | [ ] | +| 5 | 운영 환경 최종 기동 | 팀장 | [ ] | +| 6 | Jenkins 운영 파이프라인 활성화 | 팀장 | [ ] | +| 7 | 모니터링/헬스체크 최종 확인 | 팀장 | [ ] | +| 8 | 사용자 접속 안내 (URL 변경) | 팀장 | [ ] | +| 9 | 2시간 집중 모니터링 | 전원 | [ ] | +| 10 | 전환 완료 공지 | 팀장 | [ ] | + +**운영 전환 후 검증 체크리스트:** + +``` +□ React 메인 페이지 로딩 확인 +□ 로그인/로그아웃 정상 +□ MNG 관리자 화면 접속 확인 +□ API 엔드포인트 응답 확인 (/up) +□ 파일 업로드/다운로드 정상 +□ 바로빌 세금계산서 발행 테스트 +□ FCM 푸시 알림 전송 확인 +□ Queue Worker 정상 동작 (failed_jobs 확인) +□ Scheduler 정상 동작 +□ Slack 알림 수신 확인 +``` + +--- + +## 11. 일정 요약 + +``` +Week 1 (02/22~02/28) Week 2 (03/01~03/07) Week 3 (03/08~03/14) + │ │ │ + Phase 1 Phase 2 Phase 3 → Phase 4 + 인프라 구축 CI/CD 구축 스테이징 운영 전환 + ├─ 서버 셋업 ├─ Jenkins 설치 ├─ 데이터 ├─ DNS 전환 + ├─ 패키지 설치 ├─ Webhook 연동 │ 마이그 ├─ 모니터링 + ├─ 방화벽/SSL ├─ 파이프라인 작성 │ 레이션 └─ 전환 공지 + └─ Nginx 설정 └─ Slack 연동 └─ 기능 + 테스트 +``` + +> **참고**: MS3 목표일(2026-02-28)은 Phase 1 완료 시점이다. 실제 운영 전환은 Week 3에 수행한다. 필요 시 Phase 1~2를 병렬로 진행하여 일정을 단축할 수 있다. + +--- + +## 12. 위험 요소 및 완화 방안 + +| # | 위험 요소 | 영향도 | 발생 확률 | 완화 방안 | +|---|----------|--------|----------|----------| +| 1 | **RAM 부족으로 React 빌드 실패** | 🔴 높음 | 중간 | Jenkins 서버 Swap 추가, 폴백으로 로컬 빌드 사용 | +| 2 | **DNS 전파 지연** | 🟡 중간 | 높음 | TTL 사전 단축 (300초), 전환 24시간 전 TTL 변경 | +| 3 | **바로빌 운영 전환 실패** | 🔴 높음 | 낮음 | DB + .env 동시 전환, 즉시 롤백 절차 준비 (`production-env-sync.md` 참조) | +| 4 | **운영 서버 호스팅 지연** | 🔴 높음 | 낮음 | 대안 호스팅 사전 조사, 최소 1주 여유 확보 | +| 5 | **Jenkins 메모리 부족** | 🟡 중간 | 중간 | Swap 4GB 추가, 동시 빌드 제한 (1개), 빌드 후 workspace 정리 | +| 6 | **마이그레이션 충돌** | 🟡 중간 | 낮음 | 배포 전 DB 스냅샷, `migrate:rollback` 준비 | +| 7 | **Google 서비스 어카운트 경로 불일치** | 🟡 중간 | 중간 | 운영 서버 경로 통일, .env 교차 검증 | + +--- + +## 관련 문서 + +- [런칭 로드맵](../guides/project-launch-roadmap.md) +- [.env 동기화 절차](../guides/production-env-sync.md) +- [Docker 환경 스펙](../specs/docker-setup.md) +- [보안 정책](../architecture/security-policy.md) +- [시스템 아키텍처](../architecture/system-overview.md) + +--- + +**최종 업데이트**: 2026-02-22