SQLVantage 리포트 시스템 사용 설명서（한국어）

1. 시스템 개요
2. 설치 및 배포（Windows / Linux）
3. 설정 설명
4. 관리자 가이드
5. 리포트 설계 가이드（핵심 장）
6. 일반 사용자 가이드
7. 요청 실행과 출력 결과
8. 자주 묻는 질문 FAQ
9. 부록: 데이터 저장과 백업 마이그레이션

1.1 이것은 무엇인가

SQLVantage는 Web 리포트 시스템입니다. 시스템에서 「관리자」가 리포트 정의를 유지 관리하며, 「일반 사용자」는 웹 페이지에서 리포트를 선택하고 쿼리 조건을 입력한 후 비동기로 결과를 받아 Excel / HTML / JSON / TEXT로 내보낼 수 있습니다.

1.2 기술 스택

본 시스템은 순수 Web 아키텍처입니다: 브라우저 측은 어떤 클라이언트나 플러그인도 설치할 필요 없이 최신 브라우저만으로 접속할 수 있으며, 서버 측은 실행 프로그램과 그에 딸린 구성 디렉터리만 있으면 실행할 수 있어 배포가 간단합니다.

1.3 핵심 개념

1.4 사용자 역할

1.5 디렉터리 구조

릴리스 패키지 해제 후의 주요 파일:

SQLVantage/
├── SQLVantage.exe / sqlvantage   # 主程序（Windows / Linux）
├── conf/
│   ├── app.conf        # 系统配置文件（端口/语言/Oracle 等）
│   ├── data.dat        # 业务数据库（用户/职责/报表/请求）
│   ├── license.dat     # 授权文件
│   └── locale/         # 语言包
├── data/               # 运行期生成：<请求ID>.xlsx / <请求ID>.json
├── docs/               # 使用文档（多语言，含 images/）
└── tmp/                # 临时文件（会话、任务）

2.1 환경 요구 사항

• 운영체제: Windows 7+ / 64비트 Linux（x86_64）
• 실행 방법（권장）: 배포된 실행 프로그램（SQLVantage.exe 또는 Linux 바이너리）을 직접 사용. 런타임 설치가 필요 없음
• Oracle 데이터베이스: 리포트 실행을 위해 Oracle에 연결할 수 있어야 함（본 시스템은 기본적으로 Oracle EBS에 연결）. 네트워크와 계정을 미리 확인할 것
• 디스크/디렉터리 권한: 프로그램 실행 디렉터리에 쓰기 권한이 필요. 실행 중 data/, tmp/ 디렉터리가 생성되고 conf/ 아래의 파일을 읽고 쓰기 때문

2.2 Windows 플랫폼 설치

1. 압축 해제: 릴리스 패키지（zip）를 임의의 디렉터리에 압축 해제. 예: D:\SQLVantage\. 해제 후 다음 주요 파일이 존재하는지 확인:

   D:\SQLVantage\
   ├── SQLVantage.exe      # 主程序
   ├── conf\app.conf       # 配置文件
   ├── conf\data.dat       # 数据库（随包附带的空库）
   └── conf\locale\        # 语言包
   

2. （선택 사항）설정 변경: 메모장으로 conf\app.conf를 열어 3장에 따라 리슨 주소, 포트, Oracle 연결 등을 수정.

3. 프로그램 시작: SQLVantage.exe를 더블클릭하거나 명령줄에서 실행:

   cd D:\SQLVantage
   SQLVantage.exe
   

   시작 성공 후 콘솔에 버전 정보와 라이선스 상태가 출력되고 리슨 상태에 진입합니다.

4. 시스템 접속: 브라우저에서 http://127.0.0.1:8080 접속（기본 주소, app.conf에서 변경 가능）.

5. 방화벽 설정: LAN/원격 접속이 필요하면 Windows 방화벽에서 해당 포트（예: 8080）를 허용:

   netsh advfirewall firewall add rule name="SQLVantage" dir=in action=allow protocol=TCP localport=8080
   

2.3 Linux 플랫폼 설치

1. 압축 해제: 릴리스 패키지（tar.gz 또는 zip）를 대상 디렉터리에 압축 해제. 예: /opt/sqlvantage:

   mkdir -p /opt/sqlvantage
   tar -xzf sqlvantage-linux-amd64.tar.gz -C /opt/sqlvantage
   cd /opt/sqlvantage
   

2. 실행 권한 부여:

   chmod +x sqlvantage
   

3. （선택 사항）설정 변경: conf/app.conf 편집（Windows와 동일）.

4. 포그라운드 시작 테스트:

   ./sqlvantage
   

   버전 정보와 리슨 로그가 보이면 시작 성공, Ctrl+C로 종료.

5. 백그라운드 실행（systemd 또는 nohup 권장）:

   방법 A: nohup

   cd /opt/sqlvantage
   nohup ./sqlvantage > sqlvantage.log 2>&1 &
   

   방법 B: systemd（/etc/systemd/system/sqlvantage.service 생성）:

   [Unit]
   Description=SQLVantage Report System
   After=network.target
   
   [Service]
   WorkingDirectory=/opt/sqlvantage
   ExecStart=/opt/sqlvantage/sqlvantage
   Restart=always
   RestartSec=5
   User=sqlvantage
   
   [Install]
   WantedBy=multi-user.target
   

   그런 다음 실행:

   systemctl daemon-reload
   systemctl enable sqlvantage
   systemctl start sqlvantage
   systemctl status sqlvantage
   

6. 방화벽 / 보안 그룹: 포트（예: 8080） 허용:

   firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload
   

2.4 소스에서 컴파일（선택 사항）

소스 코드를 보유한 사용자에게만 제공됩니다: 소스 디렉터리에서 go build를 실행하면 현재 플랫폼의 실행 파일을 컴파일할 수 있습니다. 실제 배포 환경에서는 공식적으로 배포된 실행 프로그램을 직접 사용할 것을 권장합니다.

2.5 최초 시작

최초 시작 시 시스템이 자동으로 다음 초기화를 수행합니다:

1. 데이터 파일 확인: conf/data.dat 읽기（패키지에 포함됨. 없으면 "conf/data.dat is not found" 메시지와 함께 종료되므로 해당 파일을 삭제하지 마세요）.
2. 자동 테이블 생성: user, responsibility, report, request 네 개 테이블 자동 생성.
3. 관리자 계정 자동 생성: /admin/login 최초 접속 시 사용자 root가 없으면 시스템이 자동 생성:
   • 사용자 이름: root
   • 초기 비밀번호: SQLVantage
   • 역할: admin（관리자）
   • 보안 안내: 최초 로그인 후 즉시 비밀번호를 변경하세요（관리자는 「사용자 관리」에서 변경 가능）.
4. 라이선스 파일 확인: conf/license.dat가 없거나 유효하지 않으면 콘솔에 경고가 출력되며, 시스템은 계속 실행되지만 4.7절 라이선스 제한에 따라 제한됩니다.

3.1 설정 파일 위치

설정 파일은 conf/app.conf（INI 형식）입니다. 수정 방법은 두 가지:

• 방법 1（권장, 화면 조작）: 관리자 로그인 후 「시스템 설정」（/admin/setting）에 접속하여 작성 후 저장하면 시스템이 자동으로 app.conf에 다시 기록.
• 방법 2（파일 직접 편집）: 텍스트 편집기로 conf/app.conf를 수정한 후 프로그램 재시작.

3.2 파라미터 설명표

3.3 수정 후 적용

• sessiongcmaxlifetime: 저장 후 즉시 적용.
• 그 외 파라미터（포트, Oracle 등）: 수정 후 프로그램 재시작이 필요.

3.4 언어 전환

• 시스템 내장 12가지 언어: zh-CN, zh-TW, en-US, ja-JP, ko-KR, fr-FR, de-DE, es-ES, th-TH, vi-VN, ru-RU, pt-PT.
• 전환 방법: URL에 ?lang=zh-CN 추가（예: /?lang=zh-CN）, 또는 관리 백엔드 오른쪽 위의 언어 메뉴로 전환. 선택 후 Cookie에 기록되며 유효 기간 1년.

4.1 관리자 로그인

1. 브라우저에서 http://<서버 주소>:<포트>/admin/login 접속.
2. 관리자 계정으로 로그인（최초는 root / SQLVantage）.
3. 로그인 성공 후 관리 백엔드（/admin）에 진입. 왼쪽 메뉴에는 리포트 관리, 책임 관리, 사용자 관리, 요청 관리, 라이선스 관리, 시스템 설정, 대시보드, 정보가 포함됩니다.

참고: 관리자 계정은 반드시 역할 = admin 및 상태 = active를 충족해야 하며, 그렇지 않으면 백엔드에 로그인할 수 없습니다.

4.2 대시보드와 상단 내비게이션

• 상단 내비게이션으로 빠르게 이동 가능: 대시보드（/admin）, 리포트 실행（/request, 새 창）, 포털 홈페이지（/）.
• 오른쪽 위에서 언어 전환, 로그아웃（/admin/logout）.

4.3 사용자 관리

진입점: /admin/user（왼쪽 메뉴 「사용자 관리」）.

사용자 필드 설명:

작업:

• 새로 만들기: 「새로 만들기」 버튼 클릭 → 사용자 이름/이메일/역할/상태/비밀번호/비밀번호 확인 입력 → 제출.
• 편집: 행의 「편집」 클릭 → 이메일, 역할, 상태 변경 가능. 비밀번호는 비워두면 변경하지 않음.
• 삭제: 행의 「삭제」 클릭. 주의:
  • root 계정은 삭제 금지;
  • 명의 아래에 리포트가 있는 사용자는 삭제 금지（먼저 리포트를 삭제/이전해야 함）.

관리 요점:

• 일반 사용자 로그인 진입점은 /login（홈페이지）, 관리자 로그인 진입점은 /admin/login으로 서로 다름.
• 일반 사용자를 inactive 상태로 설정하면 삭제 없이 로그인을 금지할 수 있음.
• 사용자 목록에서 root는 자동으로 숨겨짐.

4.4 책임 관리

진입점: /admin/responsibility（왼쪽 메뉴 「책임 관리」）.

책임 필드 설명:

작업:

• 새로 만들기: 「새로 만들기」 클릭 → 드롭다운에서 사용자의 책임 선택（데이터는 Oracle EBS 쿼리 인터페이스 /api/user/responsibilities/에서 가져옴）. 선택 시 RespId / RespKey / Name 자동 채움. 수동 입력도 가능 → 제출.
• 편집 / 삭제: 행 내 버튼으로 작업. 주의: 이미 리포트에 참조된 책임은 삭제할 수 없음.

용도: 리포트는 반드시 특정 책임에 귀속되어야 하며, 일반 사용자 쪽 「리포트 메뉴」는 책임별로 그룹화되어 표시됩니다（책임에 귀속되지 않은 리포트는 「미분류」 그룹으로 분류）.

4.5 리포트 관리

진입점: /admin/report（왼쪽 메뉴 「리포트 관리」）.

리포트 필드:

리포트 수명 주기（중요）:

Draft（草稿，设计阶段）──▶ Release（已发布，用户可见）
       │                        │
       │                        └──▶ 不可直接删除，需先改为 Draft/Discard
       └──▶ Discard（废弃，用户不可见）

• 상태가 Release인 리포트만 일반 사용자 쪽 리포트 메뉴에 표시됩니다.
• 배포됨（Release）리포트는 삭제 금지, 먼저 목록에서 상태를 Draft 또는 Discard로 변경한 후 삭제해야 합니다.
• 목록의 「이름」「설명」「상태」 열은 셀 더블클릭으로 직접 편집 가능（자동 저장）.

작업:

4.6 요청 관리（관리자 관점）

진입점: /admin/request（왼쪽 메뉴 「요청 관리」）.

관리자는 모든 사용자의 리포트 요청을 확인할 수 있습니다（일반 사용자는 본인 요청만 확인 가능）. 지원:

• 리포트 이름/상태/단계별 조회;
• 파라미터, 제출자, IP 주소, 생성/완료 시간 확인;
• 「출력」 드롭다운에서 해당 요청의 Excel / HTML / JSON / TEXT 결과 직접 다운로드;
• 단일 선택 삭제 또는 체크 후 「일괄 삭제」.

요청 상태의 의미는 7장 참조.

4.7 라이선스 관리（License）

진입점: /admin/license（왼쪽 메뉴 「라이선스 관리」）.

4.7.1 라이선스 파일이란

라이선스 파일은 conf/license.dat로, 공급업체가 발급하는 짧은 텍스트이며 다음 라이선스 정보를 포함합니다:

시스템은 시작 및 가져오기 시 라이선스 파일의 유효성을 자동으로 검증하며, 어떤 변조（등록 정보 또는 만료일 변경）도 라이선스를 무효화합니다.

4.7.2 구매 절차

1. SQLVantage 공급업체/개발사에 연락하여 다음 정보를 제공:
   • 기관/회사 이름（company）;
   • 라이선스를 받을 서버의 등록 ID（reg_id, 공급업체가 배정）;
   • 원하는 라이선스 기간.
2. 공급업체가 라이선스 생성 도구로 라이선스 파일을 생성（텍스트 한 줄）하여 고객에게 전달.
3. 고객은 파일을 받은 후 4.7.3에 따라 가져오면 됩니다.

4.7.3 라이선스 가져오기

1. 관리자 로그인 → 라이선스 관리（/admin/license）.
2. 페이지에 현재 라이선스 상태가 표시됨（등록 ID / 회사 / 만료일. 유효하지 않거나 없으면 빨간색 안내 표시）.
3. 「파일 선택」 클릭 → 받은 라이선스 파일 선택（이름은 임의 지정 가능, 예: license.dat）→ 「가져오기」 클릭.
4. 가져오기 성공 후 시스템이 자동으로 검증하고 페이지를 새로고침하여 유효한 라이선스 정보를 표시.

수동 배치도 가능: 라이선스 파일 내용을 conf/license.dat로 저장한 후 프로그램을 재시작하면 됩니다.

4.7.4 라이선스 없음 / 라이선스 만료 시 제한

4.8 시스템 설정

진입점: /admin/setting（왼쪽 메뉴 「시스템 설정」）, conf/app.conf를 시각적으로 편집:

• 애플리케이션 설정: 리슨 주소, 포트, 실행 모드, 기본 언어, 최대 실행 시간;
• 세션 설정: Session 만료 시간（초）;
• Oracle 데이터베이스 설정: 서버, 포트, 서비스 이름, 사용자 이름, 비밀번호（평문/암호 표시 전환 버튼 포함）.

저장 후 일부 파라미터는 즉시 적용되며, 포트 등의 파라미터는 프로그램 재시작이 필요합니다.

4.9 정보

진입점: /admin/aboutus. 시스템 버전, 릴리스 정보 등을 확인할 수 있습니다.

이것은 SQLVantage의 가장 중요한 기능입니다. 하나의 리포트는 세 부분으로 구성됩니다:

• SQL: 어떤 데이터를 조회할지 정의（데이터 소스 SQL + 컬럼 메타데이터 구성）
• FORM: 사용자가 입력할 쿼리 조건을 정의（파라미터 폼）
• HTML: 결과를 어떻게 표시할지 정의（테이블 / 차트 / KPI 카드 레이아웃）

각 부분은 「코드」와 「형식 JSON」 두 종류의 데이터를 가지며, 최종적으로 리포트 레코드에 저장됩니다.

5.1 디자이너 작업대

5.1.1 디자이너 진입

1. 관리자 로그인 → 리포트 관리（/admin/report）.
2. 대상 리포트를 찾아 「코드」 버튼（보라색）클릭.
3. 대형 디자이너 창이 팝업（화면의 약 98% 차지）, 인터페이스는 좌우 두 영역으로 구성:

┌────────────────────────────────────────────────────────┐
│ [下拉：SQL设计 | FORM设计 | HTML设计]   [保存全部]        │
├───────────────────────────────┬────────────────────────┤
│ 左侧：代码编辑器                │ 右侧：动态设计面板       │
│ （SQL 代码 / FORM 代码 /        │ （随左侧模式切换）      │
│  HTML 代码 共用一个编辑器）     │   · SQL: 列元数据配置表  │
│                               │   · FORM: 参数配置表    │
│                               │   · HTML: 布局块配置表  │
└───────────────────────────────┴────────────────────────┘

5.1.2 세 가지 모드

상단 드롭다운으로 디자인 모드를 전환하며, 전환 시 왼쪽 편집기와 오른쪽 패널이 동기화됩니다:

5.1.3 저장

• 설계 중: 오른쪽 패널의 변경 사항이 자동으로 숨김 필드（sql_code/sql_format/form_code/form_format/html_code/html_format）에 기록됨.
• 공식 저장: 왼쪽 위 「모두 저장」 버튼 클릭 시 6종 데이터를 한 번에 /admin/report/code/로 제출하여 데이터베이스에 저장.

기억하세요: SQL / FORM / HTML 편집 후 반드시 「모두 저장」을 클릭해야 하며, 그렇지 않으면 창을 닫을 때 유실됩니다.

5.2 SQL 모듈（리포트 데이터 소스 설계）

5.2.1 쿼리 SQL 작성

• SQL은 Oracle 문법이며 SELECT 문을 직접 작성（FROM/JOIN/WHERE/GROUP BY 등 포함 가능）.

• 쿼리 조건은 명명 파라미터 플레이스홀더 :파라미터명을 사용하며, 파라미터 이름은 FORM 모듈에서 정의한 field와 일치해야 합니다. 예를 들어 FORM에서 파라미터 P_OU_ID를 정의했다면 SQL에는:

  SELECT company_name, ou_id, amount
    FROM fnd_ou_tl
   WHERE ou_id = :P_OU_ID
  

• SQL에서 SELECT로 출력되는 모든 컬럼 이름이 Excel 내보내기와 HTML 페이지 테이블의 필드 식별자입니다（대문자 통일 권장, 예: COMPANY_NAME）.

5.2.2 컬럼 메타데이터 구성표（중점: Excel 내보내기）

오른쪽 「SQL 컬럼 메타데이터 구성」 테이블의 각 행은 SQL 출력의 한 컬럼에 대응합니다:

작업: 「행 추가」 클릭으로 컬럼 추가 → 셀 더블클릭하여 입력 → JSON 스냅샷 자동 생성（오른쪽 검은색 코드 미리보기 영역）, sql_format에 실시간 기록.

5.2.3 SQL 열 구성과 Excel 내보내기의 대응 관계

시스템 백엔드는 다음 매핑 규칙에 따라 Excel（xlsx）파일을 생성합니다:

즉, SQL 컬럼 구성표 = Excel 내보내기의 「열 헤더 + 열 유형 + 숫자 형식 + 정렬」 완전 정의입니다. 아무 구성도 하지 않아도 Excel은 내보낼 수 있습니다（기본 텍스트 유형, 왼쪽 정렬, 헤더는 원래 컬럼 이름 사용）. 구성한 후 내보낸 Excel이 더 전문적입니다.

5.2.4 완전한 SQL 설계 예시

「부서 비용 리포트」를 만든다고 가정합니다:

1. SQL 코드（편집기）:

   SELECT DEPT_NAME, MONTH, TOTAL_AMOUNT, RATE
     FROM DEPT_COST_V
    WHERE MONTH = :P_MONTH
    ORDER BY DEPT_NAME
   

2. 컬럼 메타데이터 구성:

   field	title	type	precision	format	align
   DEPT_NAME	부서 이름	text			left
   MONTH	월	date		yyyy-mm	center
   TOTAL_AMOUNT	비용 총액	number	2	#,##0.00	right
   RATE	비용 비율	percent	2	0.00%	right

3. 내보낸 Excel 효과: 헤더가 「부서 이름 / 월 / 비용 총액 / 비용 비율」, 금액은 오른쪽 정렬, 천 단위 구분, 소수 2자리, 비율은 백분율로 표시.

5.3 FORM 모듈（쿼리 파라미터 폼 설계）

5.3.1 파라미터 구성표

오른쪽 「파라미터 구성표」의 각 행은 하나의 쿼리 파라미터를 정의합니다:

컴포넌트 유형 표:

5.3.2 파라미터 연동（의존 필터링）

• api_url / query_sql은 {변수명} 플레이스홀더를 지원: 사용자가 상위 파라미터（예: 조직 선택）를 변경하면 시스템이 자동으로 플레이스홀더를 현재 폼의 실제 값으로 치환하여 하위 드롭다운 옵션을 동적으로 요청.
• 상위 파라미터가 입력되지 않으면 하위 드롭다운에 「위 필터 조건을 먼저 완성해 주세요」가 표시되고 옵션이 비워져 오염 데이터를 방지.
• 정적 드롭다운（static_options）과 동적 드롭다운（api_url / query_sql）은 둘 중 하나만 사용하면 됩니다.

드롭다운 동적 옵션의 데이터 형식 요구 사항: 인터페이스/SQL이 반환하는 각 레코드에는 val（값）과 txt（표시 텍스트）두 필드가 포함되어야 합니다.

5.3.3 실시간 미리보기와 코드 생성

• 테이블 아래는 「실시간 미리보기 영역」: 파라미터 구성에 따라 폼（날짜 컨트롤, 연동 드롭다운 등 포함）이 실시간으로 렌더링됨.
• 하단 「폼 코드 초안」 텍스트 상자에 완전한 FORM HTML 코드가 실시간 생성됨.
• 「복사 후 적용」 버튼 클릭: 초안 코드를 편집기（FORM 모드）에 기록하고 form_code / form_format에 동기화.

오른쪽 패널을 사용하지 않고 왼쪽 편집기에서 FORM HTML（폼 문법）을 직접 작성해도 저장 시 동일하게 적용됩니다.

5.3.4 런타임 동작

일반 사용자가 폼을 제출하면 시스템이 폼 데이터를 명명 파라미터로 SQL에 바인딩하여 실행합니다. 동시에 파라미터를 요청에 기록하여 결과 페이지/내보내기 파일에서 쿼리 조건을 다시 표시합니다.

5.4 HTML 모듈（결과 표시 설계）

5.4.1 레이아웃 블록 구성표

오른쪽 「HTML 뷰 컴포넌트 구성」의 각 행은 하나의 표시 블록을 정의합니다:

컴포넌트 설명:

5.4.2 레이아웃 미리보기와 코드 생성

• 「실시간 레이아웃 미리보기」 영역에 각 블록의 고충실도 스켈레톤（제목 + 블록 유형 + 폭）이 실시간 표시됨.
• 「Html Code 초안」에 완전한 HTML 코드가 실시간 생성됨（data-component, data-subtotal, data-charttype, data-xfield, data-yfields 등 런타임 속성 포함）.
• 「복사 후 적용」 클릭 시 편집기에 기록하고 html_code / html_format에 동기화.

왼쪽 편집기에서 HTML 템플릿 조각（일반 템플릿 구문 지원）을 직접 작성할 수도 있습니다. 런타임 렌더링 시 템플릿에서 사용할 수 있는 데이터 객체는 5.4.3 참조.

5.4.3 결과 페이지 렌더링 메커니즘

일반 사용자가 HTML 결과를 다운로드/조회할 때（/request/output?ext=html）, 시스템이 리포트 HTML 코드를 쿼리 결과 JSON, 컬럼 구성 등과 함께 렌더링합니다:

페이지는 자동으로 data-component="table" 컨테이너를 데이터 테이블로, chart는 차트로, card는 KPI 카드로 렌더링합니다.

5.5 리포트 발행 절차（관리자 운영 권장 사항）

1. 报表管理 → 新建报表（选择职责、填名称、状态选 Draft）
2. 点「代码」进入设计器
3. SQL 设计：写查询 SQL + 配置列元数据（Excel 导出依据）
4. FORM 设计：配置查询参数（与 SQL 参数一一对应）
5. HTML 设计：配置展示布局（表格/图表/指标卡）
6. 点「保存全部」→ 关闭设计器
7. 回到报表列表，把状态改为 Release（发布）
8. 普通用户登录即可在报表菜单中看到该报表并执行

5.6 설계 시 유의 사항

• SQL과 FORM의 파라미터 이름은 완전히 일치해야 함（SQL은 :파라미터명, FORM은 field）.
• SQL 컬럼 이름은 대문자 권장. 컬럼 메타데이터 구성표가 field를 자동으로 대문자 변환.
• 리포트 SQL은 Oracle 사전 컴파일（db.Prepare）이 가능해야 하며, 문법 오류가 있으면 요청 실행이 실패함（상태 Error）.
• 미인가 상태에서 리포트 수량 상한은 3개. 설계 전에 라이선스 상태를 확인할 것.
• 저장 후 「요청 관리」 또는 일반 사용자 쪽에서 요청을 한 번 실행하여 SQL과 표시가 올바른지 검증할 수 있음.

6.1 로그인

브라우저에서 시스템 홈페이지（기본 http://<서버 주소>:<포트>/）에 접속한 후 「사용자 로그인」 카드 클릭 → 로그인 페이지 /login 진입. 로그인 페이지는 두 가지 로그인 방식（탭 전환）을 제공합니다:

방식 1: ERP 인증（Oracle EBS 단일 로그인）

1. 「ERP 인증」 탭으로 전환.
2. EBS 사용자 이름（예: APPS）입력 후 「인증 로그인」 클릭.
3. 시스템이 Oracle을 통해 해당 사용자의 EBS icx_sessions 세션이 유효한지 확인（30분 유효 창）. 유효하면 바로 시스템에 진입.
4. 특징: 로컬 비밀번호 불필요. 로그인 신원은 사용자의 EBS 신원.

방식 2: 로컬 계정

1. 「로컬 계정」 탭으로 전환.
2. 관리자가 배정한 사용자 이름과 비밀번호 입력 후 「로그인」 클릭.
3. 특징: 계정은 관리자가 「사용자 관리」에서 생성.

참고: 계정이 관리자에 의해 inactive（퇴사）로 설정되면 로그인할 수 없습니다.

6.2 포털 홈페이지

로그인 성공 후 포털 홈페이지（/）에 진입하며 다음을 포함합니다:

• 상단: 환영 문구（사용자 이름）, 비밀번호 변경 진입점.
• 내비게이션 카드:
  • 새 리포트 요청（리포트 실행 페이지 /request로 진입）;
  • 내 요청（과거 요청과 결과 확인）;
  • 관리자 로그인, 시스템 설정, 라이선스 관리, 정보 등 카드（일반 사용자는 사용할 필요 없음. 클릭 시 관리자 로그인 페이지로 이동）.
• 오른쪽 위에서 인터페이스 언어 전환 가능.

6.3 새 리포트 요청

1. 포털 홈페이지에서 「새 리포트 요청」 카드 클릭, 또는 /request 직접 접속.
2. 요청 목록 페이지에서 「새로 만들기」 버튼 클릭.
3. 「리포트 메뉴」 창 팝업: 리포트가 책임（모듈）별로 그룹화되어 표시되며, 배포됨（Release）리포트만 표시됩니다. 상단 드롭다운에서 이름으로 검색할 수도 있습니다.
4. 리포트 클릭 시 오른쪽에 해당 리포트의 파라미터 폼이 로드됨.
5. 쿼리 조건（날짜/드롭다운/텍스트 등）입력 후 「제출」 클릭.
6. 제출 성공 후 요청 목록에 새 레코드가 표시되며 상태는 Queued（대기 중）.

6.4 내 요청 목록

진입점: /request（상단에서도 포털 카드로 진입 가능）.

작업: 행의 「출력」 드롭다운 클릭 → Excel / HTML / JSON / TEXT 선택 → 새 창에서 열거나 해당 형식의 결과 파일 다운로드.

6.5 비밀번호 변경

1. 포털 홈페이지 상단에서 「비밀번호 변경」 클릭.
2. 현재 비밀번호, 새 비밀번호, 새 비밀번호 확인 입력（새 비밀번호는 최소 6자리）.
3. 제출 성공 후 새 비밀번호로 로그인 가능（로컬 계정 로그인에만 적용. ERP 인증 방식은 EBS 비밀번호와 무관）.

7.1 실행 흐름（비동기）

用户提交请求
   │
   ▼
写入 request 表（Phase=Pending, Status=Queued）
   │
   ▼
后台轮询协程（每 3 秒）拉取排队任务（每批最多 5 个，并发最多 3 个）
   │
   ▼
乐观锁抢占任务 → Phase=Running, Status=Processing
   │
   ▼
解析参数 → 读取报表 SQL → Oracle 预编译执行
   │
   ├── 失败 → Status=Error（记录错误消息）
   │
   ▼
生成结果文件：data/<请求ID>.xlsx 与 data/<请求ID>.json
   │
   ▼
Phase=Completed, Status=Success

• 시간 초과 보호: max_execution_time（기본 30분）을 초과하는 작업은 자동으로 Terminated로 표시됩니다.
• 결과 파일은 요청 ID별로 data/ 디렉터리에 저장되어 서로 덮어쓰지 않습니다.

7.2 출력 형식

7.3 권한 제어

• 일반 사용자는 본인이 제출한 요청만 확인 가능（생성자 기준 필터링）.
• 관리자는 「요청 관리」에서 모든 사용자의 요청을 확인 가능.
• ERP 로그인 사용자가 제출할 때 폼에 P_OU_ID / P_ORG_ID 등 조직 권한 파라미터가 포함되어 있으면, 시스템이 해당 값이 사용자의 EBS 소유 OU/ORG 범위 내에 있는지 검증하며, 권한 밖의 값은 거부됩니다.

Q1: 시작 시 "conf/data.dat is not found" 오류가 발생하나요? 데이터베이스 파일 누락. 압축 해제가 완전한지, conf/data.dat가 존재하는지 확인하세요. 빈 파일로 대체하지 말고 릴리스 패키지에 포함된 데이터베이스 파일을 사용해야 합니다.

Q2: 브라우저에서 페이지가 열리지 않나요? 프로그램이 시작되었는지 확인. httpaddr/httpport 설정이 올바른지 확인（기본 127.0.0.1:8080. 로컬 접속은 OK, 다른 머신에서 접속하려면 0.0.0.0으로 변경하고 방화벽 포트를 허용해야 함）.

Q3: 로그인 시 계정 또는 비밀번호 오류가 표시되나요?

• 로컬 계정: 사용자 이름/비밀번호가 올바른지, 상태가 active인지 확인.
• 관리자: 역할이 admin인지 확인.
• 비밀번호 분실: 관리자에게 「사용자 관리」에서 초기화를 요청.

Q4: 리포트 요청 제출 후 상태가 계속 Error인가요? 대부분 SQL 문법 오류 또는 Oracle 연결 문제. 요청 「메시지」 열의 오류 정보를 확인: Prepare statement failed는 SQL 사전 컴파일 실패, Oracle connection failed는 데이터베이스 연결 설정 오류를 의미（app.conf의 oracle_* 파라미터 확인）.

Q5: 리포트가 일반 사용자 메뉴에 보이지 않나요? 리포트 상태가 Release인지 확인（배포된 리포트만 표시됨）.

Q6: 요청이 오래 Running 상태인가요? 실행 시간이 max_execution_time 분을 초과하면 자동 종료됩니다. 해당 파라미터를 적절히 늘린 후 재시작할 수 있습니다.

Q7: 리포트 생성 시 라이선스 상한 안내가 표시되나요? 유효한 라이선스 파일을 가져오지 않았거나（만료됨）미인가 상태에서 최대 3개 리포트. 4.7절에 따라 라이선스를 가져오세요.

Q8: Excel 내보내기 열 헤더가 영문 컬럼 이름인가요? SQL 컬럼 메타데이터 구성에 title이 없거나 SQL 출력 컬럼 이름과 매칭되지 않음. 「SQL 설계」의 컬럼 구성표에서 field를 SQL 출력 컬럼과 일치하게 입력하고 title을 채우세요.

Q9: Oracle 비밀번호 변경 후에도 시스템이 이전 비밀번호로 연결하나요? conf/app.conf에서 oracle_password 수정 후 프로그램 재시작 필요.

Q10: 포트 변경이 적용되지 않나요? app.conf 수정 후 재시작 필요. 「시스템 설정」 페이지에서 수정해도 됨（동일하게 재시작 필요）.

9.1 데이터 저장 위치

9.2 백업 권장 사항

• 최소 백업 세트: conf/（app.conf + data.dat + license.dat）+ 선택적으로 data/（과거 결과）.
• 전체 백업: 전체 프로그램 디렉터리（conf/, data/ 포함）.

9.3 새 서버로 마이그레이션

1. 대상 머신에 2장에 따라 동일 버전 프로그램 배포.
2. 이전 프로그램 중지 → conf/（app.conf, data.dat, license.dat）를 새 머신의 해당 위치에 복사.
3. 과거 결과가 필요하면 data/도 함께 복사.
4. 새 프로그램 시작 후 설정（Oracle 주소, 포트 등）이 새 환경에 맞는지 확인.

9.4 본 문서（다국어 버전）의 마이그레이션과 온라인 열람

• 본 설명서는 프로그램 디렉터리 docs/ 아래에 언어별로 저장됩니다: zh-CN.md, zh-TW.md, en-US.md, ja-JP.md, ko-KR.md, fr-FR.md, de-DE.md, es-ES.md, th-TH.md, vi-VN.md, ru-RU.md, pt-PT.md.
• 이미지는 docs/images/ 디렉터리에 통일 저장되며, 문서 내에서는 로컬 상대 경로로 참조합니다（예: ![예시](images/xxx.png)）. 타사 원격 이미지 링크는 없습니다. 문서를 마이그레이션할 때 docs/images/ 디렉터리를 함께 복사하면 이미지도 함께 이동합니다.
• 온라인 열람: 모든 .md 파일은 순수 Markdown이며, Gitea / GitHub / GitLab / Gitee 등 플랫폼의 문서 저장소에서 추가 도구 없이 온라인 렌더링 열람 가능.
• 각 언어 버전의 내용은 동일하며, 진입점은 docs/README.md 인덱스 참조.