RepoQ Answer Desk

Language: English | 한국어 | 日本語

社内コードベースを連携し、チーム単位の権限内で根拠付きの回答を生成する Repository Q&A コンソール

RepoQ は Azure DevOps または GitHub のリポジトリを同期し、ユーザーがプロジェクト/ブランチのスコープを選択してコードベースに質問できる社内 Q&A ツールです。バックエンドは Go の単一サーバー、フロントエンドは React/Vite で、本番デプロイ時は React のビルド成果物（web/dist）を Go バイナリに embed することで単一実行ファイルとして配布できます。

一言要約: CS / TS / 開発 / 運用組織が「どのブランチを基準に、どのコードを根拠に、なぜその答えになったのか」を追跡可能な形で問い、答えるためのツールです。

なぜ RepoQ なのか
ユースケース
主な機能
動作の仕組み
プロジェクト構成
必要要件
クイックスタート
初期セットアップの流れ
主要コンセプト
ローカル開発
設定値
ビルドとデプロイ
Docker
運用チェックリスト
API
フロントエンド / i18n 開発
テスト / 検証
トラブルシューティング
セキュリティ上の注意
関連ドキュメント

なぜ RepoQ なのか

汎用チャットボットに「うちのコードでこれってどうなってる?」と聞くのは速い反面、運用ではいくつもの問題があります。

問題	RepoQ のアプローチ
どのリポジトリ / ブランチを基準に答えたのか不明確	ユーザーがプロジェクトと質問基準ブランチを明示的に選択
権限のないユーザーが社内リポジトリ構造を覗ける	チームごとに質問可能なリポジトリ / ブランチを運用者が指定
根拠が無く CS/TS 応対に使いづらい	ファイルパス、行範囲、スニペットの出処を一緒に保存
トークンとコードが LLM 実行環境に過度に露出	PAT / トークンはサーバー側で管理し Codex 実行 env からは除去
質問品質を継続的に改善しづらい	質問履歴、失敗、フィードバック、満足度ダッシュボードを内蔵

RepoQ は「社内の全コードを誰でも検索できるチャットボット」ではなく、運用者が承認した範囲内でコードを根拠に回答する社内ナレッジ / サポートコンソールを目指しています。

ユースケース

1. CS / TS の顧客対応サポート

顧客からの問い合わせを受けた担当者が、製品ブランチを基準に質問します。

質問例:

「release/3.1 ブランチでログイン失敗時、どんなエラーメッセージが返る?」
「決済キャンセル要求が来たときの状態遷移を説明して。」
「このオプションが無効化される条件を、顧客に説明できる形でまとめて。」

ポイント:

回答だけでなく、関連するファイル / 行の根拠も確認できます。
チームごとの応答ガイドラインを差し込むことで、顧客に渡せるトーンを保てます。
Q&A 結果に「役立った / 改善が必要」のフィードバックを残し、品質を継続追跡できます。

2. リリース / ブランチ単位の機能確認

同じ機能でも main, develop, release/*, hotfix/* で実装が異なることがあります。RepoQ は質問時に基準ブランチを必ず選ばせるので、「リリース予定ブランチ基準」の回答を得るのに向いています。

質問例:

「release/4.0 で新しい認証フローが有効になる条件を教えて。」
「hotfix ブランチに特定の例外処理が入っているか確認して。」
「この設定値の既定値はどのファイルで定義されている?」

3. 新メンバーのオンボーディング

新たに入った開発者 / 運用者が、リポジトリを直接探検する前に全体像を素早く掴めます。

質問例:

「管理者ログインのフローをファイル単位で説明して。」
「サーバーで質問の回答生成はどんな順序で実行される?」
「ユーザー権限のチェックはどの層で行われている?」

4. 運用コンソール / 管理機能の理解

RepoQ 自体も、チーム / ユーザー / リポジトリ / ブランチ / 質問履歴を管理するコンソールを備えています。社内運用者は次の流れでシステムを管理します。

Provider 接続を保存
リポジトリ / ブランチを同期
Q&A 対象リポジトリを有効化
チーム単位でアクセス可能ブランチを指定
ユーザー作成 / チーム配属
質問履歴 / フィードバックを確認

5. 監査可能な社内 AI 導入

RepoQ は質問と回答結果を DB に保存します。個人用チャットボットよりも運用上の追跡性が高いです。

誰がどんな質問をしたか
どんな回答が生成されたか
どの出処が使われたか
失敗 / ブロック / 完了したか
役に立ったとユーザーが評価したか

6. 使うべきでないケース

RepoQ は次の用途には向きません。

権限のないリポジトリを迂回して閲覧する用途
シークレット / トークン / 個人情報を抽出する用途
大規模なコード改修を自動実行するエージェント
承認なく外部システムへコードを送出するパイプライン

サーバー側に危険な要求のブロックルールがあり、Codex 実行は read-only 性質で設計されています。

主な機能

ソースプロバイダ連携: Azure DevOps / GitHub のリポジトリ・ブランチ一覧を同期
リポジトリ運用管理: Q&A 対象の有効化、include/exclude パス、リポジトリ別検索ガイドの管理
チーム / 権限管理: 組織ツリー、メンバー、チーム単位の質問可能リポジトリ・ブランチ指定
ユーザー / 管理者ロール: 一般ユーザーは質問、管理者は運用コンソール
コード Q&A: 選択したプロジェクト / ブランチのワークスペースを同期し、Codex CLI で回答生成
根拠付き回答: 検索したファイルスニペットと出処を回答とともに保存
履歴 / フィードバック: 質問ログ、満足 / 改善要求、ダッシュボード統計
多言語 UI: 日本語 / 英語 / 韓国語
単一バイナリ配布: go build -tags embed で web/dist をバイナリに同梱
ローカル / 本番分離: -dev, -insecure-cookie, Secure cookie, CSRF, セッション TTL の分離

動作の仕組み

flowchart LR
  User[User / Admin Browser] -->|Cookie session + CSRF| Go[Go HTTP Server]
  Go --> SQLite[(SQLite DB)]
  Go --> Source[Azure DevOps / GitHub]
  Go --> Workspace[.repoq-workspaces]
  Workspace --> Retrieval[Snippet Retrieval]
  Retrieval --> Codex[Codex CLI]
  Codex --> Go
  Go -->|SSE answer stream| User

  Admin[Admin Console] -->|Provider token save| Go
  Go -->|PAT/Token encrypted| SQLite

質問処理フロー:

ユーザーがプロジェクト / ブランチと質問を送信。
サーバーが qa_runs に質問履歴レコードを作成。
危険なパターンであれば Codex 呼び出し前にブロック。
チーム / ブランチの権限を元に対象リポジトリを算出。
.repoq-workspaces/ 配下にリポジトリ / ブランチのワークスペースを同期。
ローカルワークスペースから関連ファイルのスニペットを取得。
根拠が不足する場合は Azure Code Search にフォールバック。
read-only 性質の実行環境で Codex CLI を呼び出し回答を生成。
回答 / 出処 / ステータス / フィードバックを DB に保存。

プロジェクト構成

repoq/
├─ api/                         # Go バックエンドパッケージ
│  ├─ server.go                 # CLI flags / env のロードとサーバー起動
│  ├─ handler*.go               # HTTP ルーティング / API / 認証 / セキュリティ
│  ├─ store*.go                 # SQLite/GORM ストア (auth / catalog / groups / runs)
│  ├─ source_*_service.go       # Azure / GitHub の同期とブランチ更新
│  ├─ workspace.go              # 質問時のローカルワークスペース同期
│  ├─ retrieval.go              # 根拠スニペット取得
│  ├─ codex_runner.go           # Codex CLI 実行
│  ├─ crypto.go                 # PAT/Token の AES-GCM 暗号化
│  └─ guard.go                  # 危険要求のブロックルール
├─ web/                         # React / Vite フロントエンド
│  ├─ src/main.tsx              # アプリ Shell / ルーティング起点
│  ├─ src/app/AppProviders.tsx  # I18n / Dialog / Route / User Provider 構築
│  ├─ src/api.ts                # API / SSE クライアント
│  ├─ src/i18n/                 # i18n provider / runtime / locales
│  ├─ src/features/             # Q&A / Dashboard / Admin 画面
│  └─ src/styles/               # CSS トークン / レイアウト / レスポンシブ
├─ main.go                      # ルート実行エントリポイント (embed 前提)
├─ web_dev.go                   # 既定ビルド: web/dist をディスクから配信
├─ web_embed.go                 # embed タグビルド: web/dist をバイナリ同梱
├─ Makefile
├─ Dockerfile
├─ go.mod / go.sum
└─ README.md

必要要件

項目	推奨バージョン / 条件	必要な理由
Go	1.25+	バックエンドのビルド / 実行
Node.js	22+	React / Vite ビルド
npm	10.x	lockfile ベースのインストール
Git	PATH に登録	リポジトリの clone / fetch
Codex CLI	PATH に登録	質問の回答生成
Azure DevOps PAT または GitHub Token	読み取り権限が必要	リポジトリ / ブランチ / コードの参照

トークン権限ガイド

Azure DevOps: プロジェクト / リポジトリ / コード / ブランチの読み取り権限が必要。Azure Code Search フォールバックを使うなら Code Search API へのアクセス権も必要です。
GitHub: public リポジトリのみなら public read、private まで使うなら private 読み取り権限が必要。
トークンは SQLite DB に暗号化して保存されます。DB と暗号化キーをセットでバックアップ / 保護してください。

クイックスタート

PowerShell ベースで記載しています。ローカル HTTP でブラウザログインがそのまま通るように -dev -insecure-cookie を付けます。

# 1) フロントエンド依存のインストール + ビルド
cd web
npm ci
npm run build
cd ..

# 2) バックエンド + フロントエンド統合サーバーを実行
# -dev: ローカル便宜モード。admin/admin ブートストラップを許可
# -insecure-cookie: HTTP ローカルで Secure cookie を無効化
# 既定ポートは :8080
go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

ブラウザでアクセス:

アプリ: http://127.0.0.1:8080/
管理コンソール: http://127.0.0.1:8080/admin
ヘルスチェック: http://127.0.0.1:8080/health

ローカル dev モードのブートストラップアカウント:

既定: admin / admin
共有 / 本番では -dev, -insecure-cookie, admin/admin を使わないでください。

本番モードで ADMIN_PASSWORD が空または admin のままだと、初回起動時にランダムな管理者パスワードを stdout に出力します。表示されたパスワードでログインし、すぐに変更してください。

別ポートにする場合は -addr を変えるだけです（例: 18080）。

go run . -addr 127.0.0.1:18080 -dev -insecure-cookie
# アクセス: http://127.0.0.1:18080/

別ポートで Vite dev server を併用する場合は VITE_API_BASE でバックエンド URL を合わせてください（ローカル開発 § 2 参照）。

初期セットアップの流れ

初回起動時は次の順番で進めれば OK です。管理者でログインすると Q&A / ダッシュボード / ソース管理の空状態画面に次へ進む CTA ボタンが出るので、その流れに沿って進めることもできます（例: Q&A 空状態の [ソースを接続する] から「システム設定」タブへジャンプ）。

flowchart TD
  A[ログイン] --> B[システム設定: Provider 接続]
  B --> C[リポジトリ同期]
  C --> D[ソース管理: RepoQ で使うリポジトリを有効化]
  D --> E[アクセス権限: チーム / ブランチ権限の指定]
  E --> F[ユーザー作成 + チーム配属]
  F --> G[Q&A でプロジェクト / ブランチを選んで質問]

ログイン
- /login で管理者アカウントでログイン。
システム設定
- /admin → システム設定
- Provider を Azure DevOps または GitHub から選択
- Organization / Owner と PAT / Token を入力
- 「接続を保存」をクリック
- 「リポジトリを同期」をクリック
ソース管理
- /admin → ソース管理
- Q&A 対象のリポジトリを有効化
- 必要に応じて include / exclude パスを設定
- リポジトリ別の検索ガイドを記入
アクセス権限
- /admin → アクセス権限
- チームを作りメンバーを配属
- チームごとに質問可能なリポジトリ / ブランチを指定
ユーザー管理
- /admin → ユーザー
- 一般ユーザーまたは管理者を作成
質問する
- / でプロジェクトとブランチを選んで質問

主要コンセプト

Provider 接続

Provider は RepoQ がソース一覧とファイルを読み出す外部のコードホスティングです。

サポート対象:

Azure DevOps
GitHub

接続情報は azure_connections テーブルに保存され、PAT/Token は REPOQ_SECRET_KEY または .repoq.key をキーに暗号化されます。

ソース管理

ソース管理は「このリポジトリを RepoQ Q&A の候補にするか」を決めるステップです。

RepoQ で使う を OFF にしたリポジトリは質問検索範囲から除外されます。
有効化しただけではユーザーへ公開されません。
ユーザー画面に出すにはチームのアクセス権限でブランチを許可する必要があります。

アクセス権限

アクセス権限は「どのチームがどのリポジトリのどのブランチを質問できるか」を決めます。

ユーザーは所属チームに許可されたプロジェクト / ブランチのみ見えます。
管理者は運用目的でより広い範囲が見られます。
ブランチ権限のないリポジトリは Q&A 選択肢に出ません。

チーム別回答ガイドライン

チーム別回答ガイドラインは Codex プロンプトに併せて差し込まれる運用指示です。

例:

- 顧客にそのまま渡せるトーンで先に要約
- セキュリティ / 決済の話題は断定でなく確認手順で示す
- 根拠ファイルとブランチを必ず明記

リポジトリ別検索ガイド

リポジトリ別検索ガイドは「このリポジトリをどう読むべきか」のドメイン文脈です。

例:

- src/legacy 配下は旧バージョン互換用
- 決済ステータスは payment/domain/status.go を最優先で見る
- 顧客向けメッセージは i18n/messages 配下で管理

`repoq_sid` localStorage 値

ブラウザの localStorage に入る repoq_sid は認証値ではありません。

用途: 質問履歴の session_id グルーピング
生成場所: ブラウザクライアント
セキュリティ的意味: 無し。漏れてもログインセッションは奪われない
認証は repoq_session HttpOnly cookie で処理されます

ローカル開発

1. 統合サーバー方式（推奨）

React を一度ビルドし、Go サーバーが web/dist を配信します。本番に最も近い構成です。

cd web
npm ci
npm run build
cd ..

go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

フロントを変更したら再ビルドが必要です。

cd web
npm run build
cd ..

2. Vite HMR + Go API を別プロセスで実行

フロント HMR が必要なときに使います。

ターミナル A — API サーバー:

go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

ターミナル B — Vite dev server:

cd web
npm ci
npm run dev

アクセス:

Vite: http://127.0.0.1:5173/
API: http://127.0.0.1:8080/

web/vite.config.ts の proxy は既定で http://localhost:8080 を見ます。API のポートを変えるなら次のように env で指定します。

cd web
$env:VITE_API_BASE = "http://127.0.0.1:18080"
npm run dev

設定値

CLI flag が env より優先されます。

Flag	Env	既定値	説明
`-addr`	-	`:8080`	HTTP リッスンアドレス
`-dev`	-	`false`	ローカル開発便宜モード。`admin/admin` ブートストラップ許可、Secure cookie 無効化
`-insecure-cookie`	-	`false`	HTTP ローカルで auth/csrf cookie の Secure フラグを外す
`-name`	`APP_NAME`	`RepoQ`	UI / ログに表示するアプリ名
`-db`	`REPOQ_DB_PATH`	`repoq.db`	SQLite DB のパス
`-azdo-org`	`AZDO_ORG`	空	起動時に seed する Azure DevOps organization
`-azdo-pat`	`AZDO_PAT`	空	起動時に seed する Azure DevOps PAT
`-codex-model`	`CODEX_MODEL`	`gpt-5.5`	Codex CLI に渡すモデル
`-codex-reasoning-effort`	`CODEX_REASONING_EFFORT`	`xhigh`	Codex の reasoning effort
`-codex-timeout`	`CODEX_TIMEOUT`	`2m`	質問 1 件の Codex タイムアウト。例: `120s`, `2m`
`-max-snippets`	`REPOQ_MAX_SNIPPETS`	`10`	回答生成に使う最大根拠スニペット数
`-max-context-chars`	`REPOQ_MAX_CONTEXT_CHARS`	`90000`	Codex に渡す最大根拠文字数
`-workspace-cache-dir`	`REPOQ_WORKSPACE_CACHE_DIR`	`.repoq-workspaces`	リポジトリワークスペースのキャッシュ先
`-workspace-max-files`	`REPOQ_WORKSPACE_MAX_FILES`	`800`	ワークスペースに展開する最大ファイル数
`-workspace-max-mb`	`REPOQ_WORKSPACE_MAX_MB`	`80`	ワークスペースの最大合計サイズ (MB)
`-workspace-max-file-kb`	`REPOQ_WORKSPACE_MAX_FILE_KB`	`512`	単一ファイルの最大サイズ (KB)

追加 env:

Env	既定値	説明
`ADMIN_USERNAME`	`admin`	ユーザーが居ないときに作る管理者の ID
`ADMIN_PASSWORD`	dev: `admin`, prod: ランダム生成	ユーザーが居ないときに作る管理者のパスワード
`ADMIN_RESET`	空	`1` のとき次回起動でブートストラップ admin を再 seed し既存セッションを無効化
`REPOQ_SECRET_KEY`	`.repoq.key` ファイル	PAT/Token の AES-GCM 暗号化キー。本番では明示推奨
`REPOQ_SESSION_TTL`	`12h`	一般ユーザーセッション TTL
`REPOQ_MIN_PASSWORD_LENGTH`	`12`	ユーザーパスワードの最小長。強化可
`REPOQ_WORKSPACE_MARKER_TTL`	`5m`	ワークスペースの鮮度マーカー TTL
`REPOQ_SNIPPET_MAX_CHARS`	`9000`	スニペット 1 つの最大文字数
`CODEX_ALLOW_OPENAI_API_KEY`	空	`1` で Codex 実行 env に `OPENAI_API_KEY` を通す

セキュリティ上、Codex 実行 env からは AZDO_PAT, AZURE_DEVOPS_EXT_PAT が除去されます。OPENAI_API_KEY も既定で除去され、必要なときだけ CODEX_ALLOW_OPENAI_API_KEY=1 で許可します。

暗号化キーの運用

RepoQ は Provider PAT/Token を保存時に AES-GCM で暗号化します。

優先順位:

REPOQ_SECRET_KEY env
.repoq.key ファイル

本番推奨:

$env:REPOQ_SECRET_KEY = "change-this-to-a-long-random-secret-at-least-32-chars"

注意:

暗号化済み PAT は同じキーが無いと復号できません。
DB だけバックアップしてキーを失うと、Provider 接続を再保存する必要があります。
.repoq.key を使う場合は DB と同様にキーファイルもバックアップ / 保護対象に含めてください。

ビルドとデプロイ

開発用バイナリ

go build だけでは React は同梱されません。実行ディレクトリの隣に web/dist が必要です。

cd web
npm ci
npm run build
cd ..

go build -o repoq.exe .
.\repoq.exe -addr 127.0.0.1:8080 -dev -insecure-cookie

単一バイナリビルド（推奨配布方式）

embed ビルドタグで web/dist を Go バイナリに同梱します。

cd web
npm ci
npm run build
cd ..

go test ./...
go build -tags embed -trimpath -ldflags="-s -w" -o repoq.exe .

バージョン埋め込み付き:

$version = git rev-parse --short HEAD
go build -tags embed -trimpath -ldflags="-s -w -X repoq/api.Version=$version" -o repoq.exe .

実行:

$env:REPOQ_SECRET_KEY = "change-this-to-a-long-random-secret-at-least-32-chars"
.\repoq.exe -addr :8080 -db .\data\repoq.db -workspace-cache-dir .\data\.repoq-workspaces

注意:

バイナリに同梱されるのは React の静的ファイルだけです。
SQLite DB, .repoq-workspaces/, ログ / ランタイムファイルは別途生成されます。
デプロイ先サーバーには git と codex が PATH に必要です。
本番では TLS reverse proxy の背後に置き -insecure-cookie を使わない構成を推奨。

Linux 向けクロスビルド例

PowerShell:

cd web
npm ci
npm run build
cd ..

$env:GOOS = "linux"
$env:GOARCH = "amd64"
go build -tags embed -trimpath -ldflags="-s -w" -o repoq-linux-amd64 .
Remove-Item Env:\GOOS
Remove-Item Env:\GOARCH

Makefile ターゲット

ターゲット	説明
`make build`	git SHA をバージョンに含めた embed ビルド (`bin/repoq`)
`make test`	`go test ./...`
`make test-race`	`go test -race ./...`
`make lint`	`golangci-lint run ./...`
`make vet`	`go vet ./...`
`make tidy`	`go mod tidy`
`make fmt`	`gofmt -s -w .`
`make dev`	`go run ./ -dev -insecure-cookie`
`make run`	`go run ./`
`make mod-why`	`go mod why -m all`

Docker

現在の Dockerfile は ビルド前に web/dist が既に存在することを前提としています。

cd web
npm ci
npm run build
cd ..

$version = git rev-parse --short HEAD
docker build --build-arg VERSION=$version -t repoq:dev .

実行例:

docker volume create repoq-data

docker run --rm -p 8080:8080 `
  -v repoq-data:/data `
  -e REPOQ_SECRET_KEY="change-this-to-a-long-random-secret-at-least-32-chars" `
  repoq:dev `
  -addr :8080 `
  -db /data/repoq.db `
  -workspace-cache-dir /data/.repoq-workspaces

重要:

現行のランタイムイメージは distroless ベースのため git, codex は同梱されていません。
UI / API のスモークテスト用途には使えますが、コンテナ内で Q&A まで行うには git と codex を含めたランタイムイメージへの拡張が必要です。
単一ホスト内デプロイは現状 embed バイナリ直接実行が最もシンプルです。

運用チェックリスト

初回デプロイ前

web/dist を最新ビルドで生成したか?
go test ./... と npm test がパスしたか?
本番から -dev, -insecure-cookie を外したか?
REPOQ_SECRET_KEY を安全な値に設定したか?
サーバー PATH で git, codex を実行できるか?
DB と .repoq-workspaces を本番データディレクトリに分離したか?
TLS reverse proxy または社内 HTTPS の背後に配置したか?
初期 admin パスワードを変更したか?

バックアップ対象

パス / 値	重要度	説明
`repoq.db`	必須	ユーザー / チーム / 権限 / Provider 接続 / 質問履歴
`repoq.db-wal`, `repoq.db-shm`	推奨	SQLite WAL 使用中なら一緒にバックアップ推奨
`REPOQ_SECRET_KEY` または `.repoq.key`	必須	暗号化された PAT/Token の復号鍵
`.repoq-workspaces/`	任意	リポジトリキャッシュ。削除しても再同期可能
実行バイナリ	推奨	デプロイバージョンの再現

DB 初期化（開発用）

サーバーを止めてから削除します。

Get-NetTCPConnection -State Listen -LocalPort 8080 -ErrorAction SilentlyContinue |
  ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Remove-Item -LiteralPath .\repoq.db, .\repoq.db-shm, .\repoq.db-wal -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath .\.repoq-workspaces -Recurse -Force -ErrorAction SilentlyContinue

管理者パスワード復旧

管理者パスワードを失った場合は、一度だけ ADMIN_RESET=1 でブートストラップ admin を再 seed します。

$env:ADMIN_USERNAME = "admin"
$env:ADMIN_PASSWORD = "new-strong-password-1234"
$env:ADMIN_RESET = "1"
.\repoq.exe -addr :8080 -db .\data\repoq.db
Remove-Item Env:\ADMIN_RESET

ADMIN_RESET=1 を付けたまま起動し続けると毎回パスワードがリセットされる可能性があるので、復旧後は必ず外してください。

主な画面

パス	権限	説明
`/login`	公開	ログイン
`/`	ログイン必須	Q&A メイン画面
`/dashboard`	ログイン必須	満足度 / 利用統計ダッシュボード
`/admin`	管理者	運用コンソール
`/logs`	管理者	管理者ログ画面の alias
`/health`	公開	ヘルスチェック JSON

API

認証は repoq_session HttpOnly cookie ベースです。フロントエンドは same-origin credential で呼び出します。

Mutating リクエスト (POST, PUT, PATCH, DELETE) には CSRF が必要です。

CSRF cookie: qa_csrf
CSRF header: X-CSRF-Token

Method	Path	権限	説明
`POST`	`/login`	公開	ログイン、セッション / CSRF cookie 発行
`POST`	`/logout`	ログイン	ログアウト
`GET`	`/api/me`	ログイン	現在のユーザー
`PUT`	`/api/me/password`	ログイン	自分のパスワード変更
`GET`	`/api/dashboard-summary`	ログイン	ダッシュボード統計
`GET`	`/api/repositories/summary`	ログイン	質問可能リポジトリのサマリ
`GET`	`/api/question-access`	ログイン	ユーザーから見えるプロジェクト / ブランチ
`POST`	`/ask`	ログイン	SSE で質問ストリーミング
`POST`	`/api/questions`	ログイン	`/ask` と同等
`PATCH`	`/api/runs/{id}/feedback`	ログイン	質問フィードバックを送信
`GET`	`/admin/api/connection`	管理者	ソース接続を取得
`PUT`	`/admin/api/connection`	管理者	ソース接続を保存
`POST`	`/admin/api/sync`	管理者	リポジトリ / ブランチ同期
`GET`	`/admin/api/projects`	管理者	プロジェクト一覧
`GET`	`/admin/api/repositories`	管理者	リポジトリ一覧
`PATCH`	`/admin/api/repositories/{id}`	管理者	有効化 / パス / ガイドの更新
`GET`	`/admin/api/repositories/{id}/branches`	管理者	リポジトリのブランチ取得 / 更新
`GET`	`/admin/api/groups`	管理者	チーム一覧
`POST`	`/admin/api/groups`	管理者	チーム作成
`PATCH`	`/admin/api/groups/{id}`	管理者	チーム情報 / 回答ガイド更新
`DELETE`	`/admin/api/groups/{id}`	管理者	チーム削除
`PUT`	`/admin/api/groups/{id}/repository-branches`	管理者	チーム単位のリポジトリ / ブランチ権限保存
`GET`	`/admin/api/users`	管理者	ユーザー一覧
`POST`	`/admin/api/users`	管理者	ユーザー作成
`PUT`	`/admin/api/users/{id}/groups`	管理者	ユーザーのチーム配属
`GET`	`/admin/api/runs`	管理者	質問履歴のページング取得
`GET`	`/admin/api/feedback-summary`	管理者	フィードバック要約

API 呼び出し例

PowerShell でログイン:

$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession

Invoke-RestMethod `
  -Uri http://127.0.0.1:8080/login `
  -Method POST `
  -WebSession $session `
  -ContentType "application/json" `
  -Body '{"username":"admin","password":"admin"}'

Invoke-RestMethod -Uri http://127.0.0.1:8080/api/me -WebSession $session

CSRF が必要なリクエスト:

$csrf = ($session.Cookies.GetCookies("http://127.0.0.1:8080") | Where-Object { $_.Name -eq "qa_csrf" }).Value

Invoke-RestMethod `
  -Uri http://127.0.0.1:8080/logout `
  -Method POST `
  -WebSession $session `
  -Headers @{ "X-CSRF-Token" = $csrf }

質問 payload:

{
  "question": "このリポジトリのログインフローを説明して",
  "session_id": "browser-generated-uuid",
  "language": "ja",
  "project_id": 1,
  "branch_name": "main"
}

応答は Server-Sent Events で status, sources, text, error, done イベントが流れます。

フロントエンド / i18n 開発

アプリ Provider の構築は web/src/app/AppProviders.tsx。
i18n Provider は web/src/i18n/provider.tsx。
i18n の public エクスポートは web/src/i18n/index.ts。
サポート言語: ko, en, ja。
選択中言語は localStorage repoq_language に保存。
質問セッション識別用ブラウザ UUID は localStorage repoq_sid に保存。
翻訳キー検証は npm run build 前に web/scripts/check-translations.cjs が実行。

Provider 構造:

<I18nProvider>
  <DialogProvider>
    <RouteProvider>
      <UserProvider>{children}</UserProvider>
    </RouteProvider>
  </DialogProvider>
</I18nProvider>

テスト / 検証

バックエンド

go test ./...
go test -race ./...
go vet ./...

フロントエンド

cd web
npm ci
npm test
npm run lint
npm run build
cd ..

E2E

Playwright と Chromium はインストール済みで、ゴールデンパス用スペック（web/tests/e2e/login.spec.ts）がスケルトンとして存在します。現在は test.describe.skip でゲートされているため、実際に走らせるにはバックエンドを起動して .skip を外してください。

ターミナル A — API サーバー:

go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

ターミナル B — Playwright:

cd web
npm run test:e2e

Embed バイナリの検証

cd web
npm ci
npm run build
cd ..

go build -tags embed -o repoq-check.exe .
.\repoq-check.exe -addr 127.0.0.1:18080 -dev -insecure-cookie

ヘルスチェック:

Invoke-RestMethod http://127.0.0.1:18080/health | ConvertTo-Json -Depth 5

正常時は status: ok, codex_available: true/false, source_configured: true/false などが返ります。

トラブルシューティング

ローカルでログイン後にログイン画面に戻る

HTTP ローカルなのに Secure cookie が有効になっている可能性が高いです。

go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

本番では HTTPS の背後で Secure cookie を維持する構成を推奨。

`React app is not embedded...` または空白画面

Go サーバーが読むべき web/dist/index.html がありません。

cd web
npm ci
npm run build
cd ..
go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

単一バイナリでは必ず go build -tags embed を使います。

Vite で API が 404 / proxy 失敗

既定 proxy は localhost:8080 です。バックエンドのポートが違うなら VITE_API_BASE を指定します。

$env:VITE_API_BASE = "http://127.0.0.1:18080"
npm run dev

`Codex CLI missing`

サーバープロセスの PATH に codex がありません。

Get-Command codex
codex --version

Codex CLI をインストール / ログインしてからサーバーを再起動。

`source connection is not configured`

管理コンソールで Provider / Organization / PAT を保存した後、「リポジトリを同期」まで実行してください。

質問範囲が空

次のいずれかが欠けています。

リポジトリが有効化されている
チームにメンバーが配属されている
チームにリポジトリ / ブランチ権限が指定されている

管理者は有効化されたリポジトリ / ブランチを基にもっと広く見られます。

ブランチが見えない

「リポジトリを同期」を再実行。
リポジトリ詳細のブランチ更新 API が provider token で到達できるか確認。
GitHub の private リポジトリは token のスコープを再確認。

根拠が見つからない

質問キーワードをより具体的に。
include / exclude パスが狭すぎないか確認。
.repoq-workspaces/ を消して再質問し、ワークスペースを作り直す。
Azure DevOps なら Code Search 権限 / 利用可否を確認。

暗号化された PAT を復号できない

REPOQ_SECRET_KEY または .repoq.key が変わっている可能性があります。

対応:

元のキーを復元する。
不可ならシステム設定から Provider Token を再保存する。

セキュリティ上の注意

既定の admin/admin はローカル確認用です。本番でそのまま使わないでください。
本番では -dev, -insecure-cookie を使わないでください。
PAT/Token は DB に暗号化保存されます。DB ファイルと暗号化キーをセットで保護してください。
Codex は read-only 性質で呼ばれますが、解析対象のワークスペースには社内コードが入ります。サーバーへのアクセス権限を制限してください。
危険なコードダンプ / シークレット抽出 / 外部送出の要求はサーバー側で事前にブロックされます。とはいえ社内セキュリティ方針に沿ってログ / DB を管理してください。
OPENAI_API_KEY は既定で Codex 実行 env から除去されます。必要なときのみ CODEX_ALLOW_OPENAI_API_KEY=1 を使ってください。
質問 / 回答 / 根拠スニペットは DB に保存されるため、個人情報や顧客の機密を質問本文に直接書かない運用ポリシーが必要です。

依存関係

Package	Version	採用理由
`gorm.io/gorm`	v1.31.x	SQL ORM。SQLite 中心ながら driver 入れ替え余地あり
`github.com/glebarez/sqlite`	v1.11.0	Pure-Go SQLite ドライバ。Windows でも CGO 不要でクロスビルド可
`golang.org/x/crypto`	v0.50.x	bcrypt パスワードハッシュ、暗号ユーティリティ
`react` / `react-dom`	v19.x	UI ランタイム
`vite`	v7.x	フロントエンドのビルド / dev サーバー
`i18next` / `react-i18next`	lockfile 最新	多言語 UI Provider

SQLite ドライバは mattn/go-sqlite3 ではなく github.com/glebarez/sqlite を使用しています。CGO 無しで Windows / Linux のクロスビルドが容易で、社内シングルテナントツールには十分なスループットです。SQLite の writer 直列化特性のため、コネクションプールは意図的に MaxOpenConns(1) に絞っています。

主要コマンドのまとめ

ローカル実行:

cd web
npm ci
npm run build
cd ..
go run . -addr 127.0.0.1:8080 -dev -insecure-cookie

単一バイナリ:

cd web
npm ci
npm run build
cd ..
go build -tags embed -trimpath -ldflags="-s -w" -o repoq.exe .

本番起動:

$env:REPOQ_SECRET_KEY = "change-this-to-a-long-random-secret-at-least-32-chars"
.\repoq.exe -addr :8080 -db .\data\repoq.db -workspace-cache-dir .\data\.repoq-workspaces

FilesExpand file tree

README.ja.md

Latest commit

History

README.ja.md

File metadata and controls

RepoQ Answer Desk

目次

なぜ RepoQ なのか

ユースケース

1. CS / TS の顧客対応サポート

2. リリース / ブランチ単位の機能確認

3. 新メンバーのオンボーディング

4. 運用コンソール / 管理機能の理解

5. 監査可能な社内 AI 導入

6. 使うべきでないケース

主な機能

動作の仕組み

プロジェクト構成

必要要件

トークン権限ガイド

クイックスタート

初期セットアップの流れ

主要コンセプト

Provider 接続

ソース管理

アクセス権限

チーム別回答ガイドライン

リポジトリ別検索ガイド

repoq_sid localStorage 値

ローカル開発

1. 統合サーバー方式（推奨）

2. Vite HMR + Go API を別プロセスで実行

設定値

暗号化キーの運用

ビルドとデプロイ

開発用バイナリ

単一バイナリビルド（推奨配布方式）

Linux 向けクロスビルド例

Makefile ターゲット

Docker

運用チェックリスト

初回デプロイ前

バックアップ対象

DB 初期化（開発用）

管理者パスワード復旧

主な画面

API

API 呼び出し例

フロントエンド / i18n 開発

テスト / 検証

バックエンド

フロントエンド

E2E

Embed バイナリの検証

トラブルシューティング

ローカルでログイン後にログイン画面に戻る

React app is not embedded... または空白画面

Vite で API が 404 / proxy 失敗

Codex CLI missing

source connection is not configured

質問範囲が空

ブランチが見えない

根拠が見つからない

暗号化された PAT を復号できない

セキュリティ上の注意

依存関係

主要コマンドのまとめ

関連ドキュメント

`repoq_sid` localStorage 値

`React app is not embedded...` または空白画面

`Codex CLI missing`

`source connection is not configured`