Skip to content

Commit db90e02

Browse files
ma91nma91n
authored
Markdown: brush up (#177)
* brush up * add embed code * Add figma link
1 parent 0123b70 commit db90e02

File tree

13 files changed

+97
-75
lines changed

13 files changed

+97
-75
lines changed

‎documents/forMarkdown/API_GET.md‎

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎documents/forMarkdown/IF定義書.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,6 @@ end
156156

157157
## エラー処理
158158

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

‎documents/forMarkdown/README.md‎

Lines changed: 71 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,21 @@ Markdown に限った話では無いが、どういった内容を設計書に
2424
- Git（GitHub, GitLab）で管理され、コードと設計書が同一リポジトリで管理される
2525
- システム開発で必要なアプリケーション開発
2626

27-
## フォルダ階層
27+
## 本規約で紹介する設計ドキュメントの位置付け
28+
29+
設計ドキュメントは様々な前提条件／制約／経緯で作成され、Excel／Word／パワーポイントなどのファイル形式で作成することが多い。
30+
31+
本規約はそれらを否定するものではなく、様々な利害関係者の要求に応え洗練され続けた上記の設計ドキュメントのテンプレートには、強く敬意を表する。
32+
33+
一方で、設計ドキュメントを精緻に管理していく優先度より、プロダクト開発の効率とビジネスピードをより重視する場合もあり、それらの開発チームでは設計ドキュメントが存在さいない、あっても設計書が実装と乖離しているなどの声も多い。
34+
35+
本規約では、後者のプロダクト開発の効率性を重視し、設計ドキュメントが開発以外の観点から求められない場合において、必要最低限必要だと思われるレベルの記載内容を示す。
36+
37+
設計ドキュメントのファイルフォーマットに制約は無いという前提に立つため、設計ドキュメントの陳腐化を防ぐのに有効だと思われる、テキストベース（Markdown）でGit管理するという思想を採用する。
38+
39+
本規約で紹介した各設計ドキュメントの記載内容を参考にしつつ、各開発チームにおいて必要な情報を追加／削除して利用するという、テンプレートとしての利用を想定する。
40+
41+
## フォルダ階層の推奨
2842

2943
リポジトリ直下に `docs` フォルダを作成し、その配下に設計ドキュメントとなる Markdown ファイルを配備する。
3044

@@ -67,9 +81,34 @@ docs
6781

6882
図は基本的に変更差分がGitと相性が良い、PlantUML（またはMermaid.js）で作成すること。
6983

84+
```plantuml
85+
86+
@startuml
87+
!include https://raw.githubusercontent.com/future-architect/puml-themes/master/themes/puml-theme-mars.puml
88+
89+
participant Participant as Foo
90+
note over Foo: Event
91+
actor Actor as Foo1
92+
boundary Boundary as Foo2
93+
control Control as Foo3
94+
entity Entity as Foo4
95+
database Database as Foo5
96+
collections Collections as Foo6
97+
queue Queue as Foo7
98+
Foo -> Foo1 : To actor
99+
Foo -> Foo2 : To boundary
100+
Foo -> Foo3 : To control
101+
Foo -> Foo4 : To entity
102+
Foo -> Foo5 : To database
103+
Foo -> Foo6 : To collections
104+
Foo -> Foo7: To queue
105+
106+
@enduml
107+
```
108+
70109
システム構成図などは上記では対応しにくいことが多いため、diagrams.net（draw.io）で作成する。
71110

72-
拡張子は以下のいずれかで作成する。
111+
diagrams.netの場合は、拡張子は以下のいずれかで作成する。
73112

74113
- `.drawio.png`
75114
- `.drawio.jpg`
@@ -80,7 +119,7 @@ docs
80119
以下の方針を取る。
81120

82121
- Figmaを用いて、画面遷移、画面表示項目を定義する
83-
- Markdown設計書には、Figmaで判断可能な見た目の情報は記載しない
122+
- Markdown設計書には、Figmaで判断可能な見た目の情報は **記載しない**
84123
- Markdown設計書には、Web APIの呼び出しやイベントの定義、パラメータの受け渡し、バリデーションロジックなどを定義する。
85124

86125
[サンプル設計書](future_muscle_partner)を参考にする。
@@ -104,15 +143,42 @@ docs
104143

105144
API 定義書は `openapi.yaml` で記載すること。
106145

107-
### プログラム設計書
146+
詳細は[OpenAPI Specification 3.0.3規約](https://future-architect.github.io/coding-standards/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.html) を参考にする。
147+
148+
### プログラム設計書（バッチ、非同期タスクなど）
108149

109150
[プログラム設計書](プログラム設計書.md)を参考にする。
110151

152+
### プログラム設計書（Web API）
153+
154+
Web APIについても、プログラム設計書と同様に機能ID単位で作成する。
155+
156+
ただし、Web APIにおいては `openapi.yaml` と重複する部分で自明な内容（例えば、リクエストパラメータの定義や、レスポンス項目）については、重複するため記載を省略する。
157+
158+
もし、検索APIで複数のテーブルを参照して結果を応答する場合に、項目の由来を示すため、下表のような形式を定義すること。
159+
160+
#### Web API応答例
161+
162+
| Parameter | Description | Settings | Note |
163+
|-----------------|-------------|----------|------|
164+
| last_name | 氏名 (姓) | m_user | |
165+
| first_name | 氏名 (名) | m_user | |
166+
| last_name_kana | 氏名カナ (姓) | m_user | |
167+
| first_name_kana | 氏名カナ (名) | m_user | |
168+
| date_of_birth | 生年月日 | m_user_detail | |
169+
| gender_type | 性別区分 | m_user_detail | |
170+
| tel | 電話番号 | m_user_detail | |
171+
| occupation_type | 職業区分 | m_user_detail | |
172+
| zipcode | 郵便番号 | m_user_detail | |
173+
174+
※Descriptionは `openapi.yaml` 側の `description` で記載済みであれば、省略すること
175+
※Noteは何かしら加工処理により生み出された項目であれば、計算ロジックを記載する
176+
111177
### I/F 定義書
112178

113179
I/F 定義書は、システム間の連携について定義と、その受信/配信処理の設計書です。
114180

115-
システム I/F は連携先の対向システムが存在するため、認識齟齬が無いように、どのようなプロトコル・項目であるかを定義する必要があります。
181+
システム I/F は連携先の対向システムが存在するため、認識齟齬が無いように、どのようなプロトコル・項目であるかを定義する必要がある。
116182

117183
[IF定義書](IF定義書.md)を参考にする。
118184

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 画面
22

3-
* Figma URL: <準備中>
3+
* 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
44

55
## 標準画面
66

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [UIM01] ログイン
22

3+
<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>
4+
35
## 概要
46

57
機能目的:

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [UIM02] トレーナー検索
22

3+
<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>
4+
35
## 概要
46

57
機能目的:

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [UIM03] カレンダー予約
22

3+
<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>
4+
35
## 概要
46

57
機能目的:

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [UIM04] 決済
22

3+
<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>
4+
35
## 概要
46

57
機能目的:

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [UIS01] トップページ
22

3+
<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>
4+
35
## 概要
46

57
機能目的:

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# [UIS02] マイページ
22

3+
<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>
4+
35
## 概要
46

57
機能目的:

0 commit comments

Comments
 (0)