Files

권혁성 2bbf220dc8 docs:견적관리 분석 문서 및 INDEX 업데이트

- INDEX.md 업데이트
- 견적관리 URL 마이그레이션 계획 수정
- API 분석 리포트, tenant-id 준수 계획 추가
- 견적관리 기능 문서 추가

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-01 20:37:04 +09:00

18 KiB

Raw Blame History

SAM API 전체 분석 보고서

작성일: 2026-01-29 목적: api/, mng/, react/ 프로젝트 간 API 중복/통합/미사용 분석 및 관계 정리 기준 문서: api/routes/api/v1/.php, mng/routes/api.php, mng/routes/web.php, react/src/lib/api/ 상태: ✅ 분석 완료

📍 분석 결과 요약

항목	수치
api/ 엔드포인트	~710+
mng/ 엔드포인트	~300+
React 실제 사용	~80+ (api/ 전체의 ~15%)
중복 도메인	10개
즉시 정리 가능	3건
통합 가능 그룹	6개

1. 개요

1.1 배경

SAM 프로젝트는 api/(REST API), mng/(관리자 패널), react/(프론트엔드) 3개 프로젝트로 구성되어 있으며, 각 프로젝트가 독립적으로 발전하면서 동일 도메인에 대한 API가 중복 생성되었다. 본 분석은 전체 API를 파악하고 정리 방안을 제시한다.

1.2 분석 범위

프로젝트	역할	분석 대상
api/	REST API 서버	routes/api/v1/*.php (14개 라우트 파일), 컨트롤러 138개
mng/	관리자 패널	routes/api.php, routes/web.php, 컨트롤러 90+개
react/	프론트엔드	src/lib/api/, src/hooks/, src/app/api/*

2. 프로젝트별 API 구조

2.1 API 프로젝트 (api/)

라우트 파일: api/routes/api/v1/

도메인	라우트 파일	엔드포인트 수	소비자
인증	`auth.php`	8	React, MNG
사용자	`users.php`	25	React
테넌트	`tenants.php`	18	React
관리자	`admin.php`	22	React, MNG
공통	`common.php`	95+	React, MNG
HR	`hr.php`	85+	React
재무	`finance.php`	130+	React
영업	`sales.php`	85+	React
재고	`inventory.php`	65+	React
생산	`production.php`	35+	React
설계	`design.php`	55+	React
파일	`files.php`	15	React
게시판	`boards.php`	70+	React
문서	`documents.php`	5+	React

2.2 MNG 프로젝트 (mng/)

API 소비 방식: 자체 모델로 DB 직접 접근 (api/ REST API를 거치지 않음)

도메인	엔드포인트 수	비고
사용자/역할/권한	30+	api/와 중복
메뉴/글로벌메뉴	25+	api/와 중복
게시판/필드	20+	api/와 중복
카테고리/글로벌	15+	api/와 중복
바로빌 (전체)	60+	MNG 전용 (외부 서비스)
프로젝트 관리	25+	MNG 전용
견적 공식	30+	MNG 전용
품목 필드	25+	MNG 전용
문서/템플릿	12+	api/와 중복
계좌/자금일정	18+	api/와 중복
기타 (회의록, 신용, 영업, Lab)	40+	MNG 전용

2.3 React 프론트엔드 (react/)

API 호출 방식: Next.js Proxy (/api/proxy/*) → Backend (/api/v1/*)

카테고리	주요 엔드포인트	사용 빈도
인증	login, logout, refresh, signup	높음
품목 CRUD	items, items/{id}, items/bom	높음
품목기준관리	item-master/* (pages, sections, fields)	높음
견적 계산	quotes/calculate, quotes/calculate/bom	높음
공통코드	settings/common/{group}	높음
대시보드	card-transactions/dashboard, loans/dashboard	중간
알림	today-issues/unread, unread/count	중간
거래처	clients, client-groups	중간
재고	stocks, work-results	중간
일괄작업	bulk-update-account-code	낮음
내보내기	attendances/export, salaries/export	낮음

3. 중복 API 분석

3.1 중복 컨트롤러 목록 (api/ vs mng/)

#	도메인	api/ 컨트롤러	mng/ 컨트롤러	중복 수준
1	사용자 관리	`Api\V1\Admin\AdminController`	`Api\Admin\UserController`	🔴 높음
2	역할 관리	`Api\V1\RoleController`	`Api\Admin\RoleController`	🔴 높음
3	메뉴 관리	`Api\V1\MenuController`	`Api\Admin\MenuController`	🔴 높음
4	카테고리	`Api\V1\CategoryController`	`Api\Admin\CategoryApiController`	🔴 높음
5	계좌 관리	`Api\V1\BankAccountController`	`Api\Admin\BankAccountController`	🔴 높음
6	권한 관리	`Api\V1\PermissionController`	`Api\Admin\PermissionController`	🟡 중간
7	부서 관리	`Api\V1\DepartmentController`	`Api\Admin\DepartmentController`	🟡 중간
8	게시판	`Api\V1\BoardController`	`Api\Admin\BoardController`	🟡 중간
9	문서	`Api\V1\Documents\DocumentController`	`Api\Admin\DocumentApiController`	🟡 중간
10	테넌트	`Api\V1\TenantController`	`Api\Admin\TenantController`	🟡 중간

3.2 상세 비교

(1) 사용자 관리 🔴

기능	api/	mng/	차이
기본 CRUD	✅	✅	동일
복구 (restore)	✅	✅	동일
비밀번호 초기화	✅	✅	동일
활성화/비활성화	✅ (PATCH /status)	❌	api/만
역할 부여/해제	✅ (POST/DELETE /roles)	❌	api/만
영구삭제	❌	✅ (DELETE /force)	mng/만 (슈퍼관리자)
개발용 로그인토큰	❌	✅ (POST /login-token)	mng/만
모달 데이터	❌	✅ (GET /modal)	mng/만

(2) 역할 관리 🔴

기능	api/	mng/	차이
기본 CRUD	✅	✅	동일
통계 (stats)	✅	❌	api/만
활성 목록 (active)	✅	❌	api/만

(3) 메뉴 관리 🔴

기능	api/	mng/	차이
기본 CRUD	✅	✅	동일
순서변경 (reorder)	✅	✅	동일
복구 (restore)	✅	✅	동일
활성화 토글	✅ (toggle)	✅ (toggle-active)	동일 기능
동기화	✅ (sync, sync-new, sync-updates)	❌	api/만
트리 구조	❌	✅ (tree)	mng/만
글로벌 복사	❌	✅ (copy-from-global)	mng/만
일괄 작업	❌	✅ (bulk-delete/restore/force)	mng/만
숨김 토글	❌	✅ (toggle-hidden)	mng/만
영구삭제	❌	✅ (force)	mng/만 (슈퍼관리자)

(4) 카테고리 🔴

기능	api/	mng/	차이
기본 CRUD	✅	✅	동일
트리/순서변경/이동	✅	✅	동일
활성화 토글	✅	✅	동일
필드 관리	✅ (fields CRUD, bulk-upsert)	❌	api/만
템플릿 관리	✅ (templates, apply, preview, diff)	❌	api/만
로그 조회	✅ (logs)	❌	api/만
글로벌 관리	❌	✅ (global-categories)	mng/만

(5) 계좌 관리 🔴

기능	api/	mng/	차이
기본 CRUD	✅	✅	동일
활성화 토글	✅	✅	동일
활성 목록 (active)	✅	❌	api/만
대표계좌 설정	✅ (set-primary)	❌	api/만
전체 조회 (all)	❌	✅	mng/만
요약 (summary)	❌	✅	mng/만
거래내역	❌	✅ (transactions)	mng/만
일괄 작업	❌	✅ (bulk-*)	mng/만
영구삭제/복구	❌	✅ (force/restore)	mng/만

(6) 권한 관리 🟡

기능	api/	mng/	차이
권한 매트릭스 조회	✅ (dept/role/user menu-matrix)	❌	api/만 (특화)
기본 CRUD	❌	✅	mng/만

분석: api/는 매트릭스 조회 전용, mng/는 CRUD 전용으로 기능 분리된 상태. 완전 중복은 아님.

4. 통합 가능 API

4.1 통합 대상 그룹

#	대상	현재 상태	통합 방안	우선순위
1	인증 API	signup + register 중복	register 제거 (signup 유지)	🔴
2	사용자 관리	api/ + mng/ 각각 CRUD	mng/ → api/ 호출로 전환	🔴
3	역할 관리	api/ + mng/ 각각 CRUD	api/에 통합, mng/는 호출만	🟡
4	메뉴 관리	api/ 동기화 + mng/ 관리 분리	관리: mng/, 조회+동기화: api/	🟡
5	대시보드 데이터	개별 엔드포인트 분산	통합 대시보드 API 제공	🟢
6	일괄 업데이트	withdrawals/deposits/sales 각각	공통 bulk-update 패턴	🟢

4.2 인증 API 중복 상세

현재:
  POST /v1/login              → 로그인
  POST /v1/logout             → 로그아웃
  POST /v1/signup             → 회원가입 (1)
  POST /v1/register           → 회원가입 (2) ← 중복!
  POST /v1/token-login        → 토큰 로그인 (MNG→DEV)
  POST /v1/refresh            → 토큰 갱신
  POST /v1/internal/exchange-token → 내부 서버 토큰 교환
  GET  /v1/debug-apikey       → 디버그용 ← 프로덕션 제거 필요

권장:
  - register 제거 (signup 유지)
  - debug-apikey 프로덕션 비활성화

5. 미사용 API

5.1 React에서 호출하지 않는 api/ 도메인

도메인	엔드포인트 수	미사용 이유
HR 전체 (employees, attendance, leave, approval)	~80+	MNG에서 직접 관리 또는 React 미구현
생산 대부분 (processes, work-orders, inspections)	~35+	work-results만 사용
설계 전체 (models, versions, bom-templates)	~55+	견적 계산 시 간접 사용만
재무 대부분 (cards, payroll, bad-debts 등)	~100+	CEO 대시보드 일부만 사용
사용자 초대 (invitations)	~5	React 미구현
알림 설정 (notification-settings)	~5	React 미구현
프로필 관리 (profiles)	~5	React 미구현
팝업 관리 (popups)	~5	React 미구현
AI 리포트 (reports/ai)	~4	React 미구현
구독/결제 (subscriptions, payments)	~20+	React 미구현
현장/시공 (sites, construction)	~30+	React 미구현
검사 관리 (inspections)	~8	React 미구현

참고: "미사용"은 React 프론트엔드 기준. MNG에서 Blade UI로 직접 사용하거나 향후 구현 예정인 경우 포함.

5.2 완전 미사용 가능성 높은 API

엔드포인트	이유	조치 권장
`GET /v1/debug-apikey`	디버그 전용	프로덕션 비활성화
`POST /v1/register`	signup과 중복	제거
`GET /v1/welfare/*`	React/MNG 모두 미호출 확인 필요	사용 여부 확인
`GET /v1/entertainment/*`	React/MNG 모두 미호출 확인 필요	사용 여부 확인
`GET /v1/calendar/schedules`	React 미호출	사용 여부 확인
`GET /v1/comprehensive-analysis`	React 미호출	사용 여부 확인

5.3 MNG 전용 기능 (정상)

기능	설명	상태
바로빌 (Barobill)	전자세금계산서, 카드, 홈택스 연동	✅ 정상
프로젝트 관리	프로젝트, 태스크, 이슈	✅ 정상
데일리 로그	일일 스크럼	✅ 정상
견적 공식	견적 계산 공식 관리	✅ 정상
회의록	녹음, AI 요약 (Google Cloud)	✅ 정상
신용 평가	Coocon API 연동	✅ 정상
영업 관리	매니저, 전망, 기록	✅ 정상
DevTools	API 탐색기, 흐름 테스터	✅ 정상
Lab/R&D	AI, 전략 실험	✅ 정상

6. 프로젝트 간 API 관계도

6.1 시스템 구조

┌─────────────────────────────────────────────────────────────┐
│                      사용자 (브라우저)                         │
│                                                              │
│     ┌──────────────┐            ┌──────────────────┐         │
│     │  React App   │            │   MNG Admin      │         │
│     │ (dev.sam.kr) │            │  (mng.sam.kr)    │         │
│     └──────┬───────┘            └──────┬───────────┘         │
│            │                           │                     │
│     Next.js Proxy               자체 모델 직접 사용           │
│   (/api/proxy/*)              + 일부 api/ 호출               │
│            │                           │                     │
│            ▼                           │                     │
│     ┌──────────────┐                   │                     │
│     │   API 서버    │◄─────────────────┘                     │
│     │ (api.sam.kr)  │     token-login,                       │
│     │              │     DevTools API 탐색                    │
│     └──────┬───────┘                                         │
│            │                                                 │
│            ▼                                                 │
│     ┌──────────────┐                                         │
│     │   Database   │◄──── MNG도 동일 DB 직접 접근             │
│     │   (MySQL)    │                                         │
│     └──────────────┘                                         │
└─────────────────────────────────────────────────────────────┘

외부 API:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Google   │ │ Coocon   │ │  FCM     │ │   NTS    │
│ Cloud    │ │ (신용)   │ │ (푸시)   │ │ (홈택스)  │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
     └────────────┴────────────┴─────────────┘
                       │
                   MNG에서 호출

6.2 데이터 흐름

흐름	방식	설명
React → API	HTTP (Proxy)	모든 비즈니스 로직 API 호출
MNG → DB	직접 모델	관리 기능은 DB 직접 접근
MNG → API	HTTP	token-login, DevTools, 일부 동기화
MNG → 외부	HTTP	Barobill, Google Cloud, Coocon, NTS
API → DB	직접 모델	모든 비즈니스 로직

6.3 중복 발생 원인

문제: MNG가 api/를 호출하지 않고 DB 직접 접근
     → 동일 도메인에 대해 api/, mng/ 각각 독립 컨트롤러 보유
     → 비즈니스 로직 분산, 유지보수 부담 증가

현재:
  React  → api/ (REST API) → DB
  MNG    → DB 직접              ← 여기가 문제

이상적:
  React  → api/ (REST API) → DB
  MNG    → api/ (REST API) → DB  (관리자 전용 엔드포인트 추가)

7. 개선 권장사항

7.1 즉시 정리 (Quick Wins) 🔴

#	작업	영향	노력
1	`POST /v1/register` 제거 (signup 유지)	코드 정리	소
2	`GET /v1/debug-apikey` 프로덕션 비활성화	보안 강화	소
3	미사용 Swagger 문서 정리	문서 정확성	소

7.2 중복 해소 (Medium Term) 🟡

#	작업	현재	목표
1	사용자 관리 통합	api/ + mng/ 각각	api/ 마스터, mng/ 관리자 기능만 추가
2	역할 관리 통합	api/ + mng/ 각각	api/ 단일 소스
3	카테고리 통합	api/ + mng/ 각각	api/ 마스터, mng/ 글로벌 관리만 유지
4	계좌 관리 통합	api/ + mng/ 각각	하나로 통합
5	메뉴 관리 정리	api/ 동기화 + mng/ 관리	역할 분리 명확화

7.3 아키텍처 개선 (Long Term) 🟢

#	작업	설명
1	MNG → API 호출 전환	MNG가 DB 직접 접근 대신 api/ REST API 호출
2	API Gateway 도입	인증/권한/레이트리밋 중앙 관리
3	미사용 API 비활성화	deprecation 헤더 추가 후 단계적 제거
4	API v2 전환	중복 정리 포함한 v2 설계

8. 전체 엔드포인트 도메인별 수

API 프로젝트

도메인	파일	수
인증	auth.php	8
사용자	users.php	25
테넌트	tenants.php	18
관리자	admin.php	22
공통	common.php	95+
HR	hr.php	85+
재무	finance.php	130+
영업	sales.php	85+
재고	inventory.php	65+
생산	production.php	35+
설계	design.php	55+
파일	files.php	15
게시판	boards.php	70+
문서	documents.php	5+
합계		~710+

MNG 프로젝트

그룹	수
사용자/역할/권한	30+
메뉴/글로벌메뉴	25+
게시판/필드	20+
카테고리/글로벌	15+
바로빌	60+
프로젝트 관리	25+
견적 공식	30+
품목 필드	25+
문서/템플릿	12+
계좌/자금일정	18+
기타	40+
합계	~300+

9. 참고 문서

docs/standards/api-rules.md - API 규칙
docs/architecture/system-overview.md - 시스템 아키텍처
docs/specs/database-schema.md - DB 스키마
api/routes/api/v1/*.php - API 라우트 파일
mng/routes/api.php - MNG API 라우트
react/src/lib/api/ - React API 클라이언트

10. 결론

api/와 mng/의 10개 도메인에서 컨트롤러 중복 발생 - 동일 DB를 각각 직접 접근하는 구조적 문제
React는 api/ 전체의 약 15%만 사용 - 나머지는 MNG 전용이거나 미구현 기능
인증 API에 signup/register 중복 존재 - 즉시 정리 가능
장기적으로 MNG → API 호출 전환이 이상적이나, 현재 아키텍처도 기능적으로 동작
Quick Wins(register 제거, debug-apikey 비활성화)부터 시작 권장

이 문서는 /sc:plan 스킬로 생성되었습니다.

18 KiB Raw Blame History