# オークションサイト 要件定義（現時点）

## 1. 目的

自社在庫をオークション形式で販売するサイトを構築する。

特に重視することは次の2点。

- 現場スタッフがスマホだけで迷わず出品できること
- 購入者がヤフオクに近い感覚で入札できること

本要件定義は、`Shopify を使うかどうかに依存しない` 形で、サイトとして実現したい機能と運用ルールを整理したものとする。

---

## 2. サービスの前提

- 初期段階では `自社スタッフのみ出品`
- 購入者は `一般会員`
- 商品は `自社在庫品`
- 主な商材は以下
  - スマホ
  - PC
  - ゲーム機
  - トレカ
  - 周辺機器

---

## 3. 実現したい全体像

### スタッフ側

1. スマホで商品情報を入力
2. 写真を登録
3. カテゴリ別テンプレートで説明文を作る
4. 下書き保存または出品登録する
5. 出品中、終了、取消、再出品を管理する

### 購入者側

1. 商品一覧またはカテゴリ一覧から商品を見る
2. 商品詳細で現在価格、終了日時、送料条件などを確認する
3. ログインして入札する
4. 必要ならウォッチする
5. 落札後はマイページから支払いへ進む

---

## 4. 出品管理の要件

出品状態は次の5段階で管理する。

- `下書き`
- `出品登録済み`
- `出品中`
- `終了`
- `取消`

### 各状態でできること

#### 下書き

- 編集
- 下書き保存
- 出品登録
- 取消

#### 出品登録済み

- 編集
- 出品開始
- 下書きへ戻す
- 取消

#### 出品中

- 商品内容確認
- 終了
- 早期終了
- 入札取消
- 取消

#### 終了

- 落札結果確認
- 未払い確認
- 再出品

#### 取消

- 再出品

---

## 5. スタッフ向け出品UIの要件

スマホだけで操作しやすいことを前提とする。

### 出品時に必要な入力

- 商品名
- カテゴリ
- 商品画像
- 状態ランク
- 商品説明
- 注意事項
- 付属品
- 開始価格
- 最低落札価格
- 開始日時
- 終了日時
- 自動延長の有無
- 在庫数
- 管理番号
- 送料負担
  - 元払い（出品者負担）
  - 着払い（購入者負担）
- 配送方法
  - ゆうパック
  - 佐川急便
- 早期終了の可否

### カテゴリ別テンプレート

カテゴリに応じて、説明文を自動生成できるようにする。

例:

- スマホ
  - 機種名
  - 容量
  - 色
  - バッテリー
  - SIMロック
  - 画面状態
  - 背面状態
- PC
  - メーカー
  - 型番
  - CPU
  - メモリ
  - SSD
  - OS
  - 動作状態
- ゲーム機
  - 機種
  - 型番
  - 付属品
  - 動作確認

---

## 6. 購入者向け商品ページの要件

商品ページは `商品理解` と `入札判断` がしやすい構成にする。

### 表示する情報

- 商品名
- 商品画像
- 商品説明
- 商品情報テーブル
- 現在価格
- 入札件数
- 終了日時
- 残り時間
- 次の最低入札額
- 送料負担
- 配送方法
- 支払い方法
- 自動延長の有無
- 最低落札価格の有無

### ページの動作

- 未ログイン時は入札フォームを出さず、ログイン導線を表示
- ログイン済みで条件を満たす場合だけ入札フォームを表示
- 商品ページ上で価格、件数、残り時間は自動更新される
- 入札履歴の詳細は `○件` リンクから別ページで見る

---

## 7. 入札方式の要件

入札方式は `ヤフオクに近い最高入札額方式` を採用する。
迷う論点については **ヤフオク踏襲** を基本方針とする。

### 基本ルール

- ユーザーは `最高入札額` を入力する
- 同額なら `先に受け付けた方` が優先
- 自動入札で価格を競り上げる
- ユーザー側からの自発的な入札取消は不可
- 出品者・管理者による入札取消は可能（§21 参照）

### 即決機能の扱い

- **即決価格は採用しない**（運用を複雑にしないため）
- 商品ページ・出品フロー・データモデルから即決価格関連を除外する

### 自動延長

- 終了5分前以内に入札があったら5分延長
- **延長は無制限**（回数制限なし、ヤフオク踏襲）

### 次の最低入札額

現在価格に対して、入札単位に応じた `次の最低入札額` を表示する。

### 入札単位

- 1円〜999円: 10円
- 1,000円〜4,999円: 100円
- 5,000円〜9,999円: 250円
- 10,000円〜49,999円: 500円
- 50,000円以上: 1,000円

### 入札失敗時のエラーメッセージ

理由ごとに明示する。

- `他の方が先に同額で入札しました（先着順）`
- `最低入札額（¥XXX）に満たない金額です`
- `あなたは既に最高入札中です`
- `SMS認証が完了していません`
- `高額商品（¥30,000以上）の入札制限中です`
- `ブラックリスト登録のため入札できません`
- `オークションは既に終了しました`
- `ネットワークエラー：再送してください`

### 大量入札への耐性

本番では次を前提に実装する。

- オークション単位で直列処理
- 同時入札時の整合性維持
- 監査可能な入札記録
- 二重送信防止（idempotency key）

---

## 8. ログイン・会員機能の要件

### 会員登録

- メールアドレス
- パスワード
- 表示名

### ログイン

- ヘッダー右上からログインできる
- 商品ページで未ログイン時は入札不可

### SMS認証

- 入札前に SMS 認証を必須にする
- マイページから SMS 認証を完了できる

---

## 9. マイページの要件

ログイン済み購入者が、自分の参加状況を一覧で把握できるようにする。

### 必須セクション

- 支払い待ち
- 入札中
- 高値更新中
- 落札済み
- ウォッチ中
- 通知一覧

### できること

- 購入待ち商品の確認
- ウォッチ商品の確認
- 通知確認
- SMS認証状況の確認
- ログアウト

ログアウト導線はマイページにのみ置く。

---

## 10. ウォッチ機能の要件

- 商品ページから `ウォッチ` できる
- 再度押すと解除できる
- ウォッチした商品はマイページに一覧表示する

---

## 11. 入札履歴ページの要件

- 商品ページの `○件` リンクから遷移する
- 未ログインでは見られない
- ログイン済みユーザーだけ履歴一覧を見られる
- 公開するのは `表示価格の履歴`
- 各ユーザーの最高入札額そのものは公開しない

---

## 12. 落札後の要件

### 支払い期限

- 落札後 **72時間** を支払い期限とする（固定、ヤフオク踏襲）
- 期限内は `購入手続きへ進む` を表示
- 期限到達で **自動的に未払い取消** （バッチで定期実行）

### 支払い方法（対応するもの）

運用簡素化と返金自動化のため、**カード決済とQR決済のみ** に絞る。
コンビニ払い・銀行振込・代引きは対応しない。

- クレジットカード（Visa / Mastercard / JCB / AMEX）
- QRコード決済（PayPay 想定。必要に応じて楽天Pay / d払い等を追加検討）

これにより、すべての返金が決済プロバイダーAPI経由で自動化できる。

### 支払い期限の警告通知タイミング

落札者に対し、以下のタイミングで **サイト内通知 ＋ メール送信** の両方で通知する。

- 落札直後（落札通知）
- 期限まで残り24時間
- 期限まで残り6時間
- 期限まで残り1時間

メール送信の詳細は §22 を参照。

### 未払い時の処理（落札者起因）

- `unpaidCount` を加算
- 落札者に通知
- 商品は「終了（未払い取消）」状態へ
- **次点繰り上げ落札は採用しない**（運用を複雑にしないため）
- 必要に応じて再出品（内容コピーで新規下書きを作成）

### 落札者都合のキャンセル要請

- 原則不可（オークションは原則キャンセル不可）
- 例外的にやむを得ない事情があれば、取引メッセージで運営と相談 → 個別判断
- 認める場合は `unpaidCount` を加算

### 出品者（運営）都合のキャンセル

詳細は **§21 取消・返金フロー** を参照。

- 商品破損・紛失・在庫違いなどの場合、運営側からキャンセル可能
- 落札者の `unpaidCount` には影響させない
- 支払い済みの場合は **返金処理が必要**（決済方法ごとにフロー異なる）
- お詫び（クーポン・ポイント等）の有無は運用ポリシーで決定

---

## 13. 悪質ユーザー対策の要件

### 制限対象

- SMS未認証
- 悪い評価割合が高い
- 総合評価が低い
- 未払い履歴が多い
- ブラックリスト登録済み

### ルール

- `unpaidCount = 1`
  - 警告
- `unpaidCount = 2`
  - 高額商品の入札不可
- `unpaidCount >= 3`
  - 自動ブラックリスト

### 管理項目

- verified
- ratingScore
- badRatio
- unpaidCount
- riskScore
- blocked
- blockedReason

### 高額商品の定義

以下のいずれかを満たす場合を高額商品とする。

- 最低落札価格 30,000円以上
- 現在価格 30,000円以上

---

## 14. 出品者による制御の要件

出品者または管理者は次を操作できる。

### 出品中の操作
- 入札取消（個別）
- 同一オークションへの再入札禁止
- 早期終了
- 出品取消（理由必須、入札者全員に通知）

### 落札後の操作
- 取引キャンセル（運営都合）— §21 参照
- 返金処理（クレカ/PayPay は自動、コンビニ/銀行振込は手動）— §21 参照
- 取引メッセージでの個別連絡

### 入札者管理
- ブラックリスト登録
- ブラックリスト解除
- 未払い回数の加算 / クリア

---

## 15. コメント・メッセージ機能の要件

### 落札前

`公開質問`

- 商品ページ下に設置
- 購入検討者が質問できる
- 出品者が回答したものだけ公開表示
- 電話番号、個人情報、外部取引誘導は弾く

### 落札後

`非公開メッセージ`

- 落札者と出品者だけ見られる
- 支払い、発送、到着、返品相談に使う
- 商品ページではなく、マイページ内でやり取りする

---

## 16. 監査ログの要件

`誰が、いつ、何をしたか` を追えるようにする。

### 保存対象

- 入札取消
- 早期終了
- 出品公開
- 下書き戻し
- 出品取消
- 再出品
- ブラックリスト登録 / 解除
- 未払い加算 / クリア
- 購入者条件変更
- 未払い自動取消

### 監査ログに持つ項目

- actor
- actorRole
- actionType
- entityType
- entityId
- auctionId
- bidder
- title
- message
- details
- at

---

## 17. カテゴリページ / 一覧ページの要件

### すべての商品

- 全商品一覧
- カテゴリ横断で比較
- 現在価格
- 入札件数
- 残り時間

### カテゴリページ

スマホ専門サイトのため、世代別に細分化する。

iPhone:
- iPhone 17
- iPhone 16
- iPhone 15
- iPhone 14
- iPhone 13以前

Android:
- Galaxy
- Pixel
- Xperia / AQUOS
- その他Android

周辺機器:
- ケース・フィルム
- 充電器・ケーブル
- イヤホン
- スマートウォッチ
- SIM・メモリ
- ジャンク・パーツ
- その他周辺機器

カテゴリページから商品詳細へ遷移できること。

---

## 18. デザインの方向性

- 参考は `ヤフオク`
- ただし完全コピーはしない
- 情報密度は高め
- 1カラム目は商品理解
- 2カラム目は入札判断
- 商品ページ、マイページ、入札履歴ページでヘッダーや世界観を統一する

---

## 19. 本番運用のために必要な技術要件

大量同時入札に耐えるため、保存基盤は最終的に DB を正にする。

必要な考え方:

- オークション単位のトランザクション
- bid intents の保存
- idempotency key
- 同時入札試験
- 監査可能なイベント記録

---

## 20. 現時点の方針

このサイトは次の前提で進める。

- 自社スタッフのみ出品（出品者は SP AUCTION 公式の単一アカウント）
- 購入者は会員登録して入札
- SMS認証あり
- ヤフオク寄せの入札方式
- **即決価格は無し**（運用簡素化のため、§7）
- **自動延長は無制限**（ヤフオク踏襲、§7）
- **次点繰り上げ落札は無し**（§12）
- **支払い期限 72時間固定**（§12）
- スマホ特化（iPhone・Android・周辺機器のみ取扱、§17）
- ネットワーク利用制限なしの端末のみ取扱（§17）
- 出品者評価は公式ストア前提のため簡略化（個別評価ロジック不要）
- コメントは落札前後で分離
- 未払い・ブラックリスト・監査ログを持つ
- スマホでも素人スタッフが扱える出品UIにする
- 迷う論点は **ヤフオク踏襲** を基本

---

## 21. 取消・返金フローの要件

### 21-1. 出品中の取消（落札確定前）

#### 入札ゼロ件のとき

- 自由に取消できる
- 監査ログ記録のみ

#### 入札ありのとき

- 取消可能。ただし以下を厳守：
  - **取消理由を必須入力**（例：商品破損 / 在庫紛失 / 検品で不具合発見 / その他）
  - すべての入札者に通知（プッシュ＋メール）
  - 入札者の `unpaidCount` には影響させない（出品者都合のため）
  - 商品は「取消」状態へ
  - 必要であれば内容コピーで新規下書きを作成して再出品
- 監査ログに `auction_cancelled_by_seller` 記録

#### 個別の入札取消

- 吊り上げ疑い・嫌がらせ入札・連絡不能の入札者などに対して
- 取消理由を記録、本人に通知
- 取り消した入札以降の現在価格は再計算
- 監査ログに `bid_cancelled` 記録

### 21-2. 落札確定後のキャンセル

#### 落札者都合（原則不可）

- 原則キャンセル不可（オークションは確定）
- やむを得ない事情がある場合、取引メッセージで運営と相談 → 個別判断
- 認める場合は `unpaidCount` を加算
- 監査ログに `cancellation_by_buyer` 記録

#### 出品者（運営）都合（条件付きで可）

商品破損・紛失・在庫違い・検品で不具合発見などのケース。

支払いフェーズ別に対応が異なる：

##### 支払い前（落札後72h以内・未払い）の場合

- 取引メッセージで落札者に謝罪＋理由説明
- 取引を **キャンセル状態** へ
- 落札者の `unpaidCount` には影響なし
- お詫び（クーポン・ポイント等）の発行は運用ポリシーで判断
- 監査ログに `transaction_cancelled_by_seller` 記録

##### 支払い後（入金済み・発送前 or 配送中）の場合

- 取引メッセージで落札者に謝罪＋理由説明
- **返金処理が必須**（決済方法別、後述）
- 落札者の `unpaidCount` には影響なし
- 商品は「終了・運営都合キャンセル」状態へ
- 監査ログに `transaction_cancelled_with_refund` 記録

### 21-3. 返金経路（決済方法別）

決済はクレカ/QRのみのため、**すべての返金が自動化** される。

| 支払い方法 | 返金経路 | 所要時間 | 手数料 |
|---|---|---|---|
| クレジットカード | 決済プロバイダー API で refund 実行 | 即時〜数日（カード会社次第） | 通常無料 |
| QR決済（PayPay等） | プロバイダー API で返金 | 即時 | 無料 |

### 21-4. 返金フロー（管理画面の操作手順）

1. 運営が「取引キャンセル」を実行（理由必須）
2. 取引メッセージに自動でお詫び文 + 返金案内を投稿
3. 決済プロバイダーの refund API を自動コール
4. プロバイダーからの完了Webhookを受信
5. 取引ステータスを「返金完了」に更新
6. 落札者へ **サイト内通知 ＋ メール** で完了報告
7. 監査ログに `refund_completed` 記録

返金失敗時：
- 自動リトライ（最大3回、指数バックオフ）
- それでも失敗した場合は運営の手動対応キューに送る
- 落札者には「処理中、もう少々お待ちください」と表示

### 21-5. 配送中の事故（紛失・破損）

責任主体ごとに分岐：

#### 発送前

- 完全に出品者責任
- §21-2「支払い後キャンセル」フローと同様

#### 発送後 / 配送中

- 配送業者の責任（ヤマト・郵便局の補償制度を利用）
- 運営は配送業者に補償請求
- その間、落札者には「商品が届かない場合は補償します」と連絡
- 補償が確定したら落札者に返金

### 21-6. 受け取り後の返品

- 商品説明と違う商品が届いた場合 → 出品者責任で全額返金
- 落札者の都合（思っていたのと違う等）→ 原則返品不可
- 個別判断は取引メッセージで対応

### 21-7. 必要な管理画面機能（実装時のメモ）

- 取引詳細ページに「取引をキャンセル」ボタン
- キャンセル理由テンプレ（破損 / 紛失 / 検品NG / 顧客都合 / その他）
- 返金処理パネル（決済方法に応じて自動/手動を切替表示）
- 返金履歴の表示
- **新規ページ**: 返金キュー（手動返金が必要な取引の一覧）
- **新規ページ**: 配送業者補償申請の管理（補償番号管理）

### 21-8. 落札者向けUI追加

- マイページに「キャンセル済み」セクション
- 取引メッセージ内で返金状況を確認可能
- 「返金開始」「返金完了」のステータス通知

---

## 22. 通知・メール配信の要件

サイト内通知だけでは伝達力が弱いため、重要イベントは **メール送信を併用** する。

### 22-1. 通知チャネル

- **サイト内通知**：マイページ・ヘッダーベルアイコン（必須）
- **メール**：すべての重要イベントで自動送信（必須）
- **プッシュ通知（PWA）**：将来追加（任意）
- **SMS通知**：認証コードのみ（マーケ通知では使わない）

### 22-2. メール送信が必要なイベント

**購入者向け（落札者・入札者）**
- 会員登録完了
- メール認証リンク
- パスワードリセットリンク
- SMS認証関連の補完通知
- 入札受付完了（自分の入札）
- 高値更新通知（自分が上回られた）
- 自動延長通知（自分の入札商品）
- 落札通知（おめでとう＋支払い案内）
- 支払い期限警告（24h前・6h前・1h前）
- 支払い完了確認
- 発送通知（追跡番号付き）
- 取引メッセージ受信
- 質問への回答（自分の質問）
- 取引完了
- キャンセル通知（運営都合）
- 返金開始・返金完了
- 未払い警告・未払い確定通知
- ブラックリスト登録・解除

**スタッフ向け**
- 新規入札（重要：高額のみ）
- 落札確定
- 支払い完了
- 新規質問
- 取引メッセージ受信
- 未払い発生
- 期限超過自動取消
- ブラックリスト自動登録
- 返金失敗（要手動対応）

### 22-3. メールテンプレート構造

各メールテンプレートは以下を持つ：

- `template_id`（識別子）
- `subject`（件名、変数差し込み可）
- `body_text`（プレーンテキスト本文）
- `body_html`（HTML本文。ブランドカラー・ロゴ入り）
- `variables`（差し込み変数の一覧）
- `cta_url`（クリック先URL、サイト内のディープリンク）

例：`tx_won`（落札通知）テンプレ：

```
template_id: tx_won
subject: 【SP AUCTION】落札おめでとうございます — {{product_name}}
variables:
  - product_name
  - price
  - deadline_at
  - tx_detail_url
cta_url: {{tx_detail_url}}
```

### 22-4. 配信プロバイダー

要件：
- 日本語環境で安定動作
- 配信成功率（reputation）が高い
- API/SMTP両対応
- バウンス・スパムレポート処理
- テンプレート機能 or 自前テンプレ運用可

候補（実装時に決定）：
- **Resend**（推奨）：日本でも使いやすく、シンプルなAPI
- SendGrid：実績豊富だが料金やや高め
- AWS SES：安価だがレピュテーション管理が必要
- Postmark：トランザクションメールに特化

### 22-5. 送信元・運用

- `From`：`SP AUCTION <noreply@sp-auction.example.com>`
- `Reply-To`：`support@sp-auction.example.com`（運営に届く）
- 認証：SPF / DKIM / DMARC を設定
- バウンス・苦情自動処理：送信失敗が続いたアドレスは無効化

### 22-6. ユーザー側の通知設定

- マイページ → 通知設定 でメールON/OFF可能（カテゴリ別）
  - **トランザクション系**（落札・支払い・発送・取引メッセージ）→ ON固定（OFFにできない）
  - **マーケ系**（キャンペーン・お得情報）→ ON/OFF切替可能
- メール内の配信解除リンクは法令上必須

### 22-7. 配信ログ

すべての送信を記録（DBテーブル `mail_logs`）：
- `to`, `template_id`, `subject_rendered`, `status`, `provider_message_id`, `sent_at`, `delivered_at`, `opened_at`, `bounced_at`
- 監査・トラブル対応・分析に利用

---

## 更新履歴

- **2026-05-19 v0.4**：
  - 支払い方法を **クレカ／QR決済のみ** に限定（コンビニ・銀行振込・代引きは対応せず、§12）
  - これにより返金が完全自動化（§21-3 / §21-4 を簡素化）
  - **§22 通知・メール配信の要件** を新設（イベント一覧／テンプレ構造／プロバイダー候補／ユーザー設定／配信ログ）
  - 支払い期限の警告通知に「メール送信併用」を明記（§12）
- **2026-05-19 v0.3**：
  - 即決価格を廃止（§5/§6/§7/§13/§17 から関連項目を削除）
  - 自動延長を **無制限** と明文化（§7、ヤフオク踏襲）
  - 入札失敗時のエラーメッセージパターンを追加（§7）
  - 支払い期限の警告タイミングを明記（§12）
  - 次点繰り上げ落札は **採用しない** と決定（§12）
  - **§14 落札後のキャンセル機能** を追加
  - **§17 カテゴリ** をスマホ世代別に細分化
  - **§21 取消・返金フロー** を新設（出品中／落札後／決済別返金経路）
  - 「迷う論点はヤフオク踏襲」を基本方針として §7 / §20 に明記
- **2026-05-19 v0.2**：出品者評価ロジックを簡素化（SP AUCTION 公式ストア前提）
- 初版：オークションサイト要件定義