From 429bef5fee197ebc5c8d0f2e46a00c67e4c57954 Mon Sep 17 00:00:00 2001
From: zichun <26684461+reporkey@users.noreply.github.com>
Date: Wed, 29 Jul 2026 14:38:32 +0800
Subject: [PATCH] docs: ERP 侧字段候选接口任务书（AI 表单 FK 选择器接入 ERP 下拉配置）

---
 docs/erp-tasks-field-options.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 160 insertions(+), 0 deletions(-)
 create mode 100644 docs/erp-tasks-field-options.md

diff --git a/docs/erp-tasks-field-options.md b/docs/erp-tasks-field-options.md
new file mode 100644
index 0000000..67f1f15
--- /dev/null
+++ b/docs/erp-tasks-field-options.md
@@ -0,0 +1,160 @@
+# 任务：ERP 侧为 AI 表单提供「字段候选值」统一接口
+
+给 ERP 侧的第二份任务书（第一份 = `rearch3-erp-tasks.md`，已交付验收通过）。
+本次只做**只读查询**，不涉及写入、不改状态协议。
+
+---
+
+## 背景：xlyAi 现在自己查候选值，和 ERP 网页不一致
+
+xlyAi 的表单卡上，外键字段（客户/产品/物料…）旁边有个【选择】按钮，点开是候选列表。
+现在这条路是 **xlyAi 自己直查共享库**：从字段字典视图 `viw_kg_field_dict` 推断外键目标表（如
+`eleproduct`），自己挑一个"名称列"，拼 `WHERE sBrandsId=? AND 名称列 LIKE ?` 分页返回。
+
+这套能跑，但和 ERP 网页的同一个下拉相比缺三样东西，**其中第二条是数据正确性问题**：
+
+1. **行级数据权限**：ERP 的下拉 SQL 里有 `[sId, sLookCustomer]` 这类宏，经
+   `BusinessCommonServiceImpl.getDataFilterAuth` 展开成权限子查询（业务员只看自己的客户）。
+   xlyAi 这条路只有"该表是否被你有权的表单引用过"的**表级**判断，**没有行级过滤**。
+2. **级联过滤（重要）**：报价单的产品下拉配置是
+   `... FROM eleproduct A ... where a.bInvalid=0 and sCustomerId=#sCustomerId# #sKeyUpFilter# #A.companyId#`，
+   配套 `sSqlCondition = master.sCustomerId.sCustomerId` —— 即**产品候选必须限定在已选客户名下**。
+   xlyAi 现在会把该品牌下所有产品都列出来，用户可以选到一个不属于该客户的产品。
+3. **联动回填**：客户控件的 `sAssignField` 有近 30 组映射
+   （`sCustomerId:sId, sCustomerName:sCustomerName, sCustomerNo:sCustomerNo, sContacts:..., sGetPayId:...`），
+   ERP 网页选中客户后会把这些列一起带进表单。xlyAi 只写外键 id，其余留空。
+
+## 好消息：映射键已经找到了，不需要新建任何映射表
+
+实测确认（本地 saaslocal 库）：
+
+- xlyAi 表单卡里的 `formId`（如报价 = `101251240115016076506222750`）
+  **就是 `gdsconfigformmaster.sId`**（该行 `sTbName='QuoQuotationmaster'`、`sParentId=` 模块 id `...222050`）。
+- ERP 的控件配置 `gdsconfigformslave` 正是以 `sParentId = 这个 formId` 挂在下面（报价主表共 146 行控件）。
+- 所以 **(xlyAi 的 formId, 字段) → ERP 控件 sId** 是一次直接查表，无需新建映射。
+
+已验证的两个控件（报价主表）：
+
+| 控件 sId | sName | sKeyUpFilter | 级联 sSqlCondition |
+| --- | --- | --- | --- |
+| `16427541500006326873721849694000` | sCustomerName | sCustomerName | 无 |
+| `16427542760005958727285709417000` | sProductName | sProductName | `master.sCustomerId.sCustomerId` |
+
+我已用普通用户 token 实测过现成端点
+`POST /business/getSelectDataBysControlId/{控件sId}?sModelsId={模块id}`：
+
+- 客户控件 + `{"sKeyUpFilterName":"中科"}` → `code=1`，3 条候选，列齐全（含 sId / sCustomerNo / sSalesManName / dTaxRate …）；
+- 产品控件不传级联值 → `code=-1`，msg 是
+  `=============下拉SQL中包含需要替换的字符，前台未传入替换的值,sSql:master.sCustomerId.sCustomerId========`；
+  传 `{"sSqlCondition":{"sCustomerId":"<客户id>"}}` → `code=1`，只列该客户的产品。**级联行为正确。**
+
+---
+
+## 要你们做的事：新增一个 AI 专用的字段候选接口
+
+**不要**让 xlyAi 直接调 `getSelectDataBysControlId`——控件解析规则（个性化表覆盖、语言列、
+`sql`/`const`/`popup` 三种类型、`sRelation` 伪列反推）是你们的领域知识，散到 AI 侧会持续错位。
+请封一个端点，把"解析 + 取数 + 元数据"一次给我们。
+
+### 接口契约（建议，可按你们习惯调整，但字段语义要覆盖到）
+
+```
+POST /ai/fieldOptions
+Authorization: <用户 token>        // 与现有 /ai/* 一致，@Authorization + @CurrentUser
+{
+  "sFormId":  "101251240115016076506222750",   // = gdsconfigformmaster.sId，xlyAi 表单卡里带的 formId
+  "sField":   "sCustomerId",                   // xlyAi 用的是外键 id 列名（见下方「字段名对齐」）
+  "q":        "中科",                          // 搜索词，可空
+  "pageNum":  1,
+  "pageSize": 20,
+  "context":  { "sCustomerId": "1752644777..." }  // 已在表单上选好的其它字段值，供级联使用；可空
+}
+```
+
+返回（外层沿用你们的 `Feedback` 信封即可）：
+
+```json
+{
+  "mode": "list",                       // list=有候选可列；none=该字段不是可选字段
+  "nameField": "sCustomerName",         // 哪一列当"名字"显示
+  "valueField": "sId",                  // 哪一列是要存进业务表的值
+  "columns": [{"col":"sCustomerName","label":"客户名称"},
+              {"col":"sCustomerNo","label":"客户编号"}],   // 建议展示的列，按重要性排序
+  "rows":   [{"sId":"...","sCustomerName":"中科袜业","sCustomerNo":"KH0012", ...}],
+  "total":  3, "pageNum": 1, "pageSize": 20,
+  "assign": {"sCustomerName":"sCustomerName","sCustomerNo":"sCustomerNo","sContacts":"sContacts"},
+  "requires": []
+}
+```
+
+### 必须满足的几点
+
+1. **字段名对齐（这条最容易踩坑）**
+   ERP 的控件挂在**显示名列**上（`sCustomerName`），而 xlyAi 传过来的是**外键 id 列**（`sCustomerId`）。
+   请在解析时两边都认：先按 `sName = sField` 找控件；找不到就找 `sAssignField` 里
+   **把结果列赋给 `sField` 的那个控件**（客户控件的 `sAssignField` 含 `sCustomerId:sId`，正是这条线）。
+   两种都找不到 → 返回 `mode:"none"`，我们回落到自己的字典查询。
+
+2. **级联依赖要结构化，不要抛内部报文**
+   配置了 `sSqlCondition` 但 `context` 里缺值时，**不要**返回现在那句
+   `下拉SQL中包含需要替换的字符...sSql:master.sCustomerId.sCustomerId`（泄漏内部实现且用户看不懂）。
+   请返回：
+
+   ```json
+   {"mode":"need_context", "requires":["sCustomerId"],
+    "msg":"请先选择客户，再选产品"}
+   ```
+
+   xlyAi 会据此先让用户选父字段，而不是把候选列表拉空或报错。
+
+3. **`popup` 类型也要能列数据**
+   全库有 25 个 `sDropDownType='popup'` 的控件，网页上是"弹出另一个业务窗体去挑"。
+   AI 没有"打开另一个窗体"的能力，请在这个端点里把 popup 也归一成 `rows` 列表返回
+   （内部走 `sActiveId` 对应窗体的 `getBusinessDataByFormcustomId` 即可），
+   并且**不要**返回 `id[-]名称` 这种拼接值，`rows` 里请拆成独立列。
+
+4. **租户隔离要在代码层兜底（我方红线）**
+   现状是靠配置里手写 `#companyId#`，漏写就跨租户。这个 AI 端点请**强制**附加
+   品牌/分公司条件；若某控件配置无法安全附加，宁可对 AI 通道返回 `mode:"none"`（我们回落），
+   **不要**返回一个没有租户过滤的结果集。
+
+5. **行级数据权限必须照常生效**
+   即保留 `getDataFilterAuth` 那一层（`[列, 权限key]` 宏展开）。这正是我们想要这个接口的主因之一。
+
+6. **纯只读、无副作用**，不写日志表/不发消息；Redis 缓存 key 请确认仍含 userId（避免串号）。
+
+7. **`assign` 回填映射要吐给我们**
+   把该控件的 `sAssignField` 解析成 `目标字段 → 结果列` 的 map 返回。
+   xlyAi 会在用户选中一行后，按它把联动列（客户编号、联系人、税率、业务员…）一并写进创建载荷，
+   让 AI 建的单和网页建的单字段完整度一致。**只回填目标表真实存在的列**——
+   实测报价主表只存在 `sCustomerName` / `sCustomerNo` / `sMemo` 三个目标列，
+   其余映射项在该表上是空转（可能是跨表单复用的配置），请你们过滤掉不存在的列，别让我们写脏字段。
+
+### 验收（希望你们跑给我们看）
+
+- 客户字段：`{sFormId:"...222750", sField:"sCustomerId", q:"中科"}` → 有候选、`nameField=sCustomerName`、
+  `assign` 含 `sCustomerName`/`sCustomerNo`。
+- 产品字段不给 context → `mode:"need_context"`, `requires:["sCustomerId"]`, 中文 msg 可读。
+- 产品字段给 context → 只返回该客户名下的产品（与网页下拉结果一致）。
+- 换一个**只能看自己客户**的业务员 token 调同一个客户字段 → 候选条数明显少于管理员（证明行级权限生效）。
+- 一个 `popup` 类型字段 → 也能返回 `rows`（不含 `[-]`）。
+- 一个纯文本字段（如备注）→ `mode:"none"`，不报错。
+
+---
+
+## 顺带两个问题
+
+1. **报价单的 `sCustomerName` 冗余列**：205 张原生报价里只有 95 张填了这一列，其余为空。
+   这列到底该不该填？我们建的单目前不填（只写 `sCustomerId`），想跟你们保持一致。
+2. **`sRelation` 伪列反查**：xlyAi 现在自己实现了"按 id 反查显示名"。
+   如果你们愿意顺手在同一个端点上加个 `POST /ai/fieldDisplay`（给 formId+字段+id，返回显示名），
+   我们就能把这块也交回给你们统一。**非必需，看你们成本。**
+
+---
+
+## 我方对应改动（供你们了解，不用你们做）
+
+拿到这个端点后，xlyAi 的 `/api/agent/form/options` 会改成：
+优先按 `(formId, 字段)` 走你们的新端点；`mode:"none"` 或网络异常时回落到现有的字典直查（保底不影响可用性）。
+`need_context` 会转成"请先选客户"的提示。`assign` 会并入创建载荷。
+涉及文件：`FormController` / `FormResolverService.fkOptionPage` / `FormRenderService.buildQuote`。
--
libgit2 0.22.2