Custom Fields · Merchant Extensibility

Contexto 1. El problema que resuelve

Cuatro restricciones simultáneas que descartan los approaches obvios:

1. Campos arbitrarios por merchant por entidad — cada vertical tiene requisitos propios. Un schema compartido no puede crecer por cada uno.
2. Performance de lectura en POS — el barcode scan debe completar en <5 ms incluyendo cualquier custom field que acompañe el producto.
3. Indexable para búsqueda — "dame todos los productos con NDC que expiran este mes" tiene que correr rápido.
4. Offline-compatible — los POS terminales usan SQLite; el approach debe replicarse.

Por qué los tres approaches "obvios" no funcionan solos

Decisión 2. JSON column + CustomFieldDefinition

Cada entidad extendible (Product, Customer, Sale, Employee) gana una columna CustomFields nvarchar(max) DEFAULT '{}' con CHECK (ISJSON(CustomFields) = 1). Una tabla nueva CustomFieldDefinition describe, per-merchant, qué campos existen para cada EntityType. Los campos marcados IsSearchable = true materializan un computed/generated column indexable.

Path de migración a native json type

Hoy: nvarchar(max) + ISJSON (compatible SQL 2022 + Azure SQL DB + SQLite). Cuando todos los environments soporten native json (SQL Server 2025 / Azure SQL DB current), migración no-breaking via ALTER COLUMN CustomFields json NOT NULL. Storage ~15% más compacto, parsing más rápido, dedicated JSON indexes (reemplazan computed columns).

Schema 3. ERD y DDL

Computed/Generated column para IsSearchable

Al marcar IsSearchable=true, el sistema agrega:

-- SQL Server (cloud):
ALTER TABLE Product ADD CustomField_ExpirationDate
    AS CAST(JSON_VALUE(CustomFields, '$.expiration_date') AS date) PERSISTED;

CREATE NONCLUSTERED INDEX IX_Product_CF_ExpirationDate
    ON Product(MerchantId, CustomField_ExpirationDate)
    WHERE CustomField_ExpirationDate IS NOT NULL;

-- SQLite (POS terminal — applied by posupdate.exe):
ALTER TABLE Product ADD COLUMN CustomField_ExpirationDate
    AS (json_extract(CustomFields, '$.expiration_date')) STORED;

CREATE INDEX IX_Product_CF_ExpirationDate
    ON Product(CustomField_ExpirationDate);

Flow 4. Ciclo de vida completo

Mockup 5. UI admin portal

5.1 Definir un custom field

5.2 Editar un Product con custom fields

Performance 6. Queries típicas

6.1 Barcode scan (POS hot path)

SELECT * FROM Product WHERE MerchantId = @m AND Sku = @sku;
-- 1 row read, CustomFields JSON inline, <1ms

6.2 Display en UI (extract específico)

-- SQL Server
SELECT
    Name,
    JSON_VALUE(CustomFields, '$.ndc_number') AS Ndc,
    JSON_VALUE(CustomFields, '$.expiration_date') AS Expiration
FROM Product WHERE Id = @id;

-- SQLite (POS terminal)
SELECT
    Name,
    json_extract(CustomFields, '$.ndc_number') AS Ndc,
    json_extract(CustomFields, '$.expiration_date') AS Expiration
FROM Product WHERE Id = @id;

6.3 Búsqueda indexed (reporting, alerts)

-- Productos que expiran este mes — usa el index
SELECT Id, Name, CustomField_ExpirationDate
FROM Product
WHERE MerchantId = @m
  AND CustomField_ExpirationDate BETWEEN @start AND @end
ORDER BY CustomField_ExpirationDate;
-- Performance idéntica a una columna real indexed

6.4 Bulk update (merchant admin)

UPDATE Product
SET CustomFields = JSON_MODIFY(CustomFields, '$.expiration_date', '2027-12-31')
WHERE MerchantId = @m AND CategoryId = @rxCategoryId;

Ejemplos 7. Custom fields por vertical

-- CustomFieldDefinition rows (seeded por módulo pharmacy.rx):
{ EntityType: "Product", FieldKey: "ndc_number",     DataType: "string",  IsRequired: true,  Module: "pharmacy" }
{ EntityType: "Product", FieldKey: "expiration_date", DataType: "date",    IsSearchable: true, Module: "pharmacy" }
{ EntityType: "Product", FieldKey: "lot_number",     DataType: "string",  Module: "pharmacy" }
{ EntityType: "Product", FieldKey: "dea_schedule",   DataType: "select",  Options: '["CII","CIII","CIV","CV"]', Module: "pharmacy.controlled" }

-- Product row con estos custom fields:
{
  "Name": "Oxycodone 5mg",
  "CustomFields": {
    "ndc_number": "12345-678-90",
    "expiration_date": "2027-06-15",
    "lot_number": "LOT-A7X-2026",
    "dea_schedule": "CII"
  }
}

-- CustomFieldDefinition rows:
{ EntityType: "Product", FieldKey: "thread_size",     DataType: "string", IsSearchable: true }
{ EntityType: "Product", FieldKey: "pipe_schedule",   DataType: "select", Options: '["SCH 40","SCH 80","SCH 160"]' }
{ EntityType: "Product", FieldKey: "material",        DataType: "select", Options: '["PVC","Acero","Cobre","Bronce"]' }
{ EntityType: "Product", FieldKey: "warranty_months", DataType: "number" }

-- Product row:
{
  "Name": "Tubo PVC 1/2" x 10ft",
  "CustomFields": {
    "thread_size": "1/2-NPT",
    "pipe_schedule": "SCH 40",
    "material": "PVC",
    "warranty_months": 24
  }
}

-- CustomFieldDefinition rows:
{ EntityType: "Product", FieldKey: "batch_number",      DataType: "string" }
{ EntityType: "Product", FieldKey: "origin_country",    DataType: "string" }
{ EntityType: "Product", FieldKey: "organic_certified", DataType: "boolean" }
{ EntityType: "Product", FieldKey: "allergen_warnings", DataType: "string" }

-- Product row:
{
  "Name": "Cereal Integral 500g",
  "CustomFields": {
    "batch_number": "B-2026-0421-A",
    "origin_country": "PR",
    "organic_certified": true,
    "allergen_warnings": "Gluten, Lácteos"
  }
}

Offline 8. Compatibilidad Cloud ↔ SQLite

El diseño funciona idénticamente en cloud y en cada POS terminal. Las funciones JSON difieren por nombre pero la semántica es la misma.

Sync strategy

1. Pull sync — CustomFieldDefinition rows bajan como cualquier otra config (watermark por UpdatedAtUtc). Product.CustomFields JSON viaja inline con el Product row, sin payload adicional.
2. Schema change en terminal — cuando llega un CustomFieldDefinition(IsSearchable=true) nuevo, posupdate.exe aplica ALTER TABLE ... ADD ... STORED + CREATE INDEX. Additive-only, alineado con §5.4 del design doc.
3. POS queries — barcode scan lee row completo (JSON inline), display extrae específico vía json_extract, búsqueda usa el generated column.

Industria 9. Qué hacen los POS modernos

Migración 10. RMH → Qiiub

Ventajas sobre RMH

• Sin límite duro — 3/15/15 slots → ilimitado
• Validation rica — IsRequired, Options, DataType (vs solo "guardar string")
• Per-merchant — cada merchant define sus campos (vs CustomCaption global en single-tenant RMS)
• Indexed search — computed columns indexados (vs full scan en RMH)
• Module-scoped — un campo puede ligarse a un módulo (solo aparece si el módulo está activo)

Roadmap 11. Future enhancements (diferidos)

Detalle completo con prerequisites en docs/research/research-custom-fields-extensibility.md §8.

Referencias

• docs/research/research-custom-fields-extensibility.md — research doc completo con industry survey
• docs/design/config-extensibility.md §4 — design doc oficial
• docs/design/offline-sync-strategy.md — cómo CustomFields y CustomFieldDefinition viajan al POS
• docs/research/research-sqlite-capacity.md — validación SQLite para POS terminals
• C:\temp\.claude\qiiub\product-module-decisions.md #09 — decision log
• src/QIIUB.Domain/Merchants/CustomFieldDefinition.cs — entity parcial (pendiente completar)
• ADR-00XX-custom-fields-json (pendiente) — formalización