Skip to content

Commit 7cf126c

Browse files
ma91nshotashotaTsubasaKanemitsushibukawa
authored
Add markdown design document part (#167)
* Markdown 1st commit * フォルダ構造を追加 (#88) * I/F定義 (#89) * プログラム詳細設計 (#93) * Update プログラム設計書.md * Update プログラム設計書.md * prettier format (#94) * add api get * 画面設計書のサンプルMarkdownを追加 (#107) * Add future muscle partner ERD (#112) * 【Markdown】Future Musche Partnerのテンプレート作成 (#117) * Add future muscle partner ERD * Muscle partnerのフォルダ構造を作成 * Add openapi.yaml of muscle partner (#124) 1st commit openapi.yaml * fix: to OAS 3.0.3 (#127) * Update revie (#131) * update (#97) * メッセージ設計書 (#106) * 区分値設計書 (#105) * add: new section (#96) * Update .editorconfig (#135) * Add attributes to Request and Response (#130) * fix: ERD * fix: endpoint parameter * add: attributes to request and response * git mv ERD (#139) * rename directory (#163) * fix markdownlint * reset unnecessary diffs * reset unnecessary diffs * reset unnecessary diffs * reset unnecessary diffs --------- Co-authored-by: shotashota <[email protected]> Co-authored-by: tk007 <[email protected]> Co-authored-by: Yoshiki Shibukawa <[email protected]>
1 parent a0b54a8 commit 7cf126c

File tree

27 files changed

+2441
-115
lines changed

27 files changed

+2441
-115
lines changed

‎.editorconfig‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,6 @@ charset = utf-8
55
trim_trailing_whitespace = true
66
insert_final_newline = true
77
end_of_line = lf
8+
9+
[*.md]
10+
trim_trailing_whitespace = false

‎documents/forMarkdown/API_GET.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# [機能ID] 会員情報取得API GET /${パス}
2+
3+
## 説明
4+
5+
- ユーザの会員情報を参照するAPI
6+
7+
## 仕様
8+
9+
- ユーザの属性を参照する。
10+
- ユーザーマスタの全属性を返却する。
11+
- DBへのSELECT時に使用する当該ユーザのキーはアクセストークン.subとする
12+
13+
## シーケンス図
14+
15+
```mermaid
16+
17+
18+
sequenceDiagram
19+
participant "Backend" as Backend
20+
participant "DB" as db
21+
22+
user ->> Backend: API Request
23+
24+
note over Backend,db: 1. Retrieve user and physical subscription information
25+
26+
Backend ->> db: 1.1 Select m_user, m_physical_sub_info
27+
28+
alt no record
29+
<- Backend: 1.1.1 Response status code: 400
30+
end
31+
32+
note over Backend,db
33+
2. Retrieve required basic user attributes and
34+
physical subscription information requirements for registered courses
35+
end note
36+
Backend -> db: 2.1 Select t_course_registration,\nm_course_basic_user_attribute, m_course
37+
38+
<- Backend: Return response and status code: 200
39+
40+
@enduml
41+
42+
```
43+
44+
## Request & Response
45+
46+
### Request
47+
48+
- なし
49+
50+
### Response
51+
52+
| Parameter | Description | Settings | Note |
53+
| ------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------- | ---- |
54+
| last_name | 氏名 (姓) | m_user | |
55+
| first_name | 氏名 (名) | m_user | |
56+
| last_name_kana | 氏名カナ (姓) | m_user | |
57+
| first_name_kana | 氏名カナ (名) | m_user | |
58+
| date_of_birth | 生年月日 | m_user | |
59+
| gender_type | 性別区分 | m_user | |
60+
| tel | 電話番号 | m_user | |
61+
| occupation_type | 職業区分 | m_user | |
62+
| zipcode | 郵便番号 | m_user | |
63+
| pref_code | 都道府県コード | m_user | |
64+
| town | 市区町村大字 | m_user | |
65+
| building | 番地・マンション名 | m_user | |
66+
| address_kana | 住所カナ | m_user | |
67+

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# IF01 設備有効開始受信
2+
3+
設備有効開始の取り込みを行う。
4+
5+
## 対向システム
6+
7+
| 連携元 | 連携先 |
8+
| ---------- | ------ |
9+
| A システム | Future |
10+
11+
## 環境情報
12+
13+
### Input
14+
15+
| Item | Value |
16+
| ---------------- | ------------------------------------------------ |
17+
| 連携 S3 バケット | `${env}-example-import` |
18+
| プレフィックス | `activate/year=${yyyy}/month=${MM}/day=${dd}/` |
19+
| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` |
20+
| 保持期限 | 3 年 |
21+
22+
### Output
23+
24+
| Item | Value |
25+
| ---------------- | ------------------------------------------------ |
26+
| 連携 S3 バケット | `${env}-example-import` |
27+
| プレフィックス | `activate/year=${yyyy}/month=${MM}/day=${dd}/` |
28+
| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` |
29+
| 保持期限 | 3 年 |
30+
31+
## 連携元定義
32+
33+
| Category | Item | Value | Memo |
34+
| -------- | ----------------------------------- | --------- | -------------------- |
35+
| Protocol | 連携方式（ファイル/API/ストリーム） | ファイル | |
36+
| | 連携タイミング（随時/定時） | 定時 | |
37+
| | 頻度 | 1 回/日 | |
38+
| | 起動時間 | **16:00** | |
39+
| | 処理完了期限 | **16:00** | |
40+
| | 未着チェック（なし/WARN/ERROR） | WARN | |
41+
| | 全件/差分 | 差分 | |
42+
| | 0 件時連携 | あり | |
43+
| Format | ファイル種別 | **CSV** | |
44+
| | レイアウト | RFC 8259 | |
45+
| | 文字コード | UTF-8 | |
46+
| | 改行コード | LF | |
47+
| | 圧縮 | - | |
48+
| | 暗号化 | - | |
49+
| | ヘッダ行 | あり | |
50+
| | 項目順 | 固定 | 項目順は入れ替え不可 |
51+
| | 機密情報 | - | |
52+
53+
### 項目定義
54+
55+
| Name | Physical Name | Type | Length | Precision | Enum | Format | Sensitive | Example | Memo |
56+
| ---------- | --------------- | ------ | ------ | --------- | ---- | ---------- | --------- | ---------- | ---- |
57+
| 会社コード | company_cd | string | 5 | - | - | - | - | 00001 | |
58+
| 設備コード | device_cd | string | 8 | - | - | - | - | 00000052 | |
59+
| 有効開始日 | activation_date | string | 10 | - | - | YYYY-MM-DD | - | 2022-10-16 | [^1] |
60+
61+
[^1]: 現在日以降である必要があるが、受信ではテスト観点で過去日も許容する
62+
63+
#### サンプル
64+
65+
```csv
66+
company_cd,device_cd,activation_date
67+
12121,00000052,2022-03-01
68+
12121,00000053,2022-03-30
69+
```
70+
71+
## 連携先定義
72+
73+
| Category | Item | Value | Memo |
74+
| -------- | ----------------------------------- | --------- | -------------------- |
75+
| Protocol | 連携方式（ファイル/API/ストリーム） | ファイル | |
76+
| | 連携タイミング（随時/定時） | 定時 | |
77+
| | 頻度 | 1 回/日 | |
78+
| | 起動時間 | **16:00** | |
79+
| | 処理完了期限 | **16:00** | |
80+
| | 未着チェック（なし/WARN/ERROR） | WARN | |
81+
| | 全件/差分 | 差分 | |
82+
| | 0 件時連携 | あり | |
83+
| Format | ファイル種別 | **CSV** | |
84+
| | レイアウト | RFC 8259 | |
85+
| | 文字コード | UTF-8 | |
86+
| | 改行コード | LF | |
87+
| | 圧縮 | - | |
88+
| | 暗号化 | - | |
89+
| | ヘッダ行 | あり | |
90+
| | 項目順 | 固定 | 項目順は入れ替え不可 |
91+
| | 機密情報 | - | |
92+
93+
94+
95+
## 処理概要
96+
97+
- ファイル定義に則ったバリデーションを実施
98+
- 次の項目変換定義に従い加工し、出力先テーブルに Merge する
99+
- 受信完了後、 Completed: YYYY-MM-DDTHH:MI:SS.SSS のタグを追加する
100+
101+
## 処理シーケンス
102+
103+
```plantuml
104+
@startuml
105+
!theme toy
106+
107+
participant システム
108+
participant S3
109+
database DB
110+
111+
システム -> DB: 処理日付取得\n[日付管理]
112+
113+
システム -> S3: 対象ファイルの存在チェック
114+
115+
alt ファイルが存在しなかった場合
116+
システム -> システム: 処理終了して、次の処理を待機
117+
end
118+
119+
システム -> DB: シーケンスの取得\n[シーケンスオブジェクト]
120+
121+
システム -> DB: 1.実行開始レコード追加\n[IF受信管理]
122+
123+
システム -> S3: 対象ファイルを取得
124+
125+
システム -> DB: 対象マスタのTruncate
126+
127+
システム -> DB: ファイル連携処理
128+
129+
システム -> システム: 連携件数確認
130+
131+
システム -> S3: 処理済対象ファイルを格納
132+
133+
システム -> DB: 2.実行終了状態の更新\n[IF受信管理]
134+
@enduml
135+
```
136+
137+
## DB 項目
138+
139+
### 参照
140+
141+
なし
142+
143+
### 登録
144+
145+
リストワークに以下のカラムでレコードを登録する
146+
147+
- xxx ワーク.会社コード
148+
- xxx ワーク.処理日付
149+
- xxx ワーク.yyy 区分
150+
151+
### 更新
152+
153+
なし
154+
155+
## ビジネスロジック
156+
157+
特記事項なし
158+
159+
## エラー処理
160+
| Pattern | Description | recovery |
161+
| -------- | ----------------------------------- | --------- |
162+
| フォーマットエラー | 連携元から提供されているデータ形式が想定外 | 連携元またはIFの処理内容の修正と再実行（運用手順書のリンクでもいいかも） |
163+

‎documents/forMarkdown/README.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
sidebarDepth: 4
3+
author: フューチャー株式会社
4+
home: true
5+
heroText: Markdown設計ドキュメント規約
6+
tagline: Future Enterprise Markdown Design Document Standards
7+
pageClass: lang-home
8+
footer: ©2015 - 2024 Future Enterprise Coding Standards - Future Corporation
9+
---
10+
11+
Markdown ベースの設計ドキュメントの規約をまとめる。
12+
13+
システム開発にて利用する設計ドキュメントを Markdown ベースにすることで、コーディングと同じ慣れたツールを用いて、Git によるバージョン管理、レビュープロセス、CI/CD などに自動化（静的解析、自動生成）を行いやすくし、ドキュメントを陳腐化させず、俊敏な設計開発を目指す。
14+
15+
Markdown に限った話では無いが、どういった内容を設計書に記載すべきかは悩むポイントは多い。
16+
17+
本規約では、アプリケーションの種別ごとに記載すべき内容と、それをどのような Markdown の構造で記載するかを規約化し、各チームで悩む余地を減らし、注力すべきことに集中できる環境を提供することを目的とする。
18+
19+
## 前提
20+
21+
本規約は以下の前提で作成されている
22+
23+
- チーム/プロジェクトが 3 ～ 30 名程度規模程度
24+
- Git（GitHub, GitLab）で管理され、コードと設計書が同一リポジトリで管理される
25+
- システム開発で必要なアプリケーション開発
26+
27+
## フォルダ階層
28+
29+
リポジトリ直下に `docs` フォルダを作成し、その配下に設計ドキュメントとなる Markdown ファイルを配備する。
30+
31+
<!-- TODO 【相談】docsだと公開フォルダとみなされるかもなので、documentsとかにしたほうが良いか？ -->
32+
33+
次はバックエンド、フロントエンド、インフラのコードをモノリポで管理している例である。
34+
35+
```sh
36+
.
37+
├── backend # バックエンド系のコード
38+
├── docs
39+
├── frontend # フロントエンド系のコード
40+
├── infrastructure # インフラ系のコード
41+
```
42+
43+
`docs` 配下は以下のルールにしたがった構造を取る。
44+
45+
- `01_`、`02_` といったプレフィックスを持つ
46+
- 番号には体系をもたせず、必要になったタイミングでインクリメントさせる
47+
- オンボーディングコストを抑えるため、なるべく先頭に新規参画者が欲する情報を配備する
48+
49+
構成例を次にあげる。
50+
51+
<!-- TODO 【相談】フロントエンド系、もっとまとめたほうが良いか？Figmaパスだけだとあれですよねぇ。画面遷移図も内容が薄い。 -->
52+
53+
```sh
54+
docs
55+
├── 01_キャッチアップ # ドメイン知識など抑えておくべき前提知識
56+
├── 02_環境構築 #
57+
├── 03_開発規約 # GitFlowなど、リリース方式、CI／CD周り
58+
├── 04_ユーザーストーリー
59+
├── 05_UI設計 # Figmaのパスなど
60+
├── 06_画面設計書
61+
├── 07_API設計書 # OpenAPIのパス＋各BL設計
62+
├── 08_データモデル # ERD, テーブル定義
63+
├── 09_IF設計書 # I/F定義＋受信/送信BL設計
64+
├── 10_バッチ設計書 # タイマー、イベント起動の非同期処理のBL設計
65+
├── 11_インフラ設計 # 監視、キャパシティサイジング、コスト
66+
├── ...
67+
└── README.md
68+
```
69+
70+
## システム構成図
71+
72+
TODO 論理, 物理, etc.
73+
74+
## フロントエンド
75+
76+
- UI設計(Figma)
77+
- [](画面設計書.md)
78+
79+
## バックエンド
80+
81+
### テーブル定義書
82+
83+
A5ER
84+
85+
以下の情報の管理
86+
87+
- 保持期限
88+
- 個人情報有無
89+
90+
パーティションなどはa5erで管理想定
91+
92+
### 区分値
93+
94+
TODO JSON/YAML で管理推奨など
95+
96+
### Web API 設計書
97+
98+
API 定義書は OpenAPI.yaml で記載する
99+
100+
TODO 各エンドポイント毎のプログラム設計
101+
102+
### プログラム設計書
103+
104+
TODO
105+
106+
### I/F 定義書
107+
108+
I/F 定義書は、システム間の連携について定義と、その受信/配信処理の設計書です。
109+
110+
システム I/F は連携先の対向システムが存在するため、認識齟齬が無いように、どのようなプロトコル・項目であるかを定義する必要があります。
111+
112+
- [レイアウト](IF定義書.md)
113+
114+
# Resources
115+
116+
次のリンクから単一ファイルで作成されたコーディング規約を取得できます。
117+
(これらのファイルは[Pandoc]を利用して作成しています。)
118+
119+
- [Markdown](https://github.com/future-architect/coding-standards/blob/master/documents/forMarkdown/xxx.md)
120+
- [HTML](https://github.com/future-architect/coding-standards/blob/gh-pages/resources/xxx.html)
121+
- [Word](https://github.com/future-architect/coding-standards/raw/gh-pages/resources/xxx.docx)
122+
123+
[pandoc]: https://pandoc.org/

‎documents/forMarkdown/future_muscle_partner/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Future Muscle Partner
2+
3+
～いきつけのジムでパーソナルトレーニングを受けよう～ のFuture Muscle Partnerのリポジトリ。
4+
5+
## サービスコンセプト
6+
7+
パーソナルトレーナーを身近なものにして、質が高く安全で楽しいフィットネス体験を提供する。
8+
9+
![アプリを通してトレーニがトレーナに予約し、トレーニングを実施するフロー](docs/future_muscle_partner_abstract.png)
10+
11+
サービス概要:
12+
13+
- アプリ上でジム公認のトレーナーを検索＆予約し、いきつけのジムでトレーニングを受けることができる
14+
15+
主なアクターとメリット:
16+
17+
- トレーニー
18+
- 自分が通っているジムでパーソナル受けられる
19+
- トレーナーの得意分野ごとにトレーナーを使い分けられる
20+
- パーソナルトレーニー
21+
- 24H型ジムでサービスを提供できる
22+
- いつ/誰に/どんなメニューでトレーニングしたかを管理できる
23+
24+
## フォルダ階層
25+
26+
```sh
27+
.
28+
├── backend # バックエンド系のコード
29+
├── docs # 設計書
30+
├── frontend # フロントエンド系のコード
31+
├── infra # インフラ系のコード
32+
```

‎documents/forMarkdown/future_muscle_partner/docs/01_環境構築/README.md‎

Whitespace-only changes.

‎documents/forMarkdown/future_muscle_partner/docs/02_開発規約/README.md‎

Whitespace-only changes.

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

Whitespace-only changes.

0 commit comments

Comments
 (0)