product-report-reasons:
  get:
    tags: [Lookups]
    summary: List active product report reasons
    operationId: listProductReportReasons
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9521-17267&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9521:17267"
    description: |
      Returns the active, non-deleted report-reason catalogue in the requested
      response language. This operation requires the application `secretkey`
      only and accepts no query parameters.

      The icon is always a usable URL. When an administrator did not upload an
      icon, or the configured local file is missing, the server returns the
      bundled product-report fallback icon.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9521-17267&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a></div>
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    responses:
      '200':
        description: Active reasons returned in display order.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ProductReportReasonsResponse'
            examples:
              arabic:
                value:
                  key: success
                  message: تم جلب أسباب الإبلاغ بنجاح
                  status: 200
                  data:
                    reasons:
                      - id: 66a1b2c3d4e5f67890123456
                        title: إعلان وهمي
                        description: استخدم هذا السبب عندما يبدو المنتج أو العرض غير حقيقي.
                        icon: https://example.com/admin/assets/img/product-report-reason-fallback.svg
              english:
                value:
                  key: success
                  message: Product report reasons loaded successfully
                  status: 200
                  data:
                    reasons:
                      - id: 66a1b2c3d4e5f67890123456
                        title: Fake listing
                        description: Use this reason when the product or offer appears to be fake.
                        icon: https://example.com/admin/assets/img/product-report-reason-fallback.svg
      '400':
        description: Query parameters are not accepted.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'
            examples:
              invalidQuery:
                value:
                  key: fail
                  message: يحتوي الطلب على حقول أو معاملات غير مسموح بها
                  status: 400
      '500':
        $ref: '../openapi.yaml#/components/responses/ServerError'

product-report-submit:
  post:
    tags: [Client Products]
    summary: Report a product
    operationId: submitProductReport
    x-figma:
      mobile: "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9521-17267&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1"
      mobileNodeId: "9521:17267"
    description: |
      Creates a pending report from an authenticated client.

      <div class="figma-links"><span>Design:</span><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9521-17267&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1" target="_blank" rel="noopener">Mobile</a></div>

      The `multipart/form-data` body accepts **only** the required `productId`,
      required `reasonId`, and optional `note`. `providerId`, reporter identity,
      workflow status, product number, and snapshot fields are forbidden.

      The provider is resolved server-side from the active, non-deleted Product
      document. The server snapshots the product name/number and bilingual
      reason data so the review history remains readable if catalogue text
      changes later.

      Duplicate policy: one pending report is allowed per
      reporter + product + reason. A new report may be submitted after the
      previous matching report leaves `pending`.

      After a successful create, one persisted notification is routed to the
      active super administrator and one to the product provider. Both include
      product name, product number, and reason. The provider notification never
      exposes reporter identity. No notification is sent for a rejected
      duplicate.
    security:
      - SecretKeyAuth: []
        ClientBearerAuth: []
    parameters:
      - $ref: '../openapi.yaml#/components/parameters/LangHeader'
    requestBody:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '../openapi.yaml#/components/schemas/ProductReportSubmitRequest'
          examples:
            arabic:
              value:
                productId: 665f1c2a9b4e1d0012ab34d0
                reasonId: 66a1b2c3d4e5f67890123456
                note: السعر والصور مكررة في إعلان آخر
            english:
              value:
                productId: 665f1c2a9b4e1d0012ab34d0
                reasonId: 66a1b2c3d4e5f67890123456
                note: The price and images duplicate another listing
            withoutNote:
              value:
                productId: 665f1c2a9b4e1d0012ab34d0
                reasonId: 66a1b2c3d4e5f67890123456
    responses:
      '200':
        description: Report created and notification records persisted.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ProductReportSubmitResponse'
            examples:
              arabic:
                value:
                  key: success
                  message: تم إرسال البلاغ بنجاح
                  status: 200
                  data:
                    report:
                      id: 66b1b2c3d4e5f67890123456
                      productId: 665f1c2a9b4e1d0012ab34d0
                      productNumber: "1042"
                      reason:
                        id: 66a1b2c3d4e5f67890123456
                        title: إعلان مكرر
                        description: استخدم هذا السبب عند تكرار نفس المنتج أكثر من مرة.
                        icon: https://example.com/admin/assets/img/product-report-reason-fallback.svg
                      note: السعر والصور مكررة في إعلان آخر
                      status: pending
                      createdAt: '2026-07-30T10:00:00.000Z'
              english:
                value:
                  key: success
                  message: Product report submitted successfully
                  status: 200
                  data:
                    report:
                      id: 66b1b2c3d4e5f67890123456
                      productId: 665f1c2a9b4e1d0012ab34d0
                      productNumber: "1042"
                      reason:
                        id: 66a1b2c3d4e5f67890123456
                        title: Duplicate listing
                        description: Use this reason when the same product is listed more than once.
                        icon: https://example.com/admin/assets/img/product-report-reason-fallback.svg
                      note: The price and images duplicate another listing
                      status: pending
                      createdAt: '2026-07-30T10:00:00.000Z'
      '400':
        description: |
          Invalid ObjectId/body shape, unavailable reason, duplicate pending
          report, self-report, missing product/provider, or operator injection.
        content:
          application/json:
            schema:
              $ref: '../openapi.yaml#/components/schemas/ValidationErrorResponse'
            examples:
              unknownField:
                value:
                  key: fail
                  message: يحتوي الطلب على حقول أو معاملات غير مسموح بها
                  status: 400
              duplicate:
                value:
                  key: fail
                  message: تم إرسال بلاغ مماثل على هذا المنتج وهو قيد المراجعة
                  status: 400
      '401':
        $ref: '../openapi.yaml#/components/responses/UnauthorizedError'
      '500':
        $ref: '../openapi.yaml#/components/responses/ServerError'
