diff --git a/.tmp-openapi-validate/make-openapi-standalone.cjs b/.tmp-openapi-validate/make-openapi-standalone.cjs
new file mode 100644
index 0000000..64b92b7
--- /dev/null
+++ b/.tmp-openapi-validate/make-openapi-standalone.cjs
@@ -0,0 +1,132 @@
+const fs = require('fs');
+const path = require('path');
+const YAML = require('yaml');
+
+const repoRoot = path.resolve(process.cwd(), '..');
+const specRoot = path.join(repoRoot, 'pocket-base', 'spec');
+const folders = ['openapi-wx', 'openapi-manage'];
+
+const allFiles = [];
+for (const folder of folders) {
+  const dir = path.join(specRoot, folder);
+  for (const name of fs.readdirSync(dir)) {
+    if (name.endsWith('.yaml')) allFiles.push(path.join(dir, name));
+  }
+}
+
+const docCache = new Map();
+function loadDoc(filePath) {
+  if (!docCache.has(filePath)) {
+    const text = fs.readFileSync(filePath, 'utf8');
+    docCache.set(filePath, YAML.parse(text));
+  }
+  return docCache.get(filePath);
+}
+
+function deepClone(v) {
+  return v == null ? v : JSON.parse(JSON.stringify(v));
+}
+
+function decodePointer(seg) {
+  return seg.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+function getByPointer(doc, pointer) {
+  if (!pointer || pointer === '#' || pointer === '') return doc;
+  const parts = pointer.replace(/^#/, '').split('/').filter(Boolean).map(decodePointer);
+  let cur = doc;
+  for (const p of parts) {
+    if (cur == null) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function mergeObjects(base, extra) {
+  if (base && typeof base === 'object' && !Array.isArray(base) && extra && typeof extra === 'object' && !Array.isArray(extra)) {
+    return { ...base, ...extra };
+  }
+  return base;
+}
+
+function isExternalRef(ref) {
+  if (typeof ref !== 'string') return false;
+  if (ref.startsWith('#')) return false;
+  if (/^https?:\/\//i.test(ref)) return false;
+  const [filePart] = ref.split('#');
+  return !!filePart;
+}
+
+function resolveExternalRef(ref, baseFile) {
+  const [filePart, hashPart = ''] = ref.split('#');
+  const targetFile = path.resolve(path.dirname(baseFile), filePart);
+  const targetDoc = loadDoc(targetFile);
+  const pointer = hashPart ? `#${hashPart}` : '#';
+  const targetNode = getByPointer(targetDoc, pointer);
+  return { targetFile, targetNode: deepClone(targetNode) };
+}
+
+function derefExternals(node, baseFile, seen = new Set()) {
+  if (Array.isArray(node)) {
+    return node.map((item) => derefExternals(item, baseFile, seen));
+  }
+  if (!node || typeof node !== 'object') {
+    return node;
+  }
+
+  if (typeof node.$ref === 'string' && isExternalRef(node.$ref)) {
+    const key = `${baseFile}::${node.$ref}`;
+    if (seen.has(key)) {
+      return node;
+    }
+    seen.add(key);
+
+    const { targetFile, targetNode } = resolveExternalRef(node.$ref, baseFile);
+    let inlined = derefExternals(targetNode, targetFile, seen);
+
+    const siblings = { ...node };
+    delete siblings.$ref;
+    if (Object.keys(siblings).length > 0) {
+      inlined = mergeObjects(inlined, derefExternals(siblings, baseFile, seen));
+    }
+    return inlined;
+  }
+
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    out[k] = derefExternals(v, baseFile, seen);
+  }
+  return out;
+}
+
+function ensureTopLevel(doc, filePath) {
+  if (!doc.openapi) doc.openapi = '3.1.0';
+  if (!doc.info || typeof doc.info !== 'object') {
+    const base = path.basename(filePath, '.yaml');
+    const group = filePath.includes('openapi-wx') ? 'WX Native' : 'Manage Hooks';
+    doc.info = {
+      title: `BAI ${group} API - ${base}`,
+      version: '1.0.0'
+    };
+  } else {
+    if (!doc.info.title) doc.info.title = `BAI API - ${path.basename(filePath, '.yaml')}`;
+    if (!doc.info.version) doc.info.version = '1.0.0';
+  }
+  if (!Array.isArray(doc.servers)) {
+    doc.servers = [
+      { url: 'https://bai-api.blv-oa.com', description: '生产环境' },
+      { url: 'http://localhost:8090', description: 'PocketBase 本地环境' }
+    ];
+  }
+}
+
+for (const filePath of allFiles) {
+  const original = loadDoc(filePath);
+  const transformed = derefExternals(deepClone(original), filePath);
+  ensureTopLevel(transformed, filePath);
+  const outText = YAML.stringify(transformed, { lineWidth: 0 });
+  fs.writeFileSync(filePath, outText, 'utf8');
+  docCache.set(filePath, transformed);
+}
+
+console.log(`Processed ${allFiles.length} yaml files under openapi-wx/openapi-manage.`);
diff --git a/docs/pb_tbl_product_list.md b/docs/pb_tbl_product_list.md
index 165bc6a..2ef0e86 100644
--- a/docs/pb_tbl_product_list.md
+++ b/docs/pb_tbl_product_list.md
@@ -16,6 +16,7 @@
 | `prod_list_id` | `text` | 是 | 产品列表业务 ID，唯一标识 |
 | `prod_list_name` | `text` | 是 | 产品名称 |
 | `prod_list_modelnumber` | `text` | 否 | 产品型号 |
+| `prod_list_barcode` | `text` | 否 | 产品料号 |
 | `prod_list_icon` | `text` | 否 | 产品图标，保存 `tbl_attachments.attachments_id`，多图时以 `|` 分隔 |
 | `prod_list_description` | `text` | 否 | 产品说明（editor 内容，建议保存 Markdown 或已净化 HTML） |
 | `prod_list_feature` | `text` | 否 | 产品特色 |
@@ -50,6 +51,7 @@
 ## 补充约定
 
 - `prod_list_icon` 仅保存附件业务 ID，真实文件统一在 `tbl_attachments`；多图时按上传顺序使用 `|` 聚合。
+- `prod_list_barcode` 为可空文本字段，用于保存产品料号；当前已接入产品管理页录入、产品列表模糊检索以及方案模板中的产品快照展示。
 - `is_delete` 用于软删除控制，产品停用/删除时建议优先标记为 `1`。
 - 集合默认查询规则已内置 `is_delete = 0`，产品列表默认不返回已软删除记录。
 - 当前预构建脚本中已将 `listRule` 与 `viewRule` 设置为空字符串（`""`），对应 PocketBase 的“任何人可查看”。
@@ -61,4 +63,4 @@
 - 前端渲染 `prod_list_description` 时应保持和存储格式一致（Markdown 渲染器或受控 HTML 渲染），避免直接注入未净化内容。
 - `prod_list_basic_price` 使用 `number`，如需货币精度策略建议后续统一为“分”或固定小数位。
 - PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。
-- 本文档为预构建结构说明，尚未执行线上建表。
+- 本文档已同步当前产品表建表脚本；若已执行脚本，则以 PocketBase 实际结构为准。
diff --git a/docs/pb_tbl_scheme_template.md b/docs/pb_tbl_scheme_template.md
index 687f949..8998949 100644
--- a/docs/pb_tbl_scheme_template.md
+++ b/docs/pb_tbl_scheme_template.md
@@ -22,7 +22,7 @@
 | `scheme_template_status` | `text` | 否 | 模板状态，如有效 / 主推 / 过期 |
 | `scheme_template_solution_type` | `text` | 否 | 适用方案类型 |
 | `scheme_template_solution_feature` | `text` | 否 | 适用方案特点 |
-| `scheme_template_product_list` | `json` | 否 | 产品清单，建议格式：`[{"product_id":"PROD-xxx","qty":5,"note":"客厅使用"}]` |
+| `scheme_template_product_list` | `json` | 否 | 产品清单，支持保存精简结构或完整产品快照数组 |
 | `scheme_template_description` | `text` | 否 | 模板说明 |
 | `scheme_template_remark` | `text` | 否 | 备注 |
 | `is_delete` | `number` | 否 | 软删除标记，`0` 表示未删除，`1` 表示已删除，默认 `0` |
@@ -53,7 +53,11 @@
 ## 补充约定
 
 - `scheme_template_icon` 建议延续现有项目做法，仅保存 `attachments_id`，真实文件统一走 `tbl_attachments`。
-- `scheme_template_product_list` 建议使用 `json` 数组，单项推荐结构：`product_id`、`qty`、`note`；不要保存自由格式长字符串。
+- `scheme_template_product_list` 建议使用 `json` 数组。
+- 兼容两种结构：
+- 精简结构：`{"product_id":"PROD-xxx","qty":5,"note":"客厅使用"}`
+- 完整快照结构：直接保存 `tbl_product_list` 导出的整行产品对象，至少应包含 `prod_list_id`，如存在产品型号 / 产品料号也建议一并保留（如 `prod_list_modelnumber`、`prod_list_barcode`）。
+- 页面 `/manage/scheme` 当前优先通过产品选择器保存完整产品快照，便于后续直接展示产品摘要与排序。
 - 若模板将来需要“官方模板 + 用户私有模板”并存，则需要额外引入发布状态字段或放宽公共模板读取规则；当前文档严格按 owner 私有模板设计。
 - `is_delete` 用于软删除控制，模板删除时建议优先标记为 `1`。
 - PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。
diff --git a/pocket-base/bai_api_pb_hooks/bai_api_shared/middlewares/requestGuards.js b/pocket-base/bai_api_pb_hooks/bai_api_shared/middlewares/requestGuards.js
index 06a781c..42460bc 100644
--- a/pocket-base/bai_api_pb_hooks/bai_api_shared/middlewares/requestGuards.js
+++ b/pocket-base/bai_api_pb_hooks/bai_api_shared/middlewares/requestGuards.js
@@ -525,6 +525,7 @@ function validateProductMutationBody(e, isUpdate) {
         prod_list_id: payload.prod_list_id || '',
         prod_list_name: payload.prod_list_name || '',
         prod_list_modelnumber: payload.prod_list_modelnumber || '',
+        prod_list_barcode: payload.prod_list_barcode || '',
         prod_list_icon: normalizeAttachmentIdList(payload.prod_list_icon, 'prod_list_icon').join('|'),
         prod_list_description: payload.prod_list_description || '',
         prod_list_feature: payload.prod_list_feature || '',
@@ -698,7 +699,7 @@ function validateCartMutationBody(e, isUpdate) {
 
     if (!isUpdate) {
         if (!payload.cart_product_id) {
-            throw createAppError(400, 'cart_product_id 为必填项')
+            throw createAppError(400, 'cart_product_id 为必填项，且必须传 tbl_product_list 的 recordId')
         }
         if (typeof payload.cart_product_quantity === 'undefined') {
             throw createAppError(400, 'cart_product_quantity 为必填项')
diff --git a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/cartOrderService.js b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/cartOrderService.js
index ac9b865..391ce2b 100644
--- a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/cartOrderService.js
+++ b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/cartOrderService.js
@@ -227,6 +227,7 @@ function buildProductInfo(record) {
             prod_list_id: '',
             prod_list_name: '',
             prod_list_modelnumber: '',
+            prod_list_barcode: '',
             prod_list_basic_price: null,
         }
     }
@@ -235,6 +236,7 @@ function buildProductInfo(record) {
         prod_list_id: record.getString('prod_list_id'),
         prod_list_name: record.getString('prod_list_name'),
         prod_list_modelnumber: record.getString('prod_list_modelnumber'),
+        prod_list_barcode: record.getString('prod_list_barcode'),
         prod_list_basic_price: record.get('prod_list_basic_price'),
     }
 }
@@ -295,6 +297,7 @@ function exportCartRecord(record, productRecord) {
         cart_remark: record.getString('cart_remark'),
         product_name: productInfo.prod_list_name,
         product_modelnumber: productInfo.prod_list_modelnumber,
+        product_barcode: productInfo.prod_list_barcode,
         product_basic_price: productInfo.prod_list_basic_price,
         created: String(record.created || ''),
         updated: String(record.updated || ''),
@@ -340,6 +343,7 @@ function exportAdminCartRecord(record) {
         cart_remark: record && typeof record.getString === 'function' ? record.getString('cart_remark') : String(record && record.cart_remark || ''),
         product_name: productInfo.prod_list_name,
         product_modelnumber: productInfo.prod_list_modelnumber,
+        product_barcode: productInfo.prod_list_barcode,
         product_basic_price: productInfo.prod_list_basic_price,
         created: String(record && record.created || ''),
         updated: String(record && record.updated || ''),
diff --git a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/productService.js b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/productService.js
index c6bd8ad..ff85726 100644
--- a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/productService.js
+++ b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/productService.js
@@ -580,6 +580,7 @@ function exportProductRecord(record, extra) {
         prod_list_id: record.getString('prod_list_id'),
         prod_list_name: record.getString('prod_list_name'),
         prod_list_modelnumber: record.getString('prod_list_modelnumber'),
+        prod_list_barcode: record.getString('prod_list_barcode'),
         prod_list_icon: iconIds.join('|'),
         prod_list_icon_ids: iconIds,
         prod_list_icon_attachments: iconAttachments,
@@ -639,6 +640,7 @@ function listProducts(payload) {
                 || item.prod_list_id.toLowerCase().indexOf(keyword) !== -1
                 || item.prod_list_name.toLowerCase().indexOf(keyword) !== -1
                 || item.prod_list_modelnumber.toLowerCase().indexOf(keyword) !== -1
+                || item.prod_list_barcode.toLowerCase().indexOf(keyword) !== -1
                 || item.prod_list_tags.toLowerCase().indexOf(keyword) !== -1
             const matchedStatus = !status || item.prod_list_status === status
             const matchedCategory = !category || item.prod_list_category === category
@@ -695,6 +697,7 @@ function createProduct(_userOpenid, payload) {
     record.set('prod_list_id', targetProductId)
     record.set('prod_list_name', normalizeText(payload.prod_list_name))
     record.set('prod_list_modelnumber', normalizeText(payload.prod_list_modelnumber))
+    record.set('prod_list_barcode', normalizeText(payload.prod_list_barcode))
     record.set('prod_list_icon', joinUniquePipeValues(payload.prod_list_icon))
     record.set('prod_list_description', normalizeText(payload.prod_list_description))
     record.set('prod_list_feature', normalizeText(payload.prod_list_feature))
@@ -746,6 +749,7 @@ function updateProduct(_userOpenid, payload) {
 
     record.set('prod_list_name', normalizeText(payload.prod_list_name))
     record.set('prod_list_modelnumber', normalizeText(payload.prod_list_modelnumber))
+    record.set('prod_list_barcode', normalizeText(payload.prod_list_barcode))
     record.set('prod_list_icon', joinUniquePipeValues(payload.prod_list_icon))
     record.set('prod_list_description', normalizeText(payload.prod_list_description))
     record.set('prod_list_feature', normalizeText(payload.prod_list_feature))
diff --git a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/schemeService.js b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/schemeService.js
index 16722e5..8f70d48 100644
--- a/pocket-base/bai_api_pb_hooks/bai_api_shared/services/schemeService.js
+++ b/pocket-base/bai_api_pb_hooks/bai_api_shared/services/schemeService.js
@@ -237,12 +237,29 @@ function normalizeTemplateProductList(value) {
             continue
         }
 
-        const productId = normalizeText(item.product_id)
+        const productId = normalizeText(item.prod_list_id || item.product_id)
         if (!productId) {
-            throw createAppError(400, 'scheme_template_product_list 第 ' + (i + 1) + ' 项 product_id 为必填项')
+            throw createAppError(400, 'scheme_template_product_list 第 ' + (i + 1) + ' 项必须包含 product_id 或 prod_list_id')
         }
         ensureProductExists(productId, 'scheme_template_product_list.product_id')
 
+        const hasProductSnapshot = Object.keys(item).some(function (key) {
+            return key.indexOf('prod_list_') === 0 || key === 'pb_id'
+        })
+
+        if (hasProductSnapshot) {
+            let snapshot = null
+            try {
+                snapshot = JSON.parse(JSON.stringify(item))
+            } catch (_error) {
+                throw createAppError(400, 'scheme_template_product_list 第 ' + (i + 1) + ' 项必须为可序列化的产品对象')
+            }
+
+            snapshot.prod_list_id = productId
+            result.push(snapshot)
+            continue
+        }
+
         const qty = Number(item.qty)
         if (!Number.isFinite(qty) || qty <= 0) {
             throw createAppError(400, 'scheme_template_product_list 第 ' + (i + 1) + ' 项 qty 必须为正数')
diff --git a/pocket-base/bai_web_pb_hooks/views/cart-order-manage.html b/pocket-base/bai_web_pb_hooks/views/cart-order-manage.html
index 70557d3..8a199da 100644
--- a/pocket-base/bai_web_pb_hooks/views/cart-order-manage.html
+++ b/pocket-base/bai_web_pb_hooks/views/cart-order-manage.html
@@ -574,12 +574,12 @@
             }
 
             return '<div class="table-wrap"><table><thead><tr>'
-                + '<th>商品名称</th><th>型号</th><th>数量</th><th>单价</th><th>状态</th><th>加入时间</th><th>购物车名</th>'
+                + '<th>商品名称</th><th>型号/料号</th><th>数量</th><th>单价</th><th>状态</th><th>加入时间</th><th>购物车名</th>'
                 + '</tr></thead><tbody>'
                 + items.map(function (item) {
                     return '<tr>'
                         + '<td data-label="商品名称"><div>' + escapeHtml(item.product_name || item.cart_product_business_id || item.cart_product_id || '-') + '</div><div class="muted">recordId：' + escapeHtml(item.cart_product_id || '-') + '</div><div class="muted">业务ID：' + escapeHtml(item.cart_product_business_id || '-') + '</div></td>'
-                        + '<td data-label="型号">' + escapeHtml(item.product_modelnumber || '-') + '</td>'
+                        + '<td data-label="型号/料号"><div>' + escapeHtml(item.product_modelnumber || '-') + '</div><div class="muted">料号：' + escapeHtml(item.product_barcode || '-') + '</div></td>'
                         + '<td data-label="数量">' + escapeHtml(item.cart_product_quantity || 0) + '</td>'
                         + '<td data-label="单价">¥' + escapeHtml(item.cart_at_price || 0) + '</td>'
                         + '<td data-label="状态">' + escapeHtml(item.cart_status || '-') + '</td>'
diff --git a/pocket-base/bai_web_pb_hooks/views/product-manage.html b/pocket-base/bai_web_pb_hooks/views/product-manage.html
index e8248e2..07ec8f3 100644
--- a/pocket-base/bai_web_pb_hooks/views/product-manage.html
+++ b/pocket-base/bai_web_pb_hooks/views/product-manage.html
@@ -122,7 +122,7 @@
 
         <section class="panel">
             <div class="toolbar">
-                <input id="keywordInput" placeholder="按名称/型号/标签搜索" />
+                <input id="keywordInput" placeholder="按名称/型号/料号/标签搜索" />
                 <select id="statusFilter"><option value="">全部状态</option></select>
                 <select id="categoryFilter"><option value="">全部分类</option></select>
                 <button class="btn btn-secondary" id="searchBtn" type="button">查询</button>
@@ -135,13 +135,19 @@
                 <div class="muted" id="editorMode">当前模式：新建</div>
             </div>
             <div class="grid" style="margin-top:14px;">
-                <div>
+                <div class="full quarter-row">
+                    <div class="quarter-col-2">
                     <label for="prodListName">产品名称</label>
                     <input id="prodListName" placeholder="必填" />
-                </div>
-                <div>
+                    </div>
+                    <div class="quarter-col">
+                    <label for="prodListBarcode">产品料号</label>
+                    <input id="prodListBarcode" placeholder="可选" />
+                    </div>
+                    <div class="quarter-col">
                     <label for="prodListModel">产品型号</label>
                     <input id="prodListModel" placeholder="可选" />
+                    </div>
                 </div>
                 <div>
                     <label>产品分类（必填，单选）</label>
@@ -344,6 +350,10 @@
                     <label for="copyModelInput">新产品型号</label>
                     <input id="copyModelInput" placeholder="请输入新产品型号" />
                 </div>
+                <div>
+                    <label for="copyBarcodeInput">新产品料号</label>
+                    <input id="copyBarcodeInput" placeholder="请输入新产品料号" />
+                </div>
             </div>
             <div class="modal-actions">
                 <button class="btn btn-light" id="copyCancelBtn" type="button">取消</button>
@@ -388,6 +398,7 @@
         const copyModalEl = document.getElementById('copyModal')
         const copyNameInputEl = document.getElementById('copyNameInput')
         const copyModelInputEl = document.getElementById('copyModelInput')
+        const copyBarcodeInputEl = document.getElementById('copyBarcodeInput')
         const loadingMaskEl = document.getElementById('loadingMask')
         const loadingTextEl = document.getElementById('loadingText')
         const iconPreviewListEl = document.getElementById('iconPreviewList')
@@ -401,6 +412,7 @@
             keyword: document.getElementById('keywordInput'),
             name: document.getElementById('prodListName'),
             model: document.getElementById('prodListModel'),
+            barcode: document.getElementById('prodListBarcode'),
             basicPrice: document.getElementById('prodListBasicPrice'),
             feature: document.getElementById('prodListFeature'),
             sort: document.getElementById('prodListSort'),
@@ -611,6 +623,7 @@
                 prod_list_id: normalizeText(item && item.prod_list_id),
                 prod_list_name: normalizeText(item && item.prod_list_name),
                 prod_list_modelnumber: normalizeText(item && item.prod_list_modelnumber),
+                prod_list_barcode: normalizeText(item && item.prod_list_barcode),
                 prod_list_icon: normalizeText(item && item.prod_list_icon),
                 prod_list_description: normalizeText(item && item.prod_list_description),
                 prod_list_feature: normalizeText(item && item.prod_list_feature),
@@ -683,6 +696,7 @@
                     || normalizeText(item.prod_list_id).toLowerCase().indexOf(keyword) !== -1
                     || normalizeText(item.prod_list_name).toLowerCase().indexOf(keyword) !== -1
                     || normalizeText(item.prod_list_modelnumber).toLowerCase().indexOf(keyword) !== -1
+                    || normalizeText(item.prod_list_barcode).toLowerCase().indexOf(keyword) !== -1
                     || normalizeText(item.prod_list_tags).toLowerCase().indexOf(keyword) !== -1
                 const matchedStatus = !status || normalizeText(item.prod_list_status) === status
                 const matchedCategory = !category || normalizeText(item.prod_list_category) === category
@@ -1741,6 +1755,7 @@
         function resetForm() {
             fields.name.value = ''
             fields.model.value = ''
+            fields.barcode.value = ''
             fields.basicPrice.value = ''
             fields.feature.value = ''
             fields.sort.value = '0'
@@ -1791,6 +1806,7 @@
         function fillFormFromItem(item) {
             fields.name.value = item.prod_list_name || ''
             fields.model.value = item.prod_list_modelnumber || ''
+            fields.barcode.value = item.prod_list_barcode || ''
             state.productStatus = item.prod_list_status || '有效'
             fields.basicPrice.value = item.prod_list_basic_price === null || typeof item.prod_list_basic_price === 'undefined' ? '' : String(item.prod_list_basic_price)
             fields.feature.value = item.prod_list_feature || ''
@@ -1849,7 +1865,7 @@
 
             tableBodyEl.innerHTML = state.list.map(function (item) {
                 return '<tr>'
-                    + '<td data-label="名称/型号"><div><strong>' + escapeHtml(item.prod_list_name || '') + '</strong></div><div class="muted">' + escapeHtml(item.prod_list_modelnumber || '') + '</div></td>'
+                    + '<td data-label="名称/型号"><div><strong>' + escapeHtml(item.prod_list_name || '') + '</strong></div><div class="muted">型号：' + escapeHtml(item.prod_list_modelnumber || '-') + '</div><div class="muted">料号：' + escapeHtml(item.prod_list_barcode || '-') + '</div></td>'
                     + '<td data-label="分类信息"><div>' + escapeHtml(item.prod_list_category || '-') + '</div><div class="muted">方案:' + escapeHtml(item.prod_list_plantype || '-') + ' / 系列:' + escapeHtml(item.prod_list_series || '-') + '</div><div class="muted">分类排序: ' + escapeHtml(item.prod_list_sort === null || typeof item.prod_list_sort === 'undefined' ? '-' : item.prod_list_sort) + '（第 ' + escapeHtml(item.prod_list_category_rank || '-') + ' 位）</div></td>'
                     + '<td data-label="标签"><div>' + escapeHtml(item.prod_list_tags || '-') + '</div></td>'
                     + '<td data-label="状态/价格"><div>' + escapeHtml(item.prod_list_status || '-') + '</div><div class="muted">¥' + escapeHtml(item.prod_list_basic_price === null || typeof item.prod_list_basic_price === 'undefined' ? '-' : item.prod_list_basic_price) + '</div></td>'
@@ -1863,12 +1879,13 @@
             }).join('')
         }
 
-        function buildCopyPayload(source, nextName, nextModel) {
+        function buildCopyPayload(source, nextName, nextModel, nextBarcode) {
             return {
                 id: generatePocketBaseRecordId(),
                 prod_list_id: '',
                 prod_list_name: normalizeText(nextName),
                 prod_list_modelnumber: normalizeText(nextModel),
+                prod_list_barcode: normalizeText(nextBarcode),
                 prod_list_icon: source && source.prod_list_icon ? normalizeText(source.prod_list_icon) : '',
                 prod_list_description: source && source.prod_list_description ? normalizeText(source.prod_list_description) : '',
                 prod_list_feature: source && source.prod_list_feature ? normalizeText(source.prod_list_feature) : '',
@@ -1894,9 +1911,11 @@
             state.copySourceProductId = source ? normalizeText(source.prod_list_id) : ''
             const defaultName = normalizeText(source && source.prod_list_name)
             const defaultModel = normalizeText(source && source.prod_list_modelnumber)
+            const defaultBarcode = normalizeText(source && source.prod_list_barcode)
 
             copyNameInputEl.value = defaultName ? (defaultName + '-副本') : ''
             copyModelInputEl.value = defaultModel
+            copyBarcodeInputEl.value = defaultBarcode
             copyModalEl.classList.add('show')
 
             setTimeout(function () {
@@ -1910,6 +1929,7 @@
             copyModalEl.classList.remove('show')
             copyNameInputEl.value = ''
             copyModelInputEl.value = ''
+            copyBarcodeInputEl.value = ''
         }
 
         async function copyProduct(productId) {
@@ -1949,7 +1969,7 @@
                 return
             }
 
-            const payload = buildCopyPayload(source, normalizedName, copyModelInputEl.value)
+            const payload = buildCopyPayload(source, normalizedName, copyModelInputEl.value, copyBarcodeInputEl.value)
 
             setStatus('正在复制产品...', '')
             showLoading('正在复制产品，请稍候...')
@@ -2126,6 +2146,7 @@
                     prod_list_id: state.mode === 'edit' ? state.editingId : '',
                     prod_list_name: normalizeText(fields.name.value),
                     prod_list_modelnumber: normalizeText(fields.model.value),
+                    prod_list_barcode: normalizeText(fields.barcode.value),
                     prod_list_icon: joinPipe(finalIconIds),
                     prod_list_description: normalizeText(fields.description.value),
                     prod_list_feature: normalizeText(fields.feature.value),
@@ -2497,6 +2518,12 @@
             }
         })
 
+        copyBarcodeInputEl.addEventListener('keydown', function (event) {
+            if (event.key === 'Enter') {
+                confirmCopyProduct()
+            }
+        })
+
         document.getElementById('submitBtn').addEventListener('click', function () {
             submitProduct()
         })
diff --git a/pocket-base/bai_web_pb_hooks/views/scheme-manage.html b/pocket-base/bai_web_pb_hooks/views/scheme-manage.html
index 7d7e423..fe1d0d0 100644
--- a/pocket-base/bai_web_pb_hooks/views/scheme-manage.html
+++ b/pocket-base/bai_web_pb_hooks/views/scheme-manage.html
@@ -17,10 +17,10 @@
         * { box-sizing: border-box; }
         body { margin: 0; font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; background: linear-gradient(180deg, #edf6ff 0%, #f8fafc 100%); color: #0f172a; }
         .container { max-width: 1520px; margin: 0 auto; padding: 24px 14px 42px; }
+        .topbar { background: rgba(255,255,255,0.96); border: 1px solid #dbe3f0; border-radius: 20px; box-shadow: 0 18px 50px rgba(15, 23, 42, 0.08); padding: 18px; margin-bottom: 14px; }
         .panel { background: rgba(255,255,255,0.96); border: 1px solid #dbe3f0; border-radius: 20px; box-shadow: 0 18px 50px rgba(15, 23, 42, 0.08); padding: 18px; }
         .panel + .panel { margin-top: 14px; }
-        .header-row, .actions, .toolbar, .form-actions, .upload-row, .summary { display: flex; flex-wrap: wrap; gap: 10px; }
-        .header-row { justify-content: space-between; align-items: center; }
+        .actions, .toolbar, .form-actions, .upload-row, .summary, .product-picker-actions { display: flex; flex-wrap: wrap; gap: 10px; }
         .toolbar { display: grid; grid-template-columns: 1.2fr 1fr 1fr 1fr auto; gap: 10px; }
         .toolbar.simple { grid-template-columns: 1.5fr 1fr 1fr auto; }
         .grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 14px; }
@@ -60,6 +60,20 @@
         .thumb { width: 120px; height: 120px; border-radius: 16px; border: 1px solid #dbe3f0; object-fit: cover; background: #f8fafc; }
         .thumb-empty { display: flex; align-items: center; justify-content: center; color: #94a3b8; font-size: 13px; }
         .section-title { display: flex; justify-content: space-between; align-items: center; gap: 12px; margin-bottom: 12px; }
+        .product-picker-box { border: 1px solid #dbe3f0; border-radius: 16px; background: linear-gradient(180deg, #f8fbff 0%, #ffffff 100%); padding: 14px; }
+        .product-picker-grid { display: grid; grid-template-columns: 1fr 1.2fr auto auto; gap: 10px; align-items: end; }
+        .product-picker-actions { justify-content: flex-end; }
+        .product-list-summary { margin-top: 12px; border: 1px solid #dbe3f0; border-radius: 14px; background: #fff; overflow: hidden; }
+        .product-list-summary:empty { display: none; }
+        .product-list-empty { padding: 16px; color: #64748b; font-size: 13px; text-align: center; }
+        .product-summary-row { display: grid; grid-template-columns: auto 1fr auto; gap: 12px; align-items: center; padding: 12px 14px; border-bottom: 1px solid #e5e7eb; }
+        .product-summary-row:last-child { border-bottom: none; }
+        .product-summary-order { width: 28px; height: 28px; border-radius: 999px; background: #eff6ff; color: #1d4ed8; display: inline-flex; align-items: center; justify-content: center; font-size: 12px; font-weight: 700; }
+        .product-summary-main { min-width: 0; }
+        .product-summary-title { font-weight: 700; color: #0f172a; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+        .product-summary-meta { margin-top: 4px; color: #64748b; font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+        .product-summary-actions { display: flex; flex-wrap: wrap; gap: 8px; justify-content: flex-end; }
+        .product-summary-actions .btn { padding: 8px 12px; font-size: 13px; }
         .loading-mask { position: fixed; inset: 0; display: none; align-items: center; justify-content: center; padding: 24px; background: rgba(15, 23, 42, 0.42); z-index: 9999; }
         .loading-mask.show { display: flex; }
         .loading-card { min-width: min(92vw, 320px); padding: 24px 20px; border-radius: 20px; background: rgba(255,255,255,0.98); border: 1px solid #dbe3f0; text-align: center; box-shadow: 0 28px 70px rgba(15, 23, 42, 0.2); }
@@ -67,7 +81,7 @@
         .muted-block { padding: 12px 14px; border-radius: 14px; background: #f8fafc; border: 1px solid #e2e8f0; color: #475569; font-size: 13px; line-height: 1.7; }
         @keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
         @media (max-width: 1080px) {
-            .grid, .toolbar, .toolbar.simple, .thumb-box { grid-template-columns: 1fr; }
+            .grid, .toolbar, .toolbar.simple, .thumb-box, .product-picker-grid { grid-template-columns: 1fr; }
         }
         @media (max-width: 920px) {
             table, thead, tbody, th, td, tr { display: block; }
@@ -75,22 +89,20 @@
             tr { margin-bottom: 12px; border-bottom: 1px solid #e5e7eb; }
             td { display: flex; justify-content: space-between; gap: 10px; }
             td::before { content: attr(data-label); font-weight: 700; color: #475569; }
+            .product-summary-row { grid-template-columns: 1fr; }
+            .product-summary-actions { justify-content: flex-start; }
         }
     </style>
     {{ template "theme_head" . }}
 </head>
 <body>
     <div class="container">
-        <section class="panel">
-            <div class="header-row">
-                <div>
-                    <h1>方案预设管理</h1>
-                    <div class="tiny" style="margin-top:8px;">页面负责管理 `tbl_scheme_template` 与 `tbl_scheme`。模板图标上传会写入附件表，再把附件 ID 回填到模板记录。</div>
-                </div>
-                <div class="actions">
-                    <a class="btn btn-light" href="/pb/manage">返回主页</a>
-                    <button class="btn btn-light" id="refreshAllBtn" type="button">刷新全部</button>
-                </div>
+        <section class="topbar">
+            <h1>方案预设管理</h1>
+            <div class="tiny" style="margin-top:8px;">页面负责管理 `tbl_scheme_template` 与 `tbl_scheme`。模板图标上传会写入附件表，再把附件 ID 回填到模板记录。</div>
+            <div class="actions" style="margin-top:12px;">
+                <a class="btn btn-light" href="/pb/manage">返回主页</a>
+                <button class="btn btn-light" id="refreshAllBtn" type="button">刷新全部</button>
             </div>
             <div class="summary" style="margin-top:16px;">
                 <div class="summary-card">
@@ -113,7 +125,7 @@
             <div class="section-title">
                 <div>
                     <h2>方案模板</h2>
-                    <div class="tiny" style="margin-top:6px;">录入和管理 `tbl_scheme_template`。`scheme_template_product_list` 使用 JSON 数组编辑。</div>
+                    <div class="tiny" style="margin-top:6px;">录入和管理 `tbl_scheme_template`。产品清单支持按分类挑选产品，并自动同步为 JSON 数组。</div>
                 </div>
                 <div class="actions">
                     <button class="btn btn-secondary" id="newTemplateBtn" type="button">新建模板</button>
@@ -202,10 +214,39 @@
                         </div>
                     </div>
                 </div>
+                <div class="full">
+                    <label>产品清单构建器</label>
+                    <div class="product-picker-box">
+                        <div class="product-picker-grid">
+                            <div>
+                                <label for="templateProductCategoryFilter">产品分类</label>
+                                <select id="templateProductCategoryFilter">
+                                    <option value="">请先加载分类</option>
+                                </select>
+                            </div>
+                            <div>
+                                <label for="templateProductSelect">选择产品</label>
+                                <select id="templateProductSelect">
+                                    <option value="">请先选择分类</option>
+                                </select>
+                            </div>
+                            <div class="product-picker-actions">
+                                <button class="btn btn-secondary" id="addTemplateProductBtn" type="button">加入产品</button>
+                            </div>
+                            <div class="product-picker-actions">
+                                <button class="btn btn-light" id="reloadTemplateProductsBtn" type="button">刷新产品源</button>
+                            </div>
+                        </div>
+                        <div class="hint">选择逻辑与产品管理页一致：先选分类，再选产品。加入后会把该产品整行数据写入下方 JSON 数组。</div>
+                        <div class="product-list-summary" id="templateProductSummary">
+                            <div class="product-list-empty">暂无已选产品，请先选择分类和产品后加入。</div>
+                        </div>
+                    </div>
+                </div>
                 <div class="full">
                     <label for="templateProductList">产品清单 JSON</label>
-                    <textarea id="templateProductList" placeholder='示例：[{"product_id":"PROD-001","qty":2,"note":"主卧"}]'></textarea>
-                    <div class="hint">必须是数组，每项至少包含 `product_id` 与正数 `qty`。</div>
+                    <textarea id="templateProductList" placeholder='示例：[{"prod_list_id":"PROD-001","prod_list_name":"智能面板","prod_list_barcode":"PLB-001","prod_list_category":"客控主机"}]'></textarea>
+                    <div class="hint">默认由上方构建器自动同步。你也可以直接手动编辑 JSON，失去焦点后页面会尝试重新渲染简要清单。</div>
                 </div>
                 <div class="full">
                     <label for="templateDescription">模板说明</label>
@@ -373,6 +414,11 @@
         const currentModeEl = document.getElementById('currentMode')
         const templateCountEl = document.getElementById('templateCount')
         const schemeCountEl = document.getElementById('schemeCount')
+        const templateProductSummaryEl = document.getElementById('templateProductSummary')
+
+        const productDictNameMap = {
+            category: '产品-产品分类',
+        }
 
         const state = {
             templateMode: 'idle',
@@ -382,6 +428,9 @@
             templates: [],
             schemes: [],
             lastUploadedTemplateIcon: null,
+            productDictionariesByName: {},
+            selectableProducts: [],
+            templateProductItems: [],
         }
 
         const templateFields = {
@@ -394,6 +443,9 @@
             solutionFeature: document.getElementById('templateSolutionFeature'),
             iconId: document.getElementById('templateIconId'),
             iconFile: document.getElementById('templateIconFile'),
+            productCategoryFilter: document.getElementById('templateProductCategoryFilter'),
+            productSelect: document.getElementById('templateProductSelect'),
+            productSummary: templateProductSummaryEl,
             productList: document.getElementById('templateProductList'),
             description: document.getElementById('templateDescription'),
             remark: document.getElementById('templateRemark'),
@@ -583,6 +635,290 @@
             }
         }
 
+        function cloneJsonValue(value) {
+            try {
+                return JSON.parse(JSON.stringify(value))
+            } catch (_error) {
+                return null
+            }
+        }
+
+        function findProductDictByName(name) {
+            return state.productDictionariesByName[name] || null
+        }
+
+        function getProductDictItems(dictName) {
+            const dict = findProductDictByName(dictName)
+            if (!dict || !Array.isArray(dict.items)) {
+                return []
+            }
+            return dict.items
+        }
+
+        function fillSelectByDict(selectEl, dictName, defaultLabel) {
+            if (!selectEl) {
+                return
+            }
+
+            const items = getProductDictItems(dictName)
+            const currentValue = selectEl.value || ''
+            let html = '<option value="">' + escapeHtml(defaultLabel || '请选择') + '</option>'
+
+            for (let i = 0; i < items.length; i += 1) {
+                const value = normalizeText(items[i].enum || '')
+                const label = normalizeText(items[i].description || value)
+                html += '<option value="' + escapeHtml(value) + '">' + escapeHtml(label) + '</option>'
+            }
+
+            selectEl.innerHTML = html
+            if (currentValue) {
+                selectEl.value = currentValue
+            }
+        }
+
+        function getTemplateProductId(item) {
+            return normalizeText(item && (item.prod_list_id || item.product_id))
+        }
+
+        function getProductSourceById(productId) {
+            const targetId = normalizeText(productId)
+            if (!targetId) {
+                return null
+            }
+
+            for (let i = 0; i < state.selectableProducts.length; i += 1) {
+                if (normalizeText(state.selectableProducts[i].prod_list_id) === targetId) {
+                    return state.selectableProducts[i]
+                }
+            }
+
+            return null
+        }
+
+        function buildTemplateProductSummary(item) {
+            const current = item && typeof item === 'object' ? item : {}
+            const productId = getTemplateProductId(current)
+            const source = getProductSourceById(productId) || current
+            const title = normalizeText(source.prod_list_name || source.product_name || productId || '未命名产品')
+            const model = normalizeText(source.prod_list_modelnumber)
+            const barcode = normalizeText(source.prod_list_barcode || source.product_barcode)
+            const category = normalizeText(source.prod_list_category)
+            const status = normalizeText(source.prod_list_status)
+            const price = source && (source.prod_list_basic_price || source.prod_list_basic_price === 0)
+                ? ('¥' + source.prod_list_basic_price)
+                : ''
+            const qty = current && (current.qty || current.qty === 0) ? ('数量 ' + current.qty) : ''
+            const note = normalizeText(current && current.note)
+
+            return {
+                productId: productId,
+                title: title,
+                meta: [productId, model, barcode, category, status, price, qty, note].filter(Boolean).join(' / '),
+            }
+        }
+
+        function syncTemplateProductListTextarea() {
+            templateFields.productList.value = toJsonText(state.templateProductItems)
+        }
+
+        function renderTemplateProductSummary() {
+            if (!templateFields.productSummary) {
+                return
+            }
+
+            if (!state.templateProductItems.length) {
+                templateFields.productSummary.innerHTML = '<div class="product-list-empty">暂无已选产品，请先选择分类和产品后加入。</div>'
+                return
+            }
+
+            const rows = []
+            for (let i = 0; i < state.templateProductItems.length; i += 1) {
+                const summary = buildTemplateProductSummary(state.templateProductItems[i])
+                rows.push(
+                    '<div class="product-summary-row">'
+                    + '<div class="product-summary-order">' + (i + 1) + '</div>'
+                    + '<div class="product-summary-main">'
+                    + '<div class="product-summary-title">' + escapeHtml(summary.title) + '</div>'
+                    + '<div class="product-summary-meta">' + escapeHtml(summary.meta || '未补充摘要信息') + '</div>'
+                    + '</div>'
+                    + '<div class="product-summary-actions">'
+                    + '<button class="btn btn-light" type="button" data-template-product-up="' + i + '"' + (i === 0 ? ' disabled' : '') + '>上移</button>'
+                    + '<button class="btn btn-light" type="button" data-template-product-down="' + i + '"' + (i === state.templateProductItems.length - 1 ? ' disabled' : '') + '>下移</button>'
+                    + '<button class="btn btn-danger" type="button" data-template-product-remove="' + i + '">移除</button>'
+                    + '</div>'
+                    + '</div>'
+                )
+            }
+
+            templateFields.productSummary.innerHTML = rows.join('')
+        }
+
+        function setTemplateProductItems(items, options) {
+            const safeItems = Array.isArray(items) ? items : []
+            const nextItems = []
+
+            for (let i = 0; i < safeItems.length; i += 1) {
+                const cloned = cloneJsonValue(safeItems[i])
+                if (cloned && typeof cloned === 'object') {
+                    nextItems.push(cloned)
+                }
+            }
+
+            state.templateProductItems = nextItems
+            if (!options || !options.skipTextareaSync) {
+                syncTemplateProductListTextarea()
+            }
+            renderTemplateProductSummary()
+        }
+
+        function hydrateTemplateProductItemsFromTextarea() {
+            try {
+                const parsed = parseJsonTextarea(templateFields.productList.value, 'scheme_template_product_list')
+                setTemplateProductItems(parsed)
+                setStatus(templateStatusEl, '产品清单 JSON 已同步为简要列表。', 'success')
+                return parsed
+            } catch (error) {
+                setStatus(templateStatusEl, error.message || '产品清单 JSON 解析失败', 'error')
+                throw error
+            }
+        }
+
+        function renderTemplateProductCategoryOptions() {
+            fillSelectByDict(templateFields.productCategoryFilter, productDictNameMap.category, '全部分类')
+        }
+
+        function renderTemplateProductOptions() {
+            const category = normalizeText(templateFields.productCategoryFilter.value)
+            const options = ['<option value="">' + escapeHtml(category ? '请选择产品' : '请先选择分类') + '</option>']
+            const items = []
+
+            for (let i = 0; i < state.selectableProducts.length; i += 1) {
+                const item = state.selectableProducts[i]
+                if (category && normalizeText(item.prod_list_category) !== category) {
+                    continue
+                }
+                items.push(item)
+            }
+
+            items.sort(function (a, b) {
+                const sortDiff = Number(a.prod_list_sort || 0) - Number(b.prod_list_sort || 0)
+                if (sortDiff !== 0) {
+                    return sortDiff
+                }
+                return String(a.prod_list_name || '').localeCompare(String(b.prod_list_name || ''))
+            })
+
+            for (let i = 0; i < items.length; i += 1) {
+                const item = items[i]
+                const value = normalizeText(item.prod_list_id)
+                const label = [
+                    normalizeText(item.prod_list_name),
+                    normalizeText(item.prod_list_modelnumber),
+                    normalizeText(item.prod_list_barcode),
+                    normalizeText(item.prod_list_category),
+                ].filter(Boolean).join(' / ')
+                options.push('<option value="' + escapeHtml(value) + '">' + escapeHtml(label || value) + '</option>')
+            }
+
+            templateFields.productSelect.innerHTML = options.join('')
+        }
+
+        async function loadTemplateProductResources(skipStatus) {
+            if (!skipStatus) {
+                showLoading('正在加载产品分类与产品库...')
+            }
+            try {
+                const dictionaries = await requestJson('/dictionary/list', {})
+                const dictItems = Array.isArray(dictionaries && dictionaries.items) ? dictionaries.items : []
+                state.productDictionariesByName = {}
+                for (let i = 0; i < dictItems.length; i += 1) {
+                    state.productDictionariesByName[dictItems[i].dict_name] = dictItems[i]
+                }
+
+                const products = await requestJson('/product/list', {
+                    keyword: '',
+                    status: '',
+                    prod_list_category: '',
+                })
+                state.selectableProducts = Array.isArray(products && products.items) ? products.items : []
+                renderTemplateProductCategoryOptions()
+                renderTemplateProductOptions()
+                renderTemplateTable()
+                renderTemplateProductSummary()
+
+                if (!skipStatus) {
+                    setStatus(pageStatusEl, '模板可选产品数据已刷新。', 'success')
+                }
+            } catch (error) {
+                if (!skipStatus) {
+                    setStatus(pageStatusEl, error.message || '加载模板可选产品失败', 'error')
+                }
+                throw error
+            } finally {
+                if (!skipStatus) {
+                    hideLoading()
+                }
+            }
+        }
+
+        async function addSelectedTemplateProduct() {
+            const productId = normalizeText(templateFields.productSelect.value)
+            if (!productId) {
+                setStatus(templateStatusEl, '请先选择要加入模板的产品。', 'error')
+                return
+            }
+
+            for (let i = 0; i < state.templateProductItems.length; i += 1) {
+                if (getTemplateProductId(state.templateProductItems[i]) === productId) {
+                    setStatus(templateStatusEl, '该产品已在清单中，可直接调整顺序。', 'error')
+                    return
+                }
+            }
+
+            showLoading('正在读取产品详情...')
+            try {
+                const detail = await requestJson('/product/detail', { prod_list_id: productId })
+                const nextItems = state.templateProductItems.slice()
+                nextItems.push(detail)
+                setTemplateProductItems(nextItems)
+                setStatus(templateStatusEl, '产品已加入模板清单。', 'success')
+            } catch (error) {
+                setStatus(templateStatusEl, error.message || '加入产品失败', 'error')
+            } finally {
+                hideLoading()
+            }
+        }
+
+        function moveTemplateProductItem(index, offset) {
+            const currentIndex = Number(index)
+            const targetIndex = currentIndex + Number(offset)
+            if (!Number.isInteger(currentIndex) || currentIndex < 0 || currentIndex >= state.templateProductItems.length) {
+                return
+            }
+            if (!Number.isInteger(targetIndex) || targetIndex < 0 || targetIndex >= state.templateProductItems.length) {
+                return
+            }
+
+            const nextItems = state.templateProductItems.slice()
+            const currentItem = nextItems[currentIndex]
+            nextItems[currentIndex] = nextItems[targetIndex]
+            nextItems[targetIndex] = currentItem
+            setTemplateProductItems(nextItems)
+            setStatus(templateStatusEl, '产品顺序已调整。', 'success')
+        }
+
+        function removeTemplateProductItem(index) {
+            const currentIndex = Number(index)
+            if (!Number.isInteger(currentIndex) || currentIndex < 0 || currentIndex >= state.templateProductItems.length) {
+                return
+            }
+
+            const nextItems = state.templateProductItems.slice()
+            nextItems.splice(currentIndex, 1)
+            setTemplateProductItems(nextItems)
+            setStatus(templateStatusEl, '产品已从模板清单移除。', 'success')
+        }
+
         function formatDateTimeInput(value) {
             const text = normalizeText(value)
             if (!text) {
@@ -633,6 +969,12 @@
             for (let i = 0; i < state.templates.length; i += 1) {
                 const item = state.templates[i]
                 const productList = Array.isArray(item.scheme_template_product_list) ? item.scheme_template_product_list : []
+                const productSummary = productList.length
+                    ? productList.map(function (productItem, index) {
+                        const summary = buildTemplateProductSummary(productItem)
+                        return (index + 1) + '. ' + summary.title + (summary.meta ? (' / ' + summary.meta) : '')
+                    }).join('\n')
+                    : '-'
                 rows.push(
                     '<tr>'
                     + '<td data-label="模板 ID"><div class="code">' + escapeHtml(item.scheme_template_id) + '</div></td>'
@@ -640,7 +982,7 @@
                     + '<td data-label="Owner"><div class="code">' + escapeHtml(item.scheme_template_owner) + '</div></td>'
                     + '<td data-label="标签 / 状态">' + escapeHtml(item.scheme_template_label || '-') + '<br /><span class="tiny">' + escapeHtml(item.scheme_template_status || '-') + '</span></td>'
                     + '<td data-label="方案类型 / 特色">' + escapeHtml(item.scheme_template_solution_type || '-') + '<br /><span class="tiny">' + escapeHtml(item.scheme_template_solution_feature || '-') + '</span></td>'
-                    + '<td data-label="产品清单"><div class="json-preview tiny">' + escapeHtml(toJsonText(productList)) + '</div></td>'
+                    + '<td data-label="产品清单"><div class="json-preview tiny">' + escapeHtml(productSummary) + '</div></td>'
                     + '<td data-label="操作"><div class="actions">'
                     + '<button class="btn btn-light" type="button" data-template-edit="' + escapeHtml(item.scheme_template_id) + '">编辑</button>'
                     + '<button class="btn btn-danger" type="button" data-template-delete="' + escapeHtml(item.scheme_template_id) + '">删除</button>'
@@ -698,11 +1040,14 @@
             templateFields.solutionFeature.value = ''
             templateFields.iconId.value = ''
             templateFields.iconFile.value = ''
-            templateFields.productList.value = '[]'
+            templateFields.productCategoryFilter.value = ''
+            templateFields.productSelect.innerHTML = '<option value="">请先选择分类</option>'
             templateFields.description.value = ''
             templateFields.remark.value = ''
             state.lastUploadedTemplateIcon = null
+            setTemplateProductItems([])
             renderTemplateIcon('')
+            renderTemplateProductOptions()
         }
 
         function resetSchemeForm() {
@@ -796,8 +1141,11 @@
         async function refreshAll() {
             showLoading('正在刷新模板与方案数据...')
             try {
-                await loadTemplates()
-                await loadSchemes()
+                await Promise.all([
+                    loadTemplates(),
+                    loadSchemes(),
+                    loadTemplateProductResources(true),
+                ])
                 setStatus(pageStatusEl, '数据刷新完成。', 'success')
             } catch (error) {
                 setStatus(pageStatusEl, error.message || '刷新失败', 'error')
@@ -824,7 +1172,7 @@
                 templateFields.solutionType.value = detail.scheme_template_solution_type || ''
                 templateFields.solutionFeature.value = detail.scheme_template_solution_feature || ''
                 templateFields.iconId.value = detail.scheme_template_icon || ''
-                templateFields.productList.value = toJsonText(detail.scheme_template_product_list || [])
+                setTemplateProductItems(detail.scheme_template_product_list || [])
                 templateFields.description.value = detail.scheme_template_description || ''
                 templateFields.remark.value = detail.scheme_template_remark || ''
                 state.lastUploadedTemplateIcon = detail.scheme_template_icon_attachment || null
@@ -877,6 +1225,8 @@
         }
 
         function buildTemplatePayload() {
+            const productList = parseJsonTextarea(templateFields.productList.value, 'scheme_template_product_list')
+            setTemplateProductItems(productList)
             return {
                 scheme_template_id: normalizeText(templateFields.id.value),
                 scheme_template_name: normalizeText(templateFields.name.value),
@@ -886,7 +1236,7 @@
                 scheme_template_status: normalizeText(templateFields.status.value),
                 scheme_template_solution_type: normalizeText(templateFields.solutionType.value),
                 scheme_template_solution_feature: normalizeText(templateFields.solutionFeature.value),
-                scheme_template_product_list: parseJsonTextarea(templateFields.productList.value, 'scheme_template_product_list'),
+                scheme_template_product_list: productList,
                 scheme_template_description: templateFields.description.value || '',
                 scheme_template_remark: templateFields.remark.value || '',
             }
@@ -1066,12 +1416,31 @@
         document.getElementById('uploadTemplateIconBtn').addEventListener('click', function () {
             handleTemplateIconUpload()
         })
+        document.getElementById('addTemplateProductBtn').addEventListener('click', function () {
+            addSelectedTemplateProduct()
+        })
+        document.getElementById('reloadTemplateProductsBtn').addEventListener('click', function () {
+            loadTemplateProductResources()
+        })
         document.getElementById('clearTemplateIconBtn').addEventListener('click', function () {
             templateFields.iconId.value = ''
             templateFields.iconFile.value = ''
             state.lastUploadedTemplateIcon = null
             renderTemplateIcon('')
         })
+        templateFields.productCategoryFilter.addEventListener('change', function () {
+            renderTemplateProductOptions()
+        })
+        templateFields.productList.addEventListener('blur', function () {
+            if (!normalizeText(templateFields.productList.value)) {
+                setTemplateProductItems([])
+                return
+            }
+
+            try {
+                hydrateTemplateProductItemsFromTextarea()
+            } catch (_error) {}
+        })
 
         templateFields.iconId.addEventListener('input', function () {
             if (!normalizeText(templateFields.iconId.value)) {
@@ -1101,6 +1470,24 @@
                 return
             }
 
+            const templateProductUpIndex = target.getAttribute('data-template-product-up')
+            if (templateProductUpIndex !== null) {
+                moveTemplateProductItem(templateProductUpIndex, -1)
+                return
+            }
+
+            const templateProductDownIndex = target.getAttribute('data-template-product-down')
+            if (templateProductDownIndex !== null) {
+                moveTemplateProductItem(templateProductDownIndex, 1)
+                return
+            }
+
+            const templateProductRemoveIndex = target.getAttribute('data-template-product-remove')
+            if (templateProductRemoveIndex !== null) {
+                removeTemplateProductItem(templateProductRemoveIndex)
+                return
+            }
+
             const schemeEditId = target.getAttribute('data-scheme-edit')
             if (schemeEditId) {
                 editScheme(schemeEditId)
diff --git a/pocket-base/spec/openapi-manage.yaml b/pocket-base/spec/openapi-manage.yaml
deleted file mode 100644
index 29ad05a..0000000
--- a/pocket-base/spec/openapi-manage.yaml
+++ /dev/null
@@ -1,1811 +0,0 @@
-openapi: 3.1.0
-info:
-  title: BAI PocketBase Manage API
-  description: |
-    基于 PocketBase `bai_api_pb_hooks` 的对外接口文档，可直接导入 Postman。
-    当前 `tbl_auth_users.openid` 已被定义为全平台统一身份锚点：
-    - 微信用户：`openid = 微信 openid`
-    - 平台用户：`openid = 服务端生成的 GUID`
-    请在 Apifox 环境中统一设置全局 Header：`Authorization: Bearer {{token}}`。
-  version: 1.0.0-manage
-  license:
-    name: Proprietary
-    identifier: LicenseRef-Proprietary
-servers:
-  - url: https://bai-api.blv-oa.com
-    description: "生产环境"
-  - url: http://localhost:8090
-    description: "PocketBase 本地环境"
-tags:
-  - name: 系统
-    description: "基础检查接口"
-  - name: 平台认证
-    description: "面向平台用户的认证接口；平台用户会生成 GUID 并写入统一 `openid` 字段。"
-  - name: 字典管理
-    description: "字典读接口公开；字典写接口面向 ManagePlatform 用户。"
-  - name: 附件管理
-    description: "面向 ManagePlatform 用户的附件上传、查询与删除接口。"
-  - name: 文档管理
-    description: "面向 ManagePlatform 用户的文档新增、查询、修改、删除接口；查询时会自动返回关联附件的 PocketBase 文件流链接。"
-  - name: 文档历史
-    description: "面向 ManagePlatform 用户的文档操作历史查询接口。"
-components:
-  schemas:
-    ApiResponse:
-      type: object
-      required: [statusCode, errMsg, data]
-      properties:
-        statusCode:
-          type: integer
-          description: "业务状态码"
-          example: 200
-        errMsg:
-          type: string
-          description: "业务提示信息"
-          example: 操作成功
-        data:
-          description: "业务响应数据"
-          type: object
-          additionalProperties: true
-    HealthData:
-      type: object
-      properties:
-        status:
-          type: string
-          example: healthy
-        version:
-          type: string
-          description: "当前已部署 hooks 版本号，用于确认发布是否生效"
-          example: 2026.03.26-health-probe.1
-        timestamp:
-          type: string
-          format: date-time
-    UsersCountData:
-      type: object
-      properties:
-        total_users:
-          type: integer
-          description: "tbl_auth_users 表中的用户总数"
-          example: 128
-    HelloWorldData:
-      type: object
-      properties:
-        message:
-          type: string
-          example: Hello, World!
-        timestamp:
-          type: string
-          format: date-time
-        status:
-          type: string
-          example: success
-        build_time:
-          type:
-            - string
-            - 'null'
-          format: date-time
-    CompanyInfo:
-      anyOf:
-        - type: object
-          description: 用户所属公司信息；当用户尚未绑定公司时返回 `null`
-          properties:
-            pb_id:
-              type: string
-              description: PocketBase 记录主键 id
-            company_id:
-              type: string
-              description: 公司业务 id，由数据库自动生成
-            company_name:
-              type: string
-              description: 公司名称
-            company_type:
-              type: string
-              description: 公司类型
-            company_entity:
-              type: string
-              description: 公司法人
-            company_usci:
-              type: string
-              description: 统一社会信用代码
-            company_nationality:
-              type: string
-              description: 国家名称
-            company_nationality_code:
-              type: string
-              description: 国家编码
-            company_province:
-              type: string
-              description: 省份名称
-            company_province_code:
-              type: string
-              description: 省份编码
-            company_city:
-              type: string
-              description: 城市名称
-            company_city_code:
-              type: string
-              description: 城市编码
-            company_district:
-              type: string
-              description: 区/县名称
-            company_district_code:
-              type: string
-              description: 区/县编码
-            company_postalcode:
-              type: string
-              description: 邮政编码
-            company_add:
-              type: string
-              description: 公司地址
-            company_status:
-              type: string
-              description: 公司状态
-            company_level:
-              type: string
-              description: 公司等级
-            company_owner_openid:
-              type: string
-              description: 公司所有者 openid
-            company_remark:
-              type: string
-              description: 备注
-            created:
-              type: string
-              description: 记录创建时间
-            updated:
-              type: string
-              description: 记录更新时间
-          example:
-            pb_id: PocketBase记录主键id | 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
-            created: 记录创建时间 | string
-            updated: 记录更新时间 | string
-        - type: 'null'
-    UserInfo:
-      type: object
-      description: |
-        统一用户视图。
-        其中 `openid` 为全平台统一身份标识：微信用户使用微信 openid，平台用户使用服务端生成 GUID。
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        users_convers_id:
-          description: "会话侧用户 ID"
-          type: string
-        users_id:
-          description: "用户业务 ID"
-          type: string
-        users_idtype:
-          description: "用户身份来源类型"
-          anyOf:
-            - type: string
-              enum: [WeChat, ManagePlatform]
-            - type: string
-        users_id_number:
-          description: "证件号"
-          type: string
-        users_status:
-          description: "用户状态"
-          type: string
-        users_rank_level:
-          description: "用户星级数值"
-          type: [number, string]
-        users_auth_type:
-          description: "账户类型"
-          type: [number, string]
-        users_type:
-          description: "用户类型"
-          anyOf:
-            - type: string
-              enum: [游客, 注册用户]
-            - type: string
-        users_name:
-          description: "用户姓名 / 昵称"
-          type: string
-        users_phone:
-          description: "手机号"
-          type: string
-        users_phone_masked:
-          type: string
-        users_level:
-          type: string
-          description: "用户等级"
-        users_level_name:
-          type: string
-          description: "用户等级名称，按 `users_level -> 数据-会员等级` 字典描述实时解析"
-        users_tag:
-          type: string
-          description: "用户标签"
-        users_picture:
-          type: string
-          description: "用户头像附件的 `attachments_id`"
-        users_picture_url:
-          type: string
-          description: "根据 `users_picture -> tbl_attachments` 自动解析出的头像文件流链接"
-        users_id_pic_a:
-          type: string
-          description: "证件正面附件的 `attachments_id`"
-        users_id_pic_a_url:
-          type: string
-          description: "根据 `users_id_pic_a -> tbl_attachments` 自动解析出的文件流链接"
-        users_id_pic_b:
-          type: string
-          description: "证件反面附件的 `attachments_id`"
-        users_id_pic_b_url:
-          type: string
-          description: "根据 `users_id_pic_b -> tbl_attachments` 自动解析出的文件流链接"
-        users_title_picture:
-          type: string
-          description: "资质附件的 `attachments_id`"
-        users_title_picture_url:
-          type: string
-          description: "根据 `users_title_picture -> tbl_attachments` 自动解析出的文件流链接"
-        openid:
-          type: string
-          description: "全平台统一身份标识；微信用户为微信 openid，平台用户为服务端生成的 GUID"
-        company_id:
-          type: string
-          description: "公司业务 id，存储 `tbl_company.company_id`"
-        users_parent_id:
-          type: string
-          description: "上级用户业务 id"
-        users_promo_code:
-          type: string
-          description: "推广码"
-        usergroups_id:
-          type: string
-          description: "用户组业务 id"
-        company:
-          $ref: '#/components/schemas/CompanyInfo'
-        created:
-          type: string
-          description: "用户创建时间"
-        updated:
-          type: string
-          description: "用户更新时间"
-      example:
-        pb_id: PocketBase记录主键id | string
-        users_convers_id: 会话侧用户ID | string
-        users_id: 用户业务ID | string
-        users_idtype: 用户身份来源类型 | string
-        users_id_number: 证件号 | string
-        users_type: 用户类型 | string
-        users_name: 用户姓名或昵称 | string
-        users_status: 用户状态 | string
-        users_rank_level: 用户星级数值 | number
-        users_auth_type: 账户类型 | number
-        users_phone: 手机号 | string
-        users_phone_masked: 手机号脱敏值 | string
-        users_level: 用户等级 | string
-        users_level_name: 用户等级名称 | string
-        users_tag: 用户标签 | string
-        users_picture: 用户头像附件ID | string
-        users_picture_url: 用户头像文件流链接 | string
-        users_id_pic_a: 证件正面附件ID | string
-        users_id_pic_a_url: 证件正面文件流链接 | string
-        users_id_pic_b: 证件反面附件ID | string
-        users_id_pic_b_url: 证件反面文件流链接 | string
-        users_title_picture: 资质附件ID | string
-        users_title_picture_url: 资质附件文件流链接 | string
-        openid: 全平台统一身份标识 | string
-        company_id: 公司业务id | string
-        users_parent_id: 上级用户业务id | string
-        users_promo_code: 推广码 | string
-        usergroups_id: 用户组业务id | string
-        company:
-          pb_id: PocketBase记录主键id | 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
-          created: 记录创建时间 | string
-          updated: 记录更新时间 | string
-        created: 用户创建时间 | string
-        updated: 用户更新时间 | string
-    PocketBaseAuthResponse:
-      type: object
-      description: |
-        项目统一认证响应。
-        所有对外接口统一返回 `statusCode`、`errMsg`、`data`，认证成功时额外返回顶层 `token`。
-      properties:
-        statusCode:
-          type: integer
-          description: "业务状态码"
-          example: 200
-        errMsg:
-          type: string
-          description: "业务提示信息"
-          example: 登录成功
-        data:
-          description: "业务响应数据"
-          type: object
-          properties:
-            status:
-              anyOf:
-                - type: string
-                  enum: [register_success, login_success]
-                - type: string
-            is_info_complete:
-              type: [boolean, string]
-            user:
-              $ref: '#/components/schemas/UserInfo'
-        token:
-          type: string
-          description: "PocketBase 原生 auth token；仅认证类接口在成功时额外返回"
-      example:
-        statusCode: 200
-        errMsg: 登录成功
-        data:
-          status: 登录或注册状态 | string
-          is_info_complete: 资料是否完整 | boolean
-          user:
-            pb_id: PocketBase记录主键id | string
-            users_id: 用户业务ID | string
-            users_idtype: 用户身份来源类型 | string
-            users_name: 用户姓名或昵称 | string
-            users_phone: 手机号 | string
-            users_phone_masked: 手机号脱敏值 | string
-            users_status: 用户状态 | string
-            users_rank_level: 用户星级数值 | number
-            users_auth_type: 账户类型 | number
-            users_type: 用户类型 | string
-            users_picture: 用户头像附件ID | string
-            users_picture_url: 用户头像文件流链接 | string
-            users_id_pic_a: 证件正面附件ID | string
-            users_id_pic_a_url: 证件正面文件流链接 | string
-            users_id_pic_b: 证件反面附件ID | string
-            users_id_pic_b_url: 证件反面文件流链接 | string
-            users_title_picture: 资质附件ID | string
-            users_title_picture_url: 资质附件文件流链接 | string
-            openid: 全平台统一身份标识 | string
-            company_id: 公司业务id | string
-            users_parent_id: 上级用户业务id | string
-            users_promo_code: 推广码 | string
-            usergroups_id: 用户组业务id | string
-            company:
-              pb_id: PocketBase记录主键id | 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
-              created: 记录创建时间 | string
-              updated: 记录更新时间 | string
-            created: 用户创建时间 | string
-            updated: 用户更新时间 | string
-        token: PocketBase原生认证token | string
-    WechatLoginRequest:
-      type: object
-      required: [users_wx_code]
-      description: "微信小程序登录/注册请求体。"
-      properties:
-        users_wx_code:
-          type: string
-          description: "微信小程序登录临时凭证 code"
-          example: 0a1b2c3d4e5f6g
-    WechatProfileRequest:
-      type: object
-      description: "微信用户资料完善请求体。"
-      properties:
-        users_name:
-          type: string
-          description: "用户姓名 / 昵称"
-          example: 张三
-        users_phone_code:
-          type: string
-          description: "可选。若传入，服务端优先通过微信接口换取真实手机号并写入数据库"
-          example: 2b7d9f2e3c4a5b6d7e8f
-        users_phone:
-          type: string
-          description: "可选。未传 `users_phone_code` 时，可直接写入手机号"
-          example: '13800138000'
-        users_type:
-          type: string
-          description: "可选。用户类型；仅在传入非空值时更新"
-          example: 服务商
-        company_id:
-          type: string
-          description: "可选。公司业务 id；仅在传入非空值时更新"
-          example: WX-COMPANY-10001
-        users_tag:
-          type: string
-          description: "可选。用户标签；非空时才更新"
-          example: 核心客户
-        users_picture:
-          type: string
-          description: "可选。用户头像附件的 `attachments_id`"
-          example: ATT-1743123456789-abc123
-        users_id_pic_a:
-          type: string
-          description: "可选。证件正面附件的 `attachments_id`"
-        users_id_pic_b:
-          type: string
-          description: "可选。证件反面附件的 `attachments_id`"
-        users_title_picture:
-          type: string
-          description: "可选。资质附件的 `attachments_id`"
-    WechatProfileResponseData:
-      type: object
-      properties:
-        status:
-          type: string
-          enum: [update_success]
-        user:
-          $ref: '#/components/schemas/UserInfo'
-    PlatformRegisterRequest:
-      type: object
-      required: [users_name, users_phone, password, passwordConfirm, users_picture]
-      description: "平台用户注册请求体；注册成功后将生成 GUID 并写入统一 `openid` 字段。"
-      properties:
-        users_name:
-          type: string
-          description: "用户姓名 / 昵称"
-          example: 张三
-        users_phone:
-          type: string
-          description: "手机号"
-          example: 13800138000
-        password:
-          type: string
-          description: "PocketBase 认证密码"
-          example: 12345678
-        passwordConfirm:
-          type: string
-          example: 12345678
-        users_picture:
-          type: string
-          description: "用户头像附件的 `attachments_id`"
-          example: ATT-1743123456789-abc123
-        users_id_number:
-          description: "证件号"
-          type: string
-        users_id_pic_a:
-          type: string
-          description: "可选。证件正面附件的 `attachments_id`"
-        users_id_pic_b:
-          type: string
-          description: "可选。证件反面附件的 `attachments_id`"
-        users_title_picture:
-          type: string
-          description: "可选。资质附件的 `attachments_id`"
-        users_level:
-          description: "用户等级文本"
-          type: string
-        users_tag:
-          description: "用户标签"
-          type: string
-        users_type:
-          description: "用户类型"
-          type: string
-        company_id:
-          description: "所属公司业务 ID"
-          type: string
-        users_parent_id:
-          description: "上级用户业务 ID"
-          type: string
-        users_promo_code:
-          description: "推广码"
-          type: string
-        usergroups_id:
-          description: "用户组 / 角色 ID"
-          type: string
-    PlatformLoginRequest:
-      type: object
-      required: [login_account, password]
-      description: "平台用户登录请求体；前端使用邮箱或手机号 + 密码提交，服务端内部转换为 PocketBase 原生 password auth。"
-      properties:
-        login_account:
-          type: string
-          description: "支持邮箱或手机号"
-          example: admin@example.com
-        password:
-          type: string
-          description: "PocketBase 认证密码"
-          example: 12345678
-    SystemRefreshTokenRequest:
-      type: object
-      description: |
-        系统刷新 token 请求体。
-        `users_wx_code` 允许为空。
-        当 `Authorization` 对应 token 有效时，可不传或传空；
-        当 token 失效时，需提供 `users_wx_code` 走微信 code 重新签发流程。
-      properties:
-        users_wx_code:
-          type:
-            - string
-            - 'null'
-          description: "微信小程序登录临时凭证 code"
-          example: 0a1b2c3d4e5f6g
-    RefreshTokenData:
-      type: object
-      properties: {}
-    DictionaryItem:
-      type: object
-      required: [enum, description, sortOrder]
-      properties:
-        enum:
-          type: string
-          example: enabled
-        description:
-          type: string
-          example: 启用
-        image:
-          type: string
-          description: "对应图片附件的 `attachments_id`，允许为空"
-          example: ATT-1743037200000-abc123
-        imageUrl:
-          type: string
-          description: "根据 `image -> tbl_attachments` 自动解析出的图片文件流链接"
-        imageAttachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        sortOrder:
-          type: [integer, string]
-          example: 1
-      example:
-        enum: 枚举值 | string
-        description: 枚举描述 | string
-        image: 图片附件ID | string
-        imageUrl: 图片文件流链接 | string
-        imageAttachment:
-          attachments_id: 附件业务ID | string
-          attachments_filename: 原始文件名 | string
-        sortOrder: 排序值 | integer
-    DictionaryRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        system_dict_id:
-          description: "字典业务 ID"
-          type: string
-        dict_name:
-          description: "字典名称，当前按全局唯一维护"
-          type: string
-        dict_word_is_enabled:
-          description: "字典是否启用"
-          type: [boolean, string]
-        dict_word_parent_id:
-          description: "父级字典业务 ID"
-          type: string
-        dict_word_remark:
-          description: "备注"
-          type: string
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/DictionaryItem'
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: PocketBase记录主键id | string
-        system_dict_id: 字典业务ID | string
-        dict_name: 字典名称 | string
-        dict_word_is_enabled: 字典是否启用 | boolean
-        dict_word_parent_id: 父级字典业务ID | string
-        dict_word_remark: 备注 | string
-        items:
-          - enum: UT1
-            description: 枚举描述 | string
-            image: 图片附件ID | string
-            imageUrl: 图片文件流链接 | string
-            sortOrder: 排序值 | integer
-        created: 记录创建时间 | string
-        updated: 记录更新时间 | string
-    DictionaryListRequest:
-      type: object
-      properties:
-        keyword:
-          type: string
-          description: "对 `dict_name` 的模糊搜索关键字"
-          example: 状态
-    DictionaryDetailRequest:
-      type: object
-      required: [dict_name]
-      properties:
-        dict_name:
-          type: string
-          description: "字典名称，当前按全局唯一维护"
-          example: 用户状态
-    DictionaryMutationRequest:
-      type: object
-      required: [dict_name, items]
-      properties:
-        original_dict_name:
-          type: string
-          description: "更新时用于定位原始记录；新增时可不传"
-          example: 用户状态
-        dict_name:
-          type: string
-          description: "字典名称，当前按全局唯一维护"
-          example: 用户状态
-        dict_word_is_enabled:
-          type: boolean
-          description: "字典是否启用"
-          example: true
-        dict_word_parent_id:
-          type: string
-          description: "父级字典业务 ID"
-          example: ''
-        dict_word_remark:
-          type: string
-          description: "备注"
-          example: 系统状态字典
-        items:
-          type: array
-          minItems: 1
-          description: "每项会分别序列化写入 `dict_word_enum`、`dict_word_description`、`dict_word_image`、`dict_word_sort_order`"
-          items:
-            $ref: '#/components/schemas/DictionaryItem'
-    DictionaryDeleteRequest:
-      type: object
-      required: [dict_name]
-      properties:
-        dict_name:
-          type: string
-          description: "字典名称，当前按全局唯一维护"
-          example: 用户状态
-    AttachmentRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        attachments_id:
-          description: "附件业务 ID"
-          type: string
-        attachments_link:
-          type: string
-          description: "PocketBase 实际存储的文件名"
-        attachments_url:
-          type: string
-          description: "附件文件流访问链接"
-        attachments_download_url:
-          type: string
-          description: "附件下载链接"
-        attachments_filename:
-          description: "原始文件名"
-          type: string
-        attachments_filetype:
-          description: "文件类型 / MIME"
-          type: string
-        attachments_size:
-          description: "文件大小"
-          type: [number, string]
-        attachments_owner:
-          description: "上传者业务标识"
-          type: string
-        attachments_md5:
-          description: "文件 MD5"
-          type: string
-        attachments_ocr:
-          description: "OCR 识别结果"
-          type: string
-        attachments_status:
-          description: "附件状态"
-          type: string
-        attachments_remark:
-          description: "备注"
-          type: string
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: PocketBase记录主键id | string
-        attachments_id: 附件业务ID | string
-        attachments_link: PocketBase实际存储文件名 | string
-        attachments_url: 附件文件流访问链接 | string
-        attachments_download_url: 附件下载链接 | 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
-        created: 记录创建时间 | string
-        updated: 记录更新时间 | string
-    AttachmentListRequest:
-      type: object
-      properties:
-        keyword:
-          type: string
-          description: "对 `attachments_id`、`attachments_filename` 的模糊搜索关键字"
-          example: 手册
-        status:
-          type: string
-          description: "按附件状态过滤"
-          example: active
-    AttachmentDetailRequest:
-      type: object
-      required: [attachments_id]
-      properties:
-        attachments_id:
-          type: string
-          description: "附件业务 ID"
-          example: ATT-1743037200000-abc123
-    AttachmentUploadRequest:
-      type: object
-      required: [attachments_link]
-      properties:
-        attachments_link:
-          type: string
-          format: binary
-          description: "要上传到 `tbl_attachments` 的单个文件"
-        attachments_filename:
-          type: string
-          description: "原始文件名；不传时可由前端直接使用文件名"
-        attachments_filetype:
-          type: string
-          description: "文件 MIME 类型"
-        attachments_size:
-          type: number
-          description: "文件大小"
-        attachments_md5:
-          description: "文件 MD5"
-          type: string
-        attachments_ocr:
-          description: "OCR 识别结果"
-          type: string
-        attachments_status:
-          type: string
-          description: "附件状态"
-          example: active
-        attachments_remark:
-          description: "备注"
-          type: string
-    DocumentRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        document_id:
-          description: "文档业务 ID"
-          type: string
-        document_create:
-          type: string
-          description: "文档创建时间，由数据库自动生成"
-        document_effect_date:
-          description: "文档生效日期"
-          type: string
-        document_expiry_date:
-          description: "文档到期日期"
-          type: string
-        document_type:
-          type: string
-          description: "多选时按 `system_dict_id@dict_word_enum|...` 保存"
-        document_title:
-          description: "文档标题"
-          type: string
-        document_subtitle:
-          description: "文档副标题"
-          type: string
-        document_summary:
-          description: "文档摘要"
-          type: string
-        document_content:
-          description: "正文内容，保存 Markdown"
-          type: string
-        document_image:
-          type: string
-          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
-        document_image_ids:
-          type: array
-          description: "`document_image` 解析后的附件 id 列表"
-          items:
-            type: string
-        document_image_urls:
-          type: array
-          description: "根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接列表"
-          items:
-            type: string
-        document_image_url:
-          type: string
-          description: "兼容字段，返回第一张图片的文件流链接"
-        document_image_attachments:
-          type: array
-          items:
-            $ref: '#/components/schemas/AttachmentRecord'
-        document_image_attachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        document_video:
-          type: string
-          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
-        document_video_ids:
-          type: array
-          description: "`document_video` 解析后的附件 id 列表"
-          items:
-            type: string
-        document_video_urls:
-          type: array
-          description: "根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接列表"
-          items:
-            type: string
-        document_video_url:
-          type: string
-          description: "兼容字段，返回第一个视频的文件流链接"
-        document_video_attachments:
-          type: array
-          items:
-            $ref: '#/components/schemas/AttachmentRecord'
-        document_video_attachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        document_file:
-          type: string
-          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
-        document_file_ids:
-          type: array
-          description: "`document_file` 解析后的附件 id 列表"
-          items:
-            type: string
-        document_file_urls:
-          type: array
-          description: "根据 `document_file -> tbl_attachments` 自动解析出的文件流链接列表"
-          items:
-            type: string
-        document_file_url:
-          type: string
-          description: "兼容字段，返回第一个文件的文件流链接"
-        document_file_attachments:
-          type: array
-          items:
-            $ref: '#/components/schemas/AttachmentRecord'
-        document_file_attachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        document_owner:
-          type: string
-          description: "上传者 openid"
-        document_relation_model:
-          description: "关联机型 / 模型标识"
-          type: string
-        document_keywords:
-          type: string
-          description: "固定字典多选字段，使用 `|` 分隔"
-        document_share_count:
-          description: "分享次数"
-          type: [number, string]
-        document_download_count:
-          description: "下载次数"
-          type: [number, string]
-        document_favorite_count:
-          description: "收藏次数"
-          type: [number, string]
-        document_status:
-          type: string
-          description: "文档状态，仅允许 `有效` 或 `过期`，由系统根据生效日期和到期日期自动计算；当两者都为空时默认 `有效`"
-        document_embedding_status:
-          description: "文档嵌入状态"
-          type: string
-        document_embedding_error:
-          description: "文档嵌入错误原因"
-          type: string
-        document_embedding_lasttime:
-          description: "最后一次嵌入更新时间"
-          type: string
-        document_vector_version:
-          description: "向量版本号 / 模型名称"
-          type: string
-        document_product_categories:
-          type: string
-          description: "固定字典多选字段，使用 `|` 分隔"
-        document_application_scenarios:
-          type: string
-          description: "固定字典多选字段，使用 `|` 分隔"
-        document_hotel_type:
-          type: string
-          description: "固定字典多选字段，使用 `|` 分隔"
-        document_remark:
-          description: "备注"
-          type: string
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: PocketBase记录主键id | string
-        document_id: 文档业务ID | string
-        document_create: 文档创建时间，由数据库自动生成 | string
-        document_effect_date: 文档生效日期 | string
-        document_expiry_date: 文档到期日期 | string
-        document_type: 文档类型，按system_dict_id@dict_word_enum保存 | string
-        document_title: 文档标题 | string
-        document_subtitle: 文档副标题 | string
-        document_summary: 文档摘要 | string
-        document_content: 正文内容Markdown | string
-        document_image: 图片附件ID列表，使用竖线分隔 | string
-        document_image_ids:
-          - 图片附件ID | string
-        document_image_urls:
-          - 图片文件流链接 | string
-        document_image_url: 第一张图片文件流链接 | string
-        document_video: 视频附件ID列表，使用竖线分隔 | string
-        document_video_ids:
-          - 视频附件ID | string
-        document_video_urls:
-          - 视频文件流链接 | string
-        document_video_url: 第一个视频文件流链接 | string
-        document_file: 文件附件ID列表，使用竖线分隔 | string
-        document_file_ids:
-          - 文件附件ID | string
-        document_file_urls:
-          - 文件流链接 | string
-        document_file_url: 第一个文件流链接 | string
-        document_owner: 上传者openid | string
-        document_relation_model: 关联机型或模型标识 | string
-        document_keywords: 关键词多选，使用竖线分隔 | string
-        document_share_count: 分享次数 | number
-        document_download_count: 下载次数 | number
-        document_favorite_count: 收藏次数 | number
-        document_status: 文档状态 | string
-        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
-        created: 记录创建时间 | string
-        updated: 记录更新时间 | string
-    DocumentListRequest:
-      type: object
-      properties:
-        keyword:
-          type: string
-          description: "对 `document_id`、`document_title`、`document_subtitle`、`document_summary`、`document_keywords` 的模糊搜索关键字"
-          example: 安装
-        status:
-          type: string
-          example: active
-        document_type:
-          type: string
-          description: "支持按存储值过滤；多选时格式为 `system_dict_id@dict_word_enum|...`"
-          example: 说明书
-    DocumentDetailRequest:
-      type: object
-      required: [document_id]
-      properties:
-        document_id:
-          type: string
-          description: "文档业务 ID"
-          example: DOC-1743037200000-abc123
-    DocumentMutationRequest:
-      type: object
-      required: [document_title, document_type]
-      properties:
-        document_id:
-          type: string
-          description: "创建时可不传，由服务端自动生成；更新时必填"
-          example: DOC-1743037200000-abc123
-        document_effect_date:
-          type: string
-          description: "支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串"
-          example: 2026-03-27
-        document_expiry_date:
-          type: string
-          description: "支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串"
-          example: 2027-03-27
-        document_type:
-          type: string
-          description: "必填；前端显示为字典项描述，存库时按 `system_dict_id@dict_word_enum|...` 保存"
-        document_title:
-          description: "文档标题"
-          type: string
-        document_subtitle:
-          description: "文档副标题"
-          type: string
-        document_summary:
-          description: "文档摘要"
-          type: string
-        document_content:
-          description: "正文内容，保存 Markdown"
-          type: string
-        document_image:
-          oneOf:
-            - type: string
-              description: "多个图片附件 id 使用 `|` 分隔"
-            - type: array
-              items:
-                type: string
-          description: "图片附件 id 列表；支持数组或 `|` 分隔字符串"
-        document_video:
-          oneOf:
-            - type: string
-              description: "多个视频附件 id 使用 `|` 分隔"
-            - type: array
-              items:
-                type: string
-          description: "视频附件 id 列表；支持数组或 `|` 分隔字符串"
-        document_file:
-          oneOf:
-            - type: string
-              description: "多个文件附件 id 使用 `|` 分隔"
-            - type: array
-              items:
-                type: string
-          description: "文件附件 id 列表；支持数组或 `|` 分隔字符串"
-        document_relation_model:
-          description: "关联机型 / 模型标识"
-          type: string
-        document_keywords:
-          type: string
-          description: "从 `文档-关键词` 字典多选后使用 `|` 分隔保存"
-        document_share_count:
-          description: "分享次数"
-          type: number
-        document_download_count:
-          description: "下载次数"
-          type: number
-        document_favorite_count:
-          description: "收藏次数"
-          type: number
-        document_status:
-          type: string
-          description: "文档状态，仅允许 `有效` 或 `过期`，由系统根据生效日期和到期日期自动计算；当两者都为空时默认 `有效`"
-        document_embedding_status:
-          description: "文档嵌入状态"
-          type: string
-        document_embedding_error:
-          description: "文档嵌入错误原因"
-          type: string
-        document_embedding_lasttime:
-          description: "最后一次嵌入更新时间"
-          type: string
-        document_vector_version:
-          description: "向量版本号 / 模型名称"
-          type: string
-        document_product_categories:
-          type: string
-          description: "从 `文档-产品关联文档` 字典多选后使用 `|` 分隔保存"
-        document_application_scenarios:
-          type: string
-          description: "从 `文档-筛选依据` 字典多选后使用 `|` 分隔保存"
-        document_hotel_type:
-          type: string
-          description: "从 `文档-适用场景` 字典多选后使用 `|` 分隔保存"
-        document_remark:
-          description: "备注"
-          type: string
-    DocumentDeleteRequest:
-      type: object
-      required: [document_id]
-      properties:
-        document_id:
-          type: string
-          description: "文档业务 ID"
-          example: DOC-1743037200000-abc123
-    DocumentHistoryRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        doh_id:
-          description: "文档操作历史业务 ID"
-          type: string
-        doh_document_id:
-          description: "关联文档业务 ID"
-          type: string
-        doh_operation_type:
-          description: "操作类型"
-          type: string
-        doh_user_id:
-          description: "操作人业务 ID"
-          type: string
-        doh_current_count:
-          description: "本次操作对应次数"
-          type: [number, string]
-        doh_remark:
-          description: "备注"
-          type: string
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: PocketBase记录主键id | string
-        doh_id: 文档操作历史业务ID | string
-        doh_document_id: 关联文档业务ID | string
-        doh_operation_type: 操作类型 | string
-        doh_user_id: 操作人业务ID | string
-        doh_current_count: 本次操作对应次数 | number
-        doh_remark: 备注 | string
-        created: 记录创建时间 | string
-        updated: 记录更新时间 | string
-    DocumentHistoryListRequest:
-      type: object
-      properties:
-        document_id:
-          type: string
-          description: "可选；传入时仅查询指定文档的操作历史"
-          example: DOC-1743037200000-abc123
-paths:
-  /pb/api/system/test-helloworld:
-    post:
-      tags: [系统]
-      summary: HelloWorld 测试接口
-      responses:
-        '200':
-          description: "成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/HelloWorldData'
-  /pb/api/system/health:
-    post:
-      tags: [系统]
-      summary: 健康检查
-      responses:
-        '200':
-          description: "成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/HealthData'
-  /pb/api/system/users-count:
-    post:
-      tags: [系统]
-      summary: 查询用户总数
-      description: "统计 `tbl_auth_users` 集合中的记录总数，并返回一个数值。"
-      responses:
-        '200':
-          description: "成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/UsersCountData'
-  /pb/api/platform/register:
-    post:
-      tags: [平台认证]
-      summary: 平台用户注册
-      description: |
-        创建平台用户 auth record。
-        服务端会自动生成 GUID 并写入统一身份字段 `openid`，同时写入 `users_idtype = ManagePlatform`。
-        前端以 `users_phone + password/passwordConfirm` 注册，但服务端仍会创建 PocketBase 原生 auth 用户。
-        首次注册创建时，`users_level` 默认保持为空，不自动写入会员等级。
-        注册成功后直接返回 PocketBase 原生 auth token。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PlatformRegisterRequest'
-      responses:
-        '200':
-          description: "注册成功"
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseAuthResponse'
-        '400':
-          description: "参数错误或手机号已存在"
-        '500':
-          description: "GUID 生成失败、auth identity 缺失或保存用户失败"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/platform/login:
-    post:
-      tags: [平台认证]
-      summary: 平台用户登录
-      description: |
-        前端使用平台注册时保存的 `邮箱或手机号 + password` 登录。
-        仅允许 `users_idtype = ManagePlatform` 的用户通过该接口登录。
-        服务端会根据 `login_account` 自动判断邮箱或手机号，并定位平台用户，再使用该用户的 PocketBase 原生 identity（当前为 `email`）执行原生 password auth。
-        返回体中的 `user.users_level_name` 为服务端按“数据-会员等级”字典实时解析后的等级名称。
-        登录成功后直接返回 PocketBase 原生 auth token。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PlatformLoginRequest'
-            example:
-              login_account: 13509214696
-              password: Momo123456
-      responses:
-        '200':
-          description: "登录成功"
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseAuthResponse'
-              example:
-                statusCode: 200
-                errMsg: 登录成功
-                data:
-                  status: login_success
-                  is_info_complete: false
-                  user:
-                    pb_id: vtukf6agem2xbcv
-                    users_id: ''
-                    users_idtype: ManagePlatform
-                    users_name: momo
-                    users_phone: '13509214696'
-                    users_phone_masked: '135****4696'
-                    users_status: ''
-                    users_rank_level: 0
-                    users_auth_type: 0
-                    users_type: ''
-                    users_picture: ''
-                    openid: app_momo
-                    company_id: ''
-                    users_parent_id: ''
-                    users_promo_code: ''
-                    usergroups_id: ''
-                    company: null
-                    created: ''
-                    updated: ''
-                token: eyJhbGciOi...
-        '400':
-          description: "参数错误、密码错误或用户类型不匹配"
-        '404':
-          description: "平台用户不存在"
-        '500':
-          description: "平台用户缺少原生登录 identity 或服务端内部错误"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/dictionary/list:
-    post:
-      tags: [字典管理]
-      summary: 查询字典列表
-      description: |
-        公开读接口，无需 token。
-        支持按 `dict_name` 模糊搜索，返回字典全量信息，并将三个聚合字段组装为 `items`。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryListRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/DictionaryRecord'
-        '415':
-          description: "请求体必须为 application/json"
-  /pb/api/dictionary/detail:
-    post:
-      tags: [字典管理]
-      summary: 查询指定字典
-      description: |
-        公开读接口，无需 token。
-        按唯一键 `dict_name` 查询单条字典，并返回组装后的 `items`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryDetailRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DictionaryRecord'
-        '400':
-          description: "参数错误"
-        '404':
-          description: "未找到对应字典"
-        '415':
-          description: "请求体必须为 application/json"
-  /pb/api/dictionary/create:
-    post:
-      tags: [字典管理]
-      summary: 新增字典
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        `system_dict_id` 由服务端自动生成；`dict_name` 必须唯一；
-        `items` 会分别序列化写入 `dict_word_enum`、`dict_word_description`、`dict_word_image`、`dict_word_sort_order` 四个字段。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryMutationRequest'
-      responses:
-        '200':
-          description: "新增成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DictionaryRecord'
-        '400':
-          description: "参数错误或 dict_name 已存在"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/dictionary/update:
-    post:
-      tags: [字典管理]
-      summary: 修改字典
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        根据 `original_dict_name`（未传时回退为 `dict_name`）定位原记录并更新。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryMutationRequest'
-      responses:
-        '200':
-          description: "修改成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DictionaryRecord'
-        '400':
-          description: "参数错误或 dict_name 冲突"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到待修改字典"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/dictionary/delete:
-    post:
-      tags: [字典管理]
-      summary: 删除字典
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `dict_name` 真删除对应记录。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryDeleteRequest'
-      responses:
-        '200':
-          description: "删除成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  dict_name:
-                    description: "字典名称，当前按全局唯一维护"
-                    type: string
-        '400':
-          description: "参数错误或删除失败"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到待删除字典"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/attachment/list:
-    post:
-      tags: [附件管理]
-      summary: 查询附件列表
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        支持按 `attachments_id`、`attachments_filename` 模糊搜索，并可按 `attachments_status` 过滤。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AttachmentListRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/AttachmentRecord'
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '415':
-          description: "请求体必须为 application/json"
-  /pb/api/attachment/detail:
-    post:
-      tags: [附件管理]
-      summary: 查询附件详情
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `attachments_id` 查询单条附件，并返回 PocketBase 文件流链接与下载链接。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AttachmentDetailRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/AttachmentRecord'
-        '400':
-          description: "参数错误"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到对应附件"
-        '415':
-          description: "请求体必须为 application/json"
-  /pb/api/attachment/upload:
-    post:
-      tags: [附件管理]
-      summary: 上传附件
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        使用 `multipart/form-data` 上传单个文件到 `tbl_attachments`，服务端会自动生成 `attachments_id`，
-        并返回可直接访问的 PocketBase 文件流链接。
-      requestBody:
-        required: true
-        content:
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/AttachmentUploadRequest'
-      responses:
-        '200':
-          description: "上传成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/AttachmentRecord'
-        '400':
-          description: "参数错误、缺少文件或附件保存失败"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-  /pb/api/attachment/delete:
-    post:
-      tags: [附件管理]
-      summary: 删除附件
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image`、`document_video` 或 `document_file` 引用，则拒绝删除。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AttachmentDetailRequest'
-      responses:
-        '200':
-          description: "删除成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  attachments_id:
-                    description: "附件业务 ID"
-                    type: string
-        '400':
-          description: "参数错误、附件已被文档引用或删除失败"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到待删除附件"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/document/list:
-    post:
-      tags: [文档管理]
-      summary: 查询文档列表
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
-        返回结果会自动根据 `document_image`、`document_video`、`document_file` 中的多个 `attachments_id` 关联 `tbl_attachments`，
-        额外补充 `document_image_urls`、`document_video_urls`、`document_file_urls` 以及对应附件对象数组。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentListRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/DocumentRecord'
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '415':
-          description: "请求体必须为 application/json"
-  /pb/api/document/detail:
-    post:
-      tags: [文档管理]
-      summary: 查询文档详情
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `document_id` 查询单条文档，并返回与附件表联动解析后的多文件流链接。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentDetailRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DocumentRecord'
-        '400':
-          description: "参数错误"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到对应文档"
-        '415':
-          description: "请求体必须为 application/json"
-  /pb/api/document/create:
-    post:
-      tags: [文档管理]
-      summary: 新增文档
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        `document_id` 可选；未传时服务端自动生成。
-        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        `document_image`、`document_video`、`document_file` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
-        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentMutationRequest'
-      responses:
-        '200':
-          description: "新增成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DocumentRecord'
-        '400':
-          description: "参数错误、附件不存在或文档创建失败"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/document/update:
-    post:
-      tags: [文档管理]
-      summary: 修改文档
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `document_id` 定位现有文档并更新。
-        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        若传入 `document_image`、`document_video`、`document_file`，则支持多个 `attachments_id`，并会逐一校验是否存在。
-        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentMutationRequest'
-      responses:
-        '200':
-          description: "修改成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DocumentRecord'
-        '400':
-          description: "参数错误、附件不存在或修改失败"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到待修改文档"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/document/delete:
-    post:
-      tags: [文档管理]
-      summary: 删除文档
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `document_id` 真删除文档，并在删除前同步写入一条 `tbl_document_operation_history`，操作类型为 `delete`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentDeleteRequest'
-      responses:
-        '200':
-          description: "删除成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  document_id:
-                    description: "文档业务 ID"
-                    type: string
-        '400':
-          description: "参数错误或删除失败"
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '404':
-          description: "未找到待删除文档"
-        '415':
-          description: "请求体必须为 application/json"
-        '429':
-          description: "重复请求过于频繁"
-  /pb/api/document-history/list:
-    post:
-      tags: [文档历史]
-      summary: 查询文档操作历史
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        若 body 传入 `document_id`，则仅查询该文档的历史；否则返回全部文档操作历史，按创建时间倒序排列。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentHistoryListRequest'
-      responses:
-        '200':
-          description: "查询成功"
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/DocumentHistoryRecord'
-        '401':
-          description: "token 无效或已过期"
-        '403':
-          description: "非 ManagePlatform 用户无权访问"
-        '415':
-          description: "请求体必须为 application/json"
diff --git a/pocket-base/spec/openapi-manage/cart.yaml b/pocket-base/spec/openapi-manage/cart.yaml
index 49a82ab..966410f 100644
--- a/pocket-base/spec/openapi-manage/cart.yaml
+++ b/pocket-base/spec/openapi-manage/cart.yaml
@@ -1,5 +1,17 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Manage Hooks API - Cart
+  version: 1.0.0
+  description: |
+    hooks 购物车接口文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
 paths:
-  cartList:
+  /pb/api/cart/list:
     post:
       tags: [购物车]
       summary: 查询购物车列表
@@ -31,7 +43,7 @@ paths:
           description: 请求体必须为 application/json
         '500':
           description: 服务端错误
-  cartDetail:
+  /pb/api/cart/detail:
     post:
       tags: [购物车]
       summary: 查询购物车详情
@@ -65,7 +77,7 @@ paths:
           description: 请求体必须为 application/json
         '500':
           description: 服务端错误
-  cartCreate:
+  /pb/api/cart/create:
     post:
       tags: [购物车]
       summary: 新增购物车记录
@@ -102,7 +114,7 @@ paths:
           description: 重复请求过于频繁
         '500':
           description: 服务端错误
-  cartUpdate:
+  /pb/api/cart/update:
     post:
       tags: [购物车]
       summary: 修改购物车记录
@@ -144,7 +156,7 @@ paths:
           description: 重复请求过于频繁
         '500':
           description: 服务端错误
-  cartDelete:
+  /pb/api/cart/delete:
     post:
       tags: [购物车]
       summary: 删除购物车记录
@@ -233,6 +245,9 @@ components:
         product_modelnumber:
           type: string
           description: 产品型号
+        product_barcode:
+          type: string
+          description: 产品料号
         product_basic_price:
           type: [integer, number, 'null']
           description: 产品基础价格
@@ -253,6 +268,7 @@ components:
         is_delete: 删除标记|integer
         product_name: 产品名称|string
         product_modelnumber: 产品型号|string
+        product_barcode: 产品料号|string
         product_basic_price: 产品基础价格|integer
     CartListRequest:
       type: object
@@ -360,6 +376,10 @@ components:
             cart_status: 购物车状态|string
             cart_at_price: 加入购物车时价格|integer
             cart_remark: 备注|string
+            product_name: 产品名称|string
+            product_modelnumber: 产品型号|string
+            product_barcode: 产品料号|string
+            product_basic_price: 产品基础价格|integer
     CartDeleteResponse:
       type: object
       properties:
diff --git a/pocket-base/spec/openapi-manage/openapi.yaml b/pocket-base/spec/openapi-manage/openapi.yaml
index a55d92e..402f96a 100644
--- a/pocket-base/spec/openapi-manage/openapi.yaml
+++ b/pocket-base/spec/openapi-manage/openapi.yaml
@@ -6,6 +6,8 @@ info:
     面向管理端与自定义 hooks 的接口文档。
     本目录仅收敛自定义 hooks API，不包含 PocketBase 原生 records API。
 
+    本文件为目录索引，支持单文件独立导入，不依赖其他 YAML。
+
     文档约定：
     - 不单独配置鉴权组件；如接口需要登录，请直接在说明中关注 `Authorization: Bearer <token>`
     - 示例字段值统一使用 `<字段说明>|<类型>` 风格
@@ -34,70 +36,8 @@ tags:
     description: hooks 购物车接口
   - name: 订单
     description: hooks 订单接口
-paths:
-  /pb/api/system/test-helloworld:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1system~1test-helloworld'
-  /pb/api/system/health:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1system~1health'
-  /pb/api/system/users-count:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1system~1users-count'
-  /pb/api/system/refresh-token:
-    $ref: '../openapi.yaml#/paths/~1pb~1api~1system~1refresh-token'
-  /pb/api/wechat/login:
-    $ref: '../openapi.yaml#/paths/~1pb~1api~1wechat~1login'
-  /pb/api/wechat/profile:
-    $ref: '../openapi.yaml#/paths/~1pb~1api~1wechat~1profile'
-  /pb/api/platform/register:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1platform~1register'
-  /pb/api/platform/login:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1platform~1login'
-  /pb/api/dictionary/list:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1list'
-  /pb/api/dictionary/detail:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1detail'
-  /pb/api/dictionary/create:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1create'
-  /pb/api/dictionary/update:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1update'
-  /pb/api/dictionary/delete:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1dictionary~1delete'
-  /pb/api/attachment/list:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1list'
-  /pb/api/attachment/detail:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1detail'
-  /pb/api/attachment/upload:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1upload'
-  /pb/api/attachment/delete:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1attachment~1delete'
-  /pb/api/document/list:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1list'
-  /pb/api/document/detail:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1detail'
-  /pb/api/document/create:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1create'
-  /pb/api/document/update:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1update'
-  /pb/api/document/delete:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document~1delete'
-  /pb/api/document-history/list:
-    $ref: '../openapi-manage.yaml#/paths/~1pb~1api~1document-history~1list'
-  /pb/api/cart/list:
-    $ref: './cart.yaml#/paths/cartList'
-  /pb/api/cart/detail:
-    $ref: './cart.yaml#/paths/cartDetail'
-  /pb/api/cart/create:
-    $ref: './cart.yaml#/paths/cartCreate'
-  /pb/api/cart/update:
-    $ref: './cart.yaml#/paths/cartUpdate'
-  /pb/api/cart/delete:
-    $ref: './cart.yaml#/paths/cartDelete'
-  /pb/api/order/list:
-    $ref: './order.yaml#/paths/orderList'
-  /pb/api/order/detail:
-    $ref: './order.yaml#/paths/orderDetail'
-  /pb/api/order/create:
-    $ref: './order.yaml#/paths/orderCreate'
-  /pb/api/order/update:
-    $ref: './order.yaml#/paths/orderUpdate'
-  /pb/api/order/delete:
-    $ref: './order.yaml#/paths/orderDelete'
\ No newline at end of file
+paths: {}
+x-index:
+  files:
+    - cart.yaml
+    - order.yaml
\ No newline at end of file
diff --git a/pocket-base/spec/openapi-manage/order.yaml b/pocket-base/spec/openapi-manage/order.yaml
index 6656aca..0b33d98 100644
--- a/pocket-base/spec/openapi-manage/order.yaml
+++ b/pocket-base/spec/openapi-manage/order.yaml
@@ -1,5 +1,17 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Manage Hooks API - Order
+  version: 1.0.0
+  description: |
+    hooks 订单接口文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
 paths:
-  orderList:
+  /pb/api/order/list:
     post:
       tags: [订单]
       summary: 查询订单列表
@@ -31,7 +43,7 @@ paths:
           description: 请求体必须为 application/json
         '500':
           description: 服务端错误
-  orderDetail:
+  /pb/api/order/detail:
     post:
       tags: [订单]
       summary: 查询订单详情
@@ -65,7 +77,7 @@ paths:
           description: 请求体必须为 application/json
         '500':
           description: 服务端错误
-  orderCreate:
+  /pb/api/order/create:
     post:
       tags: [订单]
       summary: 新增订单记录
@@ -104,7 +116,7 @@ paths:
           description: 重复请求过于频繁
         '500':
           description: 服务端错误
-  orderUpdate:
+  /pb/api/order/update:
     post:
       tags: [订单]
       summary: 修改订单记录
@@ -148,7 +160,7 @@ paths:
           description: 重复请求过于频繁
         '500':
           description: 服务端错误
-  orderDelete:
+  /pb/api/order/delete:
     post:
       tags: [订单]
       summary: 删除订单记录
diff --git a/pocket-base/spec/openapi-miniapp-company.yaml b/pocket-base/spec/openapi-miniapp-company.yaml
deleted file mode 100644
index cdd584c..0000000
--- a/pocket-base/spec/openapi-miniapp-company.yaml
+++ /dev/null
@@ -1,571 +0,0 @@
-openapi: 3.1.0
-info:
-  title: PocketBase MiniApp Company API
-  version: 1.0.0
-  summary: 小程序端通过 PocketBase JS SDK 直连 tbl_company 的基础 CRUD 文档
-  description: >-
-    本文档面向小程序端直接使用 PocketBase JS SDK / REST API 访问 `tbl_company`。
-    本文档统一以 PocketBase 原生记录主键 `id` 作为唯一识别键。
-    `company_id` 保留为普通业务字段，可用于展示、筛选和业务关联，但不再作为 CRUD 的唯一键。
-    当前线上 `tbl_company` 还包含 `company_owner_openid` 字段，用于保存公司所有者 openid，并带普通索引。
-    同时新增了国家、省、市、区的名称与编码字段，便于前端直接按行政区划存取。
-  license:
-    name: Proprietary
-    identifier: LicenseRef-Proprietary
-servers:
-  - url: https://bai-api.blv-oa.com/pb
-    description: 线上 PocketBase 服务
-tags:
-  - name: Company
-    description: tbl_company 公司信息基础 CRUD
-paths:
-  /api/collections/tbl_company/records:
-    get:
-      tags: [Company]
-      operationId: listCompanyRecords
-      summary: 查询公司列表
-      description: >-
-        使用 PocketBase 原生 records list/search 接口查询 `tbl_company`。
-        支持三种常见模式：
-        1. 全表查询：不传 `filter`；
-        2. 精确查询：`filter=id="q1w2e3r4t5y6u7i"`；
-        3. 模糊查询：`filter=(company_name~"华住" || company_usci~"9131" || company_entity~"张三")`；
-        4. 按 `company_id` 查询单条：`filter=company_id="WX-COMPANY-10001"&perPage=1&page=1`。
-      parameters:
-        - $ref: '#/components/parameters/Page'
-        - $ref: '#/components/parameters/PerPage'
-        - $ref: '#/components/parameters/Sort'
-        - $ref: '#/components/parameters/Filter'
-        - $ref: '#/components/parameters/Fields'
-        - $ref: '#/components/parameters/SkipTotal'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyListResponse'
-              examples:
-                all:
-                  summary: 全表查询
-                  value:
-                    page: 1
-                    perPage: 30
-                    totalItems: 2
-                    totalPages: 1
-                    items:
-                      - id: q1w2e3r4t5y6u7i
-                        collectionId: pbc_company_demo
-                        collectionName: tbl_company
-                        created: '2026-03-27 10:00:00.000Z'
-                        updated: '2026-03-27 10:00:00.000Z'
-                        company_id: C10001
-                        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: ''
-                exact:
-                  summary: 按 id 精确查询
-                  value:
-                    page: 1
-                    perPage: 1
-                    totalItems: 1
-                    totalPages: 1
-                    items:
-                      - id: q1w2e3r4t5y6u7i
-                        collectionId: pbc_company_demo
-                        collectionName: tbl_company
-                        created: '2026-03-27 10:00:00.000Z'
-                        updated: '2026-03-27 10:00:00.000Z'
-                        company_id: C10001
-                        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: ''
-        '400':
-          description: 过滤表达式或查询参数不合法
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '403':
-          description: 当前调用方没有 list 权限
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-    post:
-      tags: [Company]
-      operationId: createCompanyRecord
-      summary: 新增公司
-      description: >-
-        创建一条 `tbl_company` 记录。当前文档以 `id` 作为记录唯一识别键，
-        新建成功后由 PocketBase 自动生成 `id`；`company_id` 也由数据库自动生成，
-        客户端创建时不需要传入，但仍可作为后续业务查询字段。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CompanyCreateRequest'
-            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: '#/components/schemas/CompanyRecord'
-        '400':
-          description: 校验失败，例如字段类型不合法或违反当前集合约束
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '403':
-          description: 当前调用方没有 create 权限
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '404':
-          description: 集合不存在
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-  /api/collections/tbl_company/records/{recordId}:
-    get:
-      tags: [Company]
-      operationId: getCompanyRecordByRecordId
-      summary: 按 PocketBase 记录 id 查询公司
-      description: >-
-        这是 PocketBase 原生单条查询接口，路径参数必须传记录主键 `id`。
-      parameters:
-        - $ref: '#/components/parameters/RecordId'
-        - $ref: '#/components/parameters/Fields'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyRecord'
-        '403':
-          description: 当前调用方没有 view 权限
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '404':
-          description: 记录不存在
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-    patch:
-      tags: [Company]
-      operationId: updateCompanyRecordByRecordId
-      summary: 按 PocketBase 记录 id 更新公司
-      description: >-
-        这是 PocketBase 原生更新接口，路径参数统一使用记录主键 `id`。
-        如果业务侧只有 `company_id`，标准流程是先调用 list 接口
-        `filter=company_id="..."&perPage=1&page=1` 查出对应记录，再用返回的 `id` 调用本接口。
-      parameters:
-        - $ref: '#/components/parameters/RecordId'
-        - $ref: '#/components/parameters/Fields'
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CompanyUpdateRequest'
-            examples:
-              default:
-                value:
-                  company_name: 宝镜科技（更新）
-                  company_status: 有效
-                  company_level: S
-                  company_owner_openid: wx-openid-owner-002
-                  company_remark: 已更新基础资料
-      responses:
-        '200':
-          description: 更新成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyRecord'
-        '400':
-          description: 更新参数不合法
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '403':
-          description: 当前调用方没有 update 权限
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '404':
-          description: 记录不存在
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-    delete:
-      tags: [Company]
-      operationId: deleteCompanyRecordByRecordId
-      summary: 按 PocketBase 记录 id 删除公司
-      description: >-
-        这是 PocketBase 原生删除接口，路径参数统一使用记录主键 `id`。
-      parameters:
-        - $ref: '#/components/parameters/RecordId'
-      responses:
-        '204':
-          description: 删除成功
-        '400':
-          description: 删除失败，例如仍被必填 relation 引用
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '403':
-          description: 当前调用方没有 delete 权限
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-        '404':
-          description: 记录不存在
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseError'
-components:
-  parameters:
-    Page:
-      name: page
-      in: query
-      description: 页码，默认 1
-      schema:
-        type: integer
-        minimum: 1
-        default: 1
-    PerPage:
-      name: perPage
-      in: query
-      description: 每页返回条数，默认 30
-      schema:
-        type: integer
-        minimum: 1
-        default: 30
-    Sort:
-      name: sort
-      in: query
-      description: 排序字段，例如 `-created,+company_name`
-      schema:
-        type: string
-    Filter:
-      name: filter
-      in: query
-      description: >-
-        PocketBase 过滤表达式。
-        精确查询示例：`id="q1w2e3r4t5y6u7i"`；
-        模糊查询示例：`(company_name~"宝镜" || company_usci~"9131" || company_entity~"张三")`
-      schema:
-        type: string
-    Fields:
-      name: fields
-      in: query
-      description: 逗号分隔的返回字段列表，例如 `id,company_id,company_name`
-      schema:
-        type: string
-    SkipTotal:
-      name: skipTotal
-      in: query
-      description: 是否跳过 totalItems/totalPages 统计
-      schema:
-        type: boolean
-        default: false
-    RecordId:
-      name: recordId
-      in: path
-      required: true
-      description: PocketBase 记录主键 id
-      schema:
-        type: string
-  schemas:
-    CompanyBase:
-      type: object
-      properties:
-        company_id:
-          type: string
-          description: 公司业务编号字段，不再作为 CRUD 唯一键
-        company_name:
-          type: string
-          description: 公司名称
-        company_type:
-          type: string
-          description: 公司类型
-        company_entity:
-          type: string
-          description: 公司法人
-        company_usci:
-          type: string
-          description: 统一社会信用代码
-        company_nationality:
-          type: string
-          description: 国家
-        company_nationality_code:
-          type: string
-          description: 国家编码
-        company_province:
-          type: string
-          description: 省份
-        company_province_code:
-          type: string
-          description: 省份编码
-        company_city:
-          type: string
-          description: 城市
-        company_city_code:
-          type: string
-          description: 城市编码
-        company_district:
-          type: string
-          description: 区/县
-        company_district_code:
-          type: string
-          description: 区/县编码
-        company_postalcode:
-          type: string
-          description: 邮编
-        company_add:
-          type: string
-          description: 地址
-        company_status:
-          type: string
-          description: 公司状态
-        company_level:
-          type: string
-          description: 公司等级
-        company_owner_openid:
-          type: string
-          description: 公司所有者 openid
-        company_remark:
-          type: string
-          description: 备注
-    CompanyCreateRequest:
-      type: object
-      description: 创建时不需要传 `company_id`，由数据库自动生成。
-      properties:
-        company_name:
-          description: "公司名称"
-          type: string
-        company_type:
-          description: "公司类型"
-          type: string
-        company_entity:
-          description: "公司法人"
-          type: string
-        company_usci:
-          description: "统一社会信用代码"
-          type: string
-        company_nationality:
-          description: "国家名称"
-          type: string
-        company_nationality_code:
-          description: "国家编码"
-          type: string
-        company_province:
-          description: "省份名称"
-          type: string
-        company_province_code:
-          description: "省份编码"
-          type: string
-        company_city:
-          description: "城市名称"
-          type: string
-        company_city_code:
-          description: "城市编码"
-          type: string
-        company_district:
-          description: "区 / 县名称"
-          type: string
-        company_district_code:
-          description: "区 / 县编码"
-          type: string
-        company_postalcode:
-          description: "邮编"
-          type: string
-        company_add:
-          description: "地址"
-          type: string
-        company_status:
-          description: "公司状态"
-          type: string
-        company_level:
-          description: "公司等级"
-          type: string
-        company_owner_openid:
-          description: "公司所有者 openid"
-          type: string
-        company_remark:
-          description: "备注"
-          type: string
-      additionalProperties: false
-    CompanyUpdateRequest:
-      type: object
-      description: >-
-        更新时可只传需要修改的字段；记录定位统一依赖路径参数 `id`。
-      properties:
-        company_id:
-          description: "所属公司业务 ID"
-          type: string
-        company_name:
-          description: "公司名称"
-          type: string
-        company_type:
-          description: "公司类型"
-          type: string
-        company_entity:
-          description: "公司法人"
-          type: string
-        company_usci:
-          description: "统一社会信用代码"
-          type: string
-        company_nationality:
-          description: "国家名称"
-          type: string
-        company_nationality_code:
-          description: "国家编码"
-          type: string
-        company_province:
-          description: "省份名称"
-          type: string
-        company_province_code:
-          description: "省份编码"
-          type: string
-        company_city:
-          description: "城市名称"
-          type: string
-        company_city_code:
-          description: "城市编码"
-          type: string
-        company_district:
-          description: "区 / 县名称"
-          type: string
-        company_district_code:
-          description: "区 / 县编码"
-          type: string
-        company_postalcode:
-          description: "邮编"
-          type: string
-        company_add:
-          description: "地址"
-          type: string
-        company_status:
-          description: "公司状态"
-          type: string
-        company_level:
-          description: "公司等级"
-          type: string
-        company_owner_openid:
-          description: "公司所有者 openid"
-          type: string
-        company_remark:
-          description: "备注"
-          type: string
-    CompanyRecord:
-      allOf:
-        - type: object
-          properties:
-            id:
-              type: string
-              description: PocketBase 记录主键 id
-            collectionId:
-              type: string
-            collectionName:
-              type: string
-            created:
-              description: "记录创建时间"
-              type: string
-            updated:
-              description: "记录更新时间"
-              type: string
-        - $ref: '#/components/schemas/CompanyBase'
-    CompanyListResponse:
-      type: object
-      properties:
-        page:
-          type: integer
-        perPage:
-          type: integer
-        totalItems:
-          type: integer
-        totalPages:
-          type: integer
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/CompanyRecord'
-    PocketBaseError:
-      type: object
-      properties:
-        status:
-          type: integer
-        message:
-          type: string
-        data:
-          description: "业务响应数据"
-          type: object
-          additionalProperties: true
diff --git a/pocket-base/spec/openapi-wx.yaml b/pocket-base/spec/openapi-wx.yaml
deleted file mode 100644
index bad5134..0000000
--- a/pocket-base/spec/openapi-wx.yaml
+++ /dev/null
@@ -1,44 +0,0 @@
-openapi: 3.1.0
-info:
-  title: BAI PocketBase Native API
-  version: 1.0.0-wx
-  description: |
-    顶层兼容入口。
-    当前原生 API 文档已整理到 `spec/openapi-wx/` 目录下；本文件保留为兼容总入口。
-servers:
-  - url: https://bai-api.blv-oa.com
-    description: 生产环境
-  - url: http://127.0.0.1:8090
-    description: PocketBase 本地环境
-tags:
-  - name: 企业信息
-    description: PocketBase 原生公司记录接口
-  - name: 附件信息
-    description: PocketBase 原生附件记录接口
-  - name: 产品信息
-    description: PocketBase 原生产品记录接口
-  - name: 文档信息
-    description: PocketBase 原生文档记录接口
-  - name: 购物车
-    description: PocketBase 原生购物车记录接口
-  - name: 订单
-    description: PocketBase 原生订单记录接口
-paths:
-  /pb/api/collections/tbl_company/records:
-    $ref: './openapi-wx/company.yaml#/paths/companyRecords'
-  /pb/api/collections/tbl_company/records/{recordId}:
-    $ref: './openapi-wx/company.yaml#/paths/companyRecordById'
-  /pb/api/collections/tbl_attachments/records:
-    $ref: './openapi-wx/attachments.yaml#/paths/attachmentRecords'
-  /pb/api/collections/tbl_product_list/records:
-    $ref: './openapi-wx/products.yaml#/paths/productRecords'
-  /pb/api/collections/tbl_document/records:
-    $ref: './openapi-wx/documents.yaml#/paths/documentRecords'
-  /pb/api/collections/tbl_cart/records:
-    $ref: './openapi-wx/cart.yaml#/paths/cartRecords'
-  /pb/api/collections/tbl_cart/records/{recordId}:
-    $ref: './openapi-wx/cart.yaml#/paths/cartRecordById'
-  /pb/api/collections/tbl_order/records:
-    $ref: './openapi-wx/order.yaml#/paths/orderRecords'
-  /pb/api/collections/tbl_order/records/{recordId}:
-    $ref: './openapi-wx/order.yaml#/paths/orderRecordById'
diff --git a/pocket-base/spec/openapi-wx/attachments.yaml b/pocket-base/spec/openapi-wx/attachments.yaml
index 588aa0c..d287e55 100644
--- a/pocket-base/spec/openapi-wx/attachments.yaml
+++ b/pocket-base/spec/openapi-wx/attachments.yaml
@@ -1,5 +1,17 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Native API - Attachments
+  version: 1.0.0
+  description: |
+    PocketBase 原生 `tbl_attachments` records API 文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
 paths:
-  attachmentRecords:
+  /pb/api/collections/tbl_attachments/records:
     get:
       operationId: getPocketBaseAttachmentRecords
       tags:
@@ -38,7 +50,7 @@ paths:
             - 不传该参数时，返回分页列表
           schema:
             type: string
-          example: attachments_id="ATT-1774599142438-8n1UcU"
+          example: 过滤表达式|string
         - name: page
           in: query
           required: false
@@ -60,8 +72,6 @@ paths:
           description: 查询成功
           content:
             application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseAttachmentListResponse
               example:
                 page: page|integer
                 perPage: perPage|integer
@@ -85,8 +95,6 @@ paths:
           description: 查询参数错误
           content:
             application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -97,7 +105,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -108,7 +116,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -240,8 +248,6 @@ components:
           example: 总页数 | integer
         items:
           type: array
-          items:
-            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseAttachmentRecord
       example:
         page: page|integer
         perPage: perPage|integer
diff --git a/pocket-base/spec/openapi-wx/cart.yaml b/pocket-base/spec/openapi-wx/cart.yaml
index dddcf75..a32587d 100644
--- a/pocket-base/spec/openapi-wx/cart.yaml
+++ b/pocket-base/spec/openapi-wx/cart.yaml
@@ -1,11 +1,30 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Native API - Cart
+  version: 1.0.0
+  description: |
+    PocketBase 原生 `tbl_cart` records API 文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
+tags:
+  - name: 购物车
+    description: PocketBase 原生购物车记录接口
 paths:
-  cartRecords:
+  /pb/api/collections/tbl_cart/records:
     get:
+      operationId: getPocketBaseCartRecords
       tags: [购物车]
       summary: 查询购物车记录列表
       description: |
         使用 PocketBase 原生 records list 接口查询 `tbl_cart`。
-        如需鉴权，请自行在请求头中携带 `Authorization: Bearer <token>`。
+
+        说明：
+        - `cart_product_id` 是 relation 字段，默认仅返回关联记录 id。
+        - 如需同时返回 `tbl_product_list` 详情，请传 `expand=cart_product_id`。
       parameters:
         - name: filter
           in: query
@@ -13,7 +32,7 @@ paths:
           schema:
             type: string
           description: PocketBase 原生过滤表达式
-          example: cart_id="购物车业务ID|string"
+          example: 过滤表达式|string
         - name: page
           in: query
           required: false
@@ -33,7 +52,14 @@ paths:
           required: false
           schema:
             type: string
-          example: -cart_create
+          example: 排序表达式|string
+        - name: expand
+          in: query
+          required: false
+          schema:
+            type: string
+          description: 关系字段展开；传 `cart_product_id` 时返回 `expand.cart_product_id`
+          example: 关联展开字段|string
       responses:
         '200':
           description: 查询成功
@@ -43,18 +69,34 @@ paths:
                 $ref: '#/components/schemas/PocketBaseCartListResponse'
         '400':
           description: 查询参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '403':
           description: 无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
     post:
+      operationId: postPocketBaseCartRecord
       tags: [购物车]
       summary: 创建购物车记录
       description: |
         使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。
-        如集合规则要求 `cart_owner` 与当前用户一致，请客户端显式提交。
       requestBody:
         required: true
         content:
@@ -65,7 +107,7 @@ paths:
               cart_id: 购物车业务ID|string
               cart_number: 购物车名称或分组号|string
               cart_owner: 购物车所有者openid|string
-              cart_product_id: tbl_product_list 的 PocketBase recordId|string
+              cart_product_id: 产品业务ID|string
               cart_product_quantity: 产品数量|integer
               cart_status: 购物车状态|string
               cart_at_price: 加入购物车时价格|number
@@ -79,19 +121,33 @@ paths:
                 $ref: '#/components/schemas/PocketBaseCartRecord'
         '400':
           description: 参数错误或违反集合规则
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '403':
           description: 无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
-  cartRecordById:
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
+  /pb/api/collections/tbl_cart/records/{recordId}:
     patch:
+      operationId: patchPocketBaseCartRecordByRecordId
       tags: [购物车]
       summary: 更新购物车记录
-      description: |
-        使用 PocketBase 原生 records update 接口更新 `tbl_cart`。
-        路径参数使用 PocketBase 原生 `recordId`。
       parameters:
         - name: recordId
           in: path
@@ -108,7 +164,7 @@ paths:
             example:
               cart_number: 购物车名称或分组号|string
               cart_owner: 购物车所有者openid|string
-              cart_product_id: tbl_product_list 的 PocketBase recordId|string
+              cart_product_id: 产品业务ID|string
               cart_product_quantity: 产品数量|integer
               cart_status: 购物车状态|string
               cart_at_price: 加入购物车时价格|number
@@ -122,18 +178,32 @@ paths:
                 $ref: '#/components/schemas/PocketBaseCartRecord'
         '400':
           description: 参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '404':
           description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
     delete:
+      operationId: deletePocketBaseCartRecordByRecordId
       tags: [购物车]
       summary: 删除购物车记录
-      description: |
-        使用 PocketBase 原生 records delete 接口删除 `tbl_cart`。
-        路径参数使用 PocketBase 原生 `recordId`。
       parameters:
         - name: recordId
           in: path
@@ -146,878 +216,65 @@ paths:
           description: 删除成功
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '404':
           description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
-        "400":
-          description: 参数错误
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 无权访问该购物车记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 未找到对应购物车记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  cartCreate:
-    post:
-      operationId: postCartCreate
-      tags:
-        - 购物车
-      summary: 新增购物车记录
-      description: |
-        调用自定义 hooks API 新增一条购物车记录。
-
-        创建规则：
-        - 服务端自动根据当前 token 写入 `cart_owner`
-        - 服务端自动生成 `cart_id`
-        - 若未传 `cart_number`，服务端会自动生成展示编号
-        - `cart_product_id` 为必填；当前 hooks 与库结构保持一致，必须传 `tbl_product_list` 的 `recordId`
-        - `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
-            example:
-              cart_number: 可选；未传时服务端自动生成|string
-              cart_product_id: tbl_product_list 的 PocketBase recordId|string
-              cart_product_quantity: 产品数量，需为正整数|integer
-              cart_status: 可选；未传时默认 有效|string
-              cart_at_price: 加入购物车时价格|integer
-              cart_remark: 备注|string
-      responses:
-        "200":
-          description: 创建成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/CartRecord
-              example:
-                pb_id: PocketBase 记录主键 id|string
-                created: PocketBase 系统创建时间|string
-                updated: PocketBase 系统更新时间|string
-                cart_id: 购物车业务 ID|string
-                cart_number: 购物车名称或分组号|string
-                cart_create: 购物车项创建时间，由数据库自动生成|string
-                cart_owner: 购物车所有者 openid|string
-                cart_product_id: 关联产品的 PocketBase recordId|string
-                cart_product_business_id: 产品业务 ID|string
-                cart_product_quantity: 产品数量|integer
-                cart_status: 购物车状态|string
-                cart_at_price: 加入购物车时价格|integer
-                cart_remark: 备注|string
-                is_delete: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出|integer
-                product_name: 产品名称（服务端联动补充）|string
-                product_modelnumber: 产品型号（服务端联动补充）|string
-                product_basic_price: 产品基础价格（服务端联动补充）|integer
-        "400":
-          description: 参数错误、产品不存在或创建失败
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "429":
-          description: 重复请求过于频繁
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-            example:
-              cart_id: 购物车业务 ID|string
-              cart_number: cart_number|string
-              cart_product_id: tbl_product_list 的 PocketBase recordId|string
-              cart_product_quantity: cart_product_quantity|integer
-              cart_status: cart_status|string
-              cart_at_price: cart_at_price|integer
-              cart_remark: cart_remark|string
-      responses:
-        "200":
-          description: 更新成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/CartRecord
-              example:
-                pb_id: PocketBase 记录主键 id|string
-                created: PocketBase 系统创建时间|string
-                updated: PocketBase 系统更新时间|string
-                cart_id: 购物车业务 ID|string
-                cart_number: 购物车名称或分组号|string
-                cart_create: 购物车项创建时间，由数据库自动生成|string
-                cart_owner: 购物车所有者 openid|string
-                cart_product_id: 关联产品的 PocketBase recordId|string
-                cart_product_business_id: 产品业务 ID|string
-                cart_product_quantity: 产品数量|integer
-                cart_status: 购物车状态|string
-                cart_at_price: 加入购物车时价格|integer
-                cart_remark: 备注|string
-                is_delete: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出|integer
-                product_name: 产品名称（服务端联动补充）|string
-                product_modelnumber: 产品型号（服务端联动补充）|string
-                product_basic_price: 产品基础价格（服务端联动补充）|integer
-        "400":
-          description: 参数错误、产品不存在或更新失败
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 无权访问该购物车记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 未找到待修改的购物车记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "429":
-          description: 重复请求过于频繁
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-            example:
-              cart_id: 购物车业务 ID|string
-      responses:
-        "200":
-          description: 删除成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/CartDeleteResponse
-              example:
-                cart_id: 购物车业务 ID|string
-                is_delete: 目标软删除标记值；当前实现可能仍返回物理删除结果|integer
-        "400":
-          description: 参数错误或删除失败
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 无权访问该购物车记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 未找到待删除的购物车记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "429":
-          description: 重复请求过于频繁
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-              example:
-                page: page|integer
-                perPage: perPage|integer
-                totalItems: totalItems|integer
-                totalPages: totalPages|integer
-                items:
-                  - id: PocketBase 记录主键|string
-                    collectionId: collectionId|string
-                    collectionName: collectionName|string
-                    created: 记录创建时间|string
-                    updated: 记录更新时间|string
-                    cart_id: 购物车业务 ID|string
-                    cart_number: 购物车名称或分组号|string
-                    cart_create: 购物车项创建时间，由数据库自动生成|string
-                    cart_owner: 购物车所有者 openid|string
-                    cart_product_id: 产品业务 ID|string
-                    cart_product_quantity: 产品数量|integer
-                    cart_status: 购物车状态|string
-                    cart_at_price: 加入购物车时价格|number
-                    cart_remark: 备注|string
-        "400":
-          description: 查询参数错误或不满足 listRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 集合规则被锁定或服务端权限设置异常
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-    post:
-      operationId: postPocketBaseCartRecord
-      tags:
-        - 购物车
-      summary: 创建购物车记录
-      description: |
-        使用 PocketBase 原生 records create 接口向 `tbl_cart` 新增记录。
-
-        当前线上权限规则：
-        - `createRule = @request.body.cart_owner != ""`
-        - 因此客户端创建时必须显式提交非空 `cart_owner`
-        - `cart_product_id` 当前为 relation 字段，必须传 `tbl_product_list` 的 PocketBase `recordId`
-
-        这意味着：
-        - 不能依赖服务端自动补 owner
-        - 不能省略 `cart_owner`
-        - 不满足规则时 PocketBase 会直接返回 `400`
-      security:
-        - BearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartCreateRequest
-            example:
-              cart_id: cart_id|string
-              cart_number: cart_number|string
-              cart_owner: 必须显式提交非空 owner|string
-              cart_product_id: tbl_product_list 的 PocketBase recordId|string
-              cart_product_quantity: cart_product_quantity|integer，可为空
-              cart_status: cart_status|string，可为空
-              cart_at_price: cart_at_price|number，可为空
-              cart_remark: cart_remark|string
-      responses:
-        "200":
-          description: 创建成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord
-              example:
-                id: PocketBase 记录主键|string
-                collectionId: collectionId|string
-                collectionName: collectionName|string
-                created: 记录创建时间|string
-                updated: 记录更新时间|string
-                cart_id: 购物车业务 ID|string
-                cart_number: 购物车名称或分组号|string
-                cart_create: 购物车项创建时间，由数据库自动生成|string
-                cart_owner: 购物车所有者 openid|string
-                cart_product_id: 关联产品的 PocketBase recordId|string
-                cart_product_quantity: 产品数量|integer
-                cart_status: 购物车状态|string
-                cart_at_price: 加入购物车时价格|number
-                cart_remark: 备注|string
-        "400":
-          description: 参数错误、违反字段约束或不满足 createRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 集合规则被锁定或服务端权限设置异常
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-            example:
-              cart_number: cart_number|string
-              cart_owner: 若提交，必须仍等于当前 token 对应 openid|string
-              cart_product_id: cart_product_id|string
-              cart_product_quantity: cart_product_quantity|integer
-              cart_status: cart_status|string
-              cart_at_price: cart_at_price|number
-              cart_remark: cart_remark|string
-      responses:
-        "200":
-          description: 更新成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord
-              example:
-                id: PocketBase 记录主键|string
-                collectionId: collectionId|string
-                collectionName: collectionName|string
-                created: 记录创建时间|string
-                updated: 记录更新时间|string
-                cart_id: 购物车业务 ID|string
-                cart_number: 购物车名称或分组号|string
-                cart_create: 购物车项创建时间，由数据库自动生成|string
-                cart_owner: 购物车所有者 openid|string
-                cart_product_id: 产品业务 ID|string
-                cart_product_quantity: 产品数量|integer
-                cart_status: 购物车状态|string
-                cart_at_price: 加入购物车时价格|number
-                cart_remark: 备注|string
-        "400":
-          description: 参数错误或违反字段约束
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 记录不存在或不满足 updateRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-    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
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 记录不存在或不满足 deleteRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
+                $ref: '#/components/schemas/PocketBaseNativeError'
 components:
   schemas:
     PocketBaseNativeError:
       type: object
       properties:
         code:
-          type:
-            - integer
-            - string
+          type: [integer, string]
           description: PocketBase错误码
-          example: 错误状态码 | integer
         message:
           type: string
           description: PocketBase错误信息
-          example: PocketBase原生错误信息 | string
         data:
-          description: PocketBase错误数据
           type: object
           additionalProperties: true
+          description: PocketBase错误数据
       example:
-        code: 业务状态码|integer
-        message: message|string
+        code: 错误状态码|integer
+        message: PocketBase原生错误信息|string
         data:
-          业务响应数据字段|string: 业务响应数据值|string
+          字段名|string: 字段值|string
     PocketBaseRecordBase:
       type: object
-      required:
-        - id
-        - collectionId
-        - collectionName
-        - created
-        - updated
+      required: [id, collectionId, collectionName, created, updated]
       properties:
         id:
           type: string
-          description: PocketBase 记录主键
-          example: PocketBase记录主键 | string
+          description: PocketBase记录主键
         collectionId:
           type: string
-          example: 集合ID | string
+          description: 集合ID
         collectionName:
           type: string
-          example: 集合名称 | string
+          description: 集合名称
         created:
           type: string
           description: 记录创建时间
-          example: 记录创建时间 | string
         updated:
           type: string
           description: 记录更新时间
-          example: 记录更新时间 | string
       example:
-        id: PocketBase 记录主键|string
-        collectionId: collectionId|string
-        collectionName: collectionName|string
+        id: PocketBase记录主键|string
+        collectionId: 集合ID|string
+        collectionName: 集合名称|string
         created: 记录创建时间|string
         updated: 记录更新时间|string
     PocketBaseCartFields:
@@ -1025,190 +282,154 @@ components:
       properties:
         cart_id:
           type: string
-          description: 购物车业务 ID
-          example: CART-1770000000000-abc123
+          description: 购物车业务ID
         cart_number:
           type: string
           description: 购物车名称或分组号
-          example: wx-user-20260403153000
         cart_create:
           type: string
-          description: 购物车项创建时间，由数据库自动生成
-          example: 2026-04-03 15:30:00.000Z
+          description: 购物车项创建时间
         cart_owner:
           type: string
-          description: 购物车所有者 openid
-          example: wx-openid-user-001
+          description: 购物车所有者openid
         cart_product_id:
           type: string
-          description: 关联产品的 PocketBase recordId
-          example: pbc_product_record_id|string
-        cart_product_business_id:
-          type: string
-          description: 关联产品的业务 ID（prod_list_id），用于展示
-          example: PROD-1770000000000-abcd12
+          description: 产品业务ID
         cart_product_quantity:
-          type:
-            - integer
-            - number
+          type: [integer, number]
           description: 产品数量
-          example: 2
         cart_status:
           type: string
           description: 购物车状态
-          example: 有效
         cart_at_price:
-          type:
-            - number
-            - integer
+          type: [number, integer]
           description: 加入购物车时价格
-          example: 1999
         cart_remark:
           type: string
           description: 备注
-          example: 小程序加入购物车示例
       example:
-        cart_id: 购物车业务 ID|string
+        cart_id: 购物车业务ID|string
         cart_number: 购物车名称或分组号|string
-        cart_create: 购物车项创建时间，由数据库自动生成|string
-        cart_owner: 购物车所有者 openid|string
-        cart_product_id: tbl_product_list 的 PocketBase recordId|string
-        cart_product_business_id: 产品业务 ID|string
+        cart_create: 购物车项创建时间|string
+        cart_owner: 购物车所有者openid|string
+        cart_product_id: 产品业务ID|string
         cart_product_quantity: 产品数量|integer
         cart_status: 购物车状态|string
         cart_at_price: 加入购物车时价格|number
         cart_remark: 备注|string
     PocketBaseCartRecord:
       allOf:
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartFields
-      example:
-        id: PocketBase 记录主键|string
-        collectionId: collectionId|string
-        collectionName: collectionName|string
-        created: 记录创建时间|string
-        updated: 记录更新时间|string
-        cart_id: 购物车业务 ID|string
-        cart_number: 购物车名称或分组号|string
-        cart_create: 购物车项创建时间，由数据库自动生成|string
-        cart_owner: 购物车所有者 openid|string
-        cart_product_id: 产品业务 ID|string
-        cart_product_quantity: 产品数量|integer
-        cart_status: 购物车状态|string
-        cart_at_price: 加入购物车时价格|number
-        cart_remark: 备注|string
+        - $ref: '#/components/schemas/PocketBaseRecordBase'
+        - $ref: '#/components/schemas/PocketBaseCartFields'
+        - type: object
+          properties:
+            expand:
+              type: object
+              description: 关系字段展开结果（需请求参数 `expand=cart_product_id`）
+              properties:
+                cart_product_id:
+                  $ref: '#/components/schemas/PocketBaseProductListExpand'
     PocketBaseCartCreateRequest:
       type: object
-      required:
-        - cart_owner
-        - cart_product_id
+      required: [cart_owner]
       properties:
         cart_id:
           type: string
+          example: 购物车业务ID|string
         cart_number:
           type: string
+          example: 购物车名称或分组号|string
         cart_owner:
           type: string
-          description: 必须显式提交非空 owner
+          example: 购物车所有者openid|string
         cart_product_id:
           type: string
-          description: tbl_product_list 的 PocketBase recordId
+          example: 产品业务ID|string
         cart_product_quantity:
-          type:
-            - integer
-            - number
+          type: [integer, number]
+          example: 产品数量|integer
         cart_status:
           type: string
+          example: 购物车状态|string
         cart_at_price:
-          type:
-            - number
-            - integer
+          type: [number, integer]
+          example: 加入购物车时价格|number
         cart_remark:
           type: string
-      example:
-        cart_owner: 必须显式提交非空 owner|string
-        cart_product_id: tbl_product_list 的 PocketBase recordId|string
-        cart_product_quantity: cart_product_quantity|integer，可为空
-        cart_status: cart_status|string，可为空
-        cart_at_price: cart_at_price|number，可为空
-        cart_remark: cart_remark|string
+          example: 备注|string
     PocketBaseCartUpdateRequest:
       type: object
       properties:
         cart_number:
           type: string
+          example: 购物车名称或分组号|string
         cart_owner:
           type: string
-          description: 若提交，必须仍为非空 owner
+          example: 购物车所有者openid|string
         cart_product_id:
           type: string
-          description: tbl_product_list 的 PocketBase recordId
+          example: 产品业务ID|string
         cart_product_quantity:
-          type:
-            - integer
-            - number
+          type: [integer, number]
+          example: 产品数量|integer
         cart_status:
           type: string
+          example: 购物车状态|string
         cart_at_price:
-          type:
-            - number
-            - integer
+          type: [number, integer]
+          example: 加入购物车时价格|number
         cart_remark:
           type: string
-      example:
-        cart_number: cart_number|string
-        cart_owner: 若提交，必须仍为非空 owner|string
-        cart_product_id: tbl_product_list 的 PocketBase recordId|string
-        cart_product_quantity: cart_product_quantity|integer
-        cart_status: cart_status|string
-        cart_at_price: cart_at_price|number
-        cart_remark: cart_remark|string
+          example: 备注|string
     PocketBaseCartListResponse:
       type: object
-      required:
-        - page
-        - perPage
-        - totalItems
-        - totalPages
-        - items
+      required: [page, perPage, totalItems, totalPages, items]
       properties:
         page:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         perPage:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         totalItems:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         totalPages:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         items:
           type: array
           items:
-            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCartRecord
-      example:
-        page: page|integer
-        perPage: perPage|integer
-        totalItems: totalItems|integer
-        totalPages: totalPages|integer
-        items:
-          - id: PocketBase 记录主键|string
-            collectionId: collectionId|string
-            collectionName: collectionName|string
-            created: 记录创建时间|string
-            updated: 记录更新时间|string
-            cart_id: 购物车业务 ID|string
-            cart_number: 购物车名称或分组号|string
-            cart_create: 购物车项创建时间，由数据库自动生成|string
-            cart_owner: 购物车所有者 openid|string
-            cart_product_id: 产品业务 ID|string
-            cart_product_quantity: 产品数量|integer
-            cart_status: 购物车状态|string
-            cart_at_price: 加入购物车时价格|number
-            cart_remark: 备注|string
+            $ref: '#/components/schemas/PocketBaseCartRecord'
+    PocketBaseProductListExpand:
+      type: object
+      description: tbl_product_list 关联展开后的记录对象（示例字段）
+      properties:
+        id:
+          type: string
+          description: PocketBase记录主键
+          example: PocketBase记录主键|string
+        collectionId:
+          type: string
+          description: 集合ID
+          example: 集合ID|string
+        collectionName:
+          type: string
+          description: 集合名称
+          example: 集合名称|string
+        prod_list_id:
+          type: string
+          description: 产品业务ID
+          example: 产品业务ID|string
+        prod_list_name:
+          type: string
+          description: 产品名称
+          example: 产品名称|string
+        prod_list_modelnumber:
+          type: string
+          description: 产品型号
+          example: 产品型号|string
+        prod_list_basic_price:
+          type: [number, integer]
+          description: 基础价格
+          example: 基础价格|number
+        prod_list_status:
+          type: string
+          description: 产品状态
+          example: 产品状态|string
diff --git a/pocket-base/spec/openapi-wx/company.yaml b/pocket-base/spec/openapi-wx/company.yaml
index e34c0cc..21b9383 100644
--- a/pocket-base/spec/openapi-wx/company.yaml
+++ b/pocket-base/spec/openapi-wx/company.yaml
@@ -1,5 +1,17 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Native API - Company
+  version: 1.0.0
+  description: |
+    PocketBase 原生 `tbl_company` records API 文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
 paths:
-  companyRecords:
+  /pb/api/collections/tbl_company/records:
     post:
       operationId: postPocketBaseCompanyRecord
       tags:
@@ -21,7 +33,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyCreateRequest
+              $ref: #/components/schemas/PocketBaseCompanyCreateRequest
             example:
               company_name: 公司名称|string
               company_type: 公司类型|string
@@ -47,7 +59,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyRecord
+                $ref: #/components/schemas/PocketBaseCompanyRecord
               example:
                 id: PocketBase 记录主键|string
                 collectionId: collectionId|string
@@ -78,7 +90,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -89,7 +101,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -100,7 +112,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -142,7 +154,7 @@ paths:
             - 查询整个列表时：不传该参数
           schema:
             type: string
-          example: company_id="WX-COMPANY-10001"
+          example: 过滤表达式|string
         - name: page
           in: query
           required: false
@@ -165,7 +177,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyListResponse
+                $ref: #/components/schemas/PocketBaseCompanyListResponse
               example:
                 page: page|integer
                 perPage: perPage|integer
@@ -201,7 +213,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -212,7 +224,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -223,13 +235,13 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
                 data:
                   业务响应数据字段|string: 业务响应数据值|string
-  companyRecordById:
+  /pb/api/collections/tbl_company/records/{recordId}:
     patch:
       operationId: patchPocketBaseCompanyRecordByRecordId
       tags:
@@ -253,13 +265,13 @@ paths:
           description: 通过 `company_id` 查询结果拿到的 PocketBase 记录主键 `id`
           schema:
             type: string
-          example: l2r3nq7rqhuob0h
+          example: PocketBase记录主键|string
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyUpdateRequest
+              $ref: #/components/schemas/PocketBaseCompanyUpdateRequest
             example:
               company_id: 所属公司业务 ID|string
               company_name: 公司名称|string
@@ -286,7 +298,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyRecord
+                $ref: #/components/schemas/PocketBaseCompanyRecord
               example:
                 id: PocketBase 记录主键|string
                 collectionId: collectionId|string
@@ -317,7 +329,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -328,7 +340,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -339,7 +351,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -350,7 +362,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -653,8 +665,8 @@ components:
         company_remark: 备注|string
     PocketBaseCompanyRecord:
       allOf:
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyFields
+        - $ref: #/components/schemas/PocketBaseRecordBase
+        - $ref: #/components/schemas/PocketBaseCompanyFields
       example:
         id: PocketBase 记录主键|string
         collectionId: collectionId|string
@@ -870,7 +882,7 @@ components:
         items:
           type: array
           items:
-            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseCompanyRecord
+            $ref: #/components/schemas/PocketBaseCompanyRecord
       example:
         page: page|integer
         perPage: perPage|integer
diff --git a/pocket-base/spec/openapi-wx/documents.yaml b/pocket-base/spec/openapi-wx/documents.yaml
index 14632fb..7e5b60d 100644
--- a/pocket-base/spec/openapi-wx/documents.yaml
+++ b/pocket-base/spec/openapi-wx/documents.yaml
@@ -1,5 +1,17 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Native API - Documents
+  version: 1.0.0
+  description: |
+    PocketBase 原生 `tbl_document` records API 文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
 paths:
-  documentRecords:
+  /pb/api/collections/tbl_document/records:
     get:
       operationId: getPocketBaseDocumentRecords
       tags:
@@ -57,7 +69,7 @@ paths:
             - 例如：`document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"`
           schema:
             type: string
-          example: document_type ~ "DICT-1774599144591-hAEFQj" && document_type ~ "@UT1"
+          example: 过滤表达式|string
         - name: page
           in: query
           required: false
@@ -84,14 +96,14 @@ paths:
             - `-document_create`：按最新上传倒序返回
           schema:
             type: string
-          example: -document_create
+          example: 排序表达式|string
       responses:
         "200":
           description: 查询成功
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseDocumentListResponse
+                $ref: #/components/schemas/PocketBaseDocumentListResponse
               example:
                 page: page|integer
                 perPage: perPage|integer
@@ -135,7 +147,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -146,7 +158,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -157,7 +169,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -289,15 +301,15 @@ components:
         document_share_count:
           type: number
           description: 分享次数
-          example: 0
+          example: 分享次数|number
         document_download_count:
           type: number
           description: 下载次数
-          example: 0
+          example: 下载次数|number
         document_favorite_count:
           type: number
           description: 收藏次数
-          example: 0
+          example: 收藏次数|number
         document_embedding_status:
           type: string
           description: 文档嵌入状态
@@ -360,8 +372,8 @@ components:
         document_remark: 备注|string
     PocketBaseDocumentRecord:
       allOf:
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseDocumentFields
+        - $ref: #/components/schemas/PocketBaseRecordBase
+        - $ref: #/components/schemas/PocketBaseDocumentFields
       example:
         id: PocketBase 记录主键|string
         collectionId: collectionId|string
@@ -427,7 +439,7 @@ components:
         items:
           type: array
           items:
-            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseDocumentRecord
+            $ref: #/components/schemas/PocketBaseDocumentRecord
       example:
         page: page|integer
         perPage: perPage|integer
diff --git a/pocket-base/spec/openapi-wx/openapi.yaml b/pocket-base/spec/openapi-wx/openapi.yaml
index ac5af86..5e1057b 100644
--- a/pocket-base/spec/openapi-wx/openapi.yaml
+++ b/pocket-base/spec/openapi-wx/openapi.yaml
@@ -5,6 +5,8 @@ info:
   description: |
     本目录仅收敛 PocketBase 原生 API 文档，不包含自定义 hooks API。
 
+    本文件为目录索引，支持单文件独立导入，不依赖其他 YAML。
+
     文档约定：
     - 不单独配置鉴权组件；如接口需要登录，请直接在说明中关注 `Authorization: Bearer <token>`
     - 示例字段值统一使用 `<字段说明>|<类型>` 风格
@@ -27,22 +29,12 @@ tags:
     description: PocketBase 原生购物车记录接口
   - name: 订单
     description: PocketBase 原生订单记录接口
-paths:
-  /pb/api/collections/tbl_company/records:
-    $ref: './company.yaml#/paths/companyRecords'
-  /pb/api/collections/tbl_company/records/{recordId}:
-    $ref: './company.yaml#/paths/companyRecordById'
-  /pb/api/collections/tbl_attachments/records:
-    $ref: './attachments.yaml#/paths/attachmentRecords'
-  /pb/api/collections/tbl_product_list/records:
-    $ref: './products.yaml#/paths/productRecords'
-  /pb/api/collections/tbl_document/records:
-    $ref: './documents.yaml#/paths/documentRecords'
-  /pb/api/collections/tbl_cart/records:
-    $ref: './cart.yaml#/paths/cartRecords'
-  /pb/api/collections/tbl_cart/records/{recordId}:
-    $ref: './cart.yaml#/paths/cartRecordById'
-  /pb/api/collections/tbl_order/records:
-    $ref: './order.yaml#/paths/orderRecords'
-  /pb/api/collections/tbl_order/records/{recordId}:
-    $ref: './order.yaml#/paths/orderRecordById'
\ No newline at end of file
+paths: {}
+x-index:
+  files:
+    - company.yaml
+    - attachments.yaml
+    - products.yaml
+    - documents.yaml
+    - cart.yaml
+    - order.yaml
\ No newline at end of file
diff --git a/pocket-base/spec/openapi-wx/order.yaml b/pocket-base/spec/openapi-wx/order.yaml
index 276806c..1e0d65c 100644
--- a/pocket-base/spec/openapi-wx/order.yaml
+++ b/pocket-base/spec/openapi-wx/order.yaml
@@ -1,11 +1,24 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Native API - Order
+  version: 1.0.0
+  description: |
+    PocketBase 原生 `tbl_order` records API 文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
+tags:
+  - name: 订单
+    description: PocketBase 原生订单记录接口
 paths:
-  orderRecords:
+  /pb/api/collections/tbl_order/records:
     get:
+      operationId: getPocketBaseOrderRecords
       tags: [订单]
       summary: 查询订单记录列表
-      description: |
-        使用 PocketBase 原生 records list 接口查询 `tbl_order`。
-        如需鉴权，请自行在请求头中携带 `Authorization: Bearer <token>`。
       parameters:
         - name: filter
           in: query
@@ -33,7 +46,7 @@ paths:
           required: false
           schema:
             type: string
-          example: -order_create
+          example: 排序表达式|string
       responses:
         '200':
           description: 查询成功
@@ -43,18 +56,32 @@ paths:
                 $ref: '#/components/schemas/PocketBaseOrderListResponse'
         '400':
           description: 查询参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '403':
           description: 无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
     post:
+      operationId: postPocketBaseOrderRecord
       tags: [订单]
       summary: 创建订单记录
-      description: |
-        使用 PocketBase 原生 records create 接口向 `tbl_order` 新增记录。
-        如集合规则要求 `order_owner` 与当前用户一致，请客户端显式提交。
       requestBody:
         required: true
         content:
@@ -81,19 +108,33 @@ paths:
                 $ref: '#/components/schemas/PocketBaseOrderRecord'
         '400':
           description: 参数错误或违反集合规则
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '403':
           description: 无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
-  orderRecordById:
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
+  /pb/api/collections/tbl_order/records/{recordId}:
     patch:
+      operationId: patchPocketBaseOrderRecordByRecordId
       tags: [订单]
       summary: 更新订单记录
-      description: |
-        使用 PocketBase 原生 records update 接口更新 `tbl_order`。
-        路径参数使用 PocketBase 原生 `recordId`。
       parameters:
         - name: recordId
           in: path
@@ -126,18 +167,32 @@ paths:
                 $ref: '#/components/schemas/PocketBaseOrderRecord'
         '400':
           description: 参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '404':
           description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
     delete:
+      operationId: deletePocketBaseOrderRecordByRecordId
       tags: [订单]
       summary: 删除订单记录
-      description: |
-        使用 PocketBase 原生 records delete 接口删除 `tbl_order`。
-        路径参数使用 PocketBase 原生 `recordId`。
       parameters:
         - name: recordId
           in: path
@@ -150,877 +205,65 @@ paths:
           description: 删除成功
         '401':
           description: token 无效或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '404':
           description: 记录不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PocketBaseNativeError'
         '500':
           description: 服务端错误
-        "400":
-          description: 参数错误
-          components:
-            schemas:
-        创建规则：
-        - 服务端自动根据当前 token 写入 `order_owner`
-        - 服务端自动生成 `order_id`
-        - 若未传 `order_number`，服务端会自动生成展示编号
-        - `order_source`、`order_source_id`、`order_snap`、`order_amount` 为必填
-
-        目标软删除契约：
-                    description: PocketBase错误码
-        - 当前仓库导出响应中尚未显式返回 `is_delete` 字段
-      security:
-                    description: PocketBase错误信息
-                    example: PocketBase原生错误信息 | string
-      requestBody:
-                    description: PocketBase错误数据
-        content:
-          application/json:
-            schema:
-              $ref: ../openapi-wx.yaml#/components/schemas/OrderCreateRequest
-            example:
-              order_number: 可选；未传时服务端自动生成|string
-              order_source: 订单来源|string
-              order_status: 可选；未传时默认 订单已生成|string
-              order_source_id: 来源关联业务 ID|string
-              order_snap:
-                order_snap字段|string: order_snap值|string
-              order_amount: 订单金额|integer
-              order_remark: 备注|string
-      responses:
-        "200":
-          description: 创建成功
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/OrderRecord
-              example:
-                pb_id: PocketBase 记录主键 id|string
-                created: PocketBase 系统创建时间|string
-                updated: PocketBase 系统更新时间|string
-                order_id: 订单业务 ID|string
-                order_number: 订单编号|string
-                order_create: 订单创建时间，由数据库自动生成|string
-                order_owner: 订单所有者 openid|string
-                order_source: 订单来源|string
-                order_status: 订单状态|string
-                order_source_id: 来源关联业务 ID|string
-                order_snap:
-                  order_snap字段|string: order_snap值|string
-                order_amount: 订单金额|integer
-                order_remark: 备注|string
-                is_delete: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出|integer
-        "400":
-          description: 参数错误或创建失败
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "429":
-          description: 重复请求过于频繁
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-            example:
-              order_id: 订单业务 ID|string
-              order_number: order_number|string
-              order_source: order_source|string
-              order_status: order_status|string
-              order_source_id: order_source_id|string
-              order_snap:
-                order_snap字段|string: order_snap值|string
-              order_amount: order_amount|integer
-              order_remark: order_remark|string
-      responses:
-        "200":
-          description: 更新成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/OrderRecord
-              example:
-                pb_id: PocketBase 记录主键 id|string
-                created: PocketBase 系统创建时间|string
-                updated: PocketBase 系统更新时间|string
-                order_id: 订单业务 ID|string
-                order_number: 订单编号|string
-                order_create: 订单创建时间，由数据库自动生成|string
-                order_owner: 订单所有者 openid|string
-                order_source: 订单来源|string
-                order_status: 订单状态|string
-                order_source_id: 来源关联业务 ID|string
-                order_snap:
-                  order_snap字段|string: order_snap值|string
-                order_amount: 订单金额|integer
-                order_remark: 备注|string
-                is_delete: 软删除标记；目标契约字段，当前 hooks 响应可能尚未显式透出|integer
-        "400":
-          description: 参数错误或更新失败
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 无权访问该订单记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 未找到待修改的订单记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "429":
-          description: 重复请求过于频繁
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-            example:
-              order_id: 订单业务 ID|string
-      responses:
-        "200":
-          description: 删除成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/OrderDeleteResponse
-              example:
-                order_id: 订单业务 ID|string
-                is_delete: 目标软删除标记值；当前实现可能仍返回物理删除结果|integer
-        "400":
-          description: 参数错误或删除失败
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 无权访问该订单记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 未找到待删除的订单记录
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "415":
-          description: 请求体必须为 application/json
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "429":
-          description: 重复请求过于频繁
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/ErrorResponse
-              example:
-                statusCode: 业务状态码|integer
-                errMsg: 业务提示信息|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-              example:
-                page: page|integer
-                perPage: perPage|integer
-                totalItems: totalItems|integer
-                totalPages: totalPages|integer
-                items:
-                  - id: PocketBase 记录主键|string
-                    collectionId: collectionId|string
-                    collectionName: collectionName|string
-                    created: 记录创建时间|string
-                    updated: 记录更新时间|string
-                    order_id: 订单业务 ID|string
-                    order_number: 订单编号|string
-                    order_create: 订单创建时间，由数据库自动生成|string
-                    order_owner: 订单所有者 openid|string
-                    order_source: 订单来源|string
-                    order_status: 订单状态|string
-                    order_source_id: 来源关联业务 ID|string
-                    order_snap:
-                      order_snap字段|string: order_snap值|string
-                    order_amount: 订单金额|number
-                    order_remark: 备注|string
-        "400":
-          description: 查询参数错误或不满足 listRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 集合规则被锁定或服务端权限设置异常
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-    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
-            example:
-              order_id: order_id|string
-              order_number: order_number|string
-              order_owner: 必须显式提交，且值必须等于当前 token 对应 openid|string
-              order_source: order_source|string
-              order_status: order_status|string
-              order_source_id: order_source_id|string
-              order_snap:
-                order_snap字段|string: order_snap值|string
-              order_amount: order_amount|number
-              order_remark: order_remark|string
-      responses:
-        "200":
-          description: 创建成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseOrderRecord
-              example:
-                id: PocketBase 记录主键|string
-                collectionId: collectionId|string
-                collectionName: collectionName|string
-                created: 记录创建时间|string
-                updated: 记录更新时间|string
-                order_id: 订单业务 ID|string
-                order_number: 订单编号|string
-                order_create: 订单创建时间，由数据库自动生成|string
-                order_owner: 订单所有者 openid|string
-                order_source: 订单来源|string
-                order_status: 订单状态|string
-                order_source_id: 来源关联业务 ID|string
-                order_snap:
-                  order_snap字段|string: order_snap值|string
-                order_amount: 订单金额|number
-                order_remark: 备注|string
-        "400":
-          description: 参数错误、违反字段约束或不满足 createRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "403":
-          description: 集合规则被锁定或服务端权限设置异常
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-  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
-            example:
-              order_number: order_number|string
-              order_owner: 若提交，必须仍等于当前 token 对应 openid|string
-              order_source: order_source|string
-              order_status: order_status|string
-              order_source_id: order_source_id|string
-              order_snap:
-                order_snap字段|string: order_snap值|string
-              order_amount: order_amount|number
-              order_remark: order_remark|string
-      responses:
-        "200":
-          description: 更新成功
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseOrderRecord
-              example:
-                id: PocketBase 记录主键|string
-                collectionId: collectionId|string
-                collectionName: collectionName|string
-                created: 记录创建时间|string
-                updated: 记录更新时间|string
-                order_id: 订单业务 ID|string
-                order_number: 订单编号|string
-                order_create: 订单创建时间，由数据库自动生成|string
-                order_owner: 订单所有者 openid|string
-                order_source: 订单来源|string
-                order_status: 订单状态|string
-                order_source_id: 来源关联业务 ID|string
-                order_snap:
-                  order_snap字段|string: order_snap值|string
-                order_amount: 订单金额|number
-                order_remark: 备注|string
-        "400":
-          description: 参数错误或违反字段约束
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "401":
-          description: token 缺失、无效或已过期
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 记录不存在或不满足 updateRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-    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
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "404":
-          description: 记录不存在或不满足 deleteRule
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
-        "500":
-          description: 服务端错误
-          content:
-            application/json:
-              schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
-              example:
-                code: 业务状态码|integer
-                message: message|string
-                data:
-                  业务响应数据字段|string: 业务响应数据值|string
+                $ref: '#/components/schemas/PocketBaseNativeError'
 components:
   schemas:
-    ApiResponseBase:
-      type: object
-      required:
-        - statusCode
-        - errMsg
-        - data
-      properties:
-        statusCode:
-          type:
-            - integer
-            - string
-          description: 业务状态码
-          example: 业务状态码 | integer
-        errMsg:
-          type: string
-          description: 业务提示信息
-          example: 业务提示信息 | string
-        data:
-          description: 业务响应数据
-          type: object
-          additionalProperties: true
-      example:
-        statusCode: 业务状态码|integer
-        errMsg: 业务提示信息|string
-        data:
-          业务响应数据字段|string: 业务响应数据值|string
-    ErrorResponse:
-      type: object
-      required:
-        - statusCode
-        - errMsg
-        - data
-      properties:
-        statusCode:
-          type:
-            - integer
-            - string
-          description: 业务状态码
-          example: 业务状态码 | integer
-        errMsg:
-          type: string
-          description: 业务提示信息
-          example: 失败原因提示 | string
-        data:
-          description: 业务响应数据
-          type: object
-          additionalProperties: true
-      example:
-        statusCode: 业务状态码|integer
-        errMsg: 业务提示信息|string
-        data:
-          业务响应数据字段|string: 业务响应数据值|string
-    HookRecordBase:
-      type: object
-      properties:
-        pb_id:
-          type: string
-          description: PocketBase 记录主键 id
-          example: l2r3nq7rqhuob0h
-        created:
-          type: string
-          description: PocketBase 系统创建时间
-          example: 2026-04-03 15:30:00.000Z
-        updated:
-          type: string
-          description: PocketBase 系统更新时间
-          example: 2026-04-03 15:35:00.000Z
-      example:
-        pb_id: PocketBase 记录主键 id|string
-        created: PocketBase 系统创建时间|string
-        updated: PocketBase 系统更新时间|string
     PocketBaseNativeError:
       type: object
       properties:
         code:
-          type:
-            - integer
-            - string
-          description: 业务状态码
-          example: 错误状态码 | integer
+          type: [integer, string]
+          description: PocketBase错误码
         message:
           type: string
-          example: PocketBase原生错误信息 | string
+          description: PocketBase错误信息
         data:
-          description: 业务响应数据
           type: object
           additionalProperties: true
+          description: PocketBase错误数据
       example:
-        code: 业务状态码|integer
-        message: message|string
+        code: 错误状态码|integer
+        message: PocketBase原生错误信息|string
         data:
-          业务响应数据字段|string: 业务响应数据值|string
+          字段名|string: 字段值|string
     PocketBaseRecordBase:
       type: object
-      required:
-        - id
-        - collectionId
-        - collectionName
-        - created
-        - updated
+      required: [id, collectionId, collectionName, created, updated]
       properties:
         id:
           type: string
-          description: PocketBase 记录主键
-          example: PocketBase记录主键 | string
+          description: PocketBase记录主键
         collectionId:
           type: string
-          example: 集合ID | string
+          description: 集合ID
         collectionName:
           type: string
-          example: 集合名称 | string
+          description: 集合名称
         created:
           type: string
           description: 记录创建时间
-          example: 记录创建时间 | string
         updated:
           type: string
           description: 记录更新时间
-          example: 记录更新时间 | string
       example:
-        id: PocketBase 记录主键|string
-        collectionId: collectionId|string
-        collectionName: collectionName|string
+        id: PocketBase记录主键|string
+        collectionId: 集合ID|string
+        collectionName: 集合名称|string
         created: 记录创建时间|string
         updated: 记录更新时间|string
     PocketBaseOrderFields:
@@ -1028,34 +271,26 @@ components:
       properties:
         order_id:
           type: string
-          description: 订单业务 ID
-          example: ORDER-1770000000000-abc123
+          description: 订单业务ID
         order_number:
           type: string
           description: 订单编号
-          example: wx-user-20260403153500
         order_create:
           type: string
-          description: 订单创建时间，由数据库自动生成
-          example: 2026-04-03 15:35:00.000Z
+          description: 订单创建时间
         order_owner:
           type: string
-          description: 订单所有者 openid
-          example: wx-openid-user-001
+          description: 订单所有者openid
         order_source:
           type: string
           description: 订单来源
-          example: 购物车
         order_status:
           type: string
           description: 订单状态
-          example: 订单已生成
         order_source_id:
           type: string
-          description: 来源关联业务 ID
-          example: CART-1770000000000-abc123
+          description: 来源关联业务ID
         order_snap:
-          description: 订单快照 JSON
           oneOf:
             - type: object
               additionalProperties: true
@@ -1063,60 +298,32 @@ components:
               items:
                 type: object
                 additionalProperties: true
+          description: 订单快照
         order_amount:
-          type:
-            - number
-            - integer
+          type: [number, integer]
           description: 订单金额
-          example: 3998
         order_remark:
           type: string
           description: 备注
-          example: 小程序订单示例
       example:
-        order_id: 订单业务 ID|string
+        order_id: 订单业务ID|string
         order_number: 订单编号|string
-        order_create: 订单创建时间，由数据库自动生成|string
-        order_owner: 订单所有者 openid|string
+        order_create: 订单创建时间|string
+        order_owner: 订单所有者openid|string
         order_source: 订单来源|string
         order_status: 订单状态|string
-        order_source_id: 来源关联业务 ID|string
+        order_source_id: 来源关联业务ID|string
         order_snap:
-          order_snap字段|string: order_snap值|string
+          字段名|string: 字段值|string
         order_amount: 订单金额|number
         order_remark: 备注|string
     PocketBaseOrderRecord:
       allOf:
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseOrderFields
-      example:
-        id: PocketBase 记录主键|string
-        collectionId: collectionId|string
-        collectionName: collectionName|string
-        created: 记录创建时间|string
-        updated: 记录更新时间|string
-        order_id: 订单业务 ID|string
-        order_number: 订单编号|string
-        order_create: 订单创建时间，由数据库自动生成|string
-        order_owner: 订单所有者 openid|string
-        order_source: 订单来源|string
-        order_status: 订单状态|string
-        order_source_id: 来源关联业务 ID|string
-        order_snap:
-          order_snap字段|string: order_snap值|string
-        order_amount: 订单金额|number
-        order_remark: 备注|string
+        - $ref: '#/components/schemas/PocketBaseRecordBase'
+        - $ref: '#/components/schemas/PocketBaseOrderFields'
     PocketBaseOrderCreateRequest:
       type: object
-      required:
-        - order_id
-        - order_number
-        - order_owner
-        - order_source
-        - order_status
-        - order_source_id
-        - order_snap
-        - order_amount
+      required: [order_id, order_number, order_owner, order_source, order_status, order_source_id, order_snap, order_amount]
       properties:
         order_id:
           type: string
@@ -1124,7 +331,6 @@ components:
           type: string
         order_owner:
           type: string
-          description: 必须显式提交，且值必须等于当前 token 对应 openid
         order_source:
           type: string
         order_status:
@@ -1140,22 +346,9 @@ components:
                 type: object
                 additionalProperties: true
         order_amount:
-          type:
-            - number
-            - integer
+          type: [number, integer]
         order_remark:
           type: string
-      example:
-        order_id: order_id|string
-        order_number: order_number|string
-        order_owner: 必须显式提交，且值必须等于当前 token 对应 openid|string
-        order_source: order_source|string
-        order_status: order_status|string
-        order_source_id: order_source_id|string
-        order_snap:
-          order_snap字段|string: order_snap值|string
-        order_amount: order_amount|number
-        order_remark: order_remark|string
     PocketBaseOrderUpdateRequest:
       type: object
       properties:
@@ -1163,7 +356,6 @@ components:
           type: string
         order_owner:
           type: string
-          description: 若提交，必须仍等于当前 token 对应 openid
         order_source:
           type: string
         order_status:
@@ -1179,69 +371,22 @@ components:
                 type: object
                 additionalProperties: true
         order_amount:
-          type:
-            - number
-            - integer
+          type: [number, integer]
         order_remark:
           type: string
-      example:
-        order_number: order_number|string
-        order_owner: 若提交，必须仍等于当前 token 对应 openid|string
-        order_source: order_source|string
-        order_status: order_status|string
-        order_source_id: order_source_id|string
-        order_snap:
-          order_snap字段|string: order_snap值|string
-        order_amount: order_amount|number
-        order_remark: order_remark|string
     PocketBaseOrderListResponse:
       type: object
-      required:
-        - page
-        - perPage
-        - totalItems
-        - totalPages
-        - items
+      required: [page, perPage, totalItems, totalPages, items]
       properties:
         page:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         perPage:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         totalItems:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         totalPages:
-          type:
-            - integer
-            - string
+          type: [integer, string]
         items:
           type: array
           items:
-            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseOrderRecord
-      example:
-        page: page|integer
-        perPage: perPage|integer
-        totalItems: totalItems|integer
-        totalPages: totalPages|integer
-        items:
-          - id: PocketBase 记录主键|string
-            collectionId: collectionId|string
-            collectionName: collectionName|string
-            created: 记录创建时间|string
-            updated: 记录更新时间|string
-            order_id: 订单业务 ID|string
-            order_number: 订单编号|string
-            order_create: 订单创建时间，由数据库自动生成|string
-            order_owner: 订单所有者 openid|string
-            order_source: 订单来源|string
-            order_status: 订单状态|string
-            order_source_id: 来源关联业务 ID|string
-            order_snap:
-              order_snap字段|string: order_snap值|string
-            order_amount: 订单金额|number
-            order_remark: 备注|string
+            $ref: '#/components/schemas/PocketBaseOrderRecord'
diff --git a/pocket-base/spec/openapi-wx/products.yaml b/pocket-base/spec/openapi-wx/products.yaml
index bb43a17..7f10e70 100644
--- a/pocket-base/spec/openapi-wx/products.yaml
+++ b/pocket-base/spec/openapi-wx/products.yaml
@@ -1,5 +1,17 @@
+openapi: 3.1.0
+info:
+  title: BAI PocketBase Native API - Products
+  version: 1.0.0
+  description: |
+    PocketBase 原生 `tbl_product_list` records API 文档。
+    本文件可单独导入使用，不依赖其他 YAML。
+servers:
+  - url: https://bai-api.blv-oa.com
+    description: 生产环境
+  - url: http://localhost:8090
+    description: PocketBase 本地环境
 paths:
-  productRecords:
+  /pb/api/collections/tbl_product_list/records:
     get:
       operationId: getPocketBaseProductListRecords
       tags:
@@ -30,7 +42,7 @@ paths:
             推荐写法：`prod_list_category="<产品分类>"`
           schema:
             type: string
-          example: prod_list_category="<产品分类>"
+          example: 过滤表达式|string
         - name: page
           in: query
           required: false
@@ -57,14 +69,14 @@ paths:
             - `prod_list_sort`：按分类排序值从小到大
           schema:
             type: string
-          example: prod_list_sort
+          example: 排序表达式|string
       responses:
         "200":
           description: 查询成功
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseProductListListResponse
+                $ref: #/components/schemas/PocketBaseProductListListResponse
               example:
                 page: page|integer
                 perPage: perPage|integer
@@ -79,6 +91,7 @@ paths:
                     prod_list_id: 产品列表业务 ID，唯一标识|string
                     prod_list_name: 产品名称|string
                     prod_list_modelnumber: 产品型号|string
+                    prod_list_barcode: 产品料号|string
                     prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
                     prod_list_description: 产品说明|string
                     prod_list_feature: 产品特色|string
@@ -103,7 +116,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -114,7 +127,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -125,7 +138,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseNativeError
+                $ref: #/components/schemas/PocketBaseNativeError
               example:
                 code: 业务状态码|integer
                 message: message|string
@@ -202,6 +215,10 @@ components:
           type: string
           description: 产品型号
           example: <产品型号>|<string>
+        prod_list_barcode:
+          type: string
+          description: 产品料号
+          example: <产品料号>|<string>
         prod_list_icon:
           type: string
           description: 产品图标附件 ID，保存 `tbl_attachments.attachments_id`
@@ -242,7 +259,7 @@ components:
             - number
             - integer
           description: 排序值（同分类内按升序）
-          example: 10
+          example: 排序值|number
         prod_list_comm_type:
           type: string
           description: 通讯类型
@@ -268,7 +285,7 @@ components:
             - number
             - integer
           description: 基础价格
-          example: 1999
+          example: 基础价格|number
         prod_list_vip_price:
           type: array
           description: 会员价数组，每项包含会员等级枚举值与价格
@@ -282,10 +299,10 @@ components:
                 type:
                   - number
                   - integer
-                example: 1899
+                example: 会员价格|number
           example:
-            - viplevel: VIP1
-              price: 1899
+            - viplevel: 会员等级|string
+              price: 会员价格|number
         prod_list_remark:
           type: string
           description: 备注
@@ -294,6 +311,7 @@ components:
         prod_list_id: 产品列表业务 ID，唯一标识|string
         prod_list_name: 产品名称|string
         prod_list_modelnumber: 产品型号|string
+        prod_list_barcode: 产品料号|string
         prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
         prod_list_description: 产品说明|string
         prod_list_feature: 产品特色|string
@@ -315,8 +333,8 @@ components:
         prod_list_remark: 备注|string
     PocketBaseProductListRecord:
       allOf:
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseRecordBase
-        - $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseProductListFields
+        - $ref: #/components/schemas/PocketBaseRecordBase
+        - $ref: #/components/schemas/PocketBaseProductListFields
       example:
         id: PocketBase 记录主键|string
         collectionId: collectionId|string
@@ -326,6 +344,7 @@ components:
         prod_list_id: 产品列表业务 ID，唯一标识|string
         prod_list_name: 产品名称|string
         prod_list_modelnumber: 产品型号|string
+        prod_list_barcode: 产品料号|string
         prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
         prod_list_description: 产品说明|string
         prod_list_feature: 产品特色|string
@@ -377,7 +396,7 @@ components:
         items:
           type: array
           items:
-            $ref: ../openapi-wx.yaml#/components/schemas/PocketBaseProductListRecord
+            $ref: #/components/schemas/PocketBaseProductListRecord
       example:
         page: page|integer
         perPage: perPage|integer
@@ -392,6 +411,7 @@ components:
             prod_list_id: 产品列表业务 ID，唯一标识|string
             prod_list_name: 产品名称|string
             prod_list_modelnumber: 产品型号|string
+            prod_list_barcode: 产品料号|string
             prod_list_icon: 产品图标附件 ID，保存 tbl_attachments.attachments_id|string
             prod_list_description: 产品说明|string
             prod_list_feature: 产品特色|string
diff --git a/pocket-base/spec/openapi.yaml b/pocket-base/spec/openapi.yaml
deleted file mode 100644
index 2709804..0000000
--- a/pocket-base/spec/openapi.yaml
+++ /dev/null
@@ -1,1891 +0,0 @@
-openapi: 3.1.0
-info:
-  title: BAI PocketBase Hooks API
-  description: |
-    基于 PocketBase `bai_api_pb_hooks` 的对外接口文档，可直接导入 Postman。
-    当前 `tbl_auth_users.openid` 已被定义为全平台统一身份锚点：
-    - 微信用户：`openid = 微信 openid`
-    - 平台用户：`openid = 服务端生成的 GUID`
-    请在 Apifox 环境中统一设置全局 Header：`Authorization: Bearer {{token}}`。
-  version: 1.0.0
-servers:
-  - url: https://bai-api.blv-oa.com
-    description: 生产环境
-  - url: http://localhost:8090
-    description: PocketBase 本地环境
-tags:
-  - name: 系统
-    description: 基础检查接口
-  - name: 微信认证
-    description: 面向微信用户的认证接口；认证成功后仍统一使用全平台 `openid` 与 PocketBase 原生 token。
-  - name: 平台认证
-    description: 面向平台用户的认证接口；平台用户会生成 GUID 并写入统一 `openid` 字段。
-  - name: 字典管理
-    description: 字典读接口公开；字典写接口面向 ManagePlatform 用户。
-  - name: 附件管理
-    description: 面向 ManagePlatform 用户的附件上传、查询与删除接口。
-  - name: 文档管理
-    description: 面向 ManagePlatform 用户的文档新增、查询、修改、删除接口；查询时会自动返回关联附件的 PocketBase 文件流链接。
-  - name: 文档历史
-    description: 面向 ManagePlatform 用户的文档操作历史查询接口。
-components:
-  schemas:
-    ApiResponse:
-      type: object
-      required: [statusCode, errMsg, data]
-      properties:
-        statusCode:
-          type: integer
-          description: "业务状态码"
-          example: 200
-        errMsg:
-          type: string
-          description: "业务提示信息"
-          example: 操作成功
-        data:
-          description: "业务响应数据"
-          type: object
-          additionalProperties: true
-    HealthData:
-      type: object
-      properties:
-        status:
-          type: string
-          example: healthy
-        version:
-          type: string
-          description: 当前已部署 hooks 版本号，用于确认发布是否生效
-          example: 2026.03.26-health-probe.1
-        timestamp:
-          type: string
-          format: date-time
-    UsersCountData:
-      type: object
-      properties:
-        total_users:
-          type: integer
-          description: tbl_auth_users 表中的用户总数
-          example: 128
-    HelloWorldData:
-      type: object
-      properties:
-        message:
-          type: string
-          example: Hello, World!
-        timestamp:
-          type: string
-          format: date-time
-        status:
-          type: string
-          example: success
-        build_time:
-          anyOf:
-            - type: string
-              format: date-time
-            - type: 'null'
-    CompanyInfo:
-      description: 用户所属公司信息；当用户尚未绑定公司时返回 `null`
-      anyOf:
-        - type: object
-          properties:
-            pb_id:
-              type: string
-              description: PocketBase 记录主键 id
-            company_id:
-              type: string
-              description: 公司业务 id，由数据库自动生成
-            company_name:
-              type: string
-              description: 公司名称
-            company_type:
-              type: string
-              description: 公司类型
-            company_entity:
-              type: string
-              description: 公司法人
-            company_usci:
-              type: string
-              description: 统一社会信用代码
-            company_nationality:
-              type: string
-              description: 国家名称
-            company_nationality_code:
-              type: string
-              description: 国家编码
-            company_province:
-              type: string
-              description: 省份名称
-            company_province_code:
-              type: string
-              description: 省份编码
-            company_city:
-              type: string
-              description: 城市名称
-            company_city_code:
-              type: string
-              description: 城市编码
-            company_district:
-              type: string
-              description: 区/县名称
-            company_district_code:
-              type: string
-              description: 区/县编码
-            company_postalcode:
-              type: string
-              description: 邮政编码
-            company_add:
-              type: string
-              description: 公司地址
-            company_status:
-              type: string
-              description: 公司状态
-            company_level:
-              type: string
-              description: 公司等级
-            company_owner_openid:
-              type: string
-              description: 公司所有者 openid
-            company_remark:
-              type: string
-              description: 备注
-            created:
-              type: string
-              description: 记录创建时间
-            updated:
-              type: string
-              description: 记录更新时间
-        - type: 'null'
-    UserInfo:
-      type: object
-      description: |
-        统一用户视图。
-        其中 `openid` 为全平台统一身份标识：微信用户使用微信 openid，平台用户使用服务端生成 GUID。
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        users_convers_id:
-          description: "会话侧用户 ID"
-          type: string
-        users_id:
-          description: "用户业务 ID"
-          type: string
-        users_idtype:
-          description: 用户身份来源类型
-          anyOf:
-            - type: string
-              enum: [WeChat, ManagePlatform]
-            - type: string
-        users_id_number:
-          description: "证件号"
-          type: string
-        users_status:
-          description: "用户状态"
-          type: string
-        users_rank_level:
-          description: "用户星级数值"
-          type: [number, string]
-        users_auth_type:
-          description: "账户类型"
-          type: [number, string]
-        users_type:
-          description: "用户类型"
-          anyOf:
-            - type: string
-              enum: [游客, 注册用户]
-            - type: string
-        users_name:
-          description: "用户姓名 / 昵称"
-          type: string
-        users_phone:
-          description: "手机号"
-          type: string
-        users_phone_masked:
-          type: string
-        users_level:
-          type: string
-          description: 用户等级
-        users_level_name:
-          type: string
-          description: 用户等级名称，按 `users_level -> 数据-会员等级` 字典描述实时解析
-        users_tag:
-          type: string
-          description: 用户标签
-        users_picture:
-          type: string
-          description: 用户头像附件的 `attachments_id`
-        users_picture_url:
-          type: string
-          description: 根据 `users_picture -> tbl_attachments` 自动解析出的头像文件流链接
-        users_id_pic_a:
-          type: string
-          description: 证件正面附件的 `attachments_id`
-        users_id_pic_a_url:
-          type: string
-          description: 根据 `users_id_pic_a -> tbl_attachments` 自动解析出的文件流链接
-        users_id_pic_b:
-          type: string
-          description: 证件反面附件的 `attachments_id`
-        users_id_pic_b_url:
-          type: string
-          description: 根据 `users_id_pic_b -> tbl_attachments` 自动解析出的文件流链接
-        users_title_picture:
-          type: string
-          description: 资质附件的 `attachments_id`
-        users_title_picture_url:
-          type: string
-          description: 根据 `users_title_picture -> tbl_attachments` 自动解析出的文件流链接
-        openid:
-          type: string
-          description: 全平台统一身份标识；微信用户为微信 openid，平台用户为服务端生成的 GUID
-        company_id:
-          type: string
-          description: 公司业务 id，存储 `tbl_company.company_id`
-        users_parent_id:
-          type: string
-          description: 上级用户业务 id
-        users_promo_code:
-          type: string
-          description: 推广码
-        usergroups_id:
-          type: string
-          description: 用户组业务 id
-        company:
-          $ref: '#/components/schemas/CompanyInfo'
-        created:
-          type: string
-          description: 用户创建时间
-        updated:
-          type: string
-          description: 用户更新时间
-      example:
-        pb_id: PocketBase记录主键id | string
-        users_convers_id: 会话侧用户ID | string
-        users_id: 用户业务ID | string
-        users_idtype: 用户身份来源类型 | string
-        users_id_number: 证件号 | string
-        users_type: 用户类型 | string
-        users_name: 用户姓名或昵称 | string
-        users_status: 用户状态 | string
-        users_rank_level: 用户星级数值 | number
-        users_auth_type: 账户类型 | number
-        users_phone: 手机号 | string
-        users_phone_masked: 手机号脱敏值 | string
-        users_level: 用户等级 | string
-        users_level_name: 用户等级名称 | string
-        users_tag: 用户标签 | string
-        users_picture: 用户头像附件ID | string
-        users_picture_url: 用户头像文件流链接 | string
-        users_id_pic_a: 证件正面附件ID | string
-        users_id_pic_a_url: 证件正面文件流链接 | string
-        users_id_pic_b: 证件反面附件ID | string
-        users_id_pic_b_url: 证件反面文件流链接 | string
-        users_title_picture: 资质附件ID | string
-        users_title_picture_url: 资质附件文件流链接 | string
-        openid: 全平台统一身份标识 | string
-        company_id: 公司业务id | string
-        users_parent_id: 上级用户业务id | string
-        users_promo_code: 推广码 | string
-        usergroups_id: 用户组业务id | string
-        company:
-          pb_id: PocketBase记录主键id | 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
-          created: 记录创建时间 | string
-          updated: 记录更新时间 | string
-        created: 用户创建时间 | string
-        updated: 用户更新时间 | string
-    PocketBaseAuthResponse:
-      type: object
-      description: |
-        项目统一认证响应。
-        所有对外接口统一返回 `statusCode`、`errMsg`、`data`，认证成功时额外返回顶层 `token`。
-      properties:
-        statusCode:
-          type: integer
-          description: "业务状态码"
-          example: 200
-        errMsg:
-          type: string
-          description: "业务提示信息"
-          example: 登录成功
-        data:
-          description: "业务响应数据"
-          type: object
-          properties:
-            status:
-              anyOf:
-                - type: string
-                  enum: [register_success, login_success]
-                - type: string
-            is_info_complete:
-              type: [boolean, string]
-            user:
-              $ref: '#/components/schemas/UserInfo'
-        token:
-          type: string
-          description: PocketBase 原生 auth token；仅认证类接口在成功时额外返回
-      example:
-        statusCode: 200
-        errMsg: 登录成功
-        data:
-          status: 登录或注册状态 | string
-          is_info_complete: 资料是否完整 | boolean
-          user:
-            pb_id: PocketBase记录主键id | string
-            users_id: 用户业务ID | string
-            users_idtype: 用户身份来源类型 | string
-            users_name: 用户姓名或昵称 | string
-            users_phone: 手机号 | string
-            users_phone_masked: 手机号脱敏值 | string
-            users_status: 用户状态 | string
-            users_rank_level: 用户星级数值 | number
-            users_auth_type: 账户类型 | number
-            users_type: 用户类型 | string
-            users_picture: 用户头像附件ID | string
-            users_picture_url: 用户头像文件流链接 | string
-            users_id_pic_a: 证件正面附件ID | string
-            users_id_pic_a_url: 证件正面文件流链接 | string
-            users_id_pic_b: 证件反面附件ID | string
-            users_id_pic_b_url: 证件反面文件流链接 | string
-            users_title_picture: 资质附件ID | string
-            users_title_picture_url: 资质附件文件流链接 | string
-            openid: 全平台统一身份标识 | string
-            company_id: 公司业务id | string
-            users_parent_id: 上级用户业务id | string
-            users_promo_code: 推广码 | string
-            usergroups_id: 用户组业务id | string
-            company:
-              pb_id: PocketBase记录主键id | 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
-              created: 记录创建时间 | string
-              updated: 记录更新时间 | string
-            created: 用户创建时间 | string
-            updated: 用户更新时间 | string
-        token: PocketBase原生认证token | string
-    WechatLoginRequest:
-      type: object
-      required: [users_wx_code]
-      description: 微信小程序登录/注册请求体。
-      properties:
-        users_wx_code:
-          type: string
-          description: 微信小程序登录临时凭证 code
-          example: 0a1b2c3d4e5f6g
-    WechatProfileRequest:
-      type: object
-      description: 微信用户资料完善请求体。
-      properties:
-        users_name:
-          type: string
-          description: "用户姓名 / 昵称"
-          example: 张三
-        users_phone_code:
-          type: string
-          description: 可选。若传入，服务端优先通过微信接口换取真实手机号并写入数据库
-          example: 2b7d9f2e3c4a5b6d7e8f
-        users_phone:
-          type: string
-          description: 可选。未传 `users_phone_code` 时，可直接写入手机号
-          example: '13800138000'
-        users_type:
-          type: string
-          description: 可选。用户类型；仅在传入非空值时更新
-          example: 服务商
-        company_id:
-          type: string
-          description: 可选。公司业务 id；仅在传入非空值时更新
-          example: WX-COMPANY-10001
-        users_tag:
-          type: string
-          description: 可选。用户标签；非空时才更新
-          example: 核心客户
-        users_picture:
-          type: string
-          description: 可选。用户头像附件的 `attachments_id`
-          example: ATT-1743123456789-abc123
-        users_id_pic_a:
-          type: string
-          description: 可选。证件正面附件的 `attachments_id`
-        users_id_pic_b:
-          type: string
-          description: 可选。证件反面附件的 `attachments_id`
-        users_title_picture:
-          type: string
-          description: 可选。资质附件的 `attachments_id`
-    WechatProfileResponseData:
-      type: object
-      properties:
-        status:
-          type: string
-          enum: [update_success]
-        user:
-          $ref: '#/components/schemas/UserInfo'
-    PlatformRegisterRequest:
-      type: object
-      required: [users_name, users_phone, password, passwordConfirm, users_picture]
-      description: 平台用户注册请求体；注册成功后将生成 GUID 并写入统一 `openid` 字段。
-      properties:
-        users_name:
-          type: string
-          description: "用户姓名 / 昵称"
-          example: 张三
-        users_phone:
-          type: string
-          description: "手机号"
-          example: '13800138000'
-        password:
-          type: string
-          description: "PocketBase 认证密码"
-          example: '12345678'
-        passwordConfirm:
-          type: string
-          example: '12345678'
-        users_picture:
-          type: string
-          description: 用户头像附件的 `attachments_id`
-          example: ATT-1743123456789-abc123
-        users_id_number:
-          description: "证件号"
-          type: string
-        users_id_pic_a:
-          type: string
-          description: 可选。证件正面附件的 `attachments_id`
-        users_id_pic_b:
-          type: string
-          description: 可选。证件反面附件的 `attachments_id`
-        users_title_picture:
-          type: string
-          description: 可选。资质附件的 `attachments_id`
-        users_level:
-          description: "用户等级文本"
-          type: string
-        users_tag:
-          description: "用户标签"
-          type: string
-        users_type:
-          description: "用户类型"
-          type: string
-        company_id:
-          description: "所属公司业务 ID"
-          type: string
-        users_parent_id:
-          description: "上级用户业务 ID"
-          type: string
-        users_promo_code:
-          description: "推广码"
-          type: string
-        usergroups_id:
-          description: "用户组 / 角色 ID"
-          type: string
-    PlatformLoginRequest:
-      type: object
-      required: [login_account, password]
-      description: 平台用户登录请求体；前端使用邮箱或手机号 + 密码提交，服务端内部转换为 PocketBase 原生 password auth。
-      properties:
-        login_account:
-          type: string
-          description: 支持邮箱或手机号
-          example: admin@example.com
-        password:
-          type: string
-          description: "PocketBase 认证密码"
-          example: '12345678'
-    SystemRefreshTokenRequest:
-      type: object
-      description: |
-        系统刷新 token 请求体。
-        `users_wx_code` 允许为空。
-        当 `Authorization` 对应 token 有效时，可不传或传空；
-        当 token 失效时，需提供 `users_wx_code` 走微信 code 重新签发流程。
-      properties:
-        users_wx_code:
-          anyOf:
-            - type: string
-            - type: 'null'
-          description: 微信小程序登录临时凭证 code
-          example: 0a1b2c3d4e5f6g
-    RefreshTokenData:
-      type: object
-      properties: {}
-    DictionaryItem:
-      type: object
-      required: [enum, description, sortOrder]
-      properties:
-        enum:
-          type: string
-          example: enabled
-        description:
-          type: string
-          example: 启用
-        image:
-          type: string
-          description: 对应图片附件的 `attachments_id`，允许为空
-          example: ATT-1743037200000-abc123
-        imageUrl:
-          type: string
-          description: 根据 `image -> tbl_attachments` 自动解析出的图片文件流链接
-        imageAttachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        sortOrder:
-          type: integer
-          example: 1
-      example:
-        enum: enabled
-        description: 启用
-        image: ATT-1743037200000-abc123
-        imageUrl: https://bai-api.blv-oa.com/api/files/tbl_attachments/a1/enabled.png
-        imageAttachment:
-          attachments_id: ATT-1743037200000-abc123
-          attachments_filename: enabled.png
-        sortOrder: 1
-    DictionaryRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        system_dict_id:
-          description: "字典业务 ID"
-          type: string
-        dict_name:
-          description: "字典名称，当前按全局唯一维护"
-          type: string
-        dict_word_is_enabled:
-          description: "字典是否启用"
-          type: boolean
-        dict_word_parent_id:
-          description: "父级字典业务 ID"
-          type: string
-        dict_word_remark:
-          description: "备注"
-          type: string
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/DictionaryItem'
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: y3qk5cuirz515d6
-        system_dict_id: DICT-1774599144591-hAEFQj
-        dict_name: 类型-发现页菜单
-        dict_word_is_enabled: true
-        dict_word_parent_id: ''
-        dict_word_remark: 首页菜单字典
-        items:
-          - enum: UT1
-            description: 每日资讯
-            image: ATT-1743037200000-abc123
-            imageUrl: https://bai-api.blv-oa.com/api/files/tbl_attachments/a1/news.png
-            sortOrder: 1
-        created: '2026-03-28 07:20:00.000Z'
-        updated: '2026-03-29 08:00:00.000Z'
-    DictionaryListRequest:
-      type: object
-      properties:
-        keyword:
-          type: string
-          description: 对 `dict_name` 的模糊搜索关键字
-          example: 状态
-    DictionaryDetailRequest:
-      type: object
-      required: [dict_name]
-      properties:
-        dict_name:
-          type: string
-          description: "字典名称，当前按全局唯一维护"
-          example: 用户状态
-    DictionaryMutationRequest:
-      type: object
-      required: [dict_name, items]
-      properties:
-        original_dict_name:
-          type: string
-          description: 更新时用于定位原始记录；新增时可不传
-          example: 用户状态
-        dict_name:
-          type: string
-          description: "字典名称，当前按全局唯一维护"
-          example: 用户状态
-        dict_word_is_enabled:
-          type: boolean
-          description: "字典是否启用"
-          example: true
-        dict_word_parent_id:
-          type: string
-          description: "父级字典业务 ID"
-          example: ''
-        dict_word_remark:
-          type: string
-          description: "备注"
-          example: 系统状态字典
-        items:
-          type: array
-          minItems: 1
-          description: 每项会分别序列化写入 `dict_word_enum`、`dict_word_description`、`dict_word_image`、`dict_word_sort_order`
-          items:
-            $ref: '#/components/schemas/DictionaryItem'
-    DictionaryDeleteRequest:
-      type: object
-      required: [dict_name]
-      properties:
-        dict_name:
-          type: string
-          description: "字典名称，当前按全局唯一维护"
-          example: 用户状态
-    AttachmentRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        attachments_id:
-          description: "附件业务 ID"
-          type: string
-        attachments_link:
-          type: string
-          description: PocketBase 实际存储的文件名
-        attachments_url:
-          type: string
-          description: 附件文件流访问链接
-        attachments_download_url:
-          type: string
-          description: 附件下载链接
-        attachments_filename:
-          description: "原始文件名"
-          type: string
-        attachments_filetype:
-          description: "文件类型 / MIME"
-          type: string
-        attachments_size:
-          description: "文件大小"
-          type: number
-        attachments_owner:
-          description: "上传者业务标识"
-          type: string
-        attachments_md5:
-          description: "文件 MD5"
-          type: string
-        attachments_ocr:
-          description: "OCR 识别结果"
-          type: string
-        attachments_status:
-          description: "附件状态"
-          type: string
-        attachments_remark:
-          description: "备注"
-          type: string
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: a1b2c3d4e5f6g7h
-        attachments_id: ATT-1743037200000-abc123
-        attachments_link: enabled.png
-        attachments_url: https://bai-api.blv-oa.com/api/files/tbl_attachments/a1/enabled.png
-        attachments_download_url: https://bai-api.blv-oa.com/api/files/tbl_attachments/a1/enabled.png?download=1
-        attachments_filename: enabled.png
-        attachments_filetype: image/png
-        attachments_size: 24576
-        attachments_owner: app_momo
-        attachments_md5: 4b825dc642cb6eb9a060e54bf8d69288
-        attachments_ocr: ''
-        attachments_status: active
-        attachments_remark: 字典图标
-        created: '2026-03-28 07:20:00.000Z'
-        updated: '2026-03-29 08:00:00.000Z'
-    AttachmentListRequest:
-      type: object
-      properties:
-        keyword:
-          type: string
-          description: 对 `attachments_id`、`attachments_filename` 的模糊搜索关键字
-          example: 手册
-        status:
-          type: string
-          description: 按附件状态过滤
-          example: active
-    AttachmentDetailRequest:
-      type: object
-      required: [attachments_id]
-      properties:
-        attachments_id:
-          type: string
-          description: "附件业务 ID"
-          example: ATT-1743037200000-abc123
-    AttachmentUploadRequest:
-      type: object
-      required: [attachments_link]
-      properties:
-        attachments_link:
-          type: string
-          format: binary
-          description: 要上传到 `tbl_attachments` 的单个文件
-        attachments_filename:
-          type: string
-          description: 原始文件名；不传时可由前端直接使用文件名
-        attachments_filetype:
-          type: string
-          description: 文件 MIME 类型
-        attachments_size:
-          type: number
-          description: 文件大小
-        attachments_md5:
-          description: "文件 MD5"
-          type: string
-        attachments_ocr:
-          description: "OCR 识别结果"
-          type: string
-        attachments_status:
-          type: string
-          description: "附件状态"
-          example: active
-        attachments_remark:
-          description: "备注"
-          type: string
-    DocumentRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        document_id:
-          description: "文档业务 ID"
-          type: string
-        document_create:
-          type: string
-          description: 文档创建时间，由数据库自动生成
-        document_effect_date:
-          description: "文档生效日期"
-          type: string
-        document_expiry_date:
-          description: "文档到期日期"
-          type: string
-        document_type:
-          type: string
-          description: 多选时按 `system_dict_id@dict_word_enum|...` 保存
-        document_title:
-          description: "文档标题"
-          type: string
-        document_subtitle:
-          description: "文档副标题"
-          type: string
-        document_summary:
-          description: "文档摘要"
-          type: string
-        document_content:
-          description: "正文内容，保存 Markdown"
-          type: string
-        document_image:
-          type: string
-          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
-        document_image_ids:
-          type: array
-          description: "`document_image` 解析后的附件 id 列表"
-          items:
-            type: string
-        document_image_urls:
-          type: array
-          description: "根据 `document_image -> tbl_attachments` 自动解析出的图片文件流链接列表"
-          items:
-            type: string
-        document_image_url:
-          type: string
-          description: "兼容字段，返回第一张图片的文件流链接"
-        document_image_attachments:
-          type: array
-          items:
-            $ref: '#/components/schemas/AttachmentRecord'
-        document_image_attachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        document_video:
-          type: string
-          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
-        document_video_ids:
-          type: array
-          description: "`document_video` 解析后的附件 id 列表"
-          items:
-            type: string
-        document_video_urls:
-          type: array
-          description: "根据 `document_video -> tbl_attachments` 自动解析出的视频文件流链接列表"
-          items:
-            type: string
-        document_video_url:
-          type: string
-          description: "兼容字段，返回第一个视频的文件流链接"
-        document_video_attachments:
-          type: array
-          items:
-            $ref: '#/components/schemas/AttachmentRecord'
-        document_video_attachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        document_file:
-          type: string
-          description: "关联多个 `attachments_id`，底层使用 `|` 分隔保存"
-        document_file_ids:
-          type: array
-          description: "`document_file` 解析后的附件 id 列表"
-          items:
-            type: string
-        document_file_urls:
-          type: array
-          description: "根据 `document_file -> tbl_attachments` 自动解析出的文件流链接列表"
-          items:
-            type: string
-        document_file_url:
-          type: string
-          description: "兼容字段，返回第一个文件的文件流链接"
-        document_file_attachments:
-          type: array
-          items:
-            $ref: '#/components/schemas/AttachmentRecord'
-        document_file_attachment:
-          anyOf:
-            - $ref: '#/components/schemas/AttachmentRecord'
-            - type: 'null'
-        document_owner:
-          type: string
-          description: 上传者 openid
-        document_relation_model:
-          description: "关联机型 / 模型标识"
-          type: string
-        document_keywords:
-          type: string
-          description: 固定字典多选字段，使用 `|` 分隔
-        document_share_count:
-          description: "分享次数"
-          type: number
-        document_download_count:
-          description: "下载次数"
-          type: number
-        document_favorite_count:
-          description: "收藏次数"
-          type: number
-        document_status:
-          type: string
-          description: 文档状态，仅允许 `有效` 或 `过期`，由系统根据生效日期和到期日期自动计算；当两者都为空时默认 `有效`
-        document_embedding_status:
-          description: "文档嵌入状态"
-          type: string
-        document_embedding_error:
-          description: "文档嵌入错误原因"
-          type: string
-        document_embedding_lasttime:
-          description: "最后一次嵌入更新时间"
-          type: string
-        document_vector_version:
-          description: "向量版本号 / 模型名称"
-          type: string
-        document_product_categories:
-          type: string
-          description: 固定字典多选字段，使用 `|` 分隔
-        document_application_scenarios:
-          type: string
-          description: 固定字典多选字段，使用 `|` 分隔
-        document_hotel_type:
-          type: string
-          description: 固定字典多选字段，使用 `|` 分隔
-        document_remark:
-          description: "备注"
-          type: string
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: docpb_001
-        document_id: DOC-1774677099775-WtHUaJ
-        document_create: '2026-03-28 07:20:00.000Z'
-        document_effect_date: '2026-03-28'
-        document_expiry_date: '2027-03-28'
-        document_type: DICT-1774599144591-hAEFQj@UT1
-        document_title: 智能化重构补记行业价值新链条
-        document_subtitle: 每日资讯
-        document_summary: 文档摘要示例
-        document_content: '# 正文内容'
-        document_image: ATT-1743037200000-abc123|ATT-1743037200001-def456
-        document_image_ids:
-          - ATT-1743037200000-abc123
-        document_image_urls:
-          - https://bai-api.blv-oa.com/api/files/tbl_attachments/a1/news.png
-        document_image_url: https://bai-api.blv-oa.com/api/files/tbl_attachments/a1/news.png
-        document_video: ATT-1743037200002-ghi789
-        document_video_ids:
-          - ATT-1743037200002-ghi789
-        document_video_urls:
-          - https://bai-api.blv-oa.com/api/files/tbl_attachments/a2/demo.mp4
-        document_video_url: https://bai-api.blv-oa.com/api/files/tbl_attachments/a2/demo.mp4
-        document_file: ATT-1743037200003-jkl012
-        document_file_ids:
-          - ATT-1743037200003-jkl012
-        document_file_urls:
-          - https://bai-api.blv-oa.com/api/files/tbl_attachments/a3/manual.pdf
-        document_file_url: https://bai-api.blv-oa.com/api/files/tbl_attachments/a3/manual.pdf
-        document_owner: app_momo
-        document_relation_model: OR1
-        document_keywords: 酒店|智能化
-        document_share_count: 3
-        document_download_count: 12
-        document_favorite_count: 5
-        document_status: 有效
-        document_embedding_status: succeed
-        document_embedding_error: ''
-        document_embedding_lasttime: '2026-03-29'
-        document_vector_version: text-embedding-3-large
-        document_product_categories: OR1|AZ4
-        document_application_scenarios: 每日资讯
-        document_hotel_type: 高端酒店
-        document_remark: 文档备注
-        created: '2026-03-28 07:20:00.000Z'
-        updated: '2026-03-29 08:00:00.000Z'
-    DocumentListRequest:
-      type: object
-      properties:
-        keyword:
-          type: string
-          description: 对 `document_id`、`document_title`、`document_subtitle`、`document_summary`、`document_keywords` 的模糊搜索关键字
-          example: 安装
-        status:
-          type: string
-          example: active
-        document_type:
-          type: string
-          description: 支持按存储值过滤；多选时格式为 `system_dict_id@dict_word_enum|...`
-          example: 说明书
-    DocumentDetailRequest:
-      type: object
-      required: [document_id]
-      properties:
-        document_id:
-          type: string
-          description: "文档业务 ID"
-          example: DOC-1743037200000-abc123
-    DocumentMutationRequest:
-      type: object
-      required: [document_title, document_type]
-      properties:
-        document_id:
-          type: string
-          description: 创建时可不传，由服务端自动生成；更新时必填
-          example: DOC-1743037200000-abc123
-        document_effect_date:
-          type: string
-          description: 支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串
-          example: 2026-03-27
-        document_expiry_date:
-          type: string
-          description: 支持 `YYYY-MM-DD` 或 PocketBase 可识别日期时间字符串
-          example: 2027-03-27
-        document_type:
-          type: string
-          description: 必填；前端显示为字典项描述，存库时按 `system_dict_id@dict_word_enum|...` 保存
-        document_title:
-          description: "文档标题"
-          type: string
-        document_subtitle:
-          description: "文档副标题"
-          type: string
-        document_summary:
-          description: "文档摘要"
-          type: string
-        document_content:
-          description: "正文内容，保存 Markdown"
-          type: string
-        document_image:
-          oneOf:
-            - type: string
-              description: 多个图片附件 id 使用 `|` 分隔
-            - type: array
-              items:
-                type: string
-          description: 图片附件 id 列表；支持数组或 `|` 分隔字符串
-        document_video:
-          oneOf:
-            - type: string
-              description: 多个视频附件 id 使用 `|` 分隔
-            - type: array
-              items:
-                type: string
-          description: 视频附件 id 列表；支持数组或 `|` 分隔字符串
-        document_file:
-          oneOf:
-            - type: string
-              description: 多个文件附件 id 使用 `|` 分隔
-            - type: array
-              items:
-                type: string
-          description: 文件附件 id 列表；支持数组或 `|` 分隔字符串
-        document_relation_model:
-          description: "关联机型 / 模型标识"
-          type: string
-        document_keywords:
-          type: string
-          description: 从 `文档-关键词` 字典多选后使用 `|` 分隔保存
-        document_share_count:
-          description: "分享次数"
-          type: number
-        document_download_count:
-          description: "下载次数"
-          type: number
-        document_favorite_count:
-          description: "收藏次数"
-          type: number
-        document_status:
-          type: string
-          description: 文档状态，仅允许 `有效` 或 `过期`，由系统根据生效日期和到期日期自动计算；当两者都为空时默认 `有效`
-        document_embedding_status:
-          description: "文档嵌入状态"
-          type: string
-        document_embedding_error:
-          description: "文档嵌入错误原因"
-          type: string
-        document_embedding_lasttime:
-          description: "最后一次嵌入更新时间"
-          type: string
-        document_vector_version:
-          description: "向量版本号 / 模型名称"
-          type: string
-        document_product_categories:
-          type: string
-          description: 从 `文档-产品关联文档` 字典多选后使用 `|` 分隔保存
-        document_application_scenarios:
-          type: string
-          description: 从 `文档-筛选依据` 字典多选后使用 `|` 分隔保存
-        document_hotel_type:
-          type: string
-          description: 从 `文档-适用场景` 字典多选后使用 `|` 分隔保存
-        document_remark:
-          description: "备注"
-          type: string
-    DocumentDeleteRequest:
-      type: object
-      required: [document_id]
-      properties:
-        document_id:
-          type: string
-          description: "文档业务 ID"
-          example: DOC-1743037200000-abc123
-    DocumentHistoryRecord:
-      type: object
-      properties:
-        pb_id:
-          description: "PocketBase 记录主键 id"
-          type: string
-        doh_id:
-          description: "文档操作历史业务 ID"
-          type: string
-        doh_document_id:
-          description: "关联文档业务 ID"
-          type: string
-        doh_operation_type:
-          description: "操作类型"
-          type: string
-        doh_user_id:
-          description: "操作人业务 ID"
-          type: string
-        doh_current_count:
-          description: "本次操作对应次数"
-          type: number
-        doh_remark:
-          description: "备注"
-          type: string
-        created:
-          description: "记录创建时间"
-          type: string
-        updated:
-          description: "记录更新时间"
-          type: string
-      example:
-        pb_id: histpb_001
-        doh_id: DOH-1774677099775-WtHUaJ
-        doh_document_id: DOC-1774677099775-WtHUaJ
-        doh_operation_type: update
-        doh_user_id: app_momo
-        doh_current_count: 1
-        doh_remark: 更新文档
-        created: '2026-03-29 08:00:00.000Z'
-        updated: '2026-03-29 08:00:00.000Z'
-    DocumentHistoryListRequest:
-      type: object
-      properties:
-        document_id:
-          type: string
-          description: 可选；传入时仅查询指定文档的操作历史
-          example: DOC-1743037200000-abc123
-paths:
-  /pb/api/system/test-helloworld:
-    post:
-      tags: [系统]
-      summary: HelloWorld 测试接口
-      responses:
-        '200':
-          description: 成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/HelloWorldData'
-  /pb/api/system/health:
-    post:
-      tags: [系统]
-      summary: 健康检查
-      responses:
-        '200':
-          description: 成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/HealthData'
-  /pb/api/system/users-count:
-    post:
-      tags: [系统]
-      summary: 查询用户总数
-      description: 统计 `tbl_auth_users` 集合中的记录总数，并返回一个数值。
-      responses:
-        '200':
-          description: 成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/UsersCountData'
-  /pb/api/system/refresh-token:
-    post:
-      tags: [系统]
-      summary: 刷新系统认证 token
-      description: |
-        当前实现支持两种刷新路径：
-        1) 若 `Authorization` 对应 token 仍有效：直接按当前 auth record 续签（不调用微信接口）。
-        2) 若 token 已过期：仅在 body 提供 `users_wx_code` 时才走微信 code 重新签发。
-        返回体仅包含新的 `token`，不返回完整登录用户信息。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/SystemRefreshTokenRequest'
-      responses:
-        '200':
-          description: 刷新成功（返回精简 token）
-          content:
-            application/json:
-              schema:
-                allOf:
-                  - $ref: '#/components/schemas/ApiResponse'
-                  - type: object
-                    properties:
-                      token:
-                        type: string
-                        description: 新签发的 PocketBase 原生 auth token
-              example:
-                statusCode: 200
-                errMsg: 刷新成功
-                data: {}
-                token: eyJhbGciOi...
-        '400':
-          description: 参数错误或微信侧身份换取失败
-        '401':
-          description: token 无效/已过期，且未提供 users_wx_code
-        '404':
-          description: 用户不存在
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/wechat/login:
-    post:
-      tags: [微信认证]
-      summary: 微信登录/注册合一
-      description: |
-        使用微信 code 换取微信侧 openid，并写入统一身份字段 `tbl_auth_users.openid`。
-        若 `tbl_auth_users` 中不存在对应用户则自动创建 auth record，随后返回 PocketBase 原生 auth token。
-        首次注册创建时会写入 `users_idtype = WeChat`。
-        首次注册创建时，`users_level` 默认保持为空，不自动写入会员等级。
-        返回的 `token` 可直接用于 PocketBase SDK 与当前 hooks 接口调用。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/WechatLoginRequest'
-      responses:
-        '200':
-          description: 登录或注册成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseAuthResponse'
-        '400':
-          description: 参数错误或微信侧身份换取失败
-        '401':
-          description: PocketBase 原生认证失败
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-        '500':
-          description: 保存 auth 用户失败或服务端内部错误
-  /pb/api/platform/register:
-    post:
-      tags: [平台认证]
-      summary: 平台用户注册
-      description: |
-        创建平台用户 auth record。
-        服务端会自动生成 GUID 并写入统一身份字段 `openid`，同时写入 `users_idtype = ManagePlatform`。
-        前端以 `users_phone + password/passwordConfirm` 注册，但服务端仍会创建 PocketBase 原生 auth 用户。
-        首次注册创建时，`users_level` 默认保持为空，不自动写入会员等级。
-        注册成功后直接返回 PocketBase 原生 auth token。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PlatformRegisterRequest'
-      responses:
-        '200':
-          description: 注册成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseAuthResponse'
-        '400':
-          description: 参数错误或手机号已存在
-        '500':
-          description: GUID 生成失败、auth identity 缺失或保存用户失败
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/platform/login:
-    post:
-      tags: [平台认证]
-      summary: 平台用户登录
-      description: |
-        前端使用平台注册时保存的 `邮箱或手机号 + password` 登录。
-        仅允许 `users_idtype = ManagePlatform` 的用户通过该接口登录。
-        服务端会根据 `login_account` 自动判断邮箱或手机号，并定位平台用户，再使用该用户的 PocketBase 原生 identity（当前为 `email`）执行原生 password auth。
-        返回体中的 `user.users_level_name` 为服务端按“数据-会员等级”字典实时解析后的等级名称。
-        登录成功后直接返回 PocketBase 原生 auth token。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PlatformLoginRequest'
-              example:
-                login_account: '13509214696'
-                password: Momo123456
-      responses:
-        '200':
-          description: 登录成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PocketBaseAuthResponse'
-              example:
-                statusCode: 200
-                errMsg: 登录成功
-                data:
-                  status: login_success
-                  is_info_complete: false
-                  user:
-                    pb_id: vtukf6agem2xbcv
-                    users_id: ''
-                    users_idtype: ManagePlatform
-                    users_name: momo
-                    users_phone: '13509214696'
-                    users_phone_masked: '135****4696'
-                    users_status: ''
-                    users_rank_level: 0
-                    users_auth_type: 0
-                    users_type: 注册用户
-                    users_picture: ''
-                    openid: app_momo
-                    company_id: ''
-                    users_parent_id: ''
-                    users_promo_code: ''
-                    usergroups_id: ''
-                    company: null
-                    created: ''
-                    updated: ''
-                token: eyJhbGciOi...
-        '400':
-          description: 参数错误、密码错误或用户类型不匹配
-        '404':
-          description: 平台用户不存在
-        '500':
-          description: 平台用户缺少原生登录 identity 或服务端内部错误
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/wechat/profile:
-    post:
-      tags: [微信认证]
-      summary: 更新微信用户资料
-      description: |
-        基于当前 `Authorization` 对应 auth record 中的统一 `openid` 定位当前微信用户。
-        当前接口按“非空字段增量更新”处理资料完善。
-        若传入 `users_phone_code`，优先调用微信接口换取真实手机号；
-        若未传 `users_phone_code` 但传入 `users_phone`，则直接写入手机号；
-        未传或传空的字段不会清空数据库已有值。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/WechatProfileRequest'
-      responses:
-        '200':
-          description: 更新成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/WechatProfileResponseData'
-        '401':
-          description: token 无效或当前 auth record 缺少统一身份字段 openid
-        '400':
-          description: 参数错误、手机号已被注册、微信手机号换取失败或资料更新失败
-  /pb/api/dictionary/list:
-    post:
-      tags: [字典管理]
-      summary: 查询字典列表
-      description: |
-        公开读接口，无需 token。
-        支持按 `dict_name` 模糊搜索，返回字典全量信息，并将三个聚合字段组装为 `items`。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryListRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/DictionaryRecord'
-        '415':
-          description: 请求体必须为 application/json
-  /pb/api/dictionary/detail:
-    post:
-      tags: [字典管理]
-      summary: 查询指定字典
-      description: |
-        公开读接口，无需 token。
-        按唯一键 `dict_name` 查询单条字典，并返回组装后的 `items`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryDetailRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DictionaryRecord'
-        '400':
-          description: 参数错误
-        '404':
-          description: 未找到对应字典
-        '415':
-          description: 请求体必须为 application/json
-  /pb/api/dictionary/create:
-    post:
-      tags: [字典管理]
-      summary: 新增字典
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        `system_dict_id` 由服务端自动生成；`dict_name` 必须唯一；
-        `items` 会分别序列化写入 `dict_word_enum`、`dict_word_description`、`dict_word_image`、`dict_word_sort_order` 四个字段。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryMutationRequest'
-      responses:
-        '200':
-          description: 新增成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DictionaryRecord'
-        '400':
-          description: 参数错误或 dict_name 已存在
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/dictionary/update:
-    post:
-      tags: [字典管理]
-      summary: 修改字典
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        根据 `original_dict_name`（未传时回退为 `dict_name`）定位原记录并更新。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryMutationRequest'
-      responses:
-        '200':
-          description: 修改成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DictionaryRecord'
-        '400':
-          description: 参数错误或 dict_name 冲突
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到待修改字典
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/dictionary/delete:
-    post:
-      tags: [字典管理]
-      summary: 删除字典
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `dict_name` 真删除对应记录。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DictionaryDeleteRequest'
-      responses:
-        '200':
-          description: 删除成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  dict_name:
-                    description: "字典名称，当前按全局唯一维护"
-                    type: string
-        '400':
-          description: 参数错误或删除失败
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到待删除字典
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/attachment/list:
-    post:
-      tags: [附件管理]
-      summary: 查询附件列表
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        支持按 `attachments_id`、`attachments_filename` 模糊搜索，并可按 `attachments_status` 过滤。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AttachmentListRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/AttachmentRecord'
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '415':
-          description: 请求体必须为 application/json
-  /pb/api/attachment/detail:
-    post:
-      tags: [附件管理]
-      summary: 查询附件详情
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `attachments_id` 查询单条附件，并返回 PocketBase 文件流链接与下载链接。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AttachmentDetailRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/AttachmentRecord'
-        '400':
-          description: 参数错误
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到对应附件
-        '415':
-          description: 请求体必须为 application/json
-  /pb/api/attachment/upload:
-    post:
-      tags: [附件管理]
-      summary: 上传附件
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        使用 `multipart/form-data` 上传单个文件到 `tbl_attachments`，服务端会自动生成 `attachments_id`，
-        并返回可直接访问的 PocketBase 文件流链接。
-      requestBody:
-        required: true
-        content:
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/AttachmentUploadRequest'
-      responses:
-        '200':
-          description: 上传成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/AttachmentRecord'
-        '400':
-          description: 参数错误、缺少文件或附件保存失败
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-  /pb/api/attachment/delete:
-    post:
-      tags: [附件管理]
-      summary: 删除附件
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `attachments_id` 真删除附件；若附件已被 `tbl_document.document_image`、`document_video` 或 `document_file` 引用，则拒绝删除。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AttachmentDetailRequest'
-      responses:
-        '200':
-          description: 删除成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  attachments_id:
-                    description: "附件业务 ID"
-                    type: string
-        '400':
-          description: 参数错误、附件已被文档引用或删除失败
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到待删除附件
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/document/list:
-    post:
-      tags: [文档管理]
-      summary: 查询文档列表
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        支持按标题、摘要、关键词等字段模糊搜索，并可按 `document_status`、`document_type` 过滤。
-        返回结果会自动根据 `document_image`、`document_video`、`document_file` 中的多个 `attachments_id` 关联 `tbl_attachments`，
-        额外补充 `document_image_urls`、`document_video_urls`、`document_file_urls` 以及对应附件对象数组。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentListRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/DocumentRecord'
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '415':
-          description: 请求体必须为 application/json
-  /pb/api/document/detail:
-    post:
-      tags: [文档管理]
-      summary: 查询文档详情
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `document_id` 查询单条文档，并返回与附件表联动解析后的多文件流链接。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentDetailRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DocumentRecord'
-        '400':
-          description: 参数错误
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到对应文档
-        '415':
-          description: 请求体必须为 application/json
-  /pb/api/document/create:
-    post:
-      tags: [文档管理]
-      summary: 新增文档
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        `document_id` 可选；未传时服务端自动生成。
-        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        `document_image`、`document_video`、`document_file` 支持传入多个已存在于 `tbl_attachments` 的 `attachments_id`。
-        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `create`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentMutationRequest'
-      responses:
-        '200':
-          description: 新增成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DocumentRecord'
-        '400':
-          description: 参数错误、附件不存在或文档创建失败
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/document/update:
-    post:
-      tags: [文档管理]
-      summary: 修改文档
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `document_id` 定位现有文档并更新。
-        `document_title`、`document_type` 为必填；其余字段均允许为空。
-        若传入 `document_image`、`document_video`、`document_file`，则支持多个 `attachments_id`，并会逐一校验是否存在。
-        成功后会同步写入一条 `tbl_document_operation_history`，操作类型为 `update`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentMutationRequest'
-      responses:
-        '200':
-          description: 修改成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                $ref: '#/components/schemas/DocumentRecord'
-        '400':
-          description: 参数错误、附件不存在或修改失败
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到待修改文档
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/document/delete:
-    post:
-      tags: [文档管理]
-      summary: 删除文档
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        按 `document_id` 真删除文档，并在删除前同步写入一条 `tbl_document_operation_history`，操作类型为 `delete`。
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentDeleteRequest'
-      responses:
-        '200':
-          description: 删除成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  document_id:
-                    description: "文档业务 ID"
-                    type: string
-        '400':
-          description: 参数错误或删除失败
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '404':
-          description: 未找到待删除文档
-        '415':
-          description: 请求体必须为 application/json
-        '429':
-          description: 重复请求过于频繁
-  /pb/api/document-history/list:
-    post:
-      tags: [文档历史]
-      summary: 查询文档操作历史
-      description: |
-        仅允许 `ManagePlatform` 用户访问。
-        若 body 传入 `document_id`，则仅查询该文档的历史；否则返回全部文档操作历史，按创建时间倒序排列。
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentHistoryListRequest'
-      responses:
-        '200':
-          description: 查询成功
-          content:
-            application/json:
-              schema:
-                description: "业务响应数据"
-                type: object
-                properties:
-                  items:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/DocumentHistoryRecord'
-        '401':
-          description: token 无效或已过期
-        '403':
-          description: 非 ManagePlatform 用户无权访问
-        '415':
-          description: 请求体必须为 application/json
diff --git a/script/package.json b/script/package.json
index 76a50b4..9332a01 100644
--- a/script/package.json
+++ b/script/package.json
@@ -14,6 +14,7 @@
     "migrate:add-is-delete-field": "node pocketbase.add-is-delete-field.js",
     "migrate:apply-soft-delete-rules": "node pocketbase.apply-soft-delete-rules.js",
     "migrate:ensure-cart-order-autogen-id": "node pocketbase.ensure-cart-order-autogen-id.js",
+    "migrate:cart-active-unique-index": "node pocketbase.cart-active-unique-index.js",
     "migrate:product-params-array": "node migrate-product-parameters-to-array.js",
     "migrate:add-product-function-field": "node add-product-function-field.js",
     "test:company-native-api": "node test-tbl-company-native-api.js",
diff --git a/script/pocketbase.cart-active-unique-index.js b/script/pocketbase.cart-active-unique-index.js
new file mode 100644
index 0000000..4575c3f
--- /dev/null
+++ b/script/pocketbase.cart-active-unique-index.js
@@ -0,0 +1,145 @@
+import { createRequire } from 'module';
+import PocketBase from 'pocketbase';
+
+const require = createRequire(import.meta.url);
+
+let runtimeConfig = {};
+try {
+  runtimeConfig = require('../pocket-base/bai_api_pb_hooks/bai_api_shared/config/runtime.js');
+} catch (_error) {
+  runtimeConfig = {};
+}
+
+const PB_URL = String(process.env.PB_URL || 'https://bai-api.blv-oa.com/pb').replace(/\/+$/, '');
+const AUTH_TOKEN = process.env.POCKETBASE_AUTH_TOKEN || runtimeConfig.POCKETBASE_AUTH_TOKEN || '';
+const COLLECTION = 'tbl_cart';
+const ACTIVE_UNIQUE_INDEX = 'CREATE UNIQUE INDEX idx_tbl_cart_owner_product_active_unique ON tbl_cart (cart_owner, cart_product_id) WHERE is_delete = 0';
+const TEMP_RULE = '@request.auth.id != ""';
+
+if (!AUTH_TOKEN) {
+  console.error('Missing POCKETBASE_AUTH_TOKEN');
+  process.exit(1);
+}
+
+const pb = new PocketBase(PB_URL);
+
+function buildCollectionPayload(base, overrides = {}) {
+  const rawFields = Array.isArray(base.fields) ? base.fields : [];
+  const safeFields = rawFields.filter((field) => field && field.name !== 'id');
+
+  return {
+    name: base.name,
+    type: base.type,
+    listRule: Object.prototype.hasOwnProperty.call(overrides, 'listRule') ? overrides.listRule : base.listRule,
+    viewRule: Object.prototype.hasOwnProperty.call(overrides, 'viewRule') ? overrides.viewRule : base.viewRule,
+    createRule: Object.prototype.hasOwnProperty.call(overrides, 'createRule') ? overrides.createRule : base.createRule,
+    updateRule: Object.prototype.hasOwnProperty.call(overrides, 'updateRule') ? overrides.updateRule : base.updateRule,
+    deleteRule: Object.prototype.hasOwnProperty.call(overrides, 'deleteRule') ? overrides.deleteRule : base.deleteRule,
+    fields: safeFields,
+    indexes: Object.prototype.hasOwnProperty.call(overrides, 'indexes') ? overrides.indexes : (base.indexes || []),
+  };
+}
+
+async function setTempRules(collection) {
+  const payload = buildCollectionPayload(collection, {
+    listRule: TEMP_RULE,
+    viewRule: TEMP_RULE,
+    createRule: TEMP_RULE,
+    updateRule: TEMP_RULE,
+    deleteRule: TEMP_RULE,
+  });
+  await pb.collections.update(collection.id, payload);
+}
+
+async function restoreRules(collection) {
+  await pb.collections.update(collection.id, buildCollectionPayload(collection));
+}
+
+function groupKey(record) {
+  const owner = String(record.cart_owner || '').trim();
+  const product = String(record.cart_product_id || '').trim();
+  return `${owner}||${product}`;
+}
+
+async function dedupeActiveRows() {
+  const rows = await pb.collection(COLLECTION).getFullList({
+    filter: 'is_delete = 0',
+    sort: '-updated',
+    fields: 'id,cart_owner,cart_product_id,is_delete,updated',
+  });
+
+  const groups = new Map();
+  for (const row of rows) {
+    const key = groupKey(row);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(row);
+  }
+
+  let duplicateGroups = 0;
+  let softDeleted = 0;
+
+  for (const [, items] of groups) {
+    if (items.length <= 1) continue;
+    duplicateGroups += 1;
+
+    const keep = items[0];
+    for (let i = 1; i < items.length; i += 1) {
+      const row = items[i];
+      await pb.collection(COLLECTION).update(row.id, { is_delete: 1 });
+      softDeleted += 1;
+    }
+
+    console.log(`dedupe group keep=${keep.id} deleted=${items.length - 1}`);
+  }
+
+  return { total: rows.length, duplicateGroups, softDeleted };
+}
+
+async function applyActiveUniqueIndex() {
+  const collection = await pb.collections.getOne(COLLECTION);
+  const indexes = Array.isArray(collection.indexes) ? collection.indexes.slice() : [];
+  if (!indexes.includes(ACTIVE_UNIQUE_INDEX)) {
+    indexes.push(ACTIVE_UNIQUE_INDEX);
+  }
+
+  const payload = buildCollectionPayload(collection, { indexes });
+  await pb.collections.update(collection.id, payload);
+
+  const latest = await pb.collections.getOne(COLLECTION);
+  const ok = Array.isArray(latest.indexes) && latest.indexes.includes(ACTIVE_UNIQUE_INDEX);
+  if (!ok) {
+    throw new Error('Active unique index was not applied.');
+  }
+}
+
+async function main() {
+  pb.authStore.save(AUTH_TOKEN, null);
+  console.log(`connect ${PB_URL}`);
+
+  const original = await pb.collections.getOne(COLLECTION);
+
+  try {
+    await setTempRules(original);
+    const dedupe = await dedupeActiveRows();
+    console.log(JSON.stringify(dedupe, null, 2));
+  } finally {
+    const latest = await pb.collections.getOne(COLLECTION);
+    const restoreBase = {
+      ...latest,
+      listRule: original.listRule,
+      viewRule: original.viewRule,
+      createRule: original.createRule,
+      updateRule: original.updateRule,
+      deleteRule: original.deleteRule,
+    };
+    await restoreRules(restoreBase);
+  }
+
+  await applyActiveUniqueIndex();
+  console.log('active unique index applied');
+}
+
+main().catch((error) => {
+  console.error('migration failed', error?.response || error?.message || error);
+  process.exitCode = 1;
+});
diff --git a/script/pocketbase.cart-order.js b/script/pocketbase.cart-order.js
index e0c44de..4431db6 100644
--- a/script/pocketbase.cart-order.js
+++ b/script/pocketbase.cart-order.js
@@ -48,11 +48,11 @@ async function buildCollections() {
         updateRule: `${OWNER_AUTH_RULE} && ${CART_OWNER_MATCH_RULE}`,
         deleteRule: `${OWNER_AUTH_RULE} && ${CART_OWNER_MATCH_RULE}`,
         fields: [
-            { name: 'cart_id', type: 'text', required: true, autogeneratePattern: 'CART-[0-9]{13}-[A-Za-z0-9]{6}' },
+            { name: 'cart_id', type: 'text', required: false, autogeneratePattern: 'CART-[0-9]{13}-[A-Za-z0-9]{6}' },
             { name: 'cart_number', type: 'text', required: false },
             { name: 'cart_create', type: 'autodate', onCreate: true, onUpdate: false },
             { name: 'cart_owner', type: 'text', required: true },
-            { name: 'cart_product_id', type: 'relation', required: true, collectionId: productCollectionId, maxSelect: 1, cascadeDelete: false },
+            { name: 'cart_product_id', type: 'relation', required: false, collectionId: productCollectionId, maxSelect: 1, cascadeDelete: false },
             { name: 'cart_product_quantity', type: 'number', required: false },
             { name: 'cart_status', type: 'text', required: false },
             { name: 'cart_at_price', type: 'number', required: false },
@@ -61,6 +61,7 @@ async function buildCollections() {
         ],
         indexes: [
             'CREATE UNIQUE INDEX idx_tbl_cart_cart_id ON tbl_cart (cart_id)',
+            'CREATE UNIQUE INDEX idx_tbl_cart_owner_product_active_unique ON tbl_cart (cart_owner, cart_product_id) WHERE is_delete = 0',
             'CREATE INDEX idx_tbl_cart_cart_number ON tbl_cart (cart_number)',
             'CREATE INDEX idx_tbl_cart_cart_owner ON tbl_cart (cart_owner)',
             'CREATE INDEX idx_tbl_cart_cart_product_id ON tbl_cart (cart_product_id)',
diff --git a/script/pocketbase.ensure-cart-order-autogen-id.js b/script/pocketbase.ensure-cart-order-autogen-id.js
index a054ab1..a9ad3f3 100644
--- a/script/pocketbase.ensure-cart-order-autogen-id.js
+++ b/script/pocketbase.ensure-cart-order-autogen-id.js
@@ -57,11 +57,13 @@ const TARGETS = [
         collectionName: 'tbl_cart',
         fieldName: 'cart_id',
         autogeneratePattern: 'CART-[0-9]{13}-[A-Za-z0-9]{6}',
+        required: false,
     },
     {
         collectionName: 'tbl_order',
         fieldName: 'order_id',
         autogeneratePattern: 'ORDER-[0-9]{13}-[A-Za-z0-9]{6}',
+        required: true,
     },
 ];
 
@@ -128,7 +130,7 @@ async function ensureAutoGenerateField(target) {
 
             return normalizeFieldPayload(field, {
                 type: 'text',
-                required: true,
+                required: typeof target.required === 'boolean' ? target.required : true,
                 autogeneratePattern: target.autogeneratePattern,
             });
         });
diff --git a/script/pocketbase.product-list.js b/script/pocketbase.product-list.js
index 415d953..4aabe2c 100644
--- a/script/pocketbase.product-list.js
+++ b/script/pocketbase.product-list.js
@@ -35,6 +35,7 @@ const collections = [
             { name: 'prod_list_id', type: 'text', required: true },
             { name: 'prod_list_name', type: 'text', required: true },
             { name: 'prod_list_modelnumber', type: 'text' },
+            { name: 'prod_list_barcode', type: 'text' },
             { name: 'prod_list_icon', type: 'text' },
             { name: 'prod_list_description', type: 'text' },
             { name: 'prod_list_feature', type: 'text' },