SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
80bff661fc2eb3b70e53e26dfb3ee4e068448012
sam-docs/plans/erp-api-development-plan-d1.0-changes.md
hskwon 80bff661fc docs: Phase 6.1 악성채권 체크리스트 완료 상태 반영 
- erp-api-development-plan-d1.0-changes.md: 악성채권 추심관리 구현 완료 체크
- quotation/PROGRESS.md: 견적 프로젝트 진행상황 업데이트
- phase-4-integration/README.md: API 통합 문서 수정
- react-api-integration-plan.md: React API 통합 계획 추가
2025-12-22 15:53: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 게시판 연동 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%
  • 통합 테스트 통과
  • 프론트엔드 연동 준비 완료

🔗 관련 링크