朱子纯 / xlyNewAi

Commit 429bef5fee197ebc5c8d0f2e46a00c67e4c57954

Authored by zichun
1 parent 96dcd92f

docs: ERP 侧字段候选接口任务书（AI 表单 FK 选择器接入 ERP 下拉配置）

Inline Side-by-side
Showing 1 changed file with 160 additions and 0 deletions
docs/erp-tasks-field-options.md 0 → 100644
  View file @429bef5
  1 +# 任务：ERP 侧为 AI 表单提供「字段候选值」统一接口
  2 +
  3 +给 ERP 侧的第二份任务书（第一份 = `rearch3-erp-tasks.md`，已交付验收通过）。
  4 +本次只做**只读查询**，不涉及写入、不改状态协议。
  5 +
  6 +---
  7 +
  8 +## 背景：xlyAi 现在自己查候选值，和 ERP 网页不一致
  9 +
  10 +xlyAi 的表单卡上，外键字段（客户/产品/物料…）旁边有个【选择】按钮，点开是候选列表。
  11 +现在这条路是 **xlyAi 自己直查共享库**：从字段字典视图 `viw_kg_field_dict` 推断外键目标表（如
  12 +`eleproduct`），自己挑一个"名称列"，拼 `WHERE sBrandsId=? AND 名称列 LIKE ?` 分页返回。
  13 +
  14 +这套能跑，但和 ERP 网页的同一个下拉相比缺三样东西，**其中第二条是数据正确性问题**：
  15 +
  16 +1. **行级数据权限**：ERP 的下拉 SQL 里有 `[sId, sLookCustomer]` 这类宏，经
  17 + `BusinessCommonServiceImpl.getDataFilterAuth` 展开成权限子查询（业务员只看自己的客户）。
  18 + xlyAi 这条路只有"该表是否被你有权的表单引用过"的**表级**判断，**没有行级过滤**。
  19 +2. **级联过滤（重要）**：报价单的产品下拉配置是
  20 + `... FROM eleproduct A ... where a.bInvalid=0 and sCustomerId=#sCustomerId# #sKeyUpFilter# #A.companyId#`，
  21 + 配套 `sSqlCondition = master.sCustomerId.sCustomerId` —— 即**产品候选必须限定在已选客户名下**。
  22 + xlyAi 现在会把该品牌下所有产品都列出来，用户可以选到一个不属于该客户的产品。
  23 +3. **联动回填**：客户控件的 `sAssignField` 有近 30 组映射
  24 + （`sCustomerId:sId, sCustomerName:sCustomerName, sCustomerNo:sCustomerNo, sContacts:..., sGetPayId:...`），
  25 + ERP 网页选中客户后会把这些列一起带进表单。xlyAi 只写外键 id，其余留空。
  26 +
  27 +## 好消息：映射键已经找到了，不需要新建任何映射表
  28 +
  29 +实测确认（本地 saaslocal 库）：
  30 +
  31 +- xlyAi 表单卡里的 `formId`（如报价 = `101251240115016076506222750`）
  32 + **就是 `gdsconfigformmaster.sId`**（该行 `sTbName='QuoQuotationmaster'`、`sParentId=` 模块 id `...222050`）。
  33 +- ERP 的控件配置 `gdsconfigformslave` 正是以 `sParentId = 这个 formId` 挂在下面（报价主表共 146 行控件）。
  34 +- 所以 **(xlyAi 的 formId, 字段) → ERP 控件 sId** 是一次直接查表，无需新建映射。
  35 +
  36 +已验证的两个控件（报价主表）：
  37 +
  38 +| 控件 sId | sName | sKeyUpFilter | 级联 sSqlCondition |
  39 +| --- | --- | --- | --- |
  40 +| `16427541500006326873721849694000` | sCustomerName | sCustomerName | 无 |
  41 +| `16427542760005958727285709417000` | sProductName | sProductName | `master.sCustomerId.sCustomerId` |
  42 +
  43 +我已用普通用户 token 实测过现成端点
  44 +`POST /business/getSelectDataBysControlId/{控件sId}?sModelsId={模块id}`：
  45 +
  46 +- 客户控件 + `{"sKeyUpFilterName":"中科"}` → `code=1`，3 条候选，列齐全（含 sId / sCustomerNo / sSalesManName / dTaxRate …）；
  47 +- 产品控件不传级联值 → `code=-1`，msg 是
  48 + `=============下拉SQL中包含需要替换的字符，前台未传入替换的值,sSql:master.sCustomerId.sCustomerId========`；
  49 + 传 `{"sSqlCondition":{"sCustomerId":"<客户id>"}}` → `code=1`，只列该客户的产品。**级联行为正确。**
  50 +
  51 +---
  52 +
  53 +## 要你们做的事：新增一个 AI 专用的字段候选接口
  54 +
  55 +**不要**让 xlyAi 直接调 `getSelectDataBysControlId`——控件解析规则（个性化表覆盖、语言列、
  56 +`sql`/`const`/`popup` 三种类型、`sRelation` 伪列反推）是你们的领域知识，散到 AI 侧会持续错位。
  57 +请封一个端点，把"解析 + 取数 + 元数据"一次给我们。
  58 +
  59 +### 接口契约（建议，可按你们习惯调整，但字段语义要覆盖到）
  60 +
  61 +```
  62 +POST /ai/fieldOptions
  63 +Authorization: <用户 token> // 与现有 /ai/* 一致，@Authorization + @CurrentUser
  64 +{
  65 + "sFormId": "101251240115016076506222750", // = gdsconfigformmaster.sId，xlyAi 表单卡里带的 formId
  66 + "sField": "sCustomerId", // xlyAi 用的是外键 id 列名（见下方「字段名对齐」）
  67 + "q": "中科", // 搜索词，可空
  68 + "pageNum": 1,
  69 + "pageSize": 20,
  70 + "context": { "sCustomerId": "1752644777..." } // 已在表单上选好的其它字段值，供级联使用；可空
  71 +}
  72 +```
  73 +
  74 +返回（外层沿用你们的 `Feedback` 信封即可）：
  75 +
  76 +```json
  77 +{
  78 + "mode": "list", // list=有候选可列；none=该字段不是可选字段
  79 + "nameField": "sCustomerName", // 哪一列当"名字"显示
  80 + "valueField": "sId", // 哪一列是要存进业务表的值
  81 + "columns": [{"col":"sCustomerName","label":"客户名称"},
  82 + {"col":"sCustomerNo","label":"客户编号"}], // 建议展示的列，按重要性排序
  83 + "rows": [{"sId":"...","sCustomerName":"中科袜业","sCustomerNo":"KH0012", ...}],
  84 + "total": 3, "pageNum": 1, "pageSize": 20,
  85 + "assign": {"sCustomerName":"sCustomerName","sCustomerNo":"sCustomerNo","sContacts":"sContacts"},
  86 + "requires": []
  87 +}
  88 +```
  89 +
  90 +### 必须满足的几点
  91 +
  92 +1. **字段名对齐（这条最容易踩坑）**
  93 + ERP 的控件挂在**显示名列**上（`sCustomerName`），而 xlyAi 传过来的是**外键 id 列**（`sCustomerId`）。
  94 + 请在解析时两边都认：先按 `sName = sField` 找控件；找不到就找 `sAssignField` 里
  95 + **把结果列赋给 `sField` 的那个控件**（客户控件的 `sAssignField` 含 `sCustomerId:sId`，正是这条线）。
  96 + 两种都找不到 → 返回 `mode:"none"`，我们回落到自己的字典查询。
  97 +
  98 +2. **级联依赖要结构化，不要抛内部报文**
  99 + 配置了 `sSqlCondition` 但 `context` 里缺值时，**不要**返回现在那句
  100 + `下拉SQL中包含需要替换的字符...sSql:master.sCustomerId.sCustomerId`（泄漏内部实现且用户看不懂）。
  101 + 请返回：
  102 +
  103 + ```json
  104 + {"mode":"need_context", "requires":["sCustomerId"],
  105 + "msg":"请先选择客户，再选产品"}
  106 + ```
  107 +
  108 + xlyAi 会据此先让用户选父字段，而不是把候选列表拉空或报错。
  109 +
  110 +3. **`popup` 类型也要能列数据**
  111 + 全库有 25 个 `sDropDownType='popup'` 的控件，网页上是"弹出另一个业务窗体去挑"。
  112 + AI 没有"打开另一个窗体"的能力，请在这个端点里把 popup 也归一成 `rows` 列表返回
  113 + （内部走 `sActiveId` 对应窗体的 `getBusinessDataByFormcustomId` 即可），
  114 + 并且**不要**返回 `id[-]名称` 这种拼接值，`rows` 里请拆成独立列。
  115 +
  116 +4. **租户隔离要在代码层兜底（我方红线）**
  117 + 现状是靠配置里手写 `#companyId#`，漏写就跨租户。这个 AI 端点请**强制**附加
  118 + 品牌/分公司条件；若某控件配置无法安全附加，宁可对 AI 通道返回 `mode:"none"`（我们回落），
  119 + **不要**返回一个没有租户过滤的结果集。
  120 +
  121 +5. **行级数据权限必须照常生效**
  122 + 即保留 `getDataFilterAuth` 那一层（`[列, 权限key]` 宏展开）。这正是我们想要这个接口的主因之一。
  123 +
  124 +6. **纯只读、无副作用**，不写日志表/不发消息；Redis 缓存 key 请确认仍含 userId（避免串号）。
  125 +
  126 +7. **`assign` 回填映射要吐给我们**
  127 + 把该控件的 `sAssignField` 解析成 `目标字段 → 结果列` 的 map 返回。
  128 + xlyAi 会在用户选中一行后，按它把联动列（客户编号、联系人、税率、业务员…）一并写进创建载荷，
  129 + 让 AI 建的单和网页建的单字段完整度一致。**只回填目标表真实存在的列**——
  130 + 实测报价主表只存在 `sCustomerName` / `sCustomerNo` / `sMemo` 三个目标列，
  131 + 其余映射项在该表上是空转（可能是跨表单复用的配置），请你们过滤掉不存在的列，别让我们写脏字段。
  132 +
  133 +### 验收（希望你们跑给我们看）
  134 +
  135 +- 客户字段：`{sFormId:"...222750", sField:"sCustomerId", q:"中科"}` → 有候选、`nameField=sCustomerName`、
  136 + `assign` 含 `sCustomerName`/`sCustomerNo`。
  137 +- 产品字段不给 context → `mode:"need_context"`, `requires:["sCustomerId"]`, 中文 msg 可读。
  138 +- 产品字段给 context → 只返回该客户名下的产品（与网页下拉结果一致）。
  139 +- 换一个**只能看自己客户**的业务员 token 调同一个客户字段 → 候选条数明显少于管理员（证明行级权限生效）。
  140 +- 一个 `popup` 类型字段 → 也能返回 `rows`（不含 `[-]`）。
  141 +- 一个纯文本字段（如备注）→ `mode:"none"`，不报错。
  142 +
  143 +---
  144 +
  145 +## 顺带两个问题
  146 +
  147 +1. **报价单的 `sCustomerName` 冗余列**：205 张原生报价里只有 95 张填了这一列，其余为空。
  148 + 这列到底该不该填？我们建的单目前不填（只写 `sCustomerId`），想跟你们保持一致。
  149 +2. **`sRelation` 伪列反查**：xlyAi 现在自己实现了"按 id 反查显示名"。
  150 + 如果你们愿意顺手在同一个端点上加个 `POST /ai/fieldDisplay`（给 formId+字段+id，返回显示名），
  151 + 我们就能把这块也交回给你们统一。**非必需，看你们成本。**
  152 +
  153 +---
  154 +
  155 +## 我方对应改动（供你们了解，不用你们做）
  156 +
  157 +拿到这个端点后，xlyAi 的 `/api/agent/form/options` 会改成：
  158 +优先按 `(formId, 字段)` 走你们的新端点；`mode:"none"` 或网络异常时回落到现有的字典直查（保底不影响可用性）。
  159 +`need_context` 会转成"请先选客户"的提示。`assign` 会并入创建载荷。
  160 +涉及文件：`FormController` / `FormResolverService.fkOptionPage` / `FormRenderService.buildQuote`。
... ...