# 機能設計書 5-コース結果画面

## 概要

K-Shoot MANIAのコースモードでの各曲スコア一覧・合計スコア・グレードを表示するコース結果画面の機能設計書である。

### 本機能の処理概要

コース結果画面は、コースモードで複数曲を連続プレイした後に表示され、各曲の個別スコアとコース全体の合計スコア・グレード・ゲージ・メダルをスクロール可能なリスト形式で表示する画面である。

**業務上の目的・背景**：コースモードでは複数曲を連続プレイするため、各曲の成績を一覧で確認できる画面が必要である。合計スコアによるコース全体の評価と、各曲の個別成績を同時に把握できるようにする。

**機能の利用シーン**：コースモードの最終曲のリザルト画面からSCENE_COURSE_RESULTに遷移した際に表示される。Enter/Escキーで選曲画面に戻る。

**主要な処理内容**：
1. コース全体の合計スコア・グレード表示
2. 各曲のスコア一覧のスクロール可能リスト表示（IMG_CRESULT_LISTBUF）
3. コース全体のゲージ表示（IMG_CRESULT_GAUGE）
4. コース全体の判定詳細（coursecritical/coursenear/courseerrorn）表示
5. コースハイスコア更新時のNEW RECORD表示
6. コーススコアファイルへの保存

**関連システム・外部連携**：BASS Audio Library（コースリザルトBGM再生）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | コースリザルト画面 | 主画面 | コース全体のスコア・各曲スコアリスト・グレード・メダルを表示 |
| 3 | 曲選択画面 | 遷移先 | Enter/Esc押下でSCENE_SELECT（曲選択画面）へ遷移 |
| 6 | リザルト画面 | 遷移元 | コースモード最終曲完了後にSCENE_COURSE_RESULTへ遷移 |

## 機能種別

結果表示・データ保存・シーン遷移制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| coursetotalscore | int | Yes | コース合計スコア | 0以上 |
| coursecritical | int | Yes | コース全体CRITICAL数 | 0以上 |
| coursenear | int | Yes | コース全体NEAR数 | 0以上 |
| courseerrorn | int | Yes | コース全体ERROR数 | 0以上 |
| courselistnum | int | Yes | コース内曲数 | 1以上 |
| courselist | str | Yes | コース内曲リスト | 改行区切り |

### 入力データソース

- リザルト画面で累積されたコースモード成績データ
- コースファイル（.kco）内の各曲の譜面ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| scene | int | 遷移先シーンID（SCENE_SELECT） |

### 出力先

- 画面表示（コーススコア一覧、合計スコア、グレード、ゲージ）
- コーススコアファイル（スコア保存）

## 処理フロー

### 処理シーケンス

```
1. コースリザルト初期化（on_update_course_result）
   ├─ auto/adjmode判定（スキップ処理）
   ├─ 画像リソース読み込み
   ├─ 各曲の譜面ファイルからtitle/artist読み込み
   └─ 各曲スコアリスト画像の生成
2. コースリザルト表示ループ
   ├─ コース全体スコア・グレード描画
   ├─ 各曲スコアリスト描画（スクロール対応）
   ├─ ゲージ表示
   ├─ NEW RECORD表示
   └─ 入力待ち（Enter/Esc）
3. スコア保存・シーン遷移
   └─ SCENE_SELECT
```

### フローチャート

```mermaid
flowchart TD
    A[コースリザルト開始] --> B{auto/adjmode?}
    B -->|Yes| C[SCENE_SELECT直行]
    B -->|No| D[画像リソース読み込み]
    D --> E[各曲情報読み込み]
    E --> F[リスト画像生成]
    F --> G[表示ループ]
    G --> H{Enter/Esc?}
    H -->|No| G
    H -->|Yes| I[スコア保存]
    I --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | リスト表示形式 | courselistnum>=4の場合はスクロール対応リスト | courselistnum>=4 |
| BR-02 | auto時スキップ | auto=1の場合はコースリザルト表示をスキップ | auto=1 |
| BR-03 | 文字エンコード | 各曲タイトルはUTF-8/Shift-JIS自動判定 | 譜面ファイル読み込み時 |

### 計算ロジック

- リスト項目高さ: `stat_h = 128*scale + 4*(courselistnum>=4)*scale + 36*(courselistnum<4)*scale`（course_result.hsp 4行目）

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

本機能ではデータベース操作は行わない。ファイルベースのスコア保存のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 譜面ファイル不在 | コース内曲のファイルが見つからない | 代替パスを検索 |

### リトライ仕様

リトライ処理は実装されていない。

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

トランザクション処理は適用されない。

## パフォーマンス要件

特に厳密な要件なし。

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

特になし。

## 備考

- コースリザルト画面はリザルト画面と共通の画像リソース（result.png, result_grade.png等）を使用する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | IMG_CRESULT_* 定数定義 |

- **95-100行目**: IMG_CRESULT_INFO=158, IMG_CRESULT_ITEM=154, IMG_CRESULT_LISTBUF=156, IMG_CRESULT_ARROW=159, IMG_CRESULT_GAUGE=160, IMG_CRESULT_NEWRECORD=155

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | course_result.hsp | `src/scene/course_result.hsp` | on_update_course_resultサブルーチン |

**主要処理フロー**:
1. **1行目**: `#deffunc on_update_course_result`
2. **4行目**: リスト項目高さ計算
3. **5-21行目**: auto/adjmode時のスキップ処理
4. **53-69行目**: コースリザルト専用画像の読み込み
5. **71-100行目**: 各曲のタイトル・アーティスト読み込みとリスト生成

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

```
kshootmania.hsp (メインループ: 1082行目 case SCENE_COURSE_RESULT)
    │
    └─ on_update_course_result (src/scene/course_result.hsp: 1行目)
           ├─ 画像リソース読み込み（result.png, courseresult_*.png等）
           ├─ 各曲譜面ファイルからタイトル・アーティスト読み込み
           ├─ IMG_CRESULT_LISTBUFへのリスト描画
           ├─ コーススコア保存処理
           └─ SCENE_SELECT遷移
```

### データフロー図

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

coursetotalscore ───────────▶ グレード判定 ────────────────▶ 合計スコア・グレード表示
coursecritical/near/errorn ─▶ 判定詳細描画 ────────────────▶ 判定数表示
各曲.kshファイル ───────────▶ タイトル読み込み ──────────────▶ 曲リスト表示
各曲スコアデータ ───────────▶ リスト生成 ─────────────────▶ IMG_CRESULT_LISTBUF
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| course_result.hsp | `src/scene/course_result.hsp` | ソース | コースリザルト画面の全処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ・定数定義 |
| courseresult_info.png | `imgs/courseresult_info.png` | 画像 | コースリザルト情報表示枠 |
| courseresult_item.png | `imgs/courseresult_item.png` | 画像 | 各曲リスト項目枠 |
| courseresult_arrow.png | `imgs/courseresult_arrow.png` | 画像 | スクロール矢印 |
| courseresult_gauge.png | `imgs/courseresult_gauge.png` | 画像 | ゲージ表示画像 |
| courseresult_newrecord.png | `imgs/courseresult_newrecord.png` | 画像 | NEW RECORD表示画像 |
| courseresult_bgm.ogg | `se/courseresult_bgm.ogg` | 音声 | コースリザルトBGM |
