用途:在 UnoPim 中读写商品值、增改属性类型、商品类型、属性族、分组或关联类型时使用。核心事实:目录不是 EAV。每件商品是 products 表中的一行,值为单一 JSON 列 values;属性、族和分组只决定该 JSON 的结构、校验、渲染、过滤与索引。用通用 Laravel 直觉(新增列、新增表、attribute_values 关系、PHP 类型枚举)在每一层都是错的,写之前先读范例。
必要背景:惯用法、安全、规模、本地化与注释见 unopim-standards;命令解析见 unopim-exec;完成前用 unopim-verify;包脚手架、provider 接线与 ACL 见 unopim-plugin-development;目录数据导入导出见 unopim-data-transfer;商品表格列见 unopim-datagrid。
参考文件:values.md(读写 products.values、按渠道/区域/货币作用域、JSON 路径、唯一性、变体读取时继承);attribute-types.md(新增属性类型或判断不需要);product-types-variants.md(product_types 配置、AbstractType、configurable/variant_group 树、变体结构与命令、关联);events.md(目录写入钩子、触发路径、载荷,以及不触发事件的导入与批量编辑路径)。
决策流程:需要新值类型时先看现有类型加属性设置是否够用;text 已支持 number/email/decimal/url/regex 校验,select 覆盖枚举,price 覆盖分货币金额,只有存储结构、编辑器控件、过滤语义或索引映射真正不同才新增类型。新商品类型几乎不需要,simple、configurable 与内部 variant_group 硬编码在变体层级、API、导入器和表格中。读值走属性方法;有 parent_id 的商品读 resolvedValues() 而非 values。写值走 ProductRepository::update() 到类型的 update(),不要直接赋值后 save();变体写入要过 guardVariantLevelWrite()。改属性族内容走 AttributeFamilyRepository,以触发变更事件并清理完整性设置。
真实 API 要点:只有 products.values 一个 JSON 列;桶为 common、locale_specific、channel_specific、channel_locale_specific 及 categories、associations;类型校验用 array_keys(config('attribute_types')),常量已过时;事件的真实拼写与文档化的不同;属性的 type、code、value_per_locale、value_per_channel、is_unique 创建后不可改;变体命令为 unopim:variants:resync 与 unopim:variants:strip-redundant(默认演练)。
限制与注意:原始 JSON SQL 要用 DB::rawQueryGrammar()->jsonExtract(),不要手写 ->>/JSON_EXTRACT;只接受 ^\w+$ 的属性代码;表名前缀用 DB::getTablePrefix();Elasticsearch 可选,新属性类型需数据库过滤器和带标签的 ES 过滤器,否则 applyFilter() 抛错,上线后用 unopim:product:index --fresh 重建;Octane/队列中静态开关要在 finally 中恢复;新增目录路由需映射到 catalog.* ACL,按路由名失败开放;属性与商品类型名称是翻译键,包自有类型需自备命名空间并随带 33 种语言;products 有百万行,变体维护用 chunkById(200),回填同理。验证:运行 unopim-verify,过滤器覆盖 elasticsearch.enabled 两个分支,原始 JSON SQL 覆盖 MySQL 与 PostgreSQL,新属性类型需四作用域读写测试,变体与商品表单改动需跑对应测试和 Playwright 关卡。资料未提供具体收费、价格与平台信息。