oracle-jump-query-public/docs/操作示例.md

# 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` 查询确认。
- 品小二中文条件：中文值直接写入 `LIKE` 可能因字符集转换返回 0 行，应改用 Oracle `UNISTR` Unicode 转义；其他 client 可按实际验证结果使用，`UNISTR` 也可作为跨环境复用时的 ASCII-safe 兜底。

## 多对话查询

你可以先说“查未芮”，随后直接说“看商品表结构”“查这个过程”。助手沿用当前对话客户，并在每条命令中自动携带 `--client WEIRUI`；另一个对话查其他客户不会影响本对话。下面未带客户参数的历史示例仍兼容默认客户，助手实际调用时应补上本对话编号。

```powershell
python scripts/oracle_skill.py describe --client WEIRUI --json BOSNDS3 M_PRODUCT
```

常规查询无需先检查状态或切换共享默认客户；可信设备已审批时，失效登录由 CLI 自动恢复。

## 常见操作

### 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 '%' || UNISTR('\96F6\552E') || '%'
   OR DESCRIPTION LIKE '%' || UNISTR('\96F6\552E') || '%';
```

对应命令：

```bash
python scripts/oracle_skill.py query "SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT FROM AD_TABLE WHERE NAME LIKE '%' || UNISTR('\96F6\552E') || '%' OR DESCRIPTION LIKE '%' || UNISTR('\96F6\552E') || '%'"
```

### 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`、日期范围、门店权限等条件。