@lichidental/saas-cli 0.0.0-stage → 1.0.0

package/docs/api/openapi.yaml

@@ -0,0 +1,442 @@
+openapi: 3.0.3
+info:
+  title: 励齿 SaaS 预约相关接口(实测校准版)
+  version: 1.0.0
+  description: |
+    ## 目标读者
+    - **AI 工具 / 程序**:作为接口的机器可读权威规范直接消费(写对接代码、生成请求)
+    - **后端工程师**:手工核对接口参数与响应字段时参考(人类友好的导读见 接口说明.md)
+
+    ## 来源与可信度
+    - 本文档由前端调用行为(前端仓库 src/api/*.ts)+ 真实实测响应整理而成
+    - 采集时间:2026-10-12,环境:test.saas.lichidental.com;
+      每个接口的请求体与响应均与 docs/samples/ 下的实测样本一一对应
+    - 本规范为逆向整理(后端未提供正式文档);与后端实现如有出入,以后端为准
+    - sendCustomMarkSms 接口未实测(标记 x-untested: true)
+
+    ## 通用约定
+    - 所有接口均为 POST + JSON 请求体;HTTP 状态码恒为 200,业务结果看响应体 status 字段
+    - 请求头:token(必填,登录凭据)、Version(前端构建版本号,如 v26.09.2.0)、channel: html
+    - 客户端对 POST 请求不携带 clinicId query 参数;诊所归属由 token 决定
+    - 请求体中的时间为 `YYYY-MM-DD HH:mm:ss` 字符串(本地时间,非 ISO)
+    - 响应体中的时间为 ISO 格式(形如 `2026-11-01T11:00:00`,注意带 T)
+
+    ## 响应包装(所有接口一致)
+    - 成功:`{"status":200,"code":"SUCCESS","message":"处理成功","data":...}`
+    - 失败:`{"status":<错误码>,"code":"<错误标识>","message":"<错误描述>"}`(401 无 data 字段)
+servers:
+  - url: https://test.saas.lichidental.com
+    description: 测试环境(本文档样本采集环境)
+  - url: https://pre.saas.lichidental.com
+    description: 预发环境(地址来自前端 .env,未实测)
+  - url: https://saas.lichidental.com
+    description: 生产环境(地址来自前端 .env,未实测)
+
+security:
+  - tokenAuth: []
+
+tags:
+  - name: 员工
+  - name: 患者
+  - name: 预约项目
+  - name: 预约
+
+paths:
+  /user/saas/t-lichi-user-store/getStoreUserListByParam:
+    post:
+      tags: [员工]
+      operationId: getStoreUserListByParam
+      summary: 医生列表
+      description: |
+        返回"在职(0)+ 试用(2)"状态、岗位为"医生(1)"的员工列表。
+        实测样本:docs/samples/getStoreUserListByParam.json(19 条)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [delFlags, storeUserPostIds]
+              properties:
+                delFlags:
+                  type: array
+                  items: { type: integer }
+                  description: "在职状态过滤:0=在职, 1=离职, 2=试用"
+                  example: [0, 2]
+                storeUserPostIds:
+                  type: array
+                  items: { type: integer }
+                  description: "岗位过滤:1=医生, 2=管理员, 3=洁牙师, 4=咨询师, 5=助理, 6=护士, 7=前台, 8=技师, 9=行政, 10=财务, 11=客服, 12=网店营销, 13=采购, 14=库管, 15=学生, 16=销售"
+                  example: [1]
+      responses:
+        '200':
+          description: 成功时 data 为员工对象数组(关键字段见下;完整字段见样本文件)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string, example: SUCCESS }
+                  message: { type: string, example: 处理成功 }
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        userUid:
+                          type: string
+                          description: 员工唯一标识(创建预约的 doctorId 用此值)
+                          example: "26051131994"
+                        storeUserName:
+                          type: string
+                          description: 员工姓名
+                          example: 李医生
+                        storeUserPostIds:
+                          description: 岗位 id 列表(元素为字符串,如 ["1"])
+                          type: array
+                          items: { type: string }
+                        delFlag: { type: integer, description: 在职状态(0 在职 / 1 离职 / 2 试用) }
+                      additionalProperties: true
+
+  /user/saas/custom/customParamPageList:
+    post:
+      tags: [患者]
+      operationId: customParamPageList
+      summary: 搜索患者(分页)
+      description: |
+        按关键词搜索患者(paramText 支持姓名 / 手机号 / 病历号)。
+        实测样本:docs/samples/customParamPageList.json
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [pageNum, pageSize]
+              properties:
+                pageNum: { type: integer, example: 1 }
+                pageSize: { type: integer, example: 20 }
+                paramText:
+                  type: string
+                  description: 搜索关键词(姓名 / 手机号 / 病历号);不传则返回全部
+                  example: "张"
+                dateType:
+                  type: integer
+                  description: 固定传 3(前端既有写法);实测其他取值未验证
+                  example: 3
+      responses:
+        '200':
+          description: 成功时 data.list 为患者数组,data.total 为匹配总数
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string, example: SUCCESS }
+                  message: { type: string, example: 处理成功 }
+                  data:
+                    type: object
+                    properties:
+                      total: { type: integer, description: 匹配总数, example: 9 }
+                      pageNum: { type: integer }
+                      pages: { type: integer }
+                      list:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            customCode:
+                              type: string
+                              description: 患者编码(创建预约的 customCode 用此值)
+                              example: YONGCE26073100001
+                            customName: { type: string, example: 张三 }
+                            customPhone: { type: string, description: 手机号,可能为空字符串, example: "16326432746" }
+                            codeNum: { type: string, description: 病历号, example: "YONGCE26073100142" }
+                            sex: { type: integer, description: 性别(1=男, 2=女) }
+                            customSourceName: { type: string, description: 患者来源 }
+                            lableConfigDTOS: { description: 患者标签, type: array, items: { type: object, additionalProperties: true } }
+                          additionalProperties: true
+
+  /user/saas/treat-item/getTreatItemList:
+    post:
+      tags: [预约项目]
+      operationId: getTreatItemList
+      summary: 预约项目列表
+      description: |
+        返回全部预约项目(平铺数组,无分页、无请求参数)。
+        level=1 为一级分类,level=2 为二级项目(通过 upTreatItemId 关联一级分类的 id)。
+        实测样本:docs/samples/getTreatItemList.json(共 42 个,其中一级分类 10 个)
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              description: 无参数,传空对象 {} 或不传均可
+      responses:
+        '200':
+          description: 成功时 data 为项目平铺数组
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string, example: SUCCESS }
+                  message: { type: string, example: 处理成功 }
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: integer, description: 项目 id(level=2 时用于组装 treatItemJson 的 id), example: 84050 }
+                        treatItemName: { type: string, description: 项目名称, example: 口腔检查 }
+                        treatItemTitle: { type: string }
+                        upTreatItemId:
+                          type: integer
+                          description: 上级分类 id(level=1 的分类行为 0)
+                          example: 84048
+                        level: { type: integer, description: 层级:1=一级分类, 2=二级项目, enum: [1, 2], example: 2 }
+                        orderNum: { type: integer }
+                        itemNum: { type: integer }
+                      additionalProperties: true
+
+  /user/saas/custom-mark/customMarkInfoByCustom:
+    post:
+      tags: [预约]
+      operationId: customMarkInfoByCustom
+      summary: 按患者识别就诊类型(初诊/复诊)
+      description: |
+        根据患者的历史预约 / 就诊记录返回本次就诊类型。前端在"新建预约"选择患者后调用。
+        实测样本:docs/samples/customMarkInfoByCustom.json(visitType=0)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [customCode]
+              properties:
+                customCode: { type: string, description: 患者编码, example: YONGCE26073100001 }
+      responses:
+        '200':
+          description: 成功时 data.visitType 为就诊类型
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string, example: SUCCESS }
+                  message: { type: string, example: 处理成功 }
+                  data:
+                    type: object
+                    properties:
+                      visitType:
+                        type: integer
+                        description: 就诊类型:1=初诊, 0=复诊(注意:创建预约时 boolFirst 需转成字符串 "1"/"0")
+                        enum: [0, 1]
+                        example: 0
+                      customMarkDtos:
+                        type: array
+                        description: 患者历史预约记录(结构见样本文件;本工具未使用)
+                        items: { type: object, additionalProperties: true }
+                    additionalProperties: true
+
+  /user/saas/custom-mark/customMarkListByCustom:
+    post:
+      tags: [预约]
+      operationId: customMarkListByCustom
+      summary: 按患者 + 时间范围查询预约记录(列表展示用,推荐)
+      description: |
+        按患者 + 时间范围查询预约记录。前端患者详情「就诊记录」与卡片「下次预约」tab 使用本接口;CLI 的 reservation list 亦使用它。
+        实测:startTime/endTime 服务端过滤生效;返回已按 markStartTime 降序排序(前端不排序,依赖后端顺序)。
+        实测样本:docs/samples/customMarkListByCustom.json
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [customCode]
+              properties:
+                customCode:
+                  type: string
+                  description: 患者编码(精确过滤)
+                  example: YONGCE26073100001
+                startTime: { type: string, description: "开始时间 YYYY-MM-DD HH:mm:ss(实测生效)", example: "2026-10-15 00:00:00" }
+                endTime: { type: string, description: "结束时间 YYYY-MM-DD HH:mm:ss(实测生效)", example: "2026-10-15 23:59:59" }
+                pageSize: { type: integer, description: "每页条数(前端用 10;取全部可用 999)", example: 999 }
+                time: { type: string, description: 分页游标:上一页最后一条的 markStartTime }
+              additionalProperties: true
+      responses:
+        '200':
+          description: 成功时 data.cmList 为预约数组(已按 markStartTime 降序)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string, example: SUCCESS }
+                  message: { type: string, example: 处理成功 }
+                  data:
+                    type: object
+                    properties:
+                      cmList:
+                        type: array
+                        items:
+                          type: object
+                          properties:
+                            id: { type: integer, example: 1260615 }
+                            clinicId: { type: integer }
+                            customCode: { type: string }
+                            doctorId: { type: string, description: 医生 userUid(字符串) }
+                            status: { type: integer, description: "预约状态数字:1=已预约, 9=已确认, 2=已到店, 3/4=治疗中/待收费, 5=治疗完成, 6=已离店" }
+                            visitStatus: { type: integer, description: "就诊状态(前端显示状态的主键):1=预约未到, 2=待分诊, 3=治疗中, 4=待收费, 5=已完成, 6=已离店" }
+                            boolFirst: { type: integer, description: "就诊类型(数字):1=初诊 / 0=复诊" }
+                            isMark: { type: integer, description: 是否预约(0/1) }
+                            isRegister: { type: integer, description: "是否挂号(0/1);前端按 !(isMark===0 && isRegister===1) 剔除「仅挂号」" }
+                            markDate: { type: string }
+                            markStartTime: { type: string, description: "ISO 格式(带 T)", example: "2026-10-15T10:00:00" }
+                            markEndTime: { type: string }
+                            markTimeLength: { type: integer }
+                            treatItemJson: { type: string }
+                            remark: { type: string }
+                          additionalProperties: true
+                    additionalProperties: true
+
+  /user/saas/custom-mark/addCustomMark:
+    post:
+      tags: [预约]
+      operationId: addCustomMark
+      summary: 新建预约
+      description: |
+        **写操作**,调用即真实创建预约。
+        实测样本:docs/samples/addCustomMark.json(成功创建 id=1260617)。
+        注意:前端类型定义声称响应 data 只有 updateNum,但实测响应同时包含 id(预约 id)。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AddCustomMarkRequest'
+      responses:
+        '200':
+          description: 成功时 data 含 id(预约 id)与 updateNum
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string, example: SUCCESS }
+                  message: { type: string, example: 处理成功 }
+                  data:
+                    type: object
+                    properties:
+                      id: { type: integer, description: 新建预约的 id, example: 1260617 }
+                      updateNum: { type: integer, example: 1 }
+                    additionalProperties: true
+
+  /user/saas/custom-mark/sendCustomMarkSms:
+    post:
+      tags: [预约]
+      operationId: sendCustomMarkSms
+      summary: 发送预约短信给患者
+      x-untested: true
+      description: |
+        **写操作(会给患者手机发短信)**。本接口未实测(避免给真实号码发短信);
+        参数与前端调用一致,首次使用时请自行验证。工具对应参数:`reservation create --sms`。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [customCode, markStartTime]
+              properties:
+                customCode: { type: string, description: 患者编码 }
+                markStartTime:
+                  type: string
+                  description: 预约开始时间。注意与 addCustomMark 不同:此接口格式为 "YYYY-MM-DD HH:mm"(不带秒;见前端 sendCustomMarkSmsApi 调用)
+                  example: "2026-11-01 11:00"
+      responses:
+        '200':
+          description: 成功(响应结构未经实测;前端仅依据 status 判断,失败码 30002=短信发送失败、410=短信余额不足)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: integer, example: 200 }
+                  code: { type: string }
+                  message: { type: string }
+                  data: { nullable: true }
+                additionalProperties: true
+
+components:
+  securitySchemes:
+    tokenAuth:
+      type: apiKey
+      in: header
+      name: token
+      description: 登录凭据(token 头的值即 SaaS 浏览器登录后的 localStorage.userInfo.token)
+
+  schemas:
+    AddCustomMarkRequest:
+      type: object
+      required: [customCode, doctorId, markStartTime, markTimeLength, treatItemJson]
+      properties:
+        customCode:
+          type: string
+          description: 患者编码(来自 customParamPageList 的 data.list[].customCode)
+          example: YONGCE26073100001
+        doctorId:
+          type: string
+          description: 医生 userUid(来自 getStoreUserListByParam 的 data[].userUid)。字符串类型,不要传数字
+          example: "26051131994"
+        markStartTime:
+          type: string
+          description: 预约开始时间。格式严格为 "YYYY-MM-DD HH:mm:ss"(本地时间;不要用 ISO 的 T 分隔)
+          example: "2026-11-01 11:00:00"
+        markTimeLength:
+          type: integer
+          minimum: 15
+          maximum: 480
+          description: |
+            持续时长(分钟)。前端下拉可选值:15/30/45/60/75/90/105/120/135/150/165/180/195/210/225/240/300/360/420/480。
+            前端看板框选上限 480 分钟;超出范围的取值未验证
+          example: 30
+        treatItemJson:
+          type: string
+          description: |
+            预约项目的 **JSON 字符串**(不是数组本身)。元素结构见 TreatItemJsonItem。
+            组装来源:getTreatItemList 中 level=2 的项目(id/treatItemName)与其父分类(upTreatItemId 对应 level=1 的 id/treatItemName)
+          example: '[{"up_id":84048,"up_title":"口腔","id":84050,"title":"口腔检查"}]'
+        boolFirst:
+          type: string
+          enum: ["1", "0"]
+          description: 就诊类型。1=初诊,0=复诊。**字符串**(不是数字);可用 customMarkInfoByCustom 的 data.visitType 转成字符串
+          example: "0"
+        definitionCreateTime:
+          type: string
+          description: 创建时间,格式同 markStartTime。前端与 CLI 均传当前时间;省略该字段的行为未验证
+          example: "2026-10-12 11:01:51"
+        remark:
+          type: string
+          description: 备注,可为空字符串
+          example: ""
+      additionalProperties: false
+
+    TreatItemJsonItem:
+      type: object
+      description: treatItemJson 字符串解析后的单个元素
+      required: [up_id, up_title, id, title]
+      properties:
+        up_id: { type: integer, description: 一级分类 id(level=1 的 id), example: 84048 }
+        up_title: { type: string, description: 一级分类名称, example: 口腔 }
+        id: { type: integer, description: 二级项目 id(level=2 的 id), example: 84050 }
+        title: { type: string, description: 二级项目名称, example: 口腔检查 }