199 lines
12 KiB
Markdown
199 lines
12 KiB
Markdown
---
|
||
name: oracle-jump-query
|
||
description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle 数据库的元数据、存储过程源码、依赖、表结构、触发器、业务字典、表空间、服务器体检和 Oracle 运维监控。连接数据库默认为只读，禁止通过 skill 查询通道直接执行 INSERT、UPDATE、DELETE、MERGE、DDL 等写操作。当用户需要分析 Oracle 存储过程、查找依赖表、查询表结构、理解 BOS 业务元数据、生成只读查询 SQL 或生成需人工确认的写库 SQL 示例时触发。
|
||
---
|
||
|
||
# Oracle 跳板查询
|
||
|
||
> **版本：v1.5.37** · [更新日志](./CHANGELOG.md)
|
||
|
||
## 使用原则
|
||
|
||
使用本 skill 时，先确认当前登录状态和 client。用户指定“恒诺 / 品小二 / 未芮 / 康奈”等服务器时，可以用 `switch <clientCode|clientName>` 按 code 或名称切换；找不到目标服务器时，skill 会先刷新 client 列表再重试匹配。若名称不够准确并匹配到多个 client，只列出候选项，请用户指定更准确的 client code，不要直接猜测切换。
|
||
|
||
本 skill 的数据库通道默认只读。可以生成 SQL 和说明，但不得通过 `query` / `qperm` 执行写库语句，包括 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、`DDL`、提交存储过程和其他会改变业务数据的调用。用户要求写库时，只生成 SQL，并明确说明未执行。
|
||
|
||
生产环境查询必须带明确 `WHERE` 条件和行数限制。不要为了“先看看数据”查询整表；涉及库存视图、业务大表、统计查询时尤其要先限定门店、日期、单号、状态、款号、条码或主键范围。
|
||
|
||
## 参考文档
|
||
|
||
详细规则已经拆分到 `references/`，处理对应任务时必须读取相关文件：
|
||
|
||
- [命令、登录与调用方式](./references/commands-and-auth.md)
|
||
登录、client 切换、CLI 命令、HTTP action、故障排查。
|
||
- [生产查询限制与常用业务规则](./references/query-and-business-rules.md)
|
||
生产查询限制、商品/款号/条码/库存规则、新增业务记录 SQL 生成规则、字段值域映射。
|
||
- [BOS 数据字典与系统地图](./references/bos-metadata.md)
|
||
`AD_TABLE`、`AD_COLUMN`、`AD_REFBYTABLE`、`AD_TABLE_TEXT`、BOS 系统菜单和表结构地图、数据权限模型。
|
||
- [表空间、服务器体检与 Oracle 运维监控](./references/oracle-ops-and-checkup.md)
|
||
表空间、服务器体检、Oracle 运维报告、SYS/当前账号函数授权方案和 AWR 未来开发计划。
|
||
- [整理前完整 SKILL.md 备份](./references/legacy-skill-v1.5.8.md)
|
||
为防止内容遗漏保留的完整原文；如发现拆分文档缺项，以此为准补回。
|
||
|
||
## 常用命令
|
||
|
||
命令均在 skill 目录执行：
|
||
|
||
```powershell
|
||
cd C:\Users\qiang\.codex\skills\oracle-jump-query
|
||
python scripts/oracle_skill.py <command> [args]
|
||
```
|
||
|
||
登录中转机：
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py login <secretKey> [clientCode]
|
||
```
|
||
|
||
`clientCode` 是客户服务器编号，非必填；不传时中转机会默认选择 BOS 返回的第一个可用 client。登录成功后本地只保存中转机签发的 `access_token` 和过期时间，不保存 BOS `secretKey`。同一个 `secretKey` 同时只允许一个设备在线，其他设备重新登录后，当前 token 会失效。
|
||
|
||
常用命令：
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `status` | 查看登录状态、当前 client 和 Agent 状态 |
|
||
| `clients` | 无感刷新当前用户最新授权的 client 列表（只使用当前登录 token） |
|
||
| `switch <clientCode|clientName>` | 按 code 或名称切换当前 client；找不到时自动刷新 client 列表 |
|
||
| `analyze <schema> <proc>` | 完整分析存储过程 |
|
||
| `source <schema> <proc>` | 获取存储过程源码 |
|
||
| `deps <schema> <proc>` | 获取依赖对象 |
|
||
| `tables <schema> <proc>` | 获取相关表结构 |
|
||
| `describe <schema> <table>` | 查询表结构 |
|
||
| `query <SQL>` | 执行只读 SELECT 查询 |
|
||
| `qperm <userId> <tableId> <SQL>` | 带权限过滤的只读查询 |
|
||
| `tablespace` / `tablespaces` | 查询表空间 |
|
||
| `ops <item> [clientCode]` | 单项 Oracle 运维监控 |
|
||
| `ops_report [clientCode]` | Oracle 运维报告 |
|
||
| `inspection_report [clientCode] [--json] [--html [path]] [--markdown [path]]` | 生成服务器巡检报告并归档，默认导出固定格式 HTML，可同时导出 Markdown |
|
||
| `inspection_latest [clientCode] [--refresh] [--json] [--html [path]] [--markdown [path]]` | 查看最近归档巡检报告并默认导出 HTML；加 `--refresh` 时重新生成 |
|
||
| `inspection_get <id> [--json] [--html [path]] [--markdown [path]]` | 按归档 ID 查看历史巡检报告并默认导出 HTML |
|
||
| `awr_status [clientCode] [--json]` | 查看 AWR 授权确认、权限、快照和最近生成状态，不触发生成 |
|
||
| `awr_list [clientCode] [--json]` | 列出 Agent 已生成并保留的 AWR 报告 |
|
||
| `awr_download <clientCode> <yyyyMMdd> [--output path]` | 经中转机下载 Agent 原始 AWR HTML，不在本地渲染 |
|
||
| `agent_update [clientCode] [timeout]` | 触发客户 Agent 自动更新；由中转机下发更新动作，Agent 按 OSS latest.json 返回的包地址下载升级 |
|
||
|
||
## BOS 分析优先路径
|
||
|
||
遇到不懂的 BOS 业务术语、表单、菜单、模块、按钮、状态、字段含义时，优先走元数据，不要靠表名猜测：
|
||
|
||
```text
|
||
AD_SUBSYSTEM
|
||
-> AD_TABLECATEGORY
|
||
-> AD_ACCORDION
|
||
-> AD_TABLE
|
||
-> AD_COLUMN
|
||
-> AD_REFBYTABLE
|
||
-> AD_ACTION
|
||
-> DIRECTORY
|
||
-> AD_CXTAB / AD_CXTAB_JPARA / AD_CXTAB_DIMENSION / AD_CXTAB_FACT
|
||
```
|
||
|
||
处理单据类表时：
|
||
|
||
- 先查 `AD_TABLE` 找表名、业务说明、`MASK`、`PROC_SUBMIT`、权限目录。`MASK` 是该表声明支持的业务动作代码：`A` 新增、`M` 修改、`D` 删除、`Q` 查询、`U` 取消提交、`V` 作废、`S` 提交；可由多个字母组合，分析功能时以实际值为准。
|
||
- 同查 `AD_TABLE` 的表单事件过程：`HAS_TRIG_BD='Y'` 时 `TRIG_BD` 是删除前触发的存储过程（简称 bd）；`HAS_TRIG_AC='Y'` 时 `TRIG_AC` 是新增后触发的存储过程（简称 ac）；`HAS_TRIG_AM='Y'` 时 `TRIG_AM` 是修改后触发的存储过程（简称 am）。
|
||
- 再查 `AD_COLUMN` 理解字段含义、控件类型、默认值、引用列和值域。
|
||
- 明细表必须通过 `AD_REFBYTABLE` 查找，不要靠命名规则猜。
|
||
- 若 `AD_COLUMN.OBTAINMANNER='select'`，必须通过 `AD_LIMITVALUE_GROUP_ID` 查询 `AD_LIMITVALUE`，把显示值映射成数据库实际值。
|
||
- 如果用户提到“提交”，通常指执行或分析 `AD_TABLE.PROC_SUBMIT` 对应提交过程，不要简单理解为直接更新 `STATUS='2'`。
|
||
- `AD_TABLE_TEXT` 可作为 BOS 系统地图经验来源：它说明菜单、模块、业务表、字段、主子表、动作、权限目录和报表模板主要由 BOS 元数据表驱动。
|
||
|
||
常用系统地图 SQL 见 [BOS 数据字典与系统地图](./references/bos-metadata.md)。
|
||
|
||
## 业务规则速记
|
||
|
||
- 商品、款号通常指 `M_PRODUCT`。
|
||
- 条码、SKU 通常指 `M_PRODUCT_ALIAS`；查询条码时首查 `M_PRODUCT_ALIAS.NO`。
|
||
- 款号和条码是一对多关系。
|
||
- 商品明细里的 `M_PRODUCT_ID`、`M_PRODUCTALIAS_ID`、`M_ATTRIBUTESETINSTANCE_ID` 通常分别对应款号、条码、色码属性 ASI。
|
||
- `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)` 取单据编号。
|
||
- 如表存在 `AD_CLIENT_ID`，默认值 `37`；如存在 `AD_ORG_ID`，默认值 `27`。
|
||
- 子表的 `AD_CLIENT_ID`、`AD_ORG_ID` 默认继承父表。
|
||
- 新增表单若存在 `STATUS`、`STATUSERID`、`STATUSTIME`，通常只设置 `STATUS='1'`，不设置提交人和提交时间。
|
||
- 生成提交 SQL 或说明提交流程时，如果已知 `userId`，调用 `AD_TABLE.PROC_SUBMIT` 前需要先更新主单据修改人和修改时间，再调用提交存储过程；修改人、修改时间字段名必须先通过 `AD_COLUMN` 或表结构确认，不要凭经验硬写字段名。
|
||
|
||
## 运维能力速记
|
||
|
||
当用户说“给我 HENLO 的 Oracle 运维报告 / 数据库日报 / Oracle 巡检”时，使用：
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py ops_report HENLO
|
||
```
|
||
|
||
当用户说“给我 HENLO 的服务器巡检报告 / 运维体检报告 / 查看最近一次巡检报告”时，使用：
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py inspection_report HENLO
|
||
python scripts/oracle_skill.py inspection_latest HENLO
|
||
python scripts/oracle_skill.py inspection_report HENLO --markdown
|
||
```
|
||
|
||
巡检命令成功后默认在 `outputs/` 生成 HTML；需要 Markdown 时增加 `--markdown` 或 `--md`，也可在参数后指定输出路径。
|
||
|
||
生成新报告前必须先执行 `sys_function_check`。若 `SYS.HENLO_ORA_MONITOR` 和当前 schema 的 `HENLO_ORA_MONITOR` 均不可执行或版本契约不兼容，立即停止采集并返回完整 SYS 函数与授权 SQL；不得先生成部分报告。Skill 必须使用目标 Agent 返回的有效 Oracle schema 自动替换 `<AGENT_SCHEMA>`，直接向用户提供可执行 SQL，不得让用户手工修改占位符；无法确定 schema 时停止并提示检查 Agent 配置。读取既有历史报告不需要重复执行该预检，只有 `inspection_latest --refresh` 需要。
|
||
|
||
当用户要求“更新客户 Agent / 触发 Agent 升级 / 给某客户发版升级”时，使用：
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py agent_update HENLO 300
|
||
```
|
||
|
||
`clientCode` 可省略，默认使用当前已切换的 client；`timeout` 默认 300 秒。该命令只触发中转机的 `/api/admin/agent_update/trigger`，实际升级包由 Agent 从 OSS 下载，不再从 transit-server 本机下载。
|
||
|
||
涉及 `v$`、`dba_`、AWR、SYS 权限视图时，Agent 会优先调用 `SYS.HENLO_ORA_MONITOR`；如果不可用，再尝试当前登录账号下的 `HENLO_ORA_MONITOR`。函数缺失或无权限时，输出安装 SQL，让用户用 SYS 或有视图查询权限的当前账号安装后再试。
|
||
|
||
AWR 报告只有在客户 DBA 已确认 Diagnostics Pack 授权，且 Agent 配置 `awr.enabled=true`、`awr.license_confirmed=true` 后才可用。日常巡检不会隐式生成 AWR；Skill 只列出或下载 Agent 已生成的 HTML：
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py awr_status WEIRUI
|
||
python scripts/oracle_skill.py awr_list WEIRUI
|
||
python scripts/oracle_skill.py awr_download WEIRUI 20260720
|
||
```
|
||
|
||
## 内容维护
|
||
|
||
本 skill 的 Git 源地址分为私有主库和公开镜像：
|
||
|
||
```text
|
||
私有主库：https://gitea.momozhua.site/qiangayi/oracle-jump-query
|
||
公开镜像：https://gitea.momozhua.site/qiangayi/oracle-jump-query-public
|
||
```
|
||
|
||
日常开发、提交和 Codex Skill 同步使用私有主库；公开镜像只包含经人工确认的无历史快照，适合新用户下载使用。不要把 `C:\Users\qiang\.codex\skills\oracle-jump-query` 当作长期源码目录；该目录只用于安装后的运行和验证。
|
||
|
||
整理文档时不得删除既有内容。需要精简主 `SKILL.md` 时，只能把内容移动到 `references/`，并更新索引；确实要删除内容，必须先得到用户明确同意。
|
||
|
||
|
||
## Agent version query
|
||
|
||
Natural language: query all customer Agent versions, or query HENLO and RENBEN Agent versions.
|
||
|
||
Commands:
|
||
- python scripts/oracle_skill.py version agent HENLO RENBEN --json
|
||
- python scripts/oracle_skill.py version agent --all --json
|
||
|
||
Online Agents return their current version; offline customers return the last heartbeat version and offline status.
|
||
|
||
## SYS function deployment bundle
|
||
|
||
Generate all SYS-created functions required by the Skill for a customer Agent schema:
|
||
|
||
```powershell
|
||
python scripts/oracle_skill.py sys_functions BOSNDS3
|
||
```
|
||
|
||
## Skill 更新方式
|
||
|
||
Skill 仅通过 Gitea Git 仓库更新，不使用 OSS 发布或 `skill_update` 命令。源码修改、提交和推送均在源码仓库完成；已安装目录仅执行拉取与验证：
|
||
|
||
```powershell
|
||
cd C:\Users\qiang\.codex\skills\oracle-jump-query
|
||
git pull --ff-only origin main
|
||
python scripts/oracle_skill.py capabilities --json
|
||
```
|
||
|
||
The command reads every SQL file under `references/sys-functions/`, replaces `<AGENT_SCHEMA>`, and only outputs SQL for a DBA to execute. It never writes to the customer database. Any future SYS function must be added to that directory so this command includes it automatically.
|