発達

要件

• 1.26 以降を使用してください。モジュールは最小限のツールチェーンを固定します。
• Node.js 24 (を参照) .node-version).
• pnpm 9.12.2、フロントエンドと一致 packageManager 分野。
• インストーラーの総合リリース選択テスト用の jq。
• Docker はローカル開発の場合はオプションであり、コンテナーの検証の場合にのみ必要です。

すべての Make ターゲットをリポジトリ ルートから実行します。

コマンド

make clean データベースや依存関係は削除されません。 Air は、Go ソース、埋め込み SQL、 go.mod、 または go.sum 変化します。 Vite は、バックエンドを再起動せずに、HMR を通じてフロントエンド コードを更新します。使用 make dev WEB_PORT=5174 デフォルトのフロントエンド ポートが占有されている場合。

Makefile は Air v1.67.4 を実行します。 go run;最初の呼び出しでダウンロードしてビルドします。グローバルな Air インストールは必要なく、その依存関係はアプリケーション モジュールの外側に留まります。 .air.toml 一時的なビルドを無視したままにします bin/air/ また、再起動する前にサーバーが正常にシャットダウンされるまで最大 10 秒かかります。開発バックエンド ビルドは CGO を無効にし、運用ビルドと一致させ、macOS C リンカーのデプロイメント ターゲットの不一致を回避します。レーステストでは今でも CGO が使用されています。

構成

コピーする .env.example 活性化しません。シェルで変数をエクスポートするか、単一のコマンドに変数を指定します。

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

WEB_PORT フロントエンドポートのみを変更します。バックエンドはリッスンします 127.0.0.1:8080 デフォルトで、Vite も同じものを読み取ります SUBLANE_ADDR バックエンドとして。既存の Docker インスタンスまたは別のプロセスが 8080 を使用する場合は、空きバックエンド ポートを選択します。

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev Air または Vite を開始する前にバックエンド アドレスをチェックし、占有されている場合は失敗します。これにより、バインド失敗後に Air が実行されたままになっている間、新しいフロントエンドが無関係または古いバックエンドにサイレント接続することが防止されます。始動時 make dev-api そして make dev-web 別々に、同じものを渡します SUBLANE_ADDR 両方のコマンドに。

API プロキシはホスト (changeOrigin: false) 同一オリジン認証の場合。空のテスト データ ディレクトリから開始してセットアップを実行し、合成資格情報を使用してフォームから管理者を作成します。データベースを削除して動作中のインスタンスをリセットしないでください。

テスト

バックエンド テストには、環境検証、新規 SQLite 初期化、ワンタイム セットアップ/レース/ロールバック、メンバー ライフサイクル、ユーザーごとのセッション制限、無効化時の取り消し、ロールベースの API アクセス、オリジン/ボディ チェック、レート制限、準備エラー、および API/静的アセット境界が含まれます。フロントエンド テストでは、ロールを意識したルーティングとメニュー、メンバーの作成/ステータスの変更、セットアップの検証、ログイン エラー、ログアウトとアイデンティティ間キャッシュのクリア、有効期限、応答の検証、ナビゲーション、永続的なテーマ/言語の選択がカバーされます。合成フィクスチャと一時データベースのみを使用してください。

開発中に重点的なテストを実行します。

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

ブラウザーの検証では、デスクトップと狭いレイアウト、モバイル ナビゲーション、ダイレクト ルートのリロード、言語の変更、ライト/ダーク/システム テーマ、切断されたバックエンドをカバーする必要があります。単体テストはこれらのチェックに代わるものではありません。

Codex アダプターのテスト

アダプターのテストでは実際のアカウントは使用されません。運用エンドポイントの選択は固定されたままですが、トランスポート シームを通じてローカルの偽のアップストリームを注入します。インストールされた Codex CLI を分離された一時構成と合成モデル出力で実行するには、次の手順を実行します。

SUBLANE_TEST_CODEX=1 go test ./internal/server -run TestCodexCLIProtocol -count=1 -v

通常のテスト スイートは、このオプトイン外部クライアント テストをスキップします。開発者の既存の文書を読まないでください auth.json またはテスト用のキーチェーン。ライブプロバイダーとデスクトップの受け入れには、明示的に承認されたアカウントが必要です。それらの結果をプロトコルの適用範囲とは別に記録してください。

翻訳の追加

1. 英語キーを追加します web/src/locales/en.ts.
2. 同じキーを追加します web/src/locales/zh.ts および追加のすべてのロケール JSON 辞書。補間変数を保持し、各言語に必要な複数のカテゴリを提供します。
3. 使用 useTranslation() そして t() ARIA ラベルを含むコンポーネント内。
4. 走る pnpm --dir web typecheck デスクトップや狭い幅で長い翻訳を検査できます。アラビア語の右から左のレイアウトを確認し、コードと識別子を左から右に保ちます。

サポートされている言語は、英語、簡体字中国語、繁体字中国語、日本語、韓国語、スペイン語、フランス語、ドイツ語、ポルトガル語、ロシア語、アラビア語です。追加のアプリケーション辞書はオンデマンドでロードされます。ウェブサイトには英語のトピックが掲載されています content/docs/ と翻訳 content/<locale>/、一致するスラッグ、ローカライズされたナビゲーション、検索、マークダウン エクスポートを備えています。新しい翻訳は機械支援されており、ネイティブスピーカーによるレビューが必要です。

UI 設定はブラウザーに対してローカルです。これらはチーム設定ではないため、SQLite には書き込まれません。

HTTP ルートとデータベース クエリ

HTTP ルートは標準の chi を使用します net/http ハンドラー。リソースは独自に登録します Get, Head, Post、 そして Patch 内部のハンドラー Route グループ。管理者が保護するルーターに管理ルートを追加します。 internal/server/server.go。パブリック認証と個人キー ルートは明示的な例外です。セッション、ロール、およびゲートウェイベアラー認証はルーターレベルで実行されます Use、メソッドのエラーと不明なパス、および一致するエンドポイントを保護します。パブリックログイン/セットアップの使用 With 発信元の検証とスロットリング用。ハンドラーにメソッドまたはパスのディスパッチ スイッチを再導入しないでください。

各サルーターは JSON をインストールします NotFound そして MethodNotAllowed ハンドラー。 405 ハンドラーは次のように派生します。 Allow chiの登録ルートから Match、アプリケーションハンドラーを実行せずに。ヘルスチェック、システムステータス、および静的資産は HEAD を明示的に登録します。他の API は、宣言されたメソッドを保持します。 SPA はルートで GET/HEAD に対してのみ登録され、予約された API フォールバックを処理できません。

名前付きSQLクエリを書き込む internal/storage/queries/、ドメインごとにグループ化されています。 sqlc.yaml 統合初期化 SQL をスキーマとして使用し、 internal/storage/db/。走る make generate クエリ、スキーマ、またはジェネレーター構成を変更した後。 SQL と生成された Go を一緒にコミットします。生成されたファイルを手動で編集しないでください。ドメイン サービスは独自の検証とトランザクションを実行し、クエリをバインドします WithTx(tx)、行をパブリック応答タイプに変換します。

Makefile は SQL を v1.31.1 に固定し、実行します。 go run;最初の呼び出しでは、ツールがダウンロードされ、ビルドされます。 Go は、ジェネレーター用の互換性のあるツールチェーンをダウンロードする場合があります。生成にはグローバル SQL インストール、クラウド サービス、データベース接続は必要ありません。ジェネレーターの依存関係は、アプリケーションのモジュール依存関係グラフの外側に留まります。生成されたファイルはバージョン管理されるため、通常の Go ビルドと運用コンテナーには SQL は必要ありません。 make checkCIを含むが実行されます make generate-check 生成された古いコードを書き直さずに拒否します。

プレリリーススキーマの変更

001_schema.sql を含む internal/storage/migrations/ の既存ファイルを保持してください。構造変更は順序付きの追加マイグレーションで行い、internal/storage/queries/ の名前付きクエリを更新します。起動時にサポート対象のデータベースへ未適用分を実行します。001_settings.sql を含む初期の非互換構造は拒否されます。make generate、make generate-check、関連するストレージテストを実行してください。sqlc は構造を検証しますが、稼働中のデータベースを移行しません。

トラブルシューティング

• バックエンドのルートが返される frontend_not_built: 開発にはポート 5173 の Vite を使用するか、実行します make build そして始めます bin/sublane.
• フロントエンドに接続エラーが表示されます。 Go プロセスが実行中であり、Vite のプロキシが設定されたアドレスを指していることを確認します。
• ポートはすでに使用されています: WEB_PORT Viteを制御します。 SUBLANE_ADDR バックエンドとその Vite プロキシを制御します。たとえば、無料のバックエンド アドレスを選択します。 SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174。無関係なプロセスを終了させないでください。
• Go はツールチェーンをダウンロードします。 これは、インストールされている Go が より古い場合に予想されることです。 go.mod 必要。
• Docker ビルドが接続できません: Docker エンジンを始動してから実行します docker compose -f docker.compose.yaml config --quiet そして docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• 言語またはテーマは変更されたままになります。 設定は意図的にブラウザのローカル ストレージに保存されます。デフォルトに戻すには、環境設定でそれらを変更します。

メンテナンス

保つ go.sum そして web/pnpm-lock.yaml バージョン管理下にあります。依存関係のアップグレードを個別の変更として実行し、サードパーティのライセンス通知を保持します。ローカリゼーション、名前付け、アクセシビリティの変更を確認せずに、新しい Shadcn Admin ツリーをローカル コンポーネントにコピーしないでください。

パッケージングとリリースのチェック

見る 導入 コンテナの煙テストと リリース操作 タグトリガーパイプラインの場合。 make test 組み込みのノード リリース メタデータ テストと一時リポジトリ公開テストが含まれます。 make lint リリース/スモークスクリプトの構文をチェックします。 CI は、両方のネイティブ Linux アーキテクチャ上でコンテナを構築してテストし、その後、リリース ワークフローによって正確にテストされたイメージを公開し、バイナリを抽出します。プルリクエストのチェックではレジストリ認証情報は使用されません。