Files

권혁성 00023b2d69 chore: 계획 문서 정리 및 아카이브 이동

- 완료된 계획 문서 12개 → plans/archive/ 이동
- 완료된 하위 계획 2개 → plans/sub/archive/ 이동
- 새 계획 문서 추가:
  - 5130-bom-migration-plan.md (완료)
  - 5130-sam-data-migration-plan.md (완료)
  - bidding-api-implementation-plan.md (완료)
  - dashboard-api-integration-plan.md
  - order-workorder-shipment-integration-plan.md
  - dev-toolbar-plan.md
- AI 리포트 키워드 색상체계 가이드 v1.4 추가
- index_plans.md 업데이트

2026-01-20 19:05:43 +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	게시판 연동	2개	0개	~15개	✅ 완료
Phase 8	SaaS 확장	3개	1개	~10개	✅ 완료
합계		12개	~5개	~71개

🚀 Phase 5: D1.0 기본 확장 ✅ 완료

기존 테이블/모델 활용, API 추가 중심 완료일: 2025-12-22 (기존 구현 확인)

5.1 사용자 초대 기능 ✅

슬라이드: 2 | 경로: 인사관리 > 사원관리 > 사용자 초대 완료일: 2025-12-19

테이블 생성
- user_invitations 마이그레이션 (2025_12_19_100001)
- 마이그레이션 실행 및 검증
모델 생성
- UserInvitation 모델 (BelongsToTenant)
- 관계 정의 (inviter, role, tenant)
- 토큰 생성 헬퍼 (generateToken())
- 상태 상수 (pending, accepted, expired, cancelled)
서비스 구현
- UserInvitationService 생성
- 이메일 초대 발송 로직 (invite())
- 초대 수락 로직 (accept())
- 토큰 만료 처리 (expirePendingInvitations())
- 초대 재발송 로직 (resend())
API 엔드포인트 (5개)
- POST /v1/users/invite - 사용자 초대 (이메일 발송)
- GET /v1/users/invitations - 초대 목록
- POST /v1/users/invitations/{token}/accept - 초대 수락
- DELETE /v1/users/invitations/{id} - 초대 취소
- POST /v1/users/invitations/{id}/resend - 초대 재발송
Swagger 문서
- UserInvitationApi.php 작성
- 스키마 정의 (UserInvitation, InviteRequest, AcceptRequest)
테스트
- Feature 테스트 작성
- 수동 API 테스트

5.2 알림설정 확장 ✅

슬라이드: 19-22 | 경로: 기준정보 > 알림설정 완료일: 2025-12-19

테이블 확장
- notification_settings 테이블 확인/생성
모델 생성/수정
- NotificationSetting 모델 (BelongsToTenant)
- 카테고리별 그룹화 메서드
서비스 구현
- NotificationSettingService 생성
- 카테고리별 조회/수정 로직
- 사용자별 기본값 생성 로직
API 엔드포인트 (3개)
- GET /v1/users/me/notification-settings - 알림 설정 조회
- PUT /v1/users/me/notification-settings - 알림 설정 수정
- PUT /v1/users/me/notification-settings/bulk - 알림 일괄 설정
Swagger 문서
- NotificationSettingApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

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

슬라이드: 24 | 경로: 계정정보 완료일: 2025-12-19

서비스 구현
- AccountService 생성/확장
- 회원 탈퇴 로직 (withdraw())
- 사용 중지 로직 (suspend())
- 약관 동의 정보 관리 (getAgreements(), updateAgreements())
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 | 경로: 회계관리 > 매출관리 > 매출 상세 완료일: 2025-12-19

기존 구성요소:

Sale 모델, SaleService 존재
TaxInvoice 모델 존재 (세금계산서)
서비스 확장
- SaleService 확장
- 거래명세서 조회 로직 (getStatement())
- 거래명세서 발행 로직 (issueStatement())
- 거래명세서 이메일 발송 로직 (sendStatement())
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 | 경로: 회계관리 > 악성채권 추심관리 완료일: 2025-12-19 (commit: c0af888)

테이블 생성 (3개)
- bad_debts 마이그레이션 (2025_12_19_160001)
- bad_debt_documents 마이그레이션 (2025_12_19_160002)
- bad_debt_memos 마이그레이션 (2025_12_19_160003)
- 마이그레이션 실행 및 검증
모델 생성 (3개)
- BadDebt 모델 (BelongsToTenant, SoftDeletes)
  - 상태 상수: collecting, legal_action, recovered, bad_debt
  - 관계: client, assignedUser, creator, documents, memos
- BadDebtDocument 모델
  - 문서 유형: business_license, tax_invoice, additional
- BadDebtMemo 모델
서비스 구현
- BadDebtService 생성 (307줄)
- 악성채권 등록/수정/삭제 로직
- 상태 전이 로직 (추심중→법적조치→회수완료/대손처리)
- 요약 통계 (총 채권, 상태별 금액)
- 서류 첨부/삭제 로직
- 메모 추가/삭제 로직
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 작성 (433줄)
- 스키마 정의 (BadDebt, BadDebtDocument, BadDebtMemo, Summary)
테스트
- Feature 테스트 작성
- 수동 API 테스트

6.2 팝업관리 ✅

슬라이드: 15-16 | 경로: 기준정보 > 팝업관리 완료일: 2025-12-19

테이블 생성 (1개)

popups 마이그레이션

-- popups (팝업)
id, tenant_id, target_type, target_id,
title, content, status,
started_at, ended_at, options,
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 게시판 연동 ✅ 완료

완료일: 2025-12-19

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

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

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

7.1 게시판관리 ✅

슬라이드: 17-18 | 경로: 기준정보 > 게시판관리 완료일: 2025-12-19 (기존 구현 활용)

기존 모델 확인/확장
- Board 모델 확인
- BoardSetting 모델 확인
- 필요 필드 이미 존재
서비스 구현
- BoardService 존재 (테넌트별 게시판 CRUD 로직)
API 엔드포인트 (5개)
- GET /v1/boards - 게시판 목록
- POST /v1/boards - 게시판 생성
- GET /v1/boards/{id} - 게시판 상세
- PUT /v1/boards/{id} - 게시판 수정
- DELETE /v1/boards/{id} - 게시판 삭제
Swagger 문서
- BoardApi.php 작성 완료

7.2 게시판 (사용자용) ✅

슬라이드: 3-7 | 경로: 게시판 완료일: 2025-12-19

기존 모델 확인/확장
- Post 모델 확인
- 상단 노출 필드 (is_notice)
- 조회수 필드 (views)
서비스 구현
- PostService 존재
- 게시글 CRUD 로직
- 상단 노출 로직
- 조회수 증가 로직
- 나의 게시글 조회 로직 ✅ 추가됨
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 - 나의 게시글 ✅ 신규 추가
- GET /v1/boards/{code}/posts/{id}/comments - 댓글 목록
- POST /v1/boards/{code}/posts/{id}/comments - 댓글 등록
- PUT /v1/boards/{code}/posts/{id}/comments/{commentId} - 댓글 수정
- DELETE /v1/boards/{code}/posts/{id}/comments/{commentId} - 댓글 삭제
Swagger 문서
- BoardApi.php 작성 완료
- PostApi.php 작성 완료

7.3 고객센터 → 게시판관리로 대체 ⏭️

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

결정사항: 고객센터 기능은 기존 게시판관리 시스템으로 구현

공지사항, 이벤트, FAQ, 1:1 문의 → 게시판 유형(board_code)으로 관리
별도 SupportAPI 불필요, 기존 Board/Post API 활용

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

기존 Plan/Subscription/Payment 모델 활용

8.1 구독관리 ✅

슬라이드: 28 | 경로: 구독관리 완료일: 2025-12-22 (기존 구현 확인)

기존 구성요소:

Plan 모델: name, code, price, features(json)
Subscription 모델: tenant_id, plan_id, started_at, ended_at, status
DataExport 모델: 데이터 내보내기
서비스 확장
- SubscriptionService 확장 (432줄)
- 현재 구독 정보 조회 로직 (current())
- 사용량 조회 로직 (usage())
- 자료 내보내기 로직 (createExport(), getExport())
- 서비스 해지 로직 (cancel())
API 엔드포인트 (5개 + 추가 6개)
- GET /v1/subscriptions/current - 현재 구독 정보
- GET /v1/subscriptions/usage - 사용량 조회
- POST /v1/subscriptions/export - 자료 내보내기 요청
- GET /v1/subscriptions/export/{id} - 내보내기 상태 조회
- POST /v1/subscriptions/{id}/cancel - 서비스 해지
- GET /v1/subscriptions - 구독 목록 (추가)
- POST /v1/subscriptions - 구독 등록 (추가)
- GET /v1/subscriptions/{id} - 구독 상세 (추가)
- POST /v1/subscriptions/{id}/renew - 구독 갱신 (추가)
- POST /v1/subscriptions/{id}/suspend - 일시정지 (추가)
- POST /v1/subscriptions/{id}/resume - 재개 (추가)
Swagger 문서
- SubscriptionApi.php 작성 (526줄)
테스트
- Feature 테스트 작성
- 수동 API 테스트

8.2 결제내역 ✅

슬라이드: 29 | 경로: 결제내역 완료일: 2025-12-22 (기존 구현 확인)

기존 구성요소:

Payment 모델: subscription_id, amount, payment_method, paid_at, status
서비스 확장
- PaymentService 확장 (357줄)
- 결제 내역 목록 조회 로직 (index())
- 거래명세서 생성 로직 (statement())
- 결제 요약 통계 (summary())
API 엔드포인트 (2개 + 추가 6개)
- GET /v1/payments - 결제 내역 목록
- GET /v1/payments/{id}/statement - 거래명세서 조회
- GET /v1/payments/summary - 결제 요약 통계 (추가)
- GET /v1/payments/{id} - 결제 상세 (추가)
- POST /v1/payments - 결제 등록 (추가)
- POST /v1/payments/{id}/complete - 완료 처리 (추가)
- POST /v1/payments/{id}/cancel - 취소 (추가)
- POST /v1/payments/{id}/refund - 환불 (추가)
Swagger 문서
- PaymentApi.php 작성 (455줄)
테스트
- Feature 테스트 작성
- 수동 API 테스트

8.3 회사 추가 ✅

슬라이드: 25-27 | 경로: 회사정보 완료일: 2025-12-22

테이블 생성 (1개)

company_requests 마이그레이션

-- company_requests (회사 추가 신청)
id, user_id, business_number, company_name, ceo_name,
address, phone, email, status, message, reject_reason,
barobill_response(json), approved_by, created_tenant_id,
processed_at, created_at, updated_at

마이그레이션 실행 및 검증

모델 생성
- CompanyRequest 모델
  - 상태 상수: pending, approved, rejected
  - 관계: user, approver, createdTenant
  - 스코프: pending(), approved(), rejected()
서비스 구현
- CompanyService 생성
- 사업자등록번호 유효성 검사 (바로빌 연동 + 체크섬 검증)
- 회사 추가 신청 로직
- 신청 승인 로직 (테넌트 자동 생성 + 사용자 연결)
- 신청 반려 로직
- 신청 목록 조회 (관리자용/사용자용)
API 엔드포인트 (7개)
- POST /v1/companies/check - 사업자등록번호 유효성 검사
- POST /v1/companies/request - 회사 추가 신청
- GET /v1/companies/requests - 신청 목록 (관리자용)
- GET /v1/companies/requests/{id} - 신청 상세
- POST /v1/companies/requests/{id}/approve - 승인
- POST /v1/companies/requests/{id}/reject - 반려
- GET /v1/companies/my-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 모델 확인)
Phase 6.1 악성채권 추심관리 API 개발 완료 (commit: c0af888)
Phase 6.2 팝업관리 API 개발 완료
Phase 7.1 게시판관리 - 기존 구현 확인 완료
Phase 7.2 게시판(사용자용) - 기존 구현 확인 + /posts/my API 추가 (commit: c15a245)
Phase 7.3 고객센터 → 게시판관리로 대체 결정
Phase 8 SaaS 확장 분석 시작

2025-12-22

Phase 8.1 구독관리 - 기존 구현 확인 완료
Phase 8.2 결제내역 - 기존 구현 확인 완료
Phase 8.3 회사 추가 API 개발 완료 (commit: 7781253)
- company_requests 테이블 생성
- CompanyRequest 모델 생성
- CompanyService 생성 (바로빌 연동 + 테넌트 생성)
- 7개 API 엔드포인트 구현
- Swagger 문서 작성
Phase 5 전체 기존 구현 확인 완료
- 5.1 사용자 초대: 5개 API (invite, invitations, accept, cancel, resend)
- 5.2 알림설정: 3개 API (notification-settings, update, bulk)
- 5.3 계정정보: 4개 API (withdraw, suspend, agreements)
- 5.4 매출 거래명세서: 3개 API (statement, issue, send)
D1.0 Phase 5-8 전체 API 개발 완료!

✅ 완료 기준

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

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

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

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

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

게시판관리 API 구현 완료 ✅ 2025-12-19
게시판 (사용자용) API 구현 완료 ✅ 2025-12-19
고객센터 → 게시판관리로 대체 결정 ✅ 2025-12-19

Phase 8 완료 조건 (SaaS 확장) ✅

구독관리 API 구현 완료 ✅ 2025-12-22
결제내역 API 구현 완료 ✅ 2025-12-22
회사 추가 API 구현 완료 ✅ 2025-12-22
자료 내보내기 기능 구현 ✅ (SubscriptionService에 포함)

전체 완료 조건

모든 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 기본 확장 ✅ 완료

5.1 사용자 초대 기능 ✅

5.2 알림설정 확장 ✅

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

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

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

6.1 악성채권 추심관리 ✅

6.2 팝업관리 ✅

📋 Phase 7: D1.0 게시판 연동 ✅ 완료

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

2025-12-22

✅ 완료 기준

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

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

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

Phase 8 완료 조건 (SaaS 확장) ✅

전체 완료 조건

🔗 관련 링크

20 KiB

Raw Blame History