diff --git a/AGENTS.md b/AGENTS.md index c8bc775..e9022d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # oracle-jump-query Skill Release Standard +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 5625b5c..2b71823 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## 1.5.45 (2026-08-29) + +- 以客户环境只读元数据、字段值域和过程源码核验通用接口模型，补充 `AD_PROCESS` 三段任务、F/D/J 调度、出站封装、后台推送、两级回执处理和入站路由知识。 +- 明确 `DOCNO`、`HEAD_DATA`、`TBSTATUS`、`DOSTATUS` 的常见表归属，区分传输成功与业务处理成功，并将请求头合并、即时触发和运行时方向校验列为逐环境核验项。 +- 本次仅更新 Skill 业务知识，不修改 Agent、transit-server、CLI/HTTP 接口、配置格式或审计 action；命令数保持 32。 + ## 1.5.44 (2026-08-27) - Skill 每次推送私有 Git 后，必须同步更新公共镜像，不再另行等待公开确认。 diff --git a/SKILL.md b/SKILL.md index 5bbfe8c..edebc38 100644 --- a/SKILL.md +++ b/SKILL.md @@ -5,7 +5,7 @@ description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle # Oracle 跳板查询 -> **版本：v1.5.44** · [更新日志](./CHANGELOG.md) +> **版本：v1.5.45** · [更新日志](./CHANGELOG.md) ## 使用原则 @@ -26,7 +26,7 @@ description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle - [BOS 数据字典与系统地图](./references/bos-metadata.md) `AD_TABLE`、`AD_COLUMN`、`AD_REFBYTABLE`、`AD_TABLE_TEXT`、BOS 系统菜单和表结构地图、数据权限模型。 - [通用接口业务逻辑](./references/generic-interface.md) - `H_INTERFACE`、`H_INSTRUCTION`、`PUSH_LOG`、`INF_LOG` 的通用职责、入站/出站流程、常见字段、状态核验、分析步骤和风险检查；处理不同客户服务器时必须以目标环境的实际表结构、BOS 元数据、值域和过程源码为准。 + `H_INTERFACE`、`H_INSTRUCTION`、`PUSH_LOG`、`INF_LOG`、`AD_PROCESS` 的通用职责、调度任务、入站/出站流程、常见字段、状态核验、分析步骤和风险检查；处理不同客户服务器时必须以目标环境的实际表结构、BOS 元数据、值域和过程源码为准。 - [表空间、服务器体检与 Oracle 运维监控](./references/oracle-ops-and-checkup.md) 表空间、服务器体检、Oracle 运维报告、SYS/当前账号函数授权方案和 AWR 未来开发计划。 - [整理前完整 SKILL.md 备份](./references/legacy-skill-v1.5.8.md) @@ -114,7 +114,7 @@ AD_SUBSYSTEM ## 业务规则速记 -- 用户提到“通用接口”“接口指令”“接口方”“推送日志”“接收日志”或要求分析 `H_INTERFACE`、`H_INSTRUCTION`、`PUSH_LOG`、`INF_LOG` 时，先读取 [通用接口业务逻辑](./references/generic-interface.md)。这四张表是常见模型而不是固定契约；不同服务器可能缺表、增表、增减字段、改变值域或使用不同处理过程，必须先查目标环境再下结论。 +- 用户提到“通用接口”“接口指令”“接口方”“推送日志”“接收日志”“数据接口任务”“数据队列封装/推送”，或要求分析 `H_INTERFACE`、`H_INSTRUCTION`、`PUSH_LOG`、`INF_LOG`、`AD_PROCESS`、`H_INSTRUCTION_TASK`、`H_INTERFACE_DATA_TASK`、`H_INTERFACE_TASK01`、`BOS_INF_PUSH`、`INF_PUSH_DEAL`、`GET_HYJINF1` 时，先读取 [通用接口业务逻辑](./references/generic-interface.md)。这些对象是常见模型而不是固定契约；不同服务器可能缺表、增表、增减字段、改变值域、请求头合并规则或处理过程，必须先查目标环境再下结论。 - 商品、款号通常指 `M_PRODUCT`。 - 条码、SKU 通常指 `M_PRODUCT_ALIAS`；查询条码时首查 `M_PRODUCT_ALIAS.NO`。 - 款号和条码是一对多关系。 diff --git a/VERSION b/VERSION index fe2f629..eea87e0 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.5.44 +1.5.45 diff --git a/references/generic-interface.md b/references/generic-interface.md index e6382ce..986068a 100644 --- a/references/generic-interface.md +++ b/references/generic-interface.md @@ -4,16 +4,17 @@ 本业务统一称为：**通用接口**。 -通用接口通常由以下四张核心表组成： +通用接口通常由四张业务表和一个任务程序入口组成： ```text H_INTERFACE H_INSTRUCTION PUSH_LOG INF_LOG +AD_PROCESS ``` -这四张表描述的是常见接口框架，不是所有客户服务器都完全一致的固定数据库契约。不同环境可能出现： +前四张表描述接口配置和收发队列，`AD_PROCESS` 注册 BOS 可执行的任务程序。它们是常见接口框架，不是所有客户服务器都完全一致的固定数据库契约。不同环境可能出现： - 某张表不存在，或存在额外的接口方明细、IP 白名单、请求头、参数映射等子表。 - 字段数量、字段类型、默认值、是否可空、索引和约束不同。 @@ -23,7 +24,7 @@ INF_LOG 因此分析通用接口时，必须先查询目标服务器的实际结构、BOS 元数据、限定值和过程源码，不得直接套用其他客户环境的接口名称、过程名、字段列表、状态含义、数据量或结论。 -## 四表职责 +## 核心对象职责 | 表 | 通用职责 | 数据性质 | | --- | --- | --- | @@ -31,6 +32,7 @@ INF_LOG | `H_INSTRUCTION` | 定义接口指令、传输方向、处理过程、调度、重试和启停规则 | 核心指令/路由配置表 | | `PUSH_LOG` | 保存待发送数据，并记录出站推送、重试和处理结果 | 出站队列兼日志表 | | `INF_LOG` | 保存外部传入请求，并记录入站处理状态和返回结果 | 入站请求兼日志表 | +| `AD_PROCESS` | 注册数据生成、队列封装、队列推送等 BOS 任务程序 | 任务程序注册表 | 可以用下面的业务问题快速理解四表分工： @@ -39,6 +41,7 @@ H_INTERFACE：数据发给谁？目标地址和公共回执如何处理？ H_INSTRUCTION：发什么或收什么？由哪个过程处理？何时执行？ PUSH_LOG：准备发出去什么？是否已经发送和处理成功？ INF_LOG：外部传进来什么？本地是否处理成功？返回了什么？ +AD_PROCESS：BOS 任务引擎可以定期执行哪些接口程序？ ``` ## 常见关系 @@ -77,6 +80,8 @@ PUSH_LOG（出站记录） INF_LOG（入站记录） `H_INTERFACE` 用于描述一个外部系统或接口目标，常见于出站推送场景。它通常保存接口名称、地址、公共回执解析方式和启用状态，本身不保存具体待推送业务数据。 +常见做法是“一个第三方 API 或一类共用地址/回执协议对应一个接口方”。`URL` 提供基础或实际接口地址；第三方回执返回后，框架先调用接口方的 `SETPCDE` 解析传输层结果，再决定是否进入指令级业务处理。一个第三方系统拥有多个地址、请求头或协议时，也可能拆成多个接口方或接口方明细，不能把“一接口一接口方”当成物理约束。 + ### 常见字段族 | 常见字段 | 常见含义 | 核验要求 | @@ -126,6 +131,18 @@ PUSH_LOG（出站记录） INF_LOG（入站记录） | `DELQTY` | 常见为日志保留天数 | 必须验证是否真的存在清理任务 | | `MSG_ERROR` | 最近一次任务错误或执行信息 | 可能被后续执行覆盖，不等于完整历史 | +`CODE` 是接口路由的稳定标识，常见命名为“接口方缩写_业务或档案_功能”，例如用末段区分创建、更新、取消或查询。这个规则用于提高可读性，不替代唯一性约束；入站 API 的 `v_type`、日志的 `TYPE` 和代码中的大小写处理仍须实查。 + +时间规则的通用语义是： + +| `TIMERULES` | 语义 | 配置和触发方式 | +| --- | --- | --- | +| `F` | 即时 | 通常由业务事件直接生成 `PUSH_LOG`；标准任务不轮询调用 `PCDE_PUSH` | +| `D` | 定时 | `TIMES_H`、`TIMES_M` 必填，到达当天指定时刻后把指令置为待执行 | +| `J` | 间隔 | `SETTIMES` 保存选项，配置校验过程换算到 `SETTIMES_S`；任务累计 `TIMESCOUNT` 后触发 | + +常见配置校验过程会在 `F` 时清空 `PCDE_PUSH` 和调度字段，在 `D/J` 时要求 `PCDE_PUSH` 及对应时间参数。因而“即时”不等于定时任务立即调用生成过程；必须追踪业务提交过程、表单事件或其他过程在哪里直接写入 `PUSH_LOG`。 + ### 入站配置的常见约束 - `INOUT` 为入站时，通常必须配置 `SETPCDE`。 @@ -137,6 +154,8 @@ PUSH_LOG（出站记录） INF_LOG（入站记录） - `INOUT` 为出站时，通常需要接口方或可解析出的目标地址。 - 非即时任务通常需要 `PCDE_PUSH` 和有效调度参数。 - 定时或间隔任务可能通过 `IS_READY`、`TIMESCOUNT` 等字段协调执行。 +- `PCDE_PUSH` 是 `H_INSTRUCTION` 上的数据生成过程配置，不是 `PUSH_LOG` 字段。标准签名常接收指令 ID，并输出结果码和消息；签名以源码为准。 +- `SETPCDE` 是指令级触发/业务处理过程。出站时在接口方回执解析后调用；入站时在请求落入 `INF_LOG` 后调用。 ### 分析重点 @@ -161,10 +180,11 @@ PUSH_LOG（出站记录） INF_LOG（入站记录） | `NAME`、`TYPE` | 接口或业务类型 | 以生成过程为准 | | `URL` | 实际请求地址 | 可能由接口方配置拼接产生 | | `JSON`、`JSON_BEFORE` | 待推送、转换前或转换后内容 | 必须查写入源码确认区别 | +| `HEAD_DATA` | 单条推送的附加请求头 | 部分环境不存在或封装任务不读取 | | `TBSTATUS` | 传输/同步状态 | 查询限定值和任务过程 | | `DOSTATUS` | 本地处理状态 | 不要与 TBSTATUS 混用 | | `NUM_REPUSH` | 已重试次数或剩余次数 | 以更新逻辑为准 | -| `DOCNO` | 单号或搜索标识 | 可能为空或存脱敏/哈希标识 | +| `DOCNO` | 单号或快速搜索标识 | 可按业务保存单号、手机号、SKU 等；注意索引和脱敏要求 | | `MSG`、`REMARK` | 处理结果或外部响应 | 可能包含敏感信息 | | `CREATIONDATE`、`MODIFIEDDATE` | 创建、更新时间 | 用于队列时效和历史分析 | @@ -179,19 +199,38 @@ DOSTATUS：1 未处理、2 处理成功、3 处理失败 这只是常见参考，不是跨服务器固定契约。实际分析时必须从 `AD_COLUMN.OBTAINMANNER`、`AD_LIMITVALUE_GROUP_ID`、`AD_LIMITVALUE` 和任务过程源码核实。 -### 出站流程 +两类状态不能合并解释： + +- `TBSTATUS` 表示接口传输/回执解析层是否跑通。常见实现由 `H_INTERFACE.SETPCDE` 的返回码决定；第三方已经收到请求并返回可解析回执时，即使业务结果为拒绝，也可能仍是“同步成功”。 +- `DOSTATUS` 表示接口回执后的本地业务处理结果。`H_INSTRUCTION.SETPCDE` 的业务判断、单据处理或异常都可能令它失败。 +- 指令没有配置 `SETPCDE` 时，部分实现会直接把 `DOSTATUS` 映射为 `TBSTATUS`；报告必须注明这是回退行为，不代表执行过业务处理过程。 + +### 标准出站流程 ```text -业务过程或定时任务 - -> 根据 H_INSTRUCTION 产生待推送数据 - -> 写入 PUSH_LOG - -> 推送任务筛选待同步记录 - -> 根据 H_INSTRUCTION / H_INTERFACE 取得处理过程和目标地址 - -> 调用外部接口 - -> 更新 TBSTATUS、DOSTATUS、NUM_REPUSH、MSG/REMARK - -> 成功结束，或按规则重试/转人工处理 +F 即时：业务事件直接生成第三方所需 JSON 并写入 PUSH_LOG +D/J 调度：H_INSTRUCTION_TASK 判断到期 + -> 执行 H_INSTRUCTION.PCDE_PUSH，生成业务 JSON 并写入 PUSH_LOG +两条路径汇合，PUSH_LOG 初始为未同步/未处理 + -> H_INTERFACE_DATA_TASK 补 URL，先把业务 JSON 留存到 JSON_BEFORE + -> 把 URL、内容、请求头等封装成 BOS 后台可识别的请求 JSON + -> H_INTERFACE_TASK01 抢占未同步记录并置为同步中 + -> 调用 BOS_INF_PUSH，经 Oracle HTTP 请求 BOS 后台 API，并传入 PUSH_LOG.ID + -> BOS 后台按 ID 读取数据，补充应用密钥、签名或 Oracle 不便实现的加密 + -> BOS 后台请求第三方 API，取得完整回执后调用 INF_PUSH_DEAL 回写数据库 + -> 先调用 H_INTERFACE.SETPCDE，更新 TBSTATUS + -> 再调用 H_INSTRUCTION.SETPCDE，更新 DOSTATUS + -> 成功结束，或按重试规则重新入队/转人工处理 ``` +标准过程名是常见实现入口，不是所有客户必须同名。`BOS_INF_PUSH` 通常只负责从 Oracle 发起到 BOS 后台的 HTTP 请求，真正面向第三方的密钥补充、签名、加密和 HTTP 调用在后台 API 完成；只看 Oracle 源码无法证明后台内部行为，必要时还要核对对应后台接口代码。 + +### 请求数据和请求头封装 + +- 常见顺序是：`PCDE_PUSH` 先写业务 JSON，封装任务把它复制到 `JSON_BEFORE`，再用 `JSON` 保存包含 URL、业务内容和请求头的外层请求对象。 +- 公共请求头可能来自接口方明细表；单条记录的额外请求头可能来自 `PUSH_LOG.HEAD_DATA`。旧实现常见形态为 `[{"head":"content"}]`，另一些实现使用 `name`/`value` 对象。部分实现会合并两者并让单条请求头覆盖同名公共头。 +- 请求头合并和冲突优先级不是固定契约。某些服务器虽然存在 `HEAD_DATA` 字段，当前封装过程却完全不读取它。分析时必须在封装过程源码中查找实际字段和覆盖顺序，不能只根据字段存在下结论。 + `PUSH_LOG` 为空时，先检查是否存在启用的出站指令和数据生成过程，再判断是“按设计未使用”还是“出站链路没有产生日志”。 ## INF_LOG：入站请求和处理日志 @@ -214,19 +253,20 @@ DOSTATUS：1 未处理、2 处理成功、3 处理失败 | `DOCNO` | 单号或业务关键字 | 可能未填充；注意敏感信息保护 | | `CREATIONDATE` | 接收时间 | 用于时效、流量和保留期分析 | -### 入站流程 +### 标准入站流程 ```text -外部请求 - -> 入站入口函数/过程 - -> 根据 TYPE 或 CODE 查 H_INSTRUCTION - -> 写 INF_LOG，常见初始状态为未处理 - -> 调用 H_INSTRUCTION.SETPCDE - -> 处理成功：更新为成功并保存返回内容 - -> 处理失败：更新为失败并保存业务错误或技术错误 - -> 将结果返回调用方 +第三方请求 BOS 后台 API + -> 后台调用 GET_HYJINF1(jsonstr, v_type, v_url) 或客户等效入口 + -> 以 v_type 匹配 H_INSTRUCTION.CODE，并检查启用、运行和可选 IP 白名单 + -> 写 INF_LOG，保留来源、TYPE、原始/规范化内容和指令 ID + -> 动态调用 H_INSTRUCTION.SETPCDE + -> 根据返回码更新 DOSTATUS 和 MSG + -> 将业务结果经 BOS 后台返回第三方 ``` +配置模型要求入站指令使用 `INOUT='IN'`，但部分入口函数只按 `CODE`、`ISRUN`、`ISACTIVE` 匹配，并未在 SQL 中强制过滤 `INOUT`。分析时必须同时核对配置和入口源码；缺少方向校验应作为路由风险记录，不能因表单校验存在就假定运行时一定安全。 + ### 分析重点 - 是否存在长时间停留在“未处理”的积压记录。 @@ -237,9 +277,21 @@ DOSTATUS：1 未处理、2 处理成功、3 处理失败 - 来源地址是否单一、是否启用 IP 白名单、网络层是否有等效控制。 - 请求内容、响应信息是否包含个人信息、凭证、令牌或其他敏感数据。 +## AD_PROCESS 和三段任务链路 + +`AD_PROCESS` 是 BOS 任务程序注册表，常见字段包括名称、说明、过程名、累计执行次数/耗时和启用状态。通用接口部署通常注册： + +| 常见任务 | 常见过程 | 作用 | +| --- | --- | --- | +| 数据接口任务触发 | `H_INSTRUCTION_TASK` | 累加间隔计时，判断 D/J 指令是否到期，按优先级动态调用 `PCDE_PUSH` | +| 数据队列数据封装 | `H_INTERFACE_DATA_TASK` | 处理已生成但尚未补齐地址/外层请求的 `PUSH_LOG` | +| 数据队列推送 | `H_INTERFACE_TASK01` | 抢占已封装的未同步记录，调用 `BOS_INF_PUSH` 进入后台推送链路 | + +`AD_PROCESS` 注册“执行什么”，通常不保存完整的执行日历。不能只凭该表判断每十秒、每分钟或每天执行；还要检查 BOS 任务实例/调度配置、调用方和过程源码。标准任务也常设置单批行数、只处理最近记录、优先级和同步中状态，以避免重复推送；这些边界必须逐环境核验。 + ## 标准分析流程 -用户要求分析“通用接口”或这四张表时，按以下顺序执行。 +用户要求分析“通用接口”、核心四表、数据队列或上述任务过程时，按以下顺序执行。 ### 1. 确认目标环境 @@ -259,6 +311,7 @@ python scripts/oracle_skill.py describe H_INTERFACE python scripts/oracle_skill.py describe H_INSTRUCTION python scripts/oracle_skill.py describe PUSH_LOG python scripts/oracle_skill.py describe INF_LOG +python scripts/oracle_skill.py describe AD_PROCESS ``` 如果指定 schema 不正确，使用命令返回的实际 owner，并继续核验 `ALL_TAB_COLUMNS`。不要因为某环境常用某个 schema 就硬编码 owner。 @@ -328,17 +381,25 @@ ORDER BY t.NAME, c.ORDERNO - 用 `ALL_INDEXES` / `ALL_IND_COLUMNS` 查状态、时间、指令和业务关键字索引。 - 特别检查 `H_INSTRUCTION.CODE` 是否唯一，以及日志的 `H_INSTRUCTION_ID` 是否可能成为孤儿。 -### 5. 查处理过程和任务源码 +### 5. 查任务注册、处理过程和后台边界 从以下入口继续追踪： - `AD_TABLE.TRIG_AC`、`TRIG_AM`：指令配置新增/修改后的校验过程。 - `H_INSTRUCTION.SETPCDE`：入站业务处理过程。 - `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_TASK01`、`BOS_INF_PUSH`：核对抢占状态、重试、Oracle HTTP 的后台 API 入口和异常处理。 +- `INF_PUSH_DEAL`：核对接口方回执解析与指令业务处理的调用顺序、返回码和两类状态迁移。 +- `GET_HYJINF1` 或客户等效入口：核对 `v_type`/`CODE`、方向、启停、IP 白名单、日志落库和返回值。 - 依赖 `INF_LOG` 的函数/过程：查实际入站入口和状态更新逻辑。 - 依赖 `PUSH_LOG` 的过程：查出站任务、重试、状态迁移和回执处理。 - `USER_JOBS`、`USER_SCHEDULER_JOBS` 或 BOS 任务表：查调度和日志清理任务。 +遇到标准过程名不存在时，按 `AD_PROCESS.PROCEDURENAME`、`USER_DEPENDENCIES` 和对 `PUSH_LOG`/`INF_LOG` 的源码引用定位等效对象，不要据名称猜测。Oracle 源码只覆盖数据库到 BOS 后台这一段；第三方请求方式、后台补参和加密必须从后台路由或代码继续核验。 + 优先使用： ```powershell @@ -372,6 +433,8 @@ python scripts/oracle_skill.py analyze - 是否校验重复请求和幂等性，重试是否可能重复写业务数据。 - `CODE` 重复、大小写不一致或未知指令时是否返回明确错误。 - 动态调用的过程名是否经过白名单或严格配置权限控制。 +- 入站入口是否实际限制 `INOUT='IN'`，出站任务是否实际限制 `INOUT='OUT'`。 +- 即时指令由哪个业务事件写入 `PUSH_LOG`，是否可能重复入队。 ### 可观测性 @@ -385,6 +448,7 @@ python scripts/oracle_skill.py analyze - `DELQTY` 是否被实际任务读取，保留期是否真正执行。 - 清理前是否满足审计、归档、备份和可恢复要求。 - `JSON`、`JSON_BEFORE` 是否重复存储，原始报文是否真的可追溯。 +- `HEAD_DATA` 是否被封装过程读取，公共头与单条请求头冲突时谁覆盖谁。 - `DOCNO` 等搜索字段是否填充；敏感标识是否应脱敏或哈希。 - 大量 CLOB、失效索引或长期历史是否造成空间增长。