# 機能設計書 122-MD5ハッシュ

## 概要

本ドキュメントは、KShootManiaにおけるkshlib.dll経由のMD5ハッシュ計算機能の設計を記述する。譜面ファイルの一意識別やインターネットランキング(IR)連携に使用されるMD5ハッシュを計算する。

### 本機能の処理概要

本機能は、kshlib.dllが提供する`KSHLib_GetChartMD5Hash`関数を通じて、譜面ファイルのMD5ハッシュ値を計算する。計算されたハッシュ値は、IR(インターネットランキング)システムにおいて譜面を一意に識別するために使用される。

**業務上の目的・背景**：インターネットランキングシステムでは、異なるプレイヤーが同一の譜面でプレイした結果を比較する必要がある。譜面ファイルのパスやファイル名は環境によって異なるため、譜面内容のMD5ハッシュ値を使って譜面を一意に識別する仕組みが必要である。メタデータ(タイトル、アーティスト等)を除外した正規化データからハッシュを計算することで、メタデータの軽微な変更に影響されない安定した識別子を生成する。

**機能の利用シーン**：
- ゲームプレイ画面でのIR用ハッシュ計算（play_chart_load.hspのgetChartIRHash）
- 選曲画面でのIRページ表示時の譜面識別
- リザルト画面でのIRスコア送信時の譜面識別

**主要な処理内容**：
1. kshlib.dllの初期化（KSHLib_Init）
2. 譜面ファイルパスを引数としてKSHLib_GetChartMD5Hashを呼び出し
3. MD5ハッシュ値(32文字の16進数文字列)を取得

**関連システム・外部連携**：kshlib.dllを介してMD5計算を実行。IR(インターネットランキング)サーバーとの通信で譜面識別に使用。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 参照画面 | IR用譜面ハッシュ計算(play_chart_load.hsp) |

## 機能種別

計算処理（ハッシュ計算）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ファイルパス | sptr(文字列) | Yes | MD5ハッシュを計算する譜面ファイルのパス | ファイルが存在すること |
| dest | var | Yes | MD5ハッシュ値を格納する変数 | sdimで32バイト以上確保されていること |

### 入力データソース

ファイルシステム上の譜面ファイル(.ksh形式)。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| MD5ハッシュ値 | 文字列(32文字) | 譜面データのMD5ハッシュ値(16進数文字列) |

### 出力先

呼び出し元モジュールの変数(dest引数)

## 処理フロー

### 処理シーケンス

```
1. KSHLib_Init呼び出し（アプリケーション起動時）
   └─ kshlib.dllの初期化、dir_defaultの設定
2. KSHLib_GetChartMD5Hash呼び出し
   └─ 譜面ファイルパスを渡す
   └─ DLL内部でメタデータ除外の正規化処理
   └─ 正規化データのMD5ハッシュ計算
   └─ 32文字の16進数文字列としてdestに格納
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[KSHLib_Init: DLL初期化]
    B --> C[譜面ファイルパス取得]
    C --> D[KSHLib_GetChartMD5Hash呼び出し]
    D --> E[DLL内部: メタデータ除外の正規化]
    E --> F[DLL内部: MD5ハッシュ計算]
    F --> G[32文字16進数文字列を返却]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-122-01 | メタデータ除外 | title, artist等のメタデータを除外して正規化したデータからハッシュを計算 | IR用ハッシュ計算時 |
| BR-122-02 | ハッシュ形式 | MD5ハッシュは32文字の16進数文字列として返却 | 常時 |
| BR-122-03 | DLL依存 | kshlib.dllが存在し正常に初期化されていることが前提 | 常時 |

### 計算ロジック

MD5アルゴリズムに基づくハッシュ計算。具体的な計算処理はkshlib.dll内部で実行されるため、HSP側からは関数呼び出しのみ。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不存在 | 指定された譜面ファイルが存在しない | 呼び出し元でファイル存在確認を行う |
| - | DLL初期化失敗 | kshlib.dllが見つからない/初期化に失敗 | アプリケーション起動時にエラーダイアログを表示 |

### リトライ仕様

リトライ処理なし。

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

該当なし。

## パフォーマンス要件

kshlib.dllはネイティブDLLであり、MD5計算は高速に実行される。譜面ファイルの読み込みI/Oが主なボトルネックとなる可能性がある。

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

- MD5は暗号学的に破られているが、譜面識別用途(衝突耐性)としては実用上十分
- DLLから返却されるハッシュ値はIRサーバーに送信されるため、改ざんリスクを考慮する場合はサーバー側でも検証が必要

## 備考

- KSHLib_GetChartMD5Hashの第1引数はファイルパス(sptr)、第2引数はハッシュ値格納先(var)
- kshlib.dllはKSHLib_Init(dir_default)で初期化する必要がある（kshootmania.hsp 757行目）
- IR用MD5ハッシュ計算機能(No.26)とも関連が深い

---

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

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

### 推奨読解順序

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

MD5ハッシュ計算で使用されるDLL関数のインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshlib.as | `src/kshlib.as` | KSHLib_GetChartMD5Hashの関数宣言(18行目) |

**読解のコツ**: HSP3の`#uselib`は外部DLLの読み込み、`#func`はDLL関数のバインド宣言である。`sptr`は文字列ポインタ、`var`は変数参照を示す。

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

kshlib.dllの初期化と呼び出し箇所を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | KSHLib_Initの呼び出し(757行目) |
| 2-2 | kshlib.as | `src/kshlib.as` | DLL関数宣言群(4-19行目) |

**主要処理フロー**:
1. **757行目(kshootmania.hsp)**: `KSHLib_Init dir_default` - kshlib.dllの初期化
2. **18行目(kshlib.as)**: `#func KSHLib_GetChartMD5Hash "KSHLib_GetChartMD5Hash" sptr, var` - MD5ハッシュ計算関数の宣言

#### Step 3: 呼び出し元を理解する

MD5ハッシュ計算がどの場面で使用されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | getChartIRHash内でのKSHLib_GetChartMD5Hash呼び出し |

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

```
kshootmania.hsp
    |
    +-- KSHLib_Init (757行目: DLL初期化)
    |
    +-- play_chart_load.hsp
    |       |
    |       +-- getChartIRHash (サブルーチン)
    |               |
    |               +-- KSHLib_GetChartMD5Hash (kshlib.dll)
    |                       |
    |                       +-- [DLL内部] ファイル読み込み
    |                       +-- [DLL内部] メタデータ除外・正規化
    |                       +-- [DLL内部] MD5ハッシュ計算
    |
    +-- ir.hsp
            |
            +-- IR送信時にハッシュ値を使用
```

### データフロー図

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

譜面ファイルパス -------> KSHLib_GetChartMD5Hash --------> MD5ハッシュ値(32文字)
  (.ksh)                    |                                  |
                           +-- kshlib.dll内部処理              +---> IRサーバー送信
                           +-- メタデータ除外                  +---> 譜面識別用途
                           +-- MD5計算
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshlib.as | `src/kshlib.as` | ソース | kshlib.dllのHSPバインディング定義 |
| kshlib.dll | `kshlib.dll` | DLL | MD5ハッシュ計算の実体を含むネイティブDLL |
| kshootmania.hsp | `kshootmania.hsp` | ソース | KSHLib_Initの呼び出し元 |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | getChartIRHash経由でのMD5ハッシュ計算呼び出し |
| ir.hsp | `src/ir.hsp` | ソース | IRサーバー通信でハッシュ値を使用 |
