fix: 修正公开镜像文档文件名

2026-08-27 10:39:33 +08:00
parent dfc6a96e10
commit 2191805bcd
1 changed files with 0 additions and 0 deletions
@@ -0,0 +1,482 @@
+# Oracle Jump Query 操作示例
+
+这份文档用于说明如何向 `Oracle Jump Query` 提问，以及它会调用哪些只读能力完成查询。适合给业务分析、存储过程排查、表结构梳理、权限数据查询等场景使用。
+
+## 基本原则
+
+- 只执行只读操作：支持查询元数据和执行 `SELECT`，禁止 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、`TRUNCATE`、`DROP`、`ALTER` 等写操作或结构变更。
+- 优先给出明确对象：尽量提供 `schema`、表名、存储过程名、用户 ID、`AD_TABLE.ID` 等信息。
+- 业务词先查字典：遇到“零售单”“采购入库”“调拨单”等业务词时，先从 `AD_TABLE`、`AD_COLUMN`、`AD_REFBYTABLE` 确认表和字段。
+- 单据统计加状态条件：统计业务单据时，通常需要过滤 `ISACTIVE = 'Y' AND STATUS = '2'`。
+- 明细表不靠猜：主表到明细表关系应通过 `AD_REFBYTABLE` 查询确认。
+
+## 常见操作
+
+### 1. 检查服务状态
+
+用于确认中转服务和在线 Agent 是否可用。
+
+用户可以这样问：
+
+```text
+检查一下 Oracle Jump Query 服务是否正常，看看有哪些在线 Agent。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py health
+python scripts/oracle_skill.py servers
+```
+
+### 2. 查询存储过程源码
+
+用于查看某个存储过程的完整 PL/SQL 源码。
+
+用户可以这样问：
+
+```text
+帮我看一下 BOS.M_RETAIL_SUBMIT 的源码。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py source BOS M_RETAIL_SUBMIT
+```
+
+### 3. 完整分析存储过程
+
+用于一次性查看源码、依赖对象、相关表结构和触发器。
+
+用户可以这样问：
+
+```text
+完整分析 BOS.M_RETAIL_SUBMIT，包括源码、依赖表、相关表结构和触发器。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py analyze BOS M_RETAIL_SUBMIT
+```
+
+适合排查：
+
+- 提交流程做了哪些校验
+- 存储过程更新了哪些业务表
+- 是否调用了其他过程或函数
+- 哪些触发器可能影响结果
+
+### 4. 查询过程依赖
+
+用于单独查看某个过程依赖的表、视图、函数或其他过程。
+
+用户可以这样问：
+
+```text
+查一下 BOS.M_RETAIL_SUBMIT 依赖了哪些表和过程。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py deps BOS M_RETAIL_SUBMIT
+```
+
+### 5. 查询表结构
+
+用于查询字段、类型、索引、行数、注释等表结构信息。
+
+用户可以这样问：
+
+```text
+查一下 BOSNDS3.XCX_SO 的表结构。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py describe BOSNDS3 XCX_SO
+```
+
+### 6. 根据业务词找表
+
+用于从中文业务名称反查系统中的业务表。
+
+用户可以这样问：
+
+```text
+帮我找“零售单”对应哪张表，以及提交过程是什么。
+```
+
+对应 SQL：
+
+```sql
+SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT
+FROM AD_TABLE
+WHERE NAME LIKE '%零售%'
+   OR DESCRIPTION LIKE '%零售%';
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py query "SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT FROM AD_TABLE WHERE NAME LIKE '%零售%' OR DESCRIPTION LIKE '%零售%'"
+```
+
+### 7. 查询字段业务含义
+
+用于确认字段显示名、业务描述和字段类型。
+
+用户可以这样问：
+
+```text
+查一下 M_RETAILITEM 每个字段的业务含义。
+```
+
+对应 SQL：
+
+```sql
+SELECT DBNAME, NAME, DESCRIPTION, COLTYPE
+FROM AD_COLUMN
+WHERE AD_TABLE_ID = (
+    SELECT ID FROM AD_TABLE WHERE NAME = 'M_RETAILITEM'
+)
+ORDER BY ORDERNO;
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py query "SELECT DBNAME, NAME, DESCRIPTION, COLTYPE FROM AD_COLUMN WHERE AD_TABLE_ID = (SELECT ID FROM AD_TABLE WHERE NAME = 'M_RETAILITEM') ORDER BY ORDERNO"
+```
+
+### 8. 查询主表和明细表关系
+
+用于确认主表有哪些明细表，以及明细表通过哪个字段关联主表。
+
+用户可以这样问：
+
+```text
+查一下 M_RETAIL 有哪些明细表，外键字段是什么。
+```
+
+对应 SQL：
+
+```sql
+SELECT t1.NAME AS MAIN_TABLE,
+       t2.NAME AS DETAIL_TABLE,
+       c.DBNAME AS REF_COLUMN,
+       r.ASSOCTYPE
+FROM AD_REFBYTABLE r
+LEFT JOIN AD_TABLE t1 ON r.AD_TABLE_ID = t1.ID
+LEFT JOIN AD_TABLE t2 ON r.AD_REFBY_TABLE_ID = t2.ID
+LEFT JOIN AD_COLUMN c ON r.AD_REFBY_COLUMN_ID = c.ID
+WHERE t1.NAME = 'M_RETAIL';
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py query "SELECT t1.NAME AS MAIN_TABLE, t2.NAME AS DETAIL_TABLE, c.DBNAME AS REF_COLUMN, r.ASSOCTYPE FROM AD_REFBYTABLE r LEFT JOIN AD_TABLE t1 ON r.AD_TABLE_ID = t1.ID LEFT JOIN AD_TABLE t2 ON r.AD_REFBY_TABLE_ID = t2.ID LEFT JOIN AD_COLUMN c ON r.AD_REFBY_COLUMN_ID = c.ID WHERE t1.NAME = 'M_RETAIL'"
+```
+
+### 9. 查询有效已提交单据
+
+用于统计或分析正式业务数据。单据类数据通常要排除草稿、审批中、作废或删除记录。
+
+用户可以这样问：
+
+```text
+查询 2026-05-01 的有效已提交零售单，返回前 10 条。
+```
+
+对应 SQL：
+
+```sql
+SELECT *
+FROM M_RETAIL
+WHERE ISACTIVE = 'Y'
+  AND STATUS = '2'
+  AND BILLDATE = 20260501
+  AND ROWNUM <= 10;
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py query "SELECT * FROM M_RETAIL WHERE ISACTIVE = 'Y' AND STATUS = '2' AND BILLDATE = 20260501 AND ROWNUM <= 10"
+```
+
+### 10. 查询用户数据权限
+
+用于查看某个用户对某张业务表的数据范围。
+
+用户可以这样问：
+
+```text
+查一下用户 940 对 M_OTHER_INOUT 的数据权限，表 ID 是 12983。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py perm 940 12983
+```
+
+返回结果通常包含：
+
+- `perm_sql`：权限过滤条件
+- `has_restriction`：是否存在权限限制
+- 空权限条件：通常表示全权限
+
+### 11. 执行带权限过滤的查询
+
+用于按用户权限自动拼接过滤条件后查询数据。
+
+用户可以这样问：
+
+```text
+用用户 940 的权限查询 M_OTHER_INOUT，表 ID 是 12983，只看 2026-05-01 的数据。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py qperm 940 12983 "SELECT * FROM M_OTHER_INOUT WHERE BILLDATE = 20260501"
+```
+
+系统会自动把 `get_userspermsql` 返回的权限条件追加到查询中。
+
+### 12. 查询表空间使用情况
+
+用于查看数据库表空间的整体使用状况，包括总大小、已用、剩余、使用率、是否自动拓展等信息。
+
+#### 自动降级策略
+
+脚本按优先级自动尝试 **5 种方式**，无需手动切换：
+
+| 优先级 | 方式 | 条件 |
+|:---:|------|------|
+| 1️⃣ | 直查 `DBA_DATA_FILES` + `DBA_FREE_SPACE` | 用户有 `SELECT_CATALOG_ROLE` |
+| 2️⃣ | DBA 专用函数 `sys.get_tablespace_usage()` | DBA 已执行 CREATE FUNCTION |
+| 3️⃣ | 查询 DBA 授权 VIEW `HENLO_TS_USAGE` | DBA 已执行授权 SQL |
+| 4️⃣ | 查询 `SYS.HENLO_TS_USAGE`（带 sys.前缀） | DBA 以 SYS 身份创建的视图 |
+| 5️⃣ | 查 `USER_FREE_SPACE` | 始终可用（仅剩余空间） |
+
+> **经验**：DBA 以 SYS 身份登录创建的 VIEW 归属到 `SYS` schema，需用 `sys.` 前缀才能查到。脚本会自动先试无前缀，再试 `sys.` 前缀。
+
+#### 无权限时的处理流程
+
+当用户无 DBA 系统视图权限时，脚本会自动输出以下内容：
+
+1. 尝试 DBA 专用函数（如果有）
+2. 尝试 DBA 授权 VIEW（无前缀 → sys.前缀）
+3. 如果前两步都不存在，输出给 DBA 的授权 SQL
+4. 回退到 `USER_FREE_SPACE` 查询，显示各表空间的剩余空间
+
+#### HENLO 环境实际输出（授权前）
+
+```
+📊 表空间使用情况（用户视图 -- 无DBA权限，仅显示名称和剩余空间）：
+| 表空间名称 | 剩余MB |
+| --- | --- |
+| BOSNDS3 | 518.81 |
+| BOSNDS3_IDX | 17.56 |
+| RETAILNDS3 | 9.31 |
+| RETAILNDS3_IDX | 19 |
+| SYSAUX | 329.94 |
+| SYSTEM | 7.19 |
+| ULOG | 39 |
+| UNDOTBS1 | 474.38 |
+| USERS | 2.31 |
+```
+
+#### DBA 授权后的实际完整输出
+
+DBA 以 SYS 执行授权 SQL 后，再次查询自动获得完整信息（脚本自动识别 `SYS.HENLO_TS_USAGE`）：
+
+```
+📊 表空间使用情况一览（通过 DBA 授权 VIEW）：
+| 表空间名称 | 总大小MB | 已用MB | 剩余MB | 使用率% | 自动拓展 | 最大可拓展MB | 最大使用率% |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| SYSTEM | 1230 | 1222.8 | 7.2 | 99.4 | YES | 32768 | 3.7 |
+| SYSAUX | 6620 | 6290.1 | 329.9 | 95 | YES | 32768 | 19.2 |
+| UNDOTBS1 | 505 | 30.6 | 474.4 | 6.1 | YES | 32768 | 0.1 |
+| BOSNDS3_IDX | 20 | 2.4 | 17.6 | 12.2 | YES | 32768 | 0 |
+| ULOG | 40 | 1 | 39 | 2.5 | YES | 32768 | 0 |
+| RETAILNDS3_IDX | 20 | 1 | 19 | 5 | YES | 32768 | 0 |
+| USERS | 5 | 2.7 | 2.3 | 53.8 | YES | 32768 | 0 |
+| BOSNDS3 | 10690 | 10171.2 | 518.8 | 95.1 | YES | 32768 | 31 |
+| RETAILNDS3 | 110 | 100.7 | 9.3 | 91.5 | YES | 32768 | 0.3 |
+
+**共 9 行**
+```
+
+⚠️ 脚本自动检测到 3 个表空间使用率 ≥ 95% 并输出告警。
+
+#### 字段解释
+
+| 字段 | 说明 |
+|------|------|
+| 表空间名称 | Oracle 表空间名称 |
+| 总大小MB | 当前数据文件总大小（MB） |
+| 已用MB | 已分配使用的空间（MB） |
+| 剩余MB | 剩余可用空间（MB） |
+| 使用率% | （已用 / 总大小）× 100% |
+| 自动拓展 | YES=数据文件自动扩展，NO=固定大小 |
+| 最大可拓展MB | 自动扩展后能达到的最大值（MB）；不自动扩展时=当前大小 |
+| 最大使用率% | （已用 / 最大可拓展）× 100%，反映最终可用的百分比 |
+
+#### 阈值参考
+
+| 使用率 | 状态 | 建议 |
+|--------|------|------|
+| < 80% | ✅ 正常 | 无需处理 |
+| 80% ~ 95% | 🔶 关注 | 评估未来增长，制定扩容计划 |
+| ≥ 95% | ⚠️ 紧急 | 尽快扩容或清理空间！ |
+
+> **智能告警规则**：脚本逐行解析表空间数据，自动判断衡量指标。
+> - `自动拓展=YES`：按 **最大使用率%**（已用/最大可拓展）判断
+> - `自动拓展=NO`：按当前 **使用率%**（已用/当前总大小）判断
+> 
+> 例如 SYSTEM 使用率 99.4% 但最大使用率仅 3.7%，说明只是当前数据文件写满而非存储瓶颈，自动扩展后即可释放。
+
+#### 给 DBA 的授权说明
+
+当无 DBA 权限时，脚本会**自动输出**以下信息，请交给 DBA 执行：
+
+```sql
+-- 以 SYS 身份执行
+CREATE OR REPLACE VIEW SYS.HENLO_TS_USAGE AS
+SELECT
+    df.tablespace_name AS "表空间名称",
+    ROUND(df.total_bytes / 1048576, 1) AS "总大小MB",
+    ROUND((df.total_bytes - NVL(fs.free_bytes, 0)) / 1048576, 1) AS "已用MB",
+    ROUND(NVL(fs.free_bytes, 0) / 1048576, 1) AS "剩余MB",
+    ROUND((df.total_bytes - NVL(fs.free_bytes, 0)) / df.total_bytes * 100, 1) AS "使用率%",
+    df.autoextensible AS "自动拓展",
+    ROUND(df.max_bytes / 1048576, 1) AS "最大可拓展MB",
+    ROUND((df.total_bytes - NVL(fs.free_bytes, 0)) / NULLIF(df.max_bytes, 0) * 100, 1) AS "最大使用率%"
+FROM (
+    SELECT
+        tablespace_name,
+        SUM(bytes) AS total_bytes,
+        SUM(CASE WHEN autoextensible = 'YES' THEN maxbytes ELSE bytes END) AS max_bytes,
+        MAX(CASE WHEN autoextensible = 'YES' THEN 'YES' ELSE 'NO' END) AS autoextensible
+    FROM dba_data_files
+    GROUP BY tablespace_name
+) df
+LEFT JOIN (
+    SELECT tablespace_name, SUM(bytes) AS free_bytes
+    FROM dba_free_space
+    GROUP BY tablespace_name
+) fs ON df.tablespace_name = fs.tablespace_name
+ORDER BY 6 DESC;
+
+GRANT SELECT ON SYS.HENLO_TS_USAGE TO bosnds3;
+```
+
+> **为什么加 `SYS.` 前缀**：DBA 以 SYS 身份执行 `CREATE VIEW` 时，视图创建在 `SYS` schema 下。`GRANT` 也必须指定 `SYS.` 前缀，否则普通用户无法找到。脚本会自动处理带前缀和不带前缀两种情况。
+
+> **原理**：Oracle 视图默认使用定义者权限（`DEFINER`），以创建者的 DBA 身份执行。普通用户仅需 `SELECT` 权限，比直接授予 `SELECT_CATALOG_ROLE` 更安全。
+
+#### 给 AI 的指令
+
+当用户通过 AI 查询表空间时，流程：
+
+1. 自动调用 `python oracle_skill.py tablespace`
+2. 脚本自动尝试 5 层降级
+3. 如果全部权限方案不可用，输出授权 SQL + 回退到剩余空间查询
+4. 将授权 SQL 发送给用户，让其联系 DBA 执行
+5. DBA 执行后，再次查询即可自动使用完整信息
+6. 注意：DBA 以 SYS 执行时，VIEW 会创建在 `SYS` schema 下，GRANT 也需带 `SYS.` 前缀
+
+用户可以这样问：
+
+```text
+帮我查一下数据库表空间使用情况
+查看表空间
+表空间够不够用
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py tablespace
+# 或
+python scripts/oracle_skill.py tablespaces
+```
+
+### 13. 生成 NL2SQL 字典
+
+用于为自然语言转 SQL 准备 schema 字典。
+
+用户可以这样问：
+
+```text
+给 BOSNDS3 的 RETAIL 业务域生成 NL2SQL schema 字典。
+```
+
+对应命令：
+
+```bash
+python scripts/oracle_skill.py nl2sql BOSNDS3 RETAIL
+```
+
+## 典型完整流程
+
+### 流程一：分析一个业务提交流程
+
+用户可以这样问：
+
+```text
+帮我分析零售单提交逻辑，从业务表、提交过程、依赖表到关键校验都梳理出来。
+```
+
+推荐执行顺序：
+
+1. 从 `AD_TABLE` 查询“零售单”对应主表和 `PROC_SUBMIT`。
+2. 使用 `source` 或 `analyze` 查询提交过程源码。
+3. 使用 `deps` 查询依赖对象。
+4. 使用 `describe` 查询关键表结构。
+5. 结合源码解释提交校验、状态变更、库存或财务影响。
+
+### 流程二：构造一条可靠统计 SQL
+
+用户可以这样问：
+
+```text
+我要统计 2026 年 5 月零售销售额，帮我确认主表、明细表、金额字段并生成 SQL。
+```
+
+推荐执行顺序：
+
+1. 查 `AD_TABLE`，确认零售主表。
+2. 查 `AD_REFBYTABLE`，确认零售明细表。
+3. 查 `AD_COLUMN`，确认数量、金额、日期、门店字段。
+4. 生成 SQL 时加入 `ISACTIVE = 'Y' AND STATUS = '2'`。
+5. 如需按用户权限过滤，使用 `qperm`。
+
+示例 SQL：
+
+```sql
+SELECT r.C_STORE_ID,
+       SUM(i.TOT_AMT_ACTUAL) AS SALE_AMOUNT
+FROM M_RETAIL r
+JOIN M_RETAILITEM i ON i.M_RETAIL_ID = r.ID
+WHERE r.ISACTIVE = 'Y'
+  AND r.STATUS = '2'
+  AND r.BILLDATE BETWEEN 20260501 AND 20260531
+GROUP BY r.C_STORE_ID;
+```
+
+## 排查建议
+
+- `agent not found`：先执行 `servers`，确认 Agent 是否在线。
+- 查询超时：缩小查询范围，或对 `analyze` 类命令增加超时时间。
+- 查不到业务表：先扩大 `AD_TABLE` 的关键字范围，再结合 `DESCRIPTION` 判断。
+- 字段含义不明确：优先查 `AD_COLUMN.DESCRIPTION`，不要只凭字段名猜。
+- 统计结果异常：检查是否遗漏 `ISACTIVE`、`STATUS`、日期范围、门店权限等条件。
+