> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/ja/kaibumi/frontend-architecture/07-production-standards.md).

# 07 - 本番環境の標準

> \[!WARNING] **アーカイブ済みの設計記録です。** このページは完成済みの V2 フロントエンドより前の内容であり、 バージョン、パス、実装状況が古くなっている可能性があります。

> 所属: [フロントエンド・アーキテクチャ設計（索引）](/summerain/ja/kaibumi/frontend-architecture.md)

> 以下は最終的な本番成果物（`backend/web/`）に対する必須規則です。開発では署名されていない Vite 出力を使用し、SRI とリリースバージョンの対象外となるため、**開発・テスト段階は免除されます**。

## モジュール化と原子性

* JavaScript/CSS は、機能とルートに基づいて実用上可能な最小単位へ分割します（機能ベースのディレクトリ + React.lazy によるルート単位の分割。[02 アーキテクチャ](/summerain/ja/kaibumi/frontend-architecture/02-architecture.md)を参照）。単一の巨大なバンドルは禁止します。
* コンポーネント、フック、ユーティリティは、いずれも単一責任を持つ独立した再利用可能な単位にします。

## SRI 完全性（SHA512）+ SemVer バージョン

* 本番ビルドは、JavaScript/CSS の**すべての**成果物について **SHA512** 完全性ハッシュを計算し、`{ "<ファイル名>": { "version": "<semver>", "integrity": "sha512-..." } }` 形式の `backend/web/assets.manifest.json` を生成します。
* **バージョンは Semantic Versioning 2.0.0 に従います。** バージョンの粒度は**リリース単位**です。ビルド全体の SemVer（例: `1.0.0`。`package.json` の `version` から取得）を、そのビルドの全成果物に共通して付与し、各ファイルは個別の SRI ハッシュを記録します。将来モジュール単位のバージョンが必要になれば、マニフェストに `moduleVersion` フィールドを追加できます。
* **バージョン更新規則:** リリース前に `package.json` の `version` を手動で変更します。修正は `patch`、新機能は `minor`、互換性のない変更は `major` です。CI はその `version` を Git タグとマニフェストに使用します。バージョンを上げずにリリースしてはならず、成果物の `version` とタグは一致させます。現時点では changesets や standard-version などのツールは導入せず（YAGNI）、手動更新 + CI タグの運用とします。
* 今後クロスオリジンまたは外部ホストのリソースを導入する場合は、SRI を付けるか、使用自体を禁止します。現時点では該当するリソースはありません。次節を参照してください。
* **対象範囲（重要）:**
  * **エントリーポイントと静的成果物**（エントリー JavaScript/CSS、および `index.html` 内の `<link rel="modulepreload">`）-> `vite-plugin-sri3` が `index.html` に `integrity="sha512-..."` を注入し、ブラウザーが標準機能で検証します。
  * **動的バンドル**（React.lazy と `import()` で読み込むチャンク）-> ブラウザー標準の **`integrity` 機構は実行時の `import()` を対象にしません**。静的な `index.html` 要素への注入だけでは不十分です。そのため実装時に、動的 `import` の前に対象チャンクを取得し、`assets.manifest.json` の SHA512 と比較し、不一致なら実行を拒否して報告する**実行時完全性ガードを必ず追加します**。これは省略できない実装サブタスクです。
  * 代替として、Vite の modulepreload ポリフィルを書き換え、実行時に生成される preload リンクへ `integrity` を注入するプラグインを使用できます。ただし、遅延読み込みチャンクを実際に保護できることを検証する必要があります。
  * リスク背景: すべての成果物は同一オリジンで、CDN も使用しません（次節参照）。そのため SRI が主に防ぐ第三者配信元の改ざんリスクは低くなります。それでも「すべての成果物を検証する」ことが必須要件である以上、動的チャンクを免除せず、上記ガードで保護します。

## 外部リソースのローカル化

* **実行時にクロスオリジン/CDN リソースを参照することは禁止します。** 第三者依存はすべて Vite でローカル成果物へバンドルし、書体は Web フォントを使わずシステムフォントスタックを使用します。リモート画像やアイコンも使用しません。
* ビルド後、成果物に `https://` または `http://` 形式の外部リンクがないことを検証します。同一オリジンのバックエンド相対パス `/api` と `/i` のみ許可します。
* **唯一の管理された例外は CAPTCHA です。** 管理者がプロバイダーを有効化した場合（`captcha_provider ≠ none`。[03](/summerain/ja/kaibumi/frontend-architecture/03-features.md#pluggable-captcha-administrator-selected-default-none)を参照）に限り、そのプロバイダーの公式スクリプトを外部から読み込めます。reCAPTCHA、Turnstile、Geetest はセルフホストできません。既定の `none` は**外部リンクがゼロ**であり、本節の必須規則を完全に満たします。プロバイダーを有効化した場合も免除はそのプロバイダーだけに限定し、ビルド検証の許可リストへドメインを明示的に登録します。

## 変数と定数

* **マジック値を禁止します:** 数値上限、タイムアウト、ページサイズ、ストレージ単位、ルートパス、Query キー、保存キーなど、すべてのリテラルを `src/config/constants.ts` に集約します。定数は MDN の命名ガイドに従って **UPPER\_SNAKE\_CASE** でエクスポートし（[08 コーディング標準](/summerain/ja/kaibumi/frontend-architecture/08-coding-standards.md)と整合）、コンポーネント内の裸の数値・文字列を禁止します。
* **JavaScript/TypeScript 変数:** MDN の指針に従って camelCase を使用します。
* **CSS カスタムプロパティ:** CSS の仕様に従い kebab-case（例: `--coffee-bg`）を使用します。言語上の要件であり、camelCase 規則とは矛盾しません。
* **エンコーディング:** ソースファイルと成果物はすべて BOM なしの **UTF-8** とし、`index.html` に `<meta charset="UTF-8">` を含めます。

## HTML の最小化

* `index.html` のインライン JavaScript/CSS は**必要最小限**にします。唯一許可するインラインスクリプトは、保存されたテーマ設定を読み取って `.dark` を適用し、ちらつきを防ぐ短い事前描画ブートストラップです。それ以外はすべて外部バンドルに含めます。
* このスクリプトはバンドルの読み込み前に実行する必要があり、定数モジュールを `import` できません。そのため、localStorage キーを**唯一の管理された例外**とします。`config/constants.ts` の対応する定数と手動で同期し、コードコメントで関係を明記します。テーマキーは **`ic_theme`** に固定し、値は `light` または `dark` です。

## i18n（英語優先、多言語対応）

* 既定で `en-US` を使用し、`zh-CN` と `ja-JP` も提供します。コンポーネントは `react-i18next` の `t()` で文言を取得し、ユーザー向け文字列をハードコードしません（[04 テーマと UI](/summerain/ja/kaibumi/frontend-architecture/04-theme-and-ui.md)を参照）。
* 言語を切り替えてもコンポーネントコードを変更せずに済む、拡張可能な構造にします。

***

<- [06 テスト](/summerain/ja/kaibumi/frontend-architecture/06-testing.md) · [索引](/summerain/ja/kaibumi/frontend-architecture.md) · 次: [08 コーディング標準](/summerain/ja/kaibumi/frontend-architecture/08-coding-standards.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://summerain-1.gitbook.io/summerain/ja/kaibumi/frontend-architecture/07-production-standards.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.