労働者追加までの protobuf 定義 アプリケーションの MVP を作るにあたり、とりあえず基礎を作るのに必要な データモデル定義をする必要があった。勤怠や休暇の記録を付けるにもまず 労働者の登録が必要だったため、この定義を優先して行った。 設定ファイルやドキュメントは protobuf やそれに関連するツールの追加に 伴い必要になったもの。

Changes

30 changed files (+418/-1)

• .editorconfig
  • @@ -17,3 +17,9 @@
    [*.md] # Markdown では末尾スペース 2 つが改行として扱われる。 trim_trailing_whitespace = true + + # Protocol Buffers の公式スタイルガイドに準拠。 + # <https://protobuf.dev/programming-guides/style/> + [*.proto] + indent_style = space + indent_size = 2
• .gitignore (new)
  • @@ -0,0 +1,6 @@
    + # SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + # SPDX-License-Identifier: AGPL-3.0-only + + # What: Node.js 及び互換ツールが依存パッケージを格納するディレクトリ。 + # Why: サイズが非常に大きく、可読性も低いため。 + node_modules
• .tool-versions
  • @@ -4,3 +4,4 @@ #
    # SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> # SPDX-License-Identifier: AGPL-3.0-only dprint 0.47.5 + bun 1.1.38
• bun.lockb (new)
• bun.lockb.license (new)
  • @@ -0,0 +1,5 @@
    + 自動生成のバイナリファイルだが、著作権・ライセンスの所在を決めておかないと + 利用側が面倒なため他のソースコードと同様の扱いとする。 + + SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + SPDX-License-Identifier: AGPL-3.0-only
• docs/DEVELOPMENT.md (new)
  • @@ -0,0 +1,46 @@
    + <!-- + SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + SPDX-License-Identifier: AGPL-3.0-only + --> + + # 開発ガイド + + [bun]: https://bun.sh/ + [dprint]: https://dprint.dev/ + + ## 前提環境 + + このプロジェクトを開発するにあたり以下のものが必要になる。 + + - [Bun][bun] v1.1.x + - [dprint][dprint] v0.47.x + - [reuse tool](https://github.com/fsfe/reuse-tool) v4 以上 + + `.tool-versions` に対応した [asdf](https://asdf-vm.com/) や [mise](https://mise.jdx.dev/) といったバージョン管理ツールの利用を強く推奨。 + + ## JavaScript パッケージのインストール + + [Bun][bun] の Workspace 機能を利用しているため、リポジトリルートで `bun i` を実行すれば各パッケージで必要な全ての依存パッケージがインストールされる。 + + ``` + $ bun i + ``` + + この作業は `package.json` や `bun.lockb` に変更があった際に毎回実行する必要がある。 + + ## ソースコードの自動整形 + + [dprint][dprint] を使ってソースコードの自動整形を統一して行えるようになっている。 + + ``` + $ dprint fmt + ``` + + ## 著作権とライセンス表記のチェック + + このプロジェクトは [REUSE v3.3](https://reuse.software/spec-3.3/) に準拠した著作権とライセンス表記を行っている。 + 以下のコマンドで全てのファイルに適切に著作権とライセンスの表記がされているか確認できる。 + + ``` + $ reuse lint + ```
• dprint.jsonc
  • @@ -10,9 +10,18 @@ },
    "markdown": { "lineWidth": 100 }, + "exec": { + "commands": [ + { + "exts": ["proto"], + "command": "bunx buf format {{file_path}}" + } + ] + }, "plugins": [ "https://plugins.dprint.dev/markdown-0.17.8.wasm", // "Biome is a fast formatter for JavaScript, TypeScript, JSX, TSX, JSON, CSS and GraphQL..." - "https://plugins.dprint.dev/biome-0.7.1.wasm" + "https://plugins.dprint.dev/biome-0.7.1.wasm", + "https://plugins.dprint.dev/exec-0.5.0.json@8d9972eee71fa1590e04873540421f3eda7674d0f1aae3d7c788615e7b7413d0" ] }
• package.json (new)
  • @@ -0,0 +1,11 @@
    + { + "name": "@yamori/workspace", + "private": true, + "workspaces": ["packages/*"], + "scripts": { + "lint": "bun run --filter '*' lint" + }, + "devDependencies": { + "@bufbuild/buf": "^1.47.2" + } + }
• package.json.license (new)
  • @@ -0,0 +1,2 @@
    + SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + SPDX-License-Identifier: AGPL-3.0-only
• packages/proto/README.md (new)
  • @@ -0,0 +1,16 @@
    + <!-- + SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + SPDX-License-Identifier: AGPL-3.0-only + --> + + # `proto` + + このプロジェクトで取り扱う Protocol Buffers のデータ定義が全てまとまっているディレクトリ。 + + ## 品質チェック + + このプロジェクトでは [Buf CLI](https://buf.build/docs/cli/) を使って Protobuf ファイルの品質をチェックしている。以下のコマンドでチェックを実行できる。 + + ``` + $ bun lint + ```
• packages/proto/package.json (new)
  • @@ -0,0 +1,7 @@
    + { + "name": "@yamori/proto", + "private": true, + "scripts": { + "lint": "buf lint" + } + }
• packages/proto/package.json.license (new)
  • @@ -0,0 +1,2 @@
    + SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + SPDX-License-Identifier: AGPL-3.0-only
• packages/proto/yamori/error/v1/missing_field_error.proto (new)
  • @@ -0,0 +1,13 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.error.v1; + + // メッセージにおいて指定が必須のフィールドが指定されていない場合のエラー。 + message MissingFieldError { + // 必須だが空のフィールドのパス。記法は google.protobuf.FieldMask と同様。 + // <https://github.com/protocolbuffers/protobuf/blob/5d0865cf1537772b8e0969563402654087b40d31/src/google/protobuf/field_mask.proto> + string path = 1; + }
• packages/proto/yamori/error/v1/no_storage_space.proto (new)
  • @@ -0,0 +1,12 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.error.v1; + + // データをこれ以上保存できない場合のエラー。 + message NoStorageSpace { + // デバッグ・調査用のメッセージ。 + string message = 1; + }
• packages/proto/yamori/error/v1/not_implemented.proto (new)
  • @@ -0,0 +1,16 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.error.v1; + + // メソッドが未実装の際のエラー。 + message NotImplemented { + // 開発者向けの詳細。バックエンドで既知のメソッドを実装できない場合 + // などに理由のメッセージが入る。 + string details = 1; + + // 対象のメソッド。 + string method = 2; + }
• packages/proto/yamori/error/v1/system_error.proto (new)
  • @@ -0,0 +1,19 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.error.v1; + + // 予期せぬエラー。事前に定義されていないエラーは全てこのメッセージ + // で表される。また、プラットフォーム・配布形態固有のため各サービス + // で定義できないものもこれで表される。 + message SystemError { + // エラーを識別するためのシステム文字列。デバッグ・調査時の補助目的。 + string code = 1; + + // デバッグ・調査用のエラーメッセージ。システム的なものであるため + // ユーザに表示する内容ではない。完全に原因不明のクラッシュなどで + // メッセージが存在しない場合もある。 + string message = 2; + }
• packages/proto/yamori/idempotency/v1/key.proto (new)
  • @@ -0,0 +1,13 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.idempotency.v1; + + // 冪等性を確保するための任意文字列。リクエストを発行する側が + // 生成してリクエストに付与する。冪等性が必要なメソッドはこの + // メッセージをフィールドに持つこと。 + message Key { + string value = 1; + }
• packages/proto/yamori/worker/v1/create_request.proto (new)
  • @@ -0,0 +1,19 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.worker.v1; + + import "yamori/idempotency/v1/key.proto"; + import "yamori/workspace/v1/workspace_id.proto"; + + message CreateRequest { + yamori.idempotency.v1.Key idempotency_key = 1; + + // [必須] 労働者を作成するワークスペースの ID 。 + yamori.workspace.v1.WorkspaceID workspace_id = 2; + + // [必須] 労働者の表示名。 + string display_name = 3; + }
• packages/proto/yamori/worker/v1/create_response.proto (new)
  • @@ -0,0 +1,31 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.worker.v1; + + import "yamori/error/v1/missing_field_error.proto"; + import "yamori/error/v1/system_error.proto"; + import "yamori/worker/v1/worker.proto"; + import "yamori/workspace/v1/access_error.proto"; + + message CreateResponse { + message Result { + // 作成された労働者。 + Worker worker = 1; + } + + oneof result { + Result ok = 1; + + // 指定されたワークスペースにアクセスできないため作成されなかった。 + yamori.workspace.v1.AccessError workspace_access_error = 2; + + // システムエラーが発生した。 + yamori.error.v1.SystemError system_error = 3; + + // 必須フィールドに値が入っていないため作成されなかった。 + yamori.error.v1.MissingFieldError missing_field = 4; + } + }
• packages/proto/yamori/worker/v1/worker.proto (new)
  • @@ -0,0 +1,16 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.worker.v1; + + import "yamori/worker/v1/worker_id.proto"; + + // 被雇用の労働者を表す。 + message Worker { + WorkerID id = 1; + + // 労働者の表示名。 + string display_name = 2; + }
• packages/proto/yamori/worker/v1/worker_id.proto (new)
  • @@ -0,0 +1,12 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.worker.v1; + + // システムによって割り振られたワークスペース内で一意の識別子。 + // 労働者の ID は `wr-` というプリフィクスを持つ。 + message WorkerID { + string value = 1; + }
• packages/proto/yamori/worker/v1/worker_service.proto (new)
  • @@ -0,0 +1,14 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.worker.v1; + + import "yamori/worker/v1/create_request.proto"; + import "yamori/worker/v1/create_response.proto"; + + service WorkerService { + // ワークスペース内に労働者を新規登録する。 + rpc Create(CreateRequest) returns (CreateResponse); + }
• packages/proto/yamori/workspace/v1/access_error.proto (new)
  • @@ -0,0 +1,15 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + import "yamori/workspace/v1/workspace_id.proto"; + + // ワークスペースにアクセスできない場合のエラー。 + // 理由は様々だが、セキュリティのために詳細は含まれない。 + message AccessError { + // アクセスできなかった対象のワークスペースの ID 。 + WorkspaceID workspace_id = 1; + }
• packages/proto/yamori/workspace/v1/create_request.proto (new)
  • @@ -0,0 +1,15 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + import "yamori/idempotency/v1/key.proto"; + + message CreateRequest { + yamori.idempotency.v1.Key idempotency_key = 1; + + // [必須] ワークスペースの表示名。 + string display_name = 2; + }
• packages/proto/yamori/workspace/v1/create_response.proto (new)
  • @@ -0,0 +1,31 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + import "yamori/error/v1/missing_field_error.proto"; + import "yamori/error/v1/no_storage_space.proto"; + import "yamori/error/v1/system_error.proto"; + import "yamori/workspace/v1/workspace.proto"; + + message CreateResponse { + message Result { + // 作成されたワークスペース。 + Workspace workspace = 1; + } + + oneof result { + Result ok = 1; + + // 保存領域がないため保存できなかった。 + yamori.error.v1.NoStorageSpace no_storage_space = 2; + + // システムエラーが発生した。 + yamori.error.v1.SystemError system_error = 3; + + // 必須フィールドに値が入っていないため保存されなかった。 + yamori.error.v1.MissingFieldError missing_field = 4; + } + }
• packages/proto/yamori/workspace/v1/key_value_storage_based_workspace_service.proto (new)
  • @@ -0,0 +1,19 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + import "yamori/workspace/v1/create_request.proto"; + import "yamori/workspace/v1/create_response.proto"; + import "yamori/workspace/v1/list_request.proto"; + import "yamori/workspace/v1/list_response.proto"; + + service KeyValueStorageBasedWorkspaceService { + // アクセス可能なワークスペースの一覧を返す。 + rpc List(ListRequest) returns (ListResponse); + + // ワークスペースを新規作成する。 + rpc Create(CreateRequest) returns (CreateResponse); + }
• packages/proto/yamori/workspace/v1/list_request.proto (new)
  • @@ -0,0 +1,8 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + message ListRequest {}
• packages/proto/yamori/workspace/v1/list_response.proto (new)
  • @@ -0,0 +1,23 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + import "yamori/error/v1/system_error.proto"; + import "yamori/workspace/v1/workspace.proto"; + + message ListResponse { + message Result { + // アクセス可能なワークスペースの一覧。 + repeated Workspace workspaces = 1; + } + + oneof result { + Result ok = 1; + + // システムエラーが発生したため一覧を取得できなかった。 + yamori.error.v1.SystemError system_error = 2; + } + }
• packages/proto/yamori/workspace/v1/workspace.proto (new)
  • @@ -0,0 +1,18 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + import "yamori/workspace/v1/workspace_id.proto"; + + // 労働者や勤怠記録といった全てのデータの管理単位。 + // 会社や組織と考えて問題ない。 + message Workspace { + WorkspaceID id = 1; + + // ワークスペースの表示名。ユーザが選択する際などに識別 + // するための human readable な名前。 + string display_name = 2; + }
• packages/proto/yamori/workspace/v1/workspace_id.proto (new)
  • @@ -0,0 +1,12 @@
    + // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com> + // SPDX-License-Identifier: AGPL-3.0-only + + edition = "2023"; + + package yamori.workspace.v1; + + // システムによって割り振られたシステム内で一意の識別子。 + // ワークスペースの ID は `ws-` というプリフィクスを持つ。 + message WorkspaceID { + string value = 1; + }