StellaNet_r1

[[분류:StellaNet]]
[목차]

== 개요 ==
StellaNet은 세계관 위키를 보조하는 단순한 도구가 아니라, '''세계관 전체를 하나의 로컬 웹 애플리케이션으로 통합'''한 것이다. 다음 여섯 가지 기능이 하나의 데이터 위에서 동작한다.

* '''세계관 데이터베이스''' — 성계, 행성, 함선, 인물, 조직 등 모든 Entity를 구조화된 형태로 관리
* '''전략지도(Atlas)''' — 성계 간 거리·항로·세력권을 실제 좌표 기반으로 시각화
* '''민간/군사 교통''' — JR Misaki 철도망을 포함한 교통 체계 시뮬레이션
* '''WarSim''' — Canon과 분리된 전쟁 시뮬레이션 브랜치
* '''Stella Assistant''' — OpenAI/Anthropic/Gemini를 연결한 AI 설정 보조
* '''the tree 연동''' — Namumark 매크로로 위키 문서에 지도·시간표 등을 임베드

=== 만든 이유 ===
지금까지 세계관 설정은 대화와 나무마크 문서로 흩어져 있었고, 연도 환산(ISF 기년 ↔ 서기), 성계 간 거리, 함대 병력 같은 수치가 문서마다 따로 관리되며 어긋나는 문제가 반복됐다. StellaNet은 이런 수치를 '''하나의 데이터베이스에 한 번만 기록'''하고, 위키·지도·시간표·AI 어시스턴트가 모두 그 데이터를 참조하도록 만들어 이 문제를 구조적으로 없애기 위해 만들어졌다.

핵심은 '''Working DB와 Public Snapshot의 분리'''다. 작업 중인 데이터(`db.json`)와 실제로 공개되는 데이터(`published.json`)가 나뉘어 있어서, 아직 확정되지 않은 설정을 자유롭게 실험해도 위키에는 영향을 주지 않는다.

== 핵심 개념 ==
=== Canon 상태 체계 ===
모든 Entity(성계, 함선, 인물 등)는 다섯 가지 상태 중 하나를 가진다.

||<tablewidth=100%><rowbgcolor=#003399,#003399><rowcolor=#fff> '''상태''' || '''의미''' ||
||<rowbgcolor=#f8f9fa,#1c1d1f> `canon` || 확정 설정 ||
|| `draft` || 작업 중, 아직 확정 아님 ||
|| `synthetic` || 지도 확장·시뮬레이션용 자동 생성 데이터 ||
|| `verify` || 과거 언급은 있으나 현행 확정 필요 ||
|| `legacy` || 구설정 보존용 ||

작업 흐름은 항상 Draft → Validation → Canon 순서를 따른다. AI 제안이나 WarSim 결과는 자동으로 Canon이 되지 않으며, 사람이 직접 검토하고 확정해야 한다.

=== Canon Lock ===
확정된 Entity는 Lock을 걸어 실수로 덮어써지는 것을 막을 수 있다. AI 작업에서도 이 경계는 유지된다.

=== Working DB와 Published Snapshot ===
* '''Working DB'''(`data/db.json`) — 실제로 편집하는 데이터. Draft, Verify, 실험적 설정이 모두 여기 섞여 있어도 된다.
* '''Published Snapshot'''(`data/published.json`) — `Publish Validated Snapshot`을 실행해야 만들어지는 공개용 데이터. Draft와 기밀(Secret/Top Secret) 항목은 자동으로 제외된다.
* the tree embed와 Public API는 기본적으로 Published 데이터를 사용하도록 설계되어 있다.

=== Snapshot과 백업 습관 ===
Snapshot은 DB 전체 상태를 저장하는 백업이다. 큰 작업 전에는 반드시 만들어 두고, `Command Center`의 `Auto snapshot before Save All`을 켜 두면 저장할 때마다 자동으로 생성된다.

== 시작하기 ==
=== 설치 ===
압축을 풀고(예: `C:\StellaNet\StellaNet-v3.26.1`), Node.js가 설치된 상태에서 프로젝트 폴더에서 다음을 실행한다.

{{{
npm install
npm start
}}}

=== 기본 주소 ===
||<tablewidth=100%><rowbgcolor=#003399,#003399><rowcolor=#fff> '''화면''' || '''주소''' ||
||<rowbgcolor=#f8f9fa,#1c1d1f> Viewer(열람용) || `http://127.0.0.1:3210/embed` ||
|| Editor(편집용) || `http://127.0.0.1:3210/editor` ||

=== 첫 실행 후 권장 순서 ===
# `Editor` 접속
# `Validation & Tools`에서 전체 상태 확인
# Snapshot 생성
# `QOL Studio → World Health` 실행
# `Civil & Transit` 또는 `Entities`에서 실제 작업 시작
# 작업 후 `Save all`
# 다시 Validation
# Canon으로 확정할 것만 확정
# `Publish & API`에서 Public Snapshot 생성

=== 알아둘 점 ===
* localhost에서만 쓰면 Editor Token 없이도 편집할 수 있다. 외부 기기에서 쓰려면 `STELLANET_EDITOR_TOKEN` 환경 변수를 설정해야 한다.
* AI Provider 키(OpenAI/Anthropic/Gemini)는 UI에 입력해도 서버 재시작 시 사라진다. 계속 쓸 키는 환경 변수(`OPENAI_API_KEY` 등)로 등록하는 것이 안전하다.

== 핵심 워크스페이스 개관 ==
||<tablewidth=100%><rowbgcolor=#003399,#003399><rowcolor=#fff> '''워크스페이스''' || '''역할''' ||
||<rowbgcolor=#f8f9fa,#1c1d1f> Entities || 성계·행성·함선·인물·조직 등 모든 Entity를 만들고 편집. Template로 기본 구조 생성, Canon Status·Canon Lock 관리 ||
|| Atlas Layout || 성계 위치와 Territory Border(세력 경계)를 직접 편집. 수동 폴리곤이 권위 데이터이며 자동 재생성되지 않음 ||
|| World Data || 대량 Events, Relationships, Operations 등 개별 Entity Editor로 다루기 어려운 JSON 데이터를 직접 편집 ||
|| Validation & Tools || 데이터 무결성 검사, Dependency/Impact 확인, Distance Constraints 검증, Snapshot 관리, Bulk Import/Export ||
|| Command Center || 군사·전략·정보 통합 화면. World Dashboard, Order of Battle, Mission Planner, DEFCON, Intel, Wiki Generator 등 ||
|| Civil & Transit || JR Misaki 등 민간 교통망 편집. Line, Station, Platform, Service, Trip, Headway Generator, PIDS ||
|| Stella Assistant || AI(OpenAI/Anthropic/Gemini)에게 데이터 검토·제안을 요청. Draft Changeset으로만 반영되며 Canon은 직접 결정 ||
|| WarSim || Canon Timeline과 분리된 전쟁 시뮬레이션 Branch. 전투 결과는 Draft Changeset으로 제안된 뒤 검토를 거쳐야 Canon화 ||
|| Publish & API || Working DB를 검증 후 Public Snapshot으로 발행. Publish는 Validation Error가 있으면 차단됨 ||
|| World Lab || 인구·경제·건설 프로젝트 등 대규모 민간 세계 시뮬레이션과 GeoJSON/OpenAPI 연동 ||
|| QOL Studio || World Health 점검, 삭제 전 Dependency 확인, 복구·지원(Support Bundle), Embed Preview 등 운영 보조 도구 모음 ||

== 실전 워크플로 ==
=== 새 성계 만들기 ===
Snapshot → `Entities → New → System Template` → 이름/Canon/좌표 입력 → `Atlas Layout`에서 위치 조정 → Territory 지정 → Distance Constraint 확인 → Validation → Save All

=== JR Misaki 노선 만들기 ===
Snapshot → `Civil & Transit`에서 `jr-misaki-network` 확인 → Line Draft 생성 → Stations Draft 생성 → Platforms 생성 → Service 생성 → Headway Generator → Platform Conflict 검사 → PIDS 확인 → Journey Planner 확인 → Validation → Canon 검토 → Publish

=== WarSim 캠페인 만들기 ===
Snapshot → Military Readiness/OOB 정리 → `WarSim → New Scenario`(Faction/Objective/Force IDs 입력) → Create Simulation Branch → Run Turns → 전투 발생 확인 → 필요 시 Fork → Story Studio/Markup → Draft Changeset 제안 → Dependency + Validation → 필요한 결과만 Canon

=== AI로 설정 보조받기 ===
AI Key 설정 → Permission을 `Safe`로 → Inspect Context → Prompt 입력 → 결과 확인 → Changeset Review → Dependency/Dry Run → Apply Draft → Validation → Canon 여부는 직접 결정

=== the tree 문서에 지도 넣기 ===
Editor에서 Atlas 범위 확인 → Publish → `QOL Studio → Embed Preview` → `Publish & API → Embed Builder` → Namumark 복사 → the tree 문서에 삽입

== 운영 원칙 요약 ==
# 작업 전 Snapshot
# 새 데이터는 Draft로
# AI/WarSim 결과는 Canon 아님 — 사람이 직접 검토
# Territory Border는 수동 Polygon이 권위 데이터
# JR Misaki 운행은 Service → Trip → Schedule → Platform 구조 유지
# 삭제 전 Dependency Scan
# Publish 전 Validation
# Public Wiki(the tree)는 Published Snapshot만 사용
# 모바일 Offline에는 Published 데이터만 캐싱
# 문제가 생기면 Support Bundle 생성 + `npm run verify`

== 문제 발생 시 복구 ==
||<tablewidth=100%><rowbgcolor=#003399,#003399><rowcolor=#fff> '''상황''' || '''대응''' ||
||<rowbgcolor=#f8f9fa,#1c1d1f> Entity를 잘못 삭제 || `QOL Studio`/`Command Center → Trash / Recovery → Restore` ||
|| DB 작업을 크게 망침 || `Validation & Tools → Snapshot → Restore` ||
|| Editor 화면이 이상함 || 서버 재시작 → 강력 새로고침 → PWA 캐시 확인 → `npm run selftest` → `QOL Studio → Recovery / Support` → Support Bundle 생성 ||
|| 버그 신고 자료가 필요함 || `QOL Studio → Recovery / Support → Download Support Bundle` ||
|| 직접 DB 복구 || 서버 종료 후 `data/db.json`을 백업본으로 교체 (원본은 반드시 별도 보관) ||
StellaNet r1

StellaNet_r1
