Skip to content

Commit

Permalink
Add markdown design document part (#167)
Browse files Browse the repository at this point in the history 
* 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]>
  • Loading branch information
@ma91n @shotashota
@TsubasaKanemitsu @shibukawa
4 people authored Sep 2, 2024
1 parent a0b54a8 commit 7cf126c
Show file tree
Hide file tree
Showing 27 changed files with 2,441 additions and 115 deletions.
3 changes: 3 additions & 0 deletions .editorconfig
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,6 @@ charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
end_of_line = lf

[*.md]
trim_trailing_whitespace = false
67 changes: 67 additions & 0 deletions documents/forMarkdown/API_GET.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# [機能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 | |

163 changes: 163 additions & 0 deletions documents/forMarkdown/IF定義書.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# IF01 設備有効開始受信

設備有効開始の取り込みを行う。

## 対向システム

| 連携元 | 連携先 |
| ---------- | ------ |
| A システム | Future |

## 環境情報

### Input

| Item | Value |
| ---------------- | ------------------------------------------------ |
| 連携 S3 バケット | `${env}-example-import` |
| プレフィックス | `activate/year=${yyyy}/month=${MM}/day=${dd}/` |
| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` |
| 保持期限 | 3 年 |

### Output

| Item | Value |
| ---------------- | ------------------------------------------------ |
| 連携 S3 バケット | `${env}-example-import` |
| プレフィックス | `activate/year=${yyyy}/month=${MM}/day=${dd}/` |
| ファイル名 | `${yyyy}-${mm}-${dd}-${hh}-${MM}-${SS}.csv` |
| 保持期限 | 3 年 |

## 連携元定義

| Category | Item | Value | Memo |
| -------- | ----------------------------------- | --------- | -------------------- |
| Protocol | 連携方式（ファイル/API/ストリーム） | ファイル | |
| | 連携タイミング（随時/定時） | 定時 | |
| | 頻度 | 1 回/日 | |
| | 起動時間 | **16:00** | |
| | 処理完了期限 | **16:00** | |
| | 未着チェック（なし/WARN/ERROR） | WARN | |
| | 全件/差分 | 差分 | |
| | 0 件時連携 | あり | |
| Format | ファイル種別 | **CSV** | |
| | レイアウト | RFC 8259 | |
| | 文字コード | UTF-8 | |
| | 改行コード | LF | |
| | 圧縮 | - | |
| | 暗号化 | - | |
| | ヘッダ行 | あり | |
| | 項目順 | 固定 | 項目順は入れ替え不可 |
| | 機密情報 | - | |

### 項目定義

| Name | Physical Name | Type | Length | Precision | Enum | Format | Sensitive | Example | Memo |
| ---------- | --------------- | ------ | ------ | --------- | ---- | ---------- | --------- | ---------- | ---- |
| 会社コード | company_cd | string | 5 | - | - | - | - | 00001 | |
| 設備コード | device_cd | string | 8 | - | - | - | - | 00000052 | |
| 有効開始日 | activation_date | string | 10 | - | - | YYYY-MM-DD | - | 2022-10-16 | [^1] |

[^1]: 現在日以降である必要があるが、受信ではテスト観点で過去日も許容する

#### サンプル

```csv
company_cd,device_cd,activation_date
12121,00000052,2022-03-01
12121,00000053,2022-03-30
```

## 連携先定義

| Category | Item | Value | Memo |
| -------- | ----------------------------------- | --------- | -------------------- |
| Protocol | 連携方式（ファイル/API/ストリーム） | ファイル | |
| | 連携タイミング（随時/定時） | 定時 | |
| | 頻度 | 1 回/日 | |
| | 起動時間 | **16:00** | |
| | 処理完了期限 | **16:00** | |
| | 未着チェック（なし/WARN/ERROR） | WARN | |
| | 全件/差分 | 差分 | |
| | 0 件時連携 | あり | |
| Format | ファイル種別 | **CSV** | |
| | レイアウト | RFC 8259 | |
| | 文字コード | UTF-8 | |
| | 改行コード | LF | |
| | 圧縮 | - | |
| | 暗号化 | - | |
| | ヘッダ行 | あり | |
| | 項目順 | 固定 | 項目順は入れ替え不可 |
| | 機密情報 | - | |



## 処理概要

- ファイル定義に則ったバリデーションを実施
- 次の項目変換定義に従い加工し、出力先テーブルに Merge する
- 受信完了後、 Completed: YYYY-MM-DDTHH:MI:SS.SSS のタグを追加する

## 処理シーケンス

```plantuml
@startuml
!theme toy
participant システム
participant S3
database DB
システム -> DB: 処理日付取得\n[日付管理]
システム -> S3: 対象ファイルの存在チェック
alt ファイルが存在しなかった場合
システム -> システム: 処理終了して、次の処理を待機
end
システム -> DB: シーケンスの取得\n[シーケンスオブジェクト]
システム -> DB: 1.実行開始レコード追加\n[IF受信管理]
システム -> S3: 対象ファイルを取得
システム -> DB: 対象マスタのTruncate
システム -> DB: ファイル連携処理
システム -> システム: 連携件数確認
システム -> S3: 処理済対象ファイルを格納
システム -> DB: 2.実行終了状態の更新\n[IF受信管理]
@enduml
```

## DB 項目

### 参照

なし

### 登録

リストワークに以下のカラムでレコードを登録する

- xxx ワーク.会社コード
- xxx ワーク.処理日付
- xxx ワーク.yyy 区分

### 更新

なし

## ビジネスロジック

特記事項なし

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

123 changes: 123 additions & 0 deletions documents/forMarkdown/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
---
sidebarDepth: 4
author: フューチャー株式会社
home: true
heroText: Markdown設計ドキュメント規約
tagline: Future Enterprise Markdown Design Document Standards
pageClass: lang-home
footer: ©2015 - 2024 Future Enterprise Coding Standards - Future Corporation
---

Markdown ベースの設計ドキュメントの規約をまとめる。

システム開発にて利用する設計ドキュメントを Markdown ベースにすることで、コーディングと同じ慣れたツールを用いて、Git によるバージョン管理、レビュープロセス、CI/CD などに自動化（静的解析、自動生成）を行いやすくし、ドキュメントを陳腐化させず、俊敏な設計開発を目指す。

Markdown に限った話では無いが、どういった内容を設計書に記載すべきかは悩むポイントは多い。

本規約では、アプリケーションの種別ごとに記載すべき内容と、それをどのような Markdown の構造で記載するかを規約化し、各チームで悩む余地を減らし、注力すべきことに集中できる環境を提供することを目的とする。

## 前提

本規約は以下の前提で作成されている

- チーム/プロジェクトが 3 ～ 30 名程度規模程度
- Git（GitHub, GitLab）で管理され、コードと設計書が同一リポジトリで管理される
- システム開発で必要なアプリケーション開発

## フォルダ階層

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

<!-- TODO 【相談】docsだと公開フォルダとみなされるかもなので、documentsとかにしたほうが良いか？ -->

次はバックエンド、フロントエンド、インフラのコードをモノリポで管理している例である。

```sh
.
├── backend # バックエンド系のコード
├── docs
├── frontend # フロントエンド系のコード
├── infrastructure # インフラ系のコード
```

`docs` 配下は以下のルールにしたがった構造を取る。

- `01_`、`02_` といったプレフィックスを持つ
- 番号には体系をもたせず、必要になったタイミングでインクリメントさせる
- オンボーディングコストを抑えるため、なるべく先頭に新規参画者が欲する情報を配備する

構成例を次にあげる。

<!-- TODO 【相談】フロントエンド系、もっとまとめたほうが良いか？Figmaパスだけだとあれですよねぇ。画面遷移図も内容が薄い。 -->

```sh
docs
├── 01_キャッチアップ # ドメイン知識など抑えておくべき前提知識
├── 02_環境構築 #
├── 03_開発規約 # GitFlowなど、リリース方式、CI／CD周り
├── 04_ユーザーストーリー
├── 05_UI設計 # Figmaのパスなど
├── 06_画面設計書
├── 07_API設計書 # OpenAPIのパス＋各BL設計
├── 08_データモデル # ERD, テーブル定義
├── 09_IF設計書 # I/F定義＋受信/送信BL設計
├── 10_バッチ設計書 # タイマー、イベント起動の非同期処理のBL設計
├── 11_インフラ設計 # 監視、キャパシティサイジング、コスト
├── ...
└── README.md
```

## システム構成図

TODO 論理, 物理, etc.

## フロントエンド

- UI設計(Figma)
- [](画面設計書.md)

## バックエンド

### テーブル定義書

A5ER

以下の情報の管理

- 保持期限
- 個人情報有無

パーティションなどはa5erで管理想定

### 区分値

TODO JSON/YAML で管理推奨など

### Web API 設計書

API 定義書は OpenAPI.yaml で記載する

TODO 各エンドポイント毎のプログラム設計

### プログラム設計書

TODO

### I/F 定義書

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

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

- [レイアウト](IF定義書.md)

# Resources

次のリンクから単一ファイルで作成されたコーディング規約を取得できます。
(これらのファイルは[Pandoc]を利用して作成しています。)

- [Markdown](https://github.com/future-architect/coding-standards/blob/master/documents/forMarkdown/xxx.md)
- [HTML](https://github.com/future-architect/coding-standards/blob/gh-pages/resources/xxx.html)
- [Word](https://github.com/future-architect/coding-standards/raw/gh-pages/resources/xxx.docx)

[pandoc]: https://pandoc.org/
32 changes: 32 additions & 0 deletions documents/forMarkdown/future_muscle_partner/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Future Muscle Partner

～いきつけのジムでパーソナルトレーニングを受けよう～ のFuture Muscle Partnerのリポジトリ。

## サービスコンセプト

パーソナルトレーナーを身近なものにして、質が高く安全で楽しいフィットネス体験を提供する。

![アプリを通してトレーニがトレーナに予約し、トレーニングを実施するフロー](docs/future_muscle_partner_abstract.png)

サービス概要:

- アプリ上でジム公認のトレーナーを検索＆予約し、いきつけのジムでトレーニングを受けることができる

主なアクターとメリット:

- トレーニー
- 自分が通っているジムでパーソナル受けられる
- トレーナーの得意分野ごとにトレーナーを使い分けられる
- パーソナルトレーニー
- 24H型ジムでサービスを提供できる
- いつ/誰に/どんなメニューでトレーニングしたかを管理できる

## フォルダ階層

```sh
.
├── backend # バックエンド系のコード
├── docs # 設計書
├── frontend # フロントエンド系のコード
├── infra # インフラ系のコード
```
Empty file added documents/forMarkdown/future_muscle_partner/docs/01_環境構築/README.md
View file
Empty file.
Empty file added documents/forMarkdown/future_muscle_partner/docs/02_開発規約/README.md
View file
Empty file.
Empty file added documents/forMarkdown/future_muscle_partner/docs/03_画面/README.md
View file
Empty file.
Loading

0 comments on commit 7cf126c

Please sign in to comment.