Руководство пользователя SQLVantage (Русский)

1. Обзор системы
2. Установка и развертывание (Windows / Linux)
3. Инструкции по конфигурации
4. Руководство администратора
5. Руководство по проектированию отчетов (SQL/FORM/HTML)
6. Руководство конечного пользователя
7. Выполнение запросов и результаты вывода
8. Часто задаваемые вопросы (FAQ)
9. Приложение: Хранение данных, резервное копирование и миграция

Это система отчетов SQLVantage. Администратор поддерживает определения отчетов, а «пользователи конечного пользователя» выбирают отчет на веб-странице, заполняют условия запроса, асинхронно получают результаты и экспортируют их как Excel / HTML / JSON / TEXT.

SQLVantage — это веб-система для создания отчетов. «Администратор» поддерживает определения отчетов, а «пользователи конечного пользователя» выбирают отчет на веб-странице, заполняют условия запроса, асинхронно получают результаты и экспортируют их как Excel / HTML / JSON / TEXT.

Эта система имеет чистую архитектуру веб-приложения: в браузере не нужно устанавливать любой клиент или плагин — любой современный браузер может к нему обратиться. На серверной стороне для работы требуется только исполняемый программный продукт и его сопутствующие каталоги конфигурации, что упрощает развертывание.

После распаковки выпускного пакета:

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); заранее проверьте сеть и аккаунт
• Разрешения диска/каталога: каталог рабочей программы должен иметь запись (writable), так как в ходе работы создаются каталоги data/ и tmp/ и читаются/записываются файлы в conf/

2.2 Установка на Windows

1. Распаковка: Распакуйте выпускной пакет (zip) в любой каталог, например C:\\SQLVantage\\. После распаковки убедитесь, что существуют следующие ключевые файлы:

C:\\SQLVantage\\
├── SQLVantage.exe      # Основная программа
├── conf\\app.conf      # Файл конфигурации
├── conf\\data.dat      # Данные (пустая база данных, идущая в комплекте)
└── conf\\locale\\      # Языковые пакеты

2. (Опционально) Настройка: откройте conf\\app.conf с помощью Блокнота и измените адрес прослушивания, порт, подключение к Oracle и т.д. согласно Глава 3.

3. Запуск программы: дважды щелчком на SQLVantage.exe, или запустите в командной строке:

cd C:\\SQLVantage
SQLVantage.exe

После успешного запуска консоль выведет информацию о версии, состояние лицензии и войдет в состояние прослушивания.

4. Доступ к системе: откройте http://127.0.0.1:8080 в браузере (адрес по умолчанию; можно изменить в app.conf).

5. Настройка файрвола: если требуется доступ LAN/удаленный, откройте соответствующий порт (например, 8080) в防火墙 Windows:

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

Когда вы увидите информацию о версии и запись в журнал прослушивания, запуск successful; нажмите 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. 防火wall / Security Group: откройте порт (например, 8080):

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

2.4 Компиляция из исходного кода (необязательно)

Только для пользователей, получивших исходный код: запустите команду сборки в исходном каталоге для получения исполняемого файла для текущей платформы. Для производственной среды развертывания рекомендуется сразу использовать выпущенный исполняемый файл.

2.5 Первый запуск

В первый раз запуска система автоматически завершает следующую инициализацию:

1. Проверка файла данных: читает conf/data.dat (идет в комплекте; если она отсутствует, программа выдаст сообщение "conf/data.dat is not found" и завершит работу — пожалуйста, не удаляйте этот файл).
2. Автоматическое создание таблиц: 4 таблицы user, responsibility, report, request автоматически создаются.
3. Автоматическое создание аккаунта администратора: на первом посещении /admin/login, если пользователя root не существует, система автоматически создает его:
   • Имя пользователя: root
   • Начальный пароль: SQLVantage
   • Роль: администратор
   • Безопасное предупреждение: сразу после первого входа обязательно измените этот пароль (администратор может изменить его в "Управлении пользователями").
4. Проверка файла лицензии: если conf/license.dat отсутствует или недействителен, консоль выдаст предупреждение; система все равно может работать, но подвержена ограничениям лицензии, описанным в Section 4.7.

3.1 Положение файла конфигурации

Файл конфигурации — это conf/app.conf (формат INI). Существует два способа его изменить:

• Способ 1 (рекомендуется, через интерфейс пользователя): после входа в систему как администратор, перейдите к "Настройкам системы" (/admin/setting), введите значения и сохраните; система автоматически запишет их обратно в app.conf.
• Способ 2 (прямое редактирование файла): с помощью текст редактора измените conf/app.conf, а затем перезапустите программу.

3.2 Справочник параметров

| oracle_server | Например, 192.168.10.13 | IP/Hostname сервера базы данных Oracle | | oracle_port | 1521 | Порт прослушивания Oracle | | oracle_database | test | Имя сервиса Oracle (SERVICE_NAME) | | oracle_username | apps | Имя пользователя для подключения Oracle | | oracle_password | none | Пароль подключения Oracle (пожалуйста, введите настоящий пароль) |

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.
• Способ переключения: добавьте ?lang=ru-RU в URL (например, /?lang=ru-RU), или выберите через меню языка в правом верхнем углу панели администратора; после выбора это записывается в 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 (левое меню "Управление пользователями").

Детали полей пользователя:

Действия:

• Создание: нажмите кнопку "Создание" → заполните Имя пользователя/Email/Вайл/Статус/Пароль/Подтверждение пароля → отправьте.
• Редактирование: нажмите "Редактирование" в строке → можно изменить Email, Вайл и Статус; оставление поля Пароль пустым означает, что изменений не будет.
• Удаление: нажмите "Удаление" в строке. Важные примечания:
  • Аккаунт root нельзя удалять.
  • Пользователь, у которого есть отчеты, нельзя удалять (сначала нужно удалить/перенести их отчеты).

Точки управления:

• Точка входа для обычных пользователей — /login (главная страница), а для администратора — /admin/login; они различаются.
• Установка для обычного пользователя статуса inactive достаточно для блокировки входа; удалять аккаунт не нужно.
• root автоматически скрывается в списке пользователей.

4.4 Управление ответственностью (Responsibility)

Точка входа: /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:

• Настройки приложения: адрес прослушивания, порт, режим выполнения, язык по умолчанию, максимальное время выполнения;
• Настройки сессии: время жизни сессии (секунды);
• Настройки базы данных Oracle: сервер, порт, имя службы, имя пользователя, пароль (с кнопкой переключения между открытым текстом/зашифрованным текстом).

После сохранения некоторые параметры вступают в силу немедленно, параметры, такие как порт, требуют перезапуска программы.

4.9 О нас

Точка входа: /admin/aboutus, просмотр версии системы, сведения о выпуске и т.д.

Это самая важная функция SQLVantage. Отчет состоит из трех частей:

• SQL: определяет, какие данные запрашивать (SQL-запрос + конфигурация метаданных столбца)
• FORM: определяет, какие условия запроса заполняет пользователь (форма параметров)
• HTML: определяет, как отображаются результаты (таблица / график / макет KPI-карточки)

У каждой из трех частей есть два элемента данных — "код" и "формат JSON" — которые в конечном итоге сохраняются в записи отчета.

5.1 Рабочее пространство конструктора

5.1.1 Вход в конструктор

1. Войти в систему как администратор → Управление отчетами (/admin/report).
2. Найдите целевой отчет и нажмите кнопку "Code" (фиолетовый).
3. Появляется большое окно конструктора (около 98% экрана), интерфейс разделен на левую и правую панели:

┌────────────────────────────────────────────────────────┐
│ [下拉：SQL设计 | FORM设计 | HTML设计]   [保存全部]        │
├───────────────────────────────┬────────────────────────┤
│ Слева: Редактор кода          │ Справа: Динамический макет │
│ (SQL-код / FORM-код /          │ (меняется в соответствии с левым режимом) │
│  HTML-код используют общий editor) │   · 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 использует syntax Oracle; прямо напишите инструкцию SELECT (FROM/JOIN/WHERE/GROUP BY и т.д. могут быть включены).
• Условия запроса используют именованные маркеры параметров :имя_параметра, и имя параметра должно совпадать с field, определенным в режиме FORM. Например, если в FORM определен параметр P_OU_ID, напишите в SQL следующее:

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

• Все имена столбцов, выбранные в SQL, являются идентификаторами полей Excel-экспорта и HTML-страничного таблица (рекомендуется унифицированно использовать заглавные буквы, например COMPANY_NAME).

5.2.2 Таблица метаданных столбца SQL (Ключ: Excel-Export)

"Таблица метаданных столбца SQL" справа имеет 1 строку для каждой столбца, 출력由 SQL：

Действия: нажмите "Добавить строку", чтобы добавить столбец → дважды щелчок по ячейке для заполнения →Snapshot JSON будет автоматически создан (правая черная область просмотра кода) и сразу записано в sql_format в режиме реального времени.

5.3 Момент связывания между конфигурациями столбца SQL и Excel-Export

Система в фоновом режиме генерирует файл Excel (xlsx) согласно следующим правилам связывания:

Кратко: Таблица метаданных столбца SQL — это полная определение "заголовок + тип столбца + числовой формат + выравнивание" для Excel-Export. Даже без какого-либо конфигурации Excel все еще может быть экспортирован (по умолчанию текстовый тип, выравнивание по левому краю, заголовки колонок используют исходные имена столбцов), но экспортированный Excel после конфигурации будет более профессиональным.

5.3 Модуль FORM (Проектирование формы параметров запроса)

5.3.1 Таблица конфигурации параметров

"Таблица конфигурации параметров" справа определяет 1 строку 1 параметр запроса:

Таблица типов:

5.3.2 Сопровождение параметров (Зависимый фильтр)

• api_url / query_sql поддерживает {имя_переменной} маркеры: когда пользователь меняет upstream-параметр (например, выбирает организацию), система автоматически заменяет маркер на текущее значение в форме и динамически запрашивает варианты выпадающего списка downstream.

• Если upstream-параметр не заполнен, выпадающий список downstream покажет "Сначала завершите вышестоящие фильтры" и очистит варианты, избегая грязных данных.

• Выберите один из двух: статический выпадающий список (static_options) и динамический выпадающий список (api_url / query_sql).

Требование к формату данных для динамического выпадающего списка: каждый возвращенный API/SQL запись должна содержать 2 поля: val (значение) и txt (отображаемый текст).

5.3.3 Прямой предварительный просмотр и генерация кода

• Под таблицей находится "Прямой предварительный просмотр": форма (включая контроллеры даты, зависимые выпадающие списки и т.д.) в режиме реального времени отображается по мере конфигурирования параметров.
• "Черновик кода формы" внизу в режиме реального времени генерирует полный HTML-код формы.
• Нажмите кнопку "Скопировать и применить": черновик кода записывается в редактор (режим FORM) и синхронизируется с form_code / form_format.

Вы также можете обойти правую панель и вручную написать HTML-форму (форма-синтаксис) прямо в левом редакторе; это также будет работать при сохранении.

5.3.4 Реальное время

После того как конечный пользователь отправит форму, система свяжет данные формы с SQL как именованные параметры и выполнит их; параметры также будут записаны в запрос, чтобы страница результатов/файл экспорта могли отразить условия запроса.

5.4 Модуль HTML (Проектирование отображения результатов)

5.4.1 Таблица конфигурации блоков HTML

Каждая строка "Таблицы конфигурации блоков HTML" справа определяет 1 блок отображения:

Giải thích phần tử:

5.4.2 Прямой предварительный просмотр и генерация кода

• "Прямой предварительный просмотр" отображает実时-реальный образ высокой фidelities каждого блока (tên + loại bloc + chiều rộng).
• "Черновик kода HTML" автоматически генерирует полный HTML-код в режиме реального времени (включая атрибуты runtime такие как data-component, data-subtotal, data-charttype, data-xfield, data-yfields).
• Нажмите кнопку "Скопировать и применить": записывает в редактор и синхронизирует html_code / html_format.

Вы также можете вручную написать HTML-шаблон прямо в левом редакторе (поддерживает популярный синтаксис шаблона). Для данных объектов, доступных при рендеринге, см. 5.4.3.

5.4.3 Механизм отображения страницы результата

Khi người dùng cuối tải/xem kết quả HTML (/request/output?ext=html), hệ thống sẽ kết hợp mã báo cáo với kết quả JSON truy vấn, metadata столбца и т.д.:

Trang sẽ tự động将容器 có data-component="table" thành bảng dữ liệu, chart thành biểu đồ, card thành KPI card.

5.5 Quy trình phát hành báo cáo (Khuyến nghị cho Quản trị viên)

1. Quản lý báo cáo → Tạo báo cáo mới (Chọn ответственность, điền Tên, Chọn trạng thái Draft)
2. Bấm "Code" để truy cập Kiến trúc
3. SQL-Design: Viết SQL + cấu hình metadata столбца (là cơ sở cho Excel-Export)
4. FORM-Design: Cấu hình tham số (khớp 1-1 với SQL параметр)
5. HTML-Design: Cấu hình bố cục hiển thị (Bảng/Biểu đồ/KPI card)
6. Bấm "Lưu tất cả" → Đóng Kiến trúc
7. Trở lại danh sách báo cáo, chuyển trạng thái thành Release (phát hành)
8. Người dùng thường đăng nhập tức हीici có thể trong menu báo cáo thấy báo cáo đó và thực thi

5.5 Ghi chú về проектирование

• Tên параметров в SQL и FORM должны совпадать ровно (SQL использует :имя_параметра, FORM использует field).
• Имена столбцов SQL должны быть заглавными буквами; таблица метаданных столбцов автоматически将 field转换 в заглавные буквы.
• SQL отчета должен быть способен к предварительной компиляции Oracle (db.Prepare); синтаксические ошибки приведут к сбою выполнения запроса (Статус Error).
• Без действующей лицензии количество отчетов ограничено 3; перед проектированием обязательно проверьте состояние лицензии.
• После сохранения einmal можно выполнить запрос в "Управление запросами" или на стороне конечного пользователя, чтобы проверить, правильны ли SQL и отображение.

6.1 Вход в систему

1. Метод один: ERP-аутентификация (Oracle EBS Single Sign-On)
2. Метод два: Локальный аккаунт

6.2 Главная страница портала

6.3 Создание нового запроса отчета

6.4 Моя страница запросов

6.5 Смена пароля

6.6 Несколько дополнительных заметок

7.1 Процесс выполнения (асинхронный)

7.2 Формат вывода

7.3 Контроль доступа

7.4 Часто задаваемые вопросы

9.1 Адрес хранения данных

9.2 Рекомендации по резервному копированию

9.3 Миграция на новый сервер

9.4 Мультиязычный документ (Multilingual Document) Миграция и Онлайн-чтение