@shisyamo4131/air-guard-v2-schemas 1.3.0 → 1.3.1-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shisyamo4131/air-guard-v2-schemas",
-  "version": "1.3.0",
+  "version": "1.3.1-dev.3",
   "description": "Schemas for AirGuard V2",
   "type": "module",
   "main": "index.js",
@@ -33,7 +33,10 @@
     "access": "public"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev:publish": "npm version prerelease --preid=dev && npm publish --tag dev",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
   },
   "peerDependencies": {
     "@shisyamo4131/air-firebase-v2": "^1.0.0"

package/src/Agreement.js

@@ -4,13 +4,13 @@
  * ---------------------------------------------------------------------------
  * A class to manage agreement details based on WorkingResult.
  * ---------------------------------------------------------------------------
- * @props {number} unitPriceBase - Base unit price (JPY)
- * @props {number} overtimeUnitPriceBase - Overtime unit price (JPY/hour)
- * @props {number} unitPriceQualified - Qualified unit price (JPY)
- * @props {number} overtimeUnitPriceQualified - Qualified overtime unit price (JPY/hour)
- * @props {string} billingUnitType - Billing unit type
- * @props {boolean} includeBreakInBilling - Whether to include break time in billing if `billingUnitType` is `PER_HOUR`.
- * @props {number} cutoffDate - Cutoff date value from CutoffDate.VALUES
+ * @prop {number} unitPriceBase - Base unit price (JPY)
+ * @prop {number} overtimeUnitPriceBase - Overtime unit price (JPY/hour)
+ * @prop {number} unitPriceQualified - Qualified unit price (JPY)
+ * @prop {number} overtimeUnitPriceQualified - Qualified overtime unit price (JPY/hour)
+ * @prop {string} billingUnitType - Billing unit type
+ * @prop {boolean} includeBreakInBilling - Whether to include break time in billing if `billingUnitType` is `PER_HOUR`.
+ * @prop {number} cutoffDate - Cutoff date value from CutoffDate.VALUES
  * - The cutoff date for billing, using values defined in the CutoffDate utility class.
  * ---------------------------------------------------------------------------
  * @getter {Object} prices - Object containing price-related properties (read-only)
@@ -20,15 +20,15 @@
  *   unitPriceQualified, overtimeUnitPriceQualified, billingUnitType, includeBreakInBilling
  * ---------------------------------------------------------------------------
  * @inherited - The following properties are inherited from WorkingResult:
- * @props {Date} dateAt - Applicable start date (trigger property)
- * @props {string} dayType - Day type (e.g., `WEEKDAY`, `WEEKEND`, `HOLIDAY`)
- * @props {string} shiftType - Shift type (`DAY`, `NIGHT`)
- * @props {string} startTime - Start time (HH:MM format)
- * @props {boolean} isStartNextDay - Next day start flag
+ * @prop {Date} dateAt - Applicable start date (trigger property)
+ * @prop {string} dayType - Day type (e.g., `WEEKDAY`, `WEEKEND`, `HOLIDAY`)
+ * @prop {string} shiftType - Shift type (`DAY`, `NIGHT`)
+ * @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`
- * @props {string} endTime - End time (HH:MM format)
- * @props {number} breakMinutes - Break time (minutes)
- * @props {number} regulationWorkMinutes - Regulation work minutes
+ * @prop {string} endTime - End time (HH:MM format)
+ * @prop {number} breakMinutes - Break time (minutes)
+ * @prop {number} regulationWorkMinutes - Regulation work minutes
  * - The maximum working time defined by `unitPriceBase` (or `unitPriceQualified`).
  * - Exceeding this time is considered overtime.
  * ---------------------------------------------------------------------------

package/src/Billing.js

@@ -9,16 +9,18 @@
  * @prop {string} billingMonth - billing month (YYYY-MM format)
  * @prop {Date} billingDate - billing date
  * @prop {Date} paymentDueDate - payment due date
+ *
+ * @prop {Array} paymentRecords - payment records (not implemented yet)
+ *
  * @prop {string} status - status (DRAFT/CONFIRMED/PAID/CANCELLED)
- * @prop {Array<OperationResult>} items - operation result items (raw data)
+ * @prop {Array<OperationResult>} operationResults - operation result documents.
  * @prop {Object} adjustment - adjustment
  * @prop {string} remarks - remarks
- * @prop {Object} pdfInfo - PDF information
  *
- * @computed {number} subtotal - subtotal (excluding tax)
- * @computed {number} taxAmount - tax amount
- * @computed {number} totalAmount - total amount (including tax)
- * @computed {Array<Object>} itemsSummary - billing items summary for display
+ * @prop {number} subtotal - subtotal (excluding tax) (computed-readonly)
+ * @prop {number} taxAmount - tax amount (computed-readonly)
+ * @prop {number} totalAmount - total amount (including tax) (computed-readonly)
+ * @prop {Array<Object>} itemsSummary - billing items summary for display (computed-readonly)
  *****************************************************************************/
 
 import FireModel from "@shisyamo4131/air-firebase-v2";
@@ -36,29 +38,21 @@ const classProps = {
   customerId: defField("customerId", { required: true }),
   siteId: defField("siteId", { required: true }),
   billingMonth: defField("oneLine", { required: true }),
-  billingDate: defField("date"),
-  paymentDueDate: defField("date"),
-  status: defField("oneLine", { default: STATUS.DRAFT }),
+  billingDateAt: defField("date"),
+  paymentDueDateAt: defField("date"),
 
-  // OperationResult の生データを配列で保持
-  items: defField("array", { customClass: OperationResult }),
+  // 入金管理用配列（現時点では未使用 将来の拡張用）
+  paymentRecords: defField("array", { default: [] }), // Not implemented yet
 
+  status: defField("oneLine", { default: STATUS.DRAFT }),
+  operationResults: defField("array", { customClass: OperationResult }),
   adjustment: defField("object", {
     default: {
       amount: 0,
       description: "",
     },
   }),
-
   remarks: defField("multipleLine"),
-
-  pdfInfo: defField("object", {
-    default: {
-      url: null,
-      generatedAt: null,
-      version: 1,
-    },
-  }),
 };
 
 export default class Billing extends FireModel {
@@ -75,13 +69,14 @@ export default class Billing extends FireModel {
     // 小計（税抜）を計算
     Object.defineProperty(this, "subtotal", {
       get() {
-        const itemsTotal = this.items.reduce((sum, item) => {
+        const itemsTotal = this.operationResults.reduce((sum, item) => {
           return sum + (item.salesAmount || 0);
         }, 0);
         return itemsTotal + (this.adjustment?.amount || 0);
       },
       set() {},
       enumerable: true,
+      configurable: true,
     });
 
     // 消費税額を計算
@@ -91,6 +86,7 @@ export default class Billing extends FireModel {
       },
       set() {},
       enumerable: true,
+      configurable: true,
     });
 
     // 合計金額（税込）を計算
@@ -100,12 +96,13 @@ export default class Billing extends FireModel {
       },
       set() {},
       enumerable: true,
+      configurable: true,
     });
 
     // 表示用の明細サマリーを生成
     Object.defineProperty(this, "itemsSummary", {
       get() {
-        return this.items.map((item) => ({
+        return this.operationResults.map((item) => ({
           operationResultId: item.docId,
           workDate: item.dateAt,
           shiftType: item.shiftType,
@@ -134,6 +131,7 @@ export default class Billing extends FireModel {
       },
       set() {},
       enumerable: true,
+      configurable: true,
     });
   }
 

package/src/Customer.js

@@ -1,8 +1,9 @@
 /*****************************************************************************
- * Customer ver 1.0.0
+ * Customer ver 1.1.0
  * @author shisyamo4131
  *
  * @description Customer model.
+ *
  * @hasMany Sites - related sites associated with the customer
  *
  * @prop {string} code - customer code
@@ -17,6 +18,8 @@
  * @prop {string} tel - telephone number
  * @prop {string} fax - fax number
  * @prop {string} contractStatus - contract status
+ * @prop {number} paymentMonth - payment site in months
+ * @prop {string} paymentDate - payment site date
  * @prop {string} remarks - additional remarks
  *
  * @readonly
@@ -31,6 +34,7 @@ import FireModel from "@shisyamo4131/air-firebase-v2";
 import { defField } from "./parts/fieldDefinitions.js";
 import { defAccessor } from "./parts/accessorDefinitions.js";
 import { VALUES } from "./constants/contract-status.js";
+import CutoffDate from "./utils/CutoffDate.js";
 
 const classProps = {
   code: defField("code", { label: "取引先コード" }),
@@ -45,6 +49,21 @@ const classProps = {
   tel: defField("tel", { colsDefinition: { cols: 12, sm: 6 } }),
   fax: defField("fax", { colsDefinition: { cols: 12, sm: 6 } }),
   contractStatus: defField("contractStatus", { required: true }),
+  paymentMonth: defField("number", {
+    default: 1,
+    label: "入金サイト（月数）",
+    required: true,
+  }),
+  paymentDate: defField("select", {
+    label: "入金サイト（日付）",
+    default: CutoffDate.VALUES.END_OF_MONTH,
+    required: true,
+    component: {
+      attrs: {
+        items: CutoffDate.OPTIONS,
+      },
+    },
+  }),
   remarks: defField("multipleLine", { label: "備考" }),
 };
 

package/src/OperationBilling.js

@@ -1,7 +1,8 @@
 /*****************************************************************************
- * OperationBilling Model ver 1.0.0
+ * OperationBilling Model
+ * @version 1.0.0
  * @author shisyamo4131
- * ---------------------------------------------------------------------------
+ *
  * - 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.
@@ -9,104 +10,111 @@
  * - 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.
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from OperationResult:
- * @props {string|null} siteOperationScheduleId - Associated SiteOperationSchedule document ID
- * - If this OperationBilling was created from a SiteOperationSchedule, this property holds that ID.
- * - If this property is set, the instance cannot be deleted.
- * @props {boolean} useAdjustedQuantity - Flag to indicate if adjusted quantities are used for billing
- * @props {number} adjustedQuantityBase - Adjusted quantity for base workers
- * - Quantity used for billing base workers when `useAdjustedQuantity` is true.
- * @props {number} adjustedOvertimeBase - Adjusted overtime for base workers
- * - Overtime used for billing base workers when `useAdjustedQuantity` is true.
- * @props {number} adjustedQuantityQualified - Adjusted quantity for qualified workers
- * - Quantity used for billing qualified workers when `useAdjustedQuantity` is true.
- * @props {number} adjustedOvertimeQualified - Adjusted overtime for qualified workers
- * - Overtime used for billing qualified workers when `useAdjustedQuantity` is true.
- * @props {Date} billingDateAt - Billing date
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from Operation (via OperationResult):
- * @props {string} siteId - Site document ID (trigger property)
+ *
+ * @prop {string} siteId - Site document ID (trigger property)
  * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * @props {number} requiredPersonnel - Required number of personnel
- * @props {boolean} qualificationRequired - Qualification required flag
- * @props {string} workDescription - Work description
- * @props {string} remarks - Remarks
- * @props {Array<OperationResultDetail>} employees - Assigned employees
- * - Array of `OperationResultDetail` instances representing assigned employees
- * @props {Array<OperationResultDetail>} outsourcers - Assigned outsourcers
- * - Array of `OperationResultDetail` instances representing assigned outsourcers
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from Agreement (via OperationResult):
- * @props {number} unitPriceBase - Base unit price (JPY)
- * @props {number} overtimeUnitPriceBase - Overtime unit price (JPY/hour)
- * @props {number} unitPriceQualified - Qualified unit price (JPY)
- * @props {number} overtimeUnitPriceQualified - Qualified overtime unit price (JPY/hour)
- * @props {string} billingUnitType - Billing unit type
- * @props {boolean} includeBreakInBilling - Whether to include break time in billing if `billingUnitType` is `PER_HOUR`.
- * @props {number} cutoffDate - Cutoff date value from CutoffDate.VALUES
- * - The cutoff date for billing, using values defined in the CutoffDate utility class.
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from WorkingResult (via OperationResult):
- * @props {Date} dateAt - Date of operation (placement date) (trigger property)
+ * @prop {Date} dateAt - Date of operation (placement date) (trigger property)
  * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * @props {string} dayType - Day type (e.g., `WEEKDAY`, `WEEKEND`, `HOLIDAY`)
- * @props {string} shiftType - `DAY` or `NIGHT` (trigger property)
+ * - Used to determine `dayType`.
+ * - When `dateAt` changes, `billingDateAt` is also updated based on `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.
- * @props {string} startTime - Start time (HH:MM format)
- * @props {boolean} isStartNextDay - Next day start flag
+ * @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`
- * @props {string} endTime - End time (HH:MM format)
- * @props {number} breakMinutes - Break time (minutes)
- * @props {number} regulationWorkMinutes - Regulation work minutes (trigger property)
+ * @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.
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from OperationResult:
- * @computed {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: {...} }
- * @computed {Object} sales - Sales amounts (read-only)
- * - Contains sales calculations for base and qualified workers, including overtime breakdowns.
- * - Structure: { base: {...}, qualified: {...} }
- * @computed {number} salesAmount - Total sales amount (read-only)
- * - Sum of sales amounts for base and qualified workers with rounding applied.
- * @computed {number} tax - Calculated tax amount (read-only)
- * - Calculated using the `Tax` utility based on `salesAmount` and `date`.
- * @computed {number} billingAmount - Total billing amount including tax (read-only)
- * - Sum of `salesAmount` and `tax`.
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from Operation (via OperationResult):
- * @computed {Array<string>} employeeIds - Array of employee IDs from `employees` (read-only)
- * @computed {Array<string>} outsourcerIds - Array of outsourcer IDs from `outsourcers` (read-only)
- * @computed {number} employeesCount - Count of assigned employees (read-only)
- * @computed {number} outsourcersCount - Count of assigned outsourcers (sum of amounts) (read-only)
- * @computed {boolean} isPersonnelShortage - Indicates if there is a shortage of personnel (read-only)
- * - `true` if the sum of `employeesCount` and `outsourcersCount` is less than `requiredPersonnel`
- * @computed {Array<OperationResultDetail>} workers - Combined array of `employees` and `outsourcers` (read-only)
+ * @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
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from WorkingResult (via OperationResult):
- * @computed {string} date - Date string in YYYY-MM-DD format based on `dateAt` (read-only)
+ * @prop {string|null} siteOperationScheduleId - Associated SiteOperationSchedule document ID
+ * - If this OperationResult was created from a SiteOperationSchedule, this property holds that ID.
+ * - If this property is set, the instance cannot be deleted.
+ * @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
+ *
+ * @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`.
- * @computed {Date} startAt - Start date and time (Date object) (read-only)
+ * @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.
- * @computed {Date} endAt - End date and time (Date object) (read-only)
+ * @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.
- * @computed {boolean} isSpansNextDay - Flag indicating whether the date spans from start date to end date (read-only)
+ * @prop {boolean} isSpansNextDay - Flag indicating whether the date spans from start date to end date (read-only)
  * - `true` if `startTime` is later than `endTime`
- * @computed {number} totalWorkMinutes - Total working time in minutes (excluding break time) (read-only)
+ * @prop {number} totalWorkMinutes - Total working time in minutes (excluding break time) (read-only)
  * - Calculated as the difference between `endAt` and `startAt` minus `breakMinutes`
- * @computed {number} regularTimeWorkMinutes - Regular working time in minutes (read-only)
+ * @prop {number} regularTimeWorkMinutes - Regular working time in minutes (read-only)
  * - The portion of `totalWorkMinutes` that is considered within the contract's `regulationWorkMinutes`.
- * @computed {number} overtimeWorkMinutes - Overtime work in minutes (read-only)
+ * @prop {number} overtimeWorkMinutes - Overtime work in minutes (read-only)
  * - Calculated as `totalWorkMinutes` minus `regulationWorkMinutes`
- * ---------------------------------------------------------------------------
- * @inherited - The following getter properties are inherited from Operation (via OperationResult):
+ * @prop {boolean} hasAgreement - Indicates if an Agreement is associated (read-only)
+ * @prop {boolean} isValid - Indicates if the OperationResult is valid (read-only)
+ * - Valid if either an Agreement is associated or adjusted quantities are not used.
+ * - If `hasAgreement` is true, always valid.
+ * @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} 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`
+ *
+ * @inherited - The following properties are inherited from Agreement (via Operation):
+ * @prop {number} unitPriceBase - Base unit price (JPY)
+ * @prop {number} overtimeUnitPriceBase - Overtime unit price (JPY/hour)
+ * @prop {number} unitPriceQualified - Qualified unit price (JPY)
+ * @prop {number} overtimeUnitPriceQualified - Qualified overtime unit price (JPY/hour)
+ * @prop {string} billingUnitType - Billing unit type
+ * @prop {boolean} includeBreakInBilling - Whether to include break time in billing if `billingUnitType` is `PER_HOUR`.
+ * @prop {number} cutoffDate - Cutoff date value from CutoffDate.VALUES
+ * - The cutoff date for billing, using values defined in the CutoffDate utility class.
+ * - Used to calculate `billingDateAt`.
+ * - When `cutoffDate` or `dateAt` changes, `billingDateAt` is automatically updated.
+ *
  * @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`
@@ -118,8 +126,6 @@
  * - 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
- * ---------------------------------------------------------------------------
- * @inherited - The following getter properties are inherited from WorkingResult (via OperationResult):
  * @getter {number} startHour - Start hour (0-23) (read-only)
  * - Extracted from `startTime`.
  * @getter {number} startMinute - Start minute (0-59) (read-only)
@@ -128,53 +134,51 @@
  * - Extracted from `endTime`.
  * @getter {number} endMinute - End minute (0-59) (read-only)
  * - Extracted from `endTime`.
- * ---------------------------------------------------------------------------
- * @inherited - The following methods are inherited from OperationResult:
- * @method {function} beforeDelete - Override method to prevent deletion with siteOperationScheduleId
+ *
+ * @method beforeDelete - Override method to prevent deletion with siteOperationScheduleId
  * - Prevents deletion if the instance has `siteOperationScheduleId`.
  * - Throws an error if deletion is attempted on an instance created from SiteOperationSchedule.
- * ---------------------------------------------------------------------------
- * @inherited - The following methods are inherited from Operation (via OperationResult):
- * @method {function} addWorker - Adds a new worker (employee or outsourcer)
+ * @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 {function} moveWorker - Moves the position of a worker (employee or outsourcer)
+ * @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 {function} changeWorker - Changes the details of a worker
+ * @method changeWorker - Changes the details of a worker
  * - @param {Object} newWorker - New worker object
- * @method {function} removeWorker - Removes a worker (employee or outsourcer)
+ * @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 {function} setSiteIdCallback - Callback method called when `siteId` is set
+ * @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 {function} setShiftTypeCallback - Callback method called when `shiftType` is set
+ * @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 {function} setRegulationWorkMinutesCallback - Callback method called when `regulationWorkMinutes` is set
+ * @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.
- * ---------------------------------------------------------------------------
- * @inherited - The following method is inherited from WorkingResult (via OperationResult):
- * @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 and synchronizes to workers.
- * - @param {Date} v - The new `dateAt` value
+ * - 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.
+ *
+ * @override 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.
  *****************************************************************************/
 import OperationResult from "./OperationResult.js";
 

package/src/OperationResult.js

@@ -1,13 +1,44 @@
 /*****************************************************************************
- * OperationResult Model ver 1.0.0
+ * OperationResult Model
+ * @version 1.2.0 - 2025-11-19 Add `agreement`, `hasAgreement`, `isValid` properties.
  * @author shisyamo4131
- * ---------------------------------------------------------------------------
+ *
  * - Extends Operation class to represent the result of an operation.
  * - Also incorporates Agreement class properties for pricing and billing information.
  * - Prevents deletion if the instance has `siteOperationScheduleId`.
  * - Provides comprehensive billing calculations including statistics, sales amounts, and tax.
  * - Supports both daily and hourly billing with adjusted quantities.
- * ---------------------------------------------------------------------------
+ * - Automatically updates `billingDateAt` based on `dateAt` and `cutoffDate`.
+ * - Introduces a lock mechanism (`isLocked`) to prevent edits when necessary.
+ *
+ * @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 `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.
  * - If this property is set, the instance cannot be deleted.
@@ -21,36 +52,57 @@
  * @prop {number} adjustedOvertimeQualified - Adjusted overtime for qualified workers
  * - Overtime used for billing qualified workers when `useAdjustedQuantity` is true.
  * @prop {Date} billingDateAt - Billing date
- * ---------------------------------------------------------------------------
- * @computed {Object} statistics - Statistics of workers (read-only)
+ * - 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
+ *
+ * @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)
+ * @prop {boolean} isValid - Indicates if the OperationResult is valid (read-only)
+ * - Valid if either an Agreement is associated or adjusted quantities are not used.
+ * - If `hasAgreement` is true, always valid.
+ * @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.
- * @computed {Object} sales - Sales amounts (read-only)
+ * @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.
- * @computed {number} salesAmount - Total sales amount (read-only)
+ * @prop {number} salesAmount - Total sales amount (read-only)
  * - Sum of sales amounts for base and qualified workers with rounding applied.
- * @computed {number} tax - Calculated tax amount (read-only)
+ * @prop {number} tax - Calculated tax amount (read-only)
  * - Calculated using the `Tax` utility based on `salesAmount` and `date`.
- * @computed {number} billingAmount - Total billing amount including tax (read-only)
+ * @prop {number} billingAmount - Total billing amount including tax (read-only)
  * - Sum of `salesAmount` and `tax`.
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from Operation:
- * @prop {string} siteId - Site document ID (trigger property)
- * - 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 {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`
+ *
  * @inherited - The following properties are inherited from Agreement (via Operation):
  * @prop {number} unitPriceBase - Base unit price (JPY)
  * @prop {number} overtimeUnitPriceBase - Overtime unit price (JPY/hour)
@@ -60,53 +112,9 @@
  * @prop {boolean} includeBreakInBilling - Whether to include break time in billing if `billingUnitType` is `PER_HOUR`.
  * @prop {number} cutoffDate - Cutoff date value from CutoffDate.VALUES
  * - The cutoff date for billing, using values defined in the CutoffDate utility class.
- * ---------------------------------------------------------------------------
- * @inherited - The following properties are inherited from WorkingResult (via Operation):
- * @prop {Date} dateAt - Date of operation (placement date) (trigger property)
- * - Automatically synchronizes to all `employees` and `outsourcers` when changed.
- * @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.
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from Operation:
- * @computed {Array<string>} employeeIds - Array of employee IDs from `employees` (read-only)
- * @computed {Array<string>} outsourcerIds - Array of outsourcer IDs from `outsourcers` (read-only)
- * @computed {number} employeesCount - Count of assigned employees (read-only)
- * @computed {number} outsourcersCount - Count of assigned outsourcers (sum of amounts) (read-only)
- * @computed {boolean} isPersonnelShortage - Indicates if there is a shortage of personnel (read-only)
- * - `true` if the sum of `employeesCount` and `outsourcersCount` is less than `requiredPersonnel`
- * @computed {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
- * ---------------------------------------------------------------------------
- * @inherited - The following computed properties are inherited from WorkingResult (via Operation):
- * @computed {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`.
- * @computed {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.
- * @computed {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.
- * @computed {boolean} isSpansNextDay - Flag indicating whether the date spans from start date to end date (read-only)
- * - `true` if `startTime` is later than `endTime`
- * @computed {number} totalWorkMinutes - Total working time in minutes (excluding break time) (read-only)
- * - Calculated as the difference between `endAt` and `startAt` minus `breakMinutes`
- * @computed {number} regularTimeWorkMinutes - Regular working time in minutes (read-only)
- * - The portion of `totalWorkMinutes` that is considered within the contract's `regulationWorkMinutes`.
- * @computed {number} overtimeWorkMinutes - Overtime work in minutes (read-only)
- * - Calculated as `totalWorkMinutes` minus `regulationWorkMinutes`
- * ---------------------------------------------------------------------------
- * @inherited - The following getter properties are inherited from Operation:
+ * - Used to calculate `billingDateAt`.
+ * - When `cutoffDate` or `dateAt` changes, `billingDateAt` is automatically updated.
+ *
  * @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`
@@ -118,8 +126,6 @@
  * - 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
- * ---------------------------------------------------------------------------
- * @inherited - The following getter properties are inherited from WorkingResult (via Operation):
  * @getter {number} startHour - Start hour (0-23) (read-only)
  * - Extracted from `startTime`.
  * @getter {number} startMinute - Start minute (0-59) (read-only)
@@ -128,52 +134,49 @@
  * - Extracted from `endTime`.
  * @getter {number} endMinute - End minute (0-59) (read-only)
  * - Extracted from `endTime`.
- * ---------------------------------------------------------------------------
- * @method {function} beforeDelete - Override method to prevent deletion with siteOperationScheduleId
+ *
+ * @method beforeDelete - Override method to prevent deletion with siteOperationScheduleId
  * - Prevents deletion if the instance has `siteOperationScheduleId`.
  * - Throws an error if deletion is attempted on an instance created from SiteOperationSchedule.
- * ---------------------------------------------------------------------------
- * @inherited - The following methods are inherited from Operation:
- * @method {function} addWorker - Adds a new worker (employee or outsourcer)
+ * @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 {function} moveWorker - Moves the position of a worker (employee or outsourcer)
+ * @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 {function} changeWorker - Changes the details of a worker
+ * @method changeWorker - Changes the details of a worker
  * - @param {Object} newWorker - New worker object
- * @method {function} removeWorker - Removes a worker (employee or outsourcer)
+ * @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 {function} setSiteIdCallback - Callback method called when `siteId` is set
+ * @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 {function} setShiftTypeCallback - Callback method called when `shiftType` is set
+ * @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 {function} setRegulationWorkMinutesCallback - Callback method called when `regulationWorkMinutes` is set
+ * @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.
- * ---------------------------------------------------------------------------
- * @inherited - The following method is inherited from WorkingResult (via Operation):
- * @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 and synchronizes to workers.
- * - @param {Date} v - The new `dateAt` value
+ * - 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.
+ *
+ * @override setDateAtCallback - Updates `billingDateAt` based on the new `dateAt` value.
  *****************************************************************************/
 import Operation from "./Operation.js";
 import Agreement from "./Agreement.js";
@@ -214,6 +217,13 @@ const classProps = {
   outsourcers: defField("array", {
     customClass: OperationResultDetail,
   }),
+  isLocked: defField("check", {
+    label: "ロック",
+    default: false,
+  }),
+
+  /** add */
+  agreement: defField("object", { label: "取極め", customClass: Agreement }),
 };
 
 export default class OperationResult extends Operation {
@@ -421,9 +431,46 @@ export default class OperationResult extends Operation {
         },
         set(v) {},
       },
+      billingMonth: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          if (!this.billingDateAt) return null;
+          const jstDate = new Date(
+            this.billingDateAt.getTime() + 9 * 60 * 60 * 1000
+          ); /* JST補正 */
+          const year = jstDate.getUTCFullYear();
+          const month = jstDate.getUTCMonth() + 1;
+          return `${year}-${String(month).padStart(2, "0")}`;
+        },
+        set(v) {},
+      },
+
+      /** add */
+      hasAgreement: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          return this.agreement != null;
+        },
+        set(v) {},
+      },
+      isValid: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          if (this.hasAgreement) return true;
+          return !this.hasAgreement && !this.useAdjustedQuantity;
+        },
+        set(v) {},
+      },
     });
   }
 
+  /**
+   * Refresh billingDateAt based on dateAt and cutoffDate
+   * @returns {void}
+   */
   refreshBillingDateAt() {
     if (!this.dateAt) {
       this.billingDateAt = null;
@@ -439,6 +486,10 @@ export default class OperationResult extends Operation {
     );
   }
 
+  /**
+   * Override `setDateAtCallback` to refresh billingDateAt
+   * @param {Date} v
+   */
   setDateAtCallback(v) {
     super.setDateAtCallback(v);
     this.refreshBillingDateAt();
@@ -456,4 +507,32 @@ export default class OperationResult extends Operation {
       );
     }
   }
+
+  /**
+   * Override update method to prevent editing if isLocked is true
+   * @param {*} options
+   * @returns {Promise<void>}
+   */
+  async update(options = {}) {
+    if (this.isLocked) {
+      throw new Error(
+        "[OperationResult] This OperationResult is locked and cannot be edited."
+      );
+    }
+    return super.update(options);
+  }
+
+  /**
+   * Override delete method to prevent deletion if isLocked is true
+   * @param {*} options
+   * @returns {Promise<void>}
+   */
+  async delete(options = {}) {
+    if (this.isLocked) {
+      throw new Error(
+        "[OperationResult] This OperationResult is locked and cannot be deleted."
+      );
+    }
+    return super.delete(options);
+  }
 }