Research and Unification Plan for Object Class Creation (ItemType Instance)

Time: 2026-07-09 18:38+

Background: User requirements: (1) Fix the correct invocation of the unified-create pre-check hook. (2) Unify the create interface conventions. (3) For Part's hc_copied_from, skip directly if pre-creation fails. (4) First, research the current state of object class creation in ItemTypeManagement.vue, then discuss unification with ordinary object creation.

The first three items have been completed and verified; this document focuses on the findings of item 4.

I. Implementation of the Three Fixes (Completed)

1. Correct Invocation of the Pre-check Hook

• The ENABLE_RULE_PRECHECK hook in unified-create.js originally called rule-engine.createItem (a dead end: the local sciot_sequences table is empty, causing numbering to always fail).
• Changed to call relationship-resolver.resolveExistence(itemType, properties) -- real SCSAI deduplication, which already includes selection by type for name/title + hit value validation (prevents misjudgment). Returns 409 to block on exact_match, disabled by default to avoid breaking existing behavior.

1. The create interface convention is unified

• CapabilityRuntime.create(context, options) now uniformly supports three forms:
• { item_type, data, relationships, item_properties } (legacy convention)
• { itemType, properties, relationships, itemProperties } (consistent with unified-create)
• Positional create(itemType, properties, relationships, itemProperties, options)
• capability-pipeline.createObject is changed to delegate to CapabilityRuntime.create(new instance), retaining the fallback to write local_objects when SCSAI is unavailable.
• Verification: All three forms + ECN creation succeeded.

1. Pre-creation of part's hc_copied_from failed → skipped.

• In unified-create.js, when pre-creating item_property fails, only a warning is logged and it skips (non-mandatory attribute), meeting the 'skip directly' requirement, no extra handling.

II. Current Research on ItemTypeManagement.vue Object Class Creation

2.1 How It Works

• File: src/views/ItemTypeManagement.vue (99KB).
• Creation entry: createItemTypeInSCSAI() (line 1301).
• Process:

1. Duplicate check: Use rawQuery to check if an ItemType with the same name already exists in SCSAI.
2. Related object class ID pre-check: For each related_item_type in def.relationships, query the ItemType id and store in relatedIds.
3. Build relationships array, containing two types of relationships:

• relationship_type: 'Property' → inline related_items (each with name/label/data_type/is_required/stored_length/default_value);
• relationship_type: 'RelationshipType' → inline related_items (name/label + item_properties.related_id referencing the associated ItemType).

1. Call createViaUseCreate({ itemType:'ItemType', properties:{name,label,description}, relationships, options:{skipDedup:true, skipAiCorrect:true} }).

• createViaUseCreate comes from useCreate.js (L966 import, L1060 instantiation) — i.e., the older, frontend‑direct‑to‑SCSAI composable.

2.2 Can it be created successfully?

• Yes. The create() (L750) in useCreate.js is a mature client‑side creator, connecting directly to SCSAI via bomService._SCSAIApiRequest('ApplyItem', aml).
• It has special handling for self‑referencing system relationship types like Property / RelationshipType (L586 skipPrecreateRelTypes = ['Property','RelationshipType'], not pre‑created independently, but inlined into the parent‑child ItemType's AML).
• createRelationshipsRecursive (L492) correctly submits Property/RelationshipType as inline relationship items within the ItemType.
• Conclusion: Object classes (ItemType definitions, including property lists + relationship types) can be successfully created in SCSAI.

2.3 Can we create a "complex object class" like Part?

• Here we need to distinguish two meanings:
• (A) Creating a "definition of a complex object class" (i.e., creating a new ItemType called MyComplexPart with 20 Properties + multiple RelationshipTypes): ✅ Yes, because createItemTypeInSCSAI in ItemTypeManagement does exactly that.
• (B) Creating a "Part instance" (business data): ❌ This is not the responsibility of ItemTypeManagement; it builds "classes," not "instances." Part instance creation follows the unified unified-create.js (backend 7‑step process), which has been verified to work.
• Therefore, when "complex object classes like Part" refers to (A), the answer is yes; the entire process relies on the nested relationship capability of useCreate, and the path is complete in actual testing.

⚠️ Correction (2026-07-09 19:24 user correction): The original table in section 2.4 below and the conclusion that "the handling logic for the relationship between the two is fundamentally different" are conceptual errors and are now invalid.

Evidence from actual testing can be found in inv_model (real SCSAI investigation):

• Sequence is an ItemType (is_relationship=0, a regular class), and has real instances (acc_AccountPayable, etc.) → SEQUENCE is a regular object class.
• Property / RelationshipType are both ItemTypes, but with is_relationship=1 (relational type); attempting to add a Property independently reports 'source item has to be specified' → can only be created inline within a relationship, not independently.
• Part has 19 relationship types, with 'related' pointing to various ItemTypes (Part / Manufacturer Part / HC Validation…).

The correct model (SCSAI Unified Object Model): Everything is an Item, and an Item must belong to an ItemType; ItemType itself is just an instance of the ItemType 'ItemType'. Property/RelationshipType/Sequence/WBS/Part are all Items without exception.

"Object class creation" and "regular object creation" have no distinction at the model layer; both are "performing an add for a specific ItemType". The differences in code paths (inline in useCreate, pre-built/numbered in unified-create) are the root cause of the mistaken perception of a model difference.

What truly drives the differences is only the per-ItemType metadata, not 'class vs. instance':

• is_relationship=1 → This Item can only be inlined within a relationship (Property/RelationshipType) and cannot be added independently;
• Has keyed fields → Requires numbering (Part/ECN/Document; ItemType uses name as identifier, no keyed fields);
• Mandatory references → Pre-create or inline;
• Project→Top-level WBS is a specific business constraint of the SCSAI Method, belonging to 'individual ItemType hooks', not a mechanism exclusive to 'class creation'.

Therefore, there is only one set of relationship logic; differences are driven by metadata. The current code treats Property/RelationshipType as 'special types hardcoded for inlining' and unified-create as 'inlining only when pre-creation fails'—both paths are not truly metadata-driven, which is the real problem that needs unification (see corrections in Section 3).

3. Unification Approach (Corrected Version, to be implemented after user approval)

Core principle: Single entry point + behavior driven by per-ItemType metadata, not split by 'class/instance'.

Since SCSAI is a unified object model, the correct unification is not 'opening a special branch for ItemType', but having the sole unified-create.js handleCreate (7 core steps) treat all ItemTypes equally, with every step's variation derived from that ItemType's actual metadata:

1. ID: Read the keyed field of sciot_properties/SCSAI metadata → if present, use getNextItemNumber; if absent (e.g., ItemType identified by name), skip. No hardcoded branches like itemType==='ItemType'.
2. Inline vs. pre‑create relationships: Read the is_relationship flag of the related ItemType (actual measurement shows Property/RelationshipType = 1) → related Items with is_relationship=1 must be inlined, never attempted for independent pre‑creation; only those with is_relationship=0 (ordinary classes like Part) follow pre‑create/reference. The current useCreate incorrectly hardcodes Property/RelationshipType as a name and treats unified‑create as a 'fallback to inline after pre‑create fails'—this should be changed to: uniformly check the is_relationship metadata to decide; hardcoding names is a source of bugs.
3. Per-ItemType hooks: Project→top-level WBS, ECN→title identifier, etc., serve as pluggable hooks per ItemType (already handled by type in resolver/numbering), without breaking the unified flow.

Recommended implementation:

• Modify relationship handling in unified-create.js: For each related_item_type, check its is_relationship metadata to decide inline/pre-build (replacing current hardcoded ['Property','RelationshipType'] names). Frontend ItemTypeManagement.vue should call /api/unified/create with { itemType:'ItemType', properties, relationships }, processed by the same 7-step core.
• Extract the is_relationship judgment logic from useCreate.js (frontend legacy path) into a directly reusable pure function, called uniformly by the backend to ensure semantic consistency.
• Benefits: Object-class creation also gains unified existence pre-check, logging, and fallback; completely eliminates the split between 'class vs. instance' code paths.

Note: The previous approach of 'adding an ItemType branch in unified-create, skipping numbering/pre-build' still implied 'special handling by type,' contradicting the unified model, and has been replaced by this correction.

IV. Implementation and Verification (From 2026-07-09 19:50, Completed)

Changes (server/routes/unified-create.js):

1. Added isRelationshipItemType(typeName) metadata-driven determination: First check local rule_engine.db.sciot_item_types.is_relationship, if missing, then query SCSAI in real-time for ItemType's is_relationship (unified object model: ItemType itself is also an Item), with results cached.
2. Modified createRelationshipsRecursive to: For each related_item_type, first check isRelationshipItemType; if =true (e.g., Property/RelationshipType), directly inline, skipping independent pre-creation; only regular ItemTypes proceed with precreateItem.
3. Removed original hardcoded keyed field fallback logic based on type names ['Part','Document','CAD','ECR','ECN','ECO'] / 'Project'—now using generic subProps required keyed completion logic. is_relationship determination no longer relies on the ['Property','RelationshipType'] name list.

Verification (Real SCSAI):

• ✅ Successfully created a complex object class via the unified entry point handleCreate(null,null,{itemType:'ItemType',...}): containing 3 custom Properties (field_a/field_b/field_c) + 1 RelationshipType, with no source item required error (proving metadata-driven inlining is effective). Environment cleaned up with delete after verification.
• ✅ Regression verify-capability-line.mjs: All 6 capabilities (create/repair/optimize/compare/generate/identify) are success.
• ✅ Regular object Part creation remains success (unified entry point unaffected).

Conclusion: Unified object model implementation—handleCreate (7 core steps) treats all ItemTypes equally; relationship behavior is entirely driven by per-ItemType is_relationship metadata, no longer branching by "class/instance" or type name.

Remaining migration (to-do, non-blocking):

• Frontend src/views/ItemTypeManagement.vue (L966/L1060) still directly calls new useCreate (old frontend path) to create object classes; inside useCreate.js, handling for Property/RelationshipType still uses hardcoded names ['Property','RelationshipType'] (L586).
• Recommendation: Have ItemTypeManagement.vue switch to calling the backend /api/unified/create (same handleCreate), and simultaneously replace the hardcoded logic in useCreate.js with reused isRelationshipItemType logic, completely eliminating the split.

IV. To Be Confirmed

• Should the ItemType branching be unified according to the "Recommended Solution in Section III"? (Requires user approval before code changes)
• After implementation, should useCreate.js be removed from ItemTypeManagement, or just add the new backend entry point while keeping both?
• Should regular business pages (non-ItemType management) also migrate to unified-create? (Currently still using the old useCreate path, which carries the risk of nested bug paths.)