@shisyamo4131/air-guard-v2-schemas 2.4.2-dev.4 → 2.4.2-dev.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shisyamo4131/air-guard-v2-schemas",
-  "version": "2.4.2-dev.4",
+  "version": "2.4.2-dev.6",
   "description": "Schemas for AirGuard V2",
   "type": "module",
   "main": "index.js",

package/src/Operation.js

@@ -57,11 +57,13 @@
  * - Setter: Splits array into employees and outsourcers based on `isEmployee` property
  *
  * @property {string} key - `siteId`, `date`, `dayType`, `shiftType` を組み合わせたキー。（読み取り専用）
- * - 2026-01-07 現在使用していないプロパティ。
- * - `dayType` は請求時の単価情報を取得するために必要な情報であるため含める必要がないと思われる。
+ * - `WorkingResult.key` をオーバーライドして `siteId` を含めるように定義されているが、未使用。
+ *
+ * @property {string} agreementKey - `siteId`, `date`, `dayType`, `shiftType` を組み合わせたキー。（読み取り専用）
+ * - 適用する取極めを特定するためのキーとして使用される。
  *
  * @property {string} orderKey - `siteId`, `shiftType` を組み合わせたキー。（読み取り専用）
- * - `siteOrder` の `key` プロパティに対応するキー。
+ * - `siteOrder` の `key` プロパティに対応するキー。稼働予測や配置管理で使用される。
  *
  * @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)
@@ -283,6 +285,19 @@ export default class Operation extends WorkingResult {
         set() {},
       },
 
+      /**
+       * `siteId`, `date`, `dayType`, `shiftType` を組み合わせたキー。（読み取り専用）
+       * - 適用する取極めを特定するためのキーとして使用される。
+       */
+      agreementKey: {
+        configurable: true,
+        enumberable: true,
+        get() {
+          return `${this.siteId}-${this.date}-${this.dayType}-${this.shiftType}`;
+        },
+        set() {},
+      },
+
       /**
        * `siteId`, `shiftType` を組み合わせたキー。（読み取り専用）
        * - `siteOrder` の `key` プロパティに対応するキー。

package/src/OperationResult.js

@@ -1,6 +1,5 @@
 /*****************************************************************************
  * 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.
@@ -12,6 +11,8 @@
  *
  * @property { string } key - {@link Operation#key}
  *
+ * @property {string} agreementKey - {@link Operation#agreementKey}
+ *
  * @property {string} orderKey - {@link Operation#orderKey}
  *
  * @property {string} siteId - Site document ID (trigger property)
@@ -544,7 +545,6 @@ export default class OperationResult extends Operation {
   /**
    * Synchronize customerId and apply (re-apply) agreement from siteId
    * @param {Object} [args.transaction] - Firestore transaction.
-   * @param {Function} [args.callBack] - Callback function.
    * @param {string} [args.prefix] - Path prefix.
    * @returns {Promise<void>}
    * @throws {Error} If the specified siteId does not exist
@@ -601,7 +601,11 @@ export default class OperationResult extends Operation {
     }
 
     // Sync customerId and apply agreement if key changed
-    if (this.key === this._beforeData.key) return;
+    /**
+     * 2026-01-08 `agreementKey` を実装したため、`key` の使用を避ける。
+     */
+    // if (this.key === this._beforeData.key) return;
+    if (this.agreementKey === this._beforeData.agreementKey) return;
     await this._syncCustomerIdAndApplyAgreement();
   }
 

package/src/Site.js

@@ -1,16 +1,17 @@
 /**
  * @file src/Site.js
  * @author shisyamo4131
- * @version 1.1.0
- * @update 2025-11-20 version 0.2.0-bata
- *                    - Prevent changing customer reference on update.
- *                    - Move `customer` property to the top of classProps for better visibility.
  *
- * NOTE: `customer` プロパティについて
- * 自身の従属先データを持たせる場合に `XxxxxMinimal` クラスを使用するが、アプリ側でオブジェクト選択を行う場合に
- * `Xxxxx` クラスにするのか `XxxxxMinimal` クラスにするのかを判断できないため、docId を持たせて
- * `beforeCreate` フックでオブジェクトを取得するようにする。
- * 尚、取引先は変更できない仕様。
+ * NOTE: `customerId`, `customer` プロパティについて
+ * - 仮登録
+ *   - 取引先未定での現場登録のシチュエーションを考慮して現場情報は仮登録を可能とする。
+ *   - 仮登録状態の現場は `isTemporary` プロパティが `true` となる。
+ *   - 但し、一度取引先を設定した後に未設定に戻すことはできない。
+ *   - 取引先未設定の場合に、`Site` インスタンスから取引先名を参照する必要があるケースに備えて
+ *     `customerName` プロパティを設ける。
+ * - 自身の従属先データを持たせる場合に `XxxxxMinimal` クラスを使用するが、アプリ側でオブジェクト選択を行う場合に
+ *   `Xxxxx` クラスにするのか `XxxxxMinimal` クラスにするのかを判断できないため、docId を持たせて
+ *   `beforeCreate` フックでオブジェクトを取得するようにする。
  */
 import { default as FireModel } from "@shisyamo4131/air-firebase-v2";
 import { defField } from "./parts/fieldDefinitions.js";
@@ -21,17 +22,35 @@ import { VALUES } from "./constants/site-status.js";
 import { GeocodableMixin } from "./mixins/GeocodableMixin.js";
 
 const classProps = {
+  // customerId: defField("customerId", {
+  //   required: true,
+  //   component: {
+  //     attrs: {
+  //       disabled: ({ editMode }) => {
+  //         return editMode !== "CREATE";
+  //       },
+  //     },
+  //   },
+  // }),
   customerId: defField("customerId", {
-    required: true,
     component: {
       attrs: {
-        disabled: ({ editMode }) => {
-          return editMode !== "CREATE";
+        /**
+         * `_beforeData.customerId` が存在する場合（本登録後の編集時を表す）には `customerId` を必須とする。
+         */
+        required: ({ item }) => {
+          return !!item._beforeData.customerId;
         },
       },
     },
   }),
   customer: defField("customer", { hidden: true, customClass: Customer }),
+  customerName: defField("name", {
+    label: "取引先名",
+    required: ({ item }) => {
+      return !item.customerId; // isTemporary プロパティでの判定でも良いか？
+    },
+  }),
   code: defField("code", { label: "現場コード" }),
   name: defField("name", {
     label: "現場名",
@@ -55,24 +74,34 @@ const classProps = {
 };
 
 /*****************************************************************************
- * @props {string} code - Site code.
- * @props {string} name - Site name.
- * @props {string} nameKana - Site name in Kana.
- * @props {string} zipcode - Postal code.
- * @props {string} prefCode - Prefecture code.
- * @props {string} city - City name.
- * @props {string} address - Address details.
- * @props {string} building - Building name.
- * @props {object} location - Geographical location.
- * @props {object} customer - Associated customer (CustomerMinimal).
- * @props {string} remarks - Additional remarks.
- * @props {array} agreements - List of agreements (Agreement).
+ * @property {string} customerId - 取引先ドキュメントID
+ *
+ * @property {object} customer - 取引先オブジェクト
+ * - `beforeCreate`, `beforeUpdate` で `customerId` に該当する `Customer` オブジェクトと自動的に同期されます。
+ * - `Customer` が更新された場合は Cloud Functions で同期される必要があります。
+ *
+ * @property {string} code - Site code.
+ * @property {string} name - Site name.
+ * @property {string} nameKana - Site name in Kana.
+ * @property {string} zipcode - Postal code.
+ * @property {string} prefCode - Prefecture code.
+ *
+ * @property {string} prefecture - Prefecture name derived from `prefCode` (read-only)
+ *
+ * @property {string} city - City name.
+ * @property {string} address - Address details.
+ * @property {string} building - Building name.
+ *
+ * @property {string} fullAddress - Full address combining prefecture, city, and address (read-only)
+ *
+ * @property {object} location - Geographical location.
+ * @property {string} remarks - Additional remarks.
+ * @property {array} agreements - List of agreements (Agreement).
  * - Enhanced with custom methods: `add()`, `change()`, `remove()`
- * @props {string} status - Site status.
  *
- * @computed {string} customerId - ID of the associated customer (read-only)
- * @computed {string} fullAddress - Full address combining prefecture, city, and address (read-only)
- * @computed {string} prefecture - Prefecture name derived from `prefCode` (read-only)
+ * @property {string} status - Site status.
+ *
+ * @property {boolean} isTemporary - 仮登録状態かどうかを表すフラグ
  *
  * @function getAgreement
  * Gets applicable agreement based on date, dayType, and shiftType.
@@ -127,31 +156,51 @@ export default class Site extends GeocodableMixin(FireModel) {
   static STATUS_TERMINATED = VALUES.TERMINATED.value;
 
   /**
-   * Overrides to fetch and set the customer object before creation.
-   * @param {Object} args - Creation options.
-   * @param {string} [args.docId] - Document ID to use (optional).
-   * @param {boolean} [args.useAutonumber=true] - Whether to use auto-numbering.
-   * @param {Object} [args.transaction] - Firestore transaction.
-   * @param {Function} [args.callBack] - Callback function.
-   * @param {string} [args.prefix] - Path prefix.
+   * `customerId` に該当する `Customer` インスタンスを取得して `customer` プロパティにセットします。
+   * - `customerId` が未設定の場合は何もしません。
    * @returns {Promise<void>}
+   * @throws {Error} `Customer` が存在しない場合にスローされます。
    */
-  async beforeCreate(args = {}) {
-    await super.beforeCreate(args);
+  async _setCustomer() {
     if (!this.customerId) return;
     const customerInstance = new Customer();
     const isExist = await customerInstance.fetch({
-      ...args,
       docId: this.customerId,
     });
     if (!isExist) {
-      return Promise.reject(
-        new Error("Invalid customerId: Customer does not exist.")
-      );
+      throw new Error("Customer does not exist.");
     }
     this.customer = customerInstance;
   }
 
+  /**
+   * ドキュメント作成直前の処理です。
+   * - `customerId` に該当する `Customer` インスタンスを取得して `customer` プロパティにセットします。
+   * @param {Object} args - Creation options.
+   * @param {string} [args.docId] - Document ID to use (optional).
+   * @param {boolean} [args.useAutonumber=true] - Whether to use auto-numbering.
+   * @param {Object} [args.transaction] - Firestore transaction.
+   * @param {Function} [args.callBack] - Callback function.
+   * @param {string} [args.prefix] - Path prefix.
+   * @returns {Promise<void>}
+   */
+  async beforeCreate(args = {}) {
+    await super.beforeCreate(args);
+    // if (!this.customerId) return;
+    // const customerInstance = new Customer();
+    // const isExist = await customerInstance.fetch({
+    //   ...args,
+    //   docId: this.customerId,
+    // });
+    // if (!isExist) {
+    //   return Promise.reject(
+    //     new Error("Invalid customerId: Customer does not exist.")
+    //   );
+    // }
+    // this.customer = customerInstance;
+    await this._setCustomer();
+  }
+
   /**
    * Override beforeUpdate to prevent changing customer reference.
    * @param {Object} args - Creation options.
@@ -162,10 +211,21 @@ export default class Site extends GeocodableMixin(FireModel) {
    */
   async beforeUpdate(args = {}) {
     await super.beforeUpdate(args);
-    if (this.customer.docId !== this._beforeData.customer.docId) {
-      return Promise.reject(
-        new Error("Not allowed to change customer reference.")
-      );
+
+    // if (this.customer.docId !== this._beforeData.customer.docId) {
+    //   return Promise.reject(
+    //     new Error("Not allowed to change customer reference.")
+    //   );
+    // }
+
+    // 取引先を未設定に戻すことはできない。
+    if (this._beforeData.customerId && !this.customerId) {
+      throw new Error("Cannot unset customerId once it is set.");
+    }
+
+    // 取引先が変更されていた場合は `customer` プロパティを更新する。
+    if (this.customerId !== this._beforeData.customerId) {
+      await this._setCustomer();
     }
   }
 
@@ -173,12 +233,26 @@ export default class Site extends GeocodableMixin(FireModel) {
     super.afterInitialize(item);
 
     Object.defineProperties(this, {
-      // customerId: defAccessor("customerId"),
       fullAddress: defAccessor("fullAddress"),
       prefecture: defAccessor("prefecture"),
+      isTemporary: {
+        configurable: true,
+        enumerable: true,
+        get() {
+          return !!this.customerId;
+        },
+        set() {},
+      },
     });
 
     const self = this;
+
+    /**
+     * `Agreement` プロパティに対するカスタムメソッドを定義します。
+     * - add(agreement): `Agreement` インスタンスを追加します。
+     * - change(newAgreement): `key` プロパティを基に既存の `Agreement` を置き換えます。
+     * - remove(agreement): `key` プロパティを基に `Agreement` を削除します。
+     */
     Object.defineProperties(this.agreements, {
       add: {
         value: function (agreement) {

package/src/SiteOperationSchedule.js

@@ -20,6 +20,8 @@
  *
  * @property { string } key - {@link Operation#key}
  *
+ * @property {string} agreementKey - {@link Operation#agreementKey}
+ *
  * @property {string} orderKey - {@link Operation#orderKey}
  *
  * @property {string|null} operationResultId - Associated OperationResult document ID

package/src/WorkingResult.js

@@ -27,7 +27,7 @@
  * - The maximum working time defined by `unitPriceBase` (or `unitPriceQualified`).
  * - Exceeding this time is considered overtime.
  *
- * @property {string} key - `date`, `dayType`, `shifType` を組み合わせたユニークキー。（読み取り専用）
+ * @property {string} key - `date`, `dayType`, `shiftType` を組み合わせたユニークキー。（読み取り専用）
  * - 継承先である `Agreement` でデータを一意に識別するためのキーとして使用されます。
  *
  * @property {string} date - Date string in YYYY-MM-DD format based on `dateAt` (read-only)