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

package/src/OperationBilling.js

@@ -1,184 +1,133 @@
 /*****************************************************************************
- * OperationBilling Model
- * @version 1.0.0
+ * @file ./src/OperationBilling.js
  * @author shisyamo4131
+ * @description 稼働請求クラス
  *
- * - Extends OperationResult class to represent the billing of an operation.
- * - This class provides the same functionality as OperationResult but with a different semantic meaning
- *   focused on billing operations rather than general operation results.
- * - All properties, computed values, and methods are inherited from OperationResult.
- * - The `className` is set to "稼働請求" (Operation Billing) to distinguish it from OperationResult.
- * - The `create` method is overridden to indicate that creation of OperationBilling instances
- *   is not implemented, as billing records are typically generated through the OperationResult class.
+ * @class
+ * @extends OperationResult
  *
- * @prop {string} siteId - Site document ID (trigger property)
- * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * @prop {Date} dateAt - Date of operation (placement date) (trigger property)
- * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * - Used to determine `dayType`.
- * - When `dateAt` changes, `billingDateAt` is also updated based on `agreement.cutoffDate`.
- * @prop {string} dayType - Day type (e.g., `WEEKDAY`, `WEEKEND`, `HOLIDAY`)
- * @prop {string} shiftType - `DAY` or `NIGHT` (trigger property)
- * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * @prop {string} startTime - Start time (HH:MM format)
- * @prop {boolean} isStartNextDay - Next day start flag
- * - `true` if the actual work starts the day after the placement date `dateAt`
- * @prop {string} endTime - End time (HH:MM format)
- * @prop {number} breakMinutes - Break time (minutes)
- * @prop {number} regulationWorkMinutes - Regulation work minutes (trigger property)
- * - Indicates the maximum working time treated as regular working hours.
- * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * @prop {number} requiredPersonnel - Required number of personnel
- * @prop {boolean} qualificationRequired - Qualification required flag
- * @prop {string} workDescription - Work description
- * @prop {string} remarks - Remarks
- * @prop {Array<OperationResultDetail>} employees - Assigned employees
- * - Array of `OperationResultDetail` instances representing assigned employees
- * @prop {Array<OperationResultDetail>} outsourcers - Assigned outsourcers
- * - Array of `OperationResultDetail` instances representing assigned outsourcers
- * @prop {Array<OperationResultDetail>} workers - Combined array of `employees` and `outsourcers`
- * - Getter: Returns concatenated array of employees and outsourcers
- * - Setter: Splits array into employees and outsourcers based on `isEmployee` property
- * @prop {string|null} siteOperationScheduleId - Associated SiteOperationSchedule document ID
- * - If this OperationResult was created from a SiteOperationSchedule, this property holds that ID.
- * @prop {boolean} useAdjustedQuantity - Flag to indicate if adjusted quantities are used for billing
- * @prop {number} adjustedQuantityBase - Adjusted quantity for base workers
- * - Quantity used for billing base workers when `useAdjustedQuantity` is true.
- * @prop {number} adjustedOvertimeBase - Adjusted overtime for base workers
- * - Overtime used for billing base workers when `useAdjustedQuantity` is true.
- * @prop {number} adjustedQuantityQualified - Adjusted quantity for qualified workers
- * - Quantity used for billing qualified workers when `useAdjustedQuantity` is true.
- * @prop {number} adjustedOvertimeQualified - Adjusted overtime for qualified workers
- * - Overtime used for billing qualified workers when `useAdjustedQuantity` is true.
- * @prop {Date} billingDateAt - Billing date
- * - The date used for billing purposes.
- * @prop {boolean} isLocked - Lock flag
- * - When set to true, the OperationResult is locked from edits exept for editing as OperationBilling.
- * @prop {Agreement|null} agreement - Associated Agreement object
- * - The Agreement instance associated with this OperationResult for pricing and billing information.
- * - When set, it influences billing calculations such as unit prices and billing dates.
- * @prop {boolean} allowEmptyAgreement - Flag to ignore missing Agreement
- * - When set to true, allows the OperationResult to be valid even if no Agreement is associated.
+ * @property {Date} dateAt - 日付 (変更されると `dayType` が自動的に更新されます)
+ * @property {string} shiftType - 勤務区分 (変更されると `employees` と `outsourcers` の `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 - 規定労働時間 (分) (変更されると `employees` と `outsourcers` の `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} siteId - 現場ID (変更されると `employees` と `outsourcers` の `siteId` が自動的に更新されます)
+ * @property {number} requiredPersonnel - 必要人数
+ * @property {boolean} qualificationRequired - 資格要件フラグ
+ * @property {string} workDescription - 作業内容
+ * @property {string} remarks - 備考
+ * @property {Array<OperationDetail>} employees - 従業員の OperationDetail インスタンスの配列
+ * @property {Array<OperationDetail>} outsourcers - 外注の OperationDetail インスタンスの配列
+ * @property {Array<string>} employeeIds - 従業員の ID の配列 (読み取り専用)
+ * @property {Array<string>} outsourcerIds - 外注の ID の配列 (読み取り専用)
+ * @property {number} employeesCount - `employees` の要素数 (読み取り専用)
+ * @property {number} outsourcersCount - `outsourcers` の要素数 (読み取り専用)
+ * @property {boolean} isPersonnelShortage - 人員不足フラグ (読み取り専用)
+ * @property {Array<OperationDetail>} workers - 従業員と外注を合わせた配列
+ * - `employees` と `outsourcers` を結合した配列を返します。
+ * - Getter: `employees` と `outsourcers` を結合した配列を返します。
+ * - Setter: 配列を `isEmployee` プロパティに基づいて `employees` と `outsourcers` に分割します。
+ * @property {string} groupKey - `siteId`, `shiftType`, `date` を組み合わせたキー。（読み取り専用）
+ * @property {string} agreementKey - `date`, `shiftType` を組み合わせたキー。（読み取り専用）
+ * @property {string} orderKey - `siteId`, `shiftType` を組み合わせたキー。（読み取り専用）
+ * @property {string|null} siteOperationScheduleId - 現場稼働予定ID
+ * - このプロパティは、OperationResult が現場稼働予定に紐づいている場合に、その現場稼働予定の ID を保持します。
+ * @property {boolean} useAdjustedQuantity - 請求に調整済み数量を使用するかどうかのフラグ
+ * @property {number} adjustedQuantityBase - 基本従業員の調整済み数量
+ * - `useAdjustedQuantity` が true の場合、基本従業員の請求に使用される数量です。
+ * @property {number} adjustedOvertimeBase - 基本従業員の調整済み残業時間
+ * - `useAdjustedQuantity` が true の場合、基本従業員の請求に使用される残業時間です。
+ * @property {number} adjustedQuantityQualified - 資格者の調整済み数量
+ * - `useAdjustedQuantity` が true の場合、資格者の請求に使用される数量です。
+ * @property {number} adjustedOvertimeQualified - 資格者の調整済み残業時間
+ * - `useAdjustedQuantity` が true の場合、資格者の請求に使用される残業時間です。
+ * @property {Date} billingDateAt - 請求日
+ * - 請求に使用される日付です。
+ * @property {boolean} isLocked - ロックフラグ
+ * - true の場合、OperationResult は OperationBilling として編集する場合を除き、編集できません。
+ * @property {Agreement|null} agreement - 関連する取極めオブジェクト
+ * - この OperationResult に関連付けられた取極めインスタンスで、価格設定や請求情報に使用されます。
+ * - 設定されている場合、単価や請求日などの計算に影響を与えます。
+ * @property {boolean} allowEmptyAgreement - 取極めが存在しない場合を許可するフラグ
+ * - true に設定されている場合、取極めが関連付けられていなくても OperationResult は有効と見なされます。
+ * @property {boolean} hasAgreement - 取極めが関連付けられているかどうかを示すフラグ (読み取り専用)
+ * - `agreement` が設定されている場合は `true`、それ以外の場合は `false`。
+ * @property {Object} statistics - 従業員の統計情報 (読み取り専用)
+ * - 基本従業員と資格者のカウントおよび総労働時間を含む統計情報。
+ * - 構造: { base: {...}, qualified: {...}, total: {...} }
+ * - 各カテゴリには以下が含まれます: quantity, regularTimeWorkMinutes, overtimeWorkMinutes, totalWorkMinutes, breakMinutes
+ * - 各カテゴリには 'ojt' サブカテゴリも同様の構造で含まれます。
+ * @property {Object} sales - 売上金額 (読み取り専用)
+ * - 基本従業員と資格者の売上計算を含む。
+ * - 構造: { base: {...}, qualified: {...} }
+ * - 各カテゴリには以下が含まれます: unitPrice, quantity, regularAmount, overtimeUnitPrice, overtimeMinutes, overtimeAmount, total
+ * - 計算は `useAdjustedQuantity`, `billingUnitType`, `includeBreakInBilling` の設定を考慮します。
+ * @property {number} salesAmount - 売上合計金額 (読み取り専用)
+ * - 基本従業員と資格者の売上金額の合計を返します。
+ * @property {number} tax - 計算された税額 (読み取り専用)
+ * - `salesAmount` と `date` に基づいて `Tax` ユーティリティを使用して計算されます。
+ * @property {number} billingAmount - 税込の請求金額 (読み取り専用)
+ * - `salesAmount` と `tax` の合計を返します。
+ * @property {string|null} billingDate - 請求日 (YYYY-MM-DD 形式) (読み取り専用)
+ * - `billingDateAt` に基づいて YYYY-MM-DD 形式の文字列を返します。
+ * @property {string} billingMonth - 請求月 (YYYY-MM 形式) (読み取り専用)
+ * @property {string|false} isInvalid - バリデーションステータス (読み取り専用)
+ * - 有効な場合は false を返します。
+ * - 無効な場合は理由コードの文字列を返します:
+ *   - `EMPTY_BILLING_DATE`: 請求日が存在しない場合。
+ *   - `EMPTY_AGREEMENT`: 取極めが存在せず、`allowEmptyAgreement` が false の場合。
  *
- * @readonly
- * @prop {string} date - Date string in YYYY-MM-DD format based on `dateAt` (read-only)
- * - Returns a string in the format YYYY-MM-DD based on `dateAt`.
- * @prop {Date} startAt - Start date and time (Date object) (read-only)
- * - Returns a Date object with `startTime` set based on `dateAt`.
- * - If `isStartNextDay` is true, add 1 day.
- * @prop {Date} endAt - End date and time (Date object) (read-only)
- * - Returns a Date object with `endTime` set based on `dateAt`.
- * - If `isStartNextDay` is true, add 1 day.
- * - If `isSpansNextDay` is true, add 1 day.
- * @prop {boolean} isSpansNextDay - Flag indicating whether the date spans from start date to end date (read-only)
- * - `true` if `startTime` is later than `endTime`
- * @prop {number} totalWorkMinutes - Total working time in minutes (excluding break time) (read-only)
- * - Calculated as the difference between `endAt` and `startAt` minus `breakMinutes`
- * @prop {number} regularTimeWorkMinutes - Regular working time in minutes (read-only)
- * - The portion of `totalWorkMinutes` that is considered within the contract's `regulationWorkMinutes`.
- * @prop {number} overtimeWorkMinutes - Overtime work in minutes (read-only)
- * - Calculated as `totalWorkMinutes` minus `regulationWorkMinutes`
- * @prop {boolean} hasAgreement - Indicates if an Agreement is associated (read-only)
- * - `true` if `agreement` is set, otherwise `false`.
- * @prop {string|false} isInvalid - Validation status (read-only)
- * - Returns false if valid.
- * - Returns reason code string if invalid:
- *   - `EMPTY_BILLING_DATE`: Billing date is missing.
- *   - `EMPTY_AGREEMENT`: Agreement is missing and `allowEmptyAgreement` is false.
- * @prop {Object} statistics - Statistics of workers (read-only)
- * - Contains counts and total work minutes for base and qualified workers, including OJT breakdowns.
- * - Structure: { base: {...}, qualified: {...}, total: {...} }
- * - Each category contains: quantity, regularTimeWorkMinutes, overtimeWorkMinutes, totalWorkMinutes, breakMinutes
- * - Each category also has an 'ojt' subcategory with the same structure.
- * @prop {Object} sales - Sales amounts (read-only)
- * - Contains sales calculations for base and qualified workers, including overtime breakdowns.
- * - Structure: { base: {...}, qualified: {...} }
- * - Each category contains: unitPrice, quantity, regularAmount, overtimeUnitPrice, overtimeMinutes, overtimeAmount, total
- * - Calculations respect `useAdjustedQuantity`, `billingUnitType`, and `includeBreakInBilling` settings.
- * @prop {number} salesAmount - Total sales amount (read-only)
- * - Sum of sales amounts for base and qualified workers with rounding applied.
- * @prop {number} tax - Calculated tax amount (read-only)
- * - Calculated using the `Tax` utility based on `salesAmount` and `date`.
- * @prop {number} billingAmount - Total billing amount including tax (read-only)
- * - Sum of `salesAmount` and `tax`.
- * @prop {string|null} billingDate - Billing date in YYYY-MM-DD format (read-only)
- * - Returns a string in the format YYYY-MM-DD based on `billingDateAt`.
- * @prop {string} billingMonth - Billing month in YYYY-MM format (read-only)
- * @prop {Array<string>} employeeIds - Array of employee IDs from `employees` (read-only)
- * @prop {Array<string>} outsourcerIds - Array of outsourcer IDs from `outsourcers` (read-only)
- * @prop {number} employeesCount - Count of assigned employees (read-only)
- * @prop {number} outsourcersCount - Count of assigned outsourcers (sum of amounts) (read-only)
- * @prop {boolean} isPersonnelShortage - Indicates if there is a shortage of personnel (read-only)
- * - `true` if the sum of `employeesCount` and `outsourcersCount` is less than `requiredPersonnel`
+ * @method setDateAtCallback - `dateAt` が設定されたときに呼び出されるコールバック関数
+ * @method addWorker - `Workers` に新しい従業員または外注先を追加します。
+ * @method moveWorker - 従業員または外注先の位置を移動します。
+ * @method changeWorker - 従業員または外注先の詳細を変更します。
+ * @method removeWorker - 従業員または外注先を `workers` から削除します。
+ * @method setSiteIdCallback - `siteId` が変更された時に呼び出されるコールバック関数
+ * @method setShiftTypeCallback - `shiftType` が変更された時に呼び出されるコールバック関数
+ * @method setRegulationWorkMinutesCallback - `regulationWorkMinutes` が変更された時に呼び出されるコールバック関数
+ * @method refreshBillingDateAt - 請求日を `dateAt` と `cutoffDate` に基づいて更新します。
+ * - 現在の `dateAt` と `cutoffDate` の値に基づいて `billingDateAt` を更新します。
  *
- * @getter {string} groupKey - Combines `siteId`, `shiftType`, and `date` to indicate operation grouping (read-only)
- * @getter {boolean} isEmployeesChanged - Indicates whether the employees have changed (read-only)
- * - Returns true if the employee IDs have changed compared to `_beforeData`
- * @getter {boolean} isOutsourcersChanged - Indicates whether the outsourcers have changed (read-only)
- * - Returns true if the outsourcer IDs have changed compared to `_beforeData`
- * @getter {Array<OperationResultDetail>} addedWorkers - An array of workers that have been added (read-only)
- * - Workers that exist in current data but not in `_beforeData`
- * @getter {Array<OperationResultDetail>} removedWorkers - An array of workers that have been removed (read-only)
- * - Workers that exist in `_beforeData` but not in current data
- * @getter {Array<OperationResultDetail>} updatedWorkers - An array of workers that have been updated (read-only)
- * - Workers whose `startTime`, `isStartNextDay`, `endTime`, `breakMinutes`, `isQualified`, or `isOjt` have changed
- * @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`.
- *
- * @method refreshBillingDateAt - Refresh billingDateAt based on dateAt and cutoffDate
- * - Updates `billingDateAt` based on the current `dateAt` and `cutoffDate` values.
- * @method addWorker - Adds a new worker (employee or outsourcer)
- * - @param {Object} options - Options for adding a worker
- * - @param {string} options.id - The worker ID (employeeId or outsourcerId)
- * - @param {boolean} [options.isEmployee=true] - Whether the worker is an employee
- * - @param {number} [index=0] - Insertion position. If -1, adds to the end
- * @method moveWorker - Moves the position of a worker (employee or outsourcer)
- * - @param {Object} options - Options for changing worker position
- * - @param {number} options.oldIndex - The original index
- * - @param {number} options.newIndex - The new index
- * - @param {boolean} [options.isEmployee=true] - True for employee, false for outsourcer
- * @method changeWorker - Changes the details of a worker
- * - @param {Object} newWorker - New worker object
- * @method removeWorker - Removes a worker (employee or outsourcer)
- * - @param {Object} options - Options for removing a worker
- * - @param {string} options.workerId - The ID of the employee or outsourcer
- * - @param {boolean} [options.isEmployee=true] - True for employee, false for outsourcer
- * @method setSiteIdCallback - Callback method called when `siteId` is set
- * - Override this method in subclasses to add custom behavior when `siteId` changes.
- * - By default, does nothing.
- * - @param {string} v - The new `siteId` value
- * @method setShiftTypeCallback - Callback method called when `shiftType` is set
- * - Override this method in subclasses to add custom behavior when `shiftType` changes.
- * - By default, does nothing.
- * - @param {string} v - The new `shiftType` value
- * @method setRegulationWorkMinutesCallback - Callback method called when `regulationWorkMinutes` is set
- * - Override this method in subclasses to add custom behavior when `regulationWorkMinutes` changes.
- * - By default, does nothing.
- * - @param {number} v - The new `regulationWorkMinutes` value
- *
- * @static
- * @method groupKeyDivider
- * - Returns an array dividing the key into siteId, shiftType, and date.
- * - @param {Object|string} key - The combined key string or object
- * - @returns {Array<string>} - Array containing [siteId, shiftType, date]
- * - @throws {Error} - If the key is invalid.
- * @method toggleLock - Toggle the lock status of an OperationResult document
- * - @param {string} docId - Document ID
- * - @param {boolean} value - Lock status value
- * - @returns {Promise<void>}
+ * @method toggleLock - OperationResult ドキュメントのロック状態を切り替える
+ * - 指定されたドキュメント ID の OperationResult ドキュメントを取得し、その `isLocked` プロパティを指定された値に更新します。
+ * - ドキュメントが存在しない場合や、無効な引数が提供された場合はエラーをスローします。
  *
  * @override
- * @method create - Override create method to indicate not implemented
- * - Creation of OperationBilling instances is not implemented, as billing records are typically
- *   generated through the OperationResult class.
- * @method update - Override update method to allow editing even when isLocked is true
- * @method delete - Override delete method to allow deletion even when isLocked is true
+ * @method create - このクラスのインスタンスは `create` メソッドを使用できません。
+ * - 稼働請求のレコードは通常、OperationResult クラスを通じて生成されるため、OperationBilling クラスのインスタンスの作成は実装されていません。
+ * @method delete - このクラスのインスタンスは `delete` メソッドを使用できません。
+ * - 稼働請求のレコードは通常、OperationResult クラスを通じて生成されるため、OperationBilling クラスのインスタンスの削除は実装されていません。
  *****************************************************************************/
 import OperationResult from "./OperationResult.js";
 
@@ -191,21 +140,6 @@ export default class OperationBilling extends OperationResult {
     { title: "売上金額", key: "salesAmount", value: "salesAmount" },
   ];
 
-  /**
-   * Override beforeUpdate to skip `isLocked` check and sync customerId and apply agreement if key changed
-   * @param {Object} args - Creation options.
-   * @param {Object} [args.transaction] - Firestore transaction.
-   * @param {Function} [args.callBack] - Callback function.
-   * @param {string} [args.prefix] - Path prefix.
-   * @returns {Promise<void>}
-   */
-  async beforeUpdate(args = {}) {
-    await super.beforeUpdate(args);
-    // Sync customerId and apply agreement if key changed
-    if (this.key === this._beforeData.key) return;
-    await this._syncCustomerIdAndApplyAgreement(args);
-  }
-
   /**
    * Override create method to disallow creation of OperationBilling instances
    * @returns
@@ -213,8 +147,8 @@ export default class OperationBilling extends OperationResult {
   async create() {
     return Promise.reject(
       new Error(
-        "[OperationBilling.js] Creation of OperationBilling is not implemented."
-      )
+        "[OperationBilling.js] Creation of OperationBilling is not implemented.",
+      ),
     );
   }
 
@@ -225,8 +159,8 @@ export default class OperationBilling extends OperationResult {
   async delete() {
     return Promise.reject(
       new Error(
-        "[OperationBilling.js] Deletion of OperationBilling is not implemented."
-      )
+        "[OperationBilling.js] Deletion of OperationBilling is not implemented.",
+      ),
     );
   }
 

package/src/OperationDetail.js

@@ -1,99 +1,100 @@
 /*****************************************************************************
- * OperationDetail Model ver 1.0.0
+ * @file ./src/OperationDetail.js
  * @author shisyamo4131
- * ---------------------------------------------------------------------------
- * - Base class for SiteOperationScheduleDetail and OperationResultDetail.
- * - Extends WorkingResult class, inheriting all working time calculation functionality
- * - This class is intended to be inherited by other classes so, it cannot be instantiated directly.
- * - Employee or Outsourcer document ID is stored in the id property.
- *   This is useful for specifying as a key for tables.
- * - `amount` property is always fixed at 1 (reserved for future extension).
- * - `startTime` and `endTime` are managed as strings in HH:MM format.
- * - `isEmployee` property distinguishes between Employee and Outsourcer.
- * - `employeeId` and `outsourcerId` properties can be used to get each ID (null if not applicable).
- * --------------------------------------------------------------------------
- * @props {string} id - Employee or Outsourcer document ID
- * @props {number} index - Identifier index for Outsourcer (always 0 for Employee)
- * @props {boolean} isEmployee - Employee flag (true: Employee, false: Outsourcer)
- * @props {number} amount - Number of placements (always fixed at 1)
- * @props {string} siteId - Site ID
- * @props {boolean} isQualified - Qualified flag
- * @props {boolean} isOjt - OJT flag
- * --------------------------------------------------------------------------
- * @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:
- * @props {Date} dateAt - Placement date (trigger property)
- * @props {string} dayType - Day type (e.g., `WEEKDAY`, `WEEKEND`, `HOLIDAY`)
- * @props {string} shiftType - `DAY` or `NIGHT`
- * @props {string} startTime - Start time (HH:MM format)
- * @props {boolean} isStartNextDay - Next day start flag
- * @props {string} endTime - End time (HH:MM format)
- * @props {number} breakMinutes - Break time (minutes)
- * @props {number} regulationWorkMinutes - Regulation work minutes
- * --------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from WorkingResult:
- * @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:
- * @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:
- * @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 稼働明細クラス
+ * - 稼働明細を表す抽象クラスです。インスタンス化はできません。
+ * - `OperationDetail` ドキュメント群を一意に識別するためには `workerId` を使用してください。
+ *
+ * @class
+ * @extends WorkingResult
+ * @abstract
+ * @see OperationResultDetail
+ * @see SiteOperationScheduleDetail
+ *
+ * @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) (読み取り専用)
+ *
+ * @removed
+ * @deprecated
+ * @property {string} key - 使用不可
+ *
+ * @method setDateAtCallback - `dateAt` が設定されたときに呼び出されるコールバック関数
+ * @method getInvalidReasons - クラス特有のエラーの有無を返すメソッド
+ *
+ * @getter {boolean} isInvalid - クラス特有のエラーが存在するかどうかを返すプロパティ
+ * @getter {Array<string>} invalidReasons - クラス特有のエラーコードの配列を返すプロパティ
+ *
+ * @deprecated
+ * @getter {boolean} isKeyChanged - 使用不可
+ *
+ * @static SHIFT_TYPE - 勤務区分を定義する定数オブジェクト
+ * @static INVALID_REASON - クラス特有のエラーコードを定義する定数オブジェクト
+ * - `BREAK_MINUTES_NEGATIVE`: `breakMinutes` が負の値である場合のエラーコード
+ * - `REGULATION_WORK_MINUTES_NEGATIVE`: `regulationWorkMinutes` が負の値である場合のエラーコード
+ * @static DAY_TYPE - 曜日区分を定義する定数オブジェクト
  *****************************************************************************/
 import { defField } from "./parts/fieldDefinitions.js";
 import WorkingResult from "./WorkingResult.js";
 
 const classProps = {
+  ...WorkingResult.classProps, // Inherited from WorkingResult.js
   id: defField("oneLine", { default: "" }),
   index: defField("number", { default: 0 }),
   isEmployee: defField("check", { default: true, required: true }),
   amount: defField("number", { default: 1, required: true, hidden: true }),
   siteId: defField("oneLine", { required: true }),
-  ...WorkingResult.classProps, // Inherited from WorkingResult.js
   isQualified: defField("check", { label: "資格者" }),
   isOjt: defField("check", { label: "OJT" }),
 };
 
-/**
- * Wrapper to define computed properties.
- * @param {*} obj
- * @param {*} properties
- */
-function defineComputedProperties(obj, properties) {
-  const descriptors = {};
-  for (const [key, descriptor] of Object.entries(properties)) {
-    descriptors[key] = {
-      configurable: true,
-      enumerable: true,
-      ...descriptor,
-    };
-  }
-  Object.defineProperties(obj, descriptors);
-}
-
+/*****************************************************************************
+ * OperationDetail
+ *****************************************************************************/
 export default class OperationDetail extends WorkingResult {
   static className = "稼働明細ベース";
   static collectionPath = "OperationDetails";
@@ -103,13 +104,13 @@ export default class OperationDetail extends WorkingResult {
 
   /**
    * Constructor
-   * - Prevent direct instantiation of OperationDetail class.
-   * @param {*} item
+   * - 抽象クラスのため、直接のインスタンス化を防止します。
+   * @param {Object} item - 初期化オブジェクト
    */
   constructor(item = {}) {
     if (new.target === OperationDetail) {
       throw new Error(
-        `OperationDetail is an abstract class and cannot be instantiated directly.`
+        `OperationDetail is an abstract class and cannot be instantiated directly.`,
       );
     }
     super(item);
@@ -117,26 +118,32 @@ export default class OperationDetail extends WorkingResult {
 
   /**
    * afterInitialize
-   * @param {*} item
+   * @param {Object} item - 初期化オブジェクト
    */
   afterInitialize(item = {}) {
     super.afterInitialize(item);
 
     /** Define computed properties */
-    defineComputedProperties(this, {
+    Object.defineProperties(this, {
       workerId: {
+        configurable: true,
+        enumerable: true,
         get() {
           return this.isEmployee ? this.id : `${this.id}:${this.index}`;
         },
         set() {},
       },
       employeeId: {
+        configurable: true,
+        enumerable: true,
         get() {
           return this.isEmployee ? this.id : null;
         },
         set() {},
       },
       outsourcerId: {
+        configurable: true,
+        enumerable: true,
         get() {
           return !this.isEmployee ? this.id : null;
         },
@@ -144,4 +151,27 @@ export default class OperationDetail extends WorkingResult {
       },
     });
   }
+
+  /***************************************************************************
+   * FOR DEPRECATED PROPERTIES
+   ***************************************************************************/
+  get key() {
+    console.warn(
+      "OperationDetail: `key` property is deprecated and should not be used.",
+    );
+    return null;
+  }
+
+  set key(v) {
+    console.warn(
+      "OperationDetail: `key` property is deprecated and should not be used.",
+    );
+  }
+
+  get isKeyChanged() {
+    console.warn(
+      "OperationDetail: `isKeyChanged` property is deprecated and should not be used.",
+    );
+    return false;
+  }
 }