# 호스트 목록에서 기기 생성/연결하기

## 호스트 목록에서 기기 생성/연결하기

**호스트(Host)** 는 SMPLY Agent가 설치된 기기(엔드포인트)의 인벤토리 레코드입니다. 에이전트가 수집한 하드웨어·OS·로그인 정보를 기반으로 호스트와 SMPLY 기기를 연결해 관리합니다.

{% hint style="info" %}
**호스트 vs 기기**

* **호스트**: 에이전트가 설치된 실제 기기 정보 (hostname, OS, 시리얼)
* **SMPLY 기기**: 자산 관리 관점에서 등록된 기기 레코드 (관리번호, 소유자, 구매 정보 등)

하나의 SMPLY 기기에 하나의 호스트가 연결되는 구조로 운영됩니다.
{% endhint %}

***

### 1. 호스트 목록 페이지

**경로**: 사이드바 **호스트** 메뉴 → `/host/list`

**페이지 제목**: *호스트* **설명**: *"SMPLY 에이전트가 설치된 호스트 목록을 확인합니다."*

#### 헤더 액션 — `에이전트 다운로드` SplitButton

우측 상단 메인 버튼은 **`에이전트 다운로드`** (설치 패키지 받기). 드롭다운에는 **`설치 안내 메일 발송`** 이 있어 아직 설치 안 된 구성원에게 일괄로 안내 메일을 보낼 수 있습니다.

#### 상태 탭

| 탭         | 의미                                                                 |
| --------- | ------------------------------------------------------------------ |
| **전체**    | 모든 호스트                                                             |
| **활성**    | 정상 동작 중                                                            |
| **아카이브**  | 더 이상 사용하지 않는 호스트 (보관 처리)                                           |
| **연결 대기** | 시리얼 번호 매칭 기반으로 SMPLY가 연결 제안을 만든 호스트. 건수가 0이면 숨겨집니다. 주황색 텍스트로 강조 표시 |

"연결 대기" 탭은 일반 그리드 대신 **일괄 승인 전용 패널**로 전환되어, 여러 제안을 한 번에 승인할 수 있습니다.

***

### 2. 그리드 컬럼

기본 표시 컬럼 순서:

* 호스트명
* 플랫폼 (macOS / Windows 등)
* **사용자** — 자동 매칭된 구성원
* **기기** — 연결된 SMPLY 기기(관리번호). 아직 연결 전이면 연결 버튼
* OS 버전
* 하드웨어 모델
* 시리얼 번호
* 에이전트 버전
* 에이전트 확인 (마지막 체크인 시각, `온라인 / 오프라인 / 누락 / 비활성`)

***

### 3. 호스트에 SMPLY 기기 연결하기

각 호스트 행의 **기기** 셀에서 기존 기기와 연결하거나 새 기기를 생성해 연결할 수 있습니다.

**단계 1: 연결 다이얼로그 열기**

1. 연결되지 않은 호스트의 **기기** 셀에서 **연결** 버튼을 클릭합니다.
2. *"호스트와 기기 연결"* 다이얼로그가 열립니다.

**단계 2: 기존 기기 선택 또는 신규 등록 선택**

* **기존 기기 연결**: 검색창에서 관리번호/시리얼로 기기를 찾아 선택합니다. 시리얼 번호가 일치하는 기기가 있으면 **주황색 배지**로 자동 추천됩니다.
* **신규 등록**: 다이얼로그 하단 Footer의 **`새로 등록하기`** 버튼을 누르면 연결 다이얼로그가 닫히고 **기기 생성 다이얼로그**가 열립니다.

***

### 4. 호스트에서 신규 기기 생성 — 자동 채움

*"기기 생성하기"* 다이얼로그에서 다음 필드를 입력하면, 호스트가 수집한 정보가 자동으로 함께 저장됩니다.

**사용자 입력 필드**

| 필드       | 필수 | 설명                                                           |
| -------- | -- | ------------------------------------------------------------ |
| **카테고리** | ✅  | 노트북·모니터 등. 보통 노트북이 기본 제안                                     |
| **관리번호** | ✅  | 우리 조직의 관리 번호. **`추천 번호`** 버튼을 누르면 기존 번호 패턴을 분석해 다음 번호를 자동 제안 |

**자동 입력 항목** (*"호스트 정보에서 자동 입력되는 항목"* 회색 박스로 표시)

| 항목     | 소스                    |
| ------ | --------------------- |
| 모델명    | 호스트 하드웨어 모델           |
| 시리얼 번호 | 호스트 시리얼               |
| 사용자    | 호스트의 로그인 구성원          |
| OS     | 호스트 OS 버전 (OS 커스텀 필드) |
| 상태     | **사용 중** (고정)         |
| 소유구분   | **법인** (고정)           |

**단계 4: 저장 → 자동 연결**

1. **`생성하기`** 버튼을 클릭합니다.
2. 새 기기가 등록되고, 해당 호스트와 **자동으로 연결**됩니다.
3. 호스트 목록의 해당 행 **기기** 컬럼에 관리번호가 표시됩니다.

***

### 5. "연결 대기" 일괄 승인

"연결 대기" 탭에서는 SMPLY가 시리얼 매칭으로 만든 제안 목록을 확인할 수 있습니다. 체크박스로 여러 개 선택 후 한 번에 승인해 일괄 연결할 수 있습니다.

***

### 6. 기기 목록에서 에이전트 정보 일괄 업데이트

호스트-기기 연결이 완료된 기기의 하드웨어·식별 정보를 최신 에이전트 수집값으로 한 번에 반영할 수 있습니다. 자산 실사 후 OS 버전·CPU·RAM 등을 수십\~수백 대 단위로 맞춰야 할 때 유용합니다.

**단계 1: 대상 기기 선택**

1. **기기** 목록(`/device`)으로 이동합니다.
2. 체크박스로 에이전트 정보를 갱신할 기기 여러 대를 선택합니다.
3. 하단 벌크 액션 바에서 **`에이전트 정보로 업데이트`** 를 클릭합니다.

**단계 2: 동기화할 필드 선택**

다이얼로그 상단에는 매칭 요약이 표시됩니다 — *"N대 동기화 가능 · M대 제외(시리얼 없음 X · 에이전트 없음 Y)"*.

| 그룹           | 필드                                   |
| ------------ | ------------------------------------ |
| **하드웨어 정보**  | OS · CPU · RAM · GPU · MAC 주소 · 메인보드 |
| **기기 식별 정보** | 모델명 · 브랜드 · **사용자**                  |

* **기본 선택**: 현재 값과 에이전트 수집값이 다른 필드만 자동 체크됩니다.
* 체크를 해제한 필드는 덮어쓰지 않습니다. 수동 배정된 소유자 값을 보존하려면 "사용자" 체크박스를 해제하세요.
* 선택한 필드가 일부 카테고리에 없으면 **"{카테고리} {N}대 · {필드} — 이 필드는 동기화되지 않습니다."** 알럿으로 안내됩니다.

**단계 3: 실행 및 결과 확인**

1. **`동기화`** 버튼을 클릭합니다. 선택된 기기 각각에 대해 카테고리별 커스텀 필드에 맞춰 변환된 값이 저장됩니다.
2. 완료되면 *"N대 기기의 에이전트 정보가 동기화되었습니다"* 토스트가 표시되고 그리드가 새로고침됩니다.
3. 시리얼이 없거나 연결된 에이전트가 없는 기기는 변경되지 않은 채 요약의 **제외** 카운트에만 집계됩니다.

{% hint style="info" %}
**같은 기기에 구/신 에이전트가 공존할 때** 에이전트 1.0.0 전환 구간에 같은 시리얼로 두 레코드가 남아 있을 수 있습니다. 벌크 동기화는 매칭된 에이전트 중 **가장 최근에 생성된(`createdAt`) 레코드**를 기준으로 값을 반영하므로 stale 값이 덮어쓰이지 않습니다.
{% endhint %}

{% hint style="warning" %}
**기기 편집 권한이 필요합니다** 벌크 액션 바의 **`에이전트 정보로 업데이트`** 항목은 **`device-edit`** 권한이 있는 구성원에게만 노출됩니다.
{% endhint %}

***

### 7. 호스트 상태 관리

행의 `⋯` 메뉴에서 호스트 상태를 변경할 수 있습니다.

* **활성 호스트**: `아카이브` 선택 → 더 이상 사용하지 않는 호스트로 표시
* **아카이브 호스트**: `아카이브 해제` 선택 → 다시 활성 상태로 복귀

***

### 8. 좌석(Seat) 제한 안내

플랜에 호스트 좌석 수 제한이 있는 경우, 목록 상단에 안내 배너가 표시됩니다. 좌석을 초과하면 **주황색 경고 배너**와 함께 *"담당 매니저에게 문의"* CTA가 노출되고, 초과분 호스트는 🔒 아이콘으로 잠김 표시됩니다. 계속 관리하려면 플랜 업그레이드 또는 오래된 호스트 아카이브가 필요합니다.

***

### 9. 권한 안내

| 작업                      | 필요 권한            |
| ----------------------- | ---------------- |
| 호스트 목록 조회               | 기본 구성원 이상        |
| 호스트-기기 연결 / 기기 생성       | `device-edit` 권한 |
| 기기 목록에서 에이전트 정보 일괄 업데이트 | `device-edit` 권한 |
| 아카이브 / 해제               | `device-edit` 권한 |
| 에이전트 설치 안내 메일 발송        | `device-edit` 권한 |

플랜이 만료되면 편집 액션이 비활성화됩니다.

***

### 10. 자주 묻는 질문

#### Q: 호스트 연결 제안이 자동으로 만들어지는 기준은 무엇인가요

**시리얼 번호**가 일치하는 기기와 호스트가 있으면 자동 제안이 생성되어 **연결 대기** 탭에 나타납니다. 관리번호만으로는 매칭되지 않습니다.

#### Q: 호스트에서 자동 채움된 정보가 잘못되어요

* 호스트 수집 정보(특히 모델명·OS)가 잘못된 경우가 간헐적으로 있습니다.
* 기기 생성 후 기기 상세 페이지에서 해당 필드를 직접 수정할 수 있습니다.
* 반복적으로 틀린다면 채널톡으로 호스트 정보를 보내주세요.

#### Q: "추천 번호" 버튼이 이상한 번호를 제안해요

관리번호 추천은 기존 번호들의 **공통 패턴**을 분석해서 다음 값을 예측합니다. 번호 체계를 바꿨거나 부서별 규칙이 있다면 수동 입력을 권장합니다.

#### Q: 호스트를 삭제할 수 있나요

직접 삭제 대신 **아카이브** 를 사용합니다. 에이전트가 제거된 기기는 호스트 레코드가 자동으로 **`누락(missing)`** 상태로 전환됩니다.

#### Q: 이 외의 문제

채널톡으로 문의해 주세요.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smply.one/it-device/host-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.