# サーバーAPI変更要求書

**日付**: 2025年9月5日  
**要求者**: システム開発チーム  
**対象API**: 通過履歴承認API  

## 変更概要

通過履歴の承認処理において、従来の「承認」に加えて「要訂正（仮発行）」機能を追加するため、APIの拡張を要求します。

## 対象API

### エンドポイント
```
POST /api/approve_checkin_history
```

## 変更内容

### 現在のリクエストパラメータ
```json
{
  "event_code": "string",
  "zekken_number": "string", 
  "checkin_ids": [int],
  "approval_comment": "string" (optional)
}
```

### 変更後のリクエストパラメータ
```json
{
  "event_code": "string",
  "zekken_number": "string",
  "checkin_ids": [int], 
  "approval_comment": "string" (optional),
  "acc_flag": boolean (optional, new)
}
```

### 新規追加パラメータ詳細

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|-----|------------|-----|
| acc_flag | boolean | No | true | 承認フラグ<br>- `true`: 通常の承認処理（自動印刷実行）<br>- `false`: 要訂正（仮発行処理） |

## 処理仕様

### acc_flag = true（承認）の場合
- 従来通りの承認処理を実行
- サーバー側で自動印刷を実行
- 承認ステータスを「承認済み」に更新

### acc_flag = false（要訂正/仮発行）の場合  
- 仮発行処理を実行
- 通過訂正依頼の自動印刷を行う。
- 承認ステータスを「要訂正」または適切なステータスに更新
- 後で再度承認処理が可能な状態を維持

### acc_flagが省略された場合
- デフォルト値 `true` として処理（従来の承認処理）
- 既存のクライアントとの互換性を保持

## レスポンス仕様

現在のレスポンス形式を維持し、処理結果に応じてメッセージを調整：

```json
{
  "status": "OK",
  "approved_count": int,
  "message": "string"
}
```

### メッセージ例
- 承認時: "通過履歴の承認が完了しました"
- 仮発行時: "通過履歴の仮発行が完了しました"

## 実装優先度

**高**: クライアント側実装完了済み、サーバー側対応待ち

## 補足事項

- 既存のAPIとの互換性を保持すること
- acc_flagパラメータは省略可能とし、省略時は従来の承認処理を実行
- エラーハンドリングは既存の仕様を継承
- ログ出力にacc_flagの値を含めることを推奨

## 影響範囲

- 通過履歴承認API（/api/approve_checkin_history）
- 承認処理ロジック
- 印刷処理の制御
- 承認ステータス管理

## テスト項目

1. acc_flag=trueでの承認処理（従来通り）
2. acc_flag=falseでの仮発行処理
3. acc_flag省略時のデフォルト動作
4. 不正なacc_flag値のエラーハンドリング
5. 既存クライアントとの互換性確認