nexus 프로그램 명세서 (클로드 디자인 빌드용)

목적: 클로드 디자인이 이 문서만으로 nexus 프로그램(UI+연동)을 완성할 수 있게 하는 완전 명세. 근거: 2026-07-17 실측 현황(정본 19/19 컴파일·규칙표 4도메인 무결·서비스 200·6도메인 회귀 6/6). 원칙: 판정 로직=한선씨 정본, UI/오케스트레이션=이 명세 대상. 백엔드는 이미 존재·검증됨.

---

1. 제품 개요

nexus = 한선씨 1레이어 규칙기반 의사결정 고도화 도구 (SAP BRF+ / 팔란티어 파운드리 대응).

• 자연어 입력 → 도메인 판별 → 규칙엔진 판정 → 4상 결정 → 안전 게이트 → 감사 기록.
• 비개발자가 규칙표를 웹에서 편집·검증·버전관리, 결정을 재현·시뮬레이션(what-if).
• 실리콘스핀 4상균형3진 양자컴퓨팅·단백질 메모리 적용 고려(미래 확장).

4상 (모든 결정의 통일 언어)

상	의미	색(권장)
티(T)	실행·승인·YES (안전·확신)	초록 계열
옴(O)	보완·주의·저확신 (경고 후 실행/재확인)	황색 계열
타(A)	거부·정책위반 (차단)	적색 계열
음(U)	상신·이관 (사람 승인 필요)	청색/보라 계열

크라우니디자인 4상 토큰이 있으면 그것을 SSOT로. 현재 감사서버 UI는 --ti/--om/--ta/--eum CSS 변수 사용.

---

2. 사용자·역할 (RBAC)

• 관리자: 전 규칙표 편집·롤백. (첫 가입 계정 자동 부트스트랩)
• 편집자: 배분·일정·휴가 규칙표만 편집(승인규칙 차단).
• 미인증: 조회·시뮬레이션만(편집 403).
• 역할×규칙표 매트릭스 = data/규칙권한매트릭스.psv (erp 권한검증.한선 연동, 기능허용(역할, 규칙표)).

---

3. 아키텍처

[사용자 자연어/팩트]
      │
      ▼
넥서스.js  결정(입력)              ← 마스터 디스패처(단일 엔트리)
      │
      ├─ 도메인판별.한선 (키워드+금액 → 6도메인)
      │      우선순위: 배분 > 휴가 > 승인/금액 > 일정 > 조회 > 명령
      ▼
[도메인별 엔진 JS] → 팩트추출 → 규칙엔진.한선(규칙표.psv) → 결정|사상|발동규칙|근거
      │
      ├─ 승인: 승인규칙엔진.js + 승인규칙2.psv
      ├─ 배분: 배분엔진.js + 배분규칙.psv
      ├─ 일정: 일정엔진.js + 일정규칙.psv
      ├─ 조회: 조회엔진.js + 엣지존재.한선(147k 저장소 멤버십)
      ├─ 휴가: 휴가엔진.js + 휴가규칙.psv
      └─ 명령: 의사결정코어.js(라우터→슬롯→행동스펙→위험게이트→사상판정.한선)
      │
      ▼
[통일 4상] → 안전(파괴→음→승인큐 이관) → 감사기록(넥서스_감사.psv)

• 판정 로직 = 한선씨 정본(.한선→.toau). JS는 팩트추출·오케스트레이션·파일IO만.
• 범용 규칙엔진 1개(규칙엔진.한선)가 전 도메인 구동. 새 도메인 = 규칙표 psv + 팩트추출 JS 추가.

---

4. 핵심 기능 (전부 백엔드 구현·검증됨 — UI가 감싸야 할 것)

4.1 라이브 결정 콘솔

• 입력바에서 자연어 결정 제출 → 넥서스 5도메인 라우팅 → 4상·발동규칙 표시.
• 5초 자동 폴링(●라이브) — 다른 세션 결정도 실시간 반영.

4.2 감사·리플레이

• 전 결정 흐름 가시화: 입력→도메인→이해→판단→안전→4상→출력 (스테이지 카드).
• 4상·도메인 통계 + 필터.
• 재현(결정론): 각 행 ↻재현 → 넥서스 재실행 → 원본 사상 대조(일치 ✓/불일치 ✗).

4.3 what-if 시뮬레이터

• 규칙표 선택 + 팩트 입력 → 규칙 재평가 + 전 규칙 트레이스(▶발동 / ·매칭 / ✗불매칭, first-match 가시화).
• 반사실 분석: 팩트 하나 바꿔 결정이 어떻게 갈리는지.

4.4 규칙표 편집(비개발자)

• 셀 인라인 편집·행 추가/삭제·순서 이동(위→아래 = 평가순 first-match)·사상 드롭다운.
• 안전 3중: 화이트리스트(4규칙표만·경로주입 차단)·형식검증 fail-closed·저장 전 .bak 백업+충돌검사.
• 저장 즉시 규칙엔진 반영.

4.5 규칙 변경 이력(버전관리)

• 저장 시 diff(추가/삭제/수정, 필드별 old→new) + 이력 로그(시각·편집자·요약·버전) + 스냅샷.
• 이력 패널 + 버전별 되돌리기. 스냅샷 만료 버전은 "만료" 표시(되돌리기 비활성).
• 보존 정책: 규칙표별 최신 20개 항상 보존 + 30일 초과 삭제.

4.6 편집자 인증·RBAC

• 가입/로그인(scrypt·세션 토큰·7일 TTL·재기동 지속). 로그인 시 계정명·역할 표시.
• 저장·롤백에 규칙표별 편집 권한 게이트(역할 403).

4.7 안전(파괴 차단)

• 파괴적 명령(삭제·포맷·kill 등) → 음 → 승인큐(:9801) 이관. 자동실행 절대 없음.

---

5. API 명세 (감사서버 :9802 — 전부 구현됨)

메서드	경로	요청	응답
GET	/	—	HTML 콘솔
GET	/health·/api/health	—	{status,service,도메인[6],규칙표[4],감사기록,port}
GET	/api/log	—	감사 행 배열(최신 먼저, 스테이지 조인)
POST	/api/decide	{입력}	{ok,도메인,사상,출력,발동규칙}
POST	/api/replay	{입력,원본사상}	{사상,출력,발동규칙,일치}
POST	/api/whatif	{규칙표,팩트}	{발동:{규칙,결정,사상},트레이스:[{규칙,조건,결정,사상,매칭,발동}]}
GET	/api/rules?name=	—	{name,rows:[[우선,조건,결정,사상]]}
POST	/api/rules/check	{rows}	{형식오류[],충돌[]}
POST	/api/rules/save	{name,rows,토큰,편집자}	{ok,저장,백업,충돌,변경[],요약} or 403
GET	/api/rules/history?name=	—	{이력:[{시각,편집자,규칙표,요약,버전,복원가능}]}
POST	/api/rules/rollback	{name,버전,토큰,편집자}	{ok,요약,변경[]} or 403
POST	/api/auth/register	{username,password}	{ok,token,username,역할}
POST	/api/auth/login	{username,password}	{ok,token,username,역할}

응답 한글 필드는 UTF-8. 4상 값은 문자열 "티/옴/타/음".

---

6. 데이터 모델

규칙표 (PSV, 화이트리스트 4종)

우선순위|조건;조건|결정|사상
예: 10|유형=자본지출;금액<=1000|임원승인|옴
    20||보류검토|음            (빈 조건 = catch-all, 반드시 마지막)

• 조건: 필드=값(문자열) / 필드<=값·필드>=값(수치), ;=AND. 우선순위(파일 순서)순 첫 전조건매칭.
• 화이트리스트: 승인규칙(승인규칙2.psv 20행)·배분규칙(4)·일정규칙(3)·휴가규칙(6).

감사 로그

• 넥서스_감사.psv: 입력|도메인|사상|출력|발동규칙(근거)
• 의사결정_감사.psv: 입력|유형|행위종류|사상|위험등급|문장코드

버전관리

• 규칙이력.psv: 시각|편집자|규칙표|요약|버전(millis)
• 규칙이력/<규칙표>_<seq>.psv: 버전별 전체 스냅샷

인증

• 편집자.json: {username:{salt,hash,역할}} (scrypt)
• 세션.json: {token:{u,exp}} (7일 TTL, 지속)
• 규칙권한매트릭스.psv: 역할|기능(규칙표)|민감도|허용(Y/N) (erp 포맷)

---

7. UI 화면·컴포넌트 (빌드 대상)

권장 단일 페이지(대시보드) + 섹션. 현재 감사서버 page()가 참조 구현(개선·재디자인 대상).

1. 헤더: nexus 로고 + 6도메인 배지 + ●라이브 상태 + 로그인/역할.
2. 라이브 결정 입력바: 자연어 입력 → 제출 → 4상 결과 카드.
3. 통계 바: 4상 분포 + 도메인 분포(필터 가능).
4. what-if 시뮬레이터 패널(접기): 규칙표 드롭다운 + 팩트 입력 + 평가 → 트레이스 렌더(발동/매칭/불매칭 색상).
5. 규칙표 편집 패널(접기): 인증 로그인 행 + 규칙표 선택 + 편집 그리드(셀·순서이동·사상드롭다운) + 검사/저장/이력 + diff/이력/되돌리기.
6. 감사 리스트: 결정별 흐름 카드(스테이지) + ↻재현 + 4상 색상 좌측 스트라이프.

디자인 요구

• 크라우니디자인.css(studio.crowny.org/font/크라우니디자인.css) 링크 + html[data-crowny]. 중앙 CSS가 폰트·토큰 제공.
• 4상 = 의미 색상(티/옴/타/음), 액센트와 별개. 상태를 색+형태(칩·스트라이프)로 이중 인코딩.
• 정보밀도 높은 운영 도구(스캔·조작). 요약 먼저, 상세 접기.
• 모바일 = take.crowny.org 레이아웃 기준. 다크/라이트 양쪽.
• 표·트레이스는 overflow-x:auto 컨테이너(본문 가로스크롤 금지).

---

8. 접근 경로

• 로컬: http://127.0.0.1:9802/ 또는 CrownyAI 브라우저 crowny://nexus(홈 타일 '넥서스').
• 외부: nexus.crowny.org(게이트웨이 라우트 배선됨) — 단 인증서 SAN 상한(100/100)으로 외부 HTTPS 대기(별도 cert 트랙).

---

9. 제약·비목표(반드시 준수)

• 한선씨 우선: 새 판정 로직은 .한선 정본부터. UI/오케스트레이션·암호(인증)는 JS 허용(예외 명시).
• 파괴 자동실행 금지: 삭제·포맷·kill은 음→승인큐. 승인해도 자동실행 안 함(인가만 기록).
• 라이브 서버 무수정·백업 보존·자율 데몬 미생성(호출형).
• VM 함정(한선씨 백엔드 수정 시): 읽기() 64KB 절단→버퍼파일읽기+버퍼찾기 / 1e12↑ 정수 오버플로→시각산술 JS / 배열 지역변수 재호출 오염. SSOT=~/.claude/templates/한선씨-가드레일.md.
• 지어낸 수치 금지 — 실측만.

---

10. 현재 상태 요약 (2026-07-17 실측)

• ✅ 한선씨 정본 19/19 컴파일 · 규칙표 4도메인 무결 · 6도메인 회귀 6/6.
• ✅ 백엔드 기능 전부 구현(결정·감사·리플레이·what-if·편집·검증·충돌·버전·롤백·스냅샷정책·인증·RBAC).
• ✅ 서비스: 감사서버 :9802(200)·승인큐 :9801(200)·crowny://nexus 로컬.
• ⚠️ 미완: 외부 HTTPS(cert SAN 상한)·이해 라우터 68% 천장(의미어 트랙)·다단계 승인체인(G6)·정책룰 충전(G7)·서비스 LaunchAgent 상시화.

빌드 대상 = 위 백엔드/API를 감싸는 잘 설계된 nexus 프로그램 UI. 백엔드 로직 재작성 불필요(정본 존재).