Pleasanterをバックグラウンドに利用して販売・注文管理システムを構築した #4 Entity・API連携(前編)

はじめに

Pleasanterをバックグラウンドに利用して販売・注文管理システム構築の4回目、今回はEntity・API連携構築編です。
長くなりますので、前後編に分けて作っていきたいと思います。
第一回(構成)
第二回(環境構築)
第三回(Pleasanter設計)
前回Pleasanter側に登録用のサイトを作成しましたので、前回設計したPleasanterサイトに対して C# (.NET 9 / ASP.NET Core) からEntity・APIで連携する実装について説明します。

レイヤ構成

Controller
   ↓
Process（業務ロジック・ユースケース単位）
   ↓
IPleasanterApiBridge / IPleasanterRepository（共通ライブラリ）
   ↓
Pleasanter REST API

定義

• Entity
  • Pleasanterのレコード1行に対応するDTO。Pleasanter側のカラム名 (ClassA, NumA …) と1:1で対応
• Process
  • 1ユースケース（注文する／支払う／参加者を取得する 等）を1クラスで表現
• Bridge / Repository
  • Pleasanter API呼び出しを共通化したライブラリ (PleasanterBridge)。Insert / Select などを提供

PleasanterカラムとEntityマッピング

Entity設計

基底/ApiEntity

PleasanterのAPIはリクエストJSONに ApiVersionとApiKey を必須で含める必要があります。まずはこの値を持つ基底Entityを作成します。

public class ApiEntity : ApiKeyProperty
{
    public string ApiVersion { get; set; } = "1.1";
    public new string ApiKey { get; set; }

    public ApiEntity()
    {
        ApiKey = base.ApiKey!;
    }
}

各Entity

Pleasanterのサイトは、項目を作るとデータ上は内部的に ClassA, ClassB, ... / NumA, NumB, ... / DescriptionA, ... / CheckA, ... / DateA, ... という固定カラムに割り当てられます。
そのため、Entityはカラム名をプロパティ名にし、コメントで意味を補足する書き方が安全です。
コンストラクタの引数名はPleasanter上の項目名と揃えておく(対応するようにする)とわかりやすいです。

商品/PurchaseDataEntity

Pleasanterで定義した商品と対応するEntityです。

public class PurchaseDataEntity
{
    public long?   ResultId      { get; set; } // PleasanterのResultId
    public string? PurchaseName  { get; set; } // 商品名
    public string? Yomi          { get; set; } // 読み
    public string? Image         { get; set; } // 写真
    public string? Unit          { get; set; } // 単位
    public int     UnitPrice     { get; set; } // 単価
    public int     SellingPrice  { get; set; } // 売値（販売価格）
    public int     OrderCount    { get; set; } // 注文数
    public bool    Hide          { get; set; } // 隠す

    public PurchaseDataEntity(
        long? resultId,
        string? purchaseName,
        string? yomi,
        string? image,
        string? unit,
        int unitPrice,
        int sellingPrice,
        int orderCount,
        bool hide)
    {
        ResultId     = resultId;
        PurchaseName = purchaseName;
        Yomi         = yomi;
        Image        = image;
        Unit         = unit;
        UnitPrice    = unitPrice;
        SellingPrice = sellingPrice;
        OrderCount   = orderCount;
        Hide         = hide;
    }
}

イベント参加者/JoinerEntity

Pleasanterで定義した参加者と対応するEntity。

public class JoinerEntity
{
    public string? EventId       { get; set; }
    public string? UserCd        { get; set; }
    public string? UserName      { get; set; }
    public string? Sex           { get; set; }
    public string? Contact       { get; set; }
    public string? HandoverNotes { get; set; }
    public bool    IsAdmin       { get; set; }

    public JoinerEntity(
        string? eventId, string? userCd, string? userName,
        string? sex, string? contact, string? handoverNotes,
        bool isAdmin = false)
    {
        EventId       = eventId;
        UserCd        = userCd;
        UserName      = userName;
        Sex           = sex;
        Contact       = contact;
        HandoverNotes = handoverNotes;
        IsAdmin       = isAdmin;
    }
}

注文/SendOrderEntity

Pleasanterで定義した注文と対応するEntity。

public class SendOrderEntity : ApiEntity
{
    public string ClassA { get; set; } // EventId
    public string ClassB { get; set; } // UserCd（注文者）
    public string ClassC { get; set; } // 商品ResultId
    public string ClassD { get; set; } // 単位
    public int    NumA   { get; set; } // 数量
    public int    NumB   { get; set; } // 金額（売値 × 数量）
    public bool   CheckA { get; set; } // 未提供

    public SendOrderEntity(
        string eventId,
        string userCd,
        string purchaseResultId,
        string unit,
        int quantity,
        int amount,
        bool notServed = true)
    {
        ClassA = eventId;
        ClassB = userCd;
        ClassC = purchaseResultId;
        ClassD = unit;
        NumA   = quantity;
        NumB   = amount;
        CheckA = notServed;
    }
}

支払/SendPaymentEntity

Pleasanterで定義した支払と対応するEntity。

public class SendPaymentEntity : ApiEntity
{
    public string ClassA { get; set; } // EventId
    public string ClassB { get; set; } // UserCd
    public int    NumA   { get; set; } // 金額（合計）
}

まとめ

以上で、Entity・API連携用の構築は完了です。
後編では実際に、API経由でデータを登録したり取得したりするロジックについて記載していきます。