补充BOS单据取号及编号定义规则

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('<CODE>', 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。发布时同步私有主库、安装目录和无私有历史公共镜像。

CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.5.50 (2026-09-30)
+
+- 明确取单号函数 `Get_SequenceNo('<CODE>', 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` 主键模板。

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('<SEQUENCENAME>', 37)`。
+- 取单号函数为 `Get_SequenceNo('<CODE>', 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` 默认继承父表对应字段值。

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('<SEQUENCENAME>', 37)` 取单据编号。
+- 取单号函数为 `Get_SequenceNo('<CODE>', 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'`，不设置提交人和提交时间。

VERSION

@@ -1 +1 @@
-1.5.48
+1.5.50

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 '%零售%'
+WHERE NAME LIKE '%' || UNISTR('\96F6\552E') || '%'
-   OR DESCRIPTION LIKE '%零售%';
+   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. 查询字段业务含义

references/bos-metadata.md

@@ -4,10 +4,16 @@
 
 ## 数据字典（AD_TABLE / AD_COLUMN / AD_REFBYTABLE）
 
+### 单据编号定义（AD_SEQUENCE）
+
+取单号函数为 `Get_SequenceNo('<CODE>', 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 注册的数据库对象。

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('<SEQUENCENAME>', 37)` 取值。
+- 取单号函数为 `Get_SequenceNo('<CODE>', 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('<SEQUENCENAME>', <单据的 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）