oracle-jump-query-public/references/legacy-skill-v1.5.8.md

---
name: oracle-jump-query
description: Oracle 跳板查询技能。通过中转服务查询远程 Oracle 数据库的元数据（存储过程源码、依赖、表结构、触发器、直接查表），连接数据库为只读，禁止任何写操作。当用户需要分析 Oracle 存储过程、查找依赖表、查询表结构、查看业务逻辑时触发。
---

# Oracle 跳板查询

> **版本：v1.5.8** · [更新日志](./CHANGELOG.md)

## 概述

通过中转服务（Transit Server）查询远程 Oracle 数据库服务器的存储过程元数据，无需开放数据库端口。

## 架构

```
AI Skill → HTTP → Transit Server (:6357) → WebSocket → Agent → Oracle
```

## 前置条件

1. 中转服务已部署并运行（IP: 47.97.171.89, Port: 6357）
2. Agent 已部署到数据库服务器并连接中转服务
3. 本地已安装 Python 依赖：`pip install requests`

## 配置

配置文件位于技能目录下：`D:\work\恒诺\长期支持\跳板查询\demo\ai-skill\config.json`

```json
{
    "transit_url": "http://47.97.171.89:6357",
    "server_id": "server-001",
    "access_token": "",
    "expires_at": ""
}
```

使用查询命令前先登录中转机：

```bash
python oracle_skill.py login <secretKey> [clientCode]
```

登录成功后只保存中转机签发的 `access_token` 和过期时间，不保存 BOS `secretKey`。`clientCode` 是客户服务器编号，非必填；不传时中转机会默认选择 BOS 返回的第一个可用 client。

同一个 `secretKey` 同时只允许一个设备在线。另一台设备重新登录后，当前设备的 token 会立即失效，需要重新执行 `login <secretKey> [clientCode]`。

## 调用方式

使用 `scripts/oracle_skill.py` 脚本：

```bash
python scripts/oracle_skill.py <command> [args]
```

### 可用命令

| 命令 | 说明 | 示例 |
|------|------|------|
| `analyze <schema> <proc>` | 完整分析存储过程 | `python oracle_skill.py analyze BOS M_RETAIL_SUBMIT` |
| `list <schema>` | 列出 schema 下所有存储过程 | `python oracle_skill.py list BOS` |
| `source <schema> <proc>` | 获取存储过程源码 | `python oracle_skill.py source BOS M_RETAIL_SUBMIT` |
| `deps <schema> <proc>` | 获取依赖（表/存储过程） | `python oracle_skill.py deps BOS M_RETAIL_SUBMIT` |
| `tables <schema> <proc>` | 获取相关表结构 | `python oracle_skill.py tables BOS M_RETAIL_SUBMIT` |
| `describe <schema> <table>` | 查询表结构（列、索引、行数） | `python oracle_skill.py describe bosnds3 xcx_so` |
| `discover [schema] [domain]` | 发现核心业务域（NL2SQL前置） | `python oracle_skill.py discover BOSNDS3 RETAIL` |
| `nl2sql [schema] [domain]` | 生成 NL2SQL Schema 字典 | `python oracle_skill.py nl2sql BOSNDS3 RETAIL` |
| `query <SQL>` | 执行 SELECT 查询，生产表必须带过滤条件和行数限制 | `python oracle_skill.py query "SELECT * FROM M_RETAIL WHERE BILLDATE=20260501 AND ROWNUM<=20"` |
| `perm <userId> <tableId> [col]` | 查询用户数据权限 | `python oracle_skill.py perm 940 12983` |
| `qperm <userId> <tableId> <SQL>` | 带权限过滤的查询 | `python oracle_skill.py qperm 940 12983 "SELECT * FROM M_OTHER_INOUT"` |
| `login <secretKey> [clientCode]` | 登录中转机 + 选择客户服务器，clientCode 非必填 | `python oracle_skill.py login mykey HENLO` |
| `logout` | 登出中转机并清除本地 token | `python oracle_skill.py logout` |
| `status` | 查看中转机登录状态 + 当前 client | `python oracle_skill.py status` |
| `switch <clientCode>` | 切换 client | `python oracle_skill.py switch OTHER_CLIENT` |
| `clients` | 获取当前用户可访问 client 及在线状态 | `python oracle_skill.py clients` |
| `servers` | 列出在线 Agent | `python oracle_skill.py servers` |
| `health` | 检查中转服务状态 | `python oracle_skill.py health` |
| `tablespace / tablespaces` | 查询表空间使用情况 | `python oracle_skill.py tablespace` |

### 交互模式

不传参数直接运行，进入交互模式：

```bash
python scripts/oracle_skill.py
```

## 生产查询限制

直接查询业务表时，必须带明确过滤条件，不要直接查询整表。生产环境数据量很大，`SELECT * FROM <table>` 这类无条件查询可能返回大量数据、拖慢 Agent 或影响数据库。

生成或执行 `query` / `qperm` SQL 时遵守：

- 必须有 `WHERE` 条件，优先使用日期、单号、门店、客户、状态、主键等业务过滤条件。
- 必须加行数限制，例如 `ROWNUM <= 20`；需要分页时分批查询。
- 不要为了“先看看数据”执行无条件整表查询。
- 统计查询也要限定业务范围，例如日期区间、单据状态、门店范围。
- 如果用户没有给出过滤条件，先追问条件，或先用 `describe` / `AD_COLUMN` / `AD_TABLE` 查询结构和字段含义。

推荐示例：

```sql
SELECT *
FROM M_RETAIL
WHERE BILLDATE = 20260501
  AND STATUS = '2'
  AND ROWNUM <= 20
```

避免示例：

```sql
SELECT * FROM M_RETAIL
```

## 常用业务对象说明

当用户使用商品、款号、条码、SKU、库存等业务词时，默认按以下对象理解：

- “商品”“款号”通常指 `M_PRODUCT` 表。
- “条码”“SKU”通常指 `M_PRODUCT_ALIAS` 表。
- 查询条码/SKU 时，首查 `M_PRODUCT_ALIAS.NO` 字段。
- 款号和条码是一对多关系：一个 `M_PRODUCT` 可以对应多条 `M_PRODUCT_ALIAS`。
- 如果涉及库存查询，通常查询 `V_FA_STORAGE` 视图。
- `V_FA_STORAGE` 数据量很大，必须同时带店仓条件和款号/条码条件，不允许只查整张库存视图。

库存查询过滤规则：

- 店仓条件应优先使用门店、仓库、店仓 ID 或店仓编码等字段，先通过 `describe` 或 `AD_COLUMN` 确认实际字段名。
- 款号条件走 `M_PRODUCT`；条码/SKU 条件走 `M_PRODUCT_ALIAS`。
- 通过条码查库存时，应先用 `M_PRODUCT_ALIAS.NO` 找到对应商品，再关联或过滤 `V_FA_STORAGE`。
- 必须加 `ROWNUM` 或分页限制；如果用户没有提供店仓或款号/条码，先追问，不要直接查询库存视图。

示例思路：

```sql
-- 伪示例：实际字段名需先 describe / AD_COLUMN 确认
SELECT *
FROM V_FA_STORAGE s
WHERE s.C_STORE_ID = :store_id
  AND s.M_PRODUCT_ID = :product_id
  AND ROWNUM <= 20
```

## 分析报告内容

`analyze` 命令返回完整分析报告，包含：
- **源码**：完整 PL/SQL 代码
- **依赖**：涉及的表、视图、嵌套存储过程/函数
- **表结构**：相关表的列信息（列名、类型、长度、可空）
- **触发器**：相关表上的触发器列表

## 直接 HTTP 调用

不通过脚本，直接调用中转服务 API：

### 分析存储过程

```bash
curl -X POST http://47.97.171.89:6357/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "server-001",
    "action": "analyze_procedure",
    "schema": "BOS",
    "name": "M_RETAIL_SUBMIT",
    "timeout": 60
  }'
```

### 查询表结构

```bash
curl -X POST http://47.97.171.89:6357/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "server-001",
    "action": "describe_table",
    "schema": "bosnds3",
    "name": "xcx_so",
    "timeout": 30
  }'
```

### action 类型

| action | 说明 |
|--------|------|
| `analyze_procedure` | 完整分析 |
| `list_procedures` | 列出存储过程 |
| `get_source` | 源码 |
| `get_dependencies` | 依赖 |
| `get_tables` | 表结构（通过存储过程依赖） |
| `describe_table` | 查询表结构（列、索引、行数、注释） |
| `execute_query` | 执行 SELECT 查询（只读）—— 表空间查询也复用此 action |
| `schema_discovery` | 发现核心业务域 |
| `generate_nl2sql_schema` | 生成 NL2SQL Schema 字典 |

## 数据字典（AD_TABLE / AD_COLUMN / AD_REFBYTABLE）

### 通用查询规则

处理 BOS 业务单据（如零售单、采购单、调拨单、销售单等）时，必须遵循以下查询路径：

**1. 术语 → 表名（AD_TABLE）**

遇到不懂的业务术语（如"零售单提交"、"采购入库"），先查 AD_TABLE：

```sql
SELECT ID, NAME, TABLENAME, DESCRIPTION, PROC_SUBMIT
FROM AD_TABLE
WHERE NAME LIKE '%关键词%' OR DESCRIPTION LIKE '%关键词%'
```

- `NAME`：表名（英文，如 M_RETAIL）
- `DESCRIPTION`：业务说明（中文，如"零售单"）
- `PROC_SUBMIT`：该单据的提交存储过程名称（非空即代表该表有提交逻辑）

**2. 字段含义（AD_COLUMN）**

不理解某个字段的业务含义时，查 AD_COLUMN：

```sql
SELECT DBNAME, NAME, DESCRIPTION, COLTYPE
FROM AD_COLUMN
WHERE AD_TABLE_ID = <AD_TABLE.ID>
ORDER BY ORDERNO
```

**3. 主表 → 明细表（AD_REFBYTABLE）**

对于单据类表，其明细表、付款表等子表必须通过 AD_REFBYTABLE 查找，不要靠猜测命名规则：

```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 = '<AD_TABLE.NAME>'
```

- `ASSOCTYPE`："n"=一对多明细，"1"=强关联/嵌入
- 得到明细表名后，再通过 AD_COLUMN 查看各明细表的字段含义

### 核心表说明

| 表 | 说明 |
|------|------|
| `AD_TABLE` | 所有业务表的元数据注册表，每条记录对应一张业务表 |
| `AD_COLUMN` | 所有业务字段的元数据注册表，含字段名(DBNAME)、显示名(NAME)、描述(DESCRIPTION)、类型(COLTYPE)等 |
| `AD_REFBYTABLE` | **主表与明细表的关联关系**，记录主表→明细表的外键引用 |

### AD_REFBYTABLE 关联字段

| 字段 | 说明 |
|------|------|
| `AD_TABLE_ID` | 主表ID → 关联 AD_TABLE.ID |
| `AD_REFBY_TABLE_ID` | 明细表ID → 关联 AD_TABLE.ID |
| `AD_REFBY_COLUMN_ID` | 明细表中的外键列ID → 关联 AD_COLUMN.ID，通过 AD_COLUMN.DBNAME 获取实际列名 |
| `ASSOCTYPE` | 关联类型（"1"=强关联/嵌入, "n"=一对多明细） |

### 查询主表→明细表关系的 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'
```

### 示例：M_RETAIL 的明细表

| 主表 | 明细表 | 外键列 | 关联类型 |
|------|--------|--------|----------|
| M_RETAIL | M_RETAILITEM | M_RETAIL_ID | n |
| M_RETAIL | M_RETAILPAYITEM | M_RETAIL_ID | n |
| M_RETAIL | M_RETAIL_PRO_ITEM | M_RETAIL_ID | n |
| M_RETAIL | M_RETAIL_RATEITEM | M_RETAIL_ID | n |
| M_RETAIL | M_RETAIL_DISITEM | M_RETAIL_ID | n |
| M_RETAIL | M_RETAIL_VOUCHERSITEM | M_RETAIL_ID | n |
| M_RETAIL | M_RETAIL_BATCHITEM | M_RETAIL_ID | n |

### 查询字段描述的 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
```

### BOS 系统地图分析（AD_TABLE_TEXT 经验）

`BOSNDS3.AD_TABLE_TEXT` 是 BOS 内部的表配置导出脚本生成器。分析该过程可以反推出 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_SUBSYSTEM`：子系统。
- `AD_TABLECATEGORY`：表类别 / 模块分类。
- `AD_ACCORDION`：折叠菜单 / 菜单分组。
- `AD_TABLE`：业务表注册表，含 `DESCRIPTION`、`PROC_SUBMIT`、`DIRECTORY_ID`、`AD_TABLECATEGORY_ID`、`AD_ACCORDION_ID` 等。
- `AD_COLUMN`：字段元数据，含字段名、显示名、业务描述、控件类型、引用列、默认值、限定值组等。
- `AD_REFBYTABLE`：主表到明细表、子表的关系。
- `AD_ACTION`：表动作、按钮、URL、存储过程脚本入口。
- `DIRECTORY`：数据权限目录挂载点。
- `AD_CXTAB` 相关表：公开查询 / 报表模板及其参数、维度、指标。

常用系统地图 SQL：

```sql
SELECT ss.NAME AS SUBSYSTEM,
       tc.NAME AS TABLE_CATEGORY,
       ac.NAME AS ACCORDION,
       t.ID AS AD_TABLE_ID,
       t.NAME AS TABLE_NAME,
       t.DESCRIPTION,
       t.PROC_SUBMIT,
       d.NAME AS DIRECTORY_NAME
FROM AD_TABLE t
LEFT JOIN AD_TABLECATEGORY tc ON tc.ID = t.AD_TABLECATEGORY_ID
LEFT JOIN AD_SUBSYSTEM ss ON ss.ID = tc.AD_SUBSYSTEM_ID
LEFT JOIN AD_ACCORDION ac ON ac.ID = t.AD_ACCORDION_ID
LEFT JOIN DIRECTORY d ON d.ID = t.DIRECTORY_ID
WHERE t.NAME LIKE '%关键词%' OR t.DESCRIPTION LIKE '%关键词%'
ORDER BY ss.NAME, tc.ORDERNO, ac.ORDERNO, t.ORDERNO, t.NAME
```

分析单个业务表时，至少同时检查：

- `AD_TABLE`：表归属、提交过程、权限目录。
- `AD_COLUMN`：字段业务含义和值域。
- `AD_REFBYTABLE`：明细表和外键列。
- `AD_ACTION`：按钮和动作脚本。
- `ALL_TRIGGERS` / `USER_OBJECTS`：触发器、同名前缀过程或函数。

注意：这套元数据能还原 BOS 业务结构，不等于完整物理数据库模型。复杂过程内部逻辑、动态 SQL、触发器副作用和前端特殊页面仍需要结合源码继续分析。

## 表空间查询

查询 Oracle 表空间使用情况。

### 自动降级策略

脚本按优先级尝试**5 种方式**，无需人工切换：

| 优先级 | 方式 | 数据来源 | 条件 | 输出字段 |
|:---:|------|----------|------|----------|
| 1️⃣ | 直接 DBA 查询 | `DBA_DATA_FILES` + `DBA_FREE_SPACE` | 用户有 `SELECT_CATALOG_ROLE` | 全部 8 个字段 |
| 2️⃣ | DBA 专用函数 | `sys.get_tablespace_usage()`（返回 SYS_REFCURSOR） | DBA 已执行 CREATE FUNCTION + GRANT | 全部 5 个字段（自动解析） |
| 3️⃣ | DBA 授权 VIEW（无前缀） | `HENLO_TS_USAGE` 视图 | DBA 已执行授权 SQL | 全部 8 个字段 |
| 4️⃣ | DBA 授权 VIEW（sys.前缀） | `SYS.HENLO_TS_USAGE` 视图 | DBA 以 SYS 身份创建时自动处理 | 全部 8 个字段 |
| 5️⃣ | 用户视图 | `USER_FREE_SPACE` | 始终可用 | 仅表空间名称 + 剩余MB |

> **经验**：DBA 以 SYS 身份登录创建的 VIEW 会归属到 `SYS` schema，需用 `sys.HENLO_TS_USAGE` 查询。脚本会自动先试无前缀、再试 `sys.` 前缀。

### 给 DBA 的授权 SQL

如果当前用户缺少系统视图权限，脚本会**自动输出**以下 SQL。将其交给 DBA 在 Oracle 中执行一次：

```sql
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;
```

> **原理**：Oracle 视图默认使用**定义者权限**（`DEFINER`），以视图创建者的 DBA 身份执行，普通用户仅需视图的 `SELECT` 权限。这比授予 `SELECT_CATALOG_ROLE` 更安全——只暴露这一个视图的数据。

DBA 执行授权后，再次运行 `tablespace` 命令即可自动使用完整查询。

### 输出字段

| 字段 | 说明 |
|------|------|
| 表空间名称 | 表空间名称 |
| 总大小MB | 当前所有数据文件总大小 |
| 已用MB | 已使用的空间 |
| 剩余MB | 剩余可用空间 |
| 使用率% | 已用 / 总大小 × 100% |
| 自动拓展 | YES=自动扩展，NO=不自动扩展 |
| 最大可拓展MB | 开启自动扩展后的最大可达大小 |
| 最大使用率% | 已用 / 最大可拓展 × 100%（参考阈值 5%） |

### 触发语法

用户可以说：
- 「帮我查询下表空间」
- 「查看表空间使用情况」
- 「表空间是否够用」

```bash
python oracle_skill.py tablespace
# 或
python oracle_skill.py tablespaces
```

### 阈值规则

| 使用率 | 状态 | 建议 |
|--------|------|------|
| < 80% | ✅ 正常 | 无需处理 |
| 80~95% | 🔶 关注 | 评估未来增长，制定扩容计划 |
| ≥ 95% | ⚠️ 紧急 | 尽快扩容或清理空间！ |

> **智能告警规则**：脚本逐行解析表空间数据，自动判断衡量指标。
> 若表空间**已开启自动扩展**（`自动拓展=YES`），按 **最大使用率%** 判断（已用/最大可拓展）；
> 若**未开启**（`NO`），按当前 **使用率%** 判断（已用/当前总大小）。
> 
> 这让告警更准确。例如：SYSTEM 使用率 99.4% 但最大使用率仅 3.7%，说明只是当前数据文件写满了，自动扩展后即释放空间，并非真正的存储瓶颈。

### 使用场景

1. **查主表的明细表**：通过 AD_REFBYTABLE 找到主表关联的所有明细表及外键列
2. **查字段含义**：通过 AD_COLUMN 的 DESCRIPTION 字段了解业务含义
3. **构建 JOIN 查询**：根据外键列名自动拼接主表→明细表的 JOIN 条件
4. **理解业务模型**：通过表间关系理解业务单据结构（如零售单→零售明细→支付明细）

### 4. 统计数据场景的过滤条件

在 BOS 系统中，进行统计数据查询时，必须遵循以下业务规则：

**业务单据通用过滤条件**：
- `ISACTIVE = 'Y'`：单据有效（Y=可用，N=已删除/作废）
- `STATUS = '2'`：单据已提交（1=未提交，2=已提交，3=审批中）

**查询模板**：
```sql
-- 查询有效且已提交的业务单据
SELECT * FROM <业务表名>
WHERE ISACTIVE = 'Y' AND STATUS = '2'
-- 其他业务条件...
```

**字段含义**：
| 字段 | 值 | 业务含义 |
|------|-----|----------|
| `ISACTIVE` | 'Y' | 单据有效，可参与统计 |
| `ISACTIVE` | 'N' | 单据已删除/作废，应排除 |
| `STATUS` | '1' | 草稿/未提交，应排除 |
| `STATUS` | '2' | **已提交**，可参与统计 |
| `STATUS` | '3' | 审批中，通常排除（除非统计审批流程） |

**应用场景**：
- 统计销售额、销售量 → 必须用 `ISACTIVE='Y' AND STATUS='2'`
- 查询历史订单 → 必须用 `ISACTIVE='Y' AND STATUS='2'`
- 分析业务趋势 → 必须用 `ISACTIVE='Y' AND STATUS='2'`

**注意事项**：
1. 明细表（如 M_RETAILITEM）通常继承主表状态，但有时也有自己的状态字段
2. 部分表可能使用 `ISSTOP` 代替 `ISACTIVE`，逻辑相反（'Y'=停用）
3. 查询前应先通过 AD_COLUMN 确认字段名和值域

## 数据权限系统

### GET_USERSPERMSQL 函数

数据库内置 `get_userspermsql` 函数，用于获取用户的数据权限过滤条件。

**函数签名：**
```sql
FUNCTION get_userspermsql(
    p_users_id NUMBER,   -- 用户ID (USERS.ID)
    p_tableid  NUMBER,   -- 表ID (AD_TABLE.ID)
    p_col      VARCHAR2  -- 字段名 (AD_COLUMN.DBNAME)，可为NULL
) RETURN CLOB           -- 返回权限过滤SQL
```

**返回值：**
- 空字符串：全权限（无需过滤）
- SQL条件：如 `C_STORE_ID IN (...)`，需拼接到 WHERE 子句

**权限模型：**
```
用户 → GROUPUSER → 用户组 → GROUPPERM → 安全目录 → 权限SQL
                              ↓
                          AD_TABLE.DIRECTORY_ID
```

### 使用权限过滤查询

**1. 查询用户权限：**
```bash
python oracle_skill.py perm 940 12983
```
返回：
```json
{
  "user_id": "940",
  "table_id": "12983",
  "perm_sql": "M_OTHER_INOUT.C_STORE_ID IN(...)",
  "has_restriction": true
}
```

**2. 带权限过滤的查询：**
```bash
python oracle_skill.py qperm 940 12983 "SELECT * FROM M_OTHER_INOUT WHERE BILLDATE=20260501"
```
自动拼接权限条件后执行：
```sql
SELECT * FROM M_OTHER_INOUT 
WHERE BILLDATE=20260501 
AND M_OTHER_INOUT.C_STORE_ID IN(...)
```

### 常用表ID参考

| 表名 | AD_TABLE.ID | 说明 |
|------|-------------|------|
| M_RETAIL | 12964 | 零售单主表 |
| M_RETAILITEM | 12965 | 零售明细 |
| M_OTHER_INOUT | 12983 | 其他出入库 |
| C_STORE_CHKDAY | 18182 | 门店盘点日 |

## 故障排查

| 问题 | 排查 |
|------|------|
| `无法连接中转服务` | 检查 transit_url 地址和端口 |
| `agent not found` | 确认 Agent 已启动并连接成功 |
| `请求超时` | Agent 可能卡住，增大 timeout 参数 |
| Oracle 连接失败 | 检查 Agent 的 config.json 中 Oracle 配置 |

## Oracle 日常运维监控触发

当用户说“给我 HENLO 的 Oracle 运维报告”、“生成 HENLO 数据库日报”、“做一次 HENLO Oracle 巡检”这类请求时，调用：

```bash
python scripts/oracle_skill.py ops_report HENLO
```

当用户询问单项运维状态时，调用 `ops <item> [clientCode]`：

```bash
python scripts/oracle_skill.py ops blocking_locks HENLO
python scripts/oracle_skill.py ops active_slow_sql HENLO
python scripts/oracle_skill.py ops ora_errors HENLO
```

常用自然语言映射：

| 用户意图 | 命令 |
|---|---|
| 有没有锁阻塞 | `ops blocking_locks <clientCode>` |
| 当前有没有慢 SQL | `ops active_slow_sql <clientCode>` |
| 最近 ORA 错误 | `ops ora_errors <clientCode>` |
| UNDO 风险 | `ops undo <clientCode>` |
| IO 等待 | `ops io_waits <clientCode>` |
| 内存使用 | `ops memory <clientCode>` |
| 失效对象 | `ops invalid_objects <clientCode>` |

涉及 SYS/DBA 权限视图时，Agent 会优先调用 `SYS.HENLO_ORA_MONITOR`；如果不可用，再尝试当前登录账号下的 `HENLO_ORA_MONITOR`。如果两个函数都不存在或未授权，输出两种安装方案：有 SYS 账号时安装到 SYS 并授权；没有 SYS 账号但当前登录账号已有系统视图查询权限时，安装到当前账号后重试。

## 服务器体检报告触发

当用户说“给我 HENLO 的服务器体检报告”、“查询 HENLO 的服务器状态”、“看看 HENLO 的备份情况”这类请求时，调用：

```bash
python scripts/oracle_skill.py checkup HENLO
```

如果用户没有指定客户服务器编号，则调用：

```bash
python scripts/oracle_skill.py checkup
```

输出字段固定为 `clientCode`、`info_cpu_rate`、`info_memory_rate`、`info_memory`、`bak_path`、`bak_lastdate`、`computer`。`clientCode` 是客户服务器编号，非必填；不传时使用当前登录 client。

## 新增业务记录 SQL 生成规则

当用户要求分析或生成新增业务表记录的 SQL 示例时，仍然保持只读安全边界：skill 可以生成 SQL 和说明，但不能直接通过查询通道执行 INSERT、UPDATE、DELETE、MERGE、DDL 等写操作。

生成新增记录 SQL 时遵守以下默认规则：

- 主表或子表新增记录的主键 `ID` 使用 `get_sequences('<表名称>')` 取值。
- 如果目标表存在 `DOCNO` 字段，先查询 `AD_COLUMN` 中该字段是否配置 `SEQUENCENAME` 单据编号生成器。
- 如果 `DOCNO` 对应的 `SEQUENCENAME` 有值，则单据编号使用 `Get_SequenceNo('<SEQUENCENAME>', 37)` 取值。
- 如果目标表存在 `AD_CLIENT_ID` 字段，默认值使用 `37`。
- 如果目标表存在 `AD_ORG_ID` 字段，默认值使用 `27`。
- 子表的 `AD_CLIENT_ID` 和 `AD_ORG_ID` 默认取父表记录中对应字段值，不单独写固定值。
- 新增业务表单时，如果目标表存在 `STATUS`、`STATUSERID`、`STATUSTIME` 字段，通常只给 `STATUS` 赋默认值 `'1'`，不对 `STATUSERID`、`STATUSTIME` 赋值。
- `STATUS='1'` 表示草稿/未提交；提交人、提交时间等字段由提交动作或提交存储过程处理。
- 如果用户明确提到“提交”，通常不是直接把 `STATUS` 改成 `'2'`，而是应先查询 `AD_TABLE.PROC_SUBMIT`，按该表配置的提交存储过程理解提交逻辑。

查询 `DOCNO` 编号生成器示例：

```sql
SELECT SEQUENCENAME
FROM AD_COLUMN
WHERE AD_TABLE_ID = (SELECT ID FROM AD_TABLE WHERE NAME = '<表名称>')
  AND UPPER(DBNAME) = 'DOCNO'
```

## 字段值域映射规则（AD_COLUMN / AD_LIMITVALUE）

当用户要求解释字段含义、生成查询条件、分析业务类型，或生成新增业务记录 SQL 示例时，如果目标字段在 `AD_COLUMN` 中的 `OBTAINMANNER` 值为 `select`，必须继续通过 `AD_LIMITVALUE_GROUP_ID` 查询 `AD_LIMITVALUE`，拿到显示值与数据库实际值的映射关系。

关键规则：

- `AD_COLUMN.OBTAINMANNER = 'select'` 表示该字段是受限值列表。
- `AD_COLUMN.AD_LIMITVALUE_GROUP_ID` 关联 `AD_LIMITVALUE.AD_LIMITVALUE_GROUP_ID`。
- 用户通常说的是显示值，例如“券核销”。
- SQL 查询条件和新增记录 SQL 必须使用数据库实际值，例如 `VOU_USED`。
- 不要把显示值直接写入业务表字段，除非 `AD_LIMITVALUE` 查询结果证明显示值就是实际值。

示例：`XH_ORDER_FTP.BILLTYPE` 字段，当显示值为“券核销”时，对应的数据库实际值是 `VOU_USED`。因此用户说“类型为券核销”时，应生成：

```sql
XH_ORDER_FTP.BILLTYPE = 'VOU_USED'
```

查询字段值域映射模板：

```sql
SELECT c.DBNAME,
       c.NAME,
       c.OBTAINMANNER,
       c.AD_LIMITVALUE_GROUP_ID,
       v.VALUE,
       v.NAME AS DISPLAY_NAME
FROM AD_COLUMN c
LEFT JOIN AD_LIMITVALUE v ON v.AD_LIMITVALUE_GROUP_ID = c.AD_LIMITVALUE_GROUP_ID
WHERE c.AD_TABLE_ID = (SELECT ID FROM AD_TABLE WHERE NAME = '<表名称>')
  AND UPPER(c.DBNAME) = UPPER('<字段名>')
ORDER BY v.ORDERNO, v.ID
```

使用时先查字段：

```sql
SELECT ID, DBNAME, NAME, DESCRIPTION, OBTAINMANNER, AD_LIMITVALUE_GROUP_ID
FROM AD_COLUMN
WHERE AD_TABLE_ID = (SELECT ID FROM AD_TABLE WHERE NAME = 'XH_ORDER_FTP')
  AND UPPER(DBNAME) = 'BILLTYPE'
```

如果 `OBTAINMANNER='select'` 且 `AD_LIMITVALUE_GROUP_ID` 有值，再查：

```sql
SELECT VALUE, NAME AS DISPLAY_NAME
FROM AD_LIMITVALUE
WHERE AD_LIMITVALUE_GROUP_ID = <AD_LIMITVALUE_GROUP_ID>
ORDER BY ORDERNO, ID
```