AriWeb-Suite/Ariweb-Suitle_Dev-Order_v0.3.17.md

Ariweb Suite 개발 지시 — 작성자: Oz · v0.3.17

작성자: Oz 작성일: 2026-10-29 이전 버전: v0.3.10(텍스트 셸 복사, Oz) · v0.3.9 · v0.3.2 · v0.3.1 · v0.3.0 · v0.2.1 · v0.2.0 · v0.1.4 · v0.1.1 이번 개정: HawkEye 이름 변경, 역할별 통합 배포, 화면 부분 갱신, 배포 릴리스 화면 재구성(HAL 배포 제외), 작업 진행 창, agent 배포 점검, 대상 서버 선택. HAL 0.3.10 → 0.3.17(지시된 버전). HAL 에만 적용하며 이전 지시의 모든 기준은 그대로다.

1. 사용자 요구(Oz 원문, 약화 금지)

1. observability 모듈 이름 변경 → HawkEye. 전체 시스템 상황을 점검하는 모듈의 이름을 "HawkEye" 로.
2. 통합 배포 과정 추가. 시스템의 주된 역할은 webmaker·webhosting server·arimail·backup·portal 등이고 백그라운드에서 agent·HawkEye 가 이들을 잇는다. 새로운 서버를 추가하면 역할에 따라 필요한 것들을 한 번에 배포·설정하는 작업을 자동화한다. webmaker 설치(그 서버에서는 webmaker 만) / webhosting 서버 설치(사용자 웹 서비스, webmaker 의 배포 서버) / arimail 서버 설치(웹메일·POP·IMAP) / backup 서버 설치 / portal 서버 설치·이전(이미 설치된 포털이 있으면 추가 설치하지 않고 필요하면 이전). portal 을 제외한 서버는 하나의 기능을 여러 서버가 나눌 수 있으므로 각 서버의 슬롯을 확인하고 요구에 맞게 배치하는 작업은 HAL 이 관리한다.
3. HAL 화면 갱신 주기 변경. 지속적 전체 갱신으로 화면이 번쩍인다. 갱신이 필요한 정보만 모아 그 부분만 갱신한다.
4. 배포 릴리스. HAL 은 단일 통합 시스템으로 HAL 서버에서 HAL 을 추가 배포하지 않는다(먼저 설치하는 도구, 이중화·분산 미구성) → 배포 릴리스에서 HAL 배포 삭제. 다른 도구는 필요한 곳에 필요한 것만 배포하므로, 최신 버전의 도구별 설치 안내·현재 버전·기능·상호 연결(어떤 모듈이 있어야 무엇이 동작) 설명과 함께 배포하는 화면을 기본 화면으로. 이전 버전은 과거 버전 보기로 보고 되돌릴 수 있게.
5. 운영 작업 진행 상황 표시. 작업창 아래를 나눠 현재 작업 진행 상황과 그동안의 히스토리를 보인다.
6. 배포 작업 점검. agent 배포를 지시했으나 "처리대기"가 오래 지속되고 진행 상황을 알 수 없다. 작업 구성에 문제가 없는지 로그를 참고해 확인·수정.
7. 대상 서버 리스팅·선택. 배포 때 서버를 직접 입력하는 대신 관리 중인 서버 목록을 보여 주고 라디오 버튼으로 선택.

2. 점검(구현 전, bear 운영 DB·로그)

• 6번: module.deploy(agent 0.3.10) 작업이 serverIds: [] 로 만들어져 precheck 가 즉시 no_targets 로 실패했다(화면 안내 "비우면 역할 전체" 와 backend 불일치). 작업 상태가 릴리스 화면에 보이지 않아 "처리 대기"로 보였다. Agent 2대는 정상 연결.

3. 필수 동작(계약)

1. 모듈 hawkeye(label HawkEye): 기술서·배포 순서·운영 현황·공개 상태·AI 스킬·도구 enum. 옛 이름 observability 는 별칭으로 받고, DB 행은 마이그레이션으로 바꾼다.
2. 서버 프로필(SERVER_PROFILES): webmaker(agent·webmaker·hawkeye, web) · webhosting(agent·hawkeye, web, sites 슬롯) · arimail(agent·arimail·hawkeye, mail) · backup(agent·backup·hawkeye, backup) · portal(agent·portal·hawkeye, control, 하나만). 작업 server.provision: 준비된 서버에 프로필 모듈을 순서대로 배포하고 역할·프로필·슬롯을 기록, 실패 시 중단. 포털이 이미 있으면 portal_exists(API·작업), 작업 portal.relocate(새 서버 설치 → 운영자 전환 확인 → 옛 포털 비활성). 슬롯: 서버 slots(PATCH), slotsFree, pickServer 가 여유 슬롯을 본다.
3. 주기 갱신(운영 현황·서버·작업 상세·AI 대화 기록·dock)은 노드 단위 diff 로 바뀐 부분만 바꾼다(dom-patch.mjs).
4. HAL 은 배포 대상이 아니다(hal_not_deployable, 배포 순서·화면에서 제외). HAL 먼저 규칙은 "HAL 실행 버전 ≥ 릴리스 버전". 릴리스 화면 기본은 모듈별 최신 승인 릴리스·설명·필요한 것·제공·설치 방법·현재 배치·배포 단추, 상호 연결, 프로필; 과거 버전은 접힌 표(이 버전 배포·되돌리기).
5. 공통 틀 아래 작업 진행 창: 진행 중(단계·진행률·오류)·히스토리, 5초 갱신, 접기.
6. 배포 대상을 비우면 역할에 맞는 준비된 서버 전체, 없으면 API 에서 즉시 no_targets.
7. 배포·통합 배포·포털 이전 창은 서버 목록(라디오/체크, 준비 안 된 서버 비활성)에서 고른다.

4. TDD·검증

• test/hal-0317.test.mjs 를 먼저 쓰고 RED 확인 뒤 구현(HawkEye·마이그레이션 / 릴리스 API·HAL 제외·HAL 먼저 완화·기본 대상·no_targets / 통합 배포 순서·프로필·포털 싱글턴·이전·슬롯 배치 / diff·dock·서버 선택·정적 계약 / 버전·문서). 기존 테스트(HAL 자체 배포 계약 갱신 포함)·전체 Suite. 배포 뒤 bear read-back(마이그레이션·운영 현황 hawkeye·릴리스 API).

5. 버전·배포

• HAL 0.3.17: package.json·README·VERSION_HISTORY·개발 지시. 커밋 → push → main 병합 → 깨끗한 main 빌드·verify → bear HAL 만 배포 → read-back. 다른 모듈은 배포하지 않는다.

6. 완료 조건

점검 결과(6번 원인), 변경 파일, RED/GREEN·전체 테스트, 커밋·병합 커밋, artifact sha256, 배포 read-back, 운영자 조치, 알려진 제한을 보고한다.