From a314c64b0b0dd34ff9ad66f71ac095b0c32d0edd Mon Sep 17 00:00:00 2001 From: chen qiang <343005560@qq.com> Date: Wed, 30 Sep 2026 10:17:51 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85BOS=E5=8D=95=E6=8D=AE?= =?UTF-8?q?=E5=8F=96=E5=8F=B7=E5=8F=8A=E7=BC=96=E5=8F=B7=E5=AE=9A=E4=B9=89?= =?UTF-8?q?=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 6 ++++++ CHANGELOG.md | 13 +++++++++++++ README.md | 16 +++++++++++++++- SKILL.md | 7 +++++-- VERSION | 2 +- docs/操作示例.md | 7 ++++--- references/bos-metadata.md | 6 ++++++ references/query-and-business-rules.md | 21 ++++++++++++++++++++- 8 files changed, 70 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b570073..89bb38b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,11 @@ # oracle-jump-query Skill Release Standard +取号 CODE 定义在 `AD_SEQUENCE` 表；1.5.50 的编号规则分析路径为 `DOCNO -> AD_COLUMN.SEQUENCENAME -> AD_SEQUENCE`。 + +Release 1.5.50: 明确取单号函数 `Get_SequenceNo('', AD_CLIENT_ID)`，默认 `CODE` 取单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME`，客户 ID 使用单据实际值；取号仅生成 SQL 示例，不通过查询通道调用。本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置或审计 action、字段及保存策略；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。 + +Release 1.5.49: 补充品小二环境中文条件的 `UNISTR` Unicode 转义规则，并同步修正 BOS 元数据查询说明、README 和操作示例；直接中文字面量返回 0 行时先按 `UNISTR` 形式重试。其他 client 可将 `UNISTR` 作为跨环境复用和避免传输编码转换的通用兜底。本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置或审计 action、字段及保存策略；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。 + Release 1.5.48: 补充 BOS 新建表最小结构，保留八个基础字段、类型、可空性、`ISACTIVE DEFAULT 'Y' NOT NULL` 和 `ID` 主键；DDL 仅生成供人工确认执行。本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置或审计 action、字段及保存策略；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。 Release 1.5.47: 补充用户提供表名称时的 BOS 表解析规则：未明确要求绕过 BOS 元数据直接查询物理数据库对象时，先查 `AD_TABLE.NAME`、`DESCRIPTION` 和 `REALTABLE_ID`；虚拟表沿 `REALTABLE_ID` 定位实际表，未注册对象再按数据库表、视图、物化视图顺序查找。本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置或审计 action；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。 diff --git a/CHANGELOG.md b/CHANGELOG.md index d4739b0..1c47460 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,16 @@ +## 1.5.50 (2026-09-30) + +- 明确取单号函数 `Get_SequenceNo('', AD_CLIENT_ID)`，默认 `CODE` 来自该单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME`；客户 ID 使用单据实际值，不固定为 `37`。 +- 补充取号 CODE 的定义在 `AD_SEQUENCE` 表，分析编号规则时沿单据字段配置核实对应定义。 +- 同步 Skill、业务规则和 README；配置为空时不猜测生成器，特殊业务按实际配置和过程逻辑核实，取号仅生成 SQL 示例，不通过查询通道执行。 +- 本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置格式或审计 action、字段及保存策略；命令数保持 32。 + +## 1.5.49 (2026-09-14) + +- 补充品小二环境中文条件的字符集兼容规则：中文 `LIKE` 或等值条件优先使用 Oracle `UNISTR` Unicode 转义；直接中文字面量返回 0 行时先按该形式重试。 +- 同步更新 BOS 元数据查询说明、README 和操作示例，避免继续使用可能失效的中文字面量示例；其他 client 可将 `UNISTR` 作为跨环境复用和避免传输编码转换的通用兜底。 +- 本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置格式或审计 action、字段及保存策略；命令数保持 32。 + ## 1.5.48 (2026-09-03) - 补充 BOS 新建表的八个基础字段、字段类型、可空性、`ISACTIVE` 默认值和 `ID` 主键模板。 diff --git a/README.md b/README.md index dc3103e..ddc1217 100644 --- a/README.md +++ b/README.md @@ -138,6 +138,19 @@ WHERE BILLDATE = 20260501 SELECT * FROM M_RETAIL ``` +### 品小二中文条件 + +品小二环境存在已知字符集转换问题，中文条件直接写成 `LIKE '%中文%'` 可能返回 0 行。查询中文值时使用 Oracle `UNISTR` Unicode 转义，例如： + +```sql +SELECT ID, NAME, DESCRIPTION +FROM AD_TABLE +WHERE DESCRIPTION LIKE '%' || UNISTR('\96F6\552E\5355') || '%' + AND ROWNUM <= 20 +``` + +直接中文字面量查不到时，先用 `UNISTR` 形式重试；这条是品小二的客户级兼容规则。其他 client 若已验证直接中文字面量可用，不必强制改写，但 `UNISTR` 可作为跨环境复用和避免传输编码转换的通用兜底。 + ## 常用业务对象说明 - “商品”“款号”通常指 `M_PRODUCT` 表。 @@ -291,7 +304,8 @@ python scripts/oracle_skill.py ops_report HENLO - 新增记录主键 `ID` 使用 `get_sequences('<表名称>')`。 - 如果表存在 `DOCNO` 字段，先到 `AD_COLUMN` 查询该字段的 `SEQUENCENAME`。 -- 如果 `SEQUENCENAME` 有值，`DOCNO` 使用 `Get_SequenceNo('', 37)`。 +- 取单号函数为 `Get_SequenceNo('', AD_CLIENT_ID)`；默认 `CODE` 取该单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME` 值，第二个参数取单据实际的 `AD_CLIENT_ID`，确认是 `37` 时才写 `37`。配置为空时不猜测 `CODE`，特殊业务按实际配置和过程逻辑核实；只生成 SQL 示例，不通过查询通道调用取号函数。 +- 取号 `CODE` 的定义在 `AD_SEQUENCE` 表，分析编号规则时沿 `DOCNO -> AD_COLUMN.SEQUENCENAME -> AD_SEQUENCE` 核实。 - 如果表存在 `AD_CLIENT_ID` 字段，默认值为 `37`。 - 如果表存在 `AD_ORG_ID` 字段，默认值为 `27`。 - 子表 `AD_CLIENT_ID`、`AD_ORG_ID` 默认继承父表对应字段值。 diff --git a/SKILL.md b/SKILL.md index 0e0b706..f2a5021 100644 --- a/SKILL.md +++ b/SKILL.md @@ -5,7 +5,7 @@ description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle # Oracle 跳板查询 -> **版本：v1.5.48** · [更新日志](./CHANGELOG.md) +> **版本：v1.5.50** · [更新日志](./CHANGELOG.md) ## 使用原则 @@ -15,6 +15,8 @@ description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle 生产环境查询必须带明确 `WHERE` 条件和行数限制。不要为了“先看看数据”查询整表；涉及库存视图、业务大表、统计查询时尤其要先限定门店、日期、单号、状态、款号、条码或主键范围。 +品小二环境存在已知字符集兼容问题：中文条件直接写成 `LIKE '%中文%'`（或直接把中文写入等值条件）可能返回 0 行。查询该环境的中文值时，优先将中文转换为 Oracle `UNISTR` Unicode 转义，例如“零售单”使用 `LIKE '%' || UNISTR('\96F6\552E\5355') || '%'`；直接返回 0 行时先用该写法重试，不要据此判断没有数据。该规则是品小二的客户级差异；其他 client 若直接中文字面量已验证可用，不必强制改写，但可将 `UNISTR` 作为避免传输编码转换的通用兜底。 + ## 参考文档 详细规则已经拆分到 `references/`，处理对应任务时必须读取相关文件： @@ -125,7 +127,8 @@ AD_SUBSYSTEM - `M_ATTRIBUTESETINSTANCE` 是商品色码属性表：`VALUE1`/`VALUE1_CODE`/`VALUE1_ID` 对应颜色名称、颜色编号、颜色表 `M_COLOR.ID`；`VALUE2`/`VALUE2_CODE`/`VALUE2_ID` 对应尺码名称、尺码编号、尺码表 `M_SIZE.ID`。 - 库存通常查 `V_FA_STORAGE`，必须同时带店仓条件和款号/条码条件，并加行数限制。 - 新增业务记录 SQL 示例中，主键 `ID` 使用 `get_sequences('<表名称>')`。 -- 如表存在 `DOCNO`，先查 `AD_COLUMN.SEQUENCENAME`；有值时用 `Get_SequenceNo('', 37)` 取单据编号。 +- 取单号函数为 `Get_SequenceNo('', AD_CLIENT_ID)`；默认约定是 `CODE` 取该单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME` 值，第二个参数取单据实际的 `AD_CLIENT_ID`。先核实元数据；配置为空时不猜测 `CODE`，实际业务有特殊规则时按核实结果处理。只生成 SQL 示例，不通过查询通道调用取号函数。 +- 取号 `CODE` 的定义在 `AD_SEQUENCE` 表；分析编号规则时，沿 `DOCNO -> AD_COLUMN.SEQUENCENAME -> AD_SEQUENCE` 核实对应定义。 - 如表存在 `AD_CLIENT_ID`，默认值 `37`；如存在 `AD_ORG_ID`，默认值 `27`。 - 子表的 `AD_CLIENT_ID`、`AD_ORG_ID` 默认继承父表。 - 新增表单若存在 `STATUS`、`STATUSERID`、`STATUSTIME`，通常只设置 `STATUS='1'`，不设置提交人和提交时间。 diff --git a/VERSION b/VERSION index 317146c..88eb60e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.5.48 +1.5.50 diff --git a/docs/操作示例.md b/docs/操作示例.md index bd2ab49..3bf0a26 100644 --- a/docs/操作示例.md +++ b/docs/操作示例.md @@ -9,6 +9,7 @@ - 业务词先查字典：遇到“零售单”“采购入库”“调拨单”等业务词时，先从 `AD_TABLE`、`AD_COLUMN`、`AD_REFBYTABLE` 确认表和字段。 - 单据统计加状态条件：统计业务单据时，通常需要过滤 `ISACTIVE = 'Y' AND STATUS = '2'`。 - 明细表不靠猜：主表到明细表关系应通过 `AD_REFBYTABLE` 查询确认。 +- 品小二中文条件：中文值直接写入 `LIKE` 可能因字符集转换返回 0 行，应改用 Oracle `UNISTR` Unicode 转义；其他 client 可按实际验证结果使用，`UNISTR` 也可作为跨环境复用时的 ASCII-safe 兜底。 ## 常见操作 @@ -115,14 +116,14 @@ python scripts/oracle_skill.py describe BOSNDS3 XCX_SO ```sql SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT FROM AD_TABLE -WHERE NAME LIKE '%零售%' - OR DESCRIPTION LIKE '%零售%'; +WHERE NAME LIKE '%' || UNISTR('\96F6\552E') || '%' + OR DESCRIPTION LIKE '%' || UNISTR('\96F6\552E') || '%'; ``` 对应命令： ```bash -python scripts/oracle_skill.py query "SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT FROM AD_TABLE WHERE NAME LIKE '%零售%' OR DESCRIPTION LIKE '%零售%'" +python scripts/oracle_skill.py query "SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT FROM AD_TABLE WHERE NAME LIKE '%' || UNISTR('\96F6\552E') || '%' OR DESCRIPTION LIKE '%' || UNISTR('\96F6\552E') || '%'" ``` ### 7. 查询字段业务含义 diff --git a/references/bos-metadata.md b/references/bos-metadata.md index ce8bdb0..e179d57 100644 --- a/references/bos-metadata.md +++ b/references/bos-metadata.md @@ -4,10 +4,16 @@ ## 数据字典（AD_TABLE / AD_COLUMN / AD_REFBYTABLE） +### 单据编号定义（AD_SEQUENCE） + +取单号函数为 `Get_SequenceNo('', AD_CLIENT_ID)`。默认约定是 `CODE` 取单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME` 值，CODE 的定义在 `AD_SEQUENCE` 表中；第二个参数取单据实际的 `AD_CLIENT_ID`。分析编号规则时，先定位单据及其 `DOCNO` 字段配置，再到 `AD_SEQUENCE` 核实对应定义，特殊业务按目标环境的实际配置和过程逻辑处理。查询 `AD_SEQUENCE` 前先确认表结构和字段含义，不假定关联字段或编号格式。取号只生成 SQL 示例，不通过查询通道调用函数。 + ### 通用查询规则 处理 BOS 业务单据（如零售单、采购单、调拨单、销售单等）时，必须遵循以下查询路径： +在品小二环境按中文名称或中文描述筛选时，遵守 [中文条件与字符集兼容](./query-and-business-rules.md#中文条件与字符集兼容) 规则：不要直接把中文写入 `LIKE` 或等值条件，改用 `UNISTR` Unicode 转义。直接中文字面量返回 0 行时，先用 `UNISTR` 形式重试。 + #### 用户提供表名称时的对象解析顺序 用户给出一个表名称，且没有明确要求绕过 BOS 元数据、直接按 Oracle 物理对象查询时，不要立即对该名称执行 `describe` 或数据查询。先确认它是 BOS 逻辑表、BOS 实际表，还是未在 BOS 注册的数据库对象。 diff --git a/references/query-and-business-rules.md b/references/query-and-business-rules.md index aee9a85..334dad0 100644 --- a/references/query-and-business-rules.md +++ b/references/query-and-business-rules.md @@ -30,6 +30,21 @@ WHERE BILLDATE = 20260501 SELECT * FROM M_RETAIL ``` +## 中文条件与字符集兼容 + +品小二环境存在已知字符集转换问题：通过 Skill 查询时，中文字符串直接写成 `LIKE '%中文%'`，或直接把中文写入 `=` 等值条件，可能返回 0 行，即使数据库中存在匹配记录。 + +查询品小二中的中文值时，优先使用 Oracle `UNISTR` 和 Unicode 转义，将 SQL 中的中文条件保持为 ASCII。例如“零售单”的 Unicode 编码为 `96F6 552E 5355`，应写成： + +```sql +SELECT ID, NAME, DESCRIPTION +FROM AD_TABLE +WHERE DESCRIPTION LIKE '%' || UNISTR('\96F6\552E\5355') || '%' + AND ROWNUM <= 20 +``` + +精确匹配同样适用，例如“品小二”可写成 `= UNISTR('\54C1\5C0F\4E8C')`。中文条件直接查询返回 0 行时，先改用 `UNISTR` 形式重试，再判断数据是否确实不存在。对其他 client，如果直接中文字面量已验证可用，不必强制改写；但在需要跨客户复用 SQL，或希望让 SQL 文本保持 ASCII、避免客户端/HTTP/命令行传输转换时，`UNISTR` 也是有帮助的通用兜底。该函数返回 Oracle national character set，面对超大表的 `VARCHAR2` 索引条件时仍应关注执行计划；无论使用哪种写法，仍须遵守生产查询的过滤条件和行数限制。 + ## 常用业务对象说明 当用户使用商品、款号、条码、SKU、库存等业务词时，默认按以下对象理解： @@ -103,7 +118,10 @@ CREATE TABLE TableName ( - 主表或子表新增记录的主键 `ID` 使用 `get_sequences('<表名称>')` 取值。 - 如果目标表存在 `DOCNO` 字段，先查询 `AD_COLUMN` 中该字段是否配置 `SEQUENCENAME` 单据编号生成器。 -- 如果 `DOCNO` 对应的 `SEQUENCENAME` 有值，则单据编号使用 `Get_SequenceNo('', 37)` 取值。 +- 取单号函数为 `Get_SequenceNo('', AD_CLIENT_ID)`。一般情况下，`CODE` 取该单据 `DOCNO` 字段对应的 `AD_COLUMN.SEQUENCENAME` 值，第二个参数取单据实际的 `AD_CLIENT_ID`；这是默认业务约定，特殊业务以目标环境的实际配置和过程逻辑为准。 +- `CODE` 的定义在 `AD_SEQUENCE` 表中。`AD_COLUMN.SEQUENCENAME` 是单据字段配置的取号 CODE；要理解编号规则，继续到 `AD_SEQUENCE` 核实该 CODE 对应的定义。先确认目标环境的表结构和字段含义，不凭经验假定关联字段或编号格式。 +- 如果 `DOCNO` 对应的 `SEQUENCENAME` 有值，则生成 `Get_SequenceNo('', <单据的 AD_CLIENT_ID>)` 作为单据编号表达式。仅当该单据的 `AD_CLIENT_ID` 确认为 `37` 时，第二个参数才写 `37`；子表使用继承父表的客户 ID。配置为空时不猜测 `CODE`，应继续核实取号逻辑。 +- 取号函数可能推进编号状态，即使包装在 `SELECT` 中也不得通过 `query` / `qperm` 调用。这里只生成 SQL 示例，不实际取号。 - 如果目标表存在 `AD_CLIENT_ID` 字段，默认值使用 `37`。 - 如果目标表存在 `AD_ORG_ID` 字段，默认值使用 `27`。 - 子表的 `AD_CLIENT_ID` 和 `AD_ORG_ID` 默认取父表记录中对应字段值，不单独写固定值。 @@ -119,6 +137,7 @@ SELECT SEQUENCENAME FROM AD_COLUMN WHERE AD_TABLE_ID = (SELECT ID FROM AD_TABLE WHERE NAME = '<表名称>') AND UPPER(DBNAME) = 'DOCNO' + AND ROWNUM <= 20 ``` ## 字段值域映射规则（AD_COLUMN / AD_LIMITVALUE）