feat: 可扩展档案模式框架 + 内置 3C(电子) 模式 #16

2026-06-21T14:14:18+08:00

lixu commented

2026-06-21 14:14:18 +08:00

背景

下一步要收集 3C（电子）产品，且后期还会加入药品、机械等独立品类。本 PR 不为每个领域写死一张明细表，而是建立一套元数据驱动的「档案模式 (archive_kind)」框架：新增领域 = 一条迁移（种子字段模板 + 品类子树），不再改后端/前端代码。

框架

category.archive_kind：每个品类归属一个档案模式（food / electronics / drug …），子类自动继承父类模式。
kind_field 表：定义各模式的录入字段（key/中文标签/类型/单位/选项/分组/排序/是否计入合格）。
通用规格值写入既有的 product.attributes JSONB（已有 GIN 索引）。食品维持成熟的 food_detail 表作为内置模式。
完整度/合格按模式动态计算：
- food → 沿用 CompletenessFields
- 其它 → 基础字段(name/gtin/brand/category/image) + 该模式 qualified 规格字段

completenessKeys(kind, qkeys):
  if kind == "food": return CompletenessFields
  return genericBaseFields ++ qkeys   // qkeys = kind_field WHERE qualified

首批落地：electronics(3C)

种子 15 个规格字段（型号/3C认证号/颜色/发布年份/保修/尺寸/重量/电源/系统/处理器/内存/存储/屏幕/电池/接口），其中 model_number/ccc_cert/screen_size 计入合格。
种子品类树：电子数码 → 手机/笔记本/平板/智能手表/耳机/相机/电视/家电。

接口与前端

新增 GET /api/kind-fields?kind= 返回字段模板。
后台编辑页：food 显示「配料与营养」；其它模式按 kind_field 动态渲染「规格参数」表单（分组/下拉/数字/多值），保存写入 attributes。
公开详情页/接口：非食品输出带中文标签的「规格参数」表（product.specs）。

兼容性

食品商品行为完全不变（仍走 food_detail、完整度口径不变）。
attributes 为 nil 表示不改动；down 迁移可回滚（卸载 3C 品类、删 kind_field、删列）。

测试

新增 kind_test.go：验证 electronics 不要求食品字段、qualified 规格字段驱动 missing 与质量分上升、ListKindFields 模板正确。
本地 go test ./... / go vet / gofmt 全过；admin + public 前端 tsc && vite build 通过；迁移 up/down 往返验证通过。

## 背景下一步要收集 3C（电子）产品，且后期还会加入药品、机械等独立品类。本 PR 不为每个领域写死一张明细表，而是建立一套**元数据驱动的「档案模式 (archive_kind)」框架**：新增领域 = 一条迁移（种子字段模板 + 品类子树），不再改后端/前端代码。 ## 框架 - `category.archive_kind`：每个品类归属一个档案模式（food / electronics / drug …），子类自动继承父类模式。 - `kind_field` 表：定义各模式的录入字段（key/中文标签/类型/单位/选项/分组/排序/是否计入合格）。 - 通用规格值写入既有的 `product.attributes` JSONB（已有 GIN 索引）。**食品维持成熟的 `food_detail` 表**作为内置模式。 - 完整度/合格按模式动态计算： - food → 沿用 `CompletenessFields` - 其它 → `基础字段(name/gtin/brand/category/image)` + 该模式 `qualified` 规格字段 ``` completenessKeys(kind, qkeys): if kind == "food": return CompletenessFields return genericBaseFields ++ qkeys // qkeys = kind_field WHERE qualified ``` ## 首批落地：electronics(3C) - 种子 15 个规格字段（型号/3C认证号/颜色/发布年份/保修/尺寸/重量/电源/系统/处理器/内存/存储/屏幕/电池/接口），其中 `model_number`/`ccc_cert`/`screen_size` 计入合格。 - 种子品类树：电子数码 → 手机/笔记本/平板/智能手表/耳机/相机/电视/家电。 ## 接口与前端 - 新增 `GET /api/kind-fields?kind=` 返回字段模板。 - 后台编辑页：food 显示「配料与营养」；其它模式按 `kind_field` 动态渲染「规格参数」表单（分组/下拉/数字/多值），保存写入 `attributes`。 - 公开详情页/接口：非食品输出带中文标签的「规格参数」表（`product.specs`）。 ## 兼容性 - 食品商品行为完全不变（仍走 food_detail、完整度口径不变）。 - `attributes` 为 nil 表示不改动；down 迁移可回滚（卸载 3C 品类、删 kind_field、删列）。 ## 测试 - 新增 `kind_test.go`：验证 electronics 不要求食品字段、qualified 规格字段驱动 missing 与质量分上升、`ListKindFields` 模板正确。 - 本地 `go test ./...` / `go vet` / `gofmt` 全过；admin + public 前端 `tsc && vite build` 通过；迁移 up/down 往返验证通过。

lixu added 1 commit 2026-06-21 14:14:18 +08:00

feat: 可扩展档案模式框架 + 内置 3C(电子) 模式

CI / Go (api) (pull_request) Successful in 13s

Details

CI / Python (ingestion) (pull_request) Successful in 9s

Details

CI / Migrations (postgres) (pull_request) Successful in 14s

Details

916bdd9c7c

- 新增 category.archive_kind 与 kind_field 字段模板表（迁移 0010）
- 种子 electronics 字段模板 + 3C 品类树（手机/笔记本/平板等）
- 后端按档案模式动态计算完整度/合格：食品沿用 food_detail，
  其它模式走 product.attributes + kind_field
- 新增 GET /api/kind-fields?kind= 接口
- 后台编辑页按品类模式动态渲染规格参数表单
- 公开详情页/接口输出带标签的规格表

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

lixu merged commit 7f66aad779 into main

2026-06-21 14:15:21 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: lixu/goods#16