From 496201250b6adf604697d1c0fd828c3042975928 Mon Sep 17 00:00:00 2001 From: chen qiang <343005560@qq.com> Date: Wed, 2 Sep 2026 15:51:33 +0800 Subject: [PATCH] =?UTF-8?q?=E5=90=8C=E6=AD=A5=20Skill=201.5.47=20=E5=85=AC?= =?UTF-8?q?=E5=85=B1=E5=BF=AB=E7=85=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 6 +++- CHANGELOG.md | 12 +++++++ SKILL.md | 4 ++- VERSION | 2 +- references/bos-metadata.md | 55 +++++++++++++++++++++++++++++++++ references/generic-interface.md | 15 +++++---- 6 files changed, 85 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e9022d7..1723860 100644 --- a/AGENTS.md +++ b/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 提交说明 diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b71823..71a11ec 100644 --- a/CHANGELOG.md +++ b/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 调度、出站封装、后台推送、两级回执处理和入站路由知识。 diff --git a/SKILL.md b/SKILL.md index edebc38..569283f 100644 --- a/SKILL.md +++ b/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` 提交；可由多个字母组合，分析功能时以实际值为准。 diff --git a/VERSION b/VERSION index eea87e0..cc48b9f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.5.45 +1.5.47 diff --git a/references/bos-metadata.md b/references/bos-metadata.md index cd7e95d..ce8bdb0 100644 --- a/references/bos-metadata.md +++ b/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： diff --git a/references/generic-interface.md b/references/generic-interface.md index 986068a..95d21d0 100644 --- a/references/generic-interface.md +++ b/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` 对象。部分实现会合并两者并让单条请求头覆盖同名公共头。 -- 请求头合并和冲突优先级不是固定契约。某些服务器虽然存在 `HEAD_DATA` 字段，当前封装过程却完全不读取它。分析时必须在封装过程源码中查找实际字段和覆盖顺序，不能只根据字段存在下结论。 +- 公共请求头可能来自接口方明细表；单条记录的动态或附加请求头保存在 `PUSH_LOG.HEAD_DATA`。旧实现常见形态为 `[{"head":"content"}]`，另一些实现使用 `name`/`value` 对象。 +- 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 - `DELQTY` 是否被实际任务读取，保留期是否真正执行。 - 清理前是否满足审计、归档、备份和可恢复要求。 - `JSON`、`JSON_BEFORE` 是否重复存储，原始报文是否真的可追溯。 -- `HEAD_DATA` 是否被封装过程读取，公共头与单条请求头冲突时谁覆盖谁。 +- `PCDE_PUSH` 是否正确写入 `HEAD_DATA`；BOS 后台是否读取并合并；公共头与单条请求头冲突时谁覆盖谁。不要因数据库封装过程未读取该字段就判定请求头丢失。 - `DOCNO` 等搜索字段是否填充；敏感标识是否应脱敏或哈希。 - 大量 CLOB、失效索引或长期历史是否造成空间增长。