From f0d7a29be962c449c2174f61c76f64415d298063 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?=
 <lightone2017@codebridge-x.com>
Date: Wed, 11 Mar 2026 10:32:50 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20[db]=20codebridge=20DB=20=EB=B6=84?=
 =?UTF-8?q?=EB=A6=AC=20=EB=AC=B8=EC=84=9C=EC=97=90=20=ED=81=AC=EB=A1=9C?=
 =?UTF-8?q?=EC=8A=A4=20DB=20FK=20=EC=A0=9C=EA=B1=B0=20=EB=82=B4=EC=9A=A9?=
 =?UTF-8?q?=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 깨진 FK 제약조건 52개 제거 (users, tenants 등 참조) 문서화
- 운영 서버 적용 절차 5단계 → 6단계로 개정 (API 마이그레이션 단계 추가)
---
 system/database/codebridge-separation.md | 78 +++++++++++++++++++++---
 1 file changed, 68 insertions(+), 10 deletions(-)

diff --git a/system/database/codebridge-separation.md b/system/database/codebridge-separation.md
index 9022cbe..d4c5195 100644
--- a/system/database/codebridge-separation.md
+++ b/system/database/codebridge-separation.md
@@ -2,7 +2,7 @@
 
 > **작성일**: 2026-03-07
 > **상태**: 로컬/개발 서버 적용 완료, **운영 서버 코드 revert 상태 — DB 선행 작업 필요**
-> **최종 수정**: 2026-03-09 — API 사용 테이블 점검, 로컬/개발 samdb 삭제 완료, 운영 코드 revert
+> **최종 수정**: 2026-03-11 — 크로스 DB FK 제약조건 52개 제거 (개발+운영 적용 완료)
 
 ---
 
@@ -247,7 +247,53 @@ SAM 프로젝트의 DB를 **서비스용**과 **내부 관리용**으로 분리
 > - kent가 main에서 revert 2건 push → 운영 서버 정상 복구
 > - **교훈: 운영 서버는 반드시 DB 선행 작업(1~2단계) 완료 후 코드 배포(3단계)**
 
-### 4.2 코드 변경 사항
+### 4.2 크로스 DB FK 제약조건 제거 (2026-03-11)
+
+> **문제**: codebridge 테이블의 FK 제약조건이 sam DB의 `users`, `tenants` 등을 참조하여 INSERT 실패 발생.
+> **증상**: `esign_field_templates` INSERT 시 `SQLSTATE[23000]` FK violation (created_by → users(id))
+> **원인**: sam → codebridge로 테이블 이동 시, FK 제약조건은 이동되지 않고 sam의 테이블을 계속 참조.
+> **해결**: 마이그레이션으로 codebridge DB의 깨진 FK 52개 일괄 제거.
+
+| 참조 테이블 (sam에만 존재) | FK 수 | 영향 테이블 예시 |
+|---|---|---|
+| `users` | 27개 | esign_*, admin_*, business_income_payments, sales_* |
+| `tenants` | 16개 | account_codes, esign_*, barobill_*, hometax_invoices |
+| `departments` | 1개 | admin_pm_issues |
+| `processes` | 1개 | equipment_process |
+| `prospects` | 1개 | demo_links |
+| `clients` | 1개 | expense_accounts |
+| `barobill_card_transactions` | 1개 | barobill_card_transaction_amount_logs |
+| **합계** | **48개** | |
+
+> **참고**: FK 제거는 데이터 조회(JOIN/SELECT)에 영향 없음. FK는 INSERT/UPDATE 시 참조 무결성 검증만 수행하며, 실제 데이터 조회는 코드 레벨(Eloquent 관계)에서 처리한다.
+
+**마이그레이션 파일**: `api/database/migrations/2026_03_11_100000_drop_broken_foreign_keys_from_codebridge.php`
+
+```php
+// 안전한 FK 삭제: 존재 여부 확인 후 제거
+private function dropForeignKeySafe(string $connection, string $table, string $foreignKey): void
+{
+    $exists = DB::connection($connection)->select("
+        SELECT 1 FROM information_schema.TABLE_CONSTRAINTS
+        WHERE TABLE_SCHEMA = DATABASE()
+          AND TABLE_NAME = ? AND CONSTRAINT_NAME = ?
+          AND CONSTRAINT_TYPE = 'FOREIGN KEY'
+    ", [$table, $foreignKey]);
+
+    if (! empty($exists)) {
+        DB::connection($connection)->statement(
+            "ALTER TABLE `{$table}` DROP FOREIGN KEY `{$foreignKey}`"
+        );
+    }
+}
+```
+
+| 환경 | 적용 상태 |
+|------|----------|
+| 개발 서버 | ✅ 2026-03-11 마이그레이션 실행 완료 (7초) |
+| 운영 서버 | ✅ 2026-03-11 cherry-pick → main push 완료 |
+
+### 4.3 코드 변경 사항
 
 **config/database.php** — `codebridge` connection 추가:
 
@@ -282,7 +328,7 @@ class SalesPartner extends Model
 
 > **주의**: API 사용 테이블 22개에 해당하는 MNG 모델은 `$connection = 'codebridge'`를 설정하지 않는다. 기본 samdb connection을 사용해야 API와 동일한 데이터를 참조한다.
 
-### 4.3 samdb 테이블 삭제 절차 (개발 서버 완료)
+### 4.4 samdb 테이블 삭제 절차 (개발 서버 완료)
 
 > Sales 테이블 그룹은 FK 상호 참조가 있어 `FOREIGN_KEY_CHECKS = 0`으로 일괄 삭제.
 
@@ -309,7 +355,7 @@ SET FOREIGN_KEY_CHECKS = 1;
 > **현재 상태**: 운영 서버 main 코드는 revert 상태 (codebridge 코드 없음). DB 작업 완료 후 코드 재배포 필요.
 > **⚠️ 교훈**: 2026-03-09에 DB 없이 코드만 배포하여 장애 위험 발생 → **반드시 DB 선행 후 코드 배포**
 
-### 순서 (반드시 1 → 2 → 3 → 4 → 5 순서로)
+### 순서 (반드시 1 → 2 → 3 → 4 → 5 → 6 순서로)
 
 **1단계: 운영 sam DB 백업**
 
@@ -357,7 +403,18 @@ echo 'CODEBRIDGE_DB_DATABASE=codebridge' >> /home/webservice/mng/.env
 cd /home/webservice/mng && php artisan config:clear
 ```
 
-**4단계: MNG 코드 재배포 (main cherry-pick)**
+**4단계: API 마이그레이션 실행 (크로스 DB FK 제거)**
+
+> codebridge 테이블이 sam의 users, tenants 등을 참조하는 깨진 FK 52개를 제거한다.
+> 이 마이그레이션은 이미 API main 브랜치에 포함되어 있다.
+
+```bash
+cd /home/webservice/api
+git pull origin main
+php artisan migrate --force
+```
+
+**5단계: MNG 코드 재배포 (main cherry-pick)**
 
 > develop에 codebridge 코드가 있으므로, revert 커밋 이후 develop의 최신 커밋을 cherry-pick.
 > 또는 develop의 해당 커밋을 다시 cherry-pick하여 main에 push.
@@ -371,7 +428,7 @@ git push origin main
 git checkout develop
 ```
 
-**5단계: 동작 확인 + samdb 테이블 삭제 (선택)**
+**6단계: 동작 확인 + samdb 테이블 삭제 (선택)**
 
 MNG 관리자 페이지에서 영업관리, 설비, 재무 등 주요 메뉴 동작 확인 후, 문제없으면 sam DB에서 59개 테이블 삭제.
 
@@ -399,9 +456,10 @@ SET FOREIGN_KEY_CHECKS = 1;
 ```
 
 > **⚠️ 핵심 주의사항**:
-> - 반드시 **1→2→3→4** 순서 (DB 먼저, 코드 나중)
-> - 4단계(코드 배포) 전에 3단계(.env)까지 완료되어야 함
-> - 5단계(samdb 삭제)는 4단계 동작 확인 후 선택적 수행
+> - 반드시 **1→2→3→4→5→6** 순서 (DB 먼저, 코드 나중)
+> - 4단계(FK 제거) 전에 3단계(.env)까지 완료되어야 함
+> - 5단계(MNG 코드 배포) 전에 4단계(API 마이그레이션)까지 완료되어야 함
+> - 6단계(samdb 삭제)는 5단계 동작 확인 후 선택적 수행
 
 ---
 
@@ -440,4 +498,4 @@ SET FOREIGN_KEY_CHECKS = 1;
 
 ---
 
-**최종 업데이트**: 2026-03-09 (운영 revert 반영, 적용 절차 5단계로 개정)
+**최종 업데이트**: 2026-03-11 (크로스 DB FK 52개 제거, 적용 절차 6단계로 개정)