サンプルアプリケーション（Dressca）解説のドキュメントを作成する

[tsuna-can-se]

目次案

サンプルアプリケーション（Dressca）解説

サンプルアプリケーションの概要

• システムの位置づけ（架空の会社の架空システムという体にして、その解説とする）
  • どういう会社（Dressca社）
  • どういうシステム（アパレルのショッピングシステム）

システムの全体像

• システムユースケース（ユースケース図）
• データモデル
  • 概念データモデル
  • 論理データモデル
• システム構成図（クラウド環境前提で、実際に今後サンプルAPの配置場所として使うサーバーの構成を記述する）

前提知識

サンプルAPの構造を知るにあたって必要となる前提知識へのリンク

• ASP.NET Coreのミドルウェア
• 依存性の注入
• Web APIのレスポンス形式
• Open API Specification（NSwagとOpen API Generatorを使った自動生成）
• クリーンアーキテクチャ
• DDD

アプリケーションアーキテクチャ

• レイヤー構造

• プロジェクト構造

• ディレクトリ構成

  https://github.com/dotnet-architecture/eShopOnWeb/wiki/Getting-Started-for-Beginners
  これは書きすぎな気がするけどこんなものをイメージ。
  各層やコンポーネントの詳細説明は後述する。
  超お手軽単純な手順はクイックスタートに書きたい。
  うまくすみ分ける。
  こちらではVSとVS Code両方の手順を示したい。

  routerのディレクトリ構成はアーキテクチャと比較すると少し冗長。
  こういう構成も取れる、という説明をここに書きたい。

• トランザクション管理方針

• 例外処理方針

• ログ出力方針

• 入力値検証方針

アプリケーションコア層の構造

この章と同じような構成で、実装レベルの解説を細かく行っていくイメージ。
フロント側も解説対象。

• Dressca.ApplicationCore：できる限り外部ライブラリに依存しない、外部環境に影響を受けないよう安定性を重視
  • ディレクトリ構造：業務で分割し、クラスをその中に直接配置する（コンポーネントの種類でディレクトリ分割しない）
  • コンポーネント構造 ：サンプルAPにおける層の中の構造を図にしたい
  • コンポーネントの詳細：各コンポーネントの作り方、命名規則
    • エンティティ
    • 値オブジェクト：recordにする
    • ドメインサービス
    • アプリケーションサービス
    • リポジトリインターフェース
  • DIの設定：ドメインサービスとアプリケーションサービスをDIコンテナーに登録する、実行時に差し替えないのでインターフェースは作らない

その他の修正箇所

アプリケーション開発ガイド .NET編

index.md

「業務機能の開発方法について解説しません。」の後に「業務機能の開発についてはサンプルアプリケーション解説を参照してください。」のような形でこのドキュメントに参照を貼りたい。

[KentaHizume]

2024/12/20 追記案

#2101 (comment)

アプリケーションコア層の構造

• Dressca.Web.Consumer.Dto/Dressca.Web.Admin.Dto

  • ディレクトリ構造：名前空間で対象のコントローラーを識別する

    • (例) Web.Admin の CatalogBrandsController で使用するDtoであれば、 Dressca.Web.Dto.Admin.CatalogBrands 配下に配置する

  • 作成単位：API エンドポイントが持つ HTTP メソッド（アクションメソッド）について、最大でRequestに対して1つ、Responseに対して1つずつDtoクラスが対応するように作成する。

    • GET に対応するアクションメソッド GetXXXAsync に対して、GetXXXRequest と、GetXXXResponse を作成する。

  • 命名規則：クラス名で対象のコントローラーのアクションメソッドと、In/Outを識別する

    • ( In の例) アクションメソッド PostCatalogItemAsync で使用する Dto であれば、PostCatalogItemRequest と命名する
    • ( Out の例) アクションメソッド GetCatalogBrandsAsyncで使用する Dto であれば、 GetCatalogBrandsResponse と命名する

  • モデルの命名：Dto用のモデルは、ドメインモデル名の末尾に ApiModel を付加したクラス名にする。

    • （例）ドメインモデル名が CatalogItem の場合、 CatalogItemApiModel とする。

  • フィールド：　

    • Dtoのフィールドに複数のオブジェクトが含まれることは問題ない。
      • (例) GetCatalogItemResponse が PagedList<CatalogItemApiModel> を持つ。　

  • プロパティ

    • 初期化が必須のプロパティには空のインスタンスや空文字を設定するのではなく、required修飾子を使用する

    　

[KentaHizume]

ドメインモデル図

TODO

• 集約ルートのエンティティがどれかわかるように太字や下線を引く
• 多重度の矢印をつける
• 適切な補足のメモをつける

classDiagram

namespace カタログ集約 {

class カタログアイテム {
  ID
  名前
  説明
  単価
  商品コード
  カタログカテゴリID
  カタログブランドID
  行バージョン
}

class カタログアイテムアセット {
  ID
  アセットコード
  商品アイテムID
}

}

カタログアイテム "1" -- "0..*" カタログアイテムアセット 

namespace カタログブランド集約 {

class カタログブランド {
  ID
  ブランド名
}

}

namespace カタログカテゴリ集約 {

class カタログカテゴリ {
  ID
  カテゴリ名
}

}

namespace 買い物かご集約{

class 買い物かご {
  ID
  購入者ID
}

class 買い物かごアイテム {
  ID
  買い物かごID
  カタログアイテムID
  単価
  数量
}

}

買い物かご "1" -- "0..*" 買い物かごアイテム

namespace 注文集約 {

class 注文 {
  ID
  購入者ID
  注文日
  消費税率
  アイテム合計価格
  配送料
  消費税
  合計金額
  配送先氏名
  配送先住所
}

class 注文アイテム {
  ID
  単価
  数量
  注文ID
  注文された商品アイテムID
  注文された商品コード
  注文された商品名
}

class 注文アイテムアセット {
  ID
  アセットコード
  注文アイテムID
}

}

注文 "1" -- "0..*" 注文アイテム
注文アイテム "1" -- "0..*" 注文アイテムアセット

namespace アセット集約 {

class アセット {
  ID
  アセットコード
  アセットタイプ
}

}

namespace ユーザー集約 {

class ユーザー {
    ID
    ユーザー名
    ロール
}

}

Loading

[KentaHizume]

ユースケース図

mermaid ではユースケース図は対応中のため、
代替としてフローチャートを使ってユースケース図を表現しています。

• Add Use Case diagram type mermaid-js/mermaid#4628

graph TB
    subgraph "Dressca"
        Consumer((顧客))
        Administrator((管理者))
        subgraph "カタログ"
            GetCatalogItems[カタログを表示する]
            GetCatalogItemsForAdmin[管理者用カタログを表示する]
            AddItemToCatalog[カタログにアイテムを追加する]
            DeleteItemFromCatalog[カタログからアイテムを削除する]
            UpdateCatalogItem[カタログのアイテムを更新する]
        end
        subgraph "買い物"
            AddItemToBasket[買い物かごにアイテムを追加する]
            RemoveItemFromBasket[買い物かごのアイテムを削除する]
            SetBasketItemsQuantities[買い物かごのアイテムの数量を変更する]
            GetBasketItems[買い物かごのアイテムの一覧を取得する]
            Checkout[買い物かご内のアイテムを注文する]
        end
        subgraph "注文"
            GetOrder[注文情報を取得する]
        end
    end
    Consumer --> GetCatalogItems
    Consumer --> AddItemToBasket
    Consumer --> RemoveItemFromBasket
    Consumer --> SetBasketItemsQuantities
    Consumer --> GetBasketItems
    Consumer --> Checkout
    Consumer --> GetOrder

    Administrator --> GetCatalogItemsForAdmin
    Administrator --> AddItemToCatalog
    Administrator --> DeleteItemFromCatalog
    Administrator --> UpdateCatalogItem

Loading