openapi: 3.0.3
info:
  title: あおば勤怠デモ API
  version: 0.1.0
  description: >
    架空データ専用。サーバが record_url と confirm_url を返す。GET は勤怠を変更しない。
    更新はプレビューのあと、人が confirmPreview するか確認ページで確定する。
    actor_code はデモ身分であり SSO ではない。
    実行中プロセスのリンク原点は環境変数 BASE_URL。このファイルの servers は配布用の公網原点。
servers:
  - url: https://kq.talqee.com
    description: Packaged public origin. The running process still emits record_url from BASE_URL.
paths:
  /api/v1/actors:
    get:
      operationId: listDemoActors
      summary: 架空のデモ身分
      parameters:
        - $ref: "#/components/parameters/ActorCode"
      responses:
        "200":
          description: 身分一覧。results[].actor_code を後続の呼び出しに使う。
  /api/v1/months:
    get:
      operationId: searchMonths
      summary: 月次の検索
      description: year_month を省略するとデモ日付の月。flag は unsubmitted, unentered, overtime_over_45, pending_first, pending_second, approved, rejected, returned, draft。
      parameters:
        - $ref: "#/components/parameters/ActorCode"
        - name: year_month
          in: query
          schema: { type: string, example: "2026-03" }
        - name: department
          in: query
          description: DEV, SAL, HQ または部門名
          schema: { type: string }
        - name: team
          in: query
          schema: { type: string }
        - name: flag
          in: query
          schema: { type: string }
      responses:
        "200":
          description: results[] に title, subtitle, record_url, overtime_over_45, unentered_days, status。
  /api/v1/employees/{employee_code}/months/{year_month}:
    get:
      operationId: getMonth
      summary: 月次明細
      parameters:
        - $ref: "#/components/parameters/EmployeeCode"
        - $ref: "#/components/parameters/YearMonth"
        - $ref: "#/components/parameters/ActorCode"
      responses:
        "200":
          description: 月次と days[]。各 day.record_url と record_url はサーバ生成。
  /api/v1/approvals:
    get:
      operationId: listApprovalQueue
      summary: 承認待ち
      parameters:
        - $ref: "#/components/parameters/ActorCode"
        - name: year_month
          in: query
          schema: { type: string }
      responses:
        "200":
          description: results は待ち行列。各要素の record_url を開く。
  /api/v1/audit:
    get:
      operationId: listAudit
      summary: 監査ログ
      parameters:
        - $ref: "#/components/parameters/ActorCode"
      responses:
        "200":
          description: results[] に summary, at, record_url。
  /api/v1/previews/day-entries:
    post:
      operationId: createDayPreview
      summary: 日別修正のプレビュー
      description: 勤怠は変更しない。diff の old/new と confirm_url をユーザに見せる。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DayPreview"
      responses:
        "200":
          description: preview_id, expected_version, confirm_url, record_url, diff, mutated=false
        "409":
          description: 承認済、提出中、版の不一致、冪等キーの衝突
  /api/v1/previews/month-actions:
    post:
      operationId: createMonthActionPreview
      summary: 提出・承認などのプレビュー
      description: action は submit, withdraw, approve, reject, return。reject と return は reason が必須。勤怠はまだ変わらない。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionPreview"
      responses:
        "200":
          description: 状態の変更前と変更後、confirm_url。mutated=false
        "409":
          description: 月末前、未入力、休憩不足、承認者違い、段階違い
  /api/v1/previews/{preview_id}:
    get:
      operationId: getPreview
      summary: プレビューを見る
      description: この GET は勤怠もプレビューも変更しない。
      parameters:
        - $ref: "#/components/parameters/PreviewId"
        - $ref: "#/components/parameters/ActorCode"
      responses:
        "200":
          description: diff と confirm_url。mutated=false
  /api/v1/previews/{preview_id}/confirm:
    post:
      operationId: confirmPreview
      summary: プレビューを確定
      description: ユーザが明示的に確定したときだけ呼ぶ。成功応答の committed が true のときだけ保存済み。
      parameters:
        - $ref: "#/components/parameters/PreviewId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Confirm"
      responses:
        "200":
          description: committed=true, audit_id, record_url, 更新後の月次
        "409":
          description: 版が古い、期限切れ、すでに閉じたプレビュー
components:
  parameters:
    ActorCode:
      name: actor_code
      in: query
      required: true
      description: デモ身分。例 E002, TL01, M001。SSO トークンではない。
      schema: { type: string }
    EmployeeCode:
      name: employee_code
      in: path
      required: true
      schema: { type: string }
    YearMonth:
      name: year_month
      in: path
      required: true
      schema: { type: string, example: "2026-03" }
    PreviewId:
      name: preview_id
      in: path
      required: true
      schema: { type: string }
  schemas:
    DayChange:
      type: object
      required: [work_date]
      properties:
        work_date: { type: string, example: "2026-03-02" }
        start_time: { type: string, nullable: true, example: "08:40" }
        end_time: { type: string, nullable: true, example: "18:10" }
        end_next_day: { type: boolean, default: false }
        break_minutes: { type: integer, default: 60 }
        memo: { type: string }
    DayPreview:
      type: object
      required: [actor_code, employee_code, year_month, expected_version, idempotency_key, days]
      properties:
        actor_code: { type: string }
        employee_code: { type: string }
        year_month: { type: string }
        expected_version: { type: integer }
        idempotency_key: { type: string, description: 同じキーと同じ内容は同じプレビューを返す }
        days:
          type: array
          items: { $ref: "#/components/schemas/DayChange" }
    ActionPreview:
      type: object
      required: [actor_code, employee_code, year_month, action, expected_version, idempotency_key]
      properties:
        actor_code: { type: string }
        employee_code: { type: string }
        year_month: { type: string }
        action: { type: string, enum: [submit, withdraw, approve, reject, return] }
        reason: { type: string }
        expected_version: { type: integer }
        idempotency_key: { type: string }
    Confirm:
      type: object
      required: [actor_code, expected_version]
      properties:
        actor_code: { type: string }
        expected_version: { type: integer, description: プレビュー応答の expected_version をそのまま渡す }
