설치와 연결을 마치고
안전한 모드부터 시작하세요.

01 / BEFORE YOU START

시작 전

TrueFix Studio는 시장 조사, 전략 테스트, 거래 전 확인을 위한 데스크톱 앱입니다. 자금을 보관하지 않으며 증권사나 거래소를 대신하지 않습니다. 공식 Nightly 버전을 설치하고 필요한 서비스만 연결하세요.

02 / FIRST RUN

처음 실행한 뒤 15분

1. 1

   워크스페이스 열기

   이전에 선택한 시장과 패널 배치를 복구할 수 있습니다. 복구할 수 없으면 안전한 기본 화면이 열립니다.

2. 2

   상단 상태 확인

   한 서비스가 사용할 수 없어도 앱에는 들어갈 수 있습니다. 해당 서비스를 쓰기 전 복구를 기다리거나 표시된 오류를 확인하세요.

3. 3

   테스트 서비스 하나 연결

   시세 데이터나 모의 거래 서비스 하나부터 연결하세요. 종목을 검색하고 가격 출처를 확인한 뒤 전송하지 않는 주문을 만들어 봅니다.

고급 섹션에서 쓰는 용어

Provider는 증권사, 거래소, 데이터, AI 서비스를 뜻합니다. ClientInstance는 저장한 하나의 연결이고, Environment는 테스트용인지 실거래용인지를 나타냅니다. 설정 화면과 맞춰 볼 수 있도록 고급 섹션에서는 영어 이름도 함께 씁니다.

03 / PROVIDER CENTRE

Provider와 ClientInstance 구성

연결 관리에서 전체 연결 센터 열기를 선택해 Provider Centre로 이동합니다. Add monitoring ClientInstance 양식에 ID, Provider slug, 표시 이름, 시장, 상품 범위와 실제 환경을 입력합니다. 연결 매개변수는 화면의 Connection JSON 입력란에 작성합니다. Historical/Realtime과 필요한 경우 Connect after saving을 선택하고 Save monitoring ClientInstance를 누릅니다. 이 양식은 시세 모니터링용이며 거래 권한을 만들지 않습니다.

• Provider 스키마가 인스턴스 재구성 전 설정을 검증합니다.
• Secret은 쓰기 전용이며 원본 값을 다시 보여 주지 않습니다.
• 연결됨은 거래 가능을 의미하지 않습니다. capability, entitlement, 계정, 정확한 종목 mapping, 환경, health를 모두 확인하세요.

저장 후 확인

Paper와 Live는 별도 ClientInstance로 만들고 broker-paper-us / broker-live-us처럼 분명하게 이름을 지정하세요.

04 / MARKET CONTEXT

종목과 시장 소스 선택

전역 검색에서 canonical Instrument를 선택하세요. Historical, Realtime, Trading 경로는 독립적으로 해결됩니다.

Provider, ClientInstance, quality, timestamp를 항상 확인하세요. 정확한 mapping이 없으면 경로가 거부되며 비슷한 symbol을 같은 종목으로 추측하지 않습니다.

06 / PORTFOLIO

계정, 포지션, 주문, 체결

Portfolio는 권위 있는 거래 투영을 읽고 Provider, ClientInstance, 계정, 환경으로 필터링합니다. 앱 주문과 외부/알 수 없는 주문은 분리됩니다.

• 일관된 FX revision 없이 서로 다른 통화를 합산하지 않습니다.
• partial 또는 stale 평가는 상태를 유지하며 완전한 자본으로 표시되지 않습니다.
• Provider 연결 해제 또는 환경 전환 후 이전 계정 영역은 현재 작업에 참여하지 않습니다.

08 / AGENT

Agent 구성 및 사용

Agent는 권한이 제한된 운영 도우미이며 자율 거래 봇이 아닙니다. 승인된 TrueFix 도구로 종목, 시장 데이터, 뉴스, Signal, 계정, Quant 상태를 읽고 거래 요청은 검토 가능한 제안으로만 만듭니다. 사용 가능한 도구는 테스트 빌드마다 다를 수 있으므로 실행 타임라인을 기준으로 확인하세요.

A. 모델 구성

Desktop의 설정 → AI 양식에서 API Key와 모델 ID를 입력하고 저장합니다. 모델 요청 매개변수 JSON은 화면 입력란의 내용이며 앱이 저장합니다.

1. 1

   설정 → AI

   “AI trading agents”에서 추가를 선택합니다.

2. 2

   연결 정보

   표시 이름, Provider(OpenAI / Anthropic / Google / Custom), API Key, 모델 ID를 입력합니다. 호환 게이트웨이를 사용할 때만 Base URL을 지정합니다.

3. 3

   추가 매개변수

   모델 요청 매개변수는 {"enable_thinking": false} 같은 JSON 객체여야 합니다. 필요 없으면 {}를 유지하고 Secret은 넣지 마세요.

4. 4

   활성화 및 저장

   기존 Agent 편집 시 API Key를 비워 두면 저장된 키를 유지합니다. 저장 후 활성 상태를 확인합니다.

B. 안전한 세션 실행

1. 1

   Agent 열기

   Desktop, Web Desktop 또는 H5 하단 명령 바에서 새 세션을 만들고 활성 모델을 선택합니다.

2. 2

   범위 명시

   종목, 시장, 기간, 선호 소스, 목표를 알려 주세요. 계정 작업은 Environment를 명시하고 Simulator/Testnet부터 시작합니다.

3. 3

   타임라인 확인

   admission, model, tool, approval, final 상태와 Provider, ClientInstance, 시간, freshness, evidence를 확인합니다.

4. 4

   결과 검토

   사실, 추론, 상관관계를 구분합니다. stale, degraded, 거부 또는 소스 부족이면 질문 범위를 줄이거나 데이터 연결을 먼저 복구하세요.

5. 5

   거래 제안 처리

   Approval Card의 종목, 방향, 수량, 계정, 환경, 만료, 증거를 확인합니다. 승인 후에도 Review, RiskGuard, 명시적 제출이 필요하며 거부/만료 시 주문되지 않습니다.

10 / WEB GATEWAY & ACME

브라우저 접속과 HTTPS 구성

Desktop의 설정 → Web Gateway 화면에서 설정합니다. 아래의 로컬 또는 원격 접속 절차에 따라 필요한 수신 주소, 도메인과 HTTPS 항목을 입력하고 활성화 및 저장 및 적용을 선택합니다. 앱이 설정을 저장하고 적용하며 Desktop Kernel과 Provider 연결은 중단되지 않습니다. DNS 레코드와 방화벽은 DNS 서비스나 네트워크 관리 화면에서 설정합니다.

A. 로컬 접속

1. 1

   설정 → Web Gateway

   이 화면에서 임의 비밀번호 생성 버튼을 누르고 즉시 복사하거나, 사용자 지정 접근 비밀번호에 12자 이상을 입력한 후 비밀번호 변경을 누릅니다. 두 작업 모두 기존 Web/H5 세션을 폐기합니다. 저장 및 적용은 Gateway 설정만 저장하며 비밀번호는 변경하지 않습니다.

2. 2

   loopback 전용

   HTTPS 인증서에서 로컬 HTTP를 선택하고 수신 주소에 127.0.0.1 또는 ::1, 서비스 포트를 입력합니다. 활성화를 선택하고 저장 및 적용을 누른 뒤 화면에 표시된 접속 URL을 엽니다.

3. 3

   표시된 URL 열기

   비밀번호로 로그인합니다. “로그인 유지”는 장치 세션만 연장하며 거래 권한은 늘리지 않습니다.

B. 원격 접속

1. 1

   DNS

   studio.example.com의 A/AAAA를 Gateway 공인 주소로 지정합니다. IPv6가 서비스에 도달하지 못하면 잘못된 AAAA를 삭제합니다.

2. 2

   공개 주소

   허용 도메인에는 프로토콜, 포트, 경로 없는 DNS 이름만 넣습니다. 공개 접속 URL은 최종 https:// 전체 URL입니다. 와일드카드 host는 허용되지 않습니다.

3. 3

   TLS

   기존 인증서를 사용하려면 HTTPS 인증서에서 자체 인증서를 선택하고 화면의 인증서 PEM 경로와 개인 키 PEM 경로를 입력합니다. 자동 인증서는 Let’s Encrypt를 선택하고 ACME 이메일과 검증 방식을 설정합니다. DNS-01의 Cloudflare Zone ID와 API Token도 같은 양식에 입력합니다.

C. 권장 ACME 적용 순서

1. 1

   설정 → Web Gateway의 HTTPS 인증서에서 Let’s Encrypt를 선택합니다.

2. 2

   허용 도메인에 studio.example.com, 공개 접속 URL에 https://studio.example.com을 입력합니다.

3. 3

   ACME Directory 입력란에 https://acme-staging-v02.api.letsencrypt.org/directory를 입력하고 이메일, 검증 방식 및 필수 항목을 설정합니다.

4. 4

   활성화를 선택하고 저장 및 적용을 눌러 화면의 실행 상태와 인증서 상태를 확인합니다. 브라우저가 Staging 인증서를 신뢰하지 않는 것은 정상입니다.

5. 5

   확인 후 같은 ACME Directory 입력란을 https://acme-v02.api.letsencrypt.org/directory로 변경하고 다시 저장 및 적용을 누릅니다. 발급자, 도메인과 만료일을 확인합니다.

Staging 인증서가 브라우저에서 신뢰되지 않는 것은 정상입니다. HTTP-01은 공개 /.well-known/acme-challenge/* 경로를 그대로 유지해야 합니다. DNS-01은 대상 Zone에만 적용되는 최소 권한 DNS:Edit Token을 사용하고 Global API Key는 사용하지 마세요.

D. 세션과 장치

• “로그인 유지”는 회전식 HttpOnly Refresh Cookie를 사용하며 JavaScript나 URL에 들어가지 않습니다.
• Desktop 설정에서 Web 장치를 개별 해지할 수 있습니다. 로그아웃, 전체 로그아웃, 비밀번호 변경, Gateway 중지도 해당 세션을 해지합니다.
• ?workspace=<id>로 workspace를 지정할 수 있으며 기본값은 main-workspace입니다.

11 / OPERATIONS & AUDIT

운영, 로그와 감사

Operations는 언제, 누가, 무엇을, 어느 범위에서 수행했는지 조사하는 곳입니다. Logs는 회전할 수 있지만 거래/보안 Audit는 내구 기록입니다. 새 로그가 없다는 사실은 건강 상태를 증명하지 않습니다.

문제를 보고하기 전에

1. 1

   시간과 환경 기록

   시간대, Environment, Provider와 ClientInstance를 포함하세요.

2. 2

   안정적인 증거 저장

   error code, correlation ID, revision과 freshness를 남기고 비밀 정보는 제외하세요.

3. 3

   기대 결과와 실제 결과 설명

   재현 단계와 Live 또는 외부 주문에 미친 영향을 적으세요.

12 / STATUS GLOSSARY

알 수 없음을 0으로 만들지 않는 상태 용어

source, as-of, revision, stable code를 함께 확인하세요.

13 / ARCHITECTURE

아키텍처와 데이터 경계

브라우저는 종목, 계정, 주문, 시장 데이터, 리스크, AI/Quant의 권위 있는 소유자가 아닙니다. 모든 진입점은 canonical contracts를 공유하고 원본 adapter provenance를 유지합니다.

14 / TROUBLESHOOTING

자주 묻는 질문