# 機能設計書 55-システム情報

## 概要

本ドキュメントは、Nushellにおけるシステム情報取得機能の設計仕様を記載する。この機能は、sysコマンド群（sys cpu, sys disks, sys host, sys mem, sys net, sys temp, sys users）を通じて、ハードウェアおよびOS情報を取得する。

### 本機能の処理概要

システム情報機能は、システムのハードウェアリソース、OS情報、ユーザー情報などを構造化データとして取得する。

**業務上の目的・背景**：システム監視、リソース管理、環境診断において、ハードウェアおよびOS情報の取得は基本的な操作である。従来の複数コマンド（lscpu, free, df等）の出力をNushellの構造化データと統合し、統一的なインターフェースで情報を取得できるようにする。

**機能の利用シーン**：
- システムリソースの監視スクリプト作成
- サーバー構成情報の収集
- ディスク使用状況の確認
- メモリ使用状況の監視
- ネットワークインターフェース情報の取得
- 温度監視（対応ハードウェアのみ）

**主要な処理内容**：
1. sysinfo/sysinfoクレートを使用したシステム情報収集
2. CPU、メモリ、ディスク、ネットワーク等の情報取得
3. 構造化レコード/テーブル形式での出力

**関連システム・外部連携**：
- オペレーティングシステムの各種情報API
- ハードウェア監視インターフェース

**権限による制御**：一部の情報（温度センサー等）は管理者権限が必要な場合あり

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI専用コマンド |

## 機能種別

システム情報取得

## 入力仕様

### 入力パラメータ

#### sys cpu

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --long, -l | Switch | No | CPU使用率を含む詳細情報（サンプリング必要） | - |

#### その他のsysサブコマンド

パラメータなし

### 入力データソース

システムAPI（sysinfo/procfs等）

## 出力仕様

### 出力データ

#### sys cpu

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | CPUコア名 |
| brand | String | CPUブランド |
| vendor_id | String | ベンダーID |
| freq | Int | 周波数（MHz） |
| load_average | String | ロードアベレージ |
| cpu_usage | Float | CPU使用率（--long時） |

#### sys mem

| 項目名 | 型 | 説明 |
|--------|-----|------|
| total | Filesize | 総メモリ容量 |
| free | Filesize | 空きメモリ |
| used | Filesize | 使用中メモリ |
| available | Filesize | 利用可能メモリ |
| swap total | Filesize | スワップ総容量 |
| swap free | Filesize | スワップ空き |
| swap used | Filesize | スワップ使用中 |

#### sys disks

| 項目名 | 型 | 説明 |
|--------|-----|------|
| device | String | デバイス名 |
| type | String | ファイルシステムタイプ |
| mount | String | マウントポイント |
| total | Filesize | 総容量 |
| used | Filesize | 使用容量 |
| free | Filesize | 空き容量 |

#### sys host

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | ホスト名 |
| os_version | String | OSバージョン |
| kernel_version | String | カーネルバージョン |
| hostname | String | ホスト名 |
| uptime | Duration | 稼働時間 |
| boot_time | Date | 起動時刻 |

#### sys net

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | インターフェース名 |
| sent | Filesize | 送信バイト数 |
| recv | Filesize | 受信バイト数 |

#### sys temp

| 項目名 | 型 | 説明 |
|--------|-----|------|
| unit | String | センサー名 |
| temp | Float | 温度（摂氏） |

#### sys users

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | ユーザー名 |
| groups | List | 所属グループ |

### 出力先

パイプライン出力

## 処理フロー

### 処理シーケンス

```
1. sysinfoライブラリ初期化
   └─ System::new()でシステム情報収集開始
2. 情報更新
   └─ 各refresh_*メソッドで最新情報取得
3. 情報抽出
   └─ 各システム情報をValueに変換
4. 結果返却
   └─ Record/Tableとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[sys サブコマンド] --> B{サブコマンド種別}
    B -->|cpu| C[System::refresh_cpu]
    B -->|mem| D[System::refresh_memory]
    B -->|disks| E[System::refresh_disks_list]
    B -->|host| F[ホスト情報取得]
    B -->|net| G[ネットワーク情報取得]
    B -->|temp| H[温度情報取得]
    B -->|users| I[ユーザー情報取得]
    C --> J[Record/Table構築]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K[PipelineData返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | CPU使用率サンプリング | --long時は2xMINIMUM_CPU_UPDATE_INTERVALの待機 | sys cpu --long |
| BR-02 | NULL文字トリミング | C言語由来の文字列からNULL文字を除去 | 全てのシステム情報 |
| BR-03 | ロードアベレージフォーマット | 1分/5分/15分を小数点2桁で表示 | sys cpu |

### 計算ロジック

- CPU使用率は2回のサンプリング間の差分から算出
- ロードアベレージは`{1分}, {5分}, {15分}`形式

## データベース操作仕様

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| GenericError | 取得エラー | プロセス統計取得失敗 | 権限確認、OS対応確認 |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- sys cpu --long は2回のサンプリングのため数百ミリ秒の遅延あり
- 他のsysコマンドは高速に動作

## セキュリティ考慮事項

- 一部のシステム情報は管理者権限が必要
- ユーザー情報の取得はセキュリティ監査で使用可能

## 備考

- sysinfoクレートを使用したクロスプラットフォーム実装
- 一部の情報はプラットフォームによって取得不可の場合あり

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mod.rs | `crates/nu-command/src/system/sys/mod.rs` | サブコマンド一覧とtrim_cstyle_null |
| 1-2 | mem.rs | `crates/nu-command/src/system/sys/mem.rs` | メモリ情報のレコード構造 |
| 1-3 | cpu.rs | `crates/nu-command/src/system/sys/cpu.rs` | CPU情報のレコード構造 |

**読解のコツ**:
- **mod.rs 19-21行目**: trim_cstyle_null()でC言語文字列のNULL終端を処理
- **mem.rs 46-54行目**: メモリ情報のRecord構造（total, free, used, available, swap等）
- **cpu.rs 72-78行目**: CPU情報の基本Record構造

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sys_.rs | `crates/nu-command/src/system/sys/sys_.rs` | sysコマンドのヘルプ表示 |

**主要処理フロー**:
- **26-33行目**: run()でサブコマンドなしの場合はヘルプを表示

#### Step 3: 各サブコマンド実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cpu.rs | `crates/nu-command/src/system/sys/cpu.rs` | sys cpuの実装 |
| 3-2 | mem.rs | `crates/nu-command/src/system/sys/mem.rs` | sys memの実装 |
| 3-3 | disks.rs | `crates/nu-command/src/system/sys/disks.rs` | sys disksの実装 |
| 3-4 | host.rs | `crates/nu-command/src/system/sys/host.rs` | sys hostの実装 |
| 3-5 | net.rs | `crates/nu-command/src/system/sys/net.rs` | sys netの実装 |
| 3-6 | temp.rs | `crates/nu-command/src/system/sys/temp.rs` | sys tempの実装 |
| 3-7 | users.rs | `crates/nu-command/src/system/sys/users.rs` | sys usersの実装 |

**主要処理フロー（cpu.rs）**:
- **49-60行目**: cpu()関数でSystem::new()とCPU情報リフレッシュ
- **51-57行目**: --long時は2回サンプリングしてCPU使用率を取得
- **62-91行目**: 各CPUコアの情報をRecordに格納

**主要処理フロー（mem.rs）**:
- **42-57行目**: mem()関数でメモリ情報取得とRecord構築

### プログラム呼び出し階層図

```
sys サブコマンド
    │
    ├─ sys cpu
    │      ├─ System::new()
    │      ├─ refresh_cpu_specifics()
    │      ├─ [--long] sleep + 再refresh
    │      └─ Record構築
    │
    ├─ sys mem
    │      ├─ System::new()
    │      ├─ refresh_memory()
    │      └─ Record構築
    │
    ├─ sys disks
    │      ├─ System::new()
    │      ├─ refresh_disks_list()
    │      └─ Table構築
    │
    ├─ sys host
    │      ├─ sysinfo関数群
    │      └─ Record構築
    │
    ├─ sys net
    │      ├─ Networks::new()
    │      └─ Table構築
    │
    ├─ sys temp
    │      ├─ Components::new()
    │      └─ Table構築
    │
    └─ sys users
           ├─ Users::new()
           └─ Table構築
```

### データフロー図

```
[入力]                    [処理]                         [出力]

--long (cpu) ───────────▶ sys cpu ─────────────────────▶ Table (CPU情報)
                         sysinfo refresh

(なし) ─────────────────▶ sys mem ─────────────────────▶ Record (メモリ情報)
                         sysinfo refresh_memory

(なし) ─────────────────▶ sys disks ────────────────────▶ Table (ディスク情報)
                         sysinfo refresh_disks_list
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod.rs | `crates/nu-command/src/system/sys/mod.rs` | ソース | モジュール定義、共通関数 |
| sys_.rs | `crates/nu-command/src/system/sys/sys_.rs` | ソース | sysコマンド（ヘルプ） |
| cpu.rs | `crates/nu-command/src/system/sys/cpu.rs` | ソース | sys cpuコマンド |
| mem.rs | `crates/nu-command/src/system/sys/mem.rs` | ソース | sys memコマンド |
| disks.rs | `crates/nu-command/src/system/sys/disks.rs` | ソース | sys disksコマンド |
| host.rs | `crates/nu-command/src/system/sys/host.rs` | ソース | sys hostコマンド |
| net.rs | `crates/nu-command/src/system/sys/net.rs` | ソース | sys netコマンド |
| temp.rs | `crates/nu-command/src/system/sys/temp.rs` | ソース | sys tempコマンド |
| users.rs | `crates/nu-command/src/system/sys/users.rs` | ソース | sys usersコマンド |
