メッセージ管理機能方針の策定

.github/CONTRIBUTING.md

@@ -24,7 +24,7 @@ Issue や Discussions に対して追加の説明や質問がある場合は、
 
 これらでは解決できない場合、 Discussions の [Q&A](https://github.com/AlesInfiny/maia/discussions/categories/05-q-a) より質問をお寄せください。
 質問を投稿する場合、直面していることについてできる限り多くの情報を提供してください。
-可能な限りスピーディーに対応いたします。
+可能な限り迅速に対応いたします。
 ただし、質問に対する回答が常に得られることを期待しないでください。
 
 ## 本プロジェクトに対するコントリビュート

.textlintrc

@@ -358,6 +358,7 @@
         "状態",
         "ジョッキー",
         "ジレンマ",
+        "迅速",
         "スキャナー",
         "スキーマ",
         "スクエア",
@@ -377,7 +378,6 @@
         "ストーブ",
         "ストーリー",
         "スパイウェア",
-        "スピーディー",
         "スピード",
         "スペイン",
         "スポーツ",

documents/contents/app-architecture/client-side-rendering/frontend-application/index.md

@@ -155,13 +155,17 @@ Vue.js プロジェクトのフォルダー構成は、ブランクプロジェ
 ├─ cypress/ ------------------ cypress による E2E テストに関するファイルを格納します。
 ├─ public/ ------------------- メディアファイルや favicon など静的な資産を格納します。
 ├─ src/
+│  ├─ api-client/ ------------ API クライアントの設定ファイルを格納します。
 │  ├─ assets/ ---------------- コードや動的ファイルが必要とするCSSや画像などのアセットを格納します。
 │  ├─ components/ ------------ 単体で自己完結している再利用性の高い vue コンポーネントなどを格納します。
 │  ├─ config/ ---------------- 設定ファイルを格納します。
 │  ├─ generated/ ------------- 自動生成されたファイルを格納します。
+│  ├─ locales/ --------------- メッセージ管理に関するファイルを格納します。
 │  ├─ router/ ---------------- ルーティング定義を格納します。
 │  ├─ services/ -------------- サービスに関するファイルを格納します。
+│  ├─ shared/ ---------------- アプリケーション全体で再利用する共通機能のファイルを格納します。
 │  ├─ stores/ ---------------- store に関するファイルを格納します。
+│  ├─ validation/ ------------ 一元化するバリデーション定義ファイルを格納します。
 │  ├─ views/ ----------------- ルーティングで指定される vue ファイルを格納します。またページ固有の挙動などもここに含めます。
 │  ├─ App.vue
 │  └─ main.ts

documents/contents/app-architecture/client-side-rendering/global-function/exception-handling.md

@@ -3,6 +3,8 @@ title: CSR 編
 description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
 ---
 
+<!-- cspell:ignore applicationcore rgba -->
+
 # 例外処理方針 {#top}
 
 バックエンドアプリケーションで発生するシステム例外や業務例外は、例外フィルターによって捕捉します。
@@ -103,3 +105,73 @@ HTTP 通信で発生する例外について、レスポンスやステータス
     C->>B: エラー通知
     deactivate C
 ```
+
+### API 通信のエラーレスポンス {#error-response}
+
+API 通信で発生した例外において、バックエンドから返却されるエラーレスポンスには、 [ProblemDetails :material-open-in-new:](https://www.rfc-editor.org/rfc/rfc9457.html){ target=_blank } に基づくレスポンスボディーを含みます。
+
+ProblemDetails は、 HTTP API のエラーレスポンスを標準化するための構造体であり、以下のプロパティで定義されています。
+
+|             項目             | プロパティ名 |    推奨レベル    |                                                                                                               内容                                                                                                               |
+| ---------------------------- | ------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 簡易メッセージ               | title        | 必須             | 人間が読める形式で提供されます。                                                                                                                                                                                                 |
+| 詳細メッセージ               | detail       | 本番環境は非推奨 | スタックトレースなどを含めます。開発環境では生産性向上を目的に含めることを推奨しますが、本番環境では使用しません。開発環境と本番環境で構成を変更することが難しい場合には detail を使用しないよう統一することも検討してください。 |
+| ステータスコード             | status       | 任意             | HTTP エラーのステータスコードです。                                                                                                                                                                                              |
+| 詳細 URL                     | type         | 推奨             | エラーを説明する詳細 Web ドキュメントがある場合、ユーザーが参照する URL を追加します。                                                                                                                                           |
+| 問題が発生したリソースの URI | instance     | 任意             | 問題の発生場所を示す URI です。リクエスト先と異なるリソースが問題の発生したリソースである場合、実装の詳細やデータなどの内部情報が漏洩する可能性があるため、追加には注意が必要です。                                              |
+| 任意のパラメータ             |              | 任意             | 拡張メンバーです。必要に応じて ProblemDetails のプロパティを拡張する場合に利用します。                                                                                                                                           |
+
+ProblemDetails のレスポンスに含める各プロパティは以下のような観点をもとに取捨選択します。
+
+- 環境による判断
+
+    - 本番環境の場合には、ユーザーが見て管理者に伝えるための情報のみをプロパティに含めるべきです。
+    - 開発環境の場合には、開発者がデバッグやテストなどの作業で確認すべき情報を含めるべきです。
+
+- API の用途による判断
+
+    - 外部公開 API の場合には、セキュリティやプライバシーを考慮し、必要最低限の情報を提供するようにプロパティを設定します。
+    - 内部 API の場合には、画面に対応したエラーレスポンスとして含めるべきプロパティを設定します。
+
+また、 AlesInfiny Maia OSS Edition では、フロントエンド側で管理しているメッセージを取得するために以下の拡張メンバーを追加で定義しています。
+
+- exceptionId
+
+    例外 ID 。メッセージファイルからエラーメッセージを取得するためのメッセージコードとして利用します。
+
+- exceptionValues
+
+    例外値。例外 ID から取得したエラーメッセージ内のパラメーターに代入する値として利用します。
+
+クライアントサイドでポップアップやトースト通知などを用いてエラー通知を実装する場合には、 ProblemDetails の各プロパティの内容を表示します。
+
+#### エラーレスポンスの例 {#example-of-error-response}
+
+説明したエラーレスポンスの例を以下に示します。
+
+```json title="開発環境の場合のエラーレスポンス"
+HTTP/1.1 400 Bad Request
+Content-Type: application/problem+json; charset=utf-8
+
+{
+    "type": "https://hoge.com/error/catalogItemIdDoesNotExistInBasket",
+    "title": "業務エラーが発生しました。",
+    "status": 400,
+    "detail": "dressca.applicationcore.baskets.CatalogItemInBasketNotFoundException: 業務エラーが発生しました。 ###以下スタックトレースは省略###",
+    "exceptionId": "catalogItemIdDoesNotExistInBasket",
+    "exceptionValues": ["1 ###買い物かごID###", "10 ###商品ID###"]
+}
+```
+
+```json title="本番環境の場合のエラーレスポンス"
+HTTP/1.1 400 Bad Request
+Content-Type: application/problem+json; charset=utf-8
+
+{
+    "type": "https://hoge.com/error/catalogItemIdDoesNotExistInBasket",
+    "title": "業務エラーが発生しました。",
+    "status": 400,
+    "exceptionId": "catalogItemIdDoesNotExistInBasket",
+    "exceptionValues": ["1 ###買い物かごID###", "10 ###商品ID###"]
+}
+```

documents/contents/app-architecture/client-side-rendering/global-function/message-management-policy.md

@@ -9,5 +9,136 @@ Java アプリケーションのメッセージ管理方針については、以
 
 - [Java アプリケーションの処理方式 - メッセージ管理方針](../../../app-architecture/overview/java-application-processing-system/message-management-policy.md#message-management-policy)
 
-フロントエンドアプリケーションでは、特別なメッセージ管理しません。
-画面内に出力するメッセージやラベルは、各画面やソースコード内に個別に実装したものを使用します。
+フロントエンドアプリケーションにおけるメッセージとは、画面や帳票等に表示する固定文言、またはユーザーの画面操作の結果に応じて表示する動的文言を指します。
+
+## メッセージパターン {#message-pattern}
+
+フロントエンドアプリケーションにおけるメッセージパターンとメッセージの表示内容を以下に示します。
+
+| パターン             | 表示内容             | 表示例                                                       |
+| -------------------- | -------------------- | ------------------------------------------------------------ |
+| 処理メッセージ       | 処理の確認           | 注文内容を確認して「注文を確定する」ボタンを押してください。 |
+|                      | 正常終了             | 注文が完了しました。                                         |
+|                      | 業務エラー           | カートに追加できませんでした。                               |
+|                      |                      | 商品の削除に失敗しました。                                   |
+|                      | システムエラー       | サーバーエラーが発生しました。                               |
+|                      |                      | ネットワークエラーが発生しました。                           |
+| 入力値検証メッセージ | 単項目チェックエラー | 値を入力してください                                         |
+|                      | 相関チェックエラー   | パスワードと確認用パスワードが一致しません                   |
+| ラベル               | 画面のタイトル       | Dressca                                                      |
+|                      | 画面の項目名         | 合計 / 送料                                                  |
+|                      | UI ラベル         | 注文を確定する                                               |
+
+## メッセージの管理単位 {#management-unit}
+
+各メッセージの用途を明確にするため、前述したメッセージパターンごとにメッセージを管理します。
+AlesInfiny Maia OSS Edition における、メッセージパターンごとのメッセージ管理方針は以下の通りです。
+
+- 処理メッセージ
+
+    処理メッセージ管理用のファイルを定義して一括で管理します。
+
+    処理メッセージは変更や追加の要求が多く、一か所で管理することによりメンテナンスが容易になります。
+
+- 入力値検証メッセージ
+
+    入力値検証メッセージ管理用のファイルを定義して一括で管理します。
+
+    入力値検証メッセージは複数の場所で使用する可能性が高く、ファイルに定義しておくことで再利用が簡単になります。
+    これにより、コードの重複を避けることにつながります。
+
+- ラベル
+
+    画面内に出力するラベルは各画面やソースコード内に個別に実装したものを使用します。
+
+    ラベルに対してもアプリケーション全体で用語を統一する場合や後述する多言語を実施する場合には、ファイルによるメッセージの一元管理が必要です。
+    しかし、用語の統一は初期の実装やメッセージ管理ファイルの維持にかかるコストが高いです。
+    また、ラベルへの多言語対応は言語設定によって画面のレイアウトが崩れてしまう恐れがあります。
+    そのため、ラベルに対してファイルによるメッセージ管理を導入することは、慎重な検討が必要です。
+
+## メッセージのファイル管理 {#message-file-management}
+
+フロントエンドアプリケーションでは、処理メッセージや入力値検証メッセージは JSON ファイルを利用して管理します。
+JSON ファイルでは、以下のようにメッセージ文字列を識別するメッセージコードとメッセージ文字列本体を key-value で管理します。
+
+``` json title="メッセージの JSON ファイルの定義例"
+{
+  "errorOccurred": "エラーが発生しました。",
+  ...
+}
+```
+
+### メッセージコードの定義 {#message-codes-definition}
+
+前述した JSON ファイルのように、メッセージコードはそのメッセージの内容を簡潔に表す文字列とします。
+このようにすることで、以下のような利点があります。
+
+- 可読性の向上
+
+    数字のメッセージコードよりも、意味を持つメッセージコードを定義することで直感的で理解しやすい利点があります。
+    開発者がメッセージコードを見たときに、すぐにそのメッセージの内容や目的を把握できます。
+
+- エラー追跡の効率化
+
+    ログやデバッグ時に、意味を持つコードは問題を迅速に特定することに役立ちます。
+
+- ドキュメント化の簡便さ
+
+    メッセージコードがそのメッセージ内容を簡潔に表していれば、メッセージコードの意味を説明するための追加のドキュメントが不要になることがあります。
+
+### エラーメッセージコードの統一 {#unification-of-message-codes}
+
+エラー発生時のメッセージ整形の流れを以下に示します。
+
+![エラーメッセージ整形の流れ](../../../images/app-architecture/client-side-rendering/error-message-delivery-light.png#only-light){ loading=lazy }
+![エラーメッセージ整形の流れ](../../../images/app-architecture/client-side-rendering/error-message-delivery-dark.png#only-dark){ loading=lazy }
+
+この画像の通り、エラー発生時はバックエンドアプリケーションのエラーログの出力とフロントエンドアプリケーションへのエラーの画面出力が順次実施されます。
+
+そのため、同一の業務エラーやシステムエラーのメッセージコードは、バックエンド側とフロントエンド側で統一します。
+これにより、以下のような利点があります。
+
+- 一貫性の確保
+
+    統一されたメッセージコードを使用することで、エラーの識別が容易になり、システム全体の一貫性が保たれます。
+
+- デバッグの効率化
+
+    開発者がエラーを特定しやすくなり、問題解決のスピードが向上します。
+    バックエンドとフロントエンドで同じコードを使用することで、エラーの原因を迅速に特定できます。
+
+OpenAPI 仕様書などの各 JSON ファイルと命名規則を統一するため、メッセージコードをキャメルケースとします。
+それに伴い、フロントエンド側に合わせてバックエンドのプロパティファイルのメッセージコードもキャメルケースで記載します。
+バックエンドのプロパティファイルの設定例は、[こちら](../../overview/java-application-processing-system/message-management-policy.md#property-file-management) を確認してください。
+
+### エラーメッセージ内のパラメータ {#parameter-of-error-messages}
+
+以下のように、エラーメッセージの中にはパラメータを含むものがあります。
+
+```json title="パラメータを含むエラーメッセージの例"
+{
+  "assetNotFound": "アセットコード: [0] のアセットが見つかりませんでした。",
+}
+```
+
+パラメータに代入するべき値は、エラーレスポンスに含まれる ProblemDetails の拡張メンバーである `exceptionValues` から取得します。
+ProblemDetails については、[こちら](./exception-handling.md#error-response) を確認してください。
+
+### 多言語対応 {#localization}
+
+メッセージを多言語対応する場合には、それぞれの言語の JSON ファイルを作成し、各言語のメッセージをフォルダーで分割して管理します。
+以下に示すように、フォルダー名は [ISO-639 言語コード :material-open-in-new:](https://www.iso.org/iso-639-language-code){ target=_blank } に基づき、その言語を表す言語コードとします。
+
+また、各ファイルの末尾には言語コードを付与します。
+
+```terminal linenums="0"
+locales/ ------------------------------------- メッセージ管理を行うコードが配置されるフォルダー
+ ├ en/ ---------------------------------------- 英語メッセージの管理を行うフォルダー
+ │ ├ messageList_en.json ---------------------- 処理の成功や失敗などの結果メッセージを格納する JSON ファイル（英語）
+ │ └ validationTextList_en.json --------------- 入力値検証用のメッセージを格納する JSON ファイル（英語）
+ └ ja/ ---------------------------------------- 日本語メッセージの管理を行うフォルダー
+   ├ messageList_ja.json ---------------------- 処理の成功や失敗などの結果メッセージを格納する JSON ファイル（日本語）
+   └ validationTextList_ja.json --------------- 入力値検証用のメッセージを格納する JSON ファイル（日本語）
+```
+
+メッセージ管理方針に従った機能の実装方法などの詳細については、[こちら](../../../guidebooks/how-to-develop/vue-js/message-management.md) を確認してください。