[Phase 1] API Specification

# API 명세서 (API Specification) > 프린트타운 SaaS 템플릿 빌더 시스템 API 문서 **작성일**: 2025년 12월 28일  **API 버전**: 1.0  **기본 URL**: `http://custemplate/adm/` --- ## ? 개요 ### API 설계 원칙 - **REST 기반**: 리소스 중심 설계 - **JSON 응답**: 표준 JSON 포맷 - **권한 검증**: GnuBoard 세션 기반 인증 ### 인증 방식 모든 API 요청은 GnuBoard 관리자 세션이 필요합니다. ```php // 권한 체크 예시 auth_check($auth[$sub_menu], 'r'); ``` --- ## ? API 엔드포인트 목록 ### 1. 템플릿 목록 조회 (JSON) #### `GET /adm/get_template_list_json.php` GnuBoard 관리자 페이지에서 사용하는 템플릿 목록을 JSON 형식으로 반환합니다. **요청 파라미터** | 파라미터 | 타입 | 필수 | 설명 | |---------|------|------|------| | `sca` | string | X | 1단계 카테고리 ID (예: `01`) | | `sfl` | string | X | 검색 필드 (`name`, `category`, `ca_id`) | | `stx` | string | X | 검색어 | | `sst` | string | X | 정렬 기준 (기본값: `id`) | | `sod` | string | X | 정렬 방향 (`asc`, `desc`) | | `page` | int | X | 페이지 번호 (기본값: 1) | **응답 예시** ```json {   "success": true,   "total_count": 125,   "page": 1,   "rows_per_page": 20,   "data": [     {       "id": 1,       "ca_id": "0101",       "category": "Admin/Dashboard",       "theme_name": "Stellar Admin",       "origin_path": "_template/category/Admin/Dashboard/stellar_admin",       "thumb_url": "http://custemplate/data/template/Admin/Dashboard/stellar_admin.jpg",       "status": "converted",       "created_at": "2025-12-15 10:30:00",       "updated_at": "2025-12-20 14:22:00"     },     {       "id": 2,       "ca_id": "0201",       "category": "Blog/Personal",       "theme_name": "Bloggy Theme",       "origin_path": "_template/category/Blog/Personal/bloggy",       "thumb_url": "",       "status": "new",       "created_at": "2025-12-16 09:15:00",       "updated_at": "2025-12-16 09:15:00"     }   ] } ``` **에러 응답** ```json {   "success": false,   "error": "권한이 없습니다.",   "code": "AUTH_FAILED" } ``` --- ### 2. 템플릿 목록 조회 (루트) #### `GET /get_template_list_json_root.php` 루트 경로에서 접근 가능한 공개 API (권한 검증 필요 시 수정) **응답 구조**: 상동 --- ### 3. 템플릿 스캔 #### `POST /adm/saas_template_scan.php` `_template` 폴더를 스캔하여 새로운 템플릿을 데이터베이스에 등록합니다. **요청** ```http POST /adm/saas_template_scan.php Content-Type: application/x-www-form-urlencoded action=scan ``` **응답 예시** ```json {   "success": true,   "message": "스캔 완료",   "stats": {     "scanned": 150,     "new": 25,     "duplicate": 125,     "errors": 0   },   "new_templates": [     {       "name": "New Portfolio Template",       "path": "_template/category/Portfolio/Creative/new_portfolio"     }   ] } ``` --- ### 4. 템플릿 정보 수정 #### `POST /adm/saas_template_form_update.php` 템플릿 정보를 업데이트합니다. **요청 파라미터** | 파라미터 | 타입 | 필수 | 설명 | |---------|------|------|------| | `w` | string | O | 모드 (`u`: 수정) | | `id` | int | O | 템플릿 ID | | `ca_id` | string | O | 카테고리 ID | | `name` | string | O | 템플릿 이름 | | `memo` | text | X | 관리자 메모 | **요청 예시** ```http POST /adm/saas_template_form_update.php Content-Type: application/x-www-form-urlencoded w=u&id=5&ca_id=0102&name=Updated+Template+Name&memo=New+memo ``` **응답** ```json {   "success": true,   "message": "수정되었습니다.",   "redirect": "./saas_template_list.php" } ``` --- ### 5. 테마 변환 #### `POST /adm/saas_theme_convert.php` HTML 템플릿을 GnuBoard 테마로 변환합니다. **요청 파라미터** | 파라미터 | 타입 | 필수 | 설명 | |---------|------|------|------| | `id` | int | O | 템플릿 ID | **응답 예시** ```json {   "success": true,   "message": "변환이 완료되었습니다.",   "theme_name": "theme_20251228_xyz789",   "theme_path": "/theme/theme_20251228_xyz789/" } ``` **에러 응답** ```json {   "success": false,   "error": "index.html 파일을 찾을 수 없습니다.",   "code": "FILE_NOT_FOUND" } ``` --- ## ? 인증 및 권한 ### 세션 기반 인증 모든 관리자 API는 GnuBoard 세션 검증을 수행합니다. ```php // _common.php 에서 자동 처리 include_once('./_common.php'); // 특정 메뉴 권한 체크 $sub_menu = '999100'; auth_check($auth[$sub_menu], 'r'); // 읽기 권한 auth_check($auth[$sub_menu], 'w'); // 쓰기 권한 ``` ### 권한 레벨 | 레벨 | 권한 코드 | 설명 | |------|----------|------| | 읽기 | `r` | 목록 조회, 상세 보기 | | 쓰기 | `w` | 등록, 수정, 삭제 | | 관리 | `rw` | 모든 작업 | --- ## ? 응답 형식 ### 성공 응답 구조 ```json {   "success": true,   "message": "작업이 완료되었습니다.",   "data": { /* 결과 데이터 */ } } ``` ### 에러 응답 구조 ```json {   "success": false,   "error": "에러 메시지",   "code": "ERROR_CODE",   "details": { /* 추가 상세 정보 */ } } ``` --- ## ⚠️ 에러 코드 | 코드 | HTTP 상태 | 설명 | 해결 방법 | |------|-----------|------|----------| | `AUTH_FAILED` | 403 | 권한 없음 | 관리자로 로그인 | | `NOT_FOUND` | 404 | 리소스 없음 | ID 확인 | | `INVALID_PARAM` | 400 | 잘못된 파라미터 | 요청 데이터 검증 | | `FILE_NOT_FOUND` | 404 | 파일 없음 | 경로 확인 | | `DB_ERROR` | 500 | 데이터베이스 오류 | 로그 확인 | | `SCAN_ERROR` | 500 | 스캔 실패 | 폴더 접근 권한 확인 | | `CONVERT_ERROR` | 500 | 변환 실패 | 템플릿 구조 확인 | --- ## ? API 테스트 예제 ### cURL 예제 #### 템플릿 목록 조회 ```bash curl -X GET "http://custemplate/adm/get_template_list_json.php?sca=01&page=1" \   -H "Cookie: PHPSESSID=your_session_id" \   -H "Accept: application/json" ``` #### 템플릿 스캔 ```bash curl -X POST "http://custemplate/adm/saas_template_scan.php" \   -H "Cookie: PHPSESSID=your_session_id" \   -d "action=scan" ``` ### JavaScript (Fetch API) 예제 ```javascript // 템플릿 목록 조회 async function getTemplates(category = '', page = 1) {   const response = await fetch(     `/adm/get_template_list_json.php?sca=${category}&page=${page}`,     {       method: 'GET',       credentials: 'include', // 세션 쿠키 포함       headers: {         'Accept': 'application/json'       }     }   );     const data = await response.json();   return data; } // 사용 예시 getTemplates('01', 1).then(data => {   console.log('총 템플릿:', data.total_count);   console.log('템플릿 목록:', data.data); }); ``` ### PHP 예제 ```php <?php // 템플릿 목록 조회 (내부 사용) $sql = " SELECT * FROM {$g5['saas_template_table']}         WHERE ca_id LIKE '01%'         ORDER BY id DESC         LIMIT 0, 20 "; $result = sql_query($sql); while ($row = sql_fetch_array($result)) {     echo $row['name'] . "\n"; } ?> ``` --- ## ? 데이터베이스 직접 접근 ### 템플릿 정보 조회 ```sql -- 모든 템플릿 조회 SELECT * FROM g5_saas_template ORDER BY id DESC; -- 특정 카테고리 템플릿 조회 SELECT * FROM g5_saas_template WHERE LEFT(ca_id, 2) = '01' AND status = 'converted'; -- 카테고리 정보 조인 SELECT t.*, c.ca_name FROM g5_saas_template t LEFT JOIN g5_shop_category c ON t.ca_id = c.ca_id WHERE t.status = 'new'; ``` ### 템플릿 등록 ```sql INSERT INTO g5_saas_template (ca_id, category, name, origin_path, status, created_at, updated_at) VALUES ('0101', 'Admin/Dashboard', 'New Template',  '_template/category/Admin/Dashboard/new_template',  'new', NOW(), NOW()); ``` --- ## ? 참고 사항 ### 보안 고려사항 - 모든 입력값은 `sql_escape_string()` 처리 - XSS 방지를 위한 출력 시 `htmlspecialchars()` 적용 - CSRF 토큰 검증 (향후 구현 권장) ### 성능 최적화 - 페이징 필수 (기본 20개) - 인덱스 활용 (`ca_id`, `status`) - 썸네일 이미지 최적화 (JPG, 500px 이하) ### 향후 확장 계획 - [ ] RESTful API v2 설계 - [ ] OAuth 2.0 인증 - [ ] Rate Limiting - [ ] API 문서 자동 생성 (Swagger/OpenAPI) - [ ] Webhook 지원 --- ## ? 관련 문서 - [Information Architecture (IA)](file:///C:/Users/LG/.gemini/antigravity/brain/01040e19-c007-4f08-bbdd-d02539ac07b8/information_architecture.md) - [프로젝트 완료 보고서](file:///C:/Users/LG/.gemini/antigravity/brain/01040e19-c007-4f08-bbdd-d02539ac07b8/project_completion_report.md)