============================================================
  Oracle2PostgreSQL v1.0.0 説明書
  Oracle → PostgreSQL SQL 自動移行ツール（GUI / CLI 対応）
============================================================

■ ソフト名
  Oracle2PostgreSQL

■ バージョン
  1.0.0

■ 作者名
  highdefinitionaudiodriver

■ 連絡先
  GitHub: https://github.com/highdefinitionaudiodriver
  リポジトリ: https://github.com/highdefinitionaudiodriver/Oracle2PostgreSQL
  バグ報告・機能要望: highdefinitionaudiodriver@gmail.com

■ 動作環境
  対応OS: Windows 10 / 11（64bit推奨）
          macOS, Linux（ソースから実行可）
  必要メモリ: 512MB以上
  ディスク容量: 約13MB（EXE単体）
  ランタイム: 不要（EXE版は同梱済み。ソース版はPython 3.11以上）

■ ソフト種別
  フリーソフト（MITライセンス）

■ カテゴリ
  プログラミング > データベース移行ツール

■ 概要
  Oracle2PostgreSQLは、Oracle SQL / PL-SQL ソースファイルを
  PostgreSQL 互換の SQL / PL/pgSQL に自動変換するデスクトップ
  アプリケーションです。

  単純な正規表現による文字列置換ではなく、Oracle SQL を
  抽象構文木（AST）にパースしてから変換を行います。
  これにより、文字列リテラル内の誤置換を防ぎ、テーブル定義・
  制約・PL/SQL ブロックの構造を正確に把握した上で変換できます。

  GUIとCLIの両方に対応しており、GUIで手軽に変換することも、
  CLIでCI/CDパイプラインに組み込んで自動化することも可能です。
  さらにDocker Composeによるコンテナ実行にも対応しています。

■ 主な機能

  【変換機能（104ルール搭載）】
  ・データ型変換
    VARCHAR2 → VARCHAR, NUMBER → NUMERIC, DATE → TIMESTAMP,
    CLOB/NCLOB → TEXT, BLOB → BYTEA, XMLTYPE → XML 等
  ・関数変換
    SYSDATE → CURRENT_TIMESTAMP, NVL → COALESCE,
    DECODE → CASE, SUBSTR → SUBSTRING, SYS_GUID → gen_random_uuid,
    seq.NEXTVAL → nextval('seq') 等
  ・構文変換
    FROM DUAL 削除, Oracle ヒント削除, MINUS → EXCEPT,
    STORAGE/TABLESPACE 句削除, GLOBAL TEMPORARY → TEMPORARY 等
  ・PL/SQL → PL/pgSQL 変換
    DBMS_OUTPUT.PUT_LINE → RAISE NOTICE,
    RAISE_APPLICATION_ERROR → RAISE EXCEPTION,
    EXECUTE IMMEDIATE → EXECUTE, :NEW/:OLD → NEW/OLD 等
  ・トリガー分離変換
    Oracle トリガーを PostgreSQL の「関数 + CREATE TRIGGER」形式に分離
  ・パッケージ変換ガイド
    PACKAGE を Schema + 個別関数へ変換するガイドコメントを自動挿入
  ・シーケンス・シノニム変換
    Oracle 固有構文を PostgreSQL 標準形式に変換

  【AST ベースパーサー】
  ・CREATE TABLE / INDEX / VIEW の構造的パース
  ・CREATE SEQUENCE / SYNONYM のパース
  ・CREATE PROCEDURE / FUNCTION / PACKAGE のパース
  ・CREATE TRIGGER のパース
  ・PL/SQL ブロック（DECLARE/BEGIN/EXCEPTION/END）の構造解析

  【3段階重要度判定】
  ・AUTO: 自動変換済み（そのまま使用可能）
  ・REVIEW: 要確認（自動変換済みだが目視確認推奨）
  ・MANUAL: 手動対応必須（ガイドコメント付与済み）

  【HTML / CSV 移行レポート】
  ・Executive Summary（ファイル数、変更数、重要度別集計）
  ・カテゴリ別集計テーブル
  ・要確認・手動対応項目の一覧（ファイル名・行番号・ルールID）
  ・ファイルごとの変更詳細

  【GUI（62言語対応）】
  ・入力/出力フォルダの選択
  ・設定ファイル（config.yaml）の読み込み・自動反映
  ・エンコーディング・拡張子の設定
  ・変換オプションのチェックボックス切り替え
  ・リアルタイム変換ログ表示
  ・変換のキャンセル機能
  ・プログレスバーによる進捗表示

  【CLI モード】
  ・ヘッドレス実行（-i, -o オプション指定）
  ・CI/CDパイプラインへの組み込み対応
  ・YAML設定ファイルによるルールON/OFF制御

  【Docker モード】
  ・マルチステージ Docker ビルド
  ・docker-compose で migration / test / postgres の3サービス
  ・PostgreSQL コンテナで変換結果を即座に検証可能

  【設定ファイル（config.yaml）】
  ・ルールカテゴリ ON/OFF
  ・個別ルールの無効化（ルールID指定）
  ・スキーママッピング（HR → public 等）
  ・ログ設定（レベル、ローテーション、保持世代）
  ・入出力エンコーディング設定

■ 対応言語（UI）
  62言語に対応:
  日本語, English, 中文(簡体/繁体), 한국어, ไทย,
  Tiếng Việt, Bahasa Indonesia, Bahasa Melayu,
  हिन्दी, বাংলা, தமிழ், Français, Deutsch, Italiano,
  Español, Português, Русский, Українська, Polski,
  العربية, עברית, فارسی, Türkçe, Svenska, Suomi
  ほか全62言語

■ インストール方法

  【EXE版（推奨・簡単）】
  1. Oracle2PostgreSQL.exe をダウンロード
  2. 任意のフォルダに配置（インストーラ不要）
  3. ダブルクリックで起動
  ※ Pythonやその他ランタイムのインストールは不要です。

  【ソース版】
  1. Python 3.11 以上をインストール
  2. コマンドプロンプト（またはターミナル）で以下を実行:
     git clone https://github.com/highdefinitionaudiodriver/Oracle2PostgreSQL.git
     cd Oracle2PostgreSQL
     pip install -e .
     python main.py

■ 使い方

  【GUI モード（デフォルト）】
  1. Oracle2PostgreSQL.exe をダブルクリック
     （またはpython main.pyで起動）
  2. 「入力フォルダ」に変換対象のOracle SQLファイルがある
     フォルダを指定
  3. 「出力フォルダ」に変換後のPostgreSQLファイルの出力先を指定
  4. 必要に応じてオプションを設定:
     - 設定ファイル（config.yaml）の読み込み
     - エンコーディング（UTF-8, Shift_JIS, EUC-JP 等）
     - ファイル拡張子（.sql, .pls, .pkb, .pks 等）
     - 変換カテゴリの ON/OFF 切り替え
     - レポート生成・バックアップ作成の ON/OFF
  5. 「変換」ボタンをクリック
  6. ログパネルで変換の進捗を確認
  7. 出力フォルダに変換済みファイルとレポートが生成される

  【CLI モード】
  基本:
    Oracle2PostgreSQL.exe -i <入力フォルダ> -o <出力フォルダ>

  例:
    Oracle2PostgreSQL.exe -i ./oracle_sql -o ./pg_output --lang ja
    Oracle2PostgreSQL.exe -i ./input -o ./output -c config.yaml
    Oracle2PostgreSQL.exe -i ./input -o ./output --no-plsql --no-triggers

  主なオプション:
    -i, --input      : 入力フォルダ（必須）
    -o, --output     : 出力フォルダ（必須）
    -c, --config     : 設定ファイルパス（デフォルト: config.yaml）
    -e, --encoding   : エンコーディング（デフォルト: utf-8）
    --extensions     : ファイル拡張子（カンマ区切り）
    --lang           : 出力言語
    --no-datatypes   : データ型変換をスキップ
    --no-plsql       : PL/SQL変換をスキップ
    --no-sequences   : シーケンス変換をスキップ
    --no-synonyms    : シノニム変換をスキップ
    --no-packages    : パッケージ変換をスキップ
    --no-triggers    : トリガー変換をスキップ
    --no-report      : レポート生成をスキップ
    --no-backup      : バックアップ作成をスキップ

  【Docker モード】
    docker compose build
    docker compose up migration
    docker compose run --rm test

■ 推奨ワークフロー
  1. Oracle2PostgreSQL で自動変換を実行
  2. HTML レポートの REVIEW / MANUAL 項目を確認
  3. MANUAL 項目を手動で修正
  4. PostgreSQL テスト環境で変換結果を実行・検証
  5. 本番環境へ適用

■ ファイル構成（EXE版）
  Oracle2PostgreSQL.exe   - 実行ファイル（これだけで動作します）

■ ファイル構成（ソース版）
  main.py                     - エントリポイント（CLI + GUI起動）
  config.yaml                 - 設定ファイルテンプレート
  pyproject.toml              - パッケージ設定
  requirements.txt            - Python 依存パッケージ
  Dockerfile                  - マルチステージ Docker ビルド
  docker-compose.yml          - Docker Compose 設定
  test_conversion.py          - テストスイート（39件）
  src/
    __init__.py               - パッケージ初期化
    oracle_parser.py          - Oracle SQL/PL-SQL パーサー（AST生成）
    migration_rules.py        - 104 変換ルール定義
    postgres_transformer.py   - 変換エンジン（ルール適用）
    postgres_generator.py     - PostgreSQL 出力ファイル生成
    report_generator.py       - HTML/CSV レポート生成
    config_loader.py          - config.yaml ローダー
    logger.py                 - 構造化ロガー
    i18n.py                   - 62言語国際化
  samples/                    - サンプル Oracle SQL（7ファイル）
    01_create_tables.sql
    02_sequences_indexes.sql
    03_views_synonyms.sql
    04_plsql_procedures.sql
    05_packages.sql
    06_triggers.sql
    07_queries.sql
  .github/workflows/
    ci.yml                    - GitHub Actions CI パイプライン

■ 変換ルール一覧（抜粋）

  【データ型変換】
  DT_001: VARCHAR2(n) → VARCHAR(n)
  DT_002: NVARCHAR2(n) → VARCHAR(n)
  DT_003: NUMBER(p) → NUMERIC(p)
  DT_006: DATE → TIMESTAMP
  DT_007: CLOB → TEXT
  DT_009: BLOB → BYTEA
  DT_013: XMLTYPE → XML

  【関数変換】
  FN_001: SYSDATE → CURRENT_TIMESTAMP
  FN_003: NVL(a,b) → COALESCE(a,b)
  FN_005: DECODE → CASE（要手動）
  FN_008: SUBSTR → SUBSTRING
  FN_011: SYS_GUID() → gen_random_uuid()
  FN_019: seq.NEXTVAL → nextval('seq')

  【構文変換】
  SX_001: FROM DUAL → 削除
  SX_002: MINUS → EXCEPT
  SX_003: Oracle ヒント → 削除

  【PL/SQL変換】
  PL_001: DBMS_OUTPUT.PUT_LINE → RAISE NOTICE
  PL_002: RAISE_APPLICATION_ERROR → RAISE EXCEPTION
  PL_003: EXECUTE IMMEDIATE → EXECUTE

  ※ 全104ルールの詳細は README.md を参照してください。

■ 制限事項

  ・動的SQL（EXECUTE IMMEDIATE内の文字列）は
    静的解析できないため構文変換は行われません
  ・CONNECT BY 階層クエリは WITH RECURSIVE への
    完全自動変換ではなく、ガイドコメントのみ挿入されます
  ・Oracle固有パッケージ（DBMS_LOB, UTL_FILE 等）の
    呼び出しは検出・警告のみ行います
  ・データ移行（テーブルデータのETL）は対象外です。
    pgLoader 等の専用ツールをご利用ください
  ・Database Link, Advanced Queue, Oracle Text 等の
    Oracle固有ミドルウェア機能は対象外です
  ・変換後のSQLがPostgreSQLで正しく実行できることの
    保証はしません。必ずテスト環境で検証してください

■ アンインストール方法
  フォルダごと削除してください。
  レジストリへの書き込みは一切行いません。

■ 免責事項
  本ソフトウェアの使用により生じたいかなる損害に対しても、
  作者は一切の責任を負いません。
  変換結果は「ベストエフォート」です。本番環境への適用前に、
  必ず十分なテストとDBAによるレビューを実施してください。
  自己責任にてご利用ください。

■ 著作権・ライセンス
  Copyright (c) 2026 highdefinitionaudiodriver
  MITライセンスに基づき自由に使用・改変・再配布できます。
  詳細はLICENSEファイルを参照してください。

■ 変更履歴

  v1.0.0 (2026-03-28)
    - 初版リリース
    - AST ベース Oracle SQL パーサー搭載
    - 104 変換ルール（データ型/関数/構文/PL-SQL/トリガー等）
    - GUI / CLI / Docker の3モード対応
    - HTML / CSV 移行レポート生成
    - YAML 設定ファイル対応
    - 構造化ロギング（RotatingFileHandler）
    - 62言語 i18n 対応
    - GitHub Actions CI ワークフロー
    - テストスイート（39件、pytest対応）

============================================================
