Markdown: brush up (#177)

* brush up

* add embed code

* Add figma link

documents/forMarkdown/IF定義書.md

@@ -156,6 +156,6 @@ end
 
 ## エラー処理
 
-| Pattern | Description                                | recovery     |
-| -------- | ----------------------------------- | --------- |
-| フォーマットエラー | 連携元から提供されているデータ形式が想定外 | 連携元またはIFの処理内容の修正と再実行（運用手順書のリンクでもいいかも）  |
+| Pattern   | Description           | recovery                              |
+|-----------|-----------------------|---------------------------------------|
+| フォーマットエラー | 連携元から提供されているデータ形式が想定外 | 連携元またはIFの処理内容の修正と再実行（運用手順書のリンクでもいいかも） |

documents/forMarkdown/README.md

@@ -24,7 +24,21 @@ Markdown に限った話では無いが、どういった内容を設計書に
 - Git（GitHub, GitLab）で管理され、コードと設計書が同一リポジトリで管理される
 - システム開発で必要なアプリケーション開発
 
-## フォルダ階層
+## 本規約で紹介する設計ドキュメントの位置付け
+
+設計ドキュメントは様々な前提条件／制約／経緯で作成され、Excel／Word／パワーポイントなどのファイル形式で作成することが多い。
+
+本規約はそれらを否定するものではなく、様々な利害関係者の要求に応え洗練され続けた上記の設計ドキュメントのテンプレートには、強く敬意を表する。
+
+一方で、設計ドキュメントを精緻に管理していく優先度より、プロダクト開発の効率とビジネスピードをより重視する場合もあり、それらの開発チームでは設計ドキュメントが存在さいない、あっても設計書が実装と乖離しているなどの声も多い。
+
+本規約では、後者のプロダクト開発の効率性を重視し、設計ドキュメントが開発以外の観点から求められない場合において、必要最低限必要だと思われるレベルの記載内容を示す。
+
+設計ドキュメントのファイルフォーマットに制約は無いという前提に立つため、設計ドキュメントの陳腐化を防ぐのに有効だと思われる、テキストベース（Markdown）でGit管理するという思想を採用する。
+
+本規約で紹介した各設計ドキュメントの記載内容を参考にしつつ、各開発チームにおいて必要な情報を追加／削除して利用するという、テンプレートとしての利用を想定する。
+
+## フォルダ階層の推奨
 
 リポジトリ直下に `docs` フォルダを作成し、その配下に設計ドキュメントとなる Markdown ファイルを配備する。
 
@@ -67,9 +81,34 @@ docs
 
 図は基本的に変更差分がGitと相性が良い、PlantUML（またはMermaid.js）で作成すること。
 
+```plantuml
+
+@startuml
+!include https://raw.githubusercontent.com/future-architect/puml-themes/master/themes/puml-theme-mars.puml
+
+participant Participant as Foo
+note over Foo: Event
+actor       Actor       as Foo1
+boundary    Boundary    as Foo2
+control     Control     as Foo3
+entity      Entity      as Foo4
+database    Database    as Foo5
+collections Collections as Foo6
+queue       Queue       as Foo7
+Foo -> Foo1 : To actor
+Foo -> Foo2 : To boundary
+Foo -> Foo3 : To control
+Foo -> Foo4 : To entity
+Foo -> Foo5 : To database
+Foo -> Foo6 : To collections
+Foo -> Foo7: To queue
+
+@enduml
+```
+
 システム構成図などは上記では対応しにくいことが多いため、diagrams.net（draw.io）で作成する。
 
-拡張子は以下のいずれかで作成する。
+diagrams.netの場合は、拡張子は以下のいずれかで作成する。
 
 - `.drawio.png`
 - `.drawio.jpg`
@@ -80,7 +119,7 @@ docs
 以下の方針を取る。
 
 - Figmaを用いて、画面遷移、画面表示項目を定義する
-- Markdown設計書には、Figmaで判断可能な見た目の情報は記載しない
+- Markdown設計書には、Figmaで判断可能な見た目の情報は **記載しない**
 - Markdown設計書には、Web APIの呼び出しやイベントの定義、パラメータの受け渡し、バリデーションロジックなどを定義する。
 
 [サンプル設計書](future_muscle_partner)を参考にする。
@@ -104,15 +143,42 @@ docs
 
 API 定義書は `openapi.yaml` で記載すること。
 
-### プログラム設計書
+詳細は[OpenAPI Specification 3.0.3規約](https://future-architect.github.io/coding-standards/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.html) を参考にする。
+
+### プログラム設計書（バッチ、非同期タスクなど）
 
 [プログラム設計書](プログラム設計書.md)を参考にする。
 
+### プログラム設計書（Web API）
+
+Web APIについても、プログラム設計書と同様に機能ID単位で作成する。
+
+ただし、Web APIにおいては `openapi.yaml` と重複する部分で自明な内容（例えば、リクエストパラメータの定義や、レスポンス項目）については、重複するため記載を省略する。
+
+もし、検索APIで複数のテーブルを参照して結果を応答する場合に、項目の由来を示すため、下表のような形式を定義すること。
+
+#### Web API応答例
+
+| Parameter       | Description | Settings | Note |
+|-----------------|-------------|----------|------|
+| last_name       | 氏名 (姓)      | m_user   |      |
+| first_name      | 氏名 (名)      | m_user   |      |
+| last_name_kana  | 氏名カナ (姓)    | m_user   |      |
+| first_name_kana | 氏名カナ (名)    | m_user   |      |
+| date_of_birth   | 生年月日        | m_user_detail   |      |
+| gender_type     | 性別区分        | m_user_detail   |      |
+| tel             | 電話番号        | m_user_detail   |      |
+| occupation_type | 職業区分        | m_user_detail   |      |
+| zipcode         | 郵便番号        | m_user_detail   |      |
+
+※Descriptionは `openapi.yaml` 側の `description` で記載済みであれば、省略すること
+※Noteは何かしら加工処理により生み出された項目であれば、計算ロジックを記載する
+
 ### I/F 定義書
 
 I/F 定義書は、システム間の連携について定義と、その受信/配信処理の設計書です。
 
-システム I/F は連携先の対向システムが存在するため、認識齟齬が無いように、どのようなプロトコル・項目であるかを定義する必要があります。
+システム I/F は連携先の対向システムが存在するため、認識齟齬が無いように、どのようなプロトコル・項目であるかを定義する必要がある。
 
 [IF定義書](IF定義書.md)を参考にする。
 

documents/forMarkdown/future_muscle_partner/docs/01_画面/README.md

@@ -1,6 +1,6 @@
 # 画面
 
-* Figma URL: <準備中>
+* Figma URL: https://www.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=0-1&t=1RbQxA1h0GymGUm9-1
 
 ## 標準画面
 

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIM01/README.md

@@ -1,5 +1,7 @@
 # [UIM01] ログイン
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=4-5&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIM02/README.md

@@ -1,5 +1,7 @@
 # [UIM02] トレーナー検索
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=233-907&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIM03/README.md

@@ -1,5 +1,7 @@
 # [UIM03] カレンダー予約
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=115-295&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIM04/README.md

@@ -1,5 +1,7 @@
 # [UIM04] 決済
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=249-925&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIS01/README.md

@@ -1,5 +1,7 @@
 # [UIS01] トップページ
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=1-2&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIS02/README.md

@@ -1,5 +1,7 @@
 # [UIS02] マイページ
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=4-2&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIS03/README.md

@@ -1,5 +1,7 @@
 # [UIS03] トレーナー一覧
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=4-11&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/01_画面/UIS04/README.md

@@ -1,5 +1,7 @@
 # [UIS04] トレーナー詳細
 
+<iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="800" height="450" src="https://embed.figma.com/design/kLgdi4xdGRpQudMEoZYwvq/%E3%80%90FMP%E3%80%91Future-Muscle-Partner_%E7%94%BB%E9%9D%A2%E3%83%87%E3%82%B6%E3%82%A4%E3%83%B3?node-id=115-284&embed-host=share" allowfullscreen></iframe>
+
 ## 概要
 
 機能目的:

documents/forMarkdown/future_muscle_partner/docs/README.md

@@ -37,3 +37,9 @@ docs
 
 - 採番後の変更は許可しない
 - 連番とする（数字部分に新しい体系を作らない）
+
+## 画面設計書の記載方針
+
+- Web API の応答項目が、画面項目のどこにマッピングすべきかという情報は、多くの業務画面で重要である
+  - 理由は、類似名称の項目がWeb API応答項目にも画面項目多く、紐づけの認識の齟齬が生じやすいからである
+- future muscle partnerにおいては、項目数は多くなくFigmaを見れば自明であるため、画面項目定義を省略する