subdepartments:
  get:
    tags: [Lookups]
    summary: List sub-departments
    description: |
      Paginated catalogue of active sub-departments (`SubDepartment` collection) managed from the admin dashboard.

      - Public (`SecretKeyAuth` only) — registered in `MoreRoute.unRequireAuthRoutes()`.
      - Optional query `departmentId` filters by parent department.
      - Filters: `active: true`, `isDeleted: false`.
      - DTO: `@returnObj.subdepartmentItem` → `id`, `name`, `image`.

      <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=9967-24058&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><a href="https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10768-137676&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" target="_blank" rel="noopener">Web</a></div>
    operationId: listSubDepartments
    security:
      - SecretKeyAuth: []
    parameters:
      - $ref: '../../openapi.yaml#/components/parameters/LangHeader'
      - name: departmentId
        in: query
        required: false
        description: Optional parent Department Mongo id
        schema: { type: string }
        example: "665f1c2a9b4e1d0012ab34e1"
      - name: page
        in: query
        required: false
        schema: { type: integer, minimum: 1, default: 1 }
      - name: limit
        in: query
        required: false
        schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    responses:
      '200':
        description: Paginated sub-departments.
        content:
          application/json:
            schema: { $ref: '../../openapi.yaml#/components/schemas/SubDepartmentListResponse' }
            example:
              key: success
              message: "قائمة الأقسام الفرعية"
              status: 200
              data:
                - id: "665f1c2a9b4e1d0012ab34e2"
                  name: "هواتف"
                  image: "https://example.com/assets/uploads/subdepartments/phones.png"
              paginate: { currentPage: 1, lastPage: 1, perPage: 20, total: 1 }
      '400':
        description: Validation failure (pagination or departmentId).
        content:
          application/json:
            schema: { $ref: '../../openapi.yaml#/components/schemas/ValidationErrorResponse' }
            examples:
              invalidDepartment:
                value: { key: fail, message: "القسم غير موجود", status: 400 }
              invalidPage:
                value: { key: fail, message: "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", status: 400 }
      '500': { $ref: '#/shared-server-error' }

shared-server-error:
  description: Unexpected server error.
  content:
    application/json:
      schema: { $ref: '../../openapi.yaml#/components/schemas/ErrorResponse' }
      example: { key: exception, message: "حدث خطأ ما", status: 500 }
