openapi: 3.0.3
info:
  title: HDGP Engine API
  description: |
    厚德归朴（HDGP）Engine API。  
    Engine 为规则评估组件，不接入 LLM；规则判定逻辑由开发期写死的规则 + 治理流程后的规则包决定。
  version: 0.1.0-mvp
  contact:
    name: HDGP Protocol (Founder: Yvaine.He)
    url: https://github.com/HumanDignityGuardian/HDGP-protocol
    email: yvaine@hdgp-protocol.com
  x-appeal-email: ethics@hdgp-protocol.com

servers:
  - url: http://localhost:8080
    description: 本地开发

paths:
  /hdgp/v1/evaluate:
    post:
      summary: 评估候选输出
      description: |
        对候选输出（如 LLM 回复）进行伦理/规则评估与判定。
        返回 verdict（allow/modify/block/fuse）、rules_triggered、actions。
      operationId: evaluate
      parameters:
        - name: include_report
          in: query
          required: false
          schema:
            type: string
            enum: ["true", "1", "false", "0"]
          description: 为 true 或 1 时，响应附带人可读的 report 字段
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EvaluateRequest"
      responses:
        "200":
          description: 评估结果
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EvaluateResponse"
        "400":
          description: 请求体无效（JSON 解析失败等）

  /hdgp/v1/status:
    get:
      summary: 健康检查与版本信息
      description: 返回 Engine 版本、spec 版本、policy 配置，用于可用性探测与版本校验。
      operationId: getStatus
      responses:
        "200":
          description: 状态信息
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"

  /hdgp/v1/integration:
    get:
      summary: 集成与申请通路元数据（公开只读）
      description: |
        返回自助集成提示：排期模式（waitlist/self_hosted）、可选的 API Key 申请外链、
        无需鉴权的公开路径、以及 OpenAPI/一键脚本相对路径引用。不包含密钥。
      operationId: getIntegration
      responses:
        "200":
          description: 集成元数据
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntegrationResponse"

components:
  schemas:
    EvaluateRequest:
      type: object
      required: [meta, subject, candidate]
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
        subject:
          $ref: "#/components/schemas/Subject"
        input:
          $ref: "#/components/schemas/EvaluateInput"
        candidate:
          $ref: "#/components/schemas/Candidate"

    Meta:
      type: object
      properties:
        request_id: { type: string }
        scene:
          type: object
          properties:
            domain: { type: string }
            intent: { type: string }
            risk_level: { type: string }
            sensitivity: { type: array, items: { type: string } }
        policy:
          type: object
          properties:
            spec_version: { type: string }
            strategy_id: { type: string }
            bundles: { type: array, items: { type: string } }

    Subject:
      type: object
      required: [type]
      properties:
        type: { type: string }
        skill_id: { type: string }
        label: { type: string }

    EvaluateInput:
      type: object
      properties:
        prompt: { type: string }
        context: {}

    Candidate:
      type: object
      properties:
        text: { type: string }
        structured: {}
        raw: {}

    EvaluateResponse:
      type: object
      properties:
        request_id: { type: string }
        verdict: { type: string }
        actions: { type: array, items: { $ref: "#/components/schemas/Action" } }
        effective_output: { $ref: "#/components/schemas/EffectiveOutput" }
        rules_triggered: { type: array, items: { $ref: "#/components/schemas/RuleHit" } }
        engine_info: { $ref: "#/components/schemas/EngineInfo" }
        report: { type: string, description: 仅 include_report=true 时返回 }

    Action:
      type: object
      properties:
        type: { type: string }
        message: { type: string }
        details: { type: object }

    EffectiveOutput:
      type: object
      properties:
        text: { type: string }
        structured: {}

    RuleHit:
      type: object
      properties:
        rule_id: { type: string }
        principle_id: { type: string }
        article_id: { type: string }
        effect: { type: string }
        severity: { type: string }

    EngineInfo:
      type: object
      properties:
        version: { type: string }
        policy: { type: object }

    StatusResponse:
      type: object
      properties:
        engine_version: { type: string }
        spec_version: { type: string }
        policy:
          type: object
          properties:
            spec_version: { type: string }
            strategy_id: { type: string }
            bundles: { type: array, items: { type: string } }

    IntegrationResponse:
      type: object
      properties:
        generated_at_utc: { type: string, format: date-time }
        engine_version: { type: string }
        onboarding:
          type: object
          properties:
            mode: { type: string, enum: [self_hosted, waitlist] }
            api_key_request_url: { type: string, description: 可选，API Key / 候补申请外链 }
            note_zh: { type: string }
            note_en: { type: string }
        public_paths_no_api_key:
          type: array
          items: { type: string }
        quickstart:
          type: object
          properties:
            evaluate_path: { type: string }
            example_script_relative: { type: string }
            openapi_spec_relative: { type: string }
            readme_relative: { type: string }