同步 Skill 1.5.47 公共快照

AGENTS.md

@@ -1,6 +1,10 @@
 # oracle-jump-query Skill Release Standard
 
-Release 1.5.45: 以只读生产样本核验并完善 BOS 通用接口知识，覆盖核心四表、`AD_PROCESS` 三段任务、F/D/J 调度、请求封装、后台推送、两级回执处理、入站路由和客户差异核验边界。本次仅更新 Skill 文档，不修改 Agent、transit-server、接口、配置或审计 action；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。
+Release 1.5.47: 补充用户提供表名称时的 BOS 表解析规则：未明确要求绕过 BOS 元数据直接查询物理数据库对象时，先查 `AD_TABLE.NAME`、`DESCRIPTION` 和 `REALTABLE_ID`；虚拟表沿 `REALTABLE_ID` 定位实际表，未注册对象再按数据库表、视图、物化视图顺序查找。本次仅更新 Skill 文档，不修改 Agent、transit-server、CLI/HTTP 接口、配置或审计 action；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。
+
+Release 1.5.46: 明确 `PUSH_LOG.HEAD_DATA` 由 BOS 后台 API 合并，Oracle 数据库侧可能看不到该动作；排查时不得因 `H_INTERFACE_DATA_TASK` 未读取该字段就判断请求头缺失，也不得据此修改全局封装任务。本次仅更新 Skill 文档，不修改 Agent、transit-server、接口、配置或审计 action；命令数保持 32。发布时同步私有主库、安装目录和无私有历史公共镜像。
+
+Release 1.5.45: 以只读生产样本核验并完善 BOS 通用接口知识，覆盖核心四表、`AD_PROCESS` 三段任务、F/D/J 调度、请求封装、后台推送、两级回执处理、入站路由和客户差异核验边界。本次仅更新 Skill 文档，不修改 Agent、transit-server、接口、配置或审计 action；命令数保持 32。
 
 ## Git 提交说明
 

CHANGELOG.md

@@ -1,3 +1,15 @@
+## 1.5.47 (2026-09-02)
+
+- 补充用户提供表名称时的 BOS 表解析规则：默认先从 `AD_TABLE` 确认英文名称 `NAME`、中文显示名称 `DESCRIPTION` 和 `REALTABLE_ID`。
+- `REALTABLE_ID` 非空时按其指向的 `AD_TABLE` 记录定位实际数据库表，并明确原名称可能只是 BOS 虚拟表、在 Oracle 中不存在。
+- BOS 元数据未注册时，依次查询数据库表、视图和物化视图；本次仅更新 Skill 业务知识，不修改 Agent、transit-server、CLI/HTTP 接口、配置格式或审计 action，命令数保持 32。
+
+## 1.5.46 (2026-08-29)
+
+- 明确 `PUSH_LOG.HEAD_DATA` 在 BOS 标准通用接口中由后台 API 按推送记录合并，Oracle 数据库侧过程可能看不到该动作。
+- 排查请求头时不再因 `H_INTERFACE_DATA_TASK` 未读取 `HEAD_DATA` 就判定请求头缺失，也不为此修改全局封装任务；应继续核对后台实现或最终 HTTP 请求。
+- 本次仅更新 Skill 业务知识，不修改 Agent、transit-server、CLI/HTTP 接口、配置格式或审计 action；命令数保持 32。
+
 ## 1.5.45 (2026-08-29)
 
 - 以客户环境只读元数据、字段值域和过程源码核验通用接口模型，补充 `AD_PROCESS` 三段任务、F/D/J 调度、出站封装、后台推送、两级回执处理和入站路由知识。

SKILL.md

@@ -5,7 +5,7 @@ description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle
 
 # Oracle 跳板查询
 
-> **版本：v1.5.45** · [更新日志](./CHANGELOG.md)
+> **版本：v1.5.47** · [更新日志](./CHANGELOG.md)
 
 ## 使用原则
 
@@ -100,6 +100,8 @@ AD_SUBSYSTEM
   -> AD_CXTAB / AD_CXTAB_JPARA / AD_CXTAB_DIMENSION / AD_CXTAB_FACT
 ```
 
+用户提供表名称、且未明确要求绕过 BOS 元数据直接查询物理数据库对象时，先查 `AD_TABLE` 的 `NAME`、`DESCRIPTION`、`REALTABLE_ID`。若 `REALTABLE_ID` 非空，原名称可能只是 BOS 虚拟表，应改查其指向的实际表；若 `AD_TABLE` 未注册该名称，再按数据库表、视图、物化视图的顺序查找。完整 SQL 和判定规则见 [BOS 数据字典与系统地图](./references/bos-metadata.md)。
+
 处理单据类表时：
 
 - 先查 `AD_TABLE` 找表名、业务说明、`MASK`、`PROC_SUBMIT`、权限目录。`MASK` 是该表声明支持的业务动作代码：`A` 新增、`M` 修改、`D` 删除、`Q` 查询、`U` 取消提交、`V` 作废、`S` 提交；可由多个字母组合，分析功能时以实际值为准。

VERSION

@@ -1 +1 @@
-1.5.45
+1.5.47

references/bos-metadata.md

@@ -8,6 +8,61 @@
 
 处理 BOS 业务单据（如零售单、采购单、调拨单、销售单等）时，必须遵循以下查询路径：
 
+#### 用户提供表名称时的对象解析顺序
+
+用户给出一个表名称，且没有明确要求绕过 BOS 元数据、直接按 Oracle 物理对象查询时，不要立即对该名称执行 `describe` 或数据查询。先确认它是 BOS 逻辑表、BOS 实际表，还是未在 BOS 注册的数据库对象。
+
+1. 先用用户给出的名称精确查询 `AD_TABLE`，同时返回英文名称 `NAME`、通常为中文的显示名称 `DESCRIPTION` 和 `REALTABLE_ID`。必要时再用 `LIKE` 扩大范围，不要把模糊命中的第一条直接当成目标。
+
+```sql
+SELECT t.ID,
+       t.NAME,
+       t.DESCRIPTION,
+       t.REALTABLE_ID,
+       rt.NAME AS REALTABLE_NAME,
+       rt.DESCRIPTION AS REALTABLE_DESCRIPTION
+FROM AD_TABLE t
+LEFT JOIN AD_TABLE rt ON rt.ID = t.REALTABLE_ID
+WHERE UPPER(t.NAME) = UPPER('<表名称>')
+   OR t.DESCRIPTION = '<表名称>'
+```
+
+2. 查到 `AD_TABLE` 记录后，先向用户说明其 `DESCRIPTION` 和 `NAME`。若 `REALTABLE_ID` 非空，它表示该 BOS table 实际查询的表，应沿 `REALTABLE_ID -> AD_TABLE.ID` 使用目标记录的 `NAME` 继续查询结构或数据。原始名称可能只是 BOS 系统中的虚拟表，在 Oracle 数据库中并不存在；不要因为找不到同名物理表就判定对象不存在。若目标记录仍有 `REALTABLE_ID`，继续解析到最终实际表，并防止循环引用。
+3. 查到 `AD_TABLE` 记录但 `REALTABLE_ID` 为空时，使用该记录的 `NAME` 作为物理表候选，再到数据库字典确认。
+4. `AD_TABLE` 完全查不到时，该对象仍可能是未在 BOS 元数据中维护的数据库表。先查数据库表；查不到后再查普通视图，最后查物化视图。使用 `ALL_*` 字典时应返回 `OWNER`，避免把其他 schema 的同名对象误当成当前业务对象。
+
+```sql
+SELECT OWNER, TABLE_NAME
+FROM ALL_TABLES t
+WHERE t.TABLE_NAME = UPPER('<表名称>')
+  AND NOT EXISTS (
+      SELECT 1
+      FROM ALL_MVIEWS mv
+      WHERE mv.OWNER = t.OWNER
+        AND mv.MVIEW_NAME = t.TABLE_NAME
+  )
+ORDER BY CASE WHEN OWNER = SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') THEN 0 ELSE 1 END,
+         OWNER
+```
+
+```sql
+SELECT OWNER, VIEW_NAME
+FROM ALL_VIEWS
+WHERE VIEW_NAME = UPPER('<表名称>')
+ORDER BY CASE WHEN OWNER = SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') THEN 0 ELSE 1 END,
+         OWNER
+```
+
+```sql
+SELECT OWNER, MVIEW_NAME
+FROM ALL_MVIEWS
+WHERE MVIEW_NAME = UPPER('<表名称>')
+ORDER BY CASE WHEN OWNER = SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') THEN 0 ELSE 1 END,
+         OWNER
+```
+
+只有 `AD_TABLE`、数据库表、普通视图和物化视图都未命中时，才说明当前可见范围内未找到该对象。查询到 BOS 虚拟表时，业务含义和字段配置仍以原 `AD_TABLE` 记录为入口，物理结构与数据查询则以 `REALTABLE_ID` 最终指向的实际表为准。
+
 **1. 术语 → 表名（AD_TABLE）**
 
 遇到不懂的业务术语（如"零售单提交"、"采购入库"），先查 AD_TABLE：

references/generic-interface.md

@@ -180,7 +180,7 @@ PUSH_LOG（出站记录）       INF_LOG（入站记录）
 | `NAME`、`TYPE` | 接口或业务类型 | 以生成过程为准 |
 | `URL` | 实际请求地址 | 可能由接口方配置拼接产生 |
 | `JSON`、`JSON_BEFORE` | 待推送、转换前或转换后内容 | 必须查写入源码确认区别 |
-| `HEAD_DATA` | 单条推送的附加请求头 | 部分环境不存在或封装任务不读取 |
+| `HEAD_DATA` | 供 BOS 后台接口合并的单条推送附加请求头 | 数据库封装过程不读取并不代表最终请求未使用 |
 | `TBSTATUS` | 传输/同步状态 | 查询限定值和任务过程 |
 | `DOSTATUS` | 本地处理状态 | 不要与 TBSTATUS 混用 |
 | `NUM_REPUSH` | 已重试次数或剩余次数 | 以更新逻辑为准 |
@@ -216,7 +216,7 @@ D/J 调度：H_INSTRUCTION_TASK 判断到期
   -> 把 URL、内容、请求头等封装成 BOS 后台可识别的请求 JSON
   -> H_INTERFACE_TASK01 抢占未同步记录并置为同步中
   -> 调用 BOS_INF_PUSH，经 Oracle HTTP 请求 BOS 后台 API，并传入 PUSH_LOG.ID
-  -> BOS 后台按 ID 读取数据，补充应用密钥、签名或 Oracle 不便实现的加密
+  -> BOS 后台按 ID 读取数据，合并 PUSH_LOG.HEAD_DATA，并补充应用密钥、签名或 Oracle 不便实现的加密
   -> BOS 后台请求第三方 API，取得完整回执后调用 INF_PUSH_DEAL 回写数据库
   -> 先调用 H_INTERFACE.SETPCDE，更新 TBSTATUS
   -> 再调用 H_INSTRUCTION.SETPCDE，更新 DOSTATUS
@@ -228,8 +228,10 @@ D/J 调度：H_INSTRUCTION_TASK 判断到期
 ### 请求数据和请求头封装
 
 - 常见顺序是：`PCDE_PUSH` 先写业务 JSON，封装任务把它复制到 `JSON_BEFORE`，再用 `JSON` 保存包含 URL、业务内容和请求头的外层请求对象。
-- 公共请求头可能来自接口方明细表；单条记录的额外请求头可能来自 `PUSH_LOG.HEAD_DATA`。旧实现常见形态为 `[{"head":"content"}]`，另一些实现使用 `name`/`value` 对象。部分实现会合并两者并让单条请求头覆盖同名公共头。
+- 公共请求头可能来自接口方明细表；单条记录的动态或附加请求头保存在 `PUSH_LOG.HEAD_DATA`。旧实现常见形态为 `[{"head":"content"}]`，另一些实现使用 `name`/`value` 对象。
-- 请求头合并和冲突优先级不是固定契约。某些服务器虽然存在 `HEAD_DATA` 字段，当前封装过程却完全不读取它。分析时必须在封装过程源码中查找实际字段和覆盖顺序，不能只根据字段存在下结论。
+- BOS 标准通用接口中，`HEAD_DATA` 由 BOS 后台 API 按 `PUSH_LOG.ID` 读取并合并到最终第三方请求，数据库侧的 `H_INTERFACE_DATA_TASK` 等过程可能完全不读取该字段。因此，只看 Oracle 表和存储过程无法看到请求头合并动作，也不能据此判断 `HEAD_DATA` 未生效。
+- 不要为了让数据库源码“看见” `HEAD_DATA` 而直接修改全局 `H_INTERFACE_DATA_TASK`。排查请求头时，应先确认 `PCDE_PUSH` 是否正确写入 `HEAD_DATA`，再核对 BOS 后台接口代码、运行日志或最终发出的 HTTP 请求。
+- 请求头冲突优先级由 BOS 后台接口实现决定，不是 Oracle 数据库固定契约。需要判断公共头和 `HEAD_DATA` 同名时谁覆盖谁，必须查目标客户的后台实现；仅靠数据库查询无法得出结论。
 
 `PUSH_LOG` 为空时，先检查是否存在启用的出站指令和数据生成过程，再判断是“按设计未使用”还是“出站链路没有产生日志”。
 
@@ -390,8 +392,9 @@ ORDER BY t.NAME, c.ORDERNO
 - `H_INSTRUCTION.PCDE_PUSH`：出站数据生成或推送准备过程。
 - `AD_PROCESS`：确认 `H_INSTRUCTION_TASK`、`H_INTERFACE_DATA_TASK`、`H_INTERFACE_TASK01` 或客户等效任务是否注册和启用。
 - `H_INSTRUCTION_TASK`：核对 F/D/J 实际触发、计时单位、就绪状态和批次边界。
-- `H_INTERFACE_DATA_TASK`：核对 `JSON_BEFORE`、URL、接口方请求头、`HEAD_DATA` 的封装与覆盖顺序。
+- `H_INTERFACE_DATA_TASK`：核对 `JSON_BEFORE`、URL 和数据库侧外层请求封装；即使源码不读取 `HEAD_DATA`，也不能判定最终请求头缺失。
 - `H_INTERFACE_TASK01`、`BOS_INF_PUSH`：核对抢占状态、重试、Oracle HTTP 的后台 API 入口和异常处理。
+- BOS 后台 API：核对按 `PUSH_LOG.ID` 读取并合并 `HEAD_DATA`、公共头、密钥、签名和加密的实际规则；该边界无法只通过 Oracle 源码还原。
 - `INF_PUSH_DEAL`：核对接口方回执解析与指令业务处理的调用顺序、返回码和两类状态迁移。
 - `GET_HYJINF1` 或客户等效入口：核对 `v_type`/`CODE`、方向、启停、IP 白名单、日志落库和返回值。
 - 依赖 `INF_LOG` 的函数/过程：查实际入站入口和状态更新逻辑。
@@ -448,7 +451,7 @@ python scripts/oracle_skill.py analyze <schema> <object>
 - `DELQTY` 是否被实际任务读取，保留期是否真正执行。
 - 清理前是否满足审计、归档、备份和可恢复要求。
 - `JSON`、`JSON_BEFORE` 是否重复存储，原始报文是否真的可追溯。
-- `HEAD_DATA` 是否被封装过程读取，公共头与单条请求头冲突时谁覆盖谁。
+- `PCDE_PUSH` 是否正确写入 `HEAD_DATA`；BOS 后台是否读取并合并；公共头与单条请求头冲突时谁覆盖谁。不要因数据库封装过程未读取该字段就判定请求头丢失。
 - `DOCNO` 等搜索字段是否填充；敏感标识是否应脱敏或哈希。
 - 大量 CLOB、失效索引或长期历史是否造成空间增长。