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

# codebridge DB 분리

> **작성일**: 2026-03-07
> **상태**: 로컬/개발 서버 적용 완료, 운영 서버 미적용
> **최종 수정**: 2026-03-09 — API 사용 테이블 점검 완료, codebridge 이동 대상 100개 → 59개로 축소, 개발 서버 samdb에서 59개 테이블 삭제 완료

---

## 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절](#3-api-사용-테이블--samdb-유지-필수-22개) 참조.
> 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` → 실제 테이블명 |
| `api_deprecations` | API 지원종료 관리 | |
| `api_environments` | API 환경 설정 | |
| `api_histories` | API 호출 이력 | |
| `api_templates` | API 템플릿 | |

### 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 | 59개 | 미수행 | O | O (develop) | 정상 작동 |
| **개발 서버** | O | 59개 | **59개 삭제 완료** | O | O (develop) | 정상 작동 |
| **운영 서버** | X | X | X | X | X (revert) | 미적용 (기존 samdb 사용) |

> **2026-03-09 작업 내역**:
> - API 사용 테이블 22개: codebridge 이동 대상에서 제외 → samdb 유지
> - `finance_*` 17개 + `barobill_companies` 1개: codebridge에 없는 유령 테이블 → samdb에서만 삭제
> - Equipment 하위 4개 테이블: FK 의존성으로 codebridge 이동 대상에 추가 (55→59개)
> - **개발 서버 samdb에서 59개 테이블 DROP 완료** (FOREIGN_KEY_CHECKS=0 사용)
> - 백업: `/home/pro/backup/sam_backup_20260309.sql.gz` (6.3MB)
> - 개발 서버 상태: samdb 276개 테이블, codebridge 101개 테이블
>
> **테이블명 불일치 발견 (수정 완료)**:
> - `api_bookmarks` → 실제: `admin_api_bookmarks`
> - `meeting_logs` → 실제: `admin_meeting_logs`
> - `biz_certs` → 실제: `biz_cert` (단수형)

### 4.2 코드 변경 사항

**config/database.php** — `codebridge` connection 추가:

```php
'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개만):

```php
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`으로 일괄 삭제.

```sql
-- 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;
```

> **롤백**: 백업에서 특정 테이블만 복원 가능
> ```bash
> gunzip < /home/pro/backup/sam_backup_20260309.sql.gz | mysql -u codebridge -p sam
> ```

---

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

> **전제**: 운영 서버 SSH 접근 + DB root 권한 필요
> **코드는 이미 main에 배포 완료** — 운영 서버에 codebridge DB만 생성하면 즉시 적용됨

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

**1단계: codebridge DB 생성 + 테이블 복사**

```bash
# 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 → import)
mysqldump -u codebridge -p sam [테이블목록] | mysql -u codebridge -p codebridge
```

**2단계: .env 설정**

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

**3단계: MNG 웹 동작 확인**

codebridge connection이 활성화되므로 MNG 관리자 페이지에서 영업관리, 설비, 재무 등 주요 메뉴 동작 확인.

**4단계: samdb에서 59개 테이블 삭제 (선택)**

개발 서버에서 검증 완료 후, 운영 서버에서도 삭제하여 실질적 분리 완성.

```sql
SET FOREIGN_KEY_CHECKS = 0;
DROP TABLE IF EXISTS [59개 테이블 목록];
SET FOREIGN_KEY_CHECKS = 1;
```

> **주의**: 2단계 전에 1단계가 완료되어야 한다. DB가 없는 상태에서 .env를 설정하면 MNG 페이지 접속 불가.
> **코드 배포**: 이미 main에 59개 모델의 `$connection = 'codebridge'` 코드가 반영됨. .env에 `CODEBRIDGE_DB_DATABASE`가 없으면 기본값 'codebridge'가 사용되므로, DB가 존재하지 않으면 에러 발생. 반드시 1단계 먼저 완료할 것.

---

## 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](README.md) — DB 스키마 전체 현황
- [codebridge-db-separation-plan.md](/home/aweso/sam/docs/plans/codebridge-db-separation-plan.md) — 분리 작업 계획서 (plans/)

---

**최종 업데이트**: 2026-03-09