@shisyamo4131/air-guard-v2-schemas 2.4.2-dev.8 → 2.4.2-dev.80

package/src/SiteOperationScheduleDetail.js

@@ -1,68 +1,78 @@
 /*****************************************************************************
- * SiteOperationScheduleDetail ver 1.0.0
+ * @file ./src/SiteOperationScheduleDetail.js
  * @author shisyamo4131
- * ---------------------------------------------------------------------------
- * - Model representing the details of a site operation schedule.
- * - Inherits from OperationDetail.
- * ---------------------------------------------------------------------------
- * @prop {string} siteOperationScheduleId - Site Operation Schedule ID
- * @prop {boolean} hasNotification - Notification flag
- * ---------------------------------------------------------------------------
- * @computed {string} notificationKey - Notification key (read-only)
- * - Concatenation of `siteOperationScheduleId` and `workerId` with '-'
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from OperationDetail:
- * @prop {string} id - Employee or Outsourcer document ID
- * @prop {number} index - Identifier index for Outsourcer (always 0 for Employee)
- * @prop {boolean} isEmployee - Employee flag (true: Employee, false: Outsourcer)
- * @prop {number} amount - Number of placements (always fixed at 1)
- * @prop {string} siteId - Site ID
- * @prop {boolean} isQualified - Qualified flag
- * @prop {boolean} isOjt - OJT flag
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from OperationDetail:
- * @computed {string} workerId - Worker ID (read-only)
- * - For Employee, it's the same as `id`, for Outsourcer, it's a concatenation of `id` and `index` with ':'
- * @computed {string|null} employeeId - Employee ID (null if not applicable) (read-only)
- * @computed {string|null} outsourcerId - Outsourcer ID (null if not applicable) (read-only)
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from WorkingResult (via OperationDetail):
- * @prop {Date} dateAt - Placement date (trigger property)
- * @prop {string} dayType - Day type (e.g., `WEEKDAY`, `WEEKEND`, `HOLIDAY`)
- * @prop {string} shiftType - `DAY` or `NIGHT`
- * @prop {string} startTime - Start time (HH:MM format)
- * @prop {boolean} isStartNextDay - Next day start flag
- * @prop {string} endTime - End time (HH:MM format)
- * @prop {number} breakMinutes - Break time (minutes)
- * @prop {number} regulationWorkMinutes - Regulation work minutes
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from WorkingResult (via OperationDetail):
- * @computed {string} key - Unique key combining `date`, `dayType`, and `shiftType` (read-only)
- * @computed {string} date - Date string in YYYY-MM-DD format based on `dateAt` (read-only)
- * @computed {boolean} isSpansNextDay - Flag indicating whether the date spans from start date to end date (read-only)
- * @computed {Date} startAt - Start date and time (Date object) (read-only)
- * @computed {Date} endAt - End date and time (Date object) (read-only)
- * @computed {number} totalWorkMinutes - Total working time in minutes (excluding break time) (read-only)
- * @computed {number} regularTimeWorkMinutes - Regular working time in minutes (read-only)
- * @computed {number} overtimeWorkMinutes - Overtime work in minutes (read-only)
- * - Calculated as `totalWorkMinutes` minus `regulationWorkMinutes`
- * - Overtime work is not negative; the minimum is 0.
- * ---------------------------------------------------------------------------
- * @inherited - The following getter properties are inherited from WorkingResult (via OperationDetail):
- * @getter {number} startHour - Start hour (0-23) (read-only)
- * - Extracted from `startTime`.
- * @getter {number} startMinute - Start minute (0-59) (read-only)
- * - Extracted from `startTime`.
- * @getter {number} endHour - End hour (0-23) (read-only)
- * - Extracted from `endTime`.
- * @getter {number} endMinute - End minute (0-59) (read-only)
- * - Extracted from `endTime`.
- * ---------------------------------------------------------------------------
- * @inherited - The following method is inherited from WorkingResult (via OperationDetail):
- * @method {function} setDateAtCallback - Callback method called when `dateAt` is set
- * - Override this method in subclasses to add custom behavior when `dateAt` changes.
- * - By default, updates `dayType` based on the new `dateAt` value.
- * - @param {Date} v - The new `dateAt` value
+ * @description 現場稼働予定明細クラス
+ *
+ * @class
+ * @extends OperationDetail
+ * @abstract
+ * @see ArrangementNotification
+ *
+ * @property {Date} dateAt - 日付 (変更されると `dayType` が自動的に更新されます)
+ * @property {string} shiftType - 勤務区分
+ * @property {string} startTime - 開始時刻 (HH:MM 形式)
+ * @property {string} endTime - 終了時刻 (HH:MM 形式)
+ * @property {boolean} isStartNextDay - 翌日開始フラグ
+ * - `true` の場合、実際の勤務は `dateAt` の翌日であることを意味します。
+ * @property {number} breakMinutes - 休憩時間 (分)
+ * @property {string} date - `dateAt` に基づく YYYY-MM-DD 形式の日付文字列 (読み取り専用)
+ * - `dateAt` に基づいて YYYY-MM-DD 形式の文字列を返します。
+ * @property {Date} startAt - 開始日時 (Date オブジェクト) (読み取り専用)
+ * - `dateAt` に基づいて `startTime` を設定した Date オブジェクトを返します。
+ * - `isStartNextDay` が true の場合、1日加算します。
+ * @property {Date} endAt - 終了日時 (Date オブジェクト) (読み取り専用)
+ * - `startAt` を起点に、最初に現れる `endTime` の Date オブジェクトを返します。
+ * @property {boolean} isSpansNextDay - 翌日跨ぎフラグ (読み取り専用)
+ * - `true` の場合、`startAt` と `endAt` の日付が異なることを意味します。
+ * @property {number} regulationWorkMinutes - 規定労働時間 (分)
+ * - `startAt` から `endAt` までの時間から `breakMinutes` を差し引いた時間のうち、
+ *   規定内として扱う労働時間（分）です。
+ * - 実際の労働時間から残業時間を算出するための基準となる値です。
+ * - この値があることで、取極めに柔軟な設定を行うことが可能になる他、労働基準法の 1 日の所定労働時間上限が変更された際に
+ *   影響を最小限に抑えることができます。
+ * 例) 8:00 から 17:00 までの勤務で休憩が 60 分の場合
+ * - 規定労働時間を 8 時間 (480 分) とし、実際の勤務が 8 時間 (480 分) を超えた分が残業時間として扱われます。
+ * 例) 8:00 から 16:00 までの勤務で休憩が 60 分の場合
+ * - 規定労働時間を 7 時間 (420 分) とすると、実際の勤務が 7 時間 (420 分) を超えた分が残業時間として扱われます。
+ * - 規定労働時間を 8 時間 (480 分) とすると、実際の勤務が 8 時間 (480 分) を超えた分が残業時間として扱われます。
+ * 例) 7:00 から 翌日 7:00 までの勤務で休憩が 60 分の場合
+ * - 規定労働時間を 8 時間 (480 分) とすると、実際の勤務が 8 時間 (480 分) を超えた分が残業時間として扱われます。
+ *   この場合、最初の 8 時間までは基本単価が適用され、残りの 8 時間は残業単価が適用されるといった設定が可能になります。
+ * - 規定労働時間を 24 時間 (1440 分) とすると、実際の勤務が 24 時間 (1440 分) を超えた分が残業時間として扱われます。
+ *   この場合、全ての勤務時間が基本単価で扱われるといった設定が可能になります。
+ * @property {string} dayType - 曜日区分
+ * @property {number} totalWorkMinutes - 総労働時間 (休憩時間を除く) (分) (読み取り専用)
+ * @property {number} regularTimeWorkMinutes - 所定労働時間 (分) (読み取り専用)
+ * @property {number} overtimeWorkMinutes - 残業時間 (分) (読み取り専用)
+ * @property {string} id - 従業員ID または 外注先ID
+ * @property {number} index - 外注先の識別用インデックス (従業員の場合は常に0)
+ * @property {boolean} isEmployee - 従業員フラグ (true: 従業員, false: 外注先)
+ * @property {number} amount - 配置人数 (常に1で固定)
+ * @property {string} siteId - 現場ID
+ * @property {boolean} isQualified - 資格者フラグ
+ * @property {boolean} isOjt - OJTフラグ
+ * @property {string} workerId - 作業者ID (読み取り専用)
+ * - 従業員の場合は `id` と同じ、外注先の場合は `id` と `index` を `:` で結合した文字列を返します。
+ * @property {string|null} employeeId - 従業員ID (該当しない場合は null) (読み取り専用)
+ * @property {string|null} outsourcerId - 外注先ID (該当しない場合は null) (読み取り専用)
+ * @property {string} siteOperationScheduleId - 現場稼働予定ID
+ * @property {boolean} hasNotification - 配置通知が作成されているかどうかのフラグ
+ * - SiteOperationSchedule クラスから設定されます。
+ * @property {string} notificationKey - 通知キー (読み取り専用)
+ * - `siteOperationScheduleId` と `workerId` を `_` で連結した文字列を返します。
+ * - `ArrangementNotification` のドキュメント ID と一致します。
+ *
+ * @method setDateAtCallback - `dateAt` が設定されたときに呼び出されるコールバック関数
+ * @method getInvalidReasons - クラス特有のエラーの有無を返すメソッド
+ *
+ * @getter {boolean} isInvalid - クラス特有のエラーが存在するかどうかを返すプロパティ
+ * @getter {Array<string>} invalidReasons - クラス特有のエラーコードの配列を返すプロパティ
+ *
+ * @static SHIFT_TYPE - 勤務区分を定義する定数オブジェクト
+ * @static INVALID_REASON - クラス特有のエラーコードを定義する定数オブジェクト
+ * - `BREAK_MINUTES_NEGATIVE`: `breakMinutes` が負の値である場合のエラーコード
+ * - `REGULATION_WORK_MINUTES_NEGATIVE`: `regulationWorkMinutes` が負の値である場合のエラーコード
+ * @static DAY_TYPE - 曜日区分を定義する定数オブジェクト
  *****************************************************************************/
 import OperationDetail from "./OperationDetail.js";
 import { defField } from "./parts/fieldDefinitions.js";
@@ -79,7 +89,7 @@ export default class SiteOperationScheduleDetail extends OperationDetail {
 
   /**
    * afterInitialize
-   * @param {*} item
+   * @param {Object} item - 初期化オブジェクト
    */
   afterInitialize(item = {}) {
     super.afterInitialize(item);
@@ -90,7 +100,7 @@ export default class SiteOperationScheduleDetail extends OperationDetail {
         configurable: true,
         enumerable: true,
         get() {
-          return `${this.siteOperationScheduleId}-${this.workerId}`;
+          return `${this.siteOperationScheduleId}_${this.workerId}`;
         },
         set() {},
       },

package/src/SiteOrder.js

@@ -1,33 +1,26 @@
 /**
- * Represents the order of site-shift type pairs for placement management.
+ * @file ./src/SiteOrder.js
+ * @description 現場配置順序を表すクラス
+ * - 現場と勤務区分の組み合わせの順序を管理するためのクラスです。
+ * @author shisyamo4131
  *
- * @class SiteOrder
+ * @class
  * @extends BaseClass
  *
  * @property {string} siteId - The unique identifier for the site. Required.
  * @property {string} shiftType - The type of shift associated with the site. Required.
  *
- * @property {string} key - A computed property that returns a unique key in the format `${siteId}-${shiftType}` for identifying the site-shift pair.
+ * @getter {string} key - `siteId` と `shiftType` をアンダースコアで結合した文字列を返します。
+ * @setter key - `siteId` と `shiftType` をアンダースコアで結合した文字列を受け取り、両方の値を分割して `siteId` と `shiftType` に設定します。
+ * - 受け取る値は文字列である必要があり、フォーマットは "siteId-shiftType" でなければなりません。
+ * - フォーマットが正しくない場合や、値が文字列でない場合は、プロパティの値は変更されません。
  */
 import { BaseClass } from "@shisyamo4131/air-firebase-v2";
 import { defField } from "./parts/fieldDefinitions.js";
 
-/**
- * Represents the order configuration for a site and shift type.
- *
- * @class SiteOrder
- * @extends BaseClass
- *
- * @property {string} siteId - The unique identifier for the site.
- * @property {string} shiftType - The type of shift associated with the site.
- * @property {string} key - A composite key in the format "siteId-shiftType".
- *
- * @getter
- * Returns the composite key for the site and shift type in the format "siteId-shiftType".
- *
- * @setter
- * Sets the `siteId` and `shiftType` properties from a composite key string in the format "siteId-shiftType".
- */
+/*****************************************************************************
+ * SiteOrder
+ *****************************************************************************/
 export default class SiteOrder extends BaseClass {
   static className = "現場配置順序";
   static classProps = {
@@ -36,24 +29,20 @@ export default class SiteOrder extends BaseClass {
   };
 
   /**
-   * Gets the composite key for this site and shift type.
-   * @returns {string} The key in the format "siteId-shiftType".
+   * `siteId` と `shiftType` を結合したキーを返すゲッター
+   * @returns {string} The key in the format "siteId_shiftType".
    */
   get key() {
-    return `${this.siteId}-${this.shiftType}`;
+    return `${this.siteId}_${this.shiftType}`;
   }
 
   /**
-   * Setter for the `key` property.
-   * Expects a string in the format "siteId-shiftType".
-   * Splits the input string and assigns the values to `siteId` and `shiftType` properties if both are present.
-   * Ignores the value if it is not a string.
-   *
-   * @param {string} value - The key string in the format "siteId-shiftType".
+   * `siteId` と `shiftType` を結合したキーを受け取り、両方の値を分割して `siteId` と `shiftType` に設定するセッター
+   * @param {string} value - The key string in the format "siteId_shiftType".
    */
   set key(value) {
     if (typeof value !== "string") return;
-    const [siteId, shiftType] = value.split("-");
+    const [siteId, shiftType] = value.split("_");
     if (siteId && shiftType) {
       this.siteId = siteId;
       this.shiftType = shiftType;

package/src/User.js

@@ -1,57 +1,51 @@
-/**
- * User Model
- * @version 1.1.0
- * @author shisyamo4131
- * @update 2025-12-25 Added `tagSize` property.
- *                    Added `updateProperties` method for updating multiple properties.
- * @update 2025-11-24 Added `companyId`, `isAdmin`, `isTemporary` property.
- *                    Changed to prevent deletion of admin users.
- *
- * @prop {string} email - User's email address.
- * @prop {string} displayName - User's display name.
- * @prop {string} [employeeId] - Employee ID (not required as some users may not be employees).
- * @prop {Array<string>} roles - User roles/permissions.
- * @prop {boolean} disabled - Indicates if the user is disabled.
- * @prop {string} companyId - ID of the associated company.
- * @prop {boolean} isAdmin - Indicates if the user is an administrator.
- * @prop {boolean} isTemporary - Indicates if the user is temporary.
- * @prop {string} tagSize - Size of the tag associated with the user.
- */
+/*****************************************************************************
+ * @file src/User.js
+ *****************************************************************************/
 import FireModel from "@shisyamo4131/air-firebase-v2";
 import { defField } from "./parts/fieldDefinitions.js";
 import { TAG_SIZE_VALUES, TAG_SIZE_OPTIONS } from "./constants/index.js";
 
-const classProps = {
-  email: defField("email", { required: true }),
-  displayName: defField("displayName", { required: true }),
-  employeeId: defField("oneLine", { label: "従業員ID", hidden: true }),
-  roles: {
-    type: Array,
-    default: () => [],
-    label: "権限",
-    required: false,
-    hidden: false,
-  },
-  disabled: defField("check", {
-    label: "使用不可",
-    default: false,
-    required: false,
-    hidden: true,
-  }),
-  companyId: defField("oneLine", { hidden: true, required: true }),
-  isAdmin: defField("check", { hidden: true, default: false }),
-  isTemporary: defField("check", { hidden: true, default: true }),
-  tagSize: defField("select", {
-    label: "タグサイズ",
-    default: TAG_SIZE_VALUES.MEDIUM.value,
-    options: TAG_SIZE_OPTIONS,
-  }),
-};
-
+/*****************************************************************************
+ * @class User
+ * @extends FireModel
+ *
+ * @property {string} email - メールアドレス
+ * @property {string} displayName - 表示名
+ * @property {string} [employeeId] - 従業員ID（非従業員を許容するために必須とはしない）
+ * @property {Array<string>} roles - アプリケーション利用権限
+ * @property {boolean} disabled - 有効/無効
+ * @property {string} companyId - 会社ID
+ * @property {boolean} isAdmin - 管理者であるかどうか
+ * @property {boolean} isTemporary - 仮登録状態であるかどうか
+ * @property {string} tagSize - 配置管理機能におけるタグコンポーネントの表示サイズ
+ *****************************************************************************/
 export default class User extends FireModel {
   static className = "ユーザー";
   static collectionPath = "Users";
-  static classProps = classProps;
+  static classProps = {
+    /**
+     * email
+     * - 登録時以外編集不可。
+     * - ユーザーアカウントのメールアドレスの変更は Cloud Functions 経由とする。
+     * - ユーザーアカウントのグローバル重複チェックは Cloud Functions 経由とする。
+     */
+    email: defField("email", {
+      required: true,
+      component: {
+        attrs: {
+          disabled: ({ editMode, item }) => editMode !== "CREATE",
+        },
+      },
+    }),
+    displayName: defField("displayName", { required: true }),
+    employeeId: defField("oneLine", { label: "従業員ID", hidden: true }),
+    roles: defField("roles"),
+    disabled: defField("disabled", { hidden: true }),
+    companyId: defField("companyId", { hidden: true, required: true }),
+    isAdmin: defField("isAdmin", { hidden: true }),
+    isTemporary: defField("isTemporary", { hidden: true, default: true }),
+    tagSize: defField("tagSize", { required: true }),
+  };
 
   /**
    * Deletes the user document.
@@ -82,6 +76,9 @@ export default class User extends FireModel {
    * @returns {Promise<DocumentReference>} Reference to the updated document.
    * @throws {Error} If `updateData` is not a valid object.
    * @throws {Error} If `docId` is not set, or if `updateOptions.callback` is not a function.
+   *
+   * Note: このメソッドは複数のプロパティを一括更新するためのヘルパーメソッド。BaseClass に移設しても良いかもしれない。
+   * なお、`useAuthStore` で使用中のようだ。
    */
   async updateProperties(updateData = null, updateOptions = {}) {
     if (!updateData || typeof updateData !== "object") {

package/src/WorkTimeBase.js

@@ -0,0 +1,205 @@
+/*****************************************************************************
+ * @file ./src/WorkTimeBase.js
+ * @author shisyamo4131
+ * @description 勤務実績情報の基底クラス
+ * - 日付や時間に関するプロパティを持つ抽象クラスです。インスタンス化はできません。
+ * - 24時間を超える勤務は管理できません。`startTime` と `endTime` に同時刻が設定された場合は、24時間勤務と見做されます。
+ *
+ * @class
+ * @extends FireModel
+ * @abstract
+ * @see AgreementV2
+ * @see WorkingResult
+ *
+ * @property {Date} dateAt - 日付
+ * @property {string} shiftType - 勤務区分
+ * @property {string} startTime - 開始時刻 (HH:MM 形式)
+ * @property {string} endTime - 終了時刻 (HH:MM 形式)
+ * @property {boolean} isStartNextDay - 翌日開始フラグ
+ * - `true` の場合、実際の勤務は `dateAt` の翌日であることを意味します。
+ * @property {number} breakMinutes - 休憩時間 (分)
+ * @property {string} date - `dateAt` に基づく YYYY-MM-DD 形式の日付文字列 (読み取り専用)
+ * - `dateAt` に基づいて YYYY-MM-DD 形式の文字列を返します。
+ * @property {Date} startAt - 開始日時 (Date オブジェクト) (読み取り専用)
+ * - `dateAt` に基づいて `startTime` を設定した Date オブジェクトを返します。
+ * - `isStartNextDay` が true の場合、1日加算します。
+ * @property {Date} endAt - 終了日時 (Date オブジェクト) (読み取り専用)
+ * - `startAt` を起点に、最初に現れる `endTime` の Date オブジェクトを返します。
+ * @property {boolean} isSpansNextDay - 翌日跨ぎフラグ (読み取り専用)
+ * - `true` の場合、`startAt` と `endAt` の日付が異なることを意味します。
+ * @property {number} regulationWorkMinutes - 規定労働時間 (分)
+ * - `startAt` から `endAt` までの時間から `breakMinutes` を差し引いた時間のうち、
+ *   規定内として扱う労働時間（分）です。
+ * - 実際の労働時間から残業時間を算出するための基準となる値です。
+ * - この値があることで、取極めに柔軟な設定を行うことが可能になる他、労働基準法の 1 日の所定労働時間上限が変更された際に
+ *   影響を最小限に抑えることができます。
+ * 例) 8:00 から 17:00 までの勤務で休憩が 60 分の場合
+ * - 規定労働時間を 8 時間 (480 分) とし、実際の勤務が 8 時間 (480 分) を超えた分が残業時間として扱われます。
+ * 例) 8:00 から 16:00 までの勤務で休憩が 60 分の場合
+ * - 規定労働時間を 7 時間 (420 分) とすると、実際の勤務が 7 時間 (420 分) を超えた分が残業時間として扱われます。
+ * - 規定労働時間を 8 時間 (480 分) とすると、実際の勤務が 8 時間 (480 分) を超えた分が残業時間として扱われます。
+ * 例) 7:00 から 翌日 7:00 までの勤務で休憩が 60 分の場合
+ * - 規定労働時間を 8 時間 (480 分) とすると、実際の勤務が 8 時間 (480 分) を超えた分が残業時間として扱われます。
+ *   この場合、最初の 8 時間までは基本単価が適用され、残りの 8 時間は残業単価が適用されるといった設定が可能になります。
+ * - 規定労働時間を 24 時間 (1440 分) とすると、実際の勤務が 24 時間 (1440 分) を超えた分が残業時間として扱われます。
+ *   この場合、全ての勤務時間が基本単価で扱われるといった設定が可能になります。
+ *
+ * @method setDateAtCallback - `dateAt` が設定されたときに呼び出されるコールバック関数
+ *
+ * @getter {boolean} isInvalid - クラス特有のエラーが存在するかどうかを返すプロパティ
+ * @getter {Array<string>} invalidReasons - クラス特有のエラーコードの配列を返すプロパティ
+ *
+ * @static SHIFT_TYPE - 勤務区分を定義する定数オブジェクト
+ *****************************************************************************/
+import FireModel from "@shisyamo4131/air-firebase-v2";
+import { defField } from "./parts/fieldDefinitions.js";
+import { getDateAt, formatJstDate } from "./utils/index.js";
+import { VALUES as SHIFT_TYPE } from "./constants/shift-type.js";
+
+const classProps = {
+  dateAt: defField("dateAt", { required: true }),
+  shiftType: defField("shiftType", { required: true }),
+  startTime: defField("time", { label: "開始時刻", required: true }),
+  isStartNextDay: defField("check", { label: "翌日開始" }),
+  endTime: defField("time", { label: "終了時刻", required: true }),
+  breakMinutes: defField("breakMinutes", { required: true }),
+  regulationWorkMinutes: defField("regulationWorkMinutes", { required: true }),
+};
+
+/*****************************************************************************
+ * WorkTimeBase
+ *****************************************************************************/
+export default class WorkTimeBase extends FireModel {
+  static className = "WorkTimeBase";
+  static collectionPath = "WorkTimeBases";
+  static useAutonumber = false;
+  static logicalDelete = false;
+  static classProps = classProps;
+
+  static SHIFT_TYPE = SHIFT_TYPE;
+
+  /**
+   * Constructor
+   * - 抽象クラスのため、直接のインスタンス化を防止します。
+   * @param {Object} item - 初期化オブジェクト
+   */
+  constructor(item = {}) {
+    if (new.target === WorkTimeBase) {
+      throw new Error(
+        "WorkTimeBase is an abstract class and cannot be instantiated directly.",
+      );
+    }
+    super(item);
+  }
+
+  /**
+   * afterInitialize
+   * @param {Object} item - 初期化オブジェクト
+   */
+  afterInitialize(item = {}) {
+    super.afterInitialize(item);
+
+    let _dateAt = this.dateAt;
+    Object.defineProperties(this, {
+      /**
+       * `dateAt` プロパティの変更に伴った処理を実現するため、`dateAt` を getter/setter で再定義します。
+       * - `setDateAtCallback` メソッドを使用して `dateAt` の変更に伴うカスタム処理を実装可能です。
+       */
+      dateAt: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          return _dateAt;
+        },
+        set(v) {
+          if (_dateAt && v.getTime() === _dateAt.getTime()) {
+            return;
+          }
+          const newDate = new Date(v);
+          newDate.setHours(0, 0, 0, 0); // 時刻部分をクリア
+          _dateAt = newDate;
+          this.setDateAtCallback(newDate);
+        },
+      },
+
+      /**
+       * date - `dateAt` に基づく YYYY-MM-DD 形式の日付文字列 (読み取り専用)
+       */
+      date: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          return formatJstDate(this.dateAt) || "";
+        },
+        set(v) {},
+      },
+
+      /**
+       * isSpansNextDay - 翌日跨ぎフラグ (読み取り専用)
+       * - `startAt` の日付よりも `endAt` の日付が後である場合に `true` を返します。
+       */
+      isSpansNextDay: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          if (!this.startAt || !this.endAt) return false;
+          const startDate = new Date(this.startAt);
+          const endDate = new Date(this.endAt);
+          startDate.setHours(0, 0, 0, 0);
+          endDate.setHours(0, 0, 0, 0);
+          return endDate.getTime() > startDate.getTime();
+        },
+        set(v) {},
+      },
+
+      /**
+       * startAt - 開始日時 (Date オブジェクト) (読み取り専用)
+       * - `dateAt` に基づいて `startTime` を設定した Date オブジェクトを返します。
+       * - `isStartNextDay` が true の場合、1日加算します。
+       */
+      startAt: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          if (!this.startTime) return null;
+          const dateOffset = this.isStartNextDay ? 1 : 0;
+          return getDateAt(this.dateAt, this.startTime, dateOffset);
+        },
+        set(v) {},
+      },
+
+      /**
+       * endAt - 終了日時 (Date オブジェクト) (読み取り専用)
+       * - `startAt` を起点に、最初に現れる `endTime` の Date オブジェクトを返します。
+       * - `startTime` と `endTime` が同時刻の場合は 24時間勤務と見做し、`endAt` は翌日の同時刻になります。
+       */
+      endAt: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          if (!this.startAt || !this.endTime) return null;
+
+          const baseDate = new Date(this.startAt);
+          baseDate.setHours(0, 0, 0, 0);
+          const endAt = getDateAt(baseDate, this.endTime, 0);
+
+          if (endAt.getTime() <= this.startAt.getTime()) {
+            endAt.setDate(endAt.getDate() + 1);
+          }
+
+          return endAt;
+        },
+        set(v) {},
+      },
+    });
+  }
+
+  /**
+   * `dateAt` が変更されたときに呼び出されるコールバック関数
+   * - サブクラスでこのメソッドをオーバーライドして、`dateAt` の変更に伴うカスタム処理を実装できます。
+   * - `dateAt` をこの関数内で更新してはいけません。
+   * @param {Date} v - 新しい `dateAt` 値
+   * @returns {void}
+   */
+  setDateAtCallback(v) {}
+}