ソースコードガイド

千桐科技2026/08/13約7分ソース構成コアメリットソースコード構成二次開発

qData ソースコード構成説明

このガイドの対象者

qData のソースコードを初めて扱い、プロジェクト構成を早く理解したい開発者
qData を基盤に二次開発を行う開発者
画面、API、データベーステーブルからコードをすばやく特定したい開発者

モジュール一覧、バージョン、依存関係は、現在のブランチの pom.xml と実際のコードを正としてください。

1. トップレベルディレクトリ

qData/
├── pom.xml                    # Maven 集約プロジェクトと統一バージョン管理
├── qdata-server/              # メインサービス起動モジュール
├── qdata-framework/           # セキュリティ、データアクセス、キャッシュ、ファイル、スケジューリング
├── qdata-module-system/       # ユーザー、ロール、メニュー、辞書、ログ
├── qdata-module-att/          # プロジェクト、カテゴリ、タグ、テーマ、ルール
├── qdata-module-da/           # データソース、データ資産、資産検出、資産操作
├── qdata-module-dm/           # データドメイン、業務分類、DWH レイヤー、サブジェクト領域
├── qdata-module-dp/           # データ要素、コード対応、論理モデル、標準文書
├── qdata-module-dpp/          # データ統合、開発、スケジュール、品質タスク編成
├── qdata-module-ds/           # API データサービス、認証、呼び出しログ
├── qdata-module-mc/           # メタデータ収集タスク、インスタンス、バージョン
├── qdata-module-dg/           # データ分類、機密識別、マスキングガバナンス
├── qdata-module-ai/           # AI モデル、会話、メッセージの業務データと管理 API
├── qdata-api-ds/              # DolphinScheduler 契約とアダプター実装
├── qdata-executor-etl/        # Spark / DataX データ処理プログラム
├── qdata-service-quality/     # 独立したデータ品質実行サービス
├── qdata-service-ai/          # 独立したインテリジェントデータ検索 Maven プロジェクト
├── qdata-ui/                  # Vue 3 フロントエンドプロジェクト
├── sql/                       # MySQL、DM、DolphinScheduler SQL
├── docker/                    # Compose、Nginx、ミドルウェア、サービス設定
├── docs/                      # リポジトリで管理する多言語ドキュメント
└── images/                    # README とドキュメント画像

アーキテクチャ上のメリット

フロントエンドとバックエンドの分離：qdata-ui は独立してビルドされ、API 経由でバックエンドにアクセスするため、画面開発とサービス開発が互いに干渉しません。
業務モジュール化：システム、資産、標準、開発、データサービス、メタデータ、ガバナンスなどを業務領域ごとに分割し、特定と拡張を容易にしています。
管理と実行の分離：メインサービスが管理を担い、ETL、品質、AI は独立した実行単位で動作するため、リソース設定やログ調査を個別に行えます。
共通機能の再利用：セキュリティ、データアクセス、キャッシュ、ファイル、スケジューリングを qdata-framework に集約し、重複実装を減らしています。
明確なデプロイ境界：ソースコード、データベーススクリプト、Docker 設定を明確に分離し、ローカル開発とコンテナデプロイを容易にしています。

2. 実行エントリの説明

実行単位	エントリファイル	デフォルトポート	主な役割	ビルド場所
メインサービス	`QDataApplication.java`	8080	ログイン認証、システム管理、業務 API	ルート Maven プロジェクト
品質実行サービス	`QualityApplication.java`	8083	品質検査 SQL の生成と実行	ルート Maven プロジェクト
ETL プログラム	`EtlApplication.java`	なし	データの読み取り、変換、書き出し	ルート Maven、スケジューラが呼び出し
インテリジェント検索	`QDataAiApplication.java`	8087	モデル呼び出し、会話、Text2SQL	独立した `qdata-service-ai`
フロントエンド	`qdata-ui/src/main.js`	開発時 81	Vue、ルーター、Pinia、i18n の初期化	`qdata-ui`

3. フロントエンド構成

3.1 フロントエンドのルートディレクトリ

qdata-ui/
├── .env.development          # 開発環境変数
├── .env.production           # 本番環境変数
├── .env.staging              # テスト環境変数
├── .eslintignore             # ESLint 除外設定
├── eslint.config.js          # ESLint ルール
├── index.html                # Vite エントリ
├── package.json              # 依存関係と npm コマンド
├── yarn.lock                 # Yarn ロックファイル
├── vite.config.js            # Vite、プロキシ、ビルド設定
├── run-dev.sh                # 開発起動スクリプト
├── bin/                      # Windows 用ビルド・起動スクリプト
│   ├── build.bat
│   ├── package.bat
│   └── run-web.bat
├── html/
│   └── ie.html               # ブラウザ互換性の案内ページ
├── public/                   # コンパイル対象外の公開静的リソース
│   ├── excel/                # Excel インポートテンプレート
│   ├── favicon.ico
│   └── qData-simlogo.png
├── vite/
│   └── plugins/              # Vite プラグイン設定
│       ├── auto-import.js
│       ├── compression.js
│       ├── setup-extend.js
│       ├── svg-icon.js
│       └── index.js
└── src/                      # フロントエンド業務ソース

フロントエンドのルートディレクトリのメリット

設定を一元管理：環境変数、依存関係、ビルドルールをまとめて管理します。
操作が容易：複数のプラットフォーム向けに起動・ビルドスクリプトを提供します。
境界が明確：静的リソース、ビルド設定、業務ソースを分離しています。

3.2 `src` ソースディレクトリ

qdata-ui/src/
├── App.vue                   # Vue ルートコンポーネント
├── main.js                   # アプリ初期化入口
├── permission.js             # ログイン検証とルートガード
├── settings.js               # タイトル、テーマ、レイアウト
├── api/                      # HTTP リクエスト関数
├── views/                    # 画面と画面コンポーネント
├── router/                   # ルート定義
├── store/                    # Pinia 状態管理
├── layout/                   # メインレイアウト
├── components/               # 共通コンポーネント
├── composables/              # Vue Composition 関数
├── directive/                # カスタムディレクティブ
├── plugins/                  # グローバルプラグイン
├── utils/                    # 共通ユーティリティ
├── assets/                   # ビルド時静的リソース
├── locales/                  # 画面・メニュー翻訳
└── i18n/                     # 国際化互換リソース

src ソース構成のメリット

特定が容易：views と api を業務領域ごとに対応させ、リクエストを追跡しやすくしています。
責務が明確：画面、ルート、状態、共通機能をディレクトリごとに管理します。
拡張が容易：共通コンポーネントと多言語リソースを一元的に再利用します。

3.3 ルーティング

ログイン、詳細、編集などの固定・非表示ルートは src/router で管理します。
メニューのルートはバックエンド /getRouters が返し、src/store/system/permission.js が import.meta.glob で src/views の Vue コンポーネントを動的登録します。

3.4 フロントエンドに対応するバックエンドモジュールの探し方

フロントエンドは画面とリクエストを業務ディレクトリごとに整理し、バックエンドも同じ業務境界でモジュールを分割しています。主な対応関係は次のとおりです。

業務機能	フロントエンドモジュール	バックエンドモジュール
データ資産	`src/views/da`、`src/api/da`	`qdata-module-da`
メタデータ収集	`src/views/mc`、`src/api/mc`	`qdata-module-mc`
データ統合・開発	`src/views/dpp`、`src/api/dpp`	`qdata-module-dpp`
データサービス	`src/views/ds`、`src/api/ds`	`qdata-module-ds`
システム管理	`src/views/system`、`src/api/system`	`qdata-module-system`

フロントエンドとバックエンドは同じ業務略称とモジュール境界を使用します。例えば、da はデータ資産、mc はメタデータ収集を表します。

フロントエンド・バックエンドのモジュール対応のメリット

直感的な構成：フロントエンドのディレクトリから対応するバックエンド業務モジュールを判断できます。
責務の統一：同じ業務の画面、リクエスト、バックエンド実装を同一領域にまとめ、モジュール間の交差を減らします。
効率的な連携：フロントエンドとバックエンドの開発者が同じ業務モジュールを基準に開発・連携できます。
保守が容易：変更や問題調査の対象コードをすばやく絞り込めます。
拡張が明確：新しい業務機能も同じディレクトリ・モジュール規則で追加できます。

3.5 フロントエンド画面のソースコードを特定する方法

二次開発では、次の方法でブラウザに表示されている画面に対応する .vue ファイルを特定できます。

画面情報を記録する：対象画面を開き、ブラウザの URL、メニュー名、画面上の特徴的な文言を確認する。
固定画面を探す：src/router で URL のルートパスを検索する。ルート設定の component が対応する src/views ファイルを示します。
メニュー管理から探す：システム管理 → メニュー管理を開き、メニュー名から対象メニューを探して コンポーネントパスを確認し、src/views 配下の対応する画面ファイルを特定します。
業務ディレクトリから探す：URL 内の業務略称を基に、src/views 配下の同名ディレクトリを探します。例えば、da/asset は通常 src/views/da/asset に対応します。
画面文言から探す：パスから特定できない場合は、ページタイトル、ボタン名、メッセージを src/views 内で検索する。

.vue ファイルを追加した後、ルートまたは他のコンポーネントから参照されることで画面にアクセスできるようになります。

4. バックエンドモジュール

バックエンドは業務モジュール、共通フレームワーク、独立実行プログラムで構成されます。メインサービスは各 biz サブモジュールを Maven で組み込み、ETL・品質・AI は実行特性に応じて独立稼働します。

4.1 `qdata-framework`

共通フレームワークの集約モジュールで、次のサブモジュールを含みます。

サブモジュール	提供機能
`qdata-common`	統一レスポンス、例外、基底オブジェクト、enum、アノテーション、ユーティリティ、Excel、暗号化・マスキング、DB アダプター
`qdata-config`	Spring、スレッドプール、国際化、フィルター、Captcha、RabbitMQ、OpenAPI、サーバー監視の設定
`qdata-mybatis`	MyBatis-Plus、ページング、基底 Mapper、動的データソース、データ権限クエリ、型処理
`qdata-security`	ログイン認証、トークン検証、API 権限、データ権限、レート制限、操作ログ、グローバル例外処理
`qdata-auth`	Sa-Token、OAuth2、認可モード関連の設定
`qdata-redis`	Redis シリアライズ、キャッシュ設定、共通キャッシュサービス
`qdata-websocket`	WebSocket 設定、オンラインセッション管理、メッセージプッシュ
`qdata-quartz`	Quartz タスク管理、実行戦略、実行ログ、統一スケジューリングアダプター
`qdata-file`	ファイルアップロード、ストレージ設定、ファイル処理ユーティリティ
`qdata-generator`	DB テーブル解析、フロントエンド・バックエンド・SQL・多言語コードテンプレートの生成
`qdata-neo4j`	Neo4j のノード、関係、Repository、データリネージアクセス
`qdata-pay`	Alipay、WeChat Pay、返金、コールバック通知、署名検証

モジュールのメリット

共通機能の一元的な再利用：セキュリティ、データベース、キャッシュ、ファイル、スケジューリング、グラフデータアクセスなどの基盤機能を一元管理することで、業務モジュールは業務ロジックに専念でき、技術実装の一貫性も維持できます。

4.2 `api` と `biz` の分離

多くの業務モジュールは、次の構成を採用しています。

qdata-module-xxx/
├── pom.xml
├── qdata-module-xxx-api/
│   └── src/main/java/.../api/
│       ├── dto/               # モジュール間で受け渡すデータオブジェクト
│       ├── service/           # 他モジュールに公開するサービスインターフェース
│       └── enums/             # 共有 enum（一部モジュールのみ）
└── qdata-module-xxx-biz/
    └── src/main/
        ├── java/.../module/xxx/
        │   ├── controller/    # HTTP API とリクエスト・レスポンス VO
        │   ├── service/       # 業務インターフェースと実装
        │   ├── dal/
        │   │   ├── dataobject/# データベースエンティティ DO
        │   │   └── mapper/    # MyBatis Mapper インターフェース
        │   ├── convert/       # DTO、VO、DO の変換
        │   └── utils/         # 業務モジュール内部ユーティリティ
        └── resources/
            ├── mapper/        # MyBatis XML
            ├── i18n/          # モジュール国際化メッセージ
            └── application-*.yml

モジュールのメリット

明確なモジュール間境界：*-api はインターフェース、DTO、共有 enum のみを公開し、*-biz は Controller、Service、Mapper、業務実装を保持します。他モジュールが内部実装へ直接依存することを防ぎます。

*-api はモジュール間呼び出しの契約層です。他の業務モジュールで機能を再利用する場合は、ここにあるインターフェースと DTO を優先して利用します。
*-biz は Controller、Service、Mapper、リソースファイルを含む完全な実装層で、qdata-server によって一括して組み込まれます。

4.3 ETL モジュール

qdata-executor-etl はデータの読み取り、クリーニング、変換、書き出しを担当し、Web API は公開しません。

qdata-executor-etl/src/main/
├── java/tech/qiantong/qdata/
│   ├── spark/etl/
│   │   ├── EtlApplication.java     # Spark ETL メインエントリ
│   │   ├── reader/                 # データ読み取りコンポーネント
│   │   ├── transition/             # クリーニング・変換コンポーネント
│   │   ├── writer/                 # データ書き出しコンポーネント
│   │   └── utils/                  # ログ、RabbitMQ、Redis、DB ツール
│   └── datax/
│       ├── DataXExecutor.java       # DataX 実行クラス
│       ├── DataXJsonBuilder.java    # DataX Job JSON の構築
│       ├── DataXProperties.java     # DataX 設定
│       └── DataXResult.java         # DataX 実行結果
└── resources/
    ├── i18n/                       # ETL 国際化メッセージ
    └── json/                       # タスク設定例

モジュールのメリット

管理と実行の分離：DPP がタスク設定とスケジューリングを担当し、qdata-executor-etl は Spark / DataX の計算に専念します。Reader、Transition、Writer を責務ごとに分割しているため、入力、変換、出力機能をそれぞれ独立して拡張できます。

コンポーネント	役割
`ReaderFactory`	種類に応じて DB、CSV、Excel Reader を選択
`TransitionFactory`	フィールド、定数、重複排除、派生、ソート、値マッピング変換を選択
`WriterFactory`	データ書き込み実装を選択
`RabbitmqUtils`	プロセス、ノード、ログを返却
`RedisUtils`	増分読み取りなどの実行状態を保存
`DataXJsonBuilder`	入力・処理・出力ノードから DataX Job JSON を生成
`DataXExecutor`	DataX を呼び出し結果を収集

Spark ETL の呼び出しチェーン：

qdata-module-dpp
  → qdata-api-ds
  → DolphinScheduler
  → EtlApplication
  → ReaderFactory → TransitionFactory → WriterFactory
  → RabbitMQ
  → qdata-module-dpp/listener が状態とログを更新

状態リスナーの場所：

qdata-module-dpp/qdata-module-dpp-biz/src/main/java/
└── tech/qiantong/qdata/module/dpp/listener/
    ├── ProcessListener.java
    ├── TaskListener.java
    └── TaskLogListener.java

qData、DolphinScheduler、Spark、RabbitMQ、Redis、およびタスクの入出力データソースを準備し、Spark Master、ETL JAR、エントリクラスを設定します。

ds:
  spark:
    master_url: spark://spark:7077
    main_jar: file:/dolphinscheduler/default/resources/spark-jar/qdata-executor-etl.jar
    main_class: tech.qiantong.qdata.spark.etl.EtlApplication

mvn clean package -pl qdata-executor-etl -am -DskipTests

JAR をビルドし、ds.spark.main_jar が示す DolphinScheduler のリソースディレクトリにアップロードします。

その後、qData の ETL 画面で次の操作を行います。

入力元と出力先のデータソースを設定し、接続をテストする。
データ統合タスクを新規作成し、1 つの読み取りノード、0 個以上の変換ノード、1 つの書き込みノードを追加する。
タスクを保存・公開し、DolphinScheduler から Spark に送信して実行する。
タスクインスタンス画面とノードログ画面で状態およびエラーを確認する。

4.4 AI モジュール

独立した qdata-service-ai プロジェクトが、モデル呼び出し、会話オーケストレーション、Text2SQL を担当します。

モジュール	位置付け	主な役割
`qdata-ai-core`	独立 AI プロジェクトのコアモジュール	Prompt、モデルアダプター、会話オーケストレーション、Text2SQL
`qdata-ai-server`	独立 AI プロジェクトの起動モジュール	HTTP API、セキュリティ認証、例外処理、実行設定

独立した qdata-service-ai の構成は次のとおりです。

qdata-service-ai/
├── pom.xml
├── qdata-ai-core/
│   └── src/main/java/.../ai/core/
│       ├── enums/                    # プラットフォーム、メッセージ、応答タイプ
│       ├── prompt/                   # Prompt の構築
│       ├── service/                  # 会話、メッセージ、モデルサービス
│       ├── service/impl/             # インテリジェント検索のコア実装
│       ├── utils/                    # LLM ユーティリティ
│       └── vo/                       # リクエスト・レスポンスオブジェクト
└── qdata-ai-server/
    └── src/main/
        ├── java/.../ai/
        │   ├── server/               # 起動、セキュリティ、例外処理
        │   └── controller/admin/     # モデル、会話、メッセージ API
        └── resources/                # AI サービス設定

AI リクエストの関係：

インテリジェントデータ検索画面
  → requestAi.js → /prod-ai/chat/message
  → qdata-ai-server → qdata-ai-core → 大規模言語モデルサービス

モジュールのメリット

独立デプロイ：qdata-service-ai がモデル呼び出しと Text2SQL を独立して担当するため、AI の負荷に応じて個別にデプロイ、アップグレード、スケールできます。

qdata-service-ai は JDK 17 が必須ですが、メインプロジェクトは引き続き JDK 8 を使用します。AI プロジェクトは Spring Boot 3.5.8、Spring AI 1.1.0、Jakarta エコシステムを採用しており、これらは Java 17 を必要とするため、メインプロジェクトの JDK 8 では直接実行できません。

AI サービスは独立した Maven プロジェクトであり、個別にビルドして起動する必要があります。

cd qdata-service-ai
mvn clean package -DskipTests
java -jar qdata-ai-server/target/qdata-ai-server.jar --spring.profiles.active=dev

IDE で qdata-service-ai に JDK 17 を設定し、次のクラスを実行することもできます。

qdata-service-ai/qdata-ai-server/src/main/java/
└── tech/qiantong/qdata/ai/server/QDataAiApplication.java

デフォルトポートは 8087 で、フロントエンドは /prod-ai 経由でアクセスします。起動前に、AI サービスが使用するデータベース、Redis、Neo4j、モデル API の設定が利用可能であることを確認してください。共有 DTO、API、依存関係を変更した場合は、Java 8 のメインプロジェクトと Java 17 の AI プロジェクトの両方を検証する必要があります。

5. 設定、データベース、デプロイファイル

5.1 プロジェクト設定

設定	主な場所	説明
メイン共通設定	`qdata-server/src/main/resources/application.yml`	ポート、Profile、MyBatis、API ドキュメント、Spring 設定
メイン環境設定	`qdata-server/src/main/resources/application-dev.yml`、`application-prod.yml`	DB、Redis、RabbitMQ、DolphinScheduler、品質サービス
品質サービス	`qdata-service-quality/src/main/resources/application*.yml`	品質 DB、MongoDB、ファイル、メッセージ
AI サービス	`qdata-service-ai/qdata-ai-server/src/main/resources/application*.yml`	データソース、Redis、モデル、業務設定
ファイル設定	`qdata-framework/qdata-file/src/main/resources/application-file-*.yml`	ファイル保存
システム設定	`qdata-module-system/qdata-module-system-biz/src/main/resources/application-system-*.yml`	システムモジュール
メタデータ設定	`qdata-module-mc/qdata-module-mc-biz/src/main/resources/application-mc-*.yml`	メタデータ収集
フロント環境	`qdata-ui/.env.*`、`qdata-ui/vite.config.js`	API プレフィックス、認証、プロキシ、ビルド

5.2 データベーススクリプト

sql/
├── mysql/
│   ├── initialization/       # 各バージョンの完全な初期化スクリプト
│   └── upgrade/              # 隣接バージョン間のアップグレードスクリプト
├── dm/
│   ├── initialization/       # DM の完全な初期化スクリプト
│   └── upgrade/              # DM アップグレードスクリプト
└── dolphinscheduler/
    └── upgrade/              # DolphinScheduler 関連のアップグレードスクリプト

5.3 Docker

ファイル/ディレクトリ	用途
`docker/docker-compose.yml`	完全環境の Compose 入口
`docker/docker-compose-base*.yml`	DB、Redis、RabbitMQ などの基盤
`docker/docker-compose-qdata*.yml`	qData サービス構成
`docker/docker-compose-dolphinscheduler.yml`	DolphinScheduler 構成
`docker/docker-compose-spark.yml`	Spark 構成
`docker/docker-compose-hadoop.yml`	Hadoop 関連コンポーネント
`docker/nginx/sites/qdata.conf`	静的ファイルと `/prod-api`・`/prod-ai` リバースプロキシ
`docker/qdata-server`	メインサービスイメージのビルド
`docker/qdata-service-quality`	品質サービスイメージのビルド
`docker/qdata-service-ai`	AI サービスイメージのビルド
`docker/dolphinscheduler`	設定、SQL、リソース、依存ファイル