searchpipe-tech Admin API

openapi: 3.2.0
info:
  title: SearchPipe Admin API
  version: 0.2.0
tags:
- name: Admin
paths:
  /admin/:
    get:
      tags:
      - Admin
      summary: Admin Entry
      description: '管理员入口 —— 直达运营监控，无需记忆 /admin/monitor。


        - 已登录管理员（role ∈ {owner, admin}）→ 302 /admin/monitor

        - 未登录 → 302 独立管理员登录页（带回跳 next=/admin/monitor）

        - 已登录但不是管理员 → 302 登录页并提示无权限（可换管理员账号登录）'
      operationId: admin_entry_admin__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Admin Entry Admin  Get
  /admin:
    get:
      tags:
      - Admin
      summary: Admin Entry
      description: '管理员入口 —— 直达运营监控，无需记忆 /admin/monitor。


        - 已登录管理员（role ∈ {owner, admin}）→ 302 /admin/monitor

        - 未登录 → 302 独立管理员登录页（带回跳 next=/admin/monitor）

        - 已登录但不是管理员 → 302 登录页并提示无权限（可换管理员账号登录）'
      operationId: admin_entry_admin_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Admin Entry Admin Get
  /admin/login:
    get:
      tags:
      - Admin
      summary: Admin Login Page
      description: 独立管理员登录页；已登录管理员直接放行到监控页（不重复登录）。
      operationId: admin_login_page_admin_login_get
      parameters:
      - name: next
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Next
      - name: denied
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Denied
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Admin Login Page Admin Login Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Admin
      summary: Admin Login Submit
      description: '管理员登录：邮箱密码 + 管理员角色校验 → 设 session cookie → 302 监控页。


        非管理员账号（含密码正确但 role 为 user/member）一律拒绝且**不设 cookie**，

        避免顺手把普通账号登进管理端；失败的响应统一重渲染登录页并提示。

        登录成功与用户控制台口径一致：更新 last_login_at + 续发每月免费额度。'
      operationId: admin_login_submit_admin_login_post
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_admin_login_submit_admin_login_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Admin Login Submit Admin Login Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/logout:
    get:
      tags:
      - Admin
      summary: Admin Logout
      description: 管理端退出：清 session cookie（与控制台共用）→ 302 管理员登录页。
      operationId: admin_logout_admin_logout_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /admin/users:
    get:
      tags:
      - Admin
      summary: List Users
      operationId: list_users_admin_users_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Size
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminUserListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/users/{user_id}:
    patch:
      tags:
      - Admin
      summary: Update User
      operationId: update_user_admin_users__user_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Update User Admin Users  User Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/credits:
    get:
      tags:
      - Admin
      summary: Credits Overview
      description: 全平台积分总余额 + 账户数。
      operationId: credits_overview_admin_credits_get
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Credits Overview Admin Credits Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/credits/grant:
    post:
      tags:
      - Admin
      summary: Grant Credits Admin
      description: 管理员手动发放额度。
      operationId: grant_credits_admin_admin_credits_grant_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantCreditsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantCreditsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/orders:
    get:
      tags:
      - Admin
      summary: List Orders
      operationId: list_orders_admin_orders_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Size
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdminOrderItem'
                title: Response List Orders Admin Orders Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/stats:
    get:
      tags:
      - Admin
      summary: Stats
      description: 概览统计：用户数、总积分、总搜索、收入。
      operationId: stats_admin_stats_get
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/feedback:
    get:
      tags:
      - Admin
      summary: List Feedback
      description: '列全部工单，可按 status 过滤（open/closed）。


        浏览器直接访问（Accept: text/html）时渲染工单管理 SSR 页

        （含「通知该用户」入口，跳转 /admin/messages 预填收件人）；

        程序调用（fetch/API）返回 JSON。'
      operationId: list_feedback_admin_feedback_get
      security:
      - HTTPBearer: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Size
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminFeedbackListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/feedback/{ticket_id}/close:
    post:
      tags:
      - Admin
      summary: Close Feedback
      description: 关闭工单。
      operationId: close_feedback_admin_feedback__ticket_id__close_post
      security:
      - HTTPBearer: []
      parameters:
      - name: ticket_id
        in: path
        required: true
        schema:
          type: string
          title: Ticket Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Close Feedback Admin Feedback  Ticket Id  Close Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/messages:
    get:
      tags:
      - Admin
      summary: Admin Messages Page
      description: 站内信管理页。支持 ?to=邮箱 预填收件人、?ticket=工单ID 预填回复文案。
      operationId: admin_messages_page_admin_messages_get
      security:
      - HTTPBearer: []
      parameters:
      - name: to
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: To
      - name: ticket
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Ticket
      - name: sent
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Sent
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Admin Messages Page Admin Messages Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Admin
      summary: Admin Send Message
      description: '发送站内信：target_type=user 定向（按邮箱）/ broadcast 全局广播。


        广播为每个活跃用户写一行（MVP 用户量小，简单可靠）。失败重渲染表单页提示。'
      operationId: admin_send_message_admin_messages_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_admin_send_message_admin_messages_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Admin Send Message Admin Messages Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/monitor:
    get:
      tags:
      - Admin
      summary: Monitor Page
      description: 运营监控 SSR 页面：聚合关键指标、近 24h 趋势、最近登录与注册用户列表。
      operationId: monitor_page_admin_monitor_get
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Monitor Page Admin Monitor Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/perf:
    get:
      tags:
      - Admin
      summary: Perf Page
      description: '/search 分阶段耗时统计 SSR 页：总体分位 + 分阶段聚合 + 慢请求 Top20。


        数据源 search_perf_logs（perf 中间件每请求 fire-and-forget 落一行，含

        stages JSONB，见 utils/perf.py）。时间窗只接受 1h/24h/7d，非法值回落 24h。'
      operationId: perf_page_admin_perf_get
      security:
      - HTTPBearer: []
      parameters:
      - name: hours
        in: query
        required: false
        schema:
          type: integer
          default: 24
          title: Hours
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Perf Page Admin Perf Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/behavior:
    get:
      tags:
      - Admin
      summary: Behavior Page
      description: '用户行为 SSR 页：激活漏斗 + 最近事件流 + 按邮箱钻取单人时间线。


        漏斗口径从业务表取（users/api_keys/usage_logs/orders 是权威事实），

        事件流从 user_events 取（埋点上线后的行为明细；存量用户已在迁移中回填）。'
      operationId: behavior_page_admin_behavior_get
      security:
      - HTTPBearer: []
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Email
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Behavior Page Admin Behavior Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_admin_send_message_admin_messages_post:
      properties:
        target_type:
          type: string
          title: Target Type
        target_email:
          type: string
          title: Target Email
          default: ''
        title:
          type: string
          title: Title
        content:
          type: string
          title: Content
      type: object
      required:
      - target_type
      - title
      - content
      title: Body_admin_send_message_admin_messages_post
    AdminFeedbackItem:
      properties:
        id:
          type: string
          title: Id
        user_id:
          type: string
          title: User Id
        category:
          type: string
          title: Category
        subject:
          type: string
          title: Subject
        content:
          type: string
          title: Content
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - user_id
      - category
      - subject
      - content
      - status
      - created_at
      - updated_at
      title: AdminFeedbackItem
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GrantCreditsRequest:
      properties:
        user_id:
          type: string
          title: User Id
        amount:
          type: integer
          title: Amount
        remark:
          anyOf:
          - type: string
          - type: 'null'
          title: Remark
          default: 管理员发放
      type: object
      required:
      - user_id
      - amount
      title: GrantCreditsRequest
    GrantCreditsResponse:
      properties:
        user_id:
          type: string
          title: User Id
        balance:
          type: number
          title: Balance
      type: object
      required:
      - user_id
      - balance
      title: GrantCreditsResponse
    AdminUserListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AdminUserItem'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        size:
          type: integer
          title: Size
      type: object
      required:
      - items
      - total
      - page
      - size
      title: AdminUserListResponse
    AdminOrderItem:
      properties:
        id:
          type: string
          title: Id
        user_id:
          type: string
          title: User Id
        kind:
          type: string
          title: Kind
        pay_channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Pay Channel
        credits:
          type: number
          title: Credits
        amount_cents:
          type: integer
          title: Amount Cents
        status:
          type: string
          title: Status
        provider:
          type: string
          title: Provider
        provider_order_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Order Id
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - user_id
      - kind
      - pay_channel
      - credits
      - amount_cents
      - status
      - provider
      - provider_order_id
      - paid_at
      - created_at
      title: AdminOrderItem
    Body_admin_login_submit_admin_login_post:
      properties:
        email:
          type: string
          title: Email
        password:
          type: string
          title: Password
        next:
          type: string
          title: Next
          default: ''
      type: object
      required:
      - email
      - password
      title: Body_admin_login_submit_admin_login_post
    AdminStatsResponse:
      properties:
        user_count:
          type: integer
          title: User Count
        active_user_count:
          type: integer
          title: Active User Count
        total_balance:
          type: integer
          title: Total Balance
        total_searches:
          type: integer
          title: Total Searches
        total_revenue_cents:
          type: integer
          title: Total Revenue Cents
        paid_order_count:
          type: integer
          title: Paid Order Count
      type: object
      required:
      - user_count
      - active_user_count
      - total_balance
      - total_searches
      - total_revenue_cents
      - paid_order_count
      title: AdminStatsResponse
    UpdateUserRequest:
      properties:
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      type: object
      title: UpdateUserRequest
    AdminUserItem:
      properties:
        id:
          type: string
          title: Id
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        role:
          type: string
          title: Role
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        last_login_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Login At
      type: object
      required:
      - id
      - email
      - phone
      - role
      - status
      - created_at
      - last_login_at
      title: AdminUserItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AdminFeedbackListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AdminFeedbackItem'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        size:
          type: integer
          title: Size
      type: object
      required:
      - items
      - total
      - page
      - size
      title: AdminFeedbackListResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer