SKMR_현업 주도 SOP체계 구축 지원 및 자문

기능정의서

1. 개요

본 문서는 표준작업지시서(SOP) 생성·관리 시스템이 제공하는 단위기능을 식별하고, 각 기능의 입력·출력·제약 조건을 정의함을 목적으로 기술한 문서이다.

1.1. 작성 목적

시스템이 제공하는 전체 단위기능을 누락 없이 식별한다.
기능별 입력·출력·제약 조건을 명시하여 설계 및 개발의 기준을 제시한다.
기능 ID를 부여하여 설계서·테스트케이스·요구사항 간 추적성을 확보한다.
고객 승인 대상 기능과 추가 협의가 필요한 기능을 구분하여 관리한다.

1.2. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문이 구축하는 SOP 생성·관리 시스템 전체에 적용된다. 프로세스 체계도 관리, SOP 관리, SOP 에이전트, 접근제어, 사용량 관리, 데이터 저장 및 비기능 요건을 포함한다. 타 시스템과의 연계 상세 규격은 인터페이스 정의서에서 별도로 정의한다.

1.3. 기능 분류 체계

기능 ID는 FN-{영역코드}-{일련번호} 형식으로 부여하며, 영역코드는 다음과 같다.

영역코드	영역명	정의
PRC	프로세스 체계도	업무 분류 체계의 조회·편집·이력 관리
SOP	SOP 관리	SOP의 열람·편집·등록·버전 관리
AGT	SOP 에이전트	대화를 통한 SOP 생성 및 수정
AUT	접근제어 및 권한	인증, 인가, 가시 범위 제어
USG	사용량 관리	추론 사용량 계량 및 한도 제어
DAT	데이터 및 저장	영속화, 동시성 제어, 감사 기록
COM	비기능	보안·가용성·성능·사용성 요건

기능 유형은 화면 / 조회 / 등록 / 수정 / 삭제 / 처리 / 출력 / 비기능으로 구분한다. 승인 구분은 고객 승인 완료를 o, 추가 협의가 필요한 사항을 △로 표기한다.

2. 기능 구성 요약

영역	기능 수	승인 완료	협의 필요	주요 기능
프로세스 체계도	8	8	-	트리 조회, 노드 등록·이동·삭제, Lv4–SOP 연결, 개정 이력 및 롤백
SOP 관리	11	11	-	목록 조회, 프로세스 VIEW, 편집 락, 버전 저장, 등록, 다운로드
SOP 에이전트	7	7	-	지시·문서 기반 생성, 실시간 스트리밍, 근거 추적, 대화 복원
접근제어 및 권한	5	2	3	사번 로그인, 가시 범위 부여, 범위 기반 접근 필터, 관리자 기능
사용량 관리	5	5	-	호출별 계량, 사용자별 조회, 쿼터 설정, 한도 검사·차단
데이터 및 저장	5	4	1	영속 저장, 자산 저장, 편집 락, 버전 관리, 감사 기록
비기능	4	3	1	보안, 가용성, 성능, 사용성
합계	45	40	5	-

3. 프로세스 체계도

3.1. 체계도 조회

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-PRC-001	체계도 트리 조회	화면	가시 범위 내 Lv1부터 Lv4까지의 계층을 접고 펴며 탐색한다. 노드별 SOP 유무와 상태를 함께 표시한다.	사번(세션)	체계도 트리, 노드별 SOP 상태	가시 범위로 필터링한 노드만 반환한다. 범위 밖 노드는 응답에 포함하지 않는다.	process_node, user_scope, sop	o
FN-PRC-002	체계도 검색	조회	노드명·코드·주관부서·SOP명으로 검색하고 해당 노드로 이동한다.	검색어	일치 노드 목록	검색 결과는 가시 범위로 필터링한다.	process_node, sop	o

3.2. 체계도 편집

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-PRC-003	노드 등록	등록	Lv1부터 Lv4까지의 노드를 신규 등록한다. 코드는 계층을 반영하여 부여한다.	부모노드, 레벨, 명칭, 부서	생성 노드	부모 레벨의 다음 단계만 허용한다. 코드 유일성을 검증한다.	process_node	o
FN-PRC-004	노드 수정·이동	수정	노드명을 변경하고, 부모를 변경하여 하위 트리를 함께 이동한다.	노드ID, 변경값	수정 결과	이동 시 하위 노드의 경로와 코드를 재계산한다.	process_node	o
FN-PRC-005	노드 삭제	삭제	노드를 하위 노드와 함께 삭제한다.	노드ID	삭제 결과	SOP가 매핑된 Lv4 노드는 SOP 연결을 먼저 해제해야 삭제할 수 있다.	process_node, sop	o
FN-PRC-006	Lv4–SOP 연결·해제	처리	Lv4 노드에 SOP를 연결하거나 해제한다.	Lv4 노드ID, SOP ID	매핑 결과	Lv4 노드와 SOP는 1 대 0 또는 1 관계를 유지한다. 이미 SOP가 연결된 Lv4 노드에는 중복 연결할 수 없다.	process_node, sop	o

3.3. 체계도 이력

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-PRC-007	체계도 개정 이력 조회	조회	체계 개편 스냅샷과 노드의 신설·이동·폐지 이력을 조회한다.	기간	개정 이력	-	process_node_history	o
FN-PRC-008	체계도 개정 롤백	처리	프로세스 체계도 전체를 특정 시점 상태로 복원한다.	기간	수정 결과	-	process_node_history	o

4. SOP 관리

4.1. SOP 목록 및 열람

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-SOP-001	SOP 목록 조회	조회	SOP명·작성자·작성일·상태를 목록으로 조회한다. SOP는 전 구성원이 공유하며 표시는 가시 범위로 필터링한다.	사번(세션), 필터	SOP 목록	체계도 범위 필터를 적용한다.	sop, user_scope	o
FN-SOP-002	SOP 프로세스 VIEW	화면	Task 단위 흐름도로 SOP를 시각화하여 조회한다.	SOP ID	SOP 상세, 원본	본 화면에서는 편집할 수 없으며 수정은 에이전트 경로를 통한다. 편집 락 상태와 무관하게 열람할 수 있다.	sop	o
FN-SOP-003	표준 양식 다운로드	출력	SOP를 표준 양식(xlsm) 파일로 내려받는다.	SOP ID	xlsm 파일	저장본을 반환하지 않고 현재 스키마로부터 매번 생성한다.	sop, 자산 저장소	o

4.2. SOP 편집

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-SOP-004	Lv4–SOP 연결·해제	처리	SOP 편집 화면에서 Lv4 노드와의 연결을 설정하거나 해제한다.	Lv4 노드ID, SOP ID	매핑 결과	Lv4 노드와 SOP는 1 대 0 또는 1 관계를 유지한다.	process_node, sop	o
FN-SOP-005	SOP 편집 화면	화면	SOP를 수정하는 화면을 제공한다.	SOP ID	SOP 상세, 원본	편집 락이 비어 있을 때만 접근할 수 있다.	sop, sop_lock	o
FN-SOP-006	원본 대조 및 근거 강조	조회	활동을 선택하면 원본 문서의 근거 위치를 강조한다. 복수 파일로 구성된 SOP는 해당 파일로 자동 전환한다.	활동 선택	근거 강조 표시	페이지 이미지 좌표 또는 블록 식별자를 기준으로 한다. 편집 락이 비어 있을 때 접근할 수 있다.	sop, 자산 저장소, sop_lock	o
FN-SOP-007	편집 락 획득·해제	처리	편집 시작 시 락을 획득하고, 저장·취소·이탈 시 해제한다.	SOP ID, 사번	락 상태	락이 비어 있을 때만 획득한다. 타인이 편집 중이면 거절하고 보유자를 안내한다.	sop_lock	o
FN-SOP-008	SOP 저장	수정	편집 내용을 저장하고 갱신 시각과 버전을 반영한다.	SOP ID, 스키마, 기준버전	저장 결과	기준 버전을 대조하여 불일치 시 충돌을 통지한다.	sop, sop_version	o
FN-SOP-009	SOP 등록	등록	에이전트가 작성한 초안을 등록하여 조직 자산으로 전환한다. 등록 전은 작성중, 등록 후는 완료 상태로 관리한다.	스키마, 원본, 매핑 Lv4	등록 SOP	작성자는 등록 시점의 로그인 사용자로 기록하며 원본 문서의 작성자 값은 사용하지 않는다. 최초 등록자는 변경되지 않는다.	sop, process_node	o
FN-SOP-010	SOP 삭제	삭제	SOP와 함께 보관된 원본을 삭제한다.	SOP ID	삭제 결과	작성자 본인 또는 관리자만 수행할 수 있다.	sop, 자산 저장소	o
FN-SOP-011	SOP 버전 이력 및 복원	조회	저장할 때마다 버전을 기록하고, 이전 버전을 열람하거나 복원한다.	SOP ID	버전 목록, 복원 결과	-	sop_version	o

5. SOP 에이전트

5.1. SOP 생성

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-AGT-001	지시·문서 기반 SOP 생성	처리	사용자 지시 또는 첨부 문서를 근거로 SOP 초안을 생성한다.	지시문, 첨부파일	SOP 스키마 초안	도구 사용 루프로 수행한다. 호출별 사용량을 계량하여 사용량 관리와 연동한다.	sop, usage_log	o
FN-AGT-002	실시간 진행 표시	화면	도구 사용 및 생성 과정을 실시간으로 표시한다.	-	진행 이벤트	생성은 서버에서 수행하며, 화면이 끊겨도 생성은 계속되고 재접속 시 진행 상황을 이어서 표시한다.	-	o

5.2. 원본 관리

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-AGT-003	원본 다중 첨부 및 삭제	등록	복수 파일을 동시에 또는 끌어놓기로 첨부하고, 개별 삭제하거나 하나의 SOP로 통합한다.	문서 파일	첨부 목록	허용 확장자는 pdf, doc, docx, ppt, pptx, xls, xlsx, xlsm으로 한정한다. 원본은 대화 단위로 보존한다.	자산 저장소	o
FN-AGT-004	근거 추적 매핑	처리	각 활동에 대응하는 원본 블록과 좌표의 매핑을 생성한다.	원본, 스키마	근거 매핑	열람 화면의 근거 강조 기능에 사용한다.	sop	o

5.3. 대화 관리

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-AGT-005	대화 이력 조회 및 복원	조회	사번별로 대화를 보관하고, 재개 시 SOP와 원본을 함께 복원한다.	사번(세션)	대화 목록, 복원 결과	보관 한도를 초과하면 오래된 대화부터 목록에서 제외한다.	conversation	o
FN-AGT-006	기존 SOP 불러오기	처리	등록된 SOP를 대화로 불러와 수정한 뒤 다시 등록한다.	SOP ID	편집 세션	불러올 때 편집 락을 획득한다.	sop, sop_lock	o
FN-AGT-007	유사 SOP 검색	조회	체계도 위치와 내용을 근거로 유사하거나 중복된 SOP를 탐색한다.	질의	유사 SOP 목록	-	sop	o

6. 접근제어 및 권한

6.1. 인증

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-AUT-001	사번 로그인 및 세션	화면	사번과 비밀번호로 로그인하고 서명 쿠키 기반 세션을 발급한다.	사번, 비밀번호	세션 쿠키	전 화면에 로그인을 요구한다. 세션 유효기간은 1일로 한다. 로그인 실패가 누적되면 일정 시간 차단한다.	app_user	o
FN-AUT-002	비밀번호 변경	수정	사용자가 비밀번호를 변경한다.	현재 비밀번호, 새 비밀번호	변경 결과	비밀번호는 솔트를 적용한 단방향 해시로 저장한다.	app_user	o

6.2. 인가

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-AUT-003	체계도 가시 범위 부여	등록	사용자별로 조회 가능한 체계도 노드 집합을 부여한다.	사번, 노드ID 목록	범위 설정 결과	Lv1부터 Lv3까지 지정하며 하위 노드는 상속한다. 관리자만 설정할 수 있다.	user_scope	△
FN-AUT-004	범위 기반 접근 필터	처리	목록·검색·열람 및 직접 주소 접근을 가시 범위로 제한한다.	요청, 사번	허용 또는 차단	서버가 매 요청마다 검사한다. 화면 은닉에 의존하지 않는다.	user_scope	△
FN-AUT-005	관리자 기능	처리	전 범위 열람, 타인 SOP 삭제, 편집 락 강제 해제, 가시 범위 부여를 수행한다.	관리자 요청	실행 결과	역할로 판정한다. 권한 승격은 필요한 최소 범위로 한정한다.	app_user	△

7. 사용량 관리

7.1. 사용량 계량

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-USG-001	호출별 사용량 기록	처리	추론 호출마다 사용자·모델·토큰·비용을 기록한다.	호출 결과	사용량 적재 결과	세션 정보로 사용자를 귀속하여 계량한다.	usage_log, user_usage	o
FN-USG-002	사용자별 사용량 조회	조회	사용자와 기간별 토큰 및 비용 집계를 조회한다.	사번, 기간	사용량 집계	일반 사용자는 본인 사용량만, 관리자는 전체를 조회한다.	user_usage	o

7.2. 한도 제어

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-USG-003	사용자 쿼터 설정	등록	사용자 또는 역할별 월 한도와 분당 요청 수를 설정한다.	사번, 한도값	쿼터 설정 결과	관리자만 설정한다. 미설정 시 역할 기본값을 상속한다.	user_quota	o
FN-USG-004	호출 전 한도 검사	처리	호출 전에 누적 사용량을 한도와 비교하여 경고하거나 차단한다.	사번, 요청	허용 또는 차단	검사와 증가를 하나의 트랜잭션으로 처리하여 경합을 방지한다. 소프트 한도는 경고하고 하드 한도는 차단한다.	user_quota, user_usage	o
FN-USG-005	분당 요청 수 제한	처리	사용자별 분당 요청 수를 제한한다.	사번	허용 또는 거절	동시 실행 수 제한은 본 범위에서 제외한다.	user_quota	o

8. 데이터 및 저장

8.1. 저장소

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-DAT-001	관계형 데이터 저장	처리	체계도·SOP·락·권한·사용량을 관계형 데이터베이스에 저장한다.	엔티티	영속 결과	저장소 경계 뒤에서 처리하여 엔진 교체 가능성을 확보한다.	전 테이블	△
FN-DAT-002	자산 저장	처리	원본 문서·이미지·산출물 등 대용량 자산을 자산 저장소에 보관하고 테이블에는 식별자만 기록한다.	파일	자산 식별자	자산 저장소 경계 뒤에서 처리한다.	sop	o

8.2. 동시성 제어

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-DAT-003	편집 락 관리	처리	락 보유자와 유효기간을 관리하고, 연장·만료 자동 해제·관리자 강제 해제를 수행한다.	락 요청	락 상태	동시성은 데이터베이스 수준에서 보장한다.	sop_lock	o
FN-DAT-004	버전 관리	처리	저장 시 기준 버전을 대조하여 불일치하면 충돌로 처리한다.	SOP, 기준버전	저장 결과 또는 충돌	-	sop, sop_version	o

8.3. 감사

기능ID	단위기능	유형	기능 설명	입력	출력	제약 조건	관련 테이블	승인
FN-DAT-005	감사 로그 기록	처리	등록·수정·삭제·락·권한 변경을 수행자와 시각과 함께 기록한다.	이벤트	감사 로그 적재	정의되지 않은 행위 유형은 기록하지 않는다.	audit_log	o

9. 비기능 요건

기능ID	항목	유형	요건 내용	제약 조건	승인
FN-COM-001	보안	비기능	전송 구간을 암호화하고, 서명 쿠키로 세션을 관리하며, 권한과 가시 범위를 서버에서 강제한다.	화면 은닉에 의존하지 않는다. 비밀 정보는 소스에 포함하지 않고 분리하여 주입한다.	o
FN-COM-002	가용성	비기능	서버를 재시작하여도 세션과 데이터를 유지한다.	서명 키와 데이터베이스를 영속화한다. 무중단 배포는 후속 과제로 한다.	△
FN-COM-003	성능	비기능	대화형 단건 처리를 기준으로 하며, 문서 변환 시 발생하는 순간 부하를 수용한다.	자원 산정 근거를 아키텍처 정의서에 반영한다.	o
FN-COM-004	사용성	비기능	화면별 사용 가이드를 제공하고, 원본과 SOP의 근거를 대조하여 표시한다.	-	o

10. 작성 가이드

기능정의서는 요구사항 정의서를 입력으로 하여 단위기능을 식별하고, 각 기능의 입출력과 제약을 확정하여 설계 단계의 기준을 제시한다. 기능 ID는 설계서 및 테스트케이스와 연결하여 추적성을 확보한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 작성 목적을 개략적으로 기술한다.	Y
적용 범위	- 기능 식별의 대상 범위와 제외 범위를 기술한다.	Y
기능 분류 체계	- 기능 ID 부여 규칙과 영역코드를 정의한다. - 기능 유형과 승인 구분의 표기법을 정의한다.	Y
기능 구성 요약	- 영역별 기능 수와 승인 현황을 요약한다.	Y
단위기능 정의	- 기능ID, 단위기능명, 유형, 기능 설명, 입력, 출력, 제약 조건, 관련 테이블, 승인 구분을 기술한다. - 기능 설명은 수행 주체와 동작을 명확히 기술한다. - 제약 조건에는 권한 범위, 상태 전이 조건, 데이터 무결성 규칙을 포함한다.	Y
비기능 요건	- 보안·가용성·성능·사용성 요건을 기술한다. - 정량 목표가 필요한 항목은 측정 기준을 함께 기술한다.	Y
승인 구분	- 고객 승인이 완료된 기능과 추가 협의가 필요한 기능을 구분하여 표기한다. - 협의 필요 항목은 협의 대상과 일정을 비고에 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

화면 목록 및 메뉴 구조

1. 개요

본 문서는 시스템이 제공하는 화면의 목록과 메뉴 계층, 권한별 노출 조건 및 화면 간 전환 관계를 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 사용자에게 제공되는 전체 화면에 적용된다. 화면별 레이아웃, 항목 배치, 이벤트 상세는 화면 설계서에서 정의하며, 본 문서는 그 입력이 된다.

1.2. 식별 체계

화면 ID는 SC-{영역코드}-{일련번호} 형식으로 부여한다. 영역코드는 기능정의서의 구분을 따른다. 본 문서에서 부여한 화면 ID는 후속 화면 설계서와 테스트 시나리오가 그대로 승계한다.

구분	정의	표기
주화면	메뉴에서 직접 진입하는 화면	메뉴 목록에 포함한다.
하위 화면	주화면 내부에서 전환되는 화면 또는 패널	주화면에 종속하여 번호를 부여한다.
공통 영역	전 화면에 공통으로 표시되는 영역	메뉴에 포함하지 않는다.

2. 메뉴 구조

2.1. 메뉴 계층도

SOP Hub
+-- 마이페이지                    내 작업 현황 요약
+-- 프로세스 체계 관리             체계도 트리 · 노드 상세 · 검색
|     + (사이드바) 체계도 현황      선택 노드의 하위 요약
+-- 내 SOP                        내가 작성한 SOP 목록
+-- SOP 조회                      전체 SOP 목록 · 상세 열람
|     + SOP 프로세스 VIEW          흐름도 열람
|     + 원본 대조                  근거 위치 강조
|     + 버전 이력                  버전 목록 · 복원
+-- SOP Studio                    에이전트 대화로 SOP 생성 · 편집
|     + 대화 패널                  지시 입력 · 진행 표시
|     + 캔버스                     산출물 편집
|     + 원본 패널                  첨부 문서 대조
|     + (사이드바) 대화 목록        대화 전환 · 신규 · 삭제
+-- SOP 일괄 생성                  일괄 변환 요청 조회
+-- 내 요청함                      내가 올린 요청 · 진행 상태
+-- SOP 생성 가이드                사용 안내
+-- FAQ                           공지 · 자주 묻는 질문
+-- 1:1 문의                      문의 등록 · 답변 확인
+-- 사용자 테스트 설문             설문 응답
+-- PMO 검토 의견                  검토 의견 일괄 처리            [관리자]
+-- 관리                          [관리자]
      + 사용자 · 조직
      + 권한 범위
      + 관리자 지정
      + 사용 한도
      + 편집 락 현황
      + 체계도 개정 이력
      + 대화 관리
      + 감사 로그

2.2. 메뉴 목록

순서	메뉴명	화면 ID	기능 요약	노출 조건	관련 기능ID
1	마이페이지	SC-COM-001	작성 중 SOP, 요청 진행 상태, 사용량을 요약하여 제시한다.	로그인	FN-USG-002
2	프로세스 체계 관리	SC-PRC-001	가시 범위 내 체계도를 탐색하고 노드별 SOP 유무를 확인한다.	상시	FN-PRC-001, FN-PRC-002
3	내 SOP	SC-SOP-001	본인이 작성한 SOP를 상태별로 조회한다.	로그인	FN-SOP-001
4	SOP 조회	SC-SOP-002	가시 범위 내 전체 SOP를 조회하고 상세를 열람한다.	로그인	FN-SOP-001, FN-SOP-002
5	SOP Studio	SC-AGT-001	에이전트와 대화하여 SOP를 생성하고 편집한다.	상시	FN-AGT-001~007
6	SOP 일괄 생성	SC-AGT-010	일괄 변환 요청과 결과를 조회한다.	상시	-
7	내 요청함	SC-BRD-001	본인이 등록한 요청과 진행 상태를 확인한다.	로그인	-
8	SOP 생성 가이드	SC-COM-002	작성 절차와 사용 방법을 안내한다.	로그인	FN-COM-004
9	FAQ	SC-BRD-002	공지와 자주 묻는 질문을 조회한다.	로그인	-
10	1:1 문의	SC-BRD-003	문의를 등록하고 답변을 확인한다.	로그인	-
11	사용자 테스트 설문	SC-COM-003	설문에 응답한다.	설문 기간	-
12	PMO 검토 의견	SC-ADM-010	검토 의견을 일괄 반영하고 결과를 내려받는다.	관리자	-
13	관리	SC-ADM-001	계정, 권한, 운영 현황을 관리한다.	관리자	FN-AUT-003~005

3. 화면 목록

3.1. 주화면 하위 구성

화면 ID	화면명	상위	유형	기능 요약	관련 기능ID
SC-PRC-002	노드 상세	SC-PRC-001	패널	선택 노드의 속성과 연결 SOP를 표시한다.	FN-PRC-001
SC-PRC-003	노드 등록·수정	SC-PRC-001	모달	노드를 등록하거나 명칭·상위를 변경한다.	FN-PRC-003, FN-PRC-004
SC-SOP-003	SOP 프로세스 VIEW	SC-SOP-002	화면	작업 단위 흐름도로 SOP를 열람한다.	FN-SOP-002
SC-SOP-004	원본 대조	SC-SOP-003	패널	활동 선택 시 원본의 근거 위치를 강조한다.	FN-SOP-006
SC-SOP-005	버전 이력	SC-SOP-003	패널	버전 목록을 조회하고 특정 버전으로 복원한다.	FN-SOP-011
SC-SOP-006	SOP 등록	SC-AGT-001	모달	초안을 체계도 노드에 연결하여 등록한다.	FN-SOP-009
SC-AGT-002	대화 패널	SC-AGT-001	패널	지시를 입력하고 진행 상황을 확인한다.	FN-AGT-001, FN-AGT-002
SC-AGT-003	캔버스	SC-AGT-001	패널	생성된 산출물을 확인하고 직접 편집한다.	FN-AGT-001
SC-AGT-004	표 보기	SC-AGT-003	전환	작업 단위와 활동을 표 형태로 편집한다.	FN-AGT-001
SC-AGT-005	원본 패널	SC-AGT-001	패널	첨부 문서를 페이지 단위로 열람한다.	FN-AGT-003, FN-AGT-004
SC-ADM-002	사용자·조직	SC-ADM-001	탭	계정과 소속을 조회한다.	FN-AUT-005
SC-ADM-003	권한 범위	SC-ADM-001	탭	가시 범위를 부여하고 회수한다.	FN-AUT-003
SC-ADM-004	관리자 지정	SC-ADM-001	탭	관리자를 승격하고 회수한다.	FN-AUT-005
SC-ADM-005	사용 한도	SC-ADM-001	탭	사용자별 월 한도를 설정한다.	FN-USG-003
SC-ADM-006	편집 락 현황	SC-ADM-001	탭	락 보유 현황을 조회하고 강제 해제한다.	FN-DAT-003
SC-ADM-007	체계도 개정 이력	SC-ADM-001	탭	개정 이력을 조회하고 되돌린다.	FN-PRC-007, FN-PRC-008
SC-ADM-008	대화 관리	SC-ADM-001	탭	전체 대화를 조회하고 삭제한다.	FN-AUT-005
SC-ADM-009	감사 로그	SC-ADM-001	탭	기간과 대상으로 감사 기록을 조회한다.	FN-DAT-005

3.2. 공통 영역

영역	위치	구성
메뉴	좌측 상단	권한과 로그인 상태에 따라 노출되는 메뉴 항목
체계도 현황	좌측 중단	프로세스 체계 관리 화면에서만 표시한다. 선택 노드의 하위 구성을 요약한다.
대화 목록	좌측 중단	SOP Studio 화면에서만 표시한다. 대화 전환, 신규 생성, 삭제를 제공한다.
계정	좌측 하단	사용자 표기, 비밀번호 변경, 로그아웃
로그인	전체 덮음	미인증 상태에서 전 화면을 덮는다. 화면 숨김이 아니라 서버가 매 요청을 차단한다.

4. 화면 전환 흐름

4.1. SOP 신규 작성

SOP Studio --첨부·지시--> 대화 패널 --생성 진행--> 캔버스
     |                                                  |
     |                                          +-------+-------+
     |                                          v               v
     |                                      표 보기          원본 패널
     |                                          |
     +------------------------ SOP 등록 <-------+
                                   |
                                   v
                        프로세스 체계 관리(노드 연결 확인)

4.2. 기존 SOP 수정

SOP 조회 --선택--> SOP 프로세스 VIEW --수정--> SOP Studio(불러오기 · 락 획득)
                         |                            |
                         +-> 원본 대조                 v
                         +-> 버전 이력             캔버스 편집 --저장--> 버전 생성

SOP 프로세스 VIEW에서는 편집할 수 없으며 수정은 SOP Studio 경로로만 수행한다. 불러오기 시점에 편집 락을 획득하며, 타인이 보유 중이면 보유자를 안내하고 진입하지 않는다.

4.3. 체계도 기반 진입

프로세스 체계 관리에서 단위업무 노드를 선택하면 연결된 SOP의 열람 화면으로 이동하고, 연결된 SOP가 없으면 해당 노드를 대상으로 SOP Studio를 시작할 수 있다.

5. 권한별 메뉴 노출

메뉴	미인증	일반 사용자	관리자	비고
프로세스 체계 관리	표시	표시	표시	표시 내용은 가시 범위로 제한한다.
SOP Studio	표시	표시	표시	-
SOP 일괄 생성	표시	표시	표시	-
마이페이지 · 내 SOP · SOP 조회	미표시	표시	표시	-
내 요청함 · FAQ · 1:1 문의 · 가이드	미표시	표시	표시	-
사용자 테스트 설문	미표시	조건부	조건부	설문 기간이고 미응답인 경우에만 표시한다.
PMO 검토 의견 · 관리	미표시	미표시	표시	-

메뉴 미표시는 보안 통제가 아니다. 메뉴를 감추는 것과 별개로 서버가 요청마다 권한을 검증한다. 주소를 직접 입력하여 접근하더라도 권한이 없으면 자원의 존재를 노출하지 않는 응답으로 차단한다.

6. 화면 공통 규칙

항목	규칙
상태 표기	SOP 상태는 데이터베이스 정의서의 코드 정의를 따른다. 상태를 추가하거나 삭제하는 경우 데이터베이스 제약과 화면 표시 규칙을 함께 변경한다.
가시 범위	목록, 검색, 상세 조회에 동일한 범위 기준을 적용한다. 범위 밖 자원은 목록에 포함하지 않는다.
편집 가능 여부	편집 락을 보유한 경우에만 편집 조작을 활성화한다. 타인이 보유 중이면 보유자와 함께 안내한다.
진행 표시	수 분이 소요되는 처리는 단계별 진행을 표시한다. 화면을 벗어나거나 새로 고침하여도 수행은 계속되며 재진입 시 진행 상황을 이어서 표시한다.
오류 표시	처리 실패 시 사유와 다음 조치를 함께 제시한다. 내부 오류 정보를 노출하지 않는다.
표기	화면과 산출물에 이모지를 사용하지 않는다. 아이콘은 벡터 이미지 또는 텍스트로 표기한다.

7. 작성 가이드

화면 목록 및 메뉴 구조는 기능정의서를 입력으로 하여 화면 단위를 식별하고 메뉴 체계를 확정한다. 화면의 레이아웃이 확정되기 전 단계에서 작성하며, 확정 후 화면 설계서가 본 문서의 화면 ID를 승계한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적과 적용 범위를 기술한다. - 화면 ID 부여 규칙과 주화면·하위 화면·공통 영역의 구분을 정의한다.	Y
메뉴 계층도	- 메뉴 전체를 계층 구조로 기술한다. - 메뉴에 포함되지 않는 보조 영역은 구분하여 표기한다.	Y
메뉴 목록	- 메뉴명, 화면 ID, 기능 요약, 노출 조건, 관련 기능ID를 기술한다.	Y
화면 목록	- 주화면의 하위 화면과 패널을 식별하여 기술한다. - 각 화면의 유형(화면·패널·모달·탭)을 구분한다.	Y
화면 전환 흐름	- 주요 업무 시나리오별 화면 전환을 도식으로 기술한다. - 전환 시 선행 조건이 있으면 함께 기술한다.	Y
권한별 노출	- 권한 구분별 메뉴 노출 여부를 기술한다. - 메뉴 은닉이 보안 통제가 아님을 명시한다.	Y
화면 공통 규칙	- 상태 표기, 범위 적용, 편집 가능 조건, 진행 및 오류 표시 규칙을 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

애플리케이션 아키텍처 정의서

1. 개요

본 문서는 애플리케이션의 계층 구성, 모듈 구조, 주요 처리 흐름 및 품질 속성 대응 방안을 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문의 애플리케이션 내부 구조 전체에 적용된다. 인프라 구성은 클라우드 아키텍처 정의서에서, 구현 수준의 규칙은 개발표준 정의서에서 정의한다.

1.2. 설계 목표

목표	내용
경계의 명확성	계층 간 책임을 분리하고 호출 방향을 단일화하여 변경 영향 범위를 제한한다.
저장소 교체 가능성	저장 기술에 대한 의존을 한 계층에 가두어 엔진 교체 시 상위 계층을 변경하지 않는다.
권한 우회 차단	권한 확인을 거치지 않고 데이터에 접근하는 경로가 존재하지 않도록 구조로 보장한다.
장시간 처리 분리	문서 변환 등 수 분이 소요되는 처리를 요청 수명과 분리한다.
규칙의 기계적 보장	구조 규칙을 문서가 아니라 검사 도구로 강제한다.

2. 아키텍처 개요

2.1. 아키텍처 스타일

계층형 아키텍처를 채택한다. 상위 계층이 하위 계층을 호출하며 역방향 호출을 허용하지 않는다. 단일 배포 단위로 구성하고, 외부 에이전트 프레임워크를 사용하지 않는다.

2.2. 전체 구성

+---------------------------------------------+
| 프런트엔드 (브라우저)                         |
|   화면 모듈 · 공통 호출 모듈 · 상태           |
+-------------------+-------------------------+
                    | HTTP / 이벤트 스트림
+-------------------v-------------------------+
| 라우트 계층  (api)                           |
|   권한 확인 · 서비스 호출 · 기록 · 응답 변환   |
+-------------------+-------------------------+
                    |
+-------------------v-------------------------+
| 업무 로직 계층  (services)                   |
|   업무 규칙 · 처리 순서 · 에이전트 오케스트레이션|
+------+---------------------------+----------+
       |                           |
+------v----------+    +-----------v----------+
| 저장소 계층      |    | 공유 코어             |
|  (storage)      |    |  변환 파이프라인      |
|  질의 · 영속화   |    |  인증 · 설정 · 추론   |
+------+----------+    +-----------+----------+
       |                           |
+------v---------------------------v----------+
| 데이터베이스 · 자산 저장소 · LLM 서비스        |
+---------------------------------------------+

공유 코어는 애플리케이션 계층을 참조하지 않는다. 동일한 변환 파이프라인을 웹 요청과 일괄 처리가 함께 사용하며, 설정은 공유 코어의 단일 모듈에서 관리한다.

3. 논리 아키텍처

3.1. 계층별 책임

계층	책임	금지 사항
라우트 계층	- 권한 및 가시 범위 확인 - 업무 로직 계층 호출 - 감사 대상 행위 기록 - 응답 포장 및 예외의 상태코드 변환	- 계산, 집계, 판단 - 복수 도메인에 걸친 처리 순서 - 저장소 계층 직접 호출 - 질의문 작성
업무 로직 계층	- 업무 규칙 수행 - 처리 순서와 부수효과 관리 - 에이전트 턴 오케스트레이션	- 질의문 작성 - HTTP 개념 참조
저장소 계층	- 질의 및 영속화 - 저장 규칙 적용	- HTTP 상태코드 사용 - 업무 판단
공유 코어	- 문서 변환 파이프라인 - 인증 및 계정 - 설정과 추론 클라이언트 구성	- 애플리케이션 계층 참조

3.2. 호출 규칙

호출은 상위에서 하위 방향으로만 수행한다.
라우트 계층은 저장소 계층을 직접 호출하지 않으며, 계층을 건너뛰지 않는다.
공유 코어는 애플리케이션 계층을 참조하지 않는다.
위 세 규칙은 정적 분석 도구의 계약으로 검사하며 예외를 두지 않는다.

업무가 없는 전달 전용 서비스 함수가 생기는 것은 본 구조가 감수하는 비용이다. 권한 확인을 거치지 않는 데이터 접근 경로를 원천적으로 차단하는 것이 그보다 중요하다.

3.3. 기록 처리

감사 대상 행위에서 무엇을 남길지는 라우트 계층이 결정하고, 호출 경로는 업무 로직 계층을 경유한다. 행위별로 남길 속성이 다르므로 업무 함수에 기록 책임을 넣으면 호출자마다 수행자와 사유를 인자로 전달해야 한다.

4. 모듈 구성

4.1. 애플리케이션 모듈

계층	모듈	담당 영역
라우트	process · sop · agent · files · my · usage · board · survey · admin · pmo	URL 접두사별로 분리한다. 각 모듈이 전체 경로를 보유한다.
업무 로직	process · sop · agent · files · files_meta · my · usage · board · survey · orgs · users · grants · admins · audit · pageview · jobs · pmo	도메인 단위로 분리한다. 에이전트는 하위 패키지로 구성한다.
저장소	process · process_history · sop · sessions · files · files_meta · board · survey · orgs · users · grants · admins · audit · pmo · db · errors	도메인 단위로 분리한다. 데이터베이스 접속과 예외 정의를 포함한다.
공유 코어	pipeline · auth	변환 파이프라인, 설정, 추론 클라이언트, 인증과 계정

4.2. 에이전트 모듈 구성

모듈	책임
tools	Tool 계약과 시스템 프롬프트를 보유한다. 수행 로직을 포함하지 않는다.
handlers	Tool별 실제 수행을 담당한다.
loop	추론과 Tool 실행의 왕복을 제어하고 진행 이벤트를 생성한다.
turn	대화 한 턴의 오케스트레이션을 담당한다.
schema	산출물 구조의 정규화와 요약을 담당한다.
load	작성된 표준 양식의 적재를 담당한다.

4.3. 프런트엔드 구성

화면 단위 모듈과 공통 모듈로 분리한다.
서버 호출은 공통 호출 모듈 한 곳으로 일원화한다.
화면 모듈은 렌더 대상을 인자로 전달받는다.
모듈 간 순환 참조는 상위 모듈의 주입으로 해소하며 형제 모듈을 직접 참조하지 않는다.
빌드 산출물만 서버가 정적 자원으로 제공한다.

5. 주요 처리 흐름

5.1. SOP 생성

순서	계층	처리
1	라우트	대화 소유 여부를 확인한다.
2	업무 로직	생성 작업을 백그라운드 실행 단위로 등록한다. 동일 대화의 작업이 진행 중이면 그 작업에 연결한다.
3	업무 로직	시스템 프롬프트와 세션 컨텍스트를 구성하여 추론을 호출한다.
4	업무 로직	Tool 호출을 수행하고 결과를 반환한다. 장시간 Tool은 별도 실행 단위로 처리한다.
5	공유 코어	문서 변환 파이프라인을 수행하고 단계 진행을 전달한다.
6	업무 로직	산출물의 구조 유효성을 검증한 후 반영한다.
7	저장소	대화 이력과 작업 상태를 영속화한다.
8	라우트	진행 이벤트를 스트림으로 전달한다.

5.2. SOP 등록 및 편집

등록 시 작성자는 로그인 사용자로 기록하며 원본 문서의 값을 사용하지 않는다.
편집은 락을 획득한 경우에만 수행하며, 저장 시 기준 버전을 대조하여 충돌을 판정한다.
저장할 때마다 버전 스냅샷을 기록한다.
등록·수정·삭제·락 해제는 감사 기록 대상이다.

5.3. 권한 판정

모든 요청은 라우트 계층의 의존성에서 인증을 확인한다.
자원 접근은 소유 또는 가시 범위를 조건에 포함하여 판정한다.
가시 범위는 부여 범위와 그 하위 전체, 그리고 상위 경로의 뼈대로 구성한다.
권한이 없는 자원은 존재 여부를 노출하지 않는 응답으로 처리한다.

6. 상태 및 동시성

6.1. 상태 보관 위치

상태	보관 위치	비고
세션	서명 토큰(클라이언트 쿠키)	서버에 세션 레코드를 두지 않는다.
대화 이력 및 산출물	데이터베이스	재기동 후에도 유지한다.
원본 및 자산	자산 저장소	테이블에는 식별자만 기록한다.
진행 중 생성 작업	애플리케이션 메모리	재기동 시 유실된다. 단일 프로세스 구성을 전제로 한다.
변환 중간 산출물	로컬 작업 영역	재생성 가능한 데이터로 취급한다.

6.2. 동시성 제어

SOP 편집은 락과 버전 대조를 함께 적용한다. 락은 유효기간을 두고 만료 시 자동 해제한다.
버전 증가는 행 잠금으로 원자적으로 처리한다.
사용량 한도 검사와 증가는 하나의 트랜잭션으로 처리한다.
동일 대화에 대한 생성 작업의 중복 실행을 허용하지 않는다.

6.3. 백그라운드 작업

생성 작업은 요청 수명과 분리하여 서버가 소유한다. 진행 이벤트를 순번과 함께 버퍼에 축적하고, 구독자는 처음부터 재생한 후 완료까지 이어받는다. 화면 연결이 끊겨도 수행은 계속되며, 완료 후에도 일정 시간 버퍼를 유지하여 재연결을 허용한다.

7. 품질 속성 대응

품질 속성	대응 전략	한계 및 대응 계획
변경 용이성	계층 경계를 정적 분석으로 강제한다. 저장 기술 의존을 한 계층에 가둔다.	-
보안	라우트 계층이 저장소를 직접 호출할 수 없으므로 권한 확인을 우회하는 경로가 없다.	-
성능	대화형 단건 처리를 기준으로 한다. 장시간 처리를 요청과 분리한다.	문서 변환 시 순간 부하가 발생한다. 자원 산정에 반영한다.
확장성	세션과 업무 데이터를 외부화하여 상태 비보유에 근접시킨다.	진행 중 생성 작업 버퍼가 메모리에 있어 다중 프로세스로 확장할 수 없다. 확장 시 외부 저장소로 이전한다.
가용성	컨테이너 자동 재시작으로 복구한다. 데이터는 영속화한다.	단일 인스턴스 구성이며 재기동 시 진행 중 생성이 유실된다. 이중화는 후속 과제로 한다.
장애 격리	Tool 실행 실패를 값으로 반환하여 대화를 중단시키지 않는다. 저장소 예외와 서비스 불가를 별도 계열로 분리한다.	연속 장애 시 호출을 차단하는 장치를 두지 않는다. 실패 영향이 대화 단위에 한정되기 때문이다.

8. 아키텍처 결정 사항

번호	결정	검토한 대안	선택 근거	감수한 비용
AD-01	3계층 구조와 호출 방향을 정적 분석으로 강제한다.	관례에 의한 준수, 코드 리뷰	관례는 시간이 지나면 어긋난다. 기계가 판정하면 예외가 쌓이지 않는다.	전달 전용 서비스 함수가 생긴다.
AD-02	외부 에이전트 프레임워크를 사용하지 않고 직접 구현한다.	범용 에이전트 프레임워크 도입	제어 흐름이 단일 선형 왕복이고 Tool이 소수다. 진행 표시 요구가 맞춤형이다. 폐쇄망 반입에서 의존성 하나의 비용이 크다.	재연결 및 재생 기능을 직접 구현한다.
AD-03	단일 프로세스로 구동하고 생성 작업 버퍼를 메모리에 둔다.	외부 저장소 기반 작업 큐	현재 부하가 대화형 단건이며, 외부 저장소 도입의 이득이 운영 복잡도를 넘지 않는다.	재기동 시 진행 중 생성이 유실된다. 다중 프로세스로 확장할 수 없다.
AD-04	관계형 데이터베이스로 PostgreSQL을 사용하며 경량 엔진으로 대체하지 않는다.	파일 기반 경량 엔진	참조 해제 정책이 자산 보존의 핵심이며 경량 엔진에서 동일하게 동작하지 않는다. 개발 환경도 동일 엔진을 사용한다.	개발 환경에 데이터베이스 구동이 필요하다.
AD-05	체계도 노드 참조를 해제 방식으로 설정하여 SOP를 보존한다.	연쇄 삭제, 삭제 제한	체계 개편으로 노드가 폐지되어도 작성된 자산은 유실되면 안 된다.	연결이 없는 SOP가 발생하므로 재연결 절차가 필요하다.
AD-06	세션을 서명 토큰으로 관리하고 서버에 세션 레코드를 두지 않는다.	서버 세션 저장소	단일 프로세스 구성에서 저장소를 추가하지 않고 재기동 내성을 확보한다.	발급된 토큰을 만료 전에 무효화할 수 없다. 유효기간을 짧게 설정하여 완화한다.
AD-07	Tool 실행 실패를 예외로 전파하지 않고 값으로 반환한다.	예외 전파 후 대화 종료	실패 사유를 모델이 읽고 다음 조치를 판단할 수 있어야 대화가 이어진다.	예외 처리 범위가 넓어지므로 삼키는 사유를 주석으로 명시한다.
AD-08	산출물 파일을 저장하지 않고 요청 시마다 생성한다.	생성본 보관	스키마가 단일 진실이며 보관본과의 불일치가 발생하지 않는다.	다운로드 시 생성 비용이 발생한다.

9. 제약 및 전제

구분	내용
실행 환경	구동 기준은 Python 3.9이다. 런타임에 평가되는 타입 표기는 해당 버전 문법을 사용한다.
네트워크	운영 환경에 외부 인터넷 구간이 없다. 외부 자원을 실행 중에 내려받지 않는다.
배포	컨테이너 이미지를 외부에서 빌드하여 반입한다. 운영 환경에서 패키지를 설치하지 않는다.
프로세스	단일 프로세스로 구동한다. 코드 변경은 재기동을 수반한다.
외부 연계	추론 서비스, 자산 저장소 외의 외부 시스템 연계가 없다.

10. 작성 가이드

애플리케이션 아키텍처 정의서는 기능정의서와 비기능 요건을 입력으로 하여 내부 구조를 확정한다. 결정 사항은 선택한 안만이 아니라 검토한 대안과 감수한 비용을 함께 기술하여, 이후 변경 시 재검토의 근거가 되도록 한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적, 적용 범위, 설계 목표를 기술한다.	Y
아키텍처 개요	- 아키텍처 스타일과 선택 이유를 기술한다. - 전체 구성을 도식으로 기술한다.	Y
논리 아키텍처	- 계층별 책임과 금지 사항을 기술한다. - 호출 규칙과 그 강제 방법을 기술한다.	Y
모듈 구성	- 계층별 모듈 목록과 담당 영역을 기술한다. - 공유 모듈의 참조 제약을 기술한다.	Y
주요 처리 흐름	- 핵심 유스케이스를 계층 간 흐름으로 기술한다. - 권한 판정 시점을 명확히 한다.	Y
상태 및 동시성	- 상태별 보관 위치와 재기동 시 영향을 기술한다. - 동시성 제어 수단을 기술한다.	Y
품질 속성 대응	- 품질 속성별 대응 전략을 기술한다. - 한계와 대응 계획을 함께 기술한다. 달성하지 못한 속성을 누락하지 않는다.	Y
아키텍처 결정 사항	- 결정, 검토한 대안, 선택 근거, 감수한 비용을 함께 기술한다. - 결정에 번호를 부여하여 이후 변경 이력을 추적한다.	Y
제약 및 전제	- 실행 환경, 네트워크, 배포, 연계에 관한 제약을 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

클라우드 아키텍처 정의서

1. 개요

본 문서는 시스템이 운영되는 클라우드 환경의 계정 구성, 네트워크, 컴퓨팅, 저장소, 보안 구성 및 배포 절차를 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문의 운영 환경과 개발 환경 인프라 구성 전체에 적용된다. 애플리케이션 내부 구조는 애플리케이션 아키텍처 정의서에서, 보안 구현 기준은 보안 정의서에서 각각 정의한다.

1.2. 설계 전제

사용자는 사내 가상 데스크톱 환경에서 접속한다. 인터넷 구간을 경유하지 않는다.
모든 서브넷은 사설 구간이며 인터넷 게이트웨이와 주소 변환 게이트웨이를 구성하지 않는다.
외부 관리형 서비스 접근은 VPC 엔드포인트로만 수행한다.
계정을 용도별로 분리한다. 네트워크 공통 자원과 업무 자원을 서로 다른 계정에 둔다.
운영과 개발을 서로 다른 VPC로 분리한다. 각 환경은 단일 인스턴스로 구성한다.
관리형 데이터베이스 서비스를 사용하지 않고 컨테이너로 구성한다.
소프트웨어는 외부에서 빌드한 이미지를 반입하는 방식으로만 배포한다.

2. 아키텍처 구성

2.1. 전체 구성도

VDI 사용자가 Transit Gateway를 거쳐 운영과 개발 VPC의 EC2에 접속하고, 두 환경이 Network 계정의 Bedrock 런타임 엔드포인트를 공유하며, 자산 저장소는 각 VPC의 S3 게이트웨이 엔드포인트로 접근하는 구성도 — 추론 엔드포인트는 인터페이스 유형이라 Network 계정에 하나만 두고 Transit Gateway를 경유해 운영과 개발이 공유한다. 자산 저장소 엔드포인트는 게이트웨이 유형이라 VPC를 넘지 못하므로 환경마다 각각 둔다.

2.2. 계정 구성

계정	보유 자원	역할
`Network`	Transit Gateway, SKMR-NETWORK-VPC, Bedrock 런타임 엔드포인트	사내망과 업무 VPC 간 연결을 중계하고, 계정 간 공유가 가능한 인터페이스 엔드포인트를 집약한다.
`skmr_biz`	SKMR-BIZ-PRD-VPC, SKMR-BIZ-DEV-VPC, 각 환경의 EC2 및 S3 게이트웨이 엔드포인트	운영과 개발 업무 자원을 환경별로 분리하여 보유한다.

계정을 분리하여 네트워크 공통 자원과 업무 자원의 권한 경계를 나눈다. 업무 계정의 변경이 네트워크 공통 구성에 영향을 주지 않는다.

2.3. 구성 요소

구분	자원명	계정	CIDR 또는 유형	역할
연결	`SKMR-NW-TGW`	Network	Transit Gateway	사내망과 각 VPC 간 경로를 중계한다.
네트워크	`SKMR-NETWORK-VPC`	Network	10.239.185.0/25	공통 엔드포인트 전용 VPC
엔드포인트	Bedrock Runtime EP SKMR-NW-Sub-Pri-AP	Network	인터페이스	추론 서비스 접근 창구. 두 환경이 공유한다.
운영	`SKMR-BIZ-PRD-VPC`	skmr_biz	10.239.178.0/24	운영 환경 VPC
운영	`SKMR-BIZ-SOP-PRD`	skmr_biz	EC2	운영 애플리케이션 및 데이터베이스 컨테이너
운영	`SKMR-BIZ-PRD-S3-EP-GW`	skmr_biz	게이트웨이	운영 VPC의 자산 저장소 접근 경로
개발	`SKMR-BIZ-DEV-VPC`	skmr_biz	10.239.170.0/24	개발 환경 VPC
개발	`SKMR-BIZ-SOP-DEV`	skmr_biz	EC2	개발 애플리케이션 및 데이터베이스 컨테이너
개발	`SKMR-BIZ-DEV-S3-EP-GW`	skmr_biz	게이트웨이	개발 VPC의 자산 저장소 접근 경로

3. 네트워크 설계

3.1. 주소 체계

VPC	CIDR	가용 주소	용도
`SKMR-NETWORK-VPC`	10.239.185.0/25	128	엔드포인트 전용. 인스턴스를 배치하지 않으므로 소규모로 할당한다.
`SKMR-BIZ-PRD-VPC`	10.239.178.0/24	256	운영 업무 자원
`SKMR-BIZ-DEV-VPC`	10.239.170.0/24	256	개발 업무 자원

세 VPC의 대역은 중복되지 않는다. Transit Gateway를 통한 경로 중계가 성립하려면 연결되는 모든 대역이 서로 겹치지 않아야 한다.

3.2. 통신 경로

구간	경로	비고
사용자 → 운영·개발 애플리케이션	VDI → TGW → 각 VPC	사내망 구간이며 인터넷을 경유하지 않는다.
애플리케이션 → 추론 서비스	EC2 → TGW → Network VPC 엔드포인트 → Bedrock	업무 VPC에 엔드포인트를 두지 않고 공통 엔드포인트를 공유한다.
애플리케이션 → 자산 저장소	EC2 → 동일 VPC의 게이트웨이 엔드포인트 → S3	TGW를 경유하지 않는다.
운영 ↔ 개발	직접 연결하지 않는다	두 VPC 간 통신 경로를 구성하지 않는다.
외부 인터넷	경로 없음	인터넷 게이트웨이와 주소 변환 게이트웨이를 구성하지 않는다.

3.3. 엔드포인트 배치 원칙

엔드포인트는 유형에 따라 배치 위치를 달리한다.

유형	대상	배치	근거
인터페이스	추론 서비스	Network 계정에 1개	사설 주소를 가진 네트워크 인터페이스로 동작하므로 Transit Gateway를 경유하여 다른 VPC와 계정에서 사용할 수 있다. 환경별로 중복 생성하지 않는다.
게이트웨이	자산 저장소	업무 VPC마다 1개	라우팅 테이블 항목으로 동작하므로 해당 VPC 내부에서만 유효하다. Transit Gateway를 넘어 공유할 수 없어 환경별로 각각 생성한다.

공통 인터페이스 엔드포인트 사용 시 이름 해석을 함께 설계한다. 엔드포인트의 기본 사설 도메인 이름은 해당 엔드포인트가 속한 VPC에서만 해석된다. 업무 VPC에서 동일한 이름으로 접근하려면 사설 호스팅 영역을 공유하여 연결하거나, 엔드포인트 고유 도메인 이름을 애플리케이션 설정으로 주입한다. 본 시스템은 추론 클라이언트의 접속 주소를 설정으로 주입하는 방식을 사용한다.

3.4. 접근 제어

보안 그룹	대상	허용 규칙
`SKMR-BIZ-SOP-PRD-SG`	운영 EC2	- 사내망 대역에서 서비스 포트로의 수신 - 관리 대역에서 원격 접속 포트로의 수신 - 엔드포인트 방향 송신
`SKMR-BIZ-SOP-DEV-SG`	개발 EC2	- 운영과 동일한 원칙을 적용하되 허용 대역을 개발 담당 범위로 좁힌다.
`SKMR-NW-EP-Bedrock-SOP-SG`	추론 엔드포인트	- 운영 및 개발 VPC 대역에서 HTTPS 수신만 허용한다. - 그 밖의 출발지를 허용하지 않는다.

데이터베이스 포트는 인스턴스 외부로 개방하지 않는다. 컨테이너 간 내부 통신만 허용한다.
엔드포인트 정책으로 호출 가능한 모델과 접근 가능한 버킷을 제한한다.
각 VPC의 라우팅 테이블에 인터넷 방향 기본 경로를 두지 않는다.

3.5. 전송 구간 암호화

사용자와 애플리케이션 사이 구간에 TLS 1.2 이상을 적용한다.
TLS 종단은 애플리케이션 앞단에서 처리하고 인증서는 고객사 정책에 따라 발급한다.
암호화가 적용된 환경에서 세션 쿠키의 Secure 속성을 활성화한다.
엔드포인트를 경유하는 관리형 서비스 호출은 서비스가 제공하는 전송 암호화를 사용한다.

4. 컴퓨팅 및 컨테이너 구성

4.1. 인스턴스 구성

환경	인스턴스	구성 기준
운영	`SKMR-BIZ-SOP-PRD`	- 애플리케이션 컨테이너와 데이터베이스 컨테이너를 동일 인스턴스에 배치한다. - 문서 변환 병렬 처리와 이미지 처리 소요를 고려하여 사양을 산정한다.
개발	`SKMR-BIZ-SOP-DEV`	- 운영과 동일한 구성으로 배치하여 운영 전환 시의 차이를 줄인다. - 사양은 운영 대비 축소할 수 있다.

항목	기준	산정 근거
운영체제	Ubuntu 22.04 LTS	컨테이너 런타임 및 장기 지원 기준
vCPU	문서 변환 병렬 수를 고려하여 산정	평시 부하는 대화형 단건 처리이며 문서 변환 시 순간 부하가 발생한다.
메모리	변환 및 이미지 처리 소요를 고려하여 산정	페이지 렌더링과 이미지 추출 시 사용량이 증가한다.
스토리지	원본 보관과 작업 영역을 고려하여 산정	컨테이너 이미지가 문서 변환 도구를 포함하여 용량이 크다.

4.2. 컨테이너 구성

컨테이너	재시작 정책	구성 기준
애플리케이션	자동 재시작	- 문서 변환 도구를 이미지에 포함한다. 제외하면 원본 대조 기능이 동작하지 않는다. - 프런트 빌드 산출물을 이미지에 포함한다. - 단일 프로세스로 구동한다.
데이터베이스	자동 재시작	- 데이터 디렉터리를 볼륨으로 분리하여 컨테이너 교체 시에도 보존한다. - 인스턴스 외부로 포트를 개방하지 않는다.

세션 서명 키는 컨테이너 환경변수로 주입한다. 주입하지 않으면 재시작 시마다 값이 변경되어 전체 사용자의 세션이 무효화된다. 운영과 개발은 서로 다른 값을 사용한다.

5. 데이터 저장 구성

저장 대상	저장 위치	구성 기준
구조화 데이터	데이터베이스 컨테이너 볼륨	환경별로 분리된 인스턴스에 각각 보유한다. 스키마 변경은 마이그레이션 도구로 관리한다.
원본 문서 및 이미지	Amazon S3	게이트웨이 엔드포인트를 경유한다. 테이블에는 식별자만 기록한다. 운영과 개발은 서로 다른 버킷 또는 접두사를 사용한다.
중간 산출물	인스턴스 로컬 스토리지	재생성 가능한 데이터로 취급하며 정기적으로 정리한다.
백업	Amazon S3	정기 덤프를 전송한다. 보관 주기를 설정한다.

관리형 데이터베이스 서비스를 사용하지 않으므로 자동 백업 기능이 제공되지 않는다. 백업은 9장의 절차에 따라 직접 수행한다.

6. 추론 서비스 연동

6.1. 연동 구성

환경	연동 경로	자격 증명
운영	EC2 → TGW → Bedrock Runtime 엔드포인트 → Amazon Bedrock	인스턴스 역할로 취득한다. 키를 보관하지 않는다.
개발	운영과 동일 경로를 사용한다.	인스턴스 역할로 취득한다. 권한 범위를 개발용으로 분리한다.

엔드포인트 접속 주소는 설정으로 주입하며 코드에 포함하지 않는다.
연동 방식은 설정값으로 선택하며, 기동 시 선택된 방식과 모델 식별자를 기록한다.
엔드포인트 정책으로 호출 가능한 모델을 제한한다.
잘못된 설정값이 주입된 경우 기본 연동 방식으로 동작하고 사유를 기록한다.

6.2. 사용량 통제

호출마다 사용자, 모델, 토큰 수, 비용을 기록한다.
사용자별 월 한도와 분당 요청 수를 설정하고 호출 전에 검사한다.
한도 검사와 사용량 증가를 하나의 트랜잭션으로 처리한다.
운영과 개발의 사용량을 분리하여 집계한다.

7. 보안 구성

영역	구성 기준
네트워크 격리	- 공인 주소를 부여하지 않는다. - 인터넷 게이트웨이를 구성하지 않는다. - 보안 그룹으로 출발지 대역과 포트를 제한한다. - 운영과 개발 VPC 간 통신 경로를 두지 않는다.
계정 분리	- 네트워크 공통 자원과 업무 자원을 서로 다른 계정에 둔다. - 계정별로 권한 주체를 분리한다.
권한	- 인스턴스 역할에 필요한 최소 권한만 부여한다. - 자산 저장소는 지정된 버킷에 대한 접근만 허용한다. - 추론 서비스는 지정된 모델 호출만 허용한다. - 운영과 개발의 역할을 분리한다.
비밀 정보	- 접속 정보와 서명 키를 환경변수로 주입한다. - 이미지에 비밀 정보를 포함하지 않는다. - 환경별로 다른 값을 사용한다.
응답 헤더	- 프레임 삽입 차단, 형식 추론 금지, 전송 보안 강제 헤더를 적용한다.
감사	- 보안 이벤트를 애플리케이션 감사 로그에 기록한다. - 감사 로그는 추가 전용으로 보관한다.

8. 배포 및 반입 절차

8.1. 배포 원칙

운영 환경에서 패키지를 직접 설치하지 않는다.
컨테이너 이미지는 외부 빌드 환경에서 생성하여 반입한다.
반입 전 이미지에 포함된 구성요소 목록을 확인한다.
의존성 버전을 고정하여 반입 이미지와 개발 환경의 구성을 일치시킨다.
개발 환경에서 검증한 동일 이미지를 운영에 반입한다. 환경별로 다시 빌드하지 않는다.

8.2. 반입 절차

순서	단계	수행 내용
1	이미지 빌드	외부 빌드 환경에서 프런트 빌드와 컨테이너 이미지 생성을 수행한다.
2	이미지 추출	생성된 이미지를 파일로 추출한다.
3	개발 환경 반입	승인된 경로로 개발 인스턴스에 전송하여 적재하고 기능을 검증한다.
4	운영 환경 반입	검증된 동일 이미지를 운영 인스턴스에 전송하여 적재한다.
5	구성 적용	환경변수와 볼륨 구성을 적용하고 스키마 마이그레이션을 수행한다.
6	기동 확인	기동 로그에서 연동 방식과 모델 식별자를 확인하고 주요 기능을 점검한다.

8.3. 재배포

재배포 시에도 동일한 반입 절차를 적용한다.
데이터 볼륨은 유지하고 애플리케이션 컨테이너만 교체한다.
스키마 변경이 포함된 경우 마이그레이션을 먼저 수행한다.
이전 버전 이미지를 일정 기간 보관하여 복구 가능하도록 한다.

9. 백업 및 복구

대상	주기 및 방식	보관
데이터베이스	정기 덤프 생성 후 자산 저장소로 전송	보관 주기를 설정하고 초과분은 자동 삭제한다.
자산	저장소의 버전 관리 기능 사용	삭제 복구가 가능하도록 구성한다.
컨테이너 이미지	배포 시점마다 보관	직전 버전을 복구용으로 유지한다.

관리형 데이터베이스 서비스를 사용하지 않으므로 자동 백업이 제공되지 않는다. 백업 작업을 예약 작업으로 등록하여 수행한다.
백업 수행 결과를 기록하고 실패 시 확인할 수 있도록 한다.
복구 절차를 문서화하고 개발 환경에서 정기적으로 복구 시험을 수행한다.

10. 운영 및 모니터링

항목	운영 기준
가용성	- 환경별 단일 인스턴스 구성이므로 인스턴스 장애 시 해당 환경의 서비스가 중단된다. - 컨테이너는 자동 재시작으로 구성한다. - 이중화는 후속 과제로 한다.
단일 장애점	- 공통 추론 엔드포인트와 Transit Gateway는 운영과 개발이 공유하므로 장애 시 두 환경에 함께 영향을 준다. 변경 작업 시 영향 범위를 운영까지 포함하여 검토한다.
재시작 영향	- 서버 재시작 시 진행 중이던 생성 작업은 유실된다. - 저장된 산출물과 대화 이력은 유지된다.
로그	- 애플리케이션 로그와 접근 로그를 보관하고 주기적으로 순환한다. - 로그에 개인식별정보가 포함되지 않도록 한다.
사용량	- 추론 사용량과 비용을 사용자별로 집계하여 조회한다. - 환경별로 구분하여 집계한다.
자원 정리	- 소유자가 없는 잔여 자산을 정기적으로 점검한다. - 정리 작업은 점검 결과를 확인한 후 수행한다.
시간 동기화	- 감사 기록의 신뢰성을 위해 시각 동기화를 적용한다.

11. 작성 가이드

클라우드 아키텍처 정의서는 네트워크 제약과 외부 서비스 접근 경로를 먼저 확정하고, 그 제약 위에서 컴퓨팅, 저장소, 배포 방식을 정의한다. 폐쇄망 구성인 경우 반입 절차와 백업 절차를 반드시 포함한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적, 적용 범위, 설계 전제를 기술한다.	Y
아키텍처 구성	- 전체 구성도를 계정 경계가 보이도록 기술한다. - 계정별 보유 자원과 분리 근거를 기술한다. - 자원명, 계정, 주소 대역, 역할을 표로 기술한다.	Y
네트워크 설계	- VPC별 주소 대역과 중복 여부를 기술한다. - 구간별 통신 경로와 차단 구간을 기술한다. - 엔드포인트 유형별 배치 원칙과 근거를 기술한다. - 보안 그룹별 허용 규칙을 기술한다.	Y
컴퓨팅 구성	- 환경별 인스턴스와 사양 산정 근거를 기술한다. - 컨테이너 구성과 재시작 정책을 기술한다.	Y
데이터 저장 구성	- 저장 대상별 위치와 환경 간 분리 방법을 기술한다.	Y
외부 서비스 연동	- 환경별 연동 경로와 자격 증명 취득 방법을 기술한다. - 사용량 통제 방안을 기술한다.	Y
보안 구성	- 네트워크 격리, 계정 분리, 권한, 비밀 정보, 감사 구성 기준을 기술한다.	Y
배포 및 반입	- 배포 원칙과 반입 절차를 순서대로 기술한다. - 개발 검증 후 동일 이미지를 운영에 반입하는 원칙을 명시한다.	Y
백업 및 복구	- 대상별 백업 주기와 보관 기준을 기술한다. - 관리형 서비스를 사용하지 않는 경우 직접 수행할 작업을 명시한다.	Y
운영 및 모니터링	- 가용성 수준과 장애 시 영향 범위를 기술한다. - 환경 간 공유 자원을 단일 장애점으로 식별하여 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

개발표준 정의서

1. 개요

에이전트 기반 SOP 생성·관리 시스템의 개발 표준을 제시함으로써 개발자의 생산성을 향상시키고, 시스템의 일관성 및 품질을 확보하며, 유지보수를 용이하게 함을 목적으로 기술한 문서이다.

1.1. 표준 수립 방향

애플리케이션의 계층 구조와 계층 간 호출 방향에 대한 기본 원칙을 제시한다.
소스, 프롬프트, Tool 등 산출물에 대한 네이밍 규칙을 정한다.
LLM 플랫폼, 데이터베이스, 실행 환경 등 개발 환경에 대한 표준을 지정한다.
프롬프트 버전 관리 및 소스 형상 관리에 대한 표준을 정한다.
오류 처리, 로깅, 테스트, 품질 관리에 대한 표준을 정한다.
오픈소스 사용에 대한 라이선스 기준과 반입 절차를 정한다.

1.2. 표준 적용 범위

본 표준은 SKMR_현업 주도 SOP체계 구축 지원 및 자문 내에서 적용된다. 프로젝트와 관련된 개발 인력은 본 표준의 개발 환경 및 계층 구조를 이해한 후 지정된 개발 도구를 이용하여 프롬프트 표준, Tool 표준, 코딩 표준에 따라 개발에 참여한다. 보안에 관한 구현 기준은 보안 정의서에서 별도로 정의한다.

2. 개발 환경

2.1. 서버 및 인프라 환경

구분	용도	대수	환경
서버	애플리케이션 서버	1	- Cloud: AWS EC2 - OS: Ubuntu 22.04 LTS - Runtime: Python 3.9 이상 - Server: ASGI 단일 프로세스 - 외부 인터넷 구간 없음
서버	데이터베이스	1	- RDBMS: PostgreSQL 15 이상 - 동일 호스트 컨테이너로 구성 - 외부 포트를 개방하지 않는다 - 정기 백업을 오브젝트 스토리지로 전송한다
서비스	LLM 추론	-	- Amazon Bedrock - VPC 엔드포인트를 경유하여 호출한다 - 자격 증명은 인스턴스 역할로 취득한다
서비스	자산 저장소	-	- Amazon S3 - 원본 문서, 이미지, 백업 보관
개발	개발 환경	-	- OS: 고객사 VDI(Windows) 및 개발 서버 - 구동 기준 Python 3.9 - LLM 호출은 개발용 API 직결 구성을 사용한다

운영 환경은 인터넷 구간을 보유하지 않는다. 컨테이너 이미지는 외부에서 빌드하여 반입하며, 운영 환경에서 패키지를 직접 설치하지 않는다.

2.2. 개발 도구 및 설정 환경

구분	Software	Ver.	설치 대상	비고
LLM 플랫폼	Amazon Bedrock (Anthropic Claude)	-	애플리케이션 서버	운영 추론 경로
LLM 플랫폼	Anthropic API	-	개발 환경	개발용 직결 경로
에이전트 구현	자체 구현	-	애플리케이션 서버	외부 에이전트 프레임워크를 사용하지 않는다
웹 프레임워크	FastAPI	0.141	애플리케이션 서버	ASGI 기반
데이터베이스	PostgreSQL	15+	DB 컨테이너	스키마 변경은 마이그레이션 도구로 관리
문서 변환	LibreOffice	-	애플리케이션 이미지	원본 문서 변환 및 대조
형상관리	Git	-	형상관리 서버	소스 및 프롬프트 버전 관리
컨테이너	Docker	-	빌드 환경 / 운영	이미지 반입 방식으로 배포
프런트 빌드	Vite	7.x	빌드 환경	산출물만 운영에 반입한다
테스트	자체 테스트 러너	-	개발 환경 / CI	단위·통합·화면 테스트를 단일 실행으로 수행

3. 소스 관리

3.1. 소스 폴더 구조

3.1.1. 소스 폴더 구조도

프로젝트의 표준 폴더 구조는 다음과 같다.

project-root/
+-- app/                       # 애플리케이션
|   +-- api/                   # 라우트 계층
|   +-- services/              # 업무 로직 계층
|   |   +-- agent/             # 에이전트 오케스트레이션
|   +-- storage/               # 저장소 접근 계층
|   +-- migrations/            # DB 마이그레이션
|   +-- static/                # 프런트 소스 및 빌드 산출물
|   +-- tests/                 # 테스트 코드
+-- pipeline/                  # 문서 변환 및 생성 파이프라인
|   +-- scripts/               # 단계별 처리 스크립트
|   +-- config.py              # 경로·양식·설정 단일 출처
|   +-- runtime.py             # LLM 클라이언트 구성
+-- auth/                      # 인증·계정 공통 모듈
+-- docs/                      # 산출물 및 설계 문서
+-- scripts/                   # 운영 스크립트
+-- tools/                     # 개발 점검 도구
+-- deployment/                # 배포 설정
    +-- Dockerfile
    +-- docker-compose.yml

3.1.2. 폴더 구조 설명

폴더명	설명
app/api/	- HTTP 라우트만 위치하는 Directory - 권한 확인, 업무 로직 호출, 기록, 응답 변환의 네 가지만 수행한다 - 저장소 계층을 직접 호출하지 않는다
app/services/	- 업무 로직이 위치하는 Directory - 계산, 집계, 판단 및 복수 도메인에 걸친 처리 순서를 담당한다 - 에이전트 오케스트레이션은 하위 디렉터리로 분리한다
app/storage/	- 저장소 접근 코드가 위치하는 Directory - 질의와 영속화를 담당하며 HTTP 개념을 포함하지 않는다 - 저장 엔진 교체 시 본 Directory만 교체한다
pipeline/	- 문서 파싱, 생성, 검증, 산출물 작성 파이프라인이 위치하는 Directory - 애플리케이션 계층을 참조하지 않는다 - 경로 및 설정은 config 단일 모듈에서 관리한다
auth/	- 인증, 계정, 세션 발급 공통 모듈이 위치하는 Directory - 애플리케이션 계층을 참조하지 않는다
app/static/	- 프런트 소스가 위치하는 Directory - 빌드 산출물은 하위 dist Directory로 출력한다 - 외부 CDN을 참조하지 않으며 외부 라이브러리는 파일로 동봉한다
app/tests/	- 단위·통합·화면 테스트 코드가 위치하는 Directory - 테스트는 전용 계정으로만 수행하며 실데이터를 변경하지 않는다
tools/	- 코드 점검 도구가 위치하는 Directory - 계층 경계, 금지 패턴, 스키마 정합성을 기계적으로 검사한다

3.2. 네이밍 규칙

대상	규칙	예시
기능 ID	FN-{영역코드}-{일련번호}	FN-SOP-008 FN-AGT-001
모듈 파일명	snake_case, 도메인 단수형	process.py sop.py
Tool 명	{동사}_{목적어}, 소문자 snake_case	build_sop edit_sop
Tool 정의 상수	{TOOL명 대문자}_TOOL	EDIT_SOP_TOOL
테이블명	tb_{도메인}[_{하위}]	tb_sop tb_conversation
프런트 모듈	views/{화면}/{역할}.js	views/sop/viewer.js
화면 식별자	{화면}-{요소} 형식의 케밥 표기	sop-register process-tree
테스트 파일	{대상}_{관점}.py 또는 {대상}.js	sop_status.py login.js

3.3. 형상 관리

모든 소스와 프롬프트는 형상관리 저장소에서 버전 관리한다.
변경은 작업 단위로 분리하여 반영하고, 변경 사유를 이력에 기록한다.
자격 증명, 계정 정보, 개인정보가 포함된 파일은 형상관리 대상에서 제외한다.
빌드 산출물은 형상관리 대상에서 제외하고 빌드 시점에 생성한다.
의존성 버전은 고정하여 관리하며, 반입 이미지와 동일한 버전을 보장한다.

4. 계층 구조 표준

애플리케이션은 다음 세 계층으로 구성하며, 호출은 상위에서 하위 방향으로만 수행한다.

계층	역할	준수 사항
라우트 계층 (api)	요청 수신과 응답 변환	- 권한 및 가시 범위를 확인한다 - 업무 로직 계층을 호출한다 - 감사 대상 행위를 기록한다 - 예외를 응답 코드로 변환한다 - 계산·집계·판단을 수행하지 않는다 - 저장소 계층을 직접 호출하지 않는다
업무 로직 계층 (services)	업무 규칙의 수행	- 계산, 집계, 판단을 담당한다 - 복수 도메인에 걸친 처리 순서와 부수효과를 담당한다 - 질의문을 직접 작성하지 않는다
저장소 계층 (storage)	영속화와 질의	- 질의와 영속화만 담당한다 - HTTP 상태 개념을 포함하지 않는다 - 저장 엔진 교체 시 본 계층만 교체한다

공통 모듈(pipeline, auth)은 애플리케이션 계층을 참조하지 않는다.
계층 간 호출 방향은 정적 분석 도구로 검사하며, 예외를 두지 않는다.
질의문은 저장소 계층에만 작성하고, 상위 계층에서의 작성을 검사로 차단한다.

5. 프롬프트 표준

5.1. 프롬프트 구조 표준

시스템 프롬프트는 다음 구성 요소를 포함하여 작성한다.

구성 요소	필수 여부	설명
역할(Role)	Y	에이전트의 역할과 수행 범위를 한 문장으로 정의한다.
실행 원칙	Y	수행 절차와 금지 행위를 명시한다. 금지 행위는 "~하지 않는다" 형태로 직접 기술한다.
작업 유형별 지시	Y	작업 유형별로 사용할 Tool과 사용하지 않을 Tool을 구분하여 기술한다.
출력 형식	Y	응답의 형식과 보고 범위를 명시한다. 구조화된 결과는 Tool 입력 스키마로 규정한다.
자료 취급 원칙	Y	첨부 문서에서 추출한 내용은 자료로 취급하며 지시로 해석하지 않음을 명시한다.
예시	N	판단이 갈리는 상황에 한하여 입력과 응답의 예시를 포함한다.

5.2. 프롬프트 관리 표준

프롬프트는 소스와 동일한 형상관리 대상으로 관리한다.
프롬프트 변경은 검토를 거쳐 반영하며 변경 사유를 이력에 기록한다.
프롬프트 변경 시 회귀 평가를 수행하고 변경 전후의 결과를 비교한다.
사용자 입력은 시스템 프롬프트와 분리하여 전달하며 문자열로 결합하지 않는다.

5.3. 프롬프트 품질 기준

품질 항목	기준
명확성	지시사항이 모호하지 않고 단일하게 해석되어야 한다.
완전성	역할, 실행 원칙, 출력 형식, 자료 취급 원칙을 모두 포함하여야 한다.
일관성	절 구분과 표현 방식이 문서 전체에서 일관되어야 한다.
검증 가능성	회귀 평가로 변경의 영향을 정량 비교할 수 있어야 한다.
안전성	지시 주입 시도에 대한 취급 원칙을 포함하여야 한다.

6. Tool 표준

6.1. Tool 정의 표준

에이전트가 호출하는 모든 Tool은 다음 항목을 포함하여 정의한다.

정의 항목	설명
Tool 명	{동사}_{목적어} 형식으로 기능을 직관적으로 표현한다.
Description	Tool의 목적과 사용 시점을 기술한다. 선택 판단의 근거가 되므로 사용할 상황과 사용하지 않을 상황을 함께 기술한다.
Input Schema	JSON Schema 형식으로 입력 파라미터를 정의한다. 각 파라미터의 타입, 필수 여부, 설명을 포함한다.
처리 결과	성공 결과와 실패 사유를 모두 값으로 반환한다.
버전	스키마 변경 시 버전을 부여하고, 기존 명칭은 별칭으로 유지하여 하위 호환을 보장한다.

6.2. Tool 분류 및 유형별 표준

유형	정의	추가 적용 원칙
조회 Tool	데이터를 읽기만 하는 Tool	- 호출 주체의 접근 범위를 확인한다 - 현재 상태를 변경하지 않는다
변경 Tool	데이터를 생성·수정·삭제하는 Tool	- 입력 파라미터를 스키마 기준으로 재검증한다 - 기존 산출물을 대체하는 경우 수행 전 사용자에게 확인한다 - 처리 결과의 유효성을 검증한 후 반영한다
검증 Tool	산출물의 형식 또는 내용을 평가하는 Tool	- 평가 결과만 반환하고 산출물을 변경하지 않는다 - 반영 여부는 사용자가 결정한다

6.3. Tool 구현 표준

하나의 Tool은 하나의 기능만 수행한다.
Tool은 내부 상태를 보유하지 않으며, 상태는 호출 시 인자로 전달한다.
Tool 호출 실패는 오케스트레이션을 중단시키지 않고 사유를 값으로 반환한다.
Tool 호출의 입력과 결과를 로그로 기록한다.
외부 호출에는 제한 시간과 재시도 횟수를 설정한다.
Tool 단위 테스트를 필수로 작성한다.
단일 대화에서의 Tool 왕복 횟수 상한을 설정한다.

7. 코딩 표준

항목	기준
실행 환경 호환	- 구동 기준은 Python 3.9로 한다. - 런타임에 평가되는 타입 표기는 3.9 호환 문법을 사용한다. - 호환 여부는 점검 도구로 검사한다.
주석	- 주석은 동작이 아니라 그렇게 한 이유를 기술한다. - 다르게 구현하지 않은 이유와 과거 결함 이력을 함께 남긴다.
설정	- 경로, 양식, 포트 등 설정은 단일 모듈에서 관리한다. - 동일한 설정을 두 곳에서 해석하지 않는다.
화면 표기	- 산출물 및 화면에 이모지를 사용하지 않는다. - 아이콘은 벡터 이미지 또는 텍스트로 표기한다.
프런트 구조	- 화면 모듈은 렌더 대상을 인자로 전달받는다. - 모듈 간 순환 참조는 상위 모듈의 주입으로 해소한다. - 서버 호출은 공통 호출 모듈로 일원화한다.
선택자	- 복수 화면이 공유하는 속성 선택자는 식별자 또는 클래스로 한정한다.

8. 오류 처리 및 로깅 표준

8.1. 예외 분류

구분	응답 코드	적용
잘못된 입력	400	식별자 형식 오류 등 요청 자체가 성립하지 않는 경우
대상 없음	404	요청한 자원이 존재하지 않거나 접근 범위 밖인 경우
상태 충돌	409	편집 락 보유, 버전 불일치 등 현재 상태와 충돌하는 경우
요청 제한	429	로그인 실패 누적, 사용 한도 초과 등 제한에 걸린 경우
서비스 불가	503	데이터베이스 접속 불가 등 일시적으로 처리할 수 없는 경우

요청의 문제와 서비스의 문제를 서로 다른 예외 계열로 분리한다.
예외를 응답 코드로 변환하는 지점을 한 곳으로 일원화한다.
분류되지 않은 예외는 내부 정보를 노출하지 않고 미분류 사실만 응답과 로그에 기록한다.

8.2. 오류 코드 체계

오류 코드는 {시스템약어}-{발생영역}-{일련번호} 형식으로 부여한다.

발생 영역	영역 코드	적용 범위
오케스트레이션	ORCH	생성 작업의 시작, 중단, 스트림 단절
LLM 응답	LLM	제한 시간 초과, 인증 실패, 출력 절단, 토큰 한도 초과
Tool 실행	TOOL	Tool 입력 검증 실패, 처리 실패
저장소	STO	조회 실패, 상태 충돌, 영속화 실패
인증·인가	AUTH	인증 실패, 계정 잠금, 접근 거부

LLM 응답 오류는 제한 시간 초과, 인증 실패, 출력 절단, 토큰 한도 초과의 네 가지로 분류하고, 각각에 대응하는 사용자 안내 문구를 정의한다.

8.3. 로깅 표준

로깅 항목	기록 내용	레벨	마스킹
에이전트 수행 과정	Tool 선택, 실행, 결과 반영의 각 단계	INFO	N
사용자 입력	요청 구분과 처리 결과	INFO	Y
보안 이벤트	로그인 성공·실패, 계정 잠금, 접근 거부, 권한 변경, 관리자 행위	INFO	Y
오류	오류 코드, 발생 위치, 처리 결과	ERROR	Y

로그 한 줄은 발생 모듈, 사건, 속성의 순서로 기록한다.
비밀번호, 토큰, 개인식별정보는 평문으로 기록하지 않는다.
예외를 포괄적으로 처리하는 경우 무엇을 어떤 사유로 처리하는지 주석으로 명시한다.
감사 로그는 추가 전용으로 보관하며 수정과 삭제를 허용하지 않는다.

9. 테스트 및 품질 표준

9.1. 테스트 계층

계층	목적	검증 대상
단위 테스트	개별 함수와 Tool의 정상 동작 검증	입출력 정합성, 경계값, 예외 처리
통합 테스트	계층 간 연동 검증	라우트와 업무 로직, 업무 로직과 저장소
화면 테스트	사용자 시나리오 검증	로그인, 생성, 편집, 등록, 권한 분기
산출물 품질 평가	생성 산출물의 품질 회귀 검증	고정 입력 문서에 대한 형식 적합성 점수

9.2. 품질 점검 항목

점검 항목	기준
계층 경계	계층 간 호출 방향 위반이 없어야 한다. 예외를 허용하지 않는다.
금지 패턴	상위 계층의 질의문 작성, 한정자 없는 공유 선택자 사용 등 정의된 금지 패턴이 검출되지 않아야 한다.
스키마 정합성	데이터베이스 스키마가 데이터 정의서와 일치하여야 한다.
실행 환경 호환	구동 기준 버전에서 동작하지 않는 문법이 없어야 한다.
잔여 자원	테스트 수행 전후로 잔여 세션 자원이 증가하지 않아야 한다.

9.3. 품질 관리 절차

구조를 변경하는 작업은 단계마다 전체 점검을 수행하고, 전부 통과하지 않으면 다음 단계로 진행하지 않는다.
점검 도구를 추가할 때는 그 도구가 설명대로 동작하는지 확인하는 검증 케이스를 함께 작성한다.
테스트는 전용 계정으로만 수행하며 실사용 데이터를 변경하지 않는다.
테스트 수행 후 생성된 자원은 정의된 정리 절차로 제거한다.

10. 오픈소스 관리 표준

10.1. 라이선스 허용 기준

구분	라이선스	적용 조건
허용	MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC	고지문을 유지한다. 별도 승인을 요하지 않는다.
조건부	LGPL-2.1, LGPL-3.0, MPL-2.0	수정 없이 동적 연결 형태로만 사용한다. 사용 사실을 목록에 명시한다.
금지	GPL-2.0, GPL-3.0, AGPL-3.0, SSPL	납품물에 포함하지 않는다. 불가피한 경우 법무 검토 후 상용 라이선스를 취득한다.

10.2. 관리 절차

의존성을 추가할 때 명칭, 버전, 라이선스, 용도를 목록에 등재한다.
라이선스는 배포 패키지의 메타데이터에서 확인하며 추정하지 않는다.
모든 의존성의 버전을 고정하여 관리하고, 반입 이미지와 동일한 버전을 보장한다.
조건부 또는 금지 구분의 라이선스가 식별되면 반영 전에 검토 절차를 거친다.
외부 라이브러리를 파일로 동봉하는 경우 버전과 취득일을 함께 기록한다.

11. 작성 가이드

개발표준 정의서는 개발 환경과 계층 구조를 먼저 확정하고, 이에 따라 소스 관리, 프롬프트 표준, Tool 표준, 코딩 표준, 오류 처리 및 로깅 표준, 테스트 및 품질 표준, 오픈소스 관리 표준을 정의한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적을 개략적으로 기술한다.	Y
표준 수립 방향	- 표준 수립 방향을 개략적으로 기술한다.	Y
표준 적용 범위	- 표준의 적용 범위와 타 문서 소관 사항을 기술한다.	Y
서버 및 인프라 환경	- 서버, 데이터베이스, LLM 플랫폼, 자산 저장소의 사양과 용도를 기술한다. - 운영 환경과 가장 유사한 개발 환경을 갖추어 운영 전환 시의 문제를 예방한다.	Y
개발 도구 및 설정 환경	- LLM 플랫폼, 웹 프레임워크, 데이터베이스, 형상관리, 빌드, 테스트 도구를 명확히 기술한다.	Y
소스 폴더 구조	- 소스 폴더 구조를 Tree 형식으로 기술한다. - 폴더별 역할과 준수 사항을 기술한다.	Y
네이밍 규칙	- 기능 ID, 모듈, Tool, 테이블, 화면 식별자의 명명 규칙을 기술한다.	Y
계층 구조 표준	- 계층 구성과 계층별 역할, 금지 사항을 기술한다. - 계층 경계의 검사 방법을 함께 기술한다.	Y
프롬프트 표준	- 프롬프트 구성 요소와 필수 여부를 기술한다. - 버전 관리 및 품질 기준을 포함한다.	Y
Tool 표준	- Tool 정의 항목과 유형별 추가 원칙을 기술한다. - 구현 시 준수 사항을 기술한다.	Y
코딩 표준	- 실행 환경 호환, 주석, 설정 관리, 화면 표기 기준을 기술한다.	Y
오류 처리 및 로깅	- 예외 분류와 응답 코드 대응을 기술한다. - 오류 코드 체계와 로깅 항목, 마스킹 대상을 기술한다.	Y
테스트 및 품질	- 테스트 계층별 목적과 검증 대상을 기술한다. - 품질 점검 항목과 수행 절차를 기술한다.	Y
오픈소스 관리	- 라이선스 허용 기준을 구분별로 기술한다. - 의존성 등재 및 버전 고정 절차를 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

보안 정의서

1. 개요

본 문서는 시스템 개발 및 운영 전 과정에 적용할 보안 요구사항을 정의하고, 구현 시 준수하여야 할 기준을 제시함을 목적으로 기술한 문서이다.

1.1. 표준 수립 방향

소프트웨어 보안약점 진단 기준 및 공개 웹 취약점 기준을 반영한다.
입력 검증, 인증, 인가, 오류 처리, 민감정보 보호를 공통 처리 순서로 정한다.
LLM 기반 에이전트에 고유한 입출력 위협에 대한 방어 기준을 포함한다.
폐쇄망 운영 환경의 제약을 전제로 적용 가능한 통제를 선정한다.
모든 기준은 기계적으로 검사 가능한 형태를 우선한다.

1.2. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문의 신규 개발 및 변경 코드 전체에 적용된다. 본 기준을 충족하지 않는 변경은 반영하지 않는다. 예외가 필요한 경우 사유를 명시하고 책임자의 승인을 받은 후 진행한다.

1.3. 보안 처리 순서

모든 기능은 다음 순서로 보안 처리를 수행한다. 하나라도 누락되면 보안 결함으로 간주한다.

순서	처리	내용
1	입력 검증	외부에서 유입된 값의 형식과 범위를 검증한다.
2	인증	요청 주체의 신원을 확인한다.
3	인가	해당 자원에 대한 권한과 가시 범위를 확인한다.
4	안전한 오류 처리	실패 시 내부 정보를 노출하지 않고 정의된 응답을 반환한다.
5	민감정보 보호	응답과 로그에서 민감정보를 제외하거나 마스킹한다.

2. 입력값 검증 및 출력

2.1. 데이터 질의

모든 질의는 바인딩 파라미터를 사용한다. 문자열 결합으로 질의를 구성하지 않는다.
질의문은 저장소 계층에만 작성한다. 라우트 계층과 업무 로직 계층에서의 작성을 정적 검사로 차단한다.
정렬 컬럼, 정렬 방향 등 구조적 입력은 허용 목록으로만 매핑한다.
부분 일치 검색에 패턴 연산자를 사용할 때는 밑줄과 백분율 기호가 와일드카드로 해석됨을 고려하여 접두 일치 함수를 사용한다.

2.2. 출력 인코딩

사용자 입력 및 모델 생성 결과를 화면에 출력할 때는 HTML 특수문자를 치환한 후 출력한다.
마크다운 변환은 특수문자 치환을 먼저 수행한 후 서식 변환을 적용한다. 순서를 반대로 하지 않는다.
링크 생성 시 허용 스킴 목록에 해당하는 주소만 링크로 변환하고, 그 외는 본문으로 유지한다.
외부 링크에는 참조 차단 속성을 부여한다.

2.3. 파일 및 경로

항목	기준
업로드 확장자	- 허용 확장자 목록으로만 수신한다. - 허용 대상은 pdf, doc, docx, ppt, pptx, xls, xlsx, xlsm으로 한정한다.
파일 형식 검증	- 확장자와 선언된 형식에 더하여 파일 선두 시그니처를 검증한다. - 검증에 실패한 파일은 저장하지 않고 거부한다.
저장 위치	- 업로드 파일은 실행 가능한 경로 밖에 저장한다. - 저장 파일명은 시스템이 생성하며 원본 파일명을 그대로 사용하지 않는다.
경로 조합	- 외부에서 유입된 이름은 경로 조각으로 사용하기 전에 정규화한다. - 정규화 후 허용 루트 내부에 위치하는지 확인한다.
다운로드	- 안전한 콘텐츠 형식과 첨부 처리 헤더를 지정한다. - 파일명에 경로 구분자가 포함되지 않도록 한다.
외부 명령 실행	- 운영체제 명령 실행을 지양한다. - 불가피한 경우 인자를 배열로 분리하여 전달하고 셸을 경유하지 않는다.

2.4. 요청 본문 검증

요청 본문은 엔드포인트별 입력 스키마로 수신하며, 허용 필드를 명시한다.
데이터베이스 엔티티에 요청 본문을 직접 바인딩하지 않는다.
응답은 전용 응답 구조로 반환하며 내부 플래그와 민감 필드를 포함하지 않는다.
외부 데이터의 역직렬화와 구문 분석은 예외 처리로 감싸고, 실패 시 잘못된 요청으로 응답한다.
목록 조회 API는 조회 건수의 상한을 서버에서 강제한다.

2.5. 리다이렉트 및 외부 요청

사용자 입력으로 전달된 주소로 이동하지 않는다. 불가피한 경우 내부 주소 여부를 검증한다.
사용자 입력 주소로 서버가 직접 요청하지 않는다.
불가피하게 외부 요청이 필요한 경우 스킴과 호스트를 허용 목록으로 제한하고, 사설 대역, 루프백 대역, 링크로컬 대역을 차단하며, 리다이렉트 추적을 비활성화한다.

3. 보안 헤더 및 화면 속성

헤더 및 속성	필수 여부	적용 기준
X-Frame-Options	Y	동일 출처만 허용한다. 콘텐츠 보안 정책의 프레임 조상 지시자로 대체할 수 있다.
X-Content-Type-Options	Y	형식 추론을 금지한다.
Strict-Transport-Security	Y	암호화 전송이 적용된 응답에 지정한다.
Content-Security-Policy	N	교차 사이트 스크립트에 대한 심층 방어로 적용한다. 외부 자원을 참조하지 않는 구성이므로 자체 출처 기준으로 설정한다.
Referrer-Policy	N	외부로 전달되는 참조 정보를 제한한다.
비밀번호 입력 필드	Y	용도를 명시하는 자동완성 속성을 지정한다. 비밀번호 관리 도구의 사용을 차단하지 않는다.
주민번호·카드번호 입력 필드	Y	자동완성을 비활성화한다.

4. 인증

4.1. 계정 및 비밀번호

항목	기준
저장 방식	- 비밀번호는 솔트를 적용한 단방향 해시로 저장한다. - 키 유도 함수는 scrypt, bcrypt, PBKDF2 중 하나를 사용한다. - 평문, MD5, SHA-1 저장을 금지한다.
솔트	- 계정별로 서로 다른 값을 암호학적 난수로 생성한다.
초기 비밀번호	- 발급 후 최초 로그인 시 변경을 유도한다. - 초기 비밀번호 생성 규칙을 외부에 공개하지 않는다.
복잡도	- 길이와 문자 종류에 대한 최소 기준을 적용한다.
계정 식별	- 사번의 대소문자 차이를 동일한 계정으로 취급한다. - 인증 실패 시 사번과 비밀번호 중 어느 것이 틀렸는지 구분하여 응답하지 않는다.

4.2. 세션

로그인 성공 시 세션 식별값을 새로 발급한다.
세션 쿠키에 HttpOnly, Secure, SameSite 속성을 지정한다.
세션 유효기간을 설정하고, 만료된 세션은 거부한다.
로그아웃 시 세션 쿠키를 제거한다.
세션 서명 키는 환경별로 다른 값을 사용하고, 재기동 시에도 동일한 값이 유지되도록 주입한다.
서명 검증은 타이밍 공격에 안전한 비교 함수를 사용한다.

4.3. 자동화 공격 대응

로그인, 비밀번호 변경 등 민감 엔드포인트는 계정 단위와 출발지 단위로 요청 횟수를 제한한다.
인증 실패가 누적되면 일정 시간 동안 차단하고, 차단 사실을 감사 로그에 기록한다.
차단 카운터는 재기동 후에도 유지되도록 영속 저장소에 보관한다.
대량 조회를 방지하기 위해 목록 API의 조회 건수 상한을 서버에서 강제한다.

5. 인가

5.1. 권한 검증 원칙

인가는 서버에서 요청마다 검증한다. 화면 요소의 숨김은 보안 통제로 인정하지 않는다.
라우트 계층은 저장소 계층을 직접 호출하지 않으므로, 권한 확인을 우회하는 경로가 발생하지 않도록 한다.
권한 확인에 실패한 요청은 자원의 존재 여부를 노출하지 않는 응답으로 처리한다.

5.2. 가시 범위 제어

조회 및 수정 질의의 조건에 요청자의 소유 또는 가시 범위를 포함한다.
주소의 식별자를 변조하여 타인의 자원에 접근할 수 없도록 한다.
목록, 검색, 상세 조회에 동일한 범위 기준을 적용한다.

5.3. 관리자 권한

관리자 권한은 지정된 계정에 한하여 부여하며, 로그인 사용자 전체를 의미하지 않는다.
권한 확대는 필요한 최소 범위로 한정한다.
권한 부여 및 회수는 수행자, 대상, 시각과 함께 감사 로그에 기록한다.

6. 암호화 및 비밀 관리

6.1. 전송 구간

모든 통신 구간에 TLS 1.2 이상을 적용한다.
암호화가 적용된 환경에서는 세션 쿠키의 Secure 속성을 활성화한다.
인증서 검증을 비활성화하지 않는다.
서비스 포트는 필요한 대역에만 공개하고, 그 외 접근은 차단한다.

6.2. 저장 구간

비밀번호는 복호화할 수 없는 형태로 저장한다.
개인정보가 포함된 파일은 형상관리 대상에서 제외한다.
데이터베이스 백업은 접근이 통제된 저장소에 보관한다.

6.3. 비밀 정보 관리

접속 정보, API 키, 서명 키를 소스 코드에 포함하지 않는다.
비밀 정보는 환경변수 또는 비밀 관리 수단으로 분리하여 주입한다.
클라우드 서비스 호출 자격 증명은 인스턴스 역할로 취득하며 키를 보관하지 않는다.
비밀 정보가 설정되지 않은 경우 기동 시점에 사유를 확인할 수 있도록 한다.

6.4. 암호 API

토큰, 솔트, 세션 키 등 보안 용도의 난수는 암호학적 난수 생성기를 사용한다.
일반 난수 생성기를 보안 용도로 사용하지 않는다.
서명 및 해시 비교는 타이밍 공격에 안전한 비교 함수를 사용한다.

7. 에이전트 보안

7.1. 입력 가드레일

위협	방어 기준
지시 주입	- 사용자 입력을 시스템 프롬프트와 분리하여 전달하고 문자열로 결합하지 않는다. - 시스템 지시를 우회하려는 입력 패턴을 탐지하고 차단한다.
첨부 문서를 통한 간접 주입	- 첨부 문서에서 추출한 내용은 자료로 취급하며 지시로 해석하지 않음을 시스템 프롬프트에 명시한다. - 문서 내용은 지시 영역과 구분되는 위치에 배치한다.
개인정보 유입	- 입력에 포함된 개인식별정보를 탐지하여 마스킹한 후 기록한다.
과다 입력	- 입력 길이의 상한을 설정한다. - 단일 대화의 Tool 왕복 횟수 상한을 설정한다.

7.2. 출력 가드레일

시스템 프롬프트의 내용이 응답에 포함되지 않도록 지시를 명시한다.
생성 결과를 화면에 출력하기 전에 특수문자를 치환한다.
응답에 개인식별정보가 포함되지 않도록 검증한다.
산출물로 반영하기 전에 구조 유효성을 검증하고, 실패 시 반영하지 않는다.

7.3. Tool 호출 통제

Tool 호출 시 호출 주체의 자원 소유 여부를 확인한다.
데이터를 변경하는 Tool은 입력 파라미터를 스키마 기준으로 재검증한다.
기존 산출물을 대체하는 Tool은 수행 전에 사용자에게 확인한다.
Tool 실행 실패는 오케스트레이션을 중단시키지 않고 사유를 값으로 반환한다.

8. 오류 처리 및 보안 로깅

8.1. 오류 응답

스택 추적, 질의문, 내부 덤프를 사용자 응답에 포함하지 않는다.
상세 오류 정보는 서버 로그에만 기록한다.
예외를 사유 없이 무시하지 않는다. 포괄적으로 처리하는 경우 그 사유를 주석으로 명시한다.
분류되지 않은 예외는 미분류 사실만 응답에 포함하고 내부 정보를 노출하지 않는다.

8.2. 보안 이벤트 기록

다음 이벤트는 수행자, 시각, 대상과 함께 반드시 기록한다. 민감정보는 마스킹하여 기록한다.

이벤트	기록 항목
로그인 성공 및 실패	사번, 시각, 출발지 구분, 결과
계정 잠금	사번, 시각, 잠금 사유, 해제 예정 시각
인가 거부	사번, 시각, 요청 자원, 거부 사유
권한 및 역할 변경	수행자, 대상 계정, 변경 전후 값, 시각
관리자 행위	수행자, 행위 유형, 대상, 시각
자원 등록·수정·삭제	수행자, 대상 식별자, 행위 유형, 시각
편집 락 강제 해제	수행자, 대상, 기존 보유자, 시각

8.3. 감사 로그 보관

감사 로그는 추가 전용으로 보관하며, 수정과 삭제를 허용하지 않는다.
애플리케이션 계정에는 감사 테이블에 대한 수정 및 삭제 권한을 부여하지 않는다.
정의되지 않은 행위 유형은 기록 대상에서 제외하고, 제외 사실을 확인할 수 있도록 한다.
접근 로그는 보관 주기를 정하여 순환하고, 개인식별정보가 포함되지 않도록 한다.

9. 개발 및 배포 보안

배포 전 디버그 코드, 시험용 엔드포인트, 콘솔 출력을 제거한다.
운영 환경에 외부 인터넷 구간을 두지 않는다. 컨테이너 이미지는 외부에서 빌드하여 반입한다.
반입 이미지에 포함된 의존성 목록을 사전에 확인하고, 등재되지 않은 구성요소가 포함된 경우 반입하지 않는다.
데이터베이스 포트를 외부에 개방하지 않는다.
개인정보가 포함된 파일과 자격 증명 파일은 형상관리에 포함하지 않는다.
시험은 전용 계정으로만 수행하며 실사용 데이터를 변경하지 않는다.
시험 데이터에 포함된 개인정보는 마스킹하여 사용한다.

10. 보안 점검 항목

변경 반영 전에 다음 항목을 점검한다.

점검 항목	해당 절	점검 방법
질의 파라미터 바인딩	2.1	정적 검사로 상위 계층의 질의문 작성 여부를 확인한다.
출력 인코딩	2.2	사용자 및 모델 생성 값의 출력 경로를 검토한다.
파일 업로드 및 경로 검증	2.3	확장자, 시그니처, 경로 정규화 적용 여부를 확인한다.
요청 본문 스키마	2.4	엔드포인트별 입력 스키마 정의 여부를 확인한다.
보안 헤더	3	응답 헤더를 확인한다.
비밀번호 저장	4.1	해시 알고리즘과 솔트 적용을 확인한다.
세션 쿠키 속성	4.2	HttpOnly, Secure, SameSite 지정을 확인한다.
요청 횟수 제한	4.3	민감 엔드포인트의 제한 적용과 조회 상한을 확인한다.
서버측 인가 검증	5	식별자 변조 시나리오로 접근을 시도한다.
비밀 정보 분리	6.3	소스 내 자격 증명 포함 여부를 검색한다.
지시 주입 방어	7.1	입력 분리와 자료 취급 원칙의 명시 여부를 확인한다.
오류 메시지 비노출	8.1	오류 응답에 내부 정보가 포함되는지 확인한다.
보안 이벤트 기록	8.2	정의된 이벤트의 기록 여부를 확인한다.
감사 로그 보관	8.3	수정 및 삭제 권한 회수 여부를 확인한다.
디버그 코드 제거	9	정적 검사로 잔여 디버그 흔적을 확인한다.

11. 작성 가이드

보안 정의서는 요구사항 정의서의 보안 요구사항과 상위 설계 원칙을 입력으로 하여, 구현 단계에서 준수할 기준을 구체적으로 확정한다. 기준은 기계적으로 검사 가능한 형태를 우선하며, 검사 방법을 함께 기술한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적과 근거 기준을 기술한다.	Y
적용 범위	- 적용 대상과 예외 처리 절차를 기술한다.	Y
보안 처리 순서	- 모든 기능에 공통 적용할 처리 순서를 기술한다.	Y
입력값 검증 및 출력	- 질의, 출력 인코딩, 파일 및 경로, 요청 본문, 외부 요청에 대한 기준을 기술한다. - 사용하는 기술 스택에 맞는 구체적 수단으로 기술한다.	Y
보안 헤더	- 적용 헤더와 필수 여부, 적용 기준을 기술한다.	Y
인증	- 비밀번호 저장, 세션 관리, 자동화 공격 대응 기준을 기술한다.	Y
인가	- 서버측 검증 원칙, 가시 범위 제어, 관리자 권한 기준을 기술한다.	Y
암호화 및 비밀 관리	- 전송 및 저장 구간 암호화, 비밀 정보 분리, 암호 API 사용 기준을 기술한다.	Y
에이전트 보안	- 입출력 가드레일과 Tool 호출 통제 기준을 기술한다. - 첨부 문서를 통한 간접 주입에 대한 취급 원칙을 포함한다.	Y
오류 처리 및 로깅	- 오류 응답 기준, 기록할 보안 이벤트, 감사 로그 보관 기준을 기술한다. - 마스킹 대상을 명시한다.	Y
개발 및 배포 보안	- 배포 전 제거 대상, 반입 절차, 시험 데이터 취급 기준을 기술한다.	Y
보안 점검 항목	- 변경 반영 전 점검할 항목과 점검 방법을 목록으로 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

인터페이스 정의서

1. 개요

본 문서는 화면과 서버 간, 그리고 서버와 외부 서비스 간 인터페이스의 규약, 목록 및 상세 명세를 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문이 제공하는 전체 인터페이스에 적용된다. 데이터 구조는 데이터베이스 정의서에서, 인증 및 인가의 구현 기준은 보안 정의서에서 정의한다.

1.2. 식별 체계

인터페이스 ID는 IF-{영역코드}-{일련번호} 형식으로 부여한다. 영역코드는 기능정의서의 영역 구분을 따르며, 관리자 전용과 공통 영역을 추가한다.

영역코드	영역	대상
AUT	인증	로그인, 로그아웃, 세션 확인, 비밀번호 변경
PRC	프로세스 체계도	노드 조회, 검색, 등록, 삭제
SOP	SOP 관리	목록, 상세, 등록, 수정, 삭제, 락, 버전
AGT	SOP 에이전트	대화, 첨부, 생성, 스트림, 산출물
FIL	파일	원본, 페이지, 스키마, 다운로드
USG	사용량	조회, 한도
BRD	게시판	문의, 공지, 요청
COM	공통	개인 요약, 설문
ADM	관리자	계정, 권한, 조직, 감사, 개정, 락, 일괄 처리

2. 공통 규약

항목	규약
프로토콜	HTTP/1.1 이상. 전송 구간은 TLS 1.2 이상으로 암호화한다.
데이터 형식	요청과 응답 모두 JSON을 기본으로 한다. 문자 집합은 UTF-8이다. 파일 업로드는 멀티파트 형식을 사용하고, 파일 다운로드와 이벤트 스트림은 예외로 한다.
경로 규칙	자원 중심으로 구성한다. 접두사는 `/api`이며, 관리자 전용은 `/api/admin`을 사용한다.
메서드	조회는 GET, 생성은 POST, 전체 수정은 PUT, 삭제는 DELETE를 사용한다. 상태 전이 등 자원 생성이 아닌 행위는 POST에 행위명을 경로 끝에 둔다.
인증	서명 쿠키 기반 세션을 사용한다. 모든 인터페이스는 인증을 요구한다.
인가	요청마다 서버에서 검증한다. 소유 또는 가시 범위를 질의 조건에 포함한다.
목록 조회	조회 건수 상한을 서버에서 강제한다. 요청이 상한을 초과하면 상한값으로 처리한다.
버전 관리	경로에 버전을 포함하지 않는다. 호환되지 않는 변경이 필요한 경우 신규 경로를 추가하고 기존 경로를 일정 기간 유지한다.
멱등성	GET, PUT, DELETE는 멱등으로 설계한다. POST는 멱등을 보장하지 않는다.

3. 공통 응답 및 오류

3.1. 상태 코드

코드	의미	적용
200	정상	조회 및 처리 성공
400	잘못된 요청	필수 항목 누락, 형식 오류, 안전하지 않은 식별자
401	인증 필요	세션이 없거나 만료된 경우
403	권한 없음	관리자 전용 인터페이스에 일반 사용자가 접근한 경우
404	대상 없음	자원이 없거나 가시 범위 밖인 경우
409	상태 충돌	편집 락 보유, 버전 불일치, 중복 생성
422	처리 불가	요청 본문의 구조가 규격과 일치하지 않는 경우
429	요청 제한	로그인 실패 누적, 사용 한도 초과
500	서버 오류	분류되지 않은 내부 오류
503	서비스 불가	데이터베이스 접속 불가 등 일시적 장애

권한이 없는 자원은 403이 아니라 404로 응답한다. 403은 자원의 존재를 알려주므로 가시 범위 밖의 자원 식별자를 탐색할 수 있게 된다. 관리자 전용 인터페이스처럼 자원이 아니라 기능 자체에 대한 접근을 막는 경우에만 403을 사용한다.

3.2. 오류 응답 형식

항목	타입	설명
`detail`	문자열	사용자에게 표시할 사유. 스택 추적, 질의문, 내부 식별자를 포함하지 않는다.
`code`	문자열	오류 코드. 개발표준 정의서의 오류 코드 체계를 따른다.

4. 인터페이스 목록

4.1. 인증

ID	메서드	경로	기능	권한	관련 기능ID
IF-AUT-001	GET	`/api/auth/me`	세션 상태 및 로그인 필요 여부 조회	공개	FN-AUT-001
IF-AUT-002	POST	`/api/auth/login`	사번·비밀번호 인증 후 세션 발급	공개	FN-AUT-001
IF-AUT-003	POST	`/api/auth/logout`	세션 종료	로그인	FN-AUT-001
IF-AUT-004	POST	`/api/auth/password`	비밀번호 변경	로그인	FN-AUT-002

4.2. 프로세스 체계도

ID	메서드	경로	기능	권한	관련 기능ID
IF-PRC-001	GET	`/api/process/nodes`	가시 범위 내 체계도 트리 조회	로그인	FN-PRC-001
IF-PRC-002	GET	`/api/process/nodes/{node_id}`	노드 상세 및 연결 SOP 조회	로그인	FN-PRC-001
IF-PRC-003	GET	`/api/process/search`	노드명·코드·부서·SOP명 검색	로그인	FN-PRC-002
IF-PRC-004	POST	`/api/admin/process/nodes`	노드 등록 및 수정	관리자	FN-PRC-003, FN-PRC-004
IF-PRC-005	DELETE	`/api/admin/process/nodes/{node_id}`	노드 삭제	관리자	FN-PRC-005

4.3. SOP 관리

ID	메서드	경로	기능	권한	관련 기능ID
IF-SOP-001	GET	`/api/sop`	SOP 목록 조회	로그인	FN-SOP-001
IF-SOP-002	POST	`/api/sop`	SOP 등록	로그인	FN-SOP-009
IF-SOP-003	GET	`/api/sop/{sop_id}`	SOP 상세 조회	가시 범위	FN-SOP-002
IF-SOP-004	PUT	`/api/sop/{sop_id}`	SOP 저장. 기준 버전 대조	락 보유자	FN-SOP-008
IF-SOP-005	DELETE	`/api/sop/{sop_id}`	SOP 삭제	작성자·관리자	FN-SOP-010
IF-SOP-006	POST	`/api/sop/{sop_id}/lock`	편집 락 획득 및 연장	가시 범위	FN-SOP-007
IF-SOP-007	DELETE	`/api/sop/{sop_id}/lock`	편집 락 해제. 관리자는 강제 해제	락 보유자·관리자	FN-SOP-007
IF-SOP-008	GET	`/api/sop/{sop_id}/versions`	버전 목록 조회	가시 범위	FN-SOP-011
IF-SOP-009	GET	`/api/sop/{sop_id}/versions/{version}`	특정 버전 본문 조회	가시 범위	FN-SOP-011
IF-SOP-010	POST	`/api/sop/{sop_id}/restore/{version}`	특정 버전으로 복원	락 보유자	FN-SOP-011
IF-SOP-011	GET	`/api/sop/{sop_id}/xlsm`	표준 양식 산출물 다운로드	가시 범위	FN-SOP-003
IF-SOP-012	GET	`/api/sop/similar`	유사 SOP 검색	로그인	FN-AGT-007

4.4. SOP 에이전트

ID	메서드	경로	기능	권한	관련 기능ID
IF-AGT-001	GET	`/api/agent/conversations`	본인 대화 목록 조회	로그인	FN-AGT-005
IF-AGT-002	POST	`/api/agent/conversations`	대화 생성	로그인	FN-AGT-005
IF-AGT-003	GET	`/api/agent/conversations/{cid}`	대화 복원. 산출물·첨부·이력 반환	소유자	FN-AGT-005
IF-AGT-004	DELETE	`/api/agent/conversations/{cid}`	대화 삭제. 연결 자산 함께 제거	소유자	FN-AGT-005
IF-AGT-005	POST	`/api/agent/{sid}/upload`	원본 문서 첨부	소유자	FN-AGT-003
IF-AGT-006	DELETE	`/api/agent/{sid}/sources/{name}`	첨부 삭제	소유자	FN-AGT-003
IF-AGT-007	POST	`/api/agent/{sid}/sources/{name}/parse`	첨부 구조 추출	소유자	FN-AGT-004
IF-AGT-008	POST	`/api/agent/{sid}/chat`	대화 1턴 실행. 진행 이벤트 스트리밍	소유자	FN-AGT-001, FN-AGT-002
IF-AGT-009	GET	`/api/agent/{sid}/stream`	진행 중 생성에 재연결	소유자	FN-AGT-002
IF-AGT-010	POST	`/api/agent/{sid}/schema`	편집 중 산출물 저장	소유자	FN-AGT-001
IF-AGT-011	POST	`/api/agent/{sid}/message`	이력에 시스템 메시지 추가	소유자	FN-AGT-005
IF-AGT-012	POST	`/api/agent/{sid}/load-sop/{sop_id}`	등록 SOP를 대화로 불러오기. 편집 락 획득	소유자	FN-AGT-006
IF-AGT-013	POST	`/api/agent/{sid}/download`	현재 산출물을 표준 양식으로 생성	소유자	FN-SOP-003

4.5. 파일

ID	메서드	경로	기능	권한	관련 기능ID
IF-FIL-001	GET	`/api/files/{stem}/schema`	산출물 구조 조회	가시 범위	FN-SOP-002
IF-FIL-002	PUT	`/api/files/{stem}/schema`	산출물 구조 저장	락 보유자	FN-SOP-008
IF-FIL-003	GET	`/api/files/{stem}/source`	원본 문서 메타 조회	가시 범위	FN-SOP-006
IF-FIL-004	GET	`/api/files/{stem}/pages`	원본 페이지 이미지 목록 조회	가시 범위	FN-SOP-006
IF-FIL-005	GET	`/api/files/{stem}/media/{filename}`	이미지 자산 조회	가시 범위	FN-SOP-006
IF-FIL-006	POST	`/api/files/{stem}/media`	활동 사진 등록	락 보유자	FN-SOP-008
IF-FIL-007	GET	`/api/files/{stem}/download`	산출물 파일 다운로드	가시 범위	FN-SOP-003

4.6. 사용량

ID	메서드	경로	기능	권한	관련 기능ID
IF-USG-001	GET	`/api/usage/me`	본인 사용량 집계 조회	로그인	FN-USG-002
IF-USG-002	GET	`/api/usage`	전체 사용량 집계 조회	관리자	FN-USG-002
IF-USG-003	GET	`/api/usage/quota/{uid}`	사용자 한도 조회	본인·관리자	FN-USG-003
IF-USG-004	PUT	`/api/admin/usage/quota/{uid}`	사용자 한도 설정	관리자	FN-USG-003

4.7. 게시판 및 공통

ID	메서드	경로	기능	권한
IF-BRD-001	GET	`/api/faq`	공지 목록 조회	로그인
IF-BRD-002	GET	`/api/faq/{number}`	공지 상세 조회	로그인
IF-BRD-003	GET	`/api/faq/{number}/media/{filename}`	공지 첨부 조회	로그인
IF-BRD-004	POST	`/api/qa`	문의 등록	로그인
IF-BRD-005	POST	`/api/qa/{number}/images`	문의 이미지 첨부	작성자
IF-BRD-006	GET	`/api/qa/{number}/media/{filename}`	문의 첨부 조회	작성자·관리자
IF-BRD-007	POST	`/api/myreq`	내 요청 등록	로그인
IF-BRD-008	GET	`/api/requests`	요청 목록 조회	로그인
IF-BRD-009	POST	`/api/requests`	요청 등록	로그인
IF-BRD-010	GET	`/api/requests/{number}`	요청 상세 조회	작성자·관리자
IF-BRD-011	DELETE	`/api/requests/{number}`	요청 취소	작성자
IF-BRD-012	POST	`/api/requests/{number}/comments`	요청 댓글 등록	작성자·관리자
IF-BRD-013	POST	`/api/requests/{number}/close`	요청 완료 처리	관리자
IF-BRD-014	POST	`/api/requests/{number}/verify`	요청 본인 확인	로그인
IF-BRD-015	POST	`/api/requests/{number}/result-access`	요청 결과 열람 승인	작성자
IF-COM-001	GET	`/api/my/summary`	개인 작업 현황 요약	로그인
IF-COM-002	GET	`/api/survey/status`	설문 응답 여부 조회	로그인
IF-COM-003	POST	`/api/survey/submit`	설문 응답 제출	로그인

4.8. 관리자

ID	메서드	경로	기능	관련 기능ID
IF-ADM-001	GET	`/api/admin/users`	계정 목록 조회	FN-AUT-005
IF-ADM-002	GET	`/api/admin/orgs`	조직 목록 조회	FN-AUT-005
IF-ADM-003	GET	`/api/admin/roles`	역할 목록 조회	FN-AUT-005
IF-ADM-004	GET	`/api/admin/admins`	관리자 목록 조회	FN-AUT-005
IF-ADM-005	PUT	`/api/admin/admins/{uid}`	관리자 승격 및 회수	FN-AUT-005
IF-ADM-006	GET	`/api/admin/grants`	권한 부여 목록 조회	FN-AUT-003
IF-ADM-007	POST	`/api/admin/grants`	가시 범위 부여	FN-AUT-003
IF-ADM-008	DELETE	`/api/admin/grants/{grant_id}`	가시 범위 회수	FN-AUT-003
IF-ADM-009	GET	`/api/admin/locks`	편집 락 현황 조회	FN-DAT-003
IF-ADM-010	GET	`/api/admin/audit`	감사 로그 조회	FN-DAT-005
IF-ADM-011	GET	`/api/admin/revisions`	체계도 개정 목록 조회	FN-PRC-007
IF-ADM-012	GET	`/api/admin/revisions/{revision_id}`	개정 상세 조회	FN-PRC-007
IF-ADM-013	POST	`/api/admin/revisions/{revision_id}/revert`	개정 되돌리기	FN-PRC-008
IF-ADM-014	GET	`/api/admin/conversations`	전체 대화 목록 조회	FN-AUT-005
IF-ADM-015	GET	`/api/admin/conversations/{cid}`	대화 상세 조회	FN-AUT-005
IF-ADM-016	DELETE	`/api/admin/conversations/{cid}`	대화 삭제	FN-AUT-005
IF-ADM-017	GET	`/api/admin/files`	파일 메타 목록 조회	FN-DAT-002
IF-ADM-018	POST	`/api/admin/pmo/upload`	일괄 처리 대상 등록	-
IF-ADM-019	POST	`/api/admin/pmo/generate/{job}`	일괄 생성 실행	-
IF-ADM-020	GET	`/api/admin/pmo/download/{job}/{idx}`	일괄 생성 결과 다운로드	-

5. 주요 인터페이스 상세

5.1. IF-AUT-002 로그인

구분	항목	타입	필수	설명
요청	`uid`	문자열	Y	사번. 대소문자를 구분하지 않는다
요청	`password`	문자열	Y	비밀번호
응답	`uid`	문자열	Y	정규 표기 사번
	`name`	문자열	Y	성명
	세션 쿠키	헤더	Y	HttpOnly, SameSite, Secure 속성을 지정한다

오류 — 400 입력 누락, 401 인증 실패, 429 실패 누적 차단. 인증 실패 시 사번과 비밀번호 중 어느 것이 틀렸는지 구분하여 응답하지 않는다.

5.2. IF-SOP-004 SOP 저장

구분	항목	타입	필수	설명
요청	`schema`	객체	Y	산출물 본문
	`base_version`	정수	Y	편집 시작 시점의 버전
	`change_note`	문자열	N	변경 사유
응답	`version`	정수	Y	저장 후 버전
응답	`updated_at`	일시	Y	갱신 시각

오류 — 404 대상 없음 또는 가시 범위 밖, 409 기준 버전 불일치 또는 락 미보유, 422 본문 구조 불일치. 409 응답에는 현재 버전과 락 보유자를 포함하여 화면이 안내할 수 있게 한다.

5.3. IF-AGT-008 대화 1턴 실행

구분	항목	타입	필수	설명
요청	`messages`	배열	Y	표시용 대화 이력
요청	`schema`	객체	N	현재 편집 중인 산출물
응답	이벤트 스트림	스트림	Y	6장 규약을 따른다

동일 대화의 생성이 진행 중이면 새로 시작하지 않고 그 작업의 스트림에 연결한다. 응답은 즉시 시작되며 수행 완료까지 유지된다.

5.4. IF-AGT-005 원본 첨부

구분	항목	타입	필수	설명
요청	`file`	멀티파트	Y	허용 확장자로 한정한다. 확장자와 시그니처를 검증한다
응답	`name`	문자열	Y	정규화된 저장 파일명
응답	`sources`	배열	Y	갱신된 첨부 목록

오류 — 400 허용되지 않는 확장자 또는 안전하지 않은 파일명, 404 대화 없음 또는 소유자 불일치, 413 크기 초과.

6. 이벤트 스트림 규약

생성 진행 상황은 서버 전송 이벤트로 전달한다. 각 이벤트에 순번을 부여하여 재연결 시 처음부터 재생할 수 있도록 한다.

이벤트	주요 항목	설명
`text`	delta	응답 텍스트의 증분
`tool`	id, name, label, hint	Tool 실행 시작과 대상
`tool_result`	id, ok, summary	Tool 실행 결과 요약
`progress`	step, label	장시간 Tool의 단계 진행
`schema`	schema	산출물의 중간 상태
`done`	schema, stem	수행 완료와 최종 산출물
`error`	code, message	오류 코드와 사용자 안내 문구

텍스트와 Tool 이벤트는 발생 순서대로 전달한다.
연결 유지를 위한 주석 프레임을 주기적으로 전송한다.
재연결 시 해당 작업의 이벤트를 순번 순으로 처음부터 재생한 후 이어서 전달한다.
완료 후에도 일정 시간 버퍼를 유지하여 재연결을 허용한다.

7. 외부 서비스 연계

연계 대상	방식	인증	비고
LLM 추론 서비스	관리형 서비스 API	인스턴스 역할	VPC 엔드포인트를 경유한다. 호출 가능한 모델을 엔드포인트 정책으로 제한한다.
자산 저장소	오브젝트 스토리지 API	인스턴스 역할	지정 버킷에 대한 접근만 허용한다.
문서 변환 도구	로컬 프로세스 호출	-	인자를 배열로 전달하고 제한 시간을 설정한다.

사용자 입력으로 전달된 주소에 대한 서버 측 요청은 수행하지 않는다.

8. 작성 가이드

인터페이스 정의서는 기능정의서의 단위기능을 입력으로 하여 호출 규격을 확정한다. 각 인터페이스에 관련 기능ID를 연결하여 기능과 인터페이스 사이의 추적성을 확보한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적, 적용 범위, 식별 체계를 기술한다.	Y
공통 규약	- 프로토콜, 데이터 형식, 경로 및 메서드 규칙, 인증 방식을 기술한다. - 목록 조회 상한과 버전 관리 방침을 포함한다.	Y
공통 응답 및 오류	- 상태 코드별 의미와 적용 상황을 기술한다. - 오류 응답 형식을 기술한다. - 권한 없는 자원의 응답 코드 방침을 명시한다.	Y
인터페이스 목록	- 영역별로 ID, 메서드, 경로, 기능, 권한, 관련 기능ID를 기술한다. - 누락 없이 전체를 기술한다.	Y
주요 인터페이스 상세	- 요청과 응답의 항목별 타입, 필수 여부, 설명을 기술한다. - 발생 가능한 오류와 그 조건을 기술한다. - 복잡도가 높거나 상태 전이를 포함하는 인터페이스를 선정한다.	Y
이벤트 스트림	- 스트리밍 인터페이스가 있는 경우 이벤트 종류와 전달 규칙을 기술한다. - 재연결 규칙을 포함한다.	N
외부 서비스 연계	- 연계 대상, 방식, 인증 수단을 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

데이터베이스 정의서

1. 개요

본 문서는 시스템이 사용하는 데이터베이스의 테이블 구성, 컬럼 명세, 관계 및 무결성 규칙을 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문에서 사용하는 관계형 데이터베이스 전체에 적용된다. 파일 시스템 및 오브젝트 스토리지에 보관하는 자산은 데이터 파이프라인 설계서에서 정의한다.

1.2. 표기 규칙

표기	의미
PK	기본키
NN	NOT NULL
FK	외래키. 화살표 뒤에 참조 테이블과 삭제 정책을 표기한다.
UQ	유니크 제약
CK	체크 제약

2. 데이터베이스 구성

항목	내용
DBMS	PostgreSQL 15 이상
배치	애플리케이션과 동일 인스턴스의 컨테이너. 외부 포트를 개방하지 않는다.
문자 집합	UTF-8
스키마 관리	마이그레이션 도구로 버전 관리한다. 운영 환경에서 직접 변경하지 않는다.
확장 모듈	UUID 생성 및 유사 문자열 검색용 확장을 사용한다.
테이블 수	23

2.1. 명명 규칙

대상	규칙	예시
테이블	tb_{도메인}[_{하위}], 단수형 소문자	tb_sop, tb_sop_version
기본키	{도메인}_id	sop_id, conv_id
외래키	참조 테이블의 기본키명을 그대로 사용	node_id, uid
일시 컬럼	{동작}_at, timestamptz	created_at, updated_at
여부 컬럼	is_{상태}, boolean	is_active, is_admin
인덱스	idx_{약어}_{대상}	idx_sop_node
유니크 제약	uq_{약어}_{대상}	uq_sop_node_company

3. 테이블 목록

영역	테이블	논리명	용도
조직 및 권한	`tb_org_node`	조직 노드	회사와 부서의 2단 계층
	`tb_app_user`	계정	사번 기반 사용자
	`tb_role`	역할	조회자·실무자·팀장·관리자
	`tb_action`	권한 코드	단위 행위 코드
	`tb_role_perm`	역할 권한	역할과 행위의 연결
	`tb_role_grant`	권한 부여	사용자·역할·범위의 3자 결합
체계도 및 SOP	`tb_process_node`	체계도 노드	Lv1부터 Lv4까지의 업무 분류
	`tb_process_node_company`	노드 적용 회사	노드가 적용되는 회사 매핑
	`tb_process_revision`	체계도 개정	개정 단위
	`tb_process_revision_item`	개정 항목	노드별 변경 전후 상태
	`tb_sop`	SOP	표준작업지시서 본문
	`tb_sop_lock`	편집 락	동시 편집 제어
	`tb_sop_version`	SOP 버전	저장 시점 스냅샷
대화	`tb_conversation`	대화	에이전트 대화 단위
	`tb_conversation_message`	대화 메시지	표시용 메시지, 추가 전용
	`tb_conversation_state`	대화 작업 상태	추론 이력 및 편집 중 스키마
파일	`tb_file`	파일 메타	자산 메타데이터. 실물은 오브젝트 스토리지
게시판	`tb_board_post`	게시글	문의·요청·공지
게시판	`tb_board_comment`	댓글	게시글 답변
운영	`tb_user_quota`	사용 한도	사용자별 월 한도
	`tb_usage_counter`	월 누적 사용량	기간별 누적값
	`tb_usage_log`	사용량 로그	호출 단위 상세
	`tb_audit_log`	감사 로그	보안 및 변경 이벤트

4. 관계 설계

4.1. 관계도

tb_org_node --(자기참조: 회사 -> 부서)
     +-- tb_app_user.company_id / .dept_id
     +-- tb_process_node_company.company_id
     +-- tb_sop.company_id

tb_process_node --(자기참조: Lv1 -> Lv4)
     +-- tb_process_node_company   적용 회사. 없으면 부모에서 상속
     +-- tb_role_grant.scope_node_id   가시 범위. Lv1~Lv3 부여, 하위 상속
     +-- tb_sop.node_id   SET NULL — 노드가 폐지되어도 SOP 는 보존

tb_sop --+-- tb_sop_lock      1 : 0..1
         +-- tb_sop_version   1 : N
         +-- tb_file          활동 사진
         +-- tb_conversation.sop_id   SET NULL

tb_conversation --+-- tb_conversation_message   1 : N, CASCADE
                  +-- tb_conversation_state     1 : 1, CASCADE
                  +-- tb_file                   CASCADE

tb_board_post --+-- tb_board_comment   1 : N, CASCADE
                +-- tb_file            CASCADE

tb_app_user --+-- tb_role_grant · tb_user_quota · tb_usage_counter · tb_usage_log
              +-- 각 테이블의 작성자 컬럼   RESTRICT

4.2. 참조 무결성 정책

삭제 정책	적용 대상	근거
RESTRICT	계정 참조, 조직 참조, 상위 노드 참조	참조되는 행은 삭제하지 않는다. 계정과 조직은 비활성 처리로 대체한다.
CASCADE	대화 하위, 게시글 하위, SOP 하위	상위가 사라지면 존재 의미가 없는 종속 데이터
SET NULL	SOP의 체계도 노드 참조, 대화의 SOP 참조	체계도가 개편되어 노드가 폐지되어도 SOP는 보존한다. 연결만 해제하고 본문은 유지하여 자산 유실을 방지한다.

5. 테이블 상세

5.1. 조직 및 권한

tb_org_node — 조직 노드

컬럼	논리명	타입	제약	설명
`org_node_id`	조직노드ID	uuid	PK
`parent_id`	상위조직ID	uuid	FK → tb_org_node RESTRICT	회사는 NULL
`node_type`	조직유형	varchar(10)	NN, CK	회사 또는 부서
`org_code`	조직코드	varchar(20)	NN, UQ	인사 데이터의 코드. 재적재 식별 키
`node_name`	조직명	varchar(100)	NN
`is_active`	사용여부	boolean	NN	폐지 조직은 false
`created_at`	생성일시	timestamptz	NN

tb_app_user — 계정

컬럼	논리명	타입	제약	설명
`uid`	사번	varchar(20)	PK	사용자 식별자
`user_name`	성명	varchar(50)	NN
`pw_salt`	솔트	varchar(64)	NN	계정별 난수
`pw_hash`	비밀번호해시	varchar(128)	NN	솔트 적용 단방향 해시
`company_id`	회사ID	uuid	NN, FK → tb_org_node RESTRICT	회사 가시성 판정 기준
`dept_id`	부서ID	uuid	FK → tb_org_node RESTRICT
`position`	직책	varchar(30)		외부 인사 코드. 마스터를 두지 않는다
`job_title`	직무	varchar(30)		외부 인사 코드
`is_active`	재직여부	boolean	NN	퇴사자는 false. 계정 행은 삭제하지 않는다
`is_admin`	관리자	boolean	NN	관리자 판정의 기준
`created_at`	생성일시	timestamptz	NN

관리자 승격과 회수는 감사 로그에 기록한다. 자기 자신은 회수할 수 없으며, 관리자가 한 명인 경우에도 회수할 수 없다.

tb_role · tb_action · tb_role_perm

테이블	컬럼	타입	제약	설명
`tb_role`	`role_id`	varchar(20)	PK	역할 코드
`tb_role`	`role_name`	varchar(50)	NN	역할명
`tb_action`	`action_code`	varchar(30)	PK	단위 행위 코드
`tb_action`	`action_name`	varchar(50)	NN	행위명
`tb_role_perm`	`role_id`	varchar(20)	PK, FK CASCADE
`tb_role_perm`	`action_code`	varchar(30)	PK, FK RESTRICT

tb_role_grant — 권한 부여

컬럼	논리명	타입	제약	설명
`grant_id`	부여ID	uuid	PK
`uid`	사번	varchar(20)	NN, FK RESTRICT
`role_id`	역할ID	varchar(20)	NN, FK RESTRICT
`scope_node_id`	범위노드ID	uuid	NN, FK → tb_process_node CASCADE	체계도 노드. 하위로 상속
`granted_by`	부여자	varchar(20)	FK
`created_at`	생성일시	timestamptz	NN

UQ(uid, role_id, scope_node_id) — 동일 권한의 중복 부여를 금지한다. CK — 범위 노드의 레벨은 3 이하로 제한한다. 역할과 범위를 쌍으로 묶으므로 열람 권한과 편집 권한을 서로 다른 범위로 부여할 수 있다.

5.2. 체계도 및 SOP

tb_process_node — 체계도 노드

컬럼	논리명	타입	제약	설명
`node_id`	노드ID	uuid	PK
`parent_id`	상위노드ID	uuid	FK → tb_process_node RESTRICT	루트는 NULL
`node_level`	레벨	integer	NN, CK 1~4
`node_code`	노드코드	varchar(50)	NN, UQ	계층 경로를 나타낸다
`node_name`	노드명	varchar(200)	NN
`owner_dept_id`	주관부서	uuid	FK RESTRICT	검색 및 표시 용도
`sort_order`	정렬순서	integer	NN
`is_active`	사용여부	boolean	NN	폐지 노드는 false
`created_at`	생성일시	timestamptz	NN
`updated_at`	수정일시	timestamptz	NN	트리거로 갱신

하위 노드가 있으면 삭제를 제한한다. 노드 이동 시 하위 코드를 재계산하므로 노드코드 유니크 제약은 지연 검사로 설정하여 재계산 중의 일시적 중복을 허용한다.

tb_process_node_company — 노드 적용 회사

컬럼	타입	제약	설명
`node_id`	uuid	PK, FK CASCADE
`company_id`	uuid	PK, FK RESTRICT	조직 유형이 회사인 노드

매핑 상태	유효 적용 회사
매핑 행이 있는 경우	해당 노드부터 하위까지 나열된 회사에만 적용한다.
매핑 행이 없는 경우	부모의 유효 범위를 상속한다.
루트까지 없는 경우	전사 공통으로 간주한다.

tb_sop — SOP

컬럼	논리명	타입	제약	설명
`sop_id`	SOP ID	uuid	PK
`node_id`	노드ID	uuid	FK → tb_process_node SET NULL	Lv4 노드. NULL 허용 — 노드 폐지 시 보존
`company_id`	회사ID	uuid	NN, FK RESTRICT
`sop_name`	SOP명	varchar(200)	NN
`sop_schema`	SOP본문	jsonb	NN	기본정보, 작업 단위, 용어로 구성
`status`	상태	varchar(10)	NN, CK	8장 코드 정의 참조
`version`	버전	integer	NN	저장 시마다 증가
`author_uid`	작성자	varchar(20)	NN, FK RESTRICT	로그인 사용자로 기록한다. 원본 문서의 값을 사용하지 않는다
`created_at`	생성일시	timestamptz	NN
`updated_at`	수정일시	timestamptz	NN	트리거로 갱신

UQ(node_id, company_id) — Lv4 노드와 회사의 조합은 유일하다.

tb_sop_lock · tb_sop_version

테이블	컬럼	타입	제약	설명
`tb_sop_lock`	`sop_id`	uuid	PK, FK CASCADE
	`holder_uid`	varchar(20)	NN, FK RESTRICT	락 보유자
	`acquired_at`	timestamptz	NN
	`expires_at`	timestamptz	NN	만료 시각. 경과 시 자동 해제 대상
`tb_sop_version`	`sop_id`	uuid	PK, FK CASCADE
	`version`	integer	PK
	`sop_schema`	jsonb	NN	해당 시점 전문
	`change_note`	varchar(500)		변경 사유
	`created_by` / `created_at`	varchar(20) / timestamptz	NN

tb_process_revision · tb_process_revision_item

테이블	컬럼	타입	제약	설명
`tb_process_revision`	`revision_id`	uuid	PK
	`changed_by`	varchar(20)	NN, FK RESTRICT
	`change_note`	text		변경 사유
	`reverted_from`	uuid	FK RESTRICT	되돌린 대상 개정
	`created_at`	timestamptz	NN
`tb_process_revision_item`	`revision_id`	uuid	PK, FK CASCADE
	`node_id`	uuid	PK	외래키를 설정하지 않는다. 폐지된 노드의 이력도 보존한다
	`op`	varchar(10)	NN, CK	생성·수정·이동·삭제
	`before_state`	jsonb		변경 전 상태. 생성은 NULL
	`after_state`	jsonb		변경 후 상태. 삭제는 NULL

5.3. 대화

테이블	컬럼	타입	제약	설명
`tb_conversation`	`conv_id`	uuid	PK
	`uid`	varchar(20)	NN, FK RESTRICT	소유자. 본인만 열람한다
	`title`	varchar(200)		첫 메시지로 자동 생성
	`node_id`	uuid	FK SET NULL	체계도에서 시작한 경우의 대상 노드
	`sop_id`	uuid	FK SET NULL	이 대화가 생성한 SOP
	`status`	varchar(10)	NN	진행중 또는 완료
	`created_at`	timestamptz	NN
	`updated_at`	timestamptz	NN	트리거로 갱신
	`deleted_at`	timestamptz		NULL이면 유효한 대화이다
	`deleted_by`	varchar(20)	FK RESTRICT	본인 또는 관리자
`tb_conversation_message`	`msg_id`	bigserial	PK
	`conv_id`	uuid	NN, FK CASCADE
	`seq`	integer	NN, UQ	대화 내 순서. 대화ID와 함께 유일하다
	`role`	varchar(10)	NN, CK	사용자 또는 에이전트
	`content`	jsonb	NN	텍스트, 수행 표시, 첨부 참조
	`created_at`	timestamptz	NN	추가 전용. 수정하지 않는다
`tb_conversation_state`	`conv_id`	uuid	PK, FK CASCADE
	`llm_history`	jsonb	NN	추론 이력. 길이 증가 시 압축 대상
	`work_schema`	jsonb		저장 전 편집 중인 산출물
	`reference`	text		참고 자료
	`updated_at`	timestamptz	NN	트리거로 갱신

5.4. 파일

컬럼	논리명	타입	제약	설명
`file_id`	파일ID	uuid	PK
`conv_id`	대화ID	uuid	FK CASCADE	업로드 원본
`sop_id`	SOP ID	uuid	FK CASCADE	활동 사진
`post_id`	게시글ID	uuid	FK CASCADE	게시판 첨부
`file_type`	파일구분	varchar(20)	NN, CK	8장 코드 정의 참조
`file_name`	파일명	varchar(255)	NN	표시용 원래 이름
`file_ext`	확장자	varchar(10)
`byte_size`	크기	bigint
`sha256`	체크섬	varchar(64)		동일 파일 재업로드 식별
`s3_key`	자산 키	varchar(500)	NN	오브젝트 스토리지 경로
`parsed`	파싱결과	jsonb		원본 문서에 한함. 재파싱 비용 회피
`uploaded_by`	업로더	varchar(20)	NN, FK RESTRICT
`uploaded_at`	업로드일시	timestamptz	NN

CK — 대화ID, SOP ID, 게시글ID 중 정확히 하나만 값을 가진다. 소유자가 둘 이상이거나 없는 파일 행을 허용하지 않는다.

5.5. 게시판

테이블	컬럼	타입	제약	설명
`tb_board_post`	`post_id`	uuid	PK
	`board_kind`	varchar(10)	NN, CK	게시판 구분
	`post_no`	integer	NN, UQ	표시 번호. 구분과 함께 유일하다
	`title`	varchar(200)	NN
	`body`	text
	`author_uid`	varchar(20)	NN, FK RESTRICT
	`author_company`	varchar(100)		작성 시점의 소속 표기 보존
	`status`	varchar(10)	NN, CK	8장 코드 정의 참조
	`result_link`	text		완료 시 결과 주소
	`extra`	jsonb		게시판 종류별 부가 항목
	`created_at` / `updated_at`	timestamptz	NN
`tb_board_comment`	`comment_id`	bigserial	PK
	`post_id`	uuid	NN, FK CASCADE
	`author_uid`	varchar(20)	NN, FK RESTRICT
	`body`	text	NN
	`is_admin`	boolean	NN	관리자 답변 여부

5.6. 운영

테이블	컬럼	타입	제약	설명
`tb_user_quota`	`uid`	varchar(20)	PK, FK CASCADE
	`monthly_usd_cap`	numeric(10,2)		NULL이면 무제한
	`monthly_tok_cap`	bigint		NULL이면 무제한
`tb_usage_counter`	`uid`	varchar(20)	PK, FK CASCADE
	`period`	char(7)	PK	연월
	`used_usd`	numeric(12,4)	NN	누적 비용
	`used_tokens`	bigint	NN	누적 토큰
	`updated_at`	timestamptz	NN
`tb_usage_log`	`usage_id`	bigserial	PK
	`uid`	varchar(20)	NN, FK RESTRICT
	`called_at`	timestamptz	NN
	`model_id`	varchar(80)	NN	호출 모델 식별자
	`input_tokens` / `output_tokens`	integer	NN
	`cost_usd`	numeric(10,4)	NN
	`conv_id`	uuid	FK SET NULL
	`sop_id`	uuid	FK SET NULL
`tb_audit_log`	`audit_id`	bigserial	PK
	`uid`	varchar(20)	NN	외래키를 설정하지 않는다. 계정이 변경되어도 기록은 보존한다
	`action_type`	varchar(30)	NN, CK	8장 코드 정의 참조
	`target_kind`	varchar(20)		대상 종류
	`target_id`	varchar(100)		대상 식별자
	`detail`	jsonb		변경 전후 등 상세

6. 인덱스

테이블	인덱스명	대상 컬럼	유형	용도
`tb_process_node`	`idx_pnode_parent`	parent_id	B-Tree	트리 탐색
	`idx_pnode_name_trgm`	node_name	GIN	키워드 검색
	`uq_pnode_code`	node_code	Unique	계층코드 중복 방지. 지연 검사
	`idx_pnode_dept`	owner_dept_id	B-Tree	주관부서 검색
`tb_process_node_company`	`idx_pnc_company`	company_id	B-Tree	회사별 적용 노드 조회
`tb_process_revision`	`idx_prev_date`	created_at	B-Tree	최근 개정 목록
`tb_process_revision_item`	`idx_previtem_node`	node_id	B-Tree	노드별 변경 이력
`tb_sop`	`uq_sop_node_company`	node_id, company_id	Unique	Lv4 × 회사 1 대 1
	`idx_sop_name_trgm`	sop_name	GIN	키워드 검색
	`idx_sop_company`	company_id	B-Tree	회사별 조회
	`idx_sop_node`	node_id	B-Tree	체계도 연결 조회
`tb_org_node`	`uq_org_code`	org_code	Unique	인사 코드 기준 재적재
`tb_app_user`	`idx_user_company`	company_id	B-Tree	회사별 사용자 조회
`tb_role_grant`	`idx_grant_uid`	uid	B-Tree	사용자 권한 조회
	`idx_grant_scope`	scope_node_id	B-Tree	범위 판정
	`uq_grant`	uid, role_id, scope_node_id	Unique	중복 부여 방지
`tb_sop_lock`	`idx_lock_expires`	expires_at	B-Tree	만료 락 정리
`tb_conversation`	`idx_conv_uid_updated`	uid, updated_at	B-Tree	사용자 대화 목록
`tb_conversation_message`	`uq_conv_msg_seq`	conv_id, seq	Unique	순서 보장
`tb_file`	`idx_file_conv`	conv_id	B-Tree	대화 첨부 조회
	`idx_file_sop`	sop_id	B-Tree	SOP 사진 조회
	`idx_file_sha`	sha256	B-Tree	중복 파일 식별
`tb_board_post`	`uq_board_no`	board_kind, post_no	Unique	번호 중복 방지
`tb_board_post`	`idx_board_author`	author_uid	B-Tree	작성자별 조회
`tb_usage_log`	`idx_usage_uid_date`	uid, called_at	B-Tree	사용량 상세 조회
`tb_audit_log`	`idx_audit_date`	logged_at	B-Tree	기간 조회
`tb_audit_log`	`idx_audit_target`	target_kind, target_id	B-Tree	대상별 이력

7. 무결성 규칙

7.1. 공통 규칙

수정일시 컬럼은 트리거로 자동 갱신한다.
기본키는 식별자 생성 함수로 생성하며 외부에서 주입하지 않는다.
계정과 조직은 삭제하지 않고 사용 여부 컬럼으로 비활성화한다.
감사 로그는 추가 전용으로 운용하며 수정과 삭제를 허용하지 않는다.

7.2. 트리거로 보장하는 규칙

외래키로 표현할 수 없고 다른 행을 함께 확인해야 하는 규칙은 트리거로 보장한다.

번호	규칙	위반 시 영향
1	자식 노드의 명시 적용 회사는 부모의 유효 적용 회사에 포함되어야 한다.	자식만 보이고 부모가 보이지 않아 트리가 끊긴다.
2	SOP의 회사는 해당 노드의 유효 적용 회사 중 하나여야 한다.	적용 대상이 아닌 회사가 노드에 SOP를 연결할 수 있다.
3	SOP가 연결되는 노드의 레벨은 4여야 한다.	중간 계층 노드에 SOP가 연결된다.
4	회사 참조 컬럼이 가리키는 조직은 유형이 회사여야 한다.	부서에 SOP가 귀속된다.
5	계정의 부서는 유형이 부서이고 그 상위가 소속 회사여야 한다.	소속 회사와 부서가 불일치한다.
6	권한 부여 범위 노드의 레벨은 3 이하여야 한다.	단위업무 단건 구독이 생겨 범위 관리 단위가 과도하게 세분화된다.

7.3. 가시 범위 판정

조회 가능한 노드는 다음과 같이 판정한다.

가시 노드 = (부여 범위 U 그 하위 전체) U (부여 범위의 조상 경로)
                                          + 트리 표시 목적. 형제 노드는 포함하지 않는다

Lv1부터 Lv3까지는 SOP가 연결되지 않으므로 조상 경로를 표시하여도 내용이 노출되지 않는다. SOP의 기본 가시 범위는 소속 회사로 한정하며, 회사를 가로지르는 조회는 별도 권한으로 부여한다.

8. 코드 정의

대상	컬럼	허용 값
SOP 상태	`tb_sop.status`	작성중 · 검증중 · 반려 · 완료
대화 상태	`tb_conversation.status`	진행중 · 완료
조직 유형	`tb_org_node.node_type`	회사 · 부서
노드 레벨	`tb_process_node.node_level`	1 · 2 · 3 · 4
개정 작업	`tb_process_revision_item.op`	생성 · 수정 · 이동 · 삭제
메시지 역할	`tb_conversation_message.role`	사용자 · 에이전트
파일 구분	`tb_file.file_type`	원본 · 활동사진 · 첨부
게시판 구분	`tb_board_post.board_kind`	문의 · 공지 · 요청
게시글 상태	`tb_board_post.status`	접수 · 완료 · 취소
감사 행위	`tb_audit_log.action_type`	등록 · 수정 · 삭제 · 락 · 락해제 · 권한부여 · 로그인

SOP 상태를 추가하거나 삭제하는 경우 데이터베이스 체크 제약과 화면 표시 규칙을 함께 변경한다. 한쪽만 변경하면 저장은 되고 표시가 누락되거나 그 반대가 된다.

9. 작성 가이드

데이터베이스 정의서는 기능정의서의 관련 테이블 항목을 입력으로 하여 물리 모델을 확정한다. 외래키로 표현할 수 없는 업무 규칙은 트리거 규칙으로 분리하여 명시한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적, 적용 범위, 표기 규칙을 기술한다.	Y
데이터베이스 구성	- DBMS 종류와 버전, 배치 방식, 문자 집합, 스키마 관리 방법을 기술한다. - 명명 규칙을 대상별로 기술한다.	Y
테이블 목록	- 영역별로 테이블의 물리명, 논리명, 용도를 기술한다.	Y
관계 설계	- 테이블 간 관계를 도식으로 기술한다. - 삭제 정책별 적용 대상과 선택 근거를 기술한다.	Y
테이블 상세	- 테이블별로 컬럼명, 논리명, 타입, 제약, 설명을 기술한다. - 유니크 및 체크 제약은 표 아래에 별도로 기술한다.	Y
인덱스	- 인덱스명, 대상 컬럼, 유형, 용도를 기술한다. - 검색 용도의 인덱스는 사용하는 기능을 함께 기술한다.	Y
무결성 규칙	- 공통 규칙과 트리거로 보장하는 규칙을 구분하여 기술한다. - 규칙 위반 시의 영향을 함께 기술하여 제약의 필요성을 명확히 한다.	Y
코드 정의	- 체크 제약으로 제한하는 코드성 컬럼의 허용 값을 기술한다. - 값 변경 시 함께 수정할 대상을 명시한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

에이전트 설계서

1. 개요

본 문서는 SOP 생성·수정을 수행하는 에이전트의 구성, 계층 구조, 프롬프트, Tool, 대화 처리 방식을 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 SKMR_현업 주도 SOP체계 구축 지원 및 자문에 포함된 에이전트 전체에 적용된다. 에이전트가 호출하는 문서 변환 파이프라인의 내부 처리는 데이터 파이프라인 설계서에서 정의하며, 보안 통제는 보안 정의서에서 정의한다.

1.2. 설계 전제

에이전트는 사용자와의 대화를 통해 동작하며, 무인 자동 응답을 수행하지 않는다.
모든 수행 결과는 사용자가 화면에서 확인하고 반영 여부를 결정한다.
산출물의 형식은 고정된 표준 양식을 따르므로 결과의 형식 적합성은 기계적으로 검증한다.
지식베이스 검색을 수행하지 않으며, 근거는 사용자가 첨부한 문서로 한정한다.

2. 에이전트 구성

2.1. 에이전트 식별

에이전트 ID	명칭	유형	역할
AGT-SOP-TA-001	SOP 작성 에이전트	작업수행형	사용자 지시와 첨부 문서를 근거로 SOP를 생성하고 수정한다.

본 시스템은 단일 에이전트 구조로 구성한다. 에이전트 간 통신 및 오케스트레이터 계층은 구성하지 않는다. 에이전트를 추가하는 경우 상위 라우팅 설계를 별도로 정의한다.

2.2. 수행 작업 분류

작업 분류	사용자 요청 예	수행 방식
신규 생성	문서를 첨부하고 SOP 작성을 요청	문서 변환 파이프라인을 호출하여 초안을 생성한다.
불러오기	작성된 표준 양식 파일을 첨부	변환 없이 스키마로 적재한다.
지시 기반 생성	첨부 없이 업무 설명만 제시	제시된 설명으로 초안을 생성하고, 확정되지 않은 값은 검토 표식으로 남긴다.
확장	추가 문서를 첨부하여 통합 요청	기존 SOP에 해당 문서의 작업 단위를 추가한다.
편집	특정 항목의 수정·추가·삭제 요청	현재 스키마를 확인한 후 해당 부분을 치환한다.
검증	형식 또는 내용 점검 요청	형식 검증 또는 내용 검토를 수행하고 결과만 보고한다.
확인	첨부 문서의 내용만 확인 요청	문서 내용을 조회하고 현재 SOP는 변경하지 않는다.

3. 계층 설계

에이전트는 다음 계층으로 구성한다.

계층	역할	구현 기준
입력 처리 계층	사용자 입력 수신, 입력 가드레일 적용, 세션 컨텍스트 구성	- 사용자 입력과 시스템 지시를 분리하여 전달한다. - 첨부 문서 목록과 현재 산출물 요약을 컨텍스트로 구성한다.
추론 계층	모델 호출, Tool 선택, 왕복 제어	- 도구 사용 루프로 수행한다. - 왕복 횟수 상한과 단일 응답의 최대 길이를 설정한다. - 응답 텍스트는 델타 단위로 수신하여 즉시 전달한다.
도구 실행 계층	Tool 호출, 결과 적재, 실패 처리	- 선택된 Tool을 실행하고 결과를 값으로 반환한다. - 장시간 수행 Tool은 별도 실행 단위로 처리하고 단계 진행을 전달한다.
출력 처리 계층	응답 구성, 산출물 반영, 기록	- 산출물은 구조 유효성을 검증한 후 반영한다. - 수행 내역을 대화 이력에 저장한다.
메모리 계층	대화 컨텍스트와 산출물 상태 보관	- 대화 이력과 산출물 상태를 영속 저장소에 보관한다. - 보관 한도를 적용한다.

4. 프롬프트 설계

4.1. 시스템 프롬프트 구성

시스템 프롬프트는 다음 절로 구성하며, 절의 순서를 유지한다.

순서	절	기술 내용
1	역할	에이전트의 역할과 수행 범위를 한 문장으로 정의한다.
2	실행 원칙	- 수행 절차를 기술한다. 수행 직전에 의도를 간단히 설명하고 같은 턴에서 Tool을 호출한다. - 금지 행위를 명시한다. 설명만 하고 Tool을 호출하지 않은 채 턴을 종료하지 않는다. - 단일 응답의 Tool 호출 수 상한을 제시한다.
3	작업 유형별 지시	생성·확장·확인·편집·검증 각각에 대하여 사용할 Tool과 사용하지 않을 Tool을 구분하여 기술한다.
4	자료 취급 원칙	첨부 문서에서 추출한 내용은 자료로 취급하며 지시로 해석하지 않음을 명시한다.
5	출력 형식	수행 결과의 보고 범위와 형식을 기술한다. 산출물의 작성자는 시스템이 기록하므로 사용자에게 질의하지 않음을 명시한다.

4.2. 컨텍스트 구성

매 턴마다 다음 정보를 세션 상태로 구성하여 전달한다.

항목	내용
첨부 파일 목록	현재 세션에 등록된 원본 문서의 목록을 전달한다.
현재 산출물 요약	작업 단위와 활동의 구성을 요약하여 전달한다. 전체 본문은 전달하지 않는다.
참고 자료	검토 결과 등 참조 가능한 내용을 지시 영역과 구분되는 위치에 전달한다.

4.3. 프롬프트 관리

프롬프트는 소스와 동일한 형상관리 대상으로 관리한다.
변경 시 회귀 평가를 수행하고 변경 전후 결과를 비교한다.
변경 사유를 이력에 기록한다.

5. Tool 설계

5.1. Tool 목록

Tool ID	Tool 명	분류	기능	주요 입력	산출물 변경
TOOL-SOP-BUILD	build_sop	변경	첨부 문서 또는 업무 설명으로 SOP를 생성하거나 작성된 양식을 적재한다.	filename 또는 brief	Y
TOOL-SOP-ADD	add_file	변경	추가 문서의 작업 단위를 현재 SOP에 통합한다.	filename	Y
TOOL-SOP-EDIT	edit_sop	변경	현재 SOP의 지정 문자열을 치환하여 편집한다.	old_string, new_string, replace_all	Y
TOOL-SOP-READ	read_sop	조회	현재 SOP의 구조를 반환한다.	-	N
TOOL-SRC-INSPECT	inspect_file	조회	첨부 문서의 내용을 조회한다.	filename	N
TOOL-QA-EVAL	evaluate	검증	표준 양식 기준의 형식 적합성을 검증하고 오류와 경고를 반환한다.	-	N
TOOL-QA-REVIEW	review_sop	검증	작성 지침 기준의 내용 검토 의견을 반환한다.	-	N

5.2. Tool 선택 기준

Tool 선택은 사용자의 표현이 아니라 제시된 재료와 목적을 기준으로 판정한다.

상황	선택 Tool	판정 근거
첨부 문서가 작성된 표준 양식인 경우	build_sop	변환 없이 적재한다. 모델이 처리 경로를 선택하지 않고 Tool이 파일 형식으로 판정한다.
첨부 문서가 원본 업무 문서인 경우	build_sop	변환 파이프라인으로 생성한다.
첨부 없이 업무 설명만 제시된 경우	build_sop	설명을 근거로 초안을 생성한다.
기존 SOP에 다른 문서를 합치는 경우	add_file	통합 결과의 중복 여부는 사용자에게 확인한다.
문서 내용만 확인하려는 경우	inspect_file	현재 SOP를 변경하지 않는다. 통합 목적과 구분한다.
항목을 수정·추가·삭제하는 경우	read_sop 후 edit_sop	현재 구조를 확인한 후 치환한다.
형식 또는 누락을 점검하는 경우	evaluate	기계 검증 결과를 보고한다.
내용 품질을 검토하는 경우	review_sop	검토 의견만 제시하고 반영 여부는 사용자가 결정한다.

5.3. Tool 공통 구현 기준

모든 Tool은 입력 스키마와 필수 항목을 명시한다.
Tool은 내부 상태를 보유하지 않으며 상태는 호출 시 전달한다.
변경 Tool은 입력 파라미터를 스키마 기준으로 재검증하고, 결과의 구조 유효성을 확인한 후 반영한다.
실행 실패는 대화를 중단시키지 않고 사유를 값으로 반환한다.
장시간 수행 Tool은 단계별 진행 상황을 전달한다.

6. 대화 처리 설계

6.1. 턴 처리 흐름

순서	처리	내용
1	요청 수신	사용자 지시와 현재 산출물 상태를 수신한다.
2	권한 확인	대화의 소유 여부를 확인한다. 소유자가 아니면 처리하지 않는다.
3	작업 등록	생성 작업을 서버의 실행 단위로 등록한다. 동일 대화의 작업이 진행 중이면 그 작업에 연결한다.
4	추론 수행	시스템 프롬프트, 컨텍스트, Tool 목록을 전달하여 모델을 호출한다.
5	Tool 실행	Tool 호출이 반환되면 실행하고 결과를 전달한 뒤 4단계로 복귀한다.
6	완료 처리	최종 산출물과 대화 이력을 저장하고 완료를 통지한다.

6.2. 진행 이벤트

수행 과정은 다음 이벤트로 전달하며, 각 이벤트에 일련번호를 부여한다.

이벤트	내용
text	응답 텍스트의 증분
tool	Tool 실행 시작과 대상
tool_result	Tool 실행 결과
progress	장시간 수행 Tool의 단계 진행
schema	산출물의 중간 상태
done	수행 완료와 최종 산출물
error	오류 코드와 사용자 안내 문구

텍스트와 Tool 이벤트는 발생 순서대로 전달하여 수행 맥락이 유지되도록 한다.

6.3. 재연결 및 복원

생성 작업은 서버가 소유하며 화면 연결이 끊겨도 계속 수행한다.
재연결 시 해당 작업의 이벤트를 일련번호 순으로 처음부터 재생한 후 이어서 전달한다.
완료 후에도 일정 시간 동안 이벤트를 보관하여 재연결을 허용한다.
동일 대화에 대한 중복 실행을 허용하지 않는다.
대화를 전환하면 이전 대화의 전달을 중단하고, 서버의 수행은 계속한다.

7. 메모리 설계

메모리 유형	저장 대상	저장소	보관 정책
단기 메모리	대화 이력, 수행 타임라인, 산출물 상태	관계형 데이터베이스	사용자별 보관 한도를 적용하고, 초과분은 오래된 것부터 목록에서 제외한다.
세션 자산	첨부 원본, 변환 산출물, 추출 이미지	자산 저장소	대화 단위로 보관하며, 대화 삭제 시 함께 정리한다.
장기 메모리	해당 없음	-	세션 간 지속되는 사용자 선호 정보를 보관하지 않는다.
에피소드 메모리	해당 없음	-	과거 수행 경험을 검색 대상으로 보관하지 않는다.

대화 이력은 사용자 식별자에 귀속하며 타인이 조회할 수 없다.
대화를 삭제하면 연결된 세션 자산을 함께 제거한다.
보관 한도로 목록에서 제외된 대화는 제외 사유를 기록한다.

8. 오류 처리 설계

발생 구간	오류 유형	처리 방식
모델 호출	제한 시간 초과, 인증 실패, 출력 절단, 토큰 한도 초과	유형별로 분류하여 사용자 안내 문구로 변환한다. 원문을 그대로 노출하지 않는다.
Tool 실행	입력 검증 실패, 처리 실패, 대상 없음	사유를 값으로 반환하고 대화를 계속한다. 모델이 다음 조치를 판단한다.
산출물 반영	구조 유효성 실패	반영하지 않고 사유를 반환한다. 직전 상태를 유지한다.
작업 수행	작업 중단, 전달 단절	수행은 계속하고 재연결 시 이어서 전달한다.
권한	소유자 불일치	자원의 존재 여부를 노출하지 않는 응답으로 처리한다.
사용 한도	한도 초과	수행 전에 차단하고 한도 정보와 함께 안내한다.

9. 평가 설계

9.1. 평가 항목

평가 항목	정의	측정 방법
형식 적합성	산출물이 표준 양식의 구조와 필수 항목을 충족하는 정도	형식 검증 도구의 오류 및 경고 건수
필수 항목 충족률	작업 단위와 활동의 필수 항목이 채워진 비율	검증 결과의 미기재 항목 비율
Tool 선택 정확도	요청 유형에 대응하는 Tool이 선택된 비율	수행 로그의 Tool 선택 이력 분석
수행 완료율	사용자 요청이 추가 지시 없이 완료된 비율	대화 단위 수행 결과 집계
응답 지연	요청부터 최초 응답 및 완료까지의 소요 시간	구간별 소요 시간 측정

9.2. 회귀 평가 절차

고정된 입력 문서 집합을 평가 대상으로 지정하고 형상관리 대상에 포함한다.
변경 전 시점의 형식 적합성 결과를 기준선으로 기록한다.
프롬프트 또는 변환 파이프라인을 변경한 경우 동일한 입력으로 재수행하여 기준선과 비교한다.
기준선 대비 악화된 항목이 있으면 원인을 확인한 후 반영 여부를 결정한다.
평가 결과는 변경 이력과 함께 보관한다.

본 시스템은 정답 산출물을 보유한 평가 집합을 구성하지 않는다. 문서를 SOP로 변환하는 작업은 단일 정답이 존재하지 않으며, 산출물의 형식이 고정되어 있어 결정론적 형식 검증으로 품질 변화를 측정할 수 있다.

10. 작성 가이드

에이전트 설계서는 기능정의서와 개발표준 정의서를 입력으로 하여 에이전트의 구성과 동작을 확정한다. 프롬프트와 Tool은 변경 빈도가 높으므로 설계 단계에서 관리 절차를 함께 정의한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적과 적용 범위, 설계 전제를 기술한다.	Y
에이전트 구성	- 에이전트 ID, 명칭, 유형, 역할을 기술한다. - 단일 에이전트 구조인 경우 그 사실과 확장 시 절차를 함께 기술한다. - 수행 작업을 분류하고 작업별 수행 방식을 기술한다.	Y
계층 설계	- 입력·추론·도구·출력·메모리 계층의 역할과 구현 기준을 기술한다.	Y
프롬프트 설계	- 시스템 프롬프트의 절 구성과 순서를 기술한다. - 매 턴 전달할 컨텍스트 항목을 기술한다. - 프롬프트 관리 절차를 기술한다.	Y
Tool 설계	- Tool 목록을 ID, 명칭, 분류, 기능, 입력, 산출물 변경 여부로 기술한다. - Tool 선택 기준을 상황별로 기술한다. - 공통 구현 기준을 기술한다.	Y
대화 처리 설계	- 턴 처리 흐름을 순서대로 기술한다. - 진행 이벤트의 종류와 전달 규칙을 기술한다. - 재연결 및 복원 규칙을 기술한다.	Y
메모리 설계	- 메모리 유형별 저장 대상, 저장소, 보관 정책을 기술한다. - 사용하지 않는 유형은 해당 없음으로 명시한다.	Y
오류 처리 설계	- 발생 구간별 오류 유형과 처리 방식을 기술한다.	Y
평가 설계	- 평가 항목과 측정 방법을 기술한다. - 회귀 평가 절차와 기준선 관리 방법을 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

데이터 파이프라인 설계서

1. 개요

본 문서는 업무 원본 문서를 표준작업지시서 산출물로 변환하는 데이터 파이프라인의 구성, 단계별 처리, 저장 구조 및 품질 관리 방안을 정의함을 목적으로 기술한 문서이다.

1.1. 적용 범위

본 문서는 원본 문서의 수집부터 표준 양식 산출물 생성까지의 처리 전 과정에 적용된다. 파이프라인을 호출하는 에이전트의 동작은 에이전트 설계서에서 정의하며, 산출물의 데이터 구조는 데이터 정의서에서 정의한다.

1.2. 설계 전제

입력은 사용자가 보유한 업무 문서로 한정하며, 외부 지식베이스를 검색하지 않는다.
산출물의 형식은 고정된 표준 양식을 따르므로 형식 적합성을 기계적으로 검증한다.
판단이 필요한 결함은 자동으로 수정하지 않고 표식으로 남겨 사용자가 처리한다.
동일 파이프라인을 대화형 처리와 일괄 처리가 공유한다.
운영 환경에 인터넷 구간이 없으므로 외부 자원을 실행 중에 내려받지 않는다.

2. 파이프라인 구성

2.1. 전체 흐름

  [원본 문서]
       |
       v
  ① parse    문서 구조 추출 — 텍스트, 표, 이미지, 페이지 좌표
       |
       v
  ② gen      구조 설계 및 절차 추출 — 2패스 (추론 수행)
       |
       v
  ③ write    표준 양식 산출물 생성
       |
       v
  ④ eval     형식 정합성 검증
       |
       v
  ⑤ 보정     검증 결과 반영 및 미확정 항목 표식
       |
       v
  [표준 양식 산출물 + 근거 매핑]

2.2. 단계 정의

순서	단계	추론 사용	입력	출력
①	parse	조건부	원본 문서	구조화 텍스트, 블록 식별자, 이미지, 페이지 좌표
②	gen	사용	구조화 텍스트	작업 단위 및 활동으로 구성된 스키마
③	write	미사용	스키마	표준 양식 산출물
④	eval	미사용	스키마, 구조화 텍스트	오류 및 경고 목록
⑤	보정	조건부	검증 결과	보정된 스키마, 미확정 항목 표식

추론을 사용하는 단계는 ②와 일부 ①·⑤에 한정한다. ③과 ④는 결정론적으로 동작하므로 동일 입력에 대해 동일한 결과를 산출한다.

2.3. 실행 방식

실행 방식	사용 경로	처리 단위
대화형 처리	에이전트의 생성 Tool 호출	- 파일 단위로 수행한다. - 단계 진행 상황을 사용자에게 전달한다. - 서버의 백그라운드 실행 단위로 수행하여 화면 연결과 분리한다.
일괄 처리	배치 실행	- 지정 폴더의 문서를 순회하여 병렬 수행한다. - 병렬 수를 설정값으로 제한한다. - 수행 결과를 보고서로 생성한다.

두 실행 방식은 동일한 설정 모듈과 동일한 단계 구현을 사용한다. 경로 변경은 설정 모듈 한 곳에서 수행한다.

3. 입력 데이터

3.1. 입력 유형

유형	확장자	처리 방식
문서	pdf, doc, docx	본문, 표, 이미지, 페이지 좌표를 추출한다.
발표자료	ppt, pptx	슬라이드 단위로 추출하고, 레이아웃 판독이 필요한 경우 이미지로 렌더링한다.
표 문서	xls, xlsx	시트와 표 구조를 추출한다.
표준 양식	xlsm	변환하지 않고 스키마로 직접 적재한다.
업무 설명	-	첨부 없이 제시된 설명을 입력으로 사용한다.

3.2. 입력 검증

허용 확장자 목록에 해당하는 파일만 수신한다.
확장자와 더불어 파일 선두 시그니처를 검증하고, 불일치하면 처리하지 않는다.
파일명은 정규화하여 저장하며 경로 조각으로 그대로 사용하지 않는다.
복수 파일을 하나의 산출물로 통합하는 경우 기준 파일을 먼저 처리한 후 나머지를 추가한다.

4. 단계별 설계

4.1. parse 단계

원본 문서에서 후속 단계가 사용할 구조를 추출한다. 다음 하위 처리로 구성한다.

하위 처리	추론	내용
본문 추출	미사용	문단과 표를 블록 단위로 추출하고 각 블록에 식별자를 부여한다.
이미지 추출	미사용	문서에 포함된 이미지를 추출하고 원본 위치의 좌표를 함께 기록한다.
페이지 렌더	미사용	원본 대조 화면에 사용할 페이지 이미지를 생성한다.
순서 판독	조건부	다단 구성이나 도형 배치로 읽기 순서가 모호한 경우 순서를 판정한다.
이미지 판독	조건부	도표 중심 자료에서 이미지의 의미를 판독한다. 판독 실패는 치명적 오류로 처리하지 않고 해당 이미지를 생략한다.

4.2. gen 단계

구조화 텍스트로부터 작업 단위와 활동을 도출한다. 2패스로 수행한다.

패스	처리	내용
1패스	구조 설계	문서 전체를 조망하여 작업 단위의 골격을 도출한다.
2패스	절차 추출	작업 단위별로 활동을 전수 추출한다. 각 활동에 근거 블록 식별자를 부여한다.

작성자 항목은 원본 문서의 값을 사용하지 않고 시스템이 로그인 사용자로 기록한다.
원본에서 확인되지 않는 항목은 임의로 생성하지 않고 미확정 표식을 부여한다.
원본에 없는 기본 정보 항목은 정해진 기본값으로 채운 후 검토 대상으로 표시한다.
활동에 대응하는 이미지는 근거 블록 범위 또는 인접 관계를 기준으로 연결한다.

4.3. write 단계

스키마를 표준 양식 파일로 변환한다. 추론을 사용하지 않는다.
산출물은 저장하지 않고 요청 시마다 현재 스키마로부터 생성한다.
표준 양식 외의 시트가 원본에 포함된 경우 병합하며, 병합 실패 시 표준 시트만 출력한다.

4.4. eval 단계

검증 구분	결과 등급	검증 내용
필수 항목	오류	기본 정보와 작업 단위의 필수 항목 누락 여부
구조 정합성	오류	작업 단위와 활동의 계층 구조 및 번호 체계
근거 대응	경고	활동에 부여된 근거 블록 식별자의 유효성
미확정 항목	경고	검토 표식이 남아 있는 항목의 존재 여부
양식 제약	오류	표준 양식이 허용하는 값의 범위와 길이

4.5. 보정 단계

기계적으로 판정 가능한 결함만 자동 보정한다.
판단이 필요한 결함은 자동으로 수정하지 않고 검토 표식을 유지한다.
검토 표식은 화면의 작업 목록으로 제시하여 사용자가 에이전트와 함께 처리한다.
보정 후 검증을 재수행하여 결과를 기록한다.

5. 데이터 저장 설계

5.1. 저장 영역

영역	저장 대상	보관 정책
입력 영역	원본 문서	대화 또는 배치 작업 단위로 보관한다. 산출물 등록 시 함께 복사하여 보존한다.
작업 영역	구조화 텍스트, 추출 이미지, 페이지 이미지	처리 단위별 폴더로 분리한다. 작업 종료 후 정리 대상으로 관리한다.
산출 영역	표준 양식 산출물	요청 시마다 생성하므로 영구 보관하지 않는다.
보고 영역	일괄 처리 결과 보고서	수행 이력으로 보관한다.
영속 영역	스키마, 대화 이력, 근거 매핑	관계형 데이터베이스에 보관한다.

5.2. 저장소 구분 기준

데이터 유형	저장소	구분 기준
구조화 데이터	관계형 데이터베이스	참조 무결성과 트랜잭션이 필요한 데이터
대용량 자산	자산 저장소	원본 문서, 이미지 등 바이너리. 테이블에는 식별자만 기록한다.
중간 산출물	작업 영역 파일 시스템	처리 중에만 사용하며 재생성 가능한 데이터

벡터 저장소와 그래프 저장소는 사용하지 않는다. 유사도 기반 검색을 수행하지 않으므로 임베딩 생성 및 색인 과정을 두지 않는다.

5.3. 정리 정책

대화를 삭제하면 해당 대화의 작업 영역과 자산을 함께 제거한다.
보관 한도를 초과한 대화는 목록에서 제외하고 제외 사유를 기록한다.
소유자가 없는 잔여 자산은 정기적으로 점검하여 정리한다.
정리 도구는 기본적으로 점검만 수행하고, 명시적 지시가 있을 때만 삭제한다.

6. 품질 관리

6.1. 출력 형식 검증

추론 결과를 반영하기 전에 기대 형식 여부를 검사한다. 기본 정보는 객체, 작업 단위와 활동은 객체 목록이어야 한다.
형식 검사에 실패하면 반영하지 않고 사유를 반환한다.
반영 전에 값의 정규화를 수행한다. 빈 명칭, 유효하지 않은 구분값, 빈 활동은 제거하거나 보정한다.

6.2. 과다 생성 방지

활동 수의 상한을 설정하고 초과 시 처리를 중단한다.
동일 내용이 반복 생성된 경우 중복을 제거한다.
상한에 도달한 경우 사유를 기록하고 사용자에게 알린다.

6.3. 재현성

추론을 사용하지 않는 단계는 동일 입력에 대해 동일 결과를 산출한다.
고정된 입력 문서 집합에 대한 형식 검증 결과를 기준선으로 관리한다.
파이프라인 또는 프롬프트 변경 시 기준선과 비교하여 품질 변화를 확인한다.
각 단계의 소요 시간과 사용량을 기록하여 변경 영향을 추적한다.

7. 오류 처리 및 재처리

발생 단계	오류 유형	처리 방식
parse	문서 열기 실패, 형식 불일치	해당 파일의 처리를 중단하고 사유를 반환한다. 일괄 처리에서는 다음 파일로 진행한다.
parse	이미지 판독 실패, 렌더 실패	치명적 오류로 처리하지 않는다. 해당 이미지를 생략하고 진행한다.
gen	추론 호출 실패	유형별로 분류하여 안내 문구로 변환한다. 재시도 후에도 실패하면 처리를 중단한다.
gen	출력 형식 불일치	반영하지 않고 사유를 반환한다. 직전 상태를 유지한다.
write	양식 변환 실패	사유를 반환한다. 선택적 병합 실패는 표준 시트만 출력하여 진행한다.
eval	검증 수행 실패	검증 결과를 비워 두고 사유를 기록한다. 산출물 생성은 유지한다.

일괄 처리에서 개별 파일의 실패가 전체 수행을 중단시키지 않는다.
실패한 파일은 보고서에 사유와 함께 기록하고 재처리 대상으로 관리한다.
중간 산출물이 남아 있는 경우 해당 단계부터 재처리할 수 있도록 작업 영역을 유지한다.

8. 성능 및 자원

항목	기준
병렬 처리	- 일괄 처리의 동시 수행 수를 설정값으로 제한한다. - 기본값은 실행 환경의 자원을 고려하여 결정한다.
장시간 처리	- 문서 변환은 수 분이 소요될 수 있으므로 백그라운드 실행 단위로 처리한다. - 단계 진행 상황을 사용자에게 전달한다.
외부 프로세스	- 문서 변환 도구 호출에 제한 시간을 설정한다. - 인자를 배열로 전달하고 셸을 경유하지 않는다.
사용량 계량	- 단계별 추론 사용량과 소요 시간을 기록한다. - 사용자 단위로 귀속하여 한도 제어에 사용한다.
부하 특성	- 평시에는 대화형 단건 처리가 주를 이룬다. - 문서 변환 시 순간 부하가 발생하므로 이를 기준으로 자원을 산정한다.

9. 작성 가이드

데이터 파이프라인 설계서는 입력 데이터의 유형과 산출물의 형식을 먼저 확정하고, 그 사이의 변환 단계를 정의한다. 추론을 사용하는 단계와 사용하지 않는 단계를 구분하여 재현 가능한 범위를 명확히 한다.

항목명	작성 방법	필수 여부
개요	- 본 문서의 목적, 적용 범위, 설계 전제를 기술한다.	Y
파이프라인 구성	- 전체 흐름을 도식으로 기술한다. - 단계별 입력과 출력, 추론 사용 여부를 기술한다. - 대화형 처리와 일괄 처리의 차이를 기술한다.	Y
입력 데이터	- 입력 유형과 확장자, 유형별 처리 방식을 기술한다. - 입력 검증 기준을 기술한다.	Y
단계별 설계	- 각 단계의 하위 처리와 수행 내용을 기술한다. - 자동 보정 대상과 사용자 처리 대상을 구분하여 기술한다.	Y
데이터 저장 설계	- 저장 영역별 저장 대상과 보관 정책을 기술한다. - 저장소 구분 기준을 기술한다. - 사용하지 않는 저장소는 그 사실과 사유를 기술한다.	Y
품질 관리	- 출력 형식 검증과 과다 생성 방지 기준을 기술한다. - 재현성 확보 방안과 기준선 관리 방법을 기술한다.	Y
오류 처리	- 단계별 오류 유형과 처리 방식을 기술한다. - 치명적 오류와 진행 가능한 오류를 구분한다. - 재처리 방안을 기술한다.	Y
성능 및 자원	- 병렬 처리, 장시간 처리, 사용량 계량 기준을 기술한다. - 부하 특성과 자원 산정 근거를 기술한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

운영 이관 Task 목록

1. 개요

본 문서는 현재까지 개발된 내용과 개발 예정 내용을 포함하여, 운영 이관에 필요한 Task를 식별하고 우선순위와 수행 주체를 정리한 문서이다.

1.1. 구분 기준

구분	정의	처리
완료	현재 구현 및 검증이 끝난 항목	2장. 이관 시 현황으로 제시한다.
필수	이관 전 반드시 충족해야 하는 항목	3장. 미충족 시 이관하지 않는다.
강화	운영 안정성을 높이는 항목	4장. 이관 후 단계적으로 수행 가능하다.
구조	인프라 구성 변경이 필요한 항목	5장. 별도 의사결정 대상이다.

규모는 상대 크기로 표기한다(소 · 중 · 대). 상세 공수는 범위 확정 후 별도 산정한다.

2. 현재 완료 상태

운영 이관 검토의 출발점으로 현재 구현된 범위를 제시한다.

영역	구현 내용	검증 수단
기능	단위기능 45건. 프로세스 체계도, SOP 관리, 에이전트 생성, 접근제어, 사용량 관리, 데이터 저장	기능정의서 기준 고객 승인 40건, 협의 5건
인증	사번 로그인, 솔트 적용 단방향 해시 저장, 서명 토큰 세션, 로그인 실패 누적 잠금	자동 테스트
인가	역할과 가시 범위의 조합 부여, 요청마다 서버 검증, 범위 밖 자원은 존재 비노출	자동 테스트, 계층 구조로 우회 경로 차단
동시성	편집 락(유효기간·자동 해제·강제 해제), 기준 버전 대조, 행 잠금 기반 버전 증가	동시성 테스트
감사	등록·수정·삭제·락 해제·권한 변경·관리자 승격 기록. 미정의 행위는 기록 거부	자동 테스트
데이터	테이블 23종, 참조 무결성 정책, 업무 규칙 트리거, 마이그레이션 도구 기반 스키마 관리	스키마 대조 도구
사용량	호출별 계량, 사용자별 월 한도, 호출 전 검사 및 차단	자동 테스트
품질 통제	전 스위트 자동 테스트, 청결도 검사 16종, 아키텍처 계층 계약 3종(예외 없음), 실행 환경 호환 검사	단계별 전량 통과 기준
배포	폐쇄망 반입 절차 수립, 컨테이너 구성, 정기 백업 스크립트	운영 환경 반입 수행 이력
산출물	개발·설계 산출물 12종(기능·화면·아키텍처 2·개발표준·보안·인터페이스·데이터베이스·에이전트·파이프라인·이관계획·운영매뉴얼)	본 문서 묶음

인증, 인가, 감사, 동시성, 스키마 관리, 자동 테스트는 운영 서비스에 요구되는 기본 통제에 해당하며 이미 구현되어 있다. 미비 영역은 운영 환경 구성과 감시 수단에 집중되어 있다.

3. 이관 필수 Task

이관 전 충족이 필요한 항목이다. 미충족 상태로 이관하지 않는다.

번호	영역	Task	현재	규모	주체
T-01	보안	전송 구간 암호화 적용 및 세션 쿠키 보안 속성 활성화	미적용. 자격 증명이 평문 전송된다	소	인프라
T-02	백업	백업본 복구 시험 수행 및 결과 기록	미실시. 복구 가능 여부가 확인된 적 없다	소	인프라·구축
T-03	감시	서비스 가동 점검 수단 마련(상태 확인 경로 + 주기 점검)	미적용. 사용자 신고에 의존한다	중	구축·인프라
T-04	감시	백업 실패 및 자원 임계 알림	미적용. 로그 수동 확인만 가능하다	중	인프라
T-05	보안	보안 응답 헤더 적용(프레임 차단·형식 추론 금지·전송 보안·참조 정책)	미적용	소	구축
T-06	보안	보안 이벤트 기록 보강(로그인 성공·실패, 계정 잠금, 인가 거부)	부분 적용. 권한 변경과 자원 변경은 기록된다	소	구축
T-07	보안	감사 로그 추가 전용 권한 설정(수정·삭제 권한 회수)	미적용	소	인프라
T-08	보안	목록 조회 건수 서버측 상한 강제	기본값만 존재. 상한 미강제	소	구축
T-09	보안	업로드 파일 시그니처 검증	확장자 검증만 수행	소	구축
T-10	보안	로그 민감정보 마스킹 및 로그 순환	미적용. 접근 로그에 경로가 평문으로 남는다	중	구축·인프라
T-11	구성	의존성 버전 고정 및 반입 이미지 구성요소 목록화	버전 미고정. 재빌드 시 구성이 달라질 수 있다	소	구축
T-12	법무	전염성 라이선스 구성요소 조치(대체 또는 상용 라이선스 취득)	문서 처리 라이브러리 1종이 해당. 납품물 권리 귀속과 충돌 가능	중	구축·법무
T-13	이관	운영 교육 및 모의 장애 대응 수행	미실시	소	구축
T-14	이관	지원 요청 경로 및 연락 체계 확정	미확정	소	전 주체

T-12는 기능이 아니라 납품물의 권리 관계에 영향을 주는 항목이므로 이관 일정과 무관하게 조기에 결론이 필요하다.

4. 운영 안정성 강화 Task

이관 후 단계적으로 수행 가능한 항목이다.

번호	영역	Task	효과	규모	주체
T-21	감시	로그 중앙 수집 및 조회 수단	장애 원인 분석 시간 단축	중	인프라
T-22	품질	입력 스키마 검증 도입(신규·수정 구간부터)	잘못된 요청의 조기 차단	중	구축
T-23	품질	오류 코드 체계 적용 및 사용자 안내 문구 정리	문의 응대 시간 단축	중	구축
T-24	품질	산출물 품질 회귀 기준선 구축	프롬프트·변환 로직 변경 시 품질 저하 조기 감지	중	구축
T-25	보안	콘텐츠 보안 정책 적용	교차 사이트 스크립트 심층 방어	소	구축
T-26	보안	요청 제한 영속화 및 출발지 단위 제한 추가	재기동 후에도 차단 상태 유지	소	구축
T-27	운영	자산 정리 자동 탐지 및 보고	저장소 사용량 관리	소	인프라

5. 구조 변경 검토 항목

운영 조직의 표준 인수 기준에 해당하는 항목이다. 애플리케이션 재개발이 아니라 인프라 구성 변경에 해당한다 — 아래 네 건 중 애플리케이션 변경이 필요한 것은 T-33 하나다.

번호	Task	성격	애플리케이션 변경	규모
T-31	관리형 데이터베이스 서비스 전환	인프라 구성	없음 — 접속 문자열 변경으로 전환된다. 저장소 계층이 분리되어 있다	중
T-32	다중 가용영역 이중화 및 부하 분산	인프라 구성	T-33 선행 필요	대
T-33	다중 프로세스 구동을 위한 작업 상태 외부화	애플리케이션	있음 — 생성 작업 버퍼를 외부 저장소로 이전한다. 범위가 단일 모듈로 한정된다	중
T-34	무중단 배포	인프라 구성	T-32·T-33 선행 필요	중

구조 변경의 범위에 대한 판단. 운영 조직이 요구하는 가용성 수준은 인프라 구성 변경과 작업 상태 외부화 한 건으로 달성된다. 인증·인가·감사·동시성·데이터 모델 등 운영 서비스의 기본 통제는 이미 구현되어 있어 재작성 대상이 아니다. 구조 변경의 범위를 인프라와 단일 모듈로 한정하여 산정하는 것이 타당하다.

6. 선후 관계 및 수행 순서

[1단계] 이관 필수 - 병렬 수행 가능
   T-01 전송 암호화  ---+
   T-05 보안 헤더       |
   T-06 보안 이벤트     +--> T-13 운영 교육 --> T-14 연락 체계 --> 이관 가능
   T-07~T-11 보안·구성  |
   T-02 복구 시험  -----+
   T-03 T-04 감시  -----+
   T-12 라이선스 조치 (독립. 조기 결론 필요)

[2단계] 안정성 강화 - 이관 후 단계적
   T-21 ~ T-27

[3단계] 구조 변경 - 별도 의사결정
   T-31 관리형 DB 전환  (단독 수행 가능)
   T-33 작업 상태 외부화 --> T-32 이중화 --> T-34 무중단 배포

7. 권고 이관 시나리오

시나리오	범위	판단
A. 조건부 이관	1단계 완료 후 이관. 2·3단계는 이관 후 과제로 등재	권고. 기본 통제가 구현되어 있어 1단계만으로 운영 가능 수준에 도달한다. 3단계 미충족 항목은 예외 승인으로 처리하고 일정을 명시한다
B. 완전 충족 후 이관	3단계까지 완료 후 이관	운영 조직 표준을 모두 충족하나 기간과 비용이 크게 증가한다. 그 기간 동안 운영 주체가 공백이 된다
C. 현업 운영 유지	1단계만 수행하고 업무 부서가 계속 보유	이관을 보류하는 선택이다. 담당자와 예산을 문서로 확정해야 한다

시나리오 A를 권고한다. 운영 조직이 제시하는 인수 기준 체크리스트를 수령하면 본 Task 목록과 대조하여 1단계 범위를 확정할 수 있다.

8. 확인 요청 사항

번호	요청	사유
1	운영 조직의 인수 기준 체크리스트	본 Task 목록과 대조하여 누락 항목을 식별하고 1단계 범위를 확정한다
2	목표 가용성 수준	이중화 필요 여부가 3단계 범위와 규모를 결정한다
3	관리형 데이터베이스 서비스 사용 가능 여부	사용 가능하면 백업·패치 책임이 플랫폼으로 이전되어 운영 부담이 줄어든다
4	운영 주체 및 담당자 지정	교육 대상과 연락 체계를 확정한다
5	전송 구간 인증서 발급 절차	T-01의 선행 조건이다

SKMR_현업 주도 SOP체계 구축 지원 및 자문

운영 이관 계획서

1. 개요

본 문서는 구축이 완료된 시스템을 운영 주체에게 이관하기 위한 범위, 역할 분담, 이관 조건 및 미충족 항목의 처리 방안을 정의함을 목적으로 기술한 문서이다.

1.1. 이관 대상

구분	대상
시스템	SOP 생성·관리 시스템 운영 환경 및 개발 환경
인프라	업무 계정의 EC2 2식, 각 환경의 컨테이너 2종, 자산 저장소
데이터	프로세스 체계도, SOP 본문 및 버전, 계정 및 권한, 감사 기록
산출물	개발·설계 산출물 일체, 운영 매뉴얼, 소스 형상
제외	네트워크 공통 자원(Transit Gateway, 공통 엔드포인트)은 기존 관리 주체가 계속 보유한다.

1.2. 이관 형태

본 시스템은 현업 운영 형태로 이관한다. 운영 조직이 아닌 업무 부서가 1차 운영 주체가 되므로, 서버 접속과 명령 수행이 필요한 작업은 업무 부서가 수행할 수 없음을 전제로 역할을 분담한다. 2장의 역할 분담은 이 전제 위에서 작성한다.

현업 운영의 전제. 운영 조직 이관과 달리 1차 운영 주체가 서버 운영 경험을 보유하지 않는다. 따라서 절차서에 빠진 내용을 경험으로 보완할 수 없다. 판단이 필요한 작업은 모두 지원 요청 경로로 넘긴다는 원칙으로 설계한다.

2. 역할 분담

2.1. 주체별 책임

주체	책임	비고
업무 부서 (1차 운영)	- 사용자 문의 1차 응대 - 일일·주간 점검 수행 - 계정 발급 및 권한 부여 요청 - 장애 1차 확인 및 신고 - 월간 운영 현황 보고	화면에서 수행 가능한 작업으로 한정한다.
인프라 담당 (2차 지원)	- 서버 기동·정지·재기동 - 백업 수행 확인 및 복구 - 디스크 및 자원 점검 - 계정 발급 스크립트 수행 - 네트워크 및 접근 제어 변경	서버 접속 권한을 보유한 담당자
구축 조직 (3차 지원)	- 결함 수정 및 재배포 - 스키마 변경 - 장애 원인 분석 - 기능 개선	하자보수 기간 내. 범위와 기간은 5장에서 정한다.

2.2. 작업별 수행 주체

작업	업무 부서	인프라 담당	구축 조직	비고
사용자 문의 응대	수행	-	-	사용 방법은 가이드 화면으로 안내
계정 발급	요청	수행	-	명부 기준 일괄 발급 스크립트
가시 범위 부여	수행	-	-	관리 화면에서 수행
관리자 지정	수행	-	-	관리 화면에서 수행. 감사 기록 남음
편집 락 강제 해제	수행	-	-	관리 화면에서 수행
일일 점검	수행	-	-	화면 접속 및 생성 1건 확인
백업 성공 확인	-	수행	-	로그 확인 필요
서버 재기동	요청	수행	-	진행 중 생성 작업이 유실된다
데이터 복구	-	수행	지원	복구 절차는 운영 매뉴얼 6장
고아 자산 정리	-	수행	-	월 1회. 확인 후 수동 삭제
결함 수정·재배포	요청	지원	수행	이미지 반입 절차를 따른다
스키마 변경	-	지원	수행	-
장애 원인 분석	신고	1차 확인	수행	-

3. 이관 조건 점검

운영 주체가 인수 가능한 상태인지 아래 항목으로 점검한다. 미충족 항목은 보완 또는 예외 승인으로 처리하며, 처리 방안을 함께 기재한다.

구분	점검 항목	현재 상태	처리	비고
문서	개발·설계 산출물	작성 완료	충족	10종
	운영 매뉴얼	작성 완료	충족	장애 대응·백업 복구 포함
	계정·권한 관리 절차	운영 매뉴얼에 포함	충족	-
	변경 관리 절차	운영 매뉴얼에 포함	충족	-
가용성	서버 이중화	미적용. 환경별 단일 인스턴스	예외 승인	장애 시 해당 환경 중단. 복구는 재기동으로 수행
	데이터베이스 이중화	미적용. 컨테이너 단독 구성	예외 승인	관리형 서비스 전환은 후속 과제
	무중단 배포	미적용	예외 승인	재배포 시 수 분간 중단. 업무 시간 외 수행
백업	정기 백업	예약 작업으로 수행	충족	자산 저장소로 전송
	백업 성공 알림	미적용. 로그 확인만 가능	보완	실패를 인지할 수단이 없다. 점검 항목으로 대체
	복구 시험	미실시	보완	이관 전 1회 수행하고 결과를 기록한다. 미실시 상태로 이관하지 않는다
감시	서비스 가동 감시	미적용	보완	일일 점검으로 대체하되 알림 수단 도입을 후속 과제로 둔다
	자원 사용량 감시	미적용	보완	디스크 포화가 주요 위험
	오류 알림	미적용	예외 승인	사용자 신고에 의존한다
보안	전송 구간 암호화	미적용	보완	이관 전 적용한다. 자격 증명이 평문으로 전송된다
	보안 응답 헤더	미적용	보완	적용 비용이 낮다
	보안 이벤트 기록	부분 적용	보완	로그인·인가 거부 기록 추가
	로그 마스킹	미적용	보완	접근 로그 점검 및 순환 우선
인수인계	운영 교육	미실시	보완	이관 전 수행. 4장 일정 참조
인수인계	인수인계 확인서	미작성	보완	6장 양식

3.1. 보완 항목 우선순위

순위	항목	수행 주체	사유
1	전송 구간 암호화	인프라 담당	자격 증명이 평문으로 전송되는 상태로 운영을 넘길 수 없다.
2	복구 시험 1회 수행	인프라 담당 · 구축 조직	백업이 실제로 복구되는지 확인되지 않은 상태로 운영을 넘길 수 없다.
3	보안 응답 헤더	구축 조직	적용 비용이 낮다.
4	보안 이벤트 기록 보강	구축 조직	사고 시 추적 수단이 된다.
5	운영 교육 및 모의 장애 대응	구축 조직	절차서만으로는 현업이 수행하지 못한다.
6	접근 로그 점검 및 순환	인프라 담당	디스크 포화 방지와 개인정보 노출 점검을 겸한다.

4. 이관 일정

단계	활동	주체	완료 기준
1	보완 항목 수행	구축 조직 · 인프라 담당	3.1의 1~4순위 완료
2	복구 시험	인프라 담당	백업본으로 복구 성공, 결과 기록
3	운영 교육	구축 조직 → 업무 부서 · 인프라 담당	운영 매뉴얼 기반 교육 이수
4	모의 장애 대응	전 주체	장애 유형 2건 이상에 대해 절차대로 조치 완료
5	안정화 운영	업무 부서 주관, 구축 조직 지원	합의 기간 동안 운영. 발생 건을 기록한다
6	이관 확정	전 주체	인수인계 확인서 서명

안정화 운영 기간은 운영 주체와 협의하여 정한다. 이 기간에는 업무 부서가 운영을 수행하고 구축 조직이 질의 응답과 결함 수정을 지원한다. 기간 중 발생한 장애와 문의를 기록하여 이관 확정 시 검토한다.

5. 하자보수 및 지원 범위

구분	포함 여부	내용
결함 수정	포함	인수 시점 기능이 명세대로 동작하지 않는 경우
장애 원인 분석	포함	시스템 결함에 기인한 장애
질의 응답	포함	운영 매뉴얼 범위 내 질의
기능 개선	미포함	별도 과업으로 협의한다
인프라 변경	미포함	이중화, 관리형 서비스 전환 등
데이터 작업	미포함	대량 정정, 일괄 적재 등

하자보수 기간과 대응 시간은 계약 조건을 따른다. 지원 요청 경로는 운영 매뉴얼 8장에서 정한다.

6. 인수인계 확인

아래 항목을 확인하고 서명함으로써 이관을 확정한다.

확인	항목	확인 방법
□	개발·설계 산출물 일체 인계	문서 목록 대조
□	운영 매뉴얼 인계	문서 수령
□	소스 형상 및 접근 권한 인계	저장소 접근 확인
□	서버 접속 정보 및 권한 인계	인프라 담당 접속 확인
□	관리자 계정 인계	관리 화면 진입 확인
□	보완 항목 완료	3.1의 1~4순위 결과 확인
□	복구 시험 결과 확인	시험 기록 수령
□	운영 교육 이수	참석자 명단
□	예외 승인 항목 합의	3장 예외 승인 항목에 대한 서명
□	지원 요청 경로 확인	연락 체계 공유

구분	소속	성명	서명 · 일자
인계 (구축 조직)
인수 (업무 부서)
인수 (인프라 담당)
승인

7. 작성 가이드

운영 이관 계획서는 운영 주체의 인수 기준을 입력으로 하여 현재 상태와의 차이를 식별하고, 차이를 보완할 것인지 예외로 승인받을 것인지 결정한다. 미충족 항목을 누락하지 않는 것이 이 문서의 목적이다 — 숨기고 이관하면 장애 발생 시 책임 소재가 불분명해진다.

항목명	작성 방법	필수 여부
이관 대상	- 이관 범위와 제외 범위를 명확히 구분하여 기술한다. - 이관 형태(운영 조직 / 현업 운영)와 그 전제를 기술한다.	Y
역할 분담	- 주체별 책임을 기술한다. - 작업별 수행 주체를 표로 기술한다. 현업 운영인 경우 서버 접속이 필요한 작업을 구분하여 지원 주체를 명시한다.	Y
이관 조건 점검	- 운영 주체의 인수 기준에 따라 항목별 현재 상태를 기술한다. - 처리를 충족 / 보완 / 예외 승인으로 구분한다. - 보완 항목은 우선순위와 수행 주체, 사유를 함께 기술한다.	Y
이관 일정	- 보완, 시험, 교육, 안정화 운영, 확정의 단계별 완료 기준을 기술한다.	Y
하자보수 범위	- 포함과 미포함을 구분하여 기술한다. 경계가 모호하면 분쟁이 된다.	Y
인수인계 확인	- 확인 항목과 확인 방법을 기술한다. - 예외 승인 항목에 대한 서명을 포함한다.	Y

SKMR_현업 주도 SOP체계 구축 지원 및 자문

시스템 운영 매뉴얼

1. 개요

본 문서는 시스템을 인수한 운영 주체가 일상 운영, 점검, 장애 대응을 수행하기 위한 절차를 정의함을 목적으로 기술한 문서이다.

1.1. 대상 독자와 사용 방법

독자	읽을 범위	전제
업무 부서	3장 · 4장 · 7장 · 8장	화면에서 수행 가능한 작업만 다룬다. 서버 접속이 필요 없다.
인프라 담당	전체	서버 접속 권한과 명령 수행 경험을 보유한다.
구축 조직	전체	지원 요청 시 참조한다.

각 절차에 수행 주체를 표기한다. 자신의 주체가 아닌 절차는 수행하지 않고 8장의 요청 경로로 넘긴다. 판단이 필요한 상황에서 임의로 조치하지 않는다 — 되돌릴 수 없는 작업이 포함되어 있다.

1.2. 시스템 구성 요약

항목	내용
구성	운영과 개발 환경 각각 서버 1식. 서버마다 애플리케이션과 데이터베이스 컨테이너 2종
접속	사내망에서만 접속 가능. 외부 인터넷에서 접근할 수 없다
추론 서비스	공통 엔드포인트를 경유한다. 운영과 개발이 공유한다
자산	원본 문서와 이미지는 오브젝트 스토리지에 보관한다
중단 요인	서버 또는 컨테이너 정지 시 해당 환경 전체가 중단된다. 이중화가 없다

2. 점검

2.1. 일일 점검 — 업무 부서

확인	항목	방법	이상 시
□	화면 접속	브라우저로 접속하여 로그인	7.1 접속 불가 참조
□	SOP 목록 조회	SOP 조회 화면에서 목록이 뜨는지 확인	7.2 조회 오류 참조
□	생성 동작	Studio에서 짧은 지시로 생성을 1회 수행	7.3 생성 실패 참조
□	미처리 문의	1:1 문의 화면에서 답변 대기 건 확인	업무 부서가 응대

2.2. 주간 점검 — 인프라 담당

확인	항목	명령	판정
□	컨테이너 상태	`docker compose ps`	두 컨테이너 모두 가동 중
□	백업 성공	`tail -40 /var/log/sop-backup.log`	최근 7일 모두 성공. 실패가 있으면 6.2
□	디스크 여유	`df -h /`	사용률 80% 미만. 초과 시 7.5
□	오류 로그	`docker compose logs --tail 200 app \| grep -i error`	반복되는 오류가 있으면 8장으로 요청

2.3. 월간 점검 — 인프라 담당

확인	항목	절차
□	잔여 자산 점검	5장 참조. 확인만 하고 삭제는 별도 판단
□	사용량 확인	관리 화면의 사용량에서 월 집계 확인
□	감사 기록 확인	관리 화면의 감사 로그에서 권한 변경 이력 확인
□	백업 보관 확인	오브젝트 스토리지에 최근 덤프가 쌓이는지 확인

3. 계정 및 권한 관리

3.1. 계정 발급 — 업무 부서 요청, 인프라 담당 수행

업무 부서가 발급 대상 명부를 사번·성명·연락처 형식으로 전달한다.
인프라 담당이 발급 스크립트로 일괄 생성한다.
초기 비밀번호 생성 규칙은 외부에 공개하지 않는다. 사용자에게 개별 전달한다.
명부 파일에는 개인정보가 포함되므로 형상관리에 올리지 않고 작업 후 삭제한다.

3.2. 가시 범위 부여 — 업무 부서

관리 화면의 권한 범위에서 사용자별로 체계도 노드를 부여한다.
범위를 받지 못한 사용자는 아무 것도 조회할 수 없다. 계정 발급 후 반드시 부여한다.
부여 단위는 Lv1부터 Lv3까지이며 하위는 자동으로 포함된다.
열람 권한과 편집 권한을 서로 다른 범위로 부여할 수 있다.

3.3. 관리자 지정 — 업무 부서

관리 화면의 관리자 지정에서 승격하거나 회수한다.
자기 자신은 회수할 수 없다. 관리자가 한 명인 경우에도 회수할 수 없다.
승격과 회수는 감사 기록에 남는다.
권한은 필요한 최소 범위로 부여한다. 전체 조회가 필요한 경우 관리자 승격 대신 열람 범위를 넓게 부여하는 방법을 먼저 검토한다.

3.4. 편집 락 해제 — 업무 부서

편집 중 비정상 종료로 락이 남아 다른 사용자가 편집하지 못하는 경우, 관리 화면의 편집 락 현황에서 강제 해제한다. 해제 시 기존 보유자 정보가 감사 기록에 남는다. 해제 전에 보유자에게 확인한다 — 실제 편집 중이면 작업이 유실된다.

4. 기동 및 정지 — 인프라 담당

작업	명령	유의
상태 확인	`docker compose ps`	-
애플리케이션 재기동	`docker compose restart app`	진행 중이던 생성 작업이 유실된다. 사용자에게 사전 안내한다
전체 기동	`docker compose up -d`	-
전체 정지	`docker compose down`	데이터 볼륨은 유지된다
로그 확인	`docker compose logs --tail 200 app`	-

데이터베이스 컨테이너를 임의로 정지하거나 삭제하지 않는다. 볼륨 설정이 어긋나면 기동을 거부한다. 데이터베이스 관련 작업은 8장으로 요청한다.

5. 잔여 자산 정리 — 인프라 담당

대화를 삭제하면 연결된 자산도 함께 제거된다. 그럼에도 데이터베이스를 직접 손봤거나 복구한 뒤에는 소유자 없는 자산이 남는다. 월 1회 점검한다.

순서	명령	설명
1	`docker compose exec app python3 tools/gc_assets.py`	무엇이 지워질지 확인만 한다. 인자 없이 실행하면 아무것도 삭제하지 않는다
2	건수 확인	출력된 건수가 타당한지 판단한다. 평소보다 많으면 삭제하지 않고 8장으로 요청한다
3	`... gc_assets.py --force --expect <건수>`	확인한 건수를 적어 삭제한다. 실제 건수가 다르면 멈춘다

이 작업을 자동화하지 않는다. 디렉터리 삭제이며 되돌릴 수 없다. 마이그레이션 중이거나 복구 직후에는 정상 자산이 소유자 없는 것으로 보일 수 있다. 탐지는 정기적으로, 삭제는 사람이 확인하고 수행한다.

6. 백업 및 복구 — 인프라 담당

6.1. 백업 구성

관리형 데이터베이스 서비스를 쓰지 않으므로 자동 백업이 없다. 예약 작업으로 수행한다.
예약 작업이 덤프를 생성하여 오브젝트 스토리지로 전송한다.
덤프가 비정상적으로 작으면 전송하지 않고 실패로 종료한다. 빈 덤프를 정상 백업으로 착각하지 않기 위한 장치다.
SOP는 삭제하지 않는 정책이므로 데이터 유실 시 그 정책이 무의미해진다. 백업은 정책의 일부다.

6.2. 백업 실패 시

증상	조치
로그에 실패 기록	- 디스크 여유를 확인한다(`df -h /`) - 데이터베이스 컨테이너 가동을 확인한다 - 수동으로 1회 실행하여 오류 메시지를 확인한다
덤프 크기 미달	- 데이터베이스 접속 정보가 바뀌지 않았는지 확인한다 - 해소되지 않으면 8장으로 요청한다
전송 실패	- 자산 저장소 접근 권한과 엔드포인트 경로를 확인한다

6.3. 복구 절차

순서	내용
1	복구 사유와 복구 시점을 기록한다. 복구 후 그 사이 데이터는 사라진다
2	애플리케이션 컨테이너를 정지하여 쓰기를 멈춘다
3	오브젝트 스토리지에서 복구할 덤프를 내려받는다
4	덤프를 데이터베이스에 적재한다 (`gunzip -c <덤프> \| docker compose exec -T db psql -U <계정> -d <DB>`)
5	애플리케이션을 기동하고 로그인과 SOP 목록 조회로 확인한다
6	복구 일시, 사용한 덤프, 결과를 기록한다

복구 시험을 사전에 1회 수행한다. 백업이 실제로 복구되는지 확인되지 않은 상태에서는 장애 시 이 절차가 동작한다고 보장할 수 없다. 개발 환경에서 수행하고 결과를 기록한다.

7. 장애 대응

증상별 1차 조치를 정리한다. 1차 조치로 해소되지 않으면 임의로 더 시도하지 않고 8장의 요청 경로로 넘긴다.

7.1. 화면에 접속되지 않는다

주체	확인	조치
업무 부서	다른 사용자도 동일한지 확인	본인만이면 사내망 연결과 브라우저를 확인한다. 전원이면 인프라 담당에게 신고한다
인프라 담당	`docker compose ps`	컨테이너가 멈췄으면 `docker compose up -d`
인프라 담당	`df -h /`	디스크 포화면 7.5
인프라 담당	서버 자체 응답	서버가 응답하지 않으면 인스턴스 상태를 확인하고 8장으로 요청한다

7.2. 목록이나 상세가 조회되지 않는다

주체	확인	조치
업무 부서	특정 사용자만 안 보이는지	가시 범위가 부여되지 않았을 수 있다. 3.2 확인
업무 부서	전원이 안 보이는지	인프라 담당에게 신고
인프라 담당	로그에 서비스 불가 응답이 있는지	데이터베이스 컨테이너 가동을 확인한다. 멈췄으면 기동한다

7.3. SOP 생성이 실패한다

주체	증상	조치
업무 부서	한도 초과 안내	사용 한도에 걸린 것이다. 관리 화면에서 한도를 확인하고 필요 시 조정한다
업무 부서	특정 문서에서만 실패	문서 형식 문제일 수 있다. 다른 문서로 재시도하고 실패 문서를 첨부해 신고한다
업무 부서	모든 생성이 실패	즉시 신고
인프라 담당	추론 서비스 호출 오류	공통 엔드포인트 경로와 접근 권한을 확인한다. 개발 환경에서도 동일한지 확인한다

추론 엔드포인트는 운영과 개발이 공유한다. 양쪽이 동시에 실패하면 공유 구간의 문제이고, 한쪽만 실패하면 그 환경의 문제다. 신고 시 이 구분을 함께 전달한다.

7.4. 편집이 저장되지 않는다

증상	원인과 조치
다른 사용자가 편집 중이라는 안내	정상 동작이다. 보유자에게 연락하거나 3.4로 해제한다
충돌 안내	다른 창에서 먼저 저장된 것이다. 화면을 새로 고쳐 최신 내용을 받은 뒤 다시 편집한다
안내 없이 저장되지 않음	신고한다

7.5. 디스크가 부족하다 — 인프라 담당

로그 파일 크기를 확인하고 오래된 로그를 순환하거나 제거한다.
컨테이너 이미지 중 사용하지 않는 이전 버전을 정리한다.
작업 영역의 중간 산출물을 확인한다. 재생성 가능한 데이터다.
데이터 볼륨과 업로드 원본은 임의로 삭제하지 않는다. 8장으로 요청한다.

8. 지원 요청 경로

단계	대상	요청 사유	연락
1차	업무 부서 담당자	사용 방법, 계정, 권한	{담당자 · 연락처}
2차	인프라 담당	서버 기동, 백업, 복구, 자원	{담당자 · 연락처}
3차	구축 조직	결함, 원인 분석, 재배포	{담당자 · 연락처}

8.1. 요청 시 전달 사항

발생 일시와 재현 여부
영향 범위 — 특정 사용자인지 전원인지, 운영인지 개발인지
화면에 표시된 안내 문구 전문
수행한 1차 조치와 그 결과
관련 SOP 또는 대화 식별자

영향 범위와 1차 조치 결과가 없으면 원인 분석이 처음부터 다시 시작된다. 위 다섯 가지는 반드시 포함한다.

9. 변경 관리

변경 유형	승인	절차
권한 및 범위 변경	업무 부서	관리 화면에서 수행. 감사 기록에 남는다
사용 한도 변경	업무 부서	관리 화면에서 수행
설정 변경	인프라 담당	변경 전 현재 값을 기록한다. 적용 후 기동 로그로 반영을 확인한다
결함 수정 반영	업무 부서 · 인프라 담당	개발 환경에서 확인한 뒤 동일 이미지를 운영에 반입한다. 업무 시간 외에 수행한다
데이터 직접 수정	금지	화면을 통하지 않은 데이터 수정을 수행하지 않는다. 필요한 경우 8장으로 요청한다

세션 서명 키를 변경하면 전체 사용자가 로그아웃된다. 설정 변경 시 이 값을 건드리지 않는다. 부득이하게 변경할 경우 사용자에게 사전 안내한다.

10. 작성 가이드

시스템 운영 매뉴얼은 운영 주체가 실제로 수행 가능한 수준으로 작성한다. 현업 운영인 경우 서버 접속이 필요한 작업과 화면에서 가능한 작업을 반드시 구분하고, 수행 주체를 절차마다 표기한다.

항목명	작성 방법	필수 여부
개요	- 대상 독자별로 읽을 범위를 지정한다. - 자신의 주체가 아닌 절차는 수행하지 않는다는 원칙을 명시한다.	Y
점검	- 일일·주간·월간으로 나누어 확인 항목, 방법, 이상 시 조치를 기술한다. - 일일 점검은 화면에서 가능한 항목으로만 구성한다.	Y
계정 및 권한	- 발급, 범위 부여, 관리자 지정, 락 해제 절차를 기술한다. - 개인정보가 포함된 파일의 취급 기준을 포함한다.	Y
기동 및 정지	- 명령과 유의사항을 함께 기술한다. - 수행 시 발생하는 부작용을 명시한다(진행 중 작업 유실 등).	Y
백업 및 복구	- 백업 구성과 실패 시 조치를 기술한다. - 복구 절차를 순서대로 기술하고 복구 시험 수행을 전제로 한다.	Y
장애 대응	- 증상 기준으로 작성한다. 원인 기준으로 쓰면 운영자가 찾지 못한다. - 1차 조치의 범위를 정하고, 넘어서는 경우 요청 경로로 넘긴다는 원칙을 명시한다.	Y
지원 요청 경로	- 단계별 대상과 연락처를 기술한다. - 요청 시 전달할 항목을 목록으로 기술한다.	Y
변경 관리	- 변경 유형별 승인 주체와 절차를 기술한다. - 금지되는 변경을 명시한다.	Y