diff --git a/documents/forMarkdown/API_GET.md b/documents/forMarkdown/API_GET.md deleted file mode 100644 index 9ef2f1bb..00000000 --- a/documents/forMarkdown/API_GET.md +++ /dev/null @@ -1,66 +0,0 @@ -# [機能ID] 会員情報取得API GET /${パス} - -## 説明 - -- ユーザの会員情報を参照するAPI - -## 仕様 - -- ユーザの属性を参照する。 - - ユーザーマスタの全属性を返却する。 -- DBへのSELECT時に使用する当該ユーザのキーはアクセストークン.subとする - -## シーケンス図 - -```mermaid - - -sequenceDiagram -participant "Backend" as Backend -participant "DB" as db - -user ->> Backend: API Request - -note over Backend,db: 1. Retrieve user and physical subscription information - - Backend ->> db: 1.1 Select m_user, m_physical_sub_info - - alt no record - <- Backend: 1.1.1 Response status code: 400 - end - -note over Backend,db - 2. Retrieve required basic user attributes and - physical subscription information requirements for registered courses -end note - Backend -> db: 2.1 Select t_course_registration,\nm_course_basic_user_attribute, m_course - -<- Backend: Return response and status code: 200 - -@enduml - -``` - -## Request & Response - -### Request - -- なし - -### Response - -| 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 | | -| gender_type | 性別区分 | m_user | | -| tel | 電話番号 | m_user | | -| occupation_type | 職業区分 | m_user | | -| zipcode | 郵便番号 | m_user | | -| pref_code | 都道府県コード | m_user | | -| town | 市区町村大字 | m_user | | -| building | 番地・マンション名 | m_user | | -| address_kana | 住所カナ | m_user | | diff --git "a/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" "b/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" index ef20d034..e9d20093 100644 --- "a/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" +++ "b/documents/forMarkdown/IF\345\256\232\347\276\251\346\233\270.md" @@ -156,6 +156,6 @@ end ## エラー処理 -| Pattern | Description | recovery | -| -------- | ----------------------------------- | --------- | -| フォーマットエラー | 連携元から提供されているデータ形式が想定外 | 連携元またはIFの処理内容の修正と再実行（運用手順書のリンクでもいいかも） | +| Pattern | Description | recovery | +|-----------|-----------------------|---------------------------------------| +| フォーマットエラー | 連携元から提供されているデータ形式が想定外 | 連携元またはIFの処理内容の修正と再実行（運用手順書のリンクでもいいかも） | diff --git a/documents/forMarkdown/README.md b/documents/forMarkdown/README.md index 98324327..98aa5d31 100644 --- a/documents/forMarkdown/README.md +++ b/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)を参考にする。 diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/README.md" index a8f7bfce..2afa16e8 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/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 ## 標準画面 diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/README.md" index 6709a081..efbb0e43 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM01/README.md" @@ -1,5 +1,7 @@ # [UIM01] ログイン + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM02/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM02/README.md" index a959b202..9b79850e 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM02/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM02/README.md" @@ -1,5 +1,7 @@ # [UIM02] トレーナー検索 + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM03/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM03/README.md" index e8e11a24..4fe2ec4c 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM03/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM03/README.md" @@ -1,5 +1,7 @@ # [UIM03] カレンダー予約 + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM04/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM04/README.md" index 85e7b4a9..02798414 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM04/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIM04/README.md" @@ -1,5 +1,7 @@ # [UIM04] 決済 + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS01/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS01/README.md" index 5b90d923..2ba94178 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS01/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS01/README.md" @@ -1,5 +1,7 @@ # [UIS01] トップページ + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS02/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS02/README.md" index 5b9d4127..2e33e57e 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS02/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS02/README.md" @@ -1,5 +1,7 @@ # [UIS02] マイページ + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS03/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS03/README.md" index e607c271..6cc0529b 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS03/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS03/README.md" @@ -1,5 +1,7 @@ # [UIS03] トレーナー一覧 + + ## 概要 機能目的: diff --git "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS04/README.md" "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS04/README.md" index 24bda13d..be04c6a2 100644 --- "a/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS04/README.md" +++ "b/documents/forMarkdown/future_muscle_partner/docs/01_\347\224\273\351\235\242/UIS04/README.md" @@ -1,5 +1,7 @@ # [UIS04] トレーナー詳細 + + ## 概要 機能目的: diff --git a/documents/forMarkdown/future_muscle_partner/docs/README.md b/documents/forMarkdown/future_muscle_partner/docs/README.md index 25d11531..00ea6894 100644 --- a/documents/forMarkdown/future_muscle_partner/docs/README.md +++ b/documents/forMarkdown/future_muscle_partner/docs/README.md @@ -37,3 +37,9 @@ docs - 採番後の変更は許可しない - 連番とする（数字部分に新しい体系を作らない） + +## 画面設計書の記載方針 + +- Web API の応答項目が、画面項目のどこにマッピングすべきかという情報は、多くの業務画面で重要である + - 理由は、類似名称の項目がWeb API応答項目にも画面項目多く、紐づけの認識の齟齬が生じやすいからである +- future muscle partnerにおいては、項目数は多くなくFigmaを見れば自明であるため、画面項目定義を省略する