sam-docs/sam/docs/system/database/codebridge-separation.md

codebridge DB 분리

작성일: 2026-03-07 상태: 로컬/개발 서버 적용 완료, 운영 서버 코드 revert 상태 — DB 선행 작업 필요 최종 수정: 2026-03-09 — API 사용 테이블 점검, 로컬/개발 samdb 삭제 완료, 운영 코드 revert

---

1. 개요

1.1 목적

SAM 프로젝트의 DB를 서비스용과 내부 관리용으로 분리한다.

• samdb: React 서비스가 사용하는 테이블 (수주, 견적, 생산, 거래처 등)
• codebridge: MNG(관리자 패널)에서만 사용하는 코드브릿지엑스 내부 관리 테이블

1.2 핵심 원칙

• codebridge DB에 테이블을 복사한 후, samdb에서 해당 테이블을 삭제하여 실질적 분리
• MNG 모델에 $connection = 'codebridge'를 설정하여 읽기 대상 DB만 변경
• React/API 서비스에는 영향 없음
• 개발 서버: samdb에서 59개 테이블 삭제 완료 (백업: /home/pro/backup/sam_backup_20260309.sql.gz)

1.3 분리 기준

분류	대상 DB	기준
React 서비스 테이블	samdb (유지)	React 프론트엔드 또는 API에서 사용
MNG 전용 테이블	codebridge (이동)	MNG에서만 사용, React/API 미참조
공통 테이블	samdb (유지)	양쪽 모두 사용 (users, tenants 등)
API 사용 테이블	samdb (유지 필수)	API에 모델/서비스/컨트롤러 존재 — 이동 시 데이터 불일치 발생

경고: API에서 모델/서비스/컨트롤러로 참조하는 테이블을 codebridge로 이동하면, API는 samdb에 쓰고 MNG는 codebridge에서 읽게 되어 데이터 불일치가 발생한다. 절대 이동 금지.

---

2. codebridge 테이블 목록 (59개)

2026-03-09 점검: API 프로젝트 전체 코드 조사를 통해 API에서 사용하는 22개 테이블을 제외함. 제외된 테이블은 3절 참조. Equipment 하위 테이블 4개 추가 (FK 의존성으로 equipments와 동일 DB 필수).

Admin (9)

테이블	설명
admin_api_flows	API 플로우 정의
admin_api_flow_runs	API 플로우 실행 이력
admin_pm_daily_logs	PM 일일 로그
admin_pm_daily_log_entries	PM 일일 로그 항목
admin_pm_issues	PM 이슈
admin_pm_projects	PM 프로젝트
admin_pm_tasks	PM 태스크
admin_roadmap_milestones	로드맵 마일스톤
admin_roadmap_plans	로드맵 계획

DevTools (5)

테이블	설명	비고
admin_api_bookmarks	API 북마크	기존명 api_bookmarks
admin_api_deprecations	API 지원종료 관리	기존명 api_deprecations
admin_api_environments	API 환경 설정	기존명 api_environments
admin_api_histories	API 호출 이력	기존명 api_histories
admin_api_templates	API 템플릿	기존명 api_templates

Sales (17)

테이블	설명
sales_partners	영업 파트너
sales_managers	영업 담당자
sales_manager_documents	영업 담당자 문서
sales_commissions	영업 수당
sales_commission_details	영업 수당 상세
sales_consultations	영업 상담
sales_contract_products	계약 제품
sales_products	영업 제품
sales_product_categories	영업 제품 카테고리
sales_prospects	영업 전망
sales_prospect_consultations	전망 상담
sales_prospect_products	전망 제품
sales_prospect_scenarios	전망 시나리오
sales_records	영업 실적
sales_scenario_checklists	시나리오 체크리스트
sales_tenant_managements	테넌트 영업 관리
tenant_prospects	테넌트 전망

Finance (9)

테이블	설명
condolence_expenses	경조사비
consulting_fees	컨설팅비
corporate_cards	법인카드
corporate_card_prepayments	법인카드 선결제
customer_settlements	고객 정산
daily_fund_memos	일일 자금 메모
daily_fund_transactions	일일 자금 거래
incomes	수입
vat_records	부가세 기록

ESign (2)

테이블	설명
esign_field_templates	전자서명 필드 템플릿
esign_field_template_items	전자서명 필드 항목

esign_contracts, esign_audit_logs, esign_sign_fields, esign_signers는 API에서 전자계약 기능으로 사용 중 → samdb 유지

Equipment (6)

테이블	설명
equipments	설비
equipment_processes	설비 공정
equipment_inspections	설비 점검 (FK → equipments)
equipment_inspection_details	설비 점검 상세 (FK → equipment_inspections)
equipment_inspection_templates	설비 점검 템플릿 (FK → equipments)
equipment_repairs	설비 수리 (FK → equipments)

Equipment 하위 4개 테이블은 equipments에 FK 의존하므로 반드시 동일 DB에 있어야 한다.

HR (1)

테이블	설명
business_income_payments	사업소득 지급

income_tax_brackets는 API IncomeTaxBracketSeeder에서 초기 데이터 관리 → samdb 유지

System (1)

테이블	설명
ai_configs	AI 설정

ai_pricing_configs, ai_token_usages는 API 모델에서 직접 사용 → samdb 유지

기타 (9)

테이블	설명	비고
biz_cert	사업자등록증	문서 기존명 biz_certs → 실제 테이블명 (단수)
cm_songs	R&D 곡 관리
construction_site_photos	시공 현장 사진
construction_site_photo_rows	시공 사진 행
admin_meeting_logs	회의 로그	문서 기존명 meeting_logs → 실제 테이블명
meeting_minutes	회의록
meeting_minute_segments	회의록 세그먼트
interview_knowledges	면접 지식
sales_records	매출 기록

---

3. API 사용 테이블 — samdb 유지 필수 (22개)

경고: 아래 테이블은 API 프로젝트에서 모델/서비스/컨트롤러/시더로 직접 참조한다. 절대 codebridge로 이동 금지.

2026-03-09 점검: sam/api 프로젝트 전체 코드 (모델, 컨트롤러, 서비스, 라우트, 시더) 조사 완료.

Barobill (12) — 전체 samdb 유지

테이블	API 사용처	사유
barobill_billing_records	BarobillBillingService	과금 기록 CRUD
barobill_members	BarobillUsageService	회원사 사용량 집계
barobill_monthly_summaries	BarobillBillingService	월별 집계 갱신
barobill_pricing_policies	BarobillUsageService	과금 계산
bank_sync_statuses	BankSyncStatus 모델	동기화 상태 추적
bank_transactions	BankTransactionController	은행 거래 조회/분개
bank_transaction_overrides	BankTransactionOverride 모델	거래 재정의
bank_transaction_splits	BankTransactionController	은행 거래 분개
card_transaction_amount_logs	CardTransactionAmountLog 모델	금액 수정 이력 + FK → card_transactions
card_transaction_hides	CardTransactionHide 모델	거래 숨김 + FK → card_transactions
hometax_invoices	BarobillUsageService	세금계산서 사용량 집계
hometax_invoice_journals	HometaxInvoiceJournal 모델	세금계산서 분개 + FK → hometax_invoices

핵심: API의 BarobillController, BarobillSettingController, BarobillService, EntertainmentService가 바로빌 테이블을 직접 참조. barobill_card_transactions (samdb 유지)와 FK로 연결된 자식 테이블도 분리 불가.

ESign (4) — API 전자계약 기능

테이블	API 사용처	사유
esign_contracts	EsignContractController, EsignService	전자계약 CRUD
esign_audit_logs	EsignService	감사 추적 기록
esign_sign_fields	EsignService	서명 위치 데이터
esign_signers	EsignService	서명자 정보/인증

Audit (2) — API 전사 감사 시스템

테이블	API 사용처	사유
audit_logs	AuditLog 모델, AuditLogService, AuditRollbackService	전사 DML 감사
trigger_audit_logs	TriggerAuditLog 모델, TriggerAuditLogController, RegenerateAuditTriggers 명령	DB 트리거 감사 + 파티셔닝 관리

DevTools (1)

테이블	API 사용처	사유
api_request_logs	ApiRequestLog 모델, SystemStatService	API 통계 집계

System (2)

테이블	API 사용처	사유
ai_pricing_configs	AiPricingConfig 모델	AI 서비스 비용 계산 (캐시 기반)
ai_token_usages	AiTokenUsage 모델	멀티테넌트 AI 토큰 사용량 추적

HR (1)

테이블	API 사용처	사유
income_tax_brackets	IncomeTaxBracketSeeder	소득세 구간 초기 데이터 관리

---

4. 적용 현황

4.1 환경별 상태

환경	codebridge DB	테이블 복사	samdb 삭제	.env 설정	MNG 코드	상태
로컬 Docker	O	100개	58개 삭제	O	O (develop)	✅ 정상 작동, samdb 265개
개발 서버	O	101개	63개 삭제	O	O (develop)	✅ 정상 작동, samdb 265개
운영 서버	X	X	X	X	revert됨	⚠️ DB 선행 작업 후 코드 재배포 필요

2026-03-09 작업 내역:

• API 사용 테이블 22개: codebridge 이동 대상에서 제외 → samdb 유지
• finance_* 17개 + barobill_companies 1개: codebridge에 없는 유령 테이블 → samdb에서만 삭제
• Equipment 하위 4개 테이블: FK 의존성으로 codebridge 이동 대상에 추가 (55→59개)
• 개발 서버 samdb에서 63개 테이블 DROP 완료 (59개 + DevTools 실제 테이블명 4개 추가분)
• 로컬 samdb에서 58개 테이블 DROP 완료 → 로컬/개발 265개로 동기화
• 로컬에 quality_documents 등 4개 테이블 구조 동기화 (개발서버에서 복사)
• 백업: /home/pro/backup/sam_backup_20260309.sql.gz (6.3MB)

테이블명 불일치 발견 (수정 완료):

• api_bookmarks → 실제: admin_api_bookmarks
• meeting_logs → 실제: admin_meeting_logs
• biz_certs → 실제: biz_cert (단수형)
• DevTools 4개: api_deprecations → admin_api_deprecations, api_environments → admin_api_environments, api_histories → admin_api_histories, api_templates → admin_api_templates

운영 서버 revert 사유 (2026-03-09):

• MNG main에 codebridge 코드 2건 cherry-pick → Jenkins 배포됨 (빌드 #456, #457)
• 운영 서버에 codebridge DB가 없는 상태에서 코드 배포 → 59개 모델 사용 페이지 오류 발생 위험
• kent가 main에서 revert 2건 push → 운영 서버 정상 복구
• 교훈: 운영 서버는 반드시 DB 선행 작업(1~2단계) 완료 후 코드 배포(3단계)

4.2 코드 변경 사항

config/database.php — codebridge connection 추가:

'codebridge' => [
    'driver' => 'mysql',
    'host' => env('CODEBRIDGE_DB_HOST', env('DB_HOST', '127.0.0.1')),
    'port' => env('CODEBRIDGE_DB_PORT', env('DB_PORT', '3306')),
    'database' => env('CODEBRIDGE_DB_DATABASE', 'codebridge'),
    'username' => env('CODEBRIDGE_DB_USERNAME', env('DB_USERNAME')),
    'password' => env('CODEBRIDGE_DB_PASSWORD', env('DB_PASSWORD')),
    // ... (mysql 기본 설정과 동일)
],

.env — 추가 설정:

CODEBRIDGE_DB_DATABASE=codebridge

MNG 모델 — $connection 속성 추가 (codebridge 59개만):

class SalesPartner extends Model
{
    protected $connection = 'codebridge';  // 추가
    protected $table = 'sales_partners';
    // ...
}

주의: API 사용 테이블 22개에 해당하는 MNG 모델은 $connection = 'codebridge'를 설정하지 않는다. 기본 samdb connection을 사용해야 API와 동일한 데이터를 참조한다.

4.3 samdb 테이블 삭제 절차 (개발 서버 완료)

Sales 테이블 그룹은 FK 상호 참조가 있어 FOREIGN_KEY_CHECKS = 0으로 일괄 삭제.

-- FK 체크 비활성화 (Sales, Equipment 등 FK 체인 테이블)
SET FOREIGN_KEY_CHECKS = 0;

-- 59개 테이블 DROP (codebridge에 복제 완료 확인 후)
DROP TABLE IF EXISTS admin_api_flows, admin_api_flow_runs, ...;

SET FOREIGN_KEY_CHECKS = 1;

롤백: 백업에서 특정 테이블만 복원 가능

gunzip < /home/pro/backup/sam_backup_20260309.sql.gz | mysql -u codebridge -p sam

---

5. 운영 서버 적용 절차 (미완료)

전제: 운영 서버 SSH 접근 + DB root 권한 필요 현재 상태: 운영 서버 main 코드는 revert 상태 (codebridge 코드 없음). DB 작업 완료 후 코드 재배포 필요. ⚠️ 교훈: 2026-03-09에 DB 없이 코드만 배포하여 장애 위험 발생 → 반드시 DB 선행 후 코드 배포

순서 (반드시 1 → 2 → 3 → 4 → 5 순서로)

1단계: 운영 sam DB 백업

# 운영 서버 접속 후
mysqldump -u codebridge -p'[운영PW]' sam --single-transaction > ~/backup/sam_backup_$(date +%Y%m%d).sql
gzip ~/backup/sam_backup_$(date +%Y%m%d).sql

2단계: codebridge DB 생성 + 59개 테이블 복사

# DB 생성
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS codebridge CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# DB 계정 권한 부여
mysql -u root -p -e "GRANT ALL PRIVILEGES ON codebridge.* TO 'codebridge'@'localhost'; FLUSH PRIVILEGES;"

# sam에서 59개 테이블 구조+데이터 복사
mysqldump -u codebridge -p sam \
  admin_api_flows admin_api_flow_runs \
  admin_pm_daily_logs admin_pm_daily_log_entries admin_pm_issues admin_pm_projects admin_pm_tasks \
  admin_roadmap_milestones admin_roadmap_plans \
  admin_api_bookmarks admin_api_deprecations admin_api_environments admin_api_histories admin_api_templates \
  sales_partners sales_managers sales_manager_documents sales_commissions sales_commission_details \
  sales_consultations sales_contract_products sales_products sales_product_categories \
  sales_prospects sales_prospect_consultations sales_prospect_products sales_prospect_scenarios \
  sales_records sales_scenario_checklists sales_tenant_managements tenant_prospects \
  condolence_expenses consulting_fees corporate_cards corporate_card_prepayments \
  customer_settlements daily_fund_memos daily_fund_transactions incomes vat_records \
  esign_field_templates esign_field_template_items \
  equipments equipment_process equipment_inspections equipment_inspection_details \
  equipment_inspection_templates equipment_repairs \
  business_income_payments ai_configs \
  biz_cert cm_songs construction_site_photos construction_site_photo_rows \
  admin_meeting_logs meeting_minutes meeting_minute_segments \
  interview_knowledge \
  | mysql -u codebridge -p codebridge

3단계: .env 설정

echo 'CODEBRIDGE_DB_DATABASE=codebridge' >> /home/webservice/mng/.env
cd /home/webservice/mng && php artisan config:clear

4단계: MNG 코드 재배포 (main cherry-pick)

develop에 codebridge 코드가 있으므로, revert 커밋 이후 develop의 최신 커밋을 cherry-pick. 또는 develop의 해당 커밋을 다시 cherry-pick하여 main에 push.

# 로컬에서 실행
cd /home/aweso/sam/mng
git checkout main && git pull origin main
git cherry-pick <develop의 codebridge 커밋 해시>
git push origin main
git checkout develop

5단계: 동작 확인 + samdb 테이블 삭제 (선택)

MNG 관리자 페이지에서 영업관리, 설비, 재무 등 주요 메뉴 동작 확인 후, 문제없으면 sam DB에서 59개 테이블 삭제.

SET FOREIGN_KEY_CHECKS = 0;
DROP TABLE IF EXISTS
  admin_api_flows, admin_api_flow_runs,
  admin_pm_daily_logs, admin_pm_daily_log_entries, admin_pm_issues, admin_pm_projects, admin_pm_tasks,
  admin_roadmap_milestones, admin_roadmap_plans,
  admin_api_bookmarks, admin_api_deprecations, admin_api_environments, admin_api_histories, admin_api_templates,
  sales_partners, sales_managers, sales_manager_documents, sales_commissions, sales_commission_details,
  sales_consultations, sales_contract_products, sales_products, sales_product_categories,
  sales_prospects, sales_prospect_consultations, sales_prospect_products, sales_prospect_scenarios,
  sales_records, sales_scenario_checklists, sales_tenant_managements, tenant_prospects,
  condolence_expenses, consulting_fees, corporate_cards, corporate_card_prepayments,
  customer_settlements, daily_fund_memos, daily_fund_transactions, incomes, vat_records,
  esign_field_templates, esign_field_template_items,
  equipments, equipment_process, equipment_inspections, equipment_inspection_details,
  equipment_inspection_templates, equipment_repairs,
  business_income_payments, ai_configs,
  biz_cert, cm_songs, construction_site_photos, construction_site_photo_rows,
  admin_meeting_logs, meeting_minutes, meeting_minute_segments,
  interview_knowledge;
SET FOREIGN_KEY_CHECKS = 1;

⚠️ 핵심 주의사항:

• 반드시 1→2→3→4 순서 (DB 먼저, 코드 나중)
• 4단계(코드 배포) 전에 3단계(.env)까지 완료되어야 함
• 5단계(samdb 삭제)는 4단계 동작 확인 후 선택적 수행

---

6. 아키텍처 다이어그램

                    React (사용자)
                         |
                    API 서버 (Laravel)
                         |
                    ┌─────┴─────┐
                    |           |
                  samdb      sam_stat
                (서비스 DB)  (통계 DB)
                    |
                    |  (공통 + API 사용 테이블: users, tenants, barobill_*, esign_*, audit_* 등)
                    |
                MNG (관리자)
                    |
              ┌─────┴─────┐
              |           |
            samdb     codebridge
          (공통 참조)  (MNG 전용 59개)

• React → API → samdb: 서비스 트래픽 (수주, 견적, 생산, 바로빌, 전자서명 등)
• MNG → samdb: 공통 테이블 (users, tenants, menus) + API 사용 테이블 22개 참조
• MNG → codebridge: MNG 전용 데이터 (영업관리, 재무, 설비, PM 도구 등)

---

관련 문서

• database/README.md — DB 스키마 전체 현황
• codebridge-db-separation-plan.md — 분리 작업 계획서 (plans/)

---

최종 업데이트: 2026-03-09 (운영 revert 반영, 적용 절차 5단계로 개정)