feat: 添加系统刷新令牌请求和用户统计响应的 OpenAPI 规范

feat: 添加微信认证相关的 OpenAPI 规范，包括用户信息、登录请求和个人资料请求

feat: 添加 is_delete 字段迁移脚本，支持在集合中添加软删除字段

feat: 添加软删除规则应用脚本，确保所有相关集合的查询规则包含软删除条件

feat: 添加购物车和订单业务 ID 自动生成的迁移脚本，确保字段类型和自动生成规则正确

pocket-base/spec/openapi-wx/paths/attachments.yaml

@@ -0,0 +1,135 @@
+attachmentRecords:
+  get:
+    operationId: getPocketBaseAttachmentRecords
+    tags:
+      - 附件信息
+    summary: 根据 attachments_id 查询单条或多条附件信息
+    description: |
+      使用 PocketBase 原生 records list 接口查询 `tbl_attachments`。
+
+      当前线上权限规则：
+      - `listRule = is_delete = 0`，因此任何客户端都可直接读取未软删除附件
+      - 原生 `create/update/delete` 仍仅管理员或管理后台用户允许
+
+      标准调用方式有两种：
+      1. 按 `attachments_id` 查询单条：
+         - `filter=attachments_id="ATT-1774599142438-8n1UcU"`
+         - `perPage=1`
+         - `page=1`
+      2. 按多个 `attachments_id` 批量查询：
+         - 使用 `||` 组合多个等值条件
+         - 例如：`filter=attachments_id="ATT-1774599142438-8n1UcU" || attachments_id="ATT-1774599143999-7pQkLm"`
+         - 传 `perPage` 为预期返回条数，`page=1`
+
+      注意：
+      - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
+      - `attachments_link` 返回的是 PocketBase 文件字段值，不是完整下载地址
+      - 若需文件流地址，可按 PocketBase 标准文件路径自行拼接：`/pb/api/files/{collectionId}/{recordId}/{attachments_link}`
+    parameters:
+      - name: filter
+        in: query
+        required: false
+        description: |
+          PocketBase 标准过滤表达式。
+
+          - 按 `attachments_id` 精确查询单条：`attachments_id="ATT-1774599142438-8n1UcU"`
+          - 按多个 `attachments_id` 批量查询：`attachments_id="ATT-1774599142438-8n1UcU" || attachments_id="ATT-1774599143999-7pQkLm"`
+          - 不传该参数时，返回分页列表
+        schema:
+          type: string
+        example: attachments_id="ATT-1774599142438-8n1UcU"
+      - name: page
+        in: query
+        required: false
+        description: 页码
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: perPage
+        in: query
+        required: false
+        description: 每页条数；单查建议为 `1`，批量查询建议设置为预期条数
+        schema:
+          type: integer
+          minimum: 1
+          default: 20
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseAttachmentListResponse'
+            examples:
+              byAttachmentsId:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items:
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      attachments_id: 附件业务ID | string
+                      attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
+                      attachments_filename: 原始文件名 | string
+                      attachments_filetype: 文件类型或MIME | string
+                      attachments_size: 文件大小 | number
+                      attachments_owner: 上传者业务标识 | string
+                      attachments_md5: 文件MD5 | string
+                      attachments_ocr: OCR识别结果 | string
+                      attachments_status: 附件状态 | string
+                      attachments_remark: 备注 | string
+              byAttachmentsIds:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items:
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      attachments_id: ATT-1774599142438-8n1UcU
+                      attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
+                      attachments_filename: 原始文件名 | string
+                      attachments_filetype: 文件类型或MIME | string
+                      attachments_size: 文件大小 | number
+                      attachments_owner: 上传者业务标识 | string
+                      attachments_md5: 文件MD5 | string
+                      attachments_ocr: OCR识别结果 | string
+                      attachments_status: 附件状态 | string
+                      attachments_remark: 备注 | string
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      attachments_id: ATT-1774599143999-7pQkLm
+                      attachments_link: PocketBase文件字段值，可拼接文件流地址 | string
+                      attachments_filename: 原始文件名 | string
+                      attachments_filetype: 文件类型或MIME | string
+                      attachments_size: 文件大小 | number
+                      attachments_owner: 上传者业务标识 | string
+                      attachments_md5: 文件MD5 | string
+                      attachments_ocr: OCR识别结果 | string
+                      attachments_status: 附件状态 | string
+                      attachments_remark: 备注 | string
+      '400':
+        description: 查询参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'

pocket-base/spec/openapi-wx/paths/cart-hooks.yaml

@@ -0,0 +1,335 @@
+cartList:
+  post:
+    operationId: postCartList
+    tags:
+      - 购物车
+    summary: 按索引字段模糊查询购物车列表
+    description: |
+      调用自定义 hooks API 查询当前登录用户的购物车列表。
+
+      查询规则：
+      - 仅允许查询当前 `Authorization` 对应用户自己的购物车记录
+      - 支持通过 `keyword` 对多个索引相关字段做统一模糊搜索，当前实现覆盖：
+        - `cart_id`
+        - `cart_number`
+        - `cart_product_id`
+        - `product_name`
+      - 支持按 `cart_status` 精确过滤
+      - 支持按 `cart_number` 精确过滤
+
+      目标软删除契约：
+      - 目标行为应仅返回 `is_delete = 0` 的记录
+      - 当前仓库实现尚未显式追加 `is_delete = 0` 过滤，请以实际后端代码为准
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: false
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/CartListRequest'
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/CartListResponse'
+      '400':
+        description: 参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+cartDetail:
+  post:
+    operationId: postCartDetail
+    tags:
+      - 购物车
+    summary: 按 cart_id 精确查询购物车详情
+    description: |
+      调用自定义 hooks API 按 `cart_id` 查询单条购物车记录。
+
+      查询规则：
+      - 仅允许访问当前 `Authorization` 对应用户自己的购物车记录
+      - 查询键为业务 ID `cart_id`，不是 PocketBase 原生 `recordId`
+
+      目标软删除契约：
+      - 目标行为应仅允许查询 `is_delete = 0` 的记录
+      - 当前仓库实现尚未显式追加 `is_delete = 0` 过滤，请以实际后端代码为准
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/CartDetailRequest'
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/CartRecord'
+      '400':
+        description: 参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '403':
+        description: 无权访问该购物车记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 未找到对应购物车记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+cartCreate:
+  post:
+    operationId: postCartCreate
+    tags:
+      - 购物车
+    summary: 新增购物车记录
+    description: |
+      调用自定义 hooks API 新增一条购物车记录。
+
+      创建规则：
+      - 服务端自动根据当前 token 写入 `cart_owner`
+      - 服务端自动生成 `cart_id`
+      - 若未传 `cart_number`，服务端会自动生成展示编号
+      - `cart_product_id`、`cart_product_quantity`、`cart_at_price` 为必填
+
+      目标软删除契约：
+      - 新建记录应默认为 `is_delete = 0`
+      - 当前仓库导出响应中尚未显式返回 `is_delete` 字段
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/CartCreateRequest'
+    responses:
+      '200':
+        description: 创建成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/CartRecord'
+      '400':
+        description: 参数错误、产品不存在或创建失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 重复请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+cartUpdate:
+  post:
+    operationId: postCartUpdate
+    tags:
+      - 购物车
+    summary: 修改购物车记录
+    description: |
+      调用自定义 hooks API 按 `cart_id` 更新购物车记录。
+
+      更新规则：
+      - 仅允许修改当前 `Authorization` 对应用户自己的购物车记录
+      - `cart_id` 为必填，用于精确定位目标记录
+      - 其余字段均为可选增量更新
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/CartUpdateRequest'
+    responses:
+      '200':
+        description: 更新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/CartRecord'
+      '400':
+        description: 参数错误、产品不存在或更新失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '403':
+        description: 无权访问该购物车记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 未找到待修改的购物车记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 重复请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+cartDelete:
+  post:
+    operationId: postCartDelete
+    tags:
+      - 购物车
+    summary: 软删除购物车记录
+    description: |
+      目标契约：按 `cart_id` 软删除购物车记录，将 `is_delete` 标记为 `1`，而不是物理删除。
+
+      当前仓库实现差异：
+      - 当前 `cartOrderService.deleteCart()` 仍直接调用 `$app.delete(record)` 做物理删除
+      - 因此当前后端实现与本软删除契约不一致
+      - 若要严格按本文档执行，需先同步调整后端服务实现，并在列表/详情接口中补充 `is_delete = 0` 过滤
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/CartDeleteRequest'
+    responses:
+      '200':
+        description: 删除成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/CartDeleteResponse'
+      '400':
+        description: 参数错误或删除失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '403':
+        description: 无权访问该购物车记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 未找到待删除的购物车记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 重复请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'

pocket-base/spec/openapi-wx/paths/cart-native.yaml

@@ -0,0 +1,250 @@
+cartRecords:
+  get:
+    operationId: getPocketBaseCartRecords
+    tags:
+      - 购物车
+    summary: 查询当前用户购物车列表或按业务 ID 精确查询
+    description: |
+      使用 PocketBase 原生 records list 接口查询 `tbl_cart`。
+
+      当前线上权限规则：
+      - `listRule = @request.auth.id != "" && cart_owner = @request.auth.openid && is_delete = 0`
+      - 因此调用方只能读到 `cart_owner` 等于自己 `openid` 且未软删除的记录
+
+      标准调用方式：
+      1. 查询当前登录用户全部购物车：
+         - 不传 `filter`
+         - 可选传 `sort=-cart_create`
+      2. 按业务 ID 精确查单条：
+         - `filter=cart_id="CART-..."`
+         - `perPage=1`
+         - `page=1`
+
+      注意：
+      - 这是 PocketBase 原生返回结构，不是 hooks 统一包装
+      - 即使不传 `filter`，返回结果也会继续受 `listRule` 限制
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: filter
+        in: query
+        required: false
+        description: |
+          PocketBase 标准过滤表达式。
+
+          - 查当前用户全部购物车时：不传
+          - 按 `cart_id` 精确查单条时：`cart_id="CART-1770000000000-abc123"`
+        schema:
+          type: string
+        example: cart_id="CART-1770000000000-abc123"
+      - name: page
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: perPage
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          default: 20
+      - name: sort
+        in: query
+        required: false
+        description: PocketBase 原生排序表达式，推荐 `-cart_create`
+        schema:
+          type: string
+        example: -cart_create
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCartListResponse'
+      '400':
+        description: 查询参数错误或不满足 listRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+  post:
+    operationId: postPocketBaseCartRecord
+    tags:
+      - 购物车
+    summary: 创建购物车记录
+    description: |
+      使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。
+
+      当前线上权限规则：
+      - `createRule = @request.auth.id != "" && @request.body.cart_owner = @request.auth.openid`
+      - 因此客户端创建时必须显式提交 `cart_owner`，并且值必须等于当前 token 对应的 `openid`
+
+      这意味着：
+      - 不能依赖服务端自动补 owner
+      - 不能省略 `cart_owner`
+      - 不满足规则时 PocketBase 会直接返回 `400`
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCartCreateRequest'
+    responses:
+      '200':
+        description: 创建成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord'
+      '400':
+        description: 参数错误、违反字段约束或不满足 createRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+
+cartRecordById:
+  patch:
+    operationId: patchPocketBaseCartRecordByRecordId
+    tags:
+      - 购物车
+    summary: 更新购物车记录
+    description: |
+      使用 PocketBase 原生 records update 接口更新 `tbl_cart`。
+
+      标准调用流程：
+      1. 先通过 `GET /pb/api/collections/tbl_cart/records?filter=cart_id="..."&perPage=1&page=1` 找到原生 `recordId`
+      2. 再调用当前 `PATCH /pb/api/collections/tbl_cart/records/{recordId}`
+
+      当前线上权限规则：
+      - `updateRule = @request.auth.id != "" && cart_owner = @request.auth.openid`
+      - 调用方只能修改自己的购物车记录
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: recordId
+        in: path
+        required: true
+        schema:
+          type: string
+        example: l2r3nq7rqhuob0h
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCartUpdateRequest'
+    responses:
+      '200':
+        description: 更新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord'
+      '400':
+        description: 参数错误或违反字段约束
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '404':
+        description: 记录不存在或不满足 updateRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+  delete:
+    operationId: deletePocketBaseCartRecordByRecordId
+    tags:
+      - 购物车
+    summary: 删除购物车记录
+    description: |
+      使用 PocketBase 原生 records delete 接口删除 `tbl_cart`。
+
+      当前线上权限规则：
+      - `deleteRule = @request.auth.id != "" && cart_owner = @request.auth.openid`
+      - 调用方只能删除自己的购物车记录
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: recordId
+        in: path
+        required: true
+        schema:
+          type: string
+        example: l2r3nq7rqhuob0h
+    responses:
+      '204':
+        description: 删除成功
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '404':
+        description: 记录不存在或不满足 deleteRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'

pocket-base/spec/openapi-wx/paths/company.yaml

@@ -0,0 +1,290 @@
+companyRecords:
+  post:
+    operationId: postPocketBaseCompanyRecord
+    tags:
+      - 企业信息
+    summary: 创建公司
+    description: |
+      使用 PocketBase 原生 records create 接口向 `tbl_company` 新增一行记录。
+
+      当前线上权限规则：
+      - `createRule = ""`，因此任何客户端都可直接创建
+      - 其他原生操作中，`update/delete/view` 仅管理员或管理后台用户允许
+
+      注意：
+      - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
+      - `company_id` 由数据库自动生成，客户端创建时不需要传
+      - `company_id` 仍带唯一索引，可用于后续按业务 id 查询
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCompanyCreateRequest'
+          examples:
+            default:
+              value:
+                company_name: 微信侧测试企业
+                company_type: 渠道商
+                company_entity: 张三
+                company_usci: '91310000123456789A'
+                company_nationality: 中国
+                company_nationality_code: CN
+                company_province: 上海
+                company_province_code: '310000'
+                company_city: 上海
+                company_city_code: '310100'
+                company_district: 浦东新区
+                company_district_code: '310115'
+                company_postalcode: '200000'
+                company_add: 上海市浦东新区XX路1号
+                company_status: 有效
+                company_level: A
+                company_owner_openid: wx-openid-owner-001
+                company_remark: 小程序公开创建示例
+    responses:
+      '200':
+        description: 创建成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCompanyRecord'
+      '400':
+        description: 参数错误或违反当前集合约束
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+  get:
+    operationId: getPocketBaseCompanyRecords
+    tags:
+      - 企业信息
+    summary: 查询整个 tbl_company 列表 / 根据 company_id 查询对应公司信息
+    description: |
+      使用 PocketBase 原生 records list 接口查询 `tbl_company`。
+
+      当前线上权限规则：
+      - `listRule = is_delete = 0`，因此默认只返回未软删除数据，且整个列表查询与条件查询都公开可读
+      - `createRule = ""`，因此创建也公开可调用
+      - `view/update/delete` 仅管理员或管理后台用户允许
+
+      标准调用方式有两种：
+      1. 根据 `company_id` 查询对应公司信息：
+         - `filter=company_id="WX-COMPANY-10001"`
+         - `perPage=1`
+         - `page=1`
+      2. 查询整个 `tbl_company` 列表：
+         - 不传 `filter`
+         - 按需传 `page`、`perPage`
+
+      注意：
+      - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
+      - PocketBase 原生标准接口里，“按 `company_id` 查询单条”和“查询整个列表”共用同一个 `GET /records` 路径，因此文档以同一个 GET operation 展示两种调用模式
+    parameters:
+      - name: filter
+        in: query
+        required: false
+        description: |
+          PocketBase 标准过滤表达式。
+
+          - 根据 `company_id` 查询单条时：`company_id="WX-COMPANY-10001"`
+          - 查询整个列表时：不传该参数
+        schema:
+          type: string
+        example: company_id="WX-COMPANY-10001"
+      - name: page
+        in: query
+        required: false
+        description: 页码
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: perPage
+        in: query
+        required: false
+        description: 每页条数；按 `company_id` 单查时建议固定为 `1`
+        schema:
+          type: integer
+          minimum: 1
+          default: 20
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCompanyListResponse'
+            examples:
+              byCompanyId:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items:
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      created: 记录创建时间 | string
+                      updated: 记录更新时间 | string
+                      company_id: 公司业务id，由数据库自动生成 | string
+                      company_name: 公司名称 | string
+                      company_type: 公司类型 | string
+                      company_entity: 公司法人 | string
+                      company_usci: 统一社会信用代码 | string
+                      company_nationality: 国家名称 | string
+                      company_nationality_code: 国家编码 | string
+                      company_province: 省份名称 | string
+                      company_province_code: 省份编码 | string
+                      company_city: 城市名称 | string
+                      company_city_code: 城市编码 | string
+                      company_district: 区县名称 | string
+                      company_district_code: 区县编码 | string
+                      company_postalcode: 邮政编码 | string
+                      company_add: 公司地址 | string
+                      company_status: 公司状态 | string
+                      company_level: 公司等级 | string
+                      company_owner_openid: 公司所有者openid | string
+                      company_remark: 备注 | string
+              listAll:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items:
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      created: 记录创建时间 | string
+                      updated: 记录更新时间 | string
+                      company_id: 公司业务id，由数据库自动生成 | string
+                      company_name: 公司名称 | string
+                      company_type: 公司类型 | string
+                      company_entity: 公司法人 | string
+                      company_usci: 统一社会信用代码 | string
+                      company_nationality: 国家名称 | string
+                      company_nationality_code: 国家编码 | string
+                      company_province: 省份名称 | string
+                      company_province_code: 省份编码 | string
+                      company_city: 城市名称 | string
+                      company_city_code: 城市编码 | string
+                      company_district: 区县名称 | string
+                      company_district_code: 区县编码 | string
+                      company_postalcode: 邮政编码 | string
+                      company_add: 公司地址 | string
+                      company_status: 公司状态 | string
+                      company_level: 公司等级 | string
+                      company_owner_openid: 公司所有者openid | string
+                      company_remark: 备注 | string
+              notFoundByCompanyId:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items: []
+      '400':
+        description: 查询参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+
+companyRecordById:
+  patch:
+    operationId: patchPocketBaseCompanyRecordByRecordId
+    tags:
+      - 企业信息
+    summary: 通过 company_id 定位后修改公司信息
+    description: |
+      这是 PocketBase 原生标准更新接口，实际写入路径参数仍然必须使用记录主键 `recordId`。
+
+      如果前端手里只有 `company_id`，标准调用流程是：
+      1. 先调用 `GET /pb/api/collections/tbl_company/records?filter=company_id="..."&perPage=1&page=1`
+      2. 从返回结果 `items[0].id` 中取出 PocketBase 原生记录主键
+      3. 再调用当前 `PATCH /pb/api/collections/tbl_company/records/{recordId}` 完成更新
+
+      当前线上权限规则：
+      - `updateRule` 仅管理员或管理后台用户允许
+      - 普通公开调用不能直接更新
+    parameters:
+      - name: recordId
+        in: path
+        required: true
+        description: 通过 `company_id` 查询结果拿到的 PocketBase 记录主键 `id`
+        schema:
+          type: string
+        example: l2r3nq7rqhuob0h
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCompanyUpdateRequest'
+          examples:
+            default:
+              value:
+                company_name: 微信侧测试企业（更新）
+                company_status: 有效
+                company_level: S
+                company_owner_openid: wx-openid-owner-001
+                company_district: 徐汇区
+                company_district_code: '310104'
+                company_remark: 通过 company_id 先定位再修改
+    responses:
+      '200':
+        description: 更新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseCompanyRecord'
+      '400':
+        description: 参数错误或违反集合约束
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 当前调用方没有 update 权限
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '404':
+        description: 记录不存在
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'

pocket-base/spec/openapi-wx/paths/documents.yaml

@@ -0,0 +1,222 @@
+documentRecords:
+  get:
+    operationId: getPocketBaseDocumentRecords
+    tags:
+      - 文档信息
+    summary: 分页查询文档列表 / 按 system_dict_id 与 enum 双条件分页筛选文档
+    description: |
+      使用 PocketBase 原生 records list 接口查询 `tbl_document`。
+
+      当前线上权限规则：
+      - `listRule = is_delete = 0`，因此任何客户端都可直接分页查询未软删除文档
+      - `viewRule = is_delete = 0`，因此单条详情也只可读取未软删除文档
+      - `create/update/delete` 仍仅管理员或管理后台用户允许
+
+      `document_type` 的存储格式为：
+      - `system_dict_id@dict_word_enum|system_dict_id@dict_word_enum`
+
+      业务上这里是两个独立条件，并且查询时两个条件都要满足：
+      - 条件 1：包含某个 `system_dict_id`
+      - 条件 2：包含某个 `enum`
+
+      PocketBase 原生标准接口实际只有一个 `filter` 参数，因此应在同一个 `filter` 中写成两个 `contains` 条件，例如：
+      - `system_dict_id = DICT-1774599144591-hAEFQj`
+      - `enum = UT1`
+      - 最终：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`
+
+      这条写法已经按线上真实数据验证通过。
+
+      排序说明：
+      - 当前线上统一按 `document_create` 排序
+      - 若要“最新上传的排在最前面”，请传 `sort=-document_create`
+
+      标准调用方式有两种：
+      1. 查询整个文档列表：
+         - 不传 `filter`
+         - 按需传 `page`、`perPage`
+         - 若要按最新上传倒序，传 `sort=-document_create`
+      2. 根据 `system_dict_id` 和 `enum` 两个业务条件分页筛选：
+         - 直接传 `filter=document_type ~ "<system_dict_id>" && document_type ~ "@<enum>"`
+         - 传 `page`、`perPage`
+         - 若要按最新上传倒序，传 `sort=-document_create`
+
+      注意：
+      - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
+      - 如果需要更复杂的条件组合，可继续使用 PocketBase 原生 `filter` 语法自行扩展
+    parameters:
+      - name: filter
+        in: query
+        required: false
+        description: |
+          PocketBase 标准过滤表达式。
+
+          - 查全部列表时：不传
+          - 按业务条件筛选时，同时写两个 `contains` 条件
+          - 第二个条件建议带上 `@` 前缀，避免误命中
+          - 例如：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`
+        schema:
+          type: string
+        example: document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"
+      - name: page
+        in: query
+        required: false
+        description: 页码
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: perPage
+        in: query
+        required: false
+        description: 每页条数
+        schema:
+          type: integer
+          minimum: 1
+          default: 20
+      - name: sort
+        in: query
+        required: false
+        description: |
+          PocketBase 原生排序表达式。
+
+          当前线上建议使用：
+          - `-document_create`：按最新上传倒序返回
+        schema:
+          type: string
+        example: -document_create
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseDocumentListResponse'
+            examples:
+              listAll:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items:
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      created: 记录创建时间 | string
+                      updated: 记录更新时间 | string
+                      document_id: 文档业务ID | string
+                      document_create: 文档创建时间，由数据库自动生成 | string
+                      document_effect_date: 文档生效日期 | string
+                      document_expiry_date: 文档到期日期 | string
+                      document_title: 文档标题 | string
+                      document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
+                      document_subtitle: 文档副标题 | string
+                      document_summary: 文档摘要 | string
+                      document_content: 正文内容 | string
+                      document_image: 图片附件ID串，底层按|分隔 | string
+                      document_video: 视频附件ID串，底层按|分隔 | string
+                      document_file: 文件附件ID串，底层按|分隔 | string
+                      document_status: 文档状态 | string
+                      document_owner: 上传者openid | string
+                      document_relation_model: 关联机型标识 | string
+                      document_keywords: 关键词，多选按|分隔 | string
+                      document_share_count: 0
+                      document_download_count: 0
+                      document_favorite_count: 0
+                      document_embedding_status: 文档嵌入状态 | string
+                      document_embedding_error: 文档嵌入错误原因 | string
+                      document_embedding_lasttime: 最后一次嵌入更新时间 | string
+                      document_vector_version: 向量版本号或模型名称 | string
+                      document_product_categories: 产品关联文档，多选按|分隔 | string
+                      document_application_scenarios: 筛选依据，多选按|分隔 | string
+                      document_hotel_type: 适用场景，多选按|分隔 | string
+                      document_remark: 备注 | string
+              filterByTypeToken:
+                value:
+                  page: 页码 | integer
+                  perPage: 每页条数 | integer
+                  totalItems: 总记录数 | integer
+                  totalPages: 总页数 | integer
+                  items:
+                    - id: PocketBase记录主键 | string
+                      collectionId: 集合ID | string
+                      collectionName: 集合名称 | string
+                      created: 记录创建时间 | string
+                      updated: 记录更新时间 | string
+                      document_id: 文档业务ID | string
+                      document_create: 文档创建时间，由数据库自动生成 | string
+                      document_effect_date: 文档生效日期 | string
+                      document_expiry_date: 文档到期日期 | string
+                      document_title: 文档标题 | string
+                      document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
+                      document_subtitle: 文档副标题 | string
+                      document_summary: 文档摘要 | string
+                      document_content: 正文内容 | string
+                      document_image: 图片附件ID串，底层按|分隔 | string
+                      document_video: 视频附件ID串，底层按|分隔 | string
+                      document_file: 文件附件ID串，底层按|分隔 | string
+                      document_status: 文档状态 | string
+                      document_owner: 上传者openid | string
+                      document_relation_model: 关联机型标识 | string
+                      document_keywords: 关键词，多选按|分隔 | string
+                      document_share_count: 0
+                      document_download_count: 0
+                      document_favorite_count: 0
+                      document_embedding_status: 文档嵌入状态 | string
+                      document_embedding_error: 文档嵌入错误原因 | string
+                      document_embedding_lasttime: 最后一次嵌入更新时间 | string
+                      document_vector_version: 向量版本号或模型名称 | string
+                      document_product_categories: 产品关联文档，多选按|分隔 | string
+                      document_application_scenarios: 筛选依据，多选按|分隔 | string
+                      document_hotel_type: 适用场景，多选按|分隔 | string
+                      document_remark: 备注 | string
+                    - id: ofy47wp9mmm0aub
+                      collectionId: pbc_3636602973
+                      collectionName: tbl_document
+                      created: '2026-03-28 07:20:00.000Z'
+                      updated: '2026-03-28 07:20:00.000Z'
+                      document_id: DOC-1774680568340-TeUSQn
+                      document_create: '2026-03-28 08:22:48.000Z'
+                      document_effect_date: ''
+                      document_expiry_date: ''
+                      document_title: 易从碳达人节能系统,为酒店每天每间房省二元,以智能推动酒店ESG双碳落地!上海酒店用品展我们在E7A01等您!!
+                      document_type: DICT-1774599144591-hAEFQj@UT1
+                      document_subtitle: ''
+                      document_summary: ''
+                      document_content: ''
+                      document_image: ATT-1774680568287-zuhJWN
+                      document_video: ''
+                      document_file: ''
+                      document_status: 有效
+                      document_owner: su13106859882
+                      document_relation_model: ''
+                      document_keywords: ''
+                      document_share_count: 0
+                      document_download_count: 0
+                      document_favorite_count: 0
+                      document_embedding_status: ''
+                      document_embedding_error: ''
+                      document_embedding_lasttime: ''
+                      document_vector_version: ''
+                      document_product_categories: ''
+                      document_application_scenarios: ''
+                      document_hotel_type: ''
+                      document_remark: ''
+      '400':
+        description: 查询参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'

pocket-base/spec/openapi-wx/paths/order-hooks.yaml

@@ -0,0 +1,334 @@
+orderList:
+  post:
+    operationId: postOrderList
+    tags:
+      - 订单
+    summary: 按索引字段模糊查询订单列表
+    description: |
+      调用自定义 hooks API 查询当前登录用户的订单列表。
+
+      查询规则：
+      - 仅允许查询当前 `Authorization` 对应用户自己的订单记录
+      - 支持通过 `keyword` 对多个索引相关字段做统一模糊搜索，当前实现覆盖：
+        - `order_id`
+        - `order_number`
+        - `order_source_id`
+      - 支持按 `order_status` 精确过滤
+      - 支持按 `order_source` 精确过滤
+
+      目标软删除契约：
+      - 目标行为应仅返回 `is_delete = 0` 的记录
+      - 当前仓库实现尚未显式追加 `is_delete = 0` 过滤，请以实际后端代码为准
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: false
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/OrderListRequest'
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/OrderListResponse'
+      '400':
+        description: 参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+orderDetail:
+  post:
+    operationId: postOrderDetail
+    tags:
+      - 订单
+    summary: 按 order_id 精确查询订单详情
+    description: |
+      调用自定义 hooks API 按 `order_id` 查询单条订单记录。
+
+      查询规则：
+      - 仅允许访问当前 `Authorization` 对应用户自己的订单记录
+      - 查询键为业务 ID `order_id`，不是 PocketBase 原生 `recordId`
+
+      目标软删除契约：
+      - 目标行为应仅允许查询 `is_delete = 0` 的记录
+      - 当前仓库实现尚未显式追加 `is_delete = 0` 过滤，请以实际后端代码为准
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/OrderDetailRequest'
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/OrderRecord'
+      '400':
+        description: 参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '403':
+        description: 无权访问该订单记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 未找到对应订单记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+orderCreate:
+  post:
+    operationId: postOrderCreate
+    tags:
+      - 订单
+    summary: 新增订单记录
+    description: |
+      调用自定义 hooks API 新增一条订单记录。
+
+      创建规则：
+      - 服务端自动根据当前 token 写入 `order_owner`
+      - 服务端自动生成 `order_id`
+      - 若未传 `order_number`，服务端会自动生成展示编号
+      - `order_source`、`order_source_id`、`order_snap`、`order_amount` 为必填
+
+      目标软删除契约：
+      - 新建记录应默认为 `is_delete = 0`
+      - 当前仓库导出响应中尚未显式返回 `is_delete` 字段
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/OrderCreateRequest'
+    responses:
+      '200':
+        description: 创建成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/OrderRecord'
+      '400':
+        description: 参数错误或创建失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 重复请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+orderUpdate:
+  post:
+    operationId: postOrderUpdate
+    tags:
+      - 订单
+    summary: 修改订单记录
+    description: |
+      调用自定义 hooks API 按 `order_id` 更新订单记录。
+
+      更新规则：
+      - 仅允许修改当前 `Authorization` 对应用户自己的订单记录
+      - `order_id` 为必填，用于精确定位目标记录
+      - 其余字段均为可选增量更新
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/OrderUpdateRequest'
+    responses:
+      '200':
+        description: 更新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/OrderRecord'
+      '400':
+        description: 参数错误或更新失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '403':
+        description: 无权访问该订单记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 未找到待修改的订单记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 重复请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+orderDelete:
+  post:
+    operationId: postOrderDelete
+    tags:
+      - 订单
+    summary: 软删除订单记录
+    description: |
+      目标契约：按 `order_id` 软删除订单记录，将 `is_delete` 标记为 `1`，而不是物理删除。
+
+      当前仓库实现差异：
+      - 当前 `cartOrderService.deleteOrder()` 仍直接调用 `$app.delete(record)` 做物理删除
+      - 因此当前后端实现与本软删除契约不一致
+      - 若要严格按本文档执行，需先同步调整后端服务实现，并在列表/详情接口中补充 `is_delete = 0` 过滤
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/OrderDeleteRequest'
+    responses:
+      '200':
+        description: 删除成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/OrderDeleteResponse'
+      '400':
+        description: 参数错误或删除失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '403':
+        description: 无权访问该订单记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 未找到待删除的订单记录
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体必须为 application/json
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 重复请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'

pocket-base/spec/openapi-wx/paths/order-native.yaml

@@ -0,0 +1,241 @@
+orderRecords:
+  get:
+    operationId: getPocketBaseOrderRecords
+    tags:
+      - 订单
+    summary: 查询当前用户订单列表或按业务 ID 精确查询
+    description: |
+      使用 PocketBase 原生 records list 接口查询 `tbl_order`。
+
+      当前线上权限规则：
+      - `listRule = @request.auth.id != "" && order_owner = @request.auth.openid && is_delete = 0`
+      - 因此调用方只能读到 `order_owner` 等于自己 `openid` 且未软删除的记录
+
+      标准调用方式：
+      1. 查询当前登录用户全部订单：
+         - 不传 `filter`
+         - 可选传 `sort=-order_create`
+      2. 按业务 ID 精确查单条：
+         - `filter=order_id="ORDER-..."`
+         - `perPage=1`
+         - `page=1`
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: filter
+        in: query
+        required: false
+        schema:
+          type: string
+        example: order_id="ORDER-1770000000000-abc123"
+      - name: page
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: perPage
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          default: 20
+      - name: sort
+        in: query
+        required: false
+        description: PocketBase 原生排序表达式，推荐 `-order_create`
+        schema:
+          type: string
+        example: -order_create
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseOrderListResponse'
+      '400':
+        description: 查询参数错误或不满足 listRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+  post:
+    operationId: postPocketBaseOrderRecord
+    tags:
+      - 订单
+    summary: 创建订单记录
+    description: |
+      使用 PocketBase 原生 records create 接口向 `tbl_order` 新增记录。
+
+      当前线上权限规则：
+      - `createRule = @request.auth.id != "" && @request.body.order_owner = @request.auth.openid`
+      - 因此客户端创建时必须显式提交 `order_owner`，并且值必须等于当前 token 对应的 `openid`
+
+      这意味着：
+      - 不能依赖服务端自动补 owner
+      - 不能省略 `order_owner`
+      - 不满足规则时 PocketBase 会直接返回 `400`
+    security:
+      - BearerAuth: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseOrderCreateRequest'
+    responses:
+      '200':
+        description: 创建成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseOrderRecord'
+      '400':
+        description: 参数错误、违反字段约束或不满足 createRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+
+orderRecordById:
+  patch:
+    operationId: patchPocketBaseOrderRecordByRecordId
+    tags:
+      - 订单
+    summary: 更新订单记录
+    description: |
+      使用 PocketBase 原生 records update 接口更新 `tbl_order`。
+
+      标准调用流程：
+      1. 先通过 `GET /pb/api/collections/tbl_order/records?filter=order_id="..."&perPage=1&page=1` 找到原生 `recordId`
+      2. 再调用当前 `PATCH /pb/api/collections/tbl_order/records/{recordId}`
+
+      当前线上权限规则：
+      - `updateRule = @request.auth.id != "" && order_owner = @request.auth.openid`
+      - 调用方只能修改自己的订单记录
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: recordId
+        in: path
+        required: true
+        schema:
+          type: string
+        example: l2r3nq7rqhuob0h
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseOrderUpdateRequest'
+    responses:
+      '200':
+        description: 更新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseOrderRecord'
+      '400':
+        description: 参数错误或违反字段约束
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '404':
+        description: 记录不存在或不满足 updateRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+  delete:
+    operationId: deletePocketBaseOrderRecordByRecordId
+    tags:
+      - 订单
+    summary: 删除订单记录
+    description: |
+      使用 PocketBase 原生 records delete 接口删除 `tbl_order`。
+
+      当前线上权限规则：
+      - `deleteRule = @request.auth.id != "" && order_owner = @request.auth.openid`
+      - 调用方只能删除自己的订单记录
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: recordId
+        in: path
+        required: true
+        schema:
+          type: string
+        example: l2r3nq7rqhuob0h
+    responses:
+      '204':
+        description: 删除成功
+      '401':
+        description: token 缺失、无效或已过期
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '404':
+        description: 记录不存在或不满足 deleteRule
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'

pocket-base/spec/openapi-wx/paths/products.yaml

@@ -0,0 +1,119 @@
+productRecords:
+  get:
+    operationId: getPocketBaseProductListRecords
+    tags:
+      - 产品信息
+    summary: 根据产品分类精确筛选并按分类排序值升序返回产品列表
+    description: |
+      使用 PocketBase 原生 records list 接口查询 `tbl_product_list`。
+
+      当前接口约定：
+      - 默认仅返回 `is_delete = 0` 的未软删除产品
+      - 条件：按 `prod_list_category` 精确匹配筛选
+      - 排序：按 `prod_list_sort` 从小到大排序
+
+      标准调用参数建议：
+      - `filter=prod_list_category="<产品分类>"`
+      - `sort=prod_list_sort`
+
+      注意：
+      - 这是 PocketBase 原生返回结构，不是 hooks 统一 `{ statusCode, errMsg, data }` 包装
+      - 若不传 `sort`，将由 PocketBase 默认排序策略决定返回顺序
+    parameters:
+      - name: filter
+        in: query
+        required: true
+        description: |
+          PocketBase 标准过滤表达式，当前要求按产品分类精确值筛选。
+
+          推荐写法：`prod_list_category="<产品分类>"`
+        schema:
+          type: string
+        example: prod_list_category="<产品分类>"
+      - name: page
+        in: query
+        required: false
+        description: 页码
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: perPage
+        in: query
+        required: false
+        description: 每页条数
+        schema:
+          type: integer
+          minimum: 1
+          default: 20
+      - name: sort
+        in: query
+        required: false
+        description: |
+          PocketBase 原生排序表达式。
+
+          当前要求使用：
+          - `prod_list_sort`：按分类排序值从小到大
+        schema:
+          type: string
+        example: prod_list_sort
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseProductListListResponse'
+            examples:
+              byCategoryAscSort:
+                value:
+                  page: <页码>|<integer>
+                  perPage: <每页条数>|<integer>
+                  totalItems: <总记录数>|<integer>
+                  totalPages: <总页数>|<integer>
+                  items:
+                    - id: <PocketBase记录主键>|<string>
+                      collectionId: <集合ID>|<string>
+                      collectionName: <集合名称>|<string>
+                      created: <记录创建时间>|<string>
+                      updated: <记录更新时间>|<string>
+                      prod_list_id: <产品列表业务ID>|<string>
+                      prod_list_name: <产品名称>|<string>
+                      prod_list_modelnumber: <产品型号>|<string>
+                      prod_list_icon: <产品图标附件ID>|<string>
+                      prod_list_description: <产品说明>|<string>
+                      prod_list_feature: <产品特色>|<string>
+                      prod_list_parameters:
+                        - name: <属性名>|<string>
+                          value: <属性值>|<string>
+                      prod_list_plantype: <产品方案>|<string>
+                      prod_list_category: <产品分类>|<string>
+                      prod_list_sort: 10
+                      prod_list_comm_type: <通讯类型>|<string>
+                      prod_list_series: <产品系列>|<string>
+                      prod_list_power_supply: <供电方式>|<string>
+                      prod_list_tags: <产品标签>|<string>
+                      prod_list_status: <产品状态>|<string>
+                      prod_list_basic_price: 1999
+                      prod_list_vip_price:
+                        - viplevel: VIP1
+                          price: 1899
+                      prod_list_remark: <备注>|<string>
+      '400':
+        description: 查询参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '403':
+        description: 集合规则被锁定或服务端权限设置异常
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/PocketBaseNativeError'

pocket-base/spec/openapi-wx/paths/system.yaml

@@ -0,0 +1,89 @@
+usersCount:
+  post:
+    security: []
+    operationId: postSystemUsersCount
+    tags:
+      - 系统
+    summary: 查询用户总数
+    description: 统计 `tbl_auth_users` 集合中的记录总数。
+    responses:
+      '200':
+        description: 查询成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/UsersCountResponse'
+      '400':
+        description: 请求参数错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+refreshToken:
+  post:
+    security:
+      - BearerAuth: []
+      - {}
+    operationId: postSystemRefreshToken
+    tags:
+      - 系统
+    summary: 刷新认证 token
+    description: |
+      当当前 `Authorization` 仍有效时，直接基于当前 auth 用户续签。
+      当 token 失效时，可传入 `users_wx_code` 走微信 code 重新签发。
+    requestBody:
+      required: false
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/SystemRefreshTokenRequest'
+    responses:
+      '200':
+        description: 刷新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/RefreshTokenResponse'
+      '400':
+        description: 参数错误或微信 code 换取失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 无效，且未提供有效的 `users_wx_code`
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '404':
+        description: 当前用户不存在
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体不是 JSON
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'

pocket-base/spec/openapi-wx/paths/wechat-auth.yaml

@@ -0,0 +1,117 @@
+wechatLogin:
+  post:
+    security: []
+    operationId: postWechatLogin
+    tags:
+      - 微信认证
+    summary: 微信登录或首次注册
+    description: |
+      使用微信 `users_wx_code` 换取微信 openid。
+      若 `tbl_auth_users` 中不存在对应用户，则自动创建新 auth 用户并返回 token。
+      首次注册时，`users_level` 默认保持为空，不自动写入会员等级。
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/WechatLoginRequest'
+    responses:
+      '200':
+        description: 登录或注册成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/AuthSuccessResponse'
+      '400':
+        description: 参数错误或保存用户失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: 认证失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体不是 JSON
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+
+wechatProfile:
+  post:
+    security:
+      - BearerAuth: []
+    operationId: postWechatProfile
+    tags:
+      - 微信认证
+    summary: 更新微信用户资料
+    description: |
+      基于当前 `Authorization` 对应的 auth 用户按“非空字段增量更新”资料。
+
+      更新规则：
+      - 所有字段都不是必填
+      - 如果传了 `users_phone_code`，服务端优先调用微信接口换取真实手机号并写入 `users_phone`
+      - 如果没传 `users_phone_code`，但传了 `users_phone`，则直接将该手机号写入数据库
+      - 如果上传了 `users_picture`、`users_id_pic_a`、`users_id_pic_b`、`users_title_picture`，会按附件 ID 进行关联校验并更新
+      - 若当前用户类型为 `游客`，且本次未显式传 `users_type`，服务端会自动升级为 `注册用户`
+      - 如果某个字段未传或传空，则不会清空数据库中的已有值
+      - 只有请求体里非空的字段才会更新到数据库
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../../openapi-wx.yaml#/components/schemas/WechatProfileRequest'
+    responses:
+      '200':
+        description: 更新成功
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/WechatProfileResponse'
+      '400':
+        description: 参数错误、手机号已被占用、附件 ID 无效、微信手机号换取失败或资料更新失败
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '401':
+        description: token 无效或缺少 openid
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '415':
+        description: 请求体不是 JSON
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '429':
+        description: 请求过于频繁
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'
+      '500':
+        description: 服务端错误
+        content:
+          application/json:
+            schema:
+              $ref: '../../openapi-wx.yaml#/components/schemas/ErrorResponse'