openapi: 3.0.3
info:
  title: Feedback Desk API
  version: 0.2.0
  description: |
    给多个项目共用的留言与公开路线图服务。
    公开接口不需要管理员令牌；写操作可能要求项目 submitKey 和允许的 Origin。
    管理员接口需要 `Authorization: Bearer <ADMIN_TOKEN>`。
servers:
  - url: http://127.0.0.1:8787
tags:
  - name: Public
  - name: Admin
paths:
  /api/health:
    get:
      tags: [Public]
      summary: 健康检查
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  name: { type: string }
                  version: { type: string }
  /api/public/projects:
    get:
      tags: [Public]
      summary: 公开项目列表
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items: { $ref: '#/components/schemas/PublicProjectSummary' }
  /api/public/projects/{slug}:
    get:
      tags: [Public]
      summary: 项目、路线图和公开留言
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  project: { $ref: '#/components/schemas/PublicProject' }
                  roadmap:
                    type: array
                    items: { $ref: '#/components/schemas/RoadmapItem' }
                  feedback:
                    type: array
                    items: { $ref: '#/components/schemas/PublicFeedback' }
                  stats: { $ref: '#/components/schemas/PublicStats' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/public/projects/{slug}/roadmap:
    get:
      tags: [Public]
      summary: 公开路线图
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  roadmap:
                    type: array
                    items: { $ref: '#/components/schemas/RoadmapItem' }
  /api/public/projects/{slug}/feedback:
    get:
      tags: [Public]
      summary: 公开留言列表
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  feedback:
                    type: array
                    items: { $ref: '#/components/schemas/PublicFeedback' }
    post:
      tags: [Public]
      summary: 提交留言
      description: |
        - 如果项目配置了 submitKey，必须带 `key`。
        - 如果项目配置了 allowedOrigins，请求的 `Origin` 必须匹配。
        - `public: true` 且项目未开启审核时，留言会立即出现在公开面板。
        - 返回的 `ticket` 是查询码，请保存在客户端。
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FeedbackCreate' }
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  id: { type: string, format: uuid }
                  ticket: { type: string }
                  public: { type: boolean }
                  approved: { type: boolean }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /api/public/projects/{slug}/upload:
    post:
      tags: [Public]
      summary: 上传留言截图
      description: |
        先把图片以原始二进制上传，再把返回的 `attachment` 原样放进留言的 `attachment` 字段。
        默认存本机 `data/uploads`；管理员在后台「存储」页配置七牛云后，新图片直接进入 Kodo。
        请求头 `Content-Type` 必须是图片类型；可选 `X-File-Name`（URL 编码的原始文件名）。
        默认单张上限 32MB，可在后台改成 0（不限制）。
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
      requestBody:
        required: true
        content:
          image/png:
            schema: { type: string, format: binary }
          image/jpeg:
            schema: { type: string, format: binary }
          image/webp:
            schema: { type: string, format: binary }
          image/gif:
            schema: { type: string, format: binary }
      responses:
        '201':
          description: 上传成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  attachment: { $ref: '#/components/schemas/Attachment' }
        '413': { description: 超过大小上限 }
        '415': { description: 不是支持的图片格式 }
        '429': { description: 上传太频繁 }
  /api/public/projects/{slug}/feedback/{id}/vote:
    post:
      tags: [Public]
      summary: 给公开留言点同感
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VoteRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VoteResult' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/public/projects/{slug}/roadmap/{id}/vote:
    post:
      tags: [Public]
      summary: 给路线图条目点同感
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VoteRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VoteResult' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/public/feedback/{ticket}:
    get:
      tags: [Public]
      summary: 用查询码查看自己的留言
      parameters:
        - in: path
          name: ticket
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  feedback: { $ref: '#/components/schemas/TicketFeedback' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/admin/projects:
    get:
      tags: [Admin]
      summary: 管理员项目列表
      security: [{ adminToken: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items: { $ref: '#/components/schemas/AdminProject' }
    post:
      tags: [Admin]
      summary: 创建项目
      security: [{ adminToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProjectWrite' }
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  project: { $ref: '#/components/schemas/AdminProject' }
  /api/admin/projects/{slug}:
    patch:
      tags: [Admin]
      summary: 修改项目
      security: [{ adminToken: [] }]
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProjectPatch' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  project: { $ref: '#/components/schemas/AdminProject' }
    delete:
      tags: [Admin]
      summary: 删除项目
      security: [{ adminToken: [] }]
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
        - in: query
          name: confirm
          required: true
          schema: { type: string }
          description: 必须等于项目 slug
      responses:
        '200': { description: OK }
  /api/admin/feedback:
    get:
      tags: [Admin]
      summary: 管理员留言列表
      security: [{ adminToken: [] }]
      parameters:
        - in: query
          name: project
          schema: { type: string }
        - in: query
          name: status
          schema: { type: string, enum: [new, accepted, fixing, integrating, shipped, rejected] }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  feedback:
                    type: array
                    items: { $ref: '#/components/schemas/AdminFeedback' }
  /api/admin/feedback/{id}:
    patch:
      tags: [Admin]
      summary: 处理留言
      security: [{ adminToken: [] }]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FeedbackPatch' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  feedback: { $ref: '#/components/schemas/AdminFeedback' }
                  roadmap: { $ref: '#/components/schemas/RoadmapItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
    delete:
      tags: [Admin]
      summary: 删除留言
      security: [{ adminToken: [] }]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: OK }
  /api/admin/roadmap:
    get:
      tags: [Admin]
      summary: 路线图列表
      security: [{ adminToken: [] }]
      parameters:
        - in: query
          name: project
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  roadmap:
                    type: array
                    items: { $ref: '#/components/schemas/RoadmapItem' }
    post:
      tags: [Admin]
      summary: 添加路线图
      security: [{ adminToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoadmapWrite' }
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  roadmap: { $ref: '#/components/schemas/RoadmapItem' }
  /api/admin/roadmap/{id}:
    patch:
      tags: [Admin]
      summary: 修改路线图
      security: [{ adminToken: [] }]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoadmapPatch' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  roadmap: { $ref: '#/components/schemas/RoadmapItem' }
    delete:
      tags: [Admin]
      summary: 删除路线图
      security: [{ adminToken: [] }]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: OK }
  /api/admin/storage:
    get:
      tags: [Admin]
      summary: 读取图片存储设置
      security: [{ adminToken: [] }]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  storage: { $ref: '#/components/schemas/StorageConfig' }
    put:
      tags: [Admin]
      summary: 保存图片存储设置
      description: 密钥留空表示保持原值；保存后立即生效。
      security: [{ adminToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider: { type: string, enum: [local, qiniu] }
                maxSizeMB: { type: integer, minimum: 0, maximum: 1024, description: 0 表示不限制 }
                qiniu:
                  type: object
                  properties:
                    accessKey: { type: string }
                    secretKey: { type: string }
                    bucket: { type: string }
                    domain: { type: string }
                    region: { type: string, enum: [z0, z1, z2, na0, as0, cn-east-2] }
                    prefix: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  storage: { $ref: '#/components/schemas/StorageConfig' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /api/admin/stats:
    get:
      tags: [Admin]
      summary: 统计
      security: [{ adminToken: [] }]
      parameters:
        - in: query
          name: project
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats: { type: object, additionalProperties: true }
  /api/admin/audit:
    get:
      tags: [Admin]
      summary: 操作日志
      security: [{ adminToken: [] }]
      parameters:
        - in: query
          name: project
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, default: 100 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  audit:
                    type: array
                    items: { $ref: '#/components/schemas/AuditItem' }
  /api/admin/export:
    get:
      tags: [Admin]
      summary: 导出 JSON 备份
      security: [{ adminToken: [] }]
      responses:
        '200':
          description: JSON 文件
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/admin/import:
    post:
      tags: [Admin]
      summary: 恢复 JSON 备份
      security: [{ adminToken: [] }]
      parameters:
        - in: query
          name: confirm
          required: true
          schema: { type: string, enum: [replace-all] }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data: { type: object, additionalProperties: true }
      responses:
        '200': { description: OK }
components:
  securitySchemes:
    adminToken:
      type: http
      scheme: bearer
  parameters:
    ProjectSlug:
      in: path
      name: slug
      required: true
      schema: { type: string, pattern: '^[a-z0-9][a-z0-9-]{1,39}$' }
  responses:
    BadRequest:
      description: 请求不合法
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: 缺少或错误的令牌 / key
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: 来源或 IP 被禁止
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: 请求太频繁
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        error: { type: string }
    PublicProjectSummary:
      type: object
      properties:
        slug: { type: string }
        name: { type: string }
        description: { type: string }
        publicFeedback: { type: boolean }
        feedbackCount: { type: integer }
        roadmapCount: { type: integer }
    PublicProject:
      type: object
      properties:
        slug: { type: string }
        name: { type: string }
        description: { type: string }
        publicFeedback: { type: boolean }
        moderation: { type: boolean }
        submitKeyRequired: { type: boolean }
    PublicStats:
      type: object
      properties:
        feedbackCount: { type: integer }
        publicFeedbackCount: { type: integer }
        roadmapCount: { type: integer }
        shippedCount: { type: integer }
    FeedbackCreate:
      type: object
      required: [title, body]
      properties:
        kind: { type: string, enum: [建议, 问题, 其他], default: 建议 }
        title: { type: string, maxLength: 120 }
        body: { type: string, maxLength: 4000 }
        contact: { type: string, maxLength: 120, description: 只保存在后台 }
        public: { type: boolean, default: false }
        key: { type: string, description: 项目配置了 submitKey 时必填 }
        website: { type: string, description:  honeypot，正常用户留空 }
        attachment:
          $ref: '#/components/schemas/AttachmentInput'
    AttachmentInput:
      type: object
      description: 新前端把上传接口返回的 attachment 原样提交；旧版 base64 仍兼容。
      properties:
        name: { type: string, maxLength: 120 }
        type: { type: string, enum: [image/png, image/jpeg, image/webp, image/gif] }
        size: { type: integer }
        key: { type: string, description: 上传接口返回的对象 key }
        url: { type: string, description: 上传接口返回的访问地址 }
        data: { type: string, description: "旧版 base64，不含 data: 前缀" }
    VoteRequest:
      type: object
      required: [voter]
      properties:
        voter: { type: string, maxLength: 120, description: 客户端生成的随机标识，服务端只保存哈希 }
    VoteResult:
      type: object
      properties:
        ok: { type: boolean }
        votes: { type: integer }
        added: { type: boolean }
    PublicFeedback:
      type: object
      properties:
        id: { type: string, format: uuid }
        kind: { type: string }
        title: { type: string }
        body: { type: string }
        status: { type: string, enum: [new, accepted, fixing, integrating, shipped, rejected] }
        reply: { type: string }
        replyAt: { type: string, format: date-time }
        attachment: { $ref: '#/components/schemas/Attachment' }
        votes: { type: integer }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    Attachment:
      type: object
      nullable: true
      properties:
        name: { type: string }
        type: { type: string }
        size: { type: integer }
        url: { type: string, description: 图片访问地址；本机模式为 /uploads/... 相对路径 }
        key: { type: string, description: 对象存储 key }
        provider: { type: string, enum: [local, qiniu] }
        data: { type: string, description: 旧版 base64 }
    StorageConfig:
      type: object
      properties:
        provider: { type: string, enum: [local, qiniu] }
        maxSizeMB: { type: integer, description: 0 表示不限制 }
        qiniu:
          type: object
          properties:
            bucket: { type: string }
            domain: { type: string }
            region: { type: string }
            prefix: { type: string }
            uploadUrl: { type: string }
            hasAccessKey: { type: boolean }
            hasSecretKey: { type: boolean }
            configured: { type: boolean }
    TicketFeedback:
      type: object
      properties:
        id: { type: string, format: uuid }
        project: { type: string }
        projectName: { type: string }
        kind: { type: string }
        title: { type: string }
        body: { type: string }
        status: { type: string }
        reply: { type: string }
        replyAt: { type: string }
        votes: { type: integer }
        attachment: { $ref: '#/components/schemas/Attachment' }
        createdAt: { type: string }
        updatedAt: { type: string }
        roadmap: { $ref: '#/components/schemas/RoadmapItem' }
    RoadmapItem:
      type: object
      properties:
        id: { type: string, format: uuid }
        project: { type: string }
        title: { type: string }
        summary: { type: string }
        status: { type: string, enum: [accepted, fixing, integrating, shipped, rejected] }
        date: { type: string, description: 日期或阶段标签 }
        reason: { type: string, description: 拒绝原因 }
        version: { type: string, description: 已上线版本 }
        source: { type: string, enum: [owner, user] }
        sourceFeedbackId: { type: string, nullable: true }
        order: { type: integer }
        votes: { type: integer }
        createdAt: { type: string }
        updatedAt: { type: string }
    AdminProject:
      allOf:
        - $ref: '#/components/schemas/PublicProject'
        - type: object
          properties:
            webhookUrl: { type: string }
            webhookSecret: { type: string }
            submitKey: { type: string }
            allowedOrigins:
              type: array
              items: { type: string }
            blockedWords:
              type: array
              items: { type: string }
            blockedIps:
              type: array
              items: { type: string }
            feedbackCount: { type: integer }
            newFeedbackCount: { type: integer }
            roadmapCount: { type: integer }
    ProjectWrite:
      type: object
      required: [slug, name]
      properties:
        slug: { type: string, pattern: '^[a-z0-9][a-z0-9-]{1,39}$' }
        name: { type: string, maxLength: 60 }
        description: { type: string, maxLength: 240 }
        publicFeedback: { type: boolean }
        webhookUrl: { type: string }
        webhookSecret: { type: string }
        submitKey: { type: string }
        allowedOrigins:
          type: array
          items: { type: string }
        moderation: { type: boolean }
        blockedWords:
          type: array
          items: { type: string }
        blockedIps:
          type: array
          items: { type: string }
    ProjectPatch:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        publicFeedback: { type: boolean }
        webhookUrl: { type: string }
        webhookSecret: { type: string }
        submitKey: { type: string }
        allowedOrigins:
          oneOf:
            - type: array
              items: { type: string }
            - type: string
        moderation: { type: boolean }
        blockedWords:
          oneOf:
            - type: array
              items: { type: string }
            - type: string
        blockedIps:
          oneOf:
            - type: array
              items: { type: string }
            - type: string
    AdminFeedback:
      allOf:
        - $ref: '#/components/schemas/PublicFeedback'
        - type: object
          properties:
            project: { type: string }
            contact: { type: string }
            approved: { type: boolean }
            public: { type: boolean }
            adminNote: { type: string }
            ticket: { type: string }
            roadmap: { $ref: '#/components/schemas/RoadmapItem' }
    FeedbackPatch:
      type: object
      properties:
        status: { type: string, enum: [new, accepted, fixing, integrating, shipped, rejected] }
        adminNote: { type: string, maxLength: 1000 }
        public: { type: boolean }
        approved: { type: boolean }
        reply: { type: string, maxLength: 2000 }
        reason: { type: string, maxLength: 500, description: 拒绝时必填 }
        version: { type: string, description: 已上线时写入路线图版本 }
    RoadmapWrite:
      type: object
      required: [project, title, status]
      properties:
        project: { type: string }
        title: { type: string }
        summary: { type: string }
        status: { type: string, enum: [accepted, fixing, integrating, shipped, rejected] }
        date: { type: string }
        version: { type: string }
        reason: { type: string, description: 已拒绝时必填 }
    RoadmapPatch:
      type: object
      properties:
        title: { type: string }
        summary: { type: string }
        status: { type: string, enum: [accepted, fixing, integrating, shipped, rejected] }
        date: { type: string }
        version: { type: string }
        reason: { type: string }
    AuditItem:
      type: object
      properties:
        id: { type: string }
        project: { type: string }
        entity: { type: string }
        entityId: { type: string }
        action: { type: string }
        detail: { type: string }
        createdAt: { type: string }
