SQLVantage 报表系统使用说明（简体中文）

1. 系统概述
2. 安装部署（Windows / Linux）
3. 配置说明
4. 管理员指南
5. 报表设计指南（核心章节）
6. 普通用户指南
7. 请求执行与输出结果
8. 常见问题 FAQ
9. 附录：数据存储与备份迁移

1.1 这是什么

SQLVantage 是一套 Web 报表系统。系统由「管理员」维护报表定义，「普通用户」通过网页选择报表、填写查询条件、异步获取结果并导出 Excel / HTML / JSON / TEXT。

1.2 技术栈

本系统为纯 Web 架构：浏览器端无须安装任何客户端或插件，使用现代浏览器即可访问；服务器端仅需可执行程序及其配套配置目录即可运行，部署简单。

1.3 核心概念

1.4 用户角色

1.5 目录结构

发布包解压后的主要文件：

SQLVantage/
├── SQLVantage.exe / sqlvantage   # 主程序（Windows / Linux）
├── conf/
│   ├── app.conf        # 系统配置文件（端口/语言/Oracle 等）
│   ├── data.dat        # 业务数据库（用户/职责/报表/请求）
│   ├── license.dat     # 授权文件
│   └── locale/         # 语言包
├── data/               # 运行期生成：<请求ID>.xlsx / <请求ID>.json
├── docs/               # 使用文档（多语言，含 images/）
└── tmp/                # 临时文件（会话、任务）

2.1 环境要求

• 操作系统：Windows 7+ / 64 位 Linux（x86_64）
• 运行方式（推荐）：直接使用发布好的可执行程序（SQLVantage.exe 或 Linux 二进制），无需安装任何运行时环境
• Oracle 数据库：报表执行需要能连通 Oracle（本系统默认连接 Oracle EBS），请提前确认网络与账号
• 磁盘/目录权限：程序运行目录需要可写权限，因为运行期会生成 data/、tmp/ 目录并读写 conf/ 下的文件

2.2 Windows 平台安装

1. 解压缩：将发布包（zip）解压到任意目录，例如 D:\SQLVantage\。解压后确认以下关键文件存在：

   D:\SQLVantage\
   ├── SQLVantage.exe      # 主程序
   ├── conf\app.conf       # 配置文件
   ├── conf\data.dat       # 数据库（随包附带的空库）
   └── conf\locale\        # 语言包
   

2. （可选）修改配置：用记事本打开 conf\app.conf，按 第 3 章 修改监听地址、端口、Oracle 连接等。

3. 启动程序：双击 SQLVantage.exe，或在命令行中运行：

   cd D:\SQLVantage
   SQLVantage.exe
   

   启动成功后控制台会打印版本信息、授权状态，并进入监听状态。

4. 访问系统：浏览器打开 http://127.0.0.1:8080（默认地址，可在 app.conf 中修改）。

5. 防火墙设置：若需局域网/远程访问，请在 Windows 防火墙中放行对应端口（如 8080）：

   netsh advfirewall firewall add rule name="SQLVantage" dir=in action=allow protocol=TCP localport=8080
   

2.3 Linux 平台安装

1. 解压缩：将发布包（tar.gz 或 zip）解压到目标目录，例如 /opt/sqlvantage：

   mkdir -p /opt/sqlvantage
   tar -xzf sqlvantage-linux-amd64.tar.gz -C /opt/sqlvantage
   cd /opt/sqlvantage
   

2. 赋予执行权限：

   chmod +x sqlvantage
   

3. （可选）修改配置：编辑 conf/app.conf（同 Windows）。

4. 前台启动测试：

   ./sqlvantage
   

   看到版本信息和监听日志即启动成功，按 Ctrl+C 停止。

5. 后台运行（推荐用 systemd 或 nohup）：

   方式 A：nohup

   cd /opt/sqlvantage
   nohup ./sqlvantage > sqlvantage.log 2>&1 &
   

   方式 B：systemd（创建 /etc/systemd/system/sqlvantage.service）：

   [Unit]
   Description=SQLVantage Report System
   After=network.target
   
   [Service]
   WorkingDirectory=/opt/sqlvantage
   ExecStart=/opt/sqlvantage/sqlvantage
   Restart=always
   RestartSec=5
   User=sqlvantage
   
   [Install]
   WantedBy=multi-user.target
   

   然后执行：

   systemctl daemon-reload
   systemctl enable sqlvantage
   systemctl start sqlvantage
   systemctl status sqlvantage
   

6. 防火墙 / 安全组：放行端口（如 8080）：

   firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload
   

2.4 从源码编译（可选）

仅对获得源码的用户开放：在源码目录执行 go build 即可编译产出当前平台的可执行文件。正式部署环境建议直接使用官方发布的可执行程序。

2.5 首次启动

首次启动时系统会自动完成以下初始化：

1. 检查数据文件：读取 conf/data.dat（随包附带；若缺失会提示 "conf/data.dat is not found" 并退出，请勿删除该文件）。
2. 自动建表：user、responsibility、report、request 四张表自动创建。
3. 自动创建管理员账号：首次访问 /admin/login 时，若不存在用户 root，系统自动创建：
   • 用户名：root
   • 初始密码：SQLVantage
   • 角色：admin（管理员）
   • 安全提醒：首次登录后请立即修改该密码（管理员可在「用户管理」中修改）。
4. 检查授权文件：若 conf/license.dat 缺失或无效，控制台打印警告，系统仍可运行，但受 4.7 节授权限制 约束。

3.1 配置文件位置

配置文件为 conf/app.conf（INI 格式）。有两种修改方式：

• 方式一（推荐，界面操作）：管理员登录后访问「系统设置」（/admin/setting），填写后保存，系统自动写回 app.conf。
• 方式二（直接编辑文件）：用文本编辑器修改 conf/app.conf 后重启程序。

3.2 参数说明表

3.3 修改后生效

• sessiongcmaxlifetime：保存后立即生效。
• 其余参数（端口、Oracle 等）：修改后需重启程序才生效。

3.4 语言切换

• 系统内置 12 种语言：zh-CN、zh-TW、en-US、ja-JP、ko-KR、fr-FR、de-DE、es-ES、th-TH、vi-VN、ru-RU、pt-PT。
• 切换方式：URL 加 ?lang=zh-CN（如 /?lang=zh-CN），或通过管理后台右上角语言菜单切换；选择后写入 Cookie，有效期 1 年。

4.1 管理员登录

1. 浏览器访问 http://<服务器地址>:<端口>/admin/login。
2. 使用管理员账号登录（首次为 root / SQLVantage）。
3. 登录成功进入管理后台（/admin），左侧菜单包含：报表管理、职责管理、用户管理、请求管理、授权管理、系统设置、仪表盘、关于。

说明：管理员账号必须满足 角色 = admin 且 状态 = active，否则无法登录后台。

4.2 仪表盘与顶部导航

• 顶部导航可快速跳转：仪表盘（/admin）、报表执行（/request，新窗口）、门户首页（/）。
• 右上角可切换语言、退出登录（/admin/logout）。

4.3 用户管理

入口：/admin/user（左侧菜单「用户管理」）。

用户字段说明：

操作：

• 新建：点「新建」按钮 → 填写用户名/邮箱/角色/状态/密码/确认密码 → 提交。
• 编辑：点行内「编辑」→ 可改邮箱、角色、状态；密码留空表示不修改。
• 删除：点行内「删除」。注意：
  • root 账号禁止删除；
  • 名下挂有报表的用户禁止删除（需先删除/转移其报表）。

管理要点：

• 普通用户登录入口为 /login（首页），管理员登录入口为 /admin/login，两者互不相同。
• 给普通用户设 inactive 状态即可禁止其登录，无需删除账号。
• 用户列表自动隐藏 root。

4.4 职责管理

入口：/admin/responsibility（左侧菜单「职责管理」）。

职责字段说明：

操作：

• 新建：点「新建」→ 从下拉选择某用户的职责（数据来自 Oracle EBS 查询接口 /api/user/responsibilities/），选中后自动填充 RespId / RespKey / Name；也可手动填写 → 提交。
• 编辑 / 删除：行内按钮操作。注意：已被报表引用的职责不能删除。

用途：报表必须归属某个职责；普通用户端「报表菜单」按职责分组展示（未归属职责的报表归入「未分类」组）。

4.5 报表管理

入口：/admin/report（左侧菜单「报表管理」）。

报表字段：

报表生命周期（重要）：

Draft（草稿，设计阶段）──▶ Release（已发布，用户可见）
       │                        │
       │                        └──▶ 不可直接删除，需先改为 Draft/Discard
       └──▶ Discard（废弃，用户不可见）

• 只有状态为 Release 的报表才会出现在普通用户端的报表菜单中。
• 已发布（Release）的报表禁止删除，需先在列表中把状态改为 Draft 或 Discard 再删除。
• 列表中的「名称」「描述」「状态」列支持双击单元格直接编辑（自动保存）。

操作：

4.6 请求管理（管理员视角）

入口：/admin/request（左侧菜单「请求管理」）。

管理员可查看所有用户的报表请求（普通用户只能看自己的），支持：

• 按报表名/状态/阶段查看；
• 查看参数、提交人、IP 地址、创建/完成时间；
• 「输出」下拉可直接下载该请求的 Excel / HTML / JSON / TEXT 结果；
• 单选删除或勾选后「批量删除」。

请求状态含义见 第 7 章。

4.7 授权管理（License）

入口：/admin/license（左侧菜单「授权管理」）。

4.7.1 授权文件是什么

授权文件为 conf/license.dat，由供应商签发的一小段文本，包含以下授权信息：

系统在启动与导入时会自动校验授权文件的合法性，任何篡改（修改注册信息或到期日）都会导致授权无效。

4.7.2 购买流程

1. 联系 SQLVantage 供应商/开发商，提供以下信息：
   • 单位/公司名称（company）；
   • 需要授权的服务器注册 ID（reg_id，由供应商分配）；
   • 期望的授权期限。
2. 供应商使用授权生成工具生成授权文件（一段文本），交付给客户。
3. 客户拿到文件后按 4.7.3 导入即可。

4.7.3 导入授权

1. 管理员登录 → 授权管理（/admin/license）。
2. 页面显示当前授权状态（注册 ID / 公司 / 到期日；无效或缺失时显示红色提示）。
3. 点「选择文件」选中收到的授权文件（可任意命名，如 license.dat）→ 点「导入」。
4. 导入成功后系统自动校验并刷新页面，显示有效授权信息。

也可以手动放置：将授权文件内容保存为 conf/license.dat 后重启程序。

4.7.4 无授权 / 授权过期的限制

4.8 系统设置

入口：/admin/setting（左侧菜单「系统设置」），可视化编辑 conf/app.conf：

• 应用设置：监听地址、端口、运行模式、默认语言、最大执行时间；
• 会话设置：Session 过期时间（秒）；
• Oracle 数据库设置：服务器、端口、服务名、用户名、密码（带明文/密文切换按钮）。

保存后部分参数即时生效，端口等参数需重启程序。

4.9 关于

入口：/admin/aboutus，查看系统版本、发布信息等。

这是 SQLVantage 最重要的功能。一个报表由三部分组成：

• SQL：定义查询哪些数据（数据来源 SQL + 列元数据配置）
• FORM：定义用户填写哪些查询条件（参数表单）
• HTML：定义结果如何展示（表格 / 图表 / 指标卡布局）

三者各自有「代码」与「格式 JSON」两份数据，最终保存到报表记录中。

5.1 设计器工作台

5.1.1 进入设计器

1. 管理员登录 → 报表管理（/admin/report）。
2. 找到目标报表，点「代码」按钮（紫色）。
3. 弹出大尺寸设计器窗口（占屏幕约 98%），界面分左右两栏：

┌────────────────────────────────────────────────────────┐
│ [下拉：SQL设计 | FORM设计 | HTML设计]   [保存全部]        │
├───────────────────────────────┬────────────────────────┤
│ 左侧：代码编辑器                │ 右侧：动态设计面板       │
│ （SQL 代码 / FORM 代码 /        │ （随左侧模式切换）      │
│  HTML 代码 共用一个编辑器）     │   · SQL: 列元数据配置表  │
│                               │   · FORM: 参数配置表    │
│                               │   · HTML: 布局块配置表  │
└───────────────────────────────┴────────────────────────┘

5.1.2 三个模式

顶部下拉框切换设计模式，切换时左侧编辑器与右侧面板同步切换：

5.1.3 保存

• 设计过程中：右侧面板的改动会自动写回隐藏域（sql_code/sql_format/form_code/form_format/html_code/html_format）。
• 正式保存：点左上角「保存全部」按钮，一次性把六份数据提交到 /admin/report/code/ 保存到数据库。

记住：编辑完 SQL / FORM / HTML 后务必点「保存全部」，否则关闭窗口会丢失。

5.2 SQL 模块（设计报表数据源）

5.2.1 编写查询 SQL

• SQL 为 Oracle 语法，直接写 SELECT 语句（可包含 FROM/JOIN/WHERE/GROUP BY 等）。

• 查询条件使用 命名参数占位符 :参数名，参数名需与 FORM 模块中定义的 field 一致。例如 FORM 中定义参数 P_OU_ID，SQL 中写：

  SELECT company_name, ou_id, amount
    FROM fnd_ou_tl
   WHERE ou_id = :P_OU_ID
  

• SQL 中所有 SELECT 出来的列名，就是 Excel 导出和 HTML 页面表格的字段标识（建议统一大写，如 COMPANY_NAME）。

5.2.2 列元数据配置表（重点：Excel 导出）

右侧「SQL 列元数据配置」表格，每一行对应 SQL 输出的一列：

操作：点「添加行」新增列 → 双击单元格填写 → 自动生成 JSON 快照（右侧黑色代码预览区），并实时写回 sql_format。

5.2.3 SQL 列配置与 Excel 导出的对应关系

系统后台按以下映射规则生成 Excel（xlsx）文件：

也就是说：SQL 列配置表 = Excel 导出的"列头 + 列类型 + 数字格式 + 对齐"的完整定义。即使不做任何配置，Excel 也能导出（默认文本类型、左对齐、表头用原始列名），但配置后导出的 Excel 更专业。

5.2.4 一个完整的 SQL 设计示例

假设要做一个「部门费用报表」：

1. SQL 代码（编辑器）：

   SELECT DEPT_NAME, MONTH, TOTAL_AMOUNT, RATE
     FROM DEPT_COST_V
    WHERE MONTH = :P_MONTH
    ORDER BY DEPT_NAME
   

2. 列元数据配置：

   field	title	type	precision	format	align
   DEPT_NAME	部门名称	text			left
   MONTH	月份	date		yyyy-mm	center
   TOTAL_AMOUNT	费用总额	number	2	#,##0.00	right
   RATE	费用占比	percent	2	0.00%	right

3. 导出的 Excel 效果：表头为「部门名称 / 月份 / 费用总额 / 费用占比」，金额右对齐、千分位、2 位小数，占比显示为百分比。

5.3 FORM 模块（设计查询参数表单）

5.3.1 参数配置表

右侧「参数配置表」每一行定义一个查询参数：

组件类型表：

5.3.2 参数联动（依赖筛选）

• api_url / query_sql 支持 {变量名} 占位符：用户改变上游参数（如选择组织）时，系统自动把占位符替换为当前表单的实际值，动态请求下游下拉选项。
• 若上游参数未填写，下游下拉框显示「请先完善上方筛选条件」并清空选项，避免脏数据。
• 静态下拉（static_options）与动态下拉（api_url / query_sql）二选一即可。

下拉动态选项的数据格式要求：接口/SQL 返回的每条记录包含 val（值）与 txt（显示文本）两个字段。

5.3.3 实时预览与代码生成

• 表格下方是「实时预览区」：随着参数配置实时渲染出表单（含日期控件、联动下拉等）。
• 底部「表单代码草稿」文本框实时生成完整的 FORM HTML 代码。
• 点「复制并应用」按钮：将草稿代码写入编辑器（FORM 模式），并同步到 form_code / form_format。

也可以不通过右侧面板，直接在左侧编辑器手写 FORM HTML（表单语法），保存时同样生效。

5.3.4 运行时行为

普通用户提交表单后，系统将表单数据作为命名参数与 SQL 绑定执行；同时把参数记录到请求中，供结果页/导出文件回显查询条件。

5.4 HTML 模块（设计结果展示）

5.4.1 布局块配置表

右侧「HTML 视图组件配置」每一行定义一个展示块：

组件说明：

5.4.2 布局预览与代码生成

• 「实时布局预览」区实时展示各块的高仿真骨架（标题 + 块类型 + 宽度）。
• 「Html Code 草稿」实时生成完整 HTML 代码（含 data-component、data-subtotal、data-charttype、data-xfield、data-yfields 等运行期属性）。
• 点「复制并应用」写入编辑器并同步 html_code / html_format。

也可以在左侧编辑器直接手写 HTML 模板片段（支持常用模板语法）。运行期渲染时模板可用的数据对象见 5.4.3。

5.4.3 结果页渲染机制

普通用户下载/查看 HTML 结果时（/request/output?ext=html），系统把报表 HTML 代码与查询结果 JSON、列配置等一起渲染：

页面自动把 data-component="table" 的容器渲染为数据表格、chart 渲染为图表、card 渲染为指标卡。

5.5 报表发布流程（管理员操作建议）

1. 报表管理 → 新建报表（选择职责、填名称、状态选 Draft）
2. 点「代码」进入设计器
3. SQL 设计：写查询 SQL + 配置列元数据（Excel 导出依据）
4. FORM 设计：配置查询参数（与 SQL 参数一一对应）
5. HTML 设计：配置展示布局（表格/图表/指标卡）
6. 点「保存全部」→ 关闭设计器
7. 回到报表列表，把状态改为 Release（发布）
8. 普通用户登录即可在报表菜单中看到该报表并执行

5.6 设计注意事项

• SQL 与 FORM 参数名必须完全一致（SQL 用 :参数名，FORM 用 field）。
• SQL 列名建议大写；列元数据配置表会自动把 field 转大写。
• 报表 SQL 必须能被 Oracle 预编译（db.Prepare），语法错误会导致请求执行失败（状态 Error）。
• 无授权时报表数量上限 3 个，设计前请确认授权状态。
• 保存后可在「请求管理」或普通用户端执行一次请求，验证 SQL 与展示是否正确。

6.1 登录

浏览器访问系统首页（默认 http://<服务器地址>:<端口>/），点「用户登录」卡片进入登录页 /login。登录页提供两种登录方式（标签切换）：

方式一：ERP 验证（Oracle EBS 单点）

1. 切到「ERP 验证」标签。
2. 输入 EBS 用户名（如 APPS），点「验证登录」。
3. 系统通过 Oracle 检查该用户在 EBS 的 icx_sessions 会话是否有效（30 分钟有效窗口），有效则直接进入系统。
4. 特点：无需本地密码；登录身份为用户在 EBS 中的身份。

方式二：本地账号

1. 切到「本地账号」标签。
2. 输入管理员分配的用户名和密码，点「登录」。
3. 特点：账号由管理员在「用户管理」中创建。

注意：账号被管理员设为 inactive（离职）后无法登录。

6.2 门户首页

登录成功后进入门户首页（/），包含：

• 顶部：欢迎语（用户名）、修改密码入口。
• 导航卡片：
  • 新报表请求（进入报表执行页面 /request）；
  • 我的请求（查看历史请求与结果）；
  • 管理员登录、系统设置、授权管理、关于等卡片（普通用户无需使用，点入会跳转管理员登录页）。
• 右上角可切换界面语言。

6.3 新建报表请求

1. 门户首页点「新报表请求」卡片，或直接访问 /request。
2. 在请求列表页点「新建」按钮。
3. 弹出「报表菜单」窗口：报表按职责（模块）分组展示，只显示已发布（Release）的报表；也可在顶部下拉框按名称搜索。
4. 点击某个报表，右侧加载该报表的参数表单。
5. 填写查询条件（日期/下拉/文本等），点「提交」。
6. 提交成功后在请求列表中看到新记录，状态为 Queued（排队中）。

6.4 我的请求列表

入口：/request（顶部也可从门户卡片进入）。

操作：点某行「输出」下拉，选择 Excel / HTML / JSON / TEXT，在新窗口打开或下载对应格式的结果文件。

6.5 修改密码

1. 门户首页顶部点「修改密码」。
2. 填写当前密码、新密码、确认新密码（新密码至少 6 位）。
3. 提交成功即可用新密码登录（仅本地账号登录有效；ERP 验证方式与 EBS 密码无关）。

7.1 执行流程（异步）

用户提交请求
   │
   ▼
写入 request 表（Phase=Pending, Status=Queued）
   │
   ▼
后台轮询协程（每 3 秒）拉取排队任务（每批最多 5 个，并发最多 3 个）
   │
   ▼
乐观锁抢占任务 → Phase=Running, Status=Processing
   │
   ▼
解析参数 → 读取报表 SQL → Oracle 预编译执行
   │
   ├── 失败 → Status=Error（记录错误消息）
   │
   ▼
生成结果文件：data/<请求ID>.xlsx 与 data/<请求ID>.json
   │
   ▼
Phase=Completed, Status=Success

• 超时保护：执行超过 max_execution_time（默认 30 分钟）的任务自动标记为 Terminated。
• 结果文件按请求 ID 保存在 data/ 目录，不会互相覆盖。

7.2 输出格式

7.3 权限控制

• 普通用户只能看到自己提交的请求（按创建人过滤）。
• 管理员在「请求管理」可查看所有用户的请求。
• ERP 登录用户提交时，若表单包含 P_OU_ID / P_ORG_ID 等组织权限参数，系统会校验该值是否在用户 EBS 拥有的 OU/ORG 范围内，越权会被拒绝。

Q1：启动时报 "conf/data.dat is not found"？ 数据库文件缺失。请确认解压完整，conf/data.dat 存在；不要用空文件替代，需使用随发布包提供的数据库文件。

Q2：浏览器打不开页面？ 确认程序已启动；确认 httpaddr/httpport 配置正确（默认 127.0.0.1:8080，本机访问 OK、其他机器访问需改为 0.0.0.0 并放行防火墙端口）。

Q3：登录提示账号或密码错误？

• 本地账号：确认用户名/密码正确、状态为 active。
• 管理员：确认角色为 admin。
• 忘记密码：联系管理员在「用户管理」中重置。

Q4：提交报表请求后状态一直 Error？ 多为 SQL 语法错误或 Oracle 连接问题。查看请求「消息」列的报错信息：Prepare statement failed 表示 SQL 预编译失败；Oracle connection failed 表示数据库连接配置错误（检查 app.conf 的 oracle_* 参数）。

Q5：报表在普通用户菜单中看不到？ 确认报表状态为 Release（只有已发布报表可见）。

Q6：请求长时间 Running？ 执行时间超过 max_execution_time 分钟会被自动终止。可适当调大该参数后重启。

Q7：创建报表提示授权已达上限？ 未导入有效授权文件（或已过期），未授权时最多 3 个报表。请按 4.7 节 导入授权。

Q8：Excel 导出列头是英文列名？ SQL 列元数据配置中未填 title，或未匹配到 SQL 输出列名。请在「SQL 设计」的列配置表中把 field 填成与 SQL 输出列一致、并填写 title。

Q9：Oracle 密码修改后系统还用旧密码连接？ 修改 conf/app.conf 中 oracle_password 后需重启程序。

Q10：修改端口后不生效？ app.conf 修改后需重启；也可在「系统设置」页面修改（同样需重启生效）。

9.1 数据存储位置

9.2 备份建议

• 最小备份集：conf/（app.conf + data.dat + license.dat）+ 可选 data/（历史结果）。
• 完整备份：整个程序目录（含 conf/、data/）。

9.3 迁移到新服务器

1. 在目标机器按 第 2 章 部署相同版本程序。
2. 停止旧程序 → 复制 conf/（app.conf、data.dat、license.dat）到新机器对应位置。
3. 如需要历史结果，一并复制 data/。
4. 启动新程序，检查配置（Oracle 地址、端口等）是否适用新环境。

9.4 本文档（多语言版）的迁移与在线阅读

• 本说明文档存放于程序目录 docs/ 下，按语言命名：zh-CN.md、zh-TW.md、en-US.md、ja-JP.md、ko-KR.md、fr-FR.md、de-DE.md、es-ES.md、th-TH.md、vi-VN.md、ru-RU.md、pt-PT.md。
• 图片统一存放在 docs/images/ 目录，文档内使用本地相对路径引用（如 ![示意图](images/xxx.png)），无任何第三方远程图片链接。迁移文档时请连同 docs/images/ 目录一起复制，图片即随文档走。
• 在线阅读：所有 .md 文件为纯 Markdown，可直接在 Gitea / GitHub / GitLab / Gitee 等平台的文档仓库中在线渲染阅读，无需额外工具。
• 各语言版本内容一致，入口见 docs/README.md 索引。