Files

hskwon fc92f7849c docs: D1.0 개발 계획 및 스토리보드 추가

- erp-api-development-plan-d1.0-changes.md: Phase 5-8 개발 계획
- SAM_ERP_Storyboard_D1.0_251218/: D1.0 스토리보드 이미지 38장

2025-12-19 16:04:31 +09:00

20 KiB

Raw Blame History

SAM ERP API 개발 작업 계획 - D1.0 변경사항

작성일: 2025-12-19 기준 문서: SAM_ERP_Storyboard_D1.0_251218 (38페이지) 이전 버전: SAM_ERP_Storyboard_D0.8_251216 (85페이지) 상태: ✅ Phase 5 완료 | 🔄 Phase 6 진행중 | ⬜ Phase 7 대기 | ⬜ Phase 8 대기

📚 참고 문서

핵심 참고 문서

문서	경로	용도
기존 개발 계획	`erp-api-development-plan.md`	D0.8 기준 Phase 1-4
개발 공통 정책	`../guides/PROJECT_DEVELOPMENT_POLICY.md`	개발 표준 및 정책
D0.8 스토리보드	`SAM_ERP_Storyboard_D0.8_251216/`	이전 버전 UI 참조
D1.0 스토리보드	`SAM_ERP_Storyboard_D1.0_251218/`	최신 UI/UX 참조

기존 코드 참조

항목	경로	상태
`Board` 모델	`api/app/Models/Boards/Board.php`	✅ 존재
`BoardSetting` 모델	`api/app/Models/Boards/BoardSetting.php`	✅ 존재
`BoardComment` 모델	`api/app/Models/Boards/BoardComment.php`	✅ 존재
`Plan` 모델	`api/app/Models/Tenants/Plan.php`	✅ 존재
`Subscription` 모델	`api/app/Models/Tenants/Subscription.php`	✅ 존재
`PushNotificationSetting`	`api/app/Models/PushNotificationSetting.php`	✅ 존재

📊 D1.0 개발 범위 요약

Phase	구분	항목수	신규 테이블	API 수	상태
Phase 5	기본 확장	4개	1개	~14개	✅ 완료
Phase 6	핵심 신규	2개	4개	~17개	🔄 진행중
Phase 7	게시판 연동	3개	0개	~30개	⬜ 대기
Phase 8	SaaS 확장	3개	0개	~10개	⬜ 대기
합계		12개	~5개	~71개

🚀 Phase 5: D1.0 기본 확장 (예상 1-2주)

기존 테이블/모델 활용, API 추가 중심

5.1 사용자 초대 기능 🆕

슬라이드: 2 | 경로: 인사관리 > 사원관리 > 사용자 초대

테이블 생성

user_invitations 마이그레이션

-- user_invitations (사용자 초대)
id, tenant_id, email, role_id, message, token,
status (pending/accepted/expired),
invited_by, expires_at, accepted_at,
created_at, updated_at

마이그레이션 실행 및 검증

모델 생성
- UserInvitation 모델 (BelongsToTenant)
- 관계 정의 (inviter, role)
- 토큰 생성 헬퍼
서비스 구현
- UserInvitationService 생성
- 이메일 초대 발송 로직
- 초대 수락 로직 (사원 정보 자동 매핑)
- 토큰 만료 처리
API 엔드포인트 (4개)
- POST /v1/users/invite - 사용자 초대 (이메일 발송)
- GET /v1/users/invitations - 초대 목록
- POST /v1/users/invitations/{token}/accept - 초대 수락
- DELETE /v1/users/invitations/{id} - 초대 취소
Swagger 문서
- UserInvitationApi.php 작성
- 스키마 정의 (UserInvitation, InviteRequest, AcceptRequest)
테스트
- Feature 테스트 작성
- 수동 API 테스트

5.2 알림설정 확장 🔄

슬라이드: 19-22 | 경로: 기준정보 > 알림설정

기존 구성요소:

PushNotificationSetting 모델 존재 (Push 알림용)
일반 알림설정은 신규 필요

테이블 확장

notification_settings 테이블 확인/생성

-- notification_settings (알림 설정)
id, tenant_id, user_id, category, type,
email_enabled, push_enabled, sms_enabled,
created_at, updated_at

Seeder: 기본 알림 유형 17개 등록

모델 생성/수정
- NotificationSetting 모델 (BelongsToTenant)
- 카테고리별 그룹화 메서드
서비스 구현
- NotificationSettingService 생성
- 카테고리별 조회/수정 로직
- 사용자별 기본값 생성 로직

알림 유형 정의 (17개)

카테고리	알림 항목	기본값
공지	공지사항, 이벤트	OFF, ON
일정	부가세 신고, 종합소득세 신고	OFF, ON
거래처	신규 업체 등록, 신용등급 등록	OFF, ON
근태	연차, 출근, 지각, 결근	OFF, ON, OFF, ON
수주/발주	수주 등록, 발주	OFF, ON
전자결재	결재요청, 승인, 반려, 완료	OFF, ON, OFF, OFF
생산	안전재고, 생산완료	OFF, ON

API 엔드포인트 (3개)
- GET /v1/settings/notifications - 알림 설정 조회
- PUT /v1/settings/notifications - 알림 설정 일괄 수정
- PATCH /v1/settings/notifications/{type} - 개별 알림 설정 수정
Swagger 문서
- NotificationSettingApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

5.3 계정정보 수정 (탈퇴/사용중지) 🔄

슬라이드: 24 | 경로: 계정정보

서비스 구현
- AccountService 생성/확장
- 회원 탈퇴 로직 (모든 테넌트에서 탈퇴, SAM 탈퇴)
- 사용 중지 로직 (특정 테넌트에서만 중지)
- 약관 동의 정보 관리
API 엔드포인트 (4개)
- POST /v1/account/withdraw - 회원 탈퇴
- POST /v1/account/suspend - 사용 중지 (특정 테넌트)
- GET /v1/account/agreements - 약관 동의 정보 조회
- PUT /v1/account/agreements - 약관 동의 정보 수정
Swagger 문서
- AccountApi.php 확장
테스트
- Feature 테스트 작성
- 수동 API 테스트

5.4 매출 상세 확장 (거래명세서) 🔄

슬라이드: 9 | 경로: 회계관리 > 매출관리 > 매출 상세

기존 구성요소:

Sale 모델, SaleService 존재
TaxInvoice 모델 존재 (세금계산서)
서비스 확장
- SaleService 확장
- 거래명세서 조회 로직
- 거래명세서 발행 로직
- 거래명세서 이메일 발송 로직
API 엔드포인트 (3개)
- GET /v1/sales/{id}/statement - 거래명세서 조회
- POST /v1/sales/{id}/statement/issue - 거래명세서 발행
- POST /v1/sales/{id}/statement/send - 거래명세서 이메일 발송
Swagger 문서
- SaleApi.php 확장 (거래명세서 관련 추가)
테스트
- Feature 테스트 작성
- 수동 API 테스트

🔨 Phase 6: D1.0 핵심 신규 개발 (예상 2-3주)

신규 테이블 + API 전체 신규 구현

6.1 악성채권 추심관리 🆕

슬라이드: 10-13 | 경로: 회계관리 > 악성채권 추심관리

테이블 생성 (3개)

bad_debts 마이그레이션

-- bad_debts (악성채권)
id, tenant_id, client_id, debt_amount, status,
overdue_days, assigned_user_id, occurred_at, closed_at,
is_active, options(json),
created_by, updated_by, deleted_by,
created_at, updated_at, deleted_at

bad_debt_documents 마이그레이션

-- bad_debt_documents (필요 서류)
id, bad_debt_id, document_type, file_id,
created_at

bad_debt_memos 마이그레이션

-- bad_debt_memos (메모)
id, bad_debt_id, content, created_by, created_at

마이그레이션 실행 및 검증

모델 생성 (3개)
- BadDebt 모델 (BelongsToTenant, SoftDeletes)
  - 상태 상수: COLLECTING, LEGAL_ACTION, RECOVERED, BAD_DEBT
  - 관계: client, assignedUser, documents, memos
- BadDebtDocument 모델
  - 문서 유형: business_license, tax_invoice, additional
- BadDebtMemo 모델
서비스 구현
- BadDebtService 생성
- 악성채권 등록/수정/삭제 로직
- 상태 전이 로직 (추심중→법적조치→회수완료/대손처리)
- 요약 통계 (총 채권, 상태별 금액)
- 서류 첨부/삭제 로직
- 메모 추가/삭제 로직
API 엔드포인트 (11개)
- GET /v1/bad-debts - 악성채권 목록
- POST /v1/bad-debts - 악성채권 등록
- GET /v1/bad-debts/summary - 상단 요약 (총 채권, 상태별 금액)
- GET /v1/bad-debts/{id} - 악성채권 상세
- PUT /v1/bad-debts/{id} - 악성채권 수정
- DELETE /v1/bad-debts/{id} - 악성채권 삭제
- PATCH /v1/bad-debts/{id}/toggle - 설정 ON/OFF
- POST /v1/bad-debts/{id}/documents - 서류 첨부
- DELETE /v1/bad-debts/{id}/documents/{docId} - 서류 삭제
- POST /v1/bad-debts/{id}/memos - 메모 추가
- DELETE /v1/bad-debts/{id}/memos/{memoId} - 메모 삭제
Swagger 문서
- BadDebtApi.php 작성
- 스키마 정의 (BadDebt, BadDebtDocument, BadDebtMemo, Summary)
테스트
- Feature 테스트 작성
- 수동 API 테스트

6.2 팝업관리 🆕

슬라이드: 15-16 | 경로: 기준정보 > 팝업관리

테이블 생성 (1개)

popups 마이그레이션

-- popups (팝업)
id, tenant_id, target_type, target_id,
title, content, status,
started_at, ended_at,
created_by, updated_by, deleted_by,
created_at, updated_at, deleted_at

마이그레이션 실행 및 검증

모델 생성
- Popup 모델 (BelongsToTenant, SoftDeletes)
  - target_type: all, department
  - status: active, inactive
  - 활성 팝업 스코프 (기간 + 상태 체크)
서비스 구현
- PopupService 생성
- 팝업 CRUD 로직
- 활성 팝업 조회 로직 (로그인 후 노출용)
- 기간 유효성 검사 로직
API 엔드포인트 (6개)
- GET /v1/popups - 팝업 목록 (관리자용)
- POST /v1/popups - 팝업 등록
- GET /v1/popups/active - 활성 팝업 목록 (사용자용)
- GET /v1/popups/{id} - 팝업 상세
- PUT /v1/popups/{id} - 팝업 수정
- DELETE /v1/popups/{id} - 팝업 삭제
Swagger 문서
- PopupApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

📋 Phase 7: D1.0 게시판 연동 (예상 1-2주)

기존 Board 모델 활용, API 엔드포인트 추가

기존 구성요소 (api 프로젝트):

Board 모델: is_system, board_type, board_code, name, extra_settings
BoardSetting 모델: 커스텀 필드 정의
BoardComment 모델: 댓글
Post 모델: 게시글 (확인 필요)

7.1 게시판관리 🆕

슬라이드: 17-18 | 경로: 기준정보 > 게시판관리

기존 모델 확인/확장
- Board 모델 확인
- BoardSetting 모델 확인
- 필요시 필드 추가 (allow_comments, max_pinned 등)
서비스 구현
- BoardSettingService 생성
- 테넌트별 게시판 CRUD 로직
- 디폴트 게시판 생성 로직 (공지사항, 나의 게시글)
API 엔드포인트 (5개)
- GET /v1/board-settings - 게시판 설정 목록
- POST /v1/board-settings - 게시판 생성
- GET /v1/board-settings/{id} - 게시판 설정 상세
- PUT /v1/board-settings/{id} - 게시판 설정 수정
- DELETE /v1/board-settings/{id} - 게시판 삭제
Swagger 문서
- BoardSettingApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

7.2 게시판 (사용자용) 🆕

슬라이드: 3-7 | 경로: 게시판

기존 모델 확인/확장
- Post 모델 확인/생성
- 상단 노출 필드 (is_pinned, pinned_at)
- 댓글 허용 필드 (allow_comments)
- 조회수 필드 (view_count)
서비스 구현
- PostService 생성
- 게시글 CRUD 로직
- 상단 노출 로직 (최대 5개 제한)
- 조회수 증가 로직
- 나의 게시글 조회 로직
API 엔드포인트 (10개)
- GET /v1/boards - 게시판 목록 (탭용)
- GET /v1/boards/{code}/posts - 게시글 목록
- POST /v1/boards/{code}/posts - 게시글 등록
- GET /v1/boards/{code}/posts/{id} - 게시글 상세
- PUT /v1/boards/{code}/posts/{id} - 게시글 수정
- DELETE /v1/boards/{code}/posts/{id} - 게시글 삭제
- GET /v1/posts/my - 나의 게시글
- POST /v1/posts/{id}/comments - 댓글 등록
- PUT /v1/posts/{id}/comments/{commentId} - 댓글 수정
- DELETE /v1/posts/{id}/comments/{commentId} - 댓글 삭제
Swagger 문서
- BoardApi.php 작성 (사용자용)
- PostApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

7.3 고객센터 🆕

슬라이드: 30-38 | 경로: 고객센터

기존 구성요소:

시스템 게시판 (is_system = true) 활용
board_type으로 구분: notice, event, faq, inquiry
게시판 시드 데이터
- notice - SAM 공지사항 (시스템)
- event - 이벤트 (시스템)
- faq - FAQ (시스템, 카테고리 필드)
- inquiry - 1:1 문의 (테넌트별)
서비스 확장
- SupportService 생성
- 공지사항 조회 (시스템 게시판)
- 이벤트 조회 (진행중/종료)
- FAQ 조회 (카테고리별)
- 1:1 문의 CRUD + 답변
API 엔드포인트 (15개)
- GET /v1/support/notices - 공지사항 목록
- GET /v1/support/notices/{id} - 공지사항 상세
- GET /v1/support/events - 이벤트 목록
- GET /v1/support/events/{id} - 이벤트 상세
- GET /v1/support/faqs - FAQ 목록
- GET /v1/support/faqs/categories - FAQ 카테고리 목록
- GET /v1/support/inquiries - 1:1 문의 목록
- POST /v1/support/inquiries - 1:1 문의 등록
- GET /v1/support/inquiries/{id} - 1:1 문의 상세
- PUT /v1/support/inquiries/{id} - 1:1 문의 수정
- DELETE /v1/support/inquiries/{id} - 1:1 문의 삭제
- POST /v1/support/inquiries/{id}/comments - 댓글 등록
- PUT /v1/support/inquiries/{id}/comments/{cid} - 댓글 수정
- DELETE /v1/support/inquiries/{id}/comments/{cid} - 댓글 삭제
- POST /v1/support/inquiries/{id}/reply - 관리자 답변 (관리자용)
Swagger 문서
- SupportApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

💼 Phase 8: D1.0 SaaS 확장 (예상 1-2주)

기존 Plan/Subscription/Payment 모델 활용

8.1 구독관리 🆕

슬라이드: 28 | 경로: 구독관리

기존 구성요소:

Plan 모델: name, code, price, features(json)
Subscription 모델: tenant_id, plan_id, started_at, ended_at, status
서비스 확장
- SubscriptionService 확장
- 현재 구독 정보 조회 로직
- 사용량 조회 로직 (사용자 수, 저장공간, API 호출)
- 자료 내보내기 로직 (비동기 처리)
- 서비스 해지 로직 (데이터 보관 정책)
API 엔드포인트 (5개)
- GET /v1/subscriptions/current - 현재 구독 정보
- GET /v1/subscriptions/usage - 사용량 조회
- POST /v1/subscriptions/export - 자료 내보내기 요청
- GET /v1/subscriptions/export/{id} - 내보내기 상태 조회
- POST /v1/subscriptions/cancel - 서비스 해지
Swagger 문서
- SubscriptionApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

8.2 결제내역 🆕

슬라이드: 29 | 경로: 결제내역

기존 구성요소:

Payment 모델: subscription_id, amount, payment_method, paid_at, status
서비스 확장
- PaymentService 확장
- 결제 내역 목록 조회 로직
- 거래명세서 생성 로직
API 엔드포인트 (2개)
- GET /v1/payments - 결제 내역 목록
- GET /v1/payments/{id}/statement - 거래명세서 조회
Swagger 문서
- PaymentApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

8.3 회사 추가 🔄

슬라이드: 25-27 | 경로: 회사정보

서비스 구현
- CompanyService 생성
- 사업자등록번호 유효성 검사 (바로빌 연동)
- 회사 추가 신청 로직 (매니저 알림)
- 신청 목록 조회 (관리자용)
API 엔드포인트 (3개)
- POST /v1/companies/check - 사업자등록번호 유효성 검사
- POST /v1/companies/request - 회사 추가 신청
- GET /v1/companies/requests - 회사 추가 신청 목록 (관리자용)
Swagger 문서
- CompanyApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

📋 기획 확인 필요 항목

⚠️ API 구현 전 비즈니스 로직 확정 필요

D1.0 신규 확인 필요

사용자 초대 시 권한 범위 (테넌트 단위 vs 전사)
악성채권 자동 판정 조건 (연체일수 기준, 기본 90일?)
팝업 노출 우선순위 (복수 팝업 시)
서비스 해지 시 데이터 보관 기간
자료 내보내기 포맷 (Excel, CSV, JSON)
상단 노출 게시글 최대 개수 (기본 5개)
1:1 문의 상담분류 목록 (문의하기, 신고하기, 건의사항, 서비스 오류)

기존 확인 사항 (D0.8)

테넌트: 신청→승인→만료→해지 전이 조건
전자결재→회계: 지출결의서 승인 시 출금 자동 생성?
바로빌 API 비용 확인

📝 작업 일지

2025-12-19

D1.0 스토리보드 분석 완료 (38페이지)
D0.8 대비 변경사항 식별 (신규 8개, 수정 4개)
D1.0 개발 계획 문서 작성 (Phase 5-8)
기존 코드베이스 분석 (Board, Plan, Subscription 모델 확인)

YYYY-MM-DD

(작업 내용 기록)

✅ 완료 기준

Phase 5 완료 조건 (기본 확장)

사용자 초대 API 구현 완료
알림설정 API 확장 완료
계정정보 API 확장 완료
매출 거래명세서 API 구현 완료
Swagger 문서 완성
Pint 코드 포맷팅 완료

Phase 6 완료 조건 (핵심 신규)

악성채권 추심관리 전체 구현
팝업관리 전체 구현
마이그레이션 검증 완료
Swagger 문서 완성

Phase 7 완료 조건 (게시판 연동)

게시판관리 API 구현 완료
게시판 (사용자용) API 구현 완료
고객센터 API 구현 완료
시드 데이터 (시스템 게시판) 등록

Phase 8 완료 조건 (SaaS 확장)

구독관리 API 구현 완료
결제내역 API 구현 완료
회사 추가 API 구현 완료
자료 내보내기 기능 구현

전체 완료 조건

모든 D1.0 API 구현 완료 (~71개)
Swagger 문서 100%
통합 테스트 통과
프론트엔드 연동 준비 완료

🔗 관련 링크

기존 개발 계획: erp-api-development-plan.md
API Swagger UI: http://sam.kr/api-docs/index.html
개발 공통 정책: ../guides/PROJECT_DEVELOPMENT_POLICY.md
D1.0 스토리보드: SAM_ERP_Storyboard_D1.0_251218/

20 KiB Raw Blame History

SAM ERP API 개발 작업 계획 - D1.0 변경사항

📚 참고 문서

핵심 참고 문서

기존 코드 참조

📊 D1.0 개발 범위 요약

🚀 Phase 5: D1.0 기본 확장 (예상 1-2주)

5.1 사용자 초대 기능 🆕

5.2 알림설정 확장 🔄

5.3 계정정보 수정 (탈퇴/사용중지) 🔄

5.4 매출 상세 확장 (거래명세서) 🔄

🔨 Phase 6: D1.0 핵심 신규 개발 (예상 2-3주)

6.1 악성채권 추심관리 🆕

6.2 팝업관리 🆕

📋 Phase 7: D1.0 게시판 연동 (예상 1-2주)

7.1 게시판관리 🆕

7.2 게시판 (사용자용) 🆕

7.3 고객센터 🆕

💼 Phase 8: D1.0 SaaS 확장 (예상 1-2주)

8.1 구독관리 🆕

8.2 결제내역 🆕

8.3 회사 추가 🔄

📋 기획 확인 필요 항목

D1.0 신규 확인 필요

기존 확인 사항 (D0.8)

📝 작업 일지

2025-12-19

YYYY-MM-DD

✅ 완료 기준

Phase 5 완료 조건 (기본 확장)

Phase 6 완료 조건 (핵심 신규)

Phase 7 완료 조건 (게시판 연동)

Phase 8 완료 조건 (SaaS 확장)

전체 완료 조건

🔗 관련 링크

20 KiB

Raw Blame History