lite-questionnaire 1.0.0

package/design/questionnaire-openapi.yaml

@@ -0,0 +1,522 @@
+openapi: "3.0.3"
+info:
+  title: Questionnaire 工具 API
+  description: >
+    统一问答工具 API，支持单选、多选、文本输入、确认、评分五种问题类型。
+    提供条件子问题、约束校验、会话持久化等高级特性。
+  version: "2.0.0"
+
+servers:
+  - url: http://localhost
+    description: 本地 pi 工具调用
+
+paths:
+  /questionnaire:
+    post:
+      summary: 发起交互式问卷
+      description: >
+        向用户展示一系列问题，收集用户回答。
+        支持多种问题类型（单选/多选/文本/确认/评分），
+        支持条件子问题（根据父问题答案动态插入），
+        支持声明式约束校验。
+      operationId: executeQuestionnaire
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QuestionnaireParams"
+      responses:
+        "200":
+          description: 用户成功完成并提交问卷
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/QuestionnaireResult"
+        "499":
+          description: 用户取消问卷（按 Esc）
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  cancelled:
+                    type: boolean
+                    description: 固定为 true
+                  message:
+                    type: string
+                    description: 取消消息
+                    example: "User cancelled the questionnaire"
+
+components:
+  schemas:
+    # ============================================================
+    # 顶层请求/响应
+    # ============================================================
+
+    QuestionnaireParams:
+      type: object
+      description: 问卷配置，包含问题列表
+      required:
+        - questions
+      properties:
+        questions:
+          type: array
+          description: 问题列表，按顺序展示
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/Question"
+
+    QuestionnaireResult:
+      type: object
+      description: 问卷提交结果，键为问题 id，值为对应答案
+      properties:
+        answers:
+          type: object
+          description: 每个问题的答案，键为问题 id
+          additionalProperties:
+            $ref: "#/components/schemas/Answer"
+        submittedAt:
+          type: string
+          format: date-time
+          description: 提交时间戳
+
+    # ============================================================
+    # 问题类型（多态）
+    # ============================================================
+
+    Question:
+      oneOf:
+        - $ref: "#/components/schemas/SelectQuestion"
+        - $ref: "#/components/schemas/MultiSelectQuestion"
+        - $ref: "#/components/schemas/TextQuestion"
+        - $ref: "#/components/schemas/ConfirmQuestion"
+        - $ref: "#/components/schemas/RatingQuestion"
+      discriminator:
+        propertyName: type
+        mapping:
+          select: "#/components/schemas/SelectQuestion"
+          multiSelect: "#/components/schemas/MultiSelectQuestion"
+          text: "#/components/schemas/TextQuestion"
+          confirm: "#/components/schemas/ConfirmQuestion"
+          rating: "#/components/schemas/RatingQuestion"
+
+    # ============================================================
+    # 共享基础结构
+    # ============================================================
+
+    BaseQuestion:
+      type: object
+      description: 所有问题类型的公共基础字段
+      required:
+        - id
+        - label
+        - prompt
+      properties:
+        id:
+          type: string
+          description: 问题唯一标识，用于结果映射的键名
+          example: "language"
+        label:
+          type: string
+          description: Tab 标签栏中显示的短标签
+          example: "语言"
+        prompt:
+          type: string
+          description: 完整的问题文本，展示在面板主体区域
+          example: "请选择你使用的编程语言"
+        constraints:
+          type: array
+          description: 约束条件列表，声明式校验规则
+          items:
+            $ref: "#/components/schemas/Constraint"
+        children:
+          type: array
+          description: |
+            条件子问题列表。当父问题答案为指定值时，子问题会动态插入到
+            Tab 序列中（紧跟在父问题之后）。子问题本身也可以嵌套子问题。
+          items:
+            $ref: "#/components/schemas/Question"
+        showIf:
+          type: object
+          description: |
+            条件显示规则，定义当前问题（子问题）在何种父问题答案下才显示。
+            仅用于 children 数组中的子问题，父问题无需此字段。
+          required:
+            - value
+          properties:
+            value:
+              type: string
+              description: 父问题答案匹配值。当父问题的答案等于此值时，当前子问题才会插入 Tab 序列
+              example: "ts"
+
+    Constraint:
+      type: object
+      description: 声明式约束校验规则，在用户提交问题时进行验证
+      required:
+        - type
+        - message
+      properties:
+        type:
+          type: string
+          description: 约束类型
+          enum:
+            - required
+            - minSelect
+            - maxSelect
+            - minLength
+            - maxLength
+            - pattern
+        value:
+          description: |
+            约束参数值，具体含义取决于 type：
+            - minSelect: 最少选择项数（正整数）
+            - maxSelect: 最多选择项数（正整数）
+            - minLength: 文本最小长度（正整数）
+            - maxLength: 文本最大长度（正整数）
+            - pattern: 正则表达式字符串
+            - required: 不需要 value（忽略此字段）
+          oneOf:
+            - type: number
+            - type: string
+        message:
+          type: string
+          description: 校验失败时显示的错误提示信息
+          example: "至少选择一项"
+
+    Option:
+      type: object
+      description: 选项定义，用于 select 和 multiSelect 类型问题
+      required:
+        - value
+        - label
+      properties:
+        value:
+          type: string
+          description: 选项的唯一值，作为答案返回
+          example: "ts"
+        label:
+          type: string
+          description: 选项的显示文本
+          example: "TypeScript"
+        description:
+          type: string
+          description: 选项的可选描述，显示在 label 下方
+
+    # ============================================================
+    # 具体问题类型
+    # ============================================================
+
+    SelectQuestion:
+      allOf:
+        - $ref: "#/components/schemas/BaseQuestion"
+        - type: object
+          required:
+            - type
+            - maxSelect
+            - options
+          properties:
+            type:
+              type: string
+              enum: [select]
+              description: 固定为 `select`
+            maxSelect:
+              type: integer
+              enum: [1]
+              default: 1
+              description: 固定为 1，表示单选模式
+            options:
+              type: array
+              description: 可选项列表。末尾自动追加"自定义"选项，允许用户输入自定义值
+              minItems: 1
+              items:
+                $ref: "#/components/schemas/Option"
+
+    MultiSelectQuestion:
+      allOf:
+        - $ref: "#/components/schemas/BaseQuestion"
+        - type: object
+          required:
+            - type
+            - maxSelect
+            - options
+          properties:
+            type:
+              type: string
+              enum: [multiSelect]
+              description: 固定为 `multiSelect`
+            maxSelect:
+              type: integer
+              minimum: 2
+              description: 最大可选数量，必须 > 1
+              example: 3
+            options:
+              type: array
+              description: 可选项列表。末尾自动追加"自定义"选项
+              minItems: 1
+              items:
+                $ref: "#/components/schemas/Option"
+
+    TextQuestion:
+      allOf:
+        - $ref: "#/components/schemas/BaseQuestion"
+        - type: object
+          required:
+            - type
+          properties:
+            type:
+              type: string
+              enum: [text]
+              description: 固定为 `text`
+            placeholder:
+              type: string
+              description: 输入框占位符文本
+              example: "请输入项目描述..."
+            multiline:
+              type: boolean
+              default: false
+              description: 是否使用多行文本编辑模式
+
+    ConfirmQuestion:
+      allOf:
+        - $ref: "#/components/schemas/BaseQuestion"
+        - type: object
+          required:
+            - type
+          properties:
+            type:
+              type: string
+              enum: [confirm]
+              description: 固定为 `confirm`
+            yesLabel:
+              type: string
+              default: "是"
+              description: 「是」按钮的显示文本
+              example: "创建"
+            noLabel:
+              type: string
+              default: "否"
+              description: 「否」按钮的显示文本
+              example: "取消"
+
+    RatingQuestion:
+      allOf:
+        - $ref: "#/components/schemas/BaseQuestion"
+        - type: object
+          required:
+            - type
+            - range
+          properties:
+            type:
+              type: string
+              enum: [rating]
+              description: 固定为 `rating`
+            range:
+              type: object
+              description: 评分范围
+              required:
+                - min
+                - max
+              properties:
+                min:
+                  type: integer
+                  enum: [1]
+                  description: 固定为 1
+                max:
+                  type: integer
+                  enum: [5]
+                  description: 固定为 5
+            showEmoji:
+              type: boolean
+              default: false
+              description: 是否在滑块上方显示表情量表（😡 😟 😐 😊 😍）
+            annotations:
+              type: object
+              description: 数值到文字注释的映射，显示在滑块下方
+              additionalProperties:
+                type: string
+              example:
+                "1": "非常差"
+                "3": "一般"
+                "5": "非常好"
+
+    # ============================================================
+    # 答案类型
+    # ============================================================
+
+    Answer:
+      oneOf:
+        - $ref: "#/components/schemas/SelectAnswer"
+        - $ref: "#/components/schemas/MultiSelectAnswer"
+        - $ref: "#/components/schemas/TextAnswer"
+        - $ref: "#/components/schemas/ConfirmAnswer"
+        - $ref: "#/components/schemas/RatingAnswer"
+
+    SelectAnswer:
+      type: object
+      description: 单选答案
+      properties:
+        value:
+          type: string
+          description: 用户选择的选项值
+          example: "ts"
+        label:
+          type: string
+          description: 用户选择的选项显示文本
+          example: "TypeScript"
+        wasCustom:
+          type: boolean
+          default: false
+          description: 是否来自"自定义"选项的输入
+
+    MultiSelectAnswer:
+      type: object
+      description: 多选答案
+      properties:
+        values:
+          type: array
+          description: 用户选择的所有选项值
+          items:
+            type: string
+          example: ["ts", "rs"]
+        labels:
+          type: array
+          description: 用户选择的所有选项显示文本
+          items:
+            type: string
+          example: ["TypeScript", "Rust"]
+        wasCustom:
+          type: boolean
+          default: false
+          description: 是否包含"自定义"选项的输入
+
+    TextAnswer:
+      type: object
+      description: 文本答案
+      properties:
+        text:
+          type: string
+          description: 用户输入的文本内容
+          example: "一个高性能 API 服务"
+
+    ConfirmAnswer:
+      type: object
+      description: 确认答案
+      properties:
+        confirmed:
+          type: boolean
+          description: 用户的选择，true = 是/确认，false = 否/取消
+          example: true
+        label:
+          type: string
+          description: 用户选中的按钮文本
+          example: "创建"
+
+    RatingAnswer:
+      type: object
+      description: 评分答案
+      properties:
+        value:
+          type: integer
+          minimum: 1
+          maximum: 5
+          description: 用户选择的评分值（1-5）
+          example: 5
+        annotation:
+          type: string
+          description: 对应数值的文字注释（如果配置了 annotations 且该值有注释）
+          example: "非常好"
+
+  # ============================================================
+  # 完整请求示例
+  # ============================================================
+
+  examples:
+    FullQuestionnaireExample:
+      summary: 涵盖所有 5 种问题类型的完整示例
+      value:
+        questions:
+          - id: "language"
+            type: "select"
+            maxSelect: 1
+            label: "语言"
+            prompt: "请选择你想使用的编程语言"
+            options:
+              - value: "ts"
+                label: "TypeScript"
+                description: "类型安全的 JavaScript 超集"
+              - value: "py"
+                label: "Python"
+              - value: "rs"
+                label: "Rust"
+                description: "高性能系统编程语言"
+            children:
+              - id: "framework"
+                type: "select"
+                maxSelect: 1
+                label: "框架"
+                prompt: "请选择 Web 框架"
+                showIf:
+                  value: "ts"
+                options:
+                  - value: "react"
+                    label: "React"
+                  - value: "vue"
+                    label: "Vue"
+                  - value: "svelte"
+                    label: "Svelte"
+
+          - id: "features"
+            type: "multiSelect"
+            maxSelect: 3
+            label: "功能"
+            prompt: "请选择你需要的功能模块"
+            options:
+              - value: "auth"
+                label: "用户认证"
+              - value: "api"
+                label: "REST API"
+              - value: "ws"
+                label: "WebSocket"
+              - value: "db"
+                label: "数据库"
+              - value: "cache"
+                label: "缓存"
+            constraints:
+              - type: "minSelect"
+                value: 1
+                message: "至少选择一项功能"
+              - type: "maxSelect"
+                value: 3
+                message: "最多选择 3 项功能"
+
+          - id: "description"
+            type: "text"
+            label: "描述"
+            prompt: "请简要描述你的项目"
+            placeholder: "输入项目描述..."
+            multiline: true
+            constraints:
+              - type: "minLength"
+                value: 10
+                message: "描述至少需要 10 个字符"
+
+          - id: "license"
+            type: "confirm"
+            label: "许可"
+            prompt: "是否使用 MIT 开源许可证？"
+            yesLabel: "是，使用 MIT"
+            noLabel: "否，选择其他"
+
+          - id: "satisfaction"
+            type: "rating"
+            label: "满意度"
+            prompt: "你对当前开发体验的满意度如何？"
+            range:
+              min: 1
+              max: 5
+            showEmoji: true
+            annotations:
+              "1": "非常不满意"
+              "3": "一般"
+              "5": "非常满意"