inkreach-official-website/docs/dev/database-table-design.md

-- 1. 原商品表（外部来源商品） CREATE TABLE origin_goods ( origin_good_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, sds_good_id TEXT NOT NULL, -- SDS商品ID，假设为外部系统标识 created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );

COMMENT ON TABLE origin_goods IS '原商品表，记录外部来源商品'; COMMENT ON COLUMN origin_goods.origin_good_id IS '原商品ID（主键）'; COMMENT ON COLUMN origin_goods.sds_good_id IS 'SDS商品ID';

-- 2. 国家表 CREATE TABLE countries ( country_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, country_name TEXT NOT NULL UNIQUE, -- 国家名称唯一 country_icon TEXT, -- 图标URL或路径 created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );

COMMENT ON TABLE countries IS '国家表'; COMMENT ON COLUMN countries.country_id IS '国家ID（主键）'; COMMENT ON COLUMN countries.country_name IS '国家名称'; COMMENT ON COLUMN countries.country_icon IS '国家图标';

-- 3. 品类表（支持层级） CREATE TABLE categories ( category_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, parent_category_id BIGINT REFERENCES categories(category_id) ON DELETE RESTRICT, category_name TEXT NOT NULL, category_icon TEXT, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );

COMMENT ON TABLE categories IS '品类表，支持自关联层级'; COMMENT ON COLUMN categories.category_id IS '品类ID（主键）'; COMMENT ON COLUMN categories.parent_category_id IS '父品类ID，NULL表示顶级品类'; COMMENT ON COLUMN categories.category_name IS '品类名称'; COMMENT ON COLUMN categories.category_icon IS '品类图标';

-- 索引：外键列 CREATE INDEX idx_categories_parent_id ON categories(parent_category_id);

-- 4. 标签表 CREATE TABLE tags ( tag_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, tag_name TEXT NOT NULL UNIQUE, tag_color TEXT, -- 十六进制颜色码，如 '#FF0000' timing TEXT, -- 时机（如促销时段） created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );

COMMENT ON TABLE tags IS '标签表'; COMMENT ON COLUMN tags.tag_id IS '标签ID（主键）'; COMMENT ON COLUMN tags.tag_name IS '标签名'; COMMENT ON COLUMN tags.tag_color IS '标签颜色（前端展示用）'; COMMENT ON COLUMN tags.timing IS '时机（例如节日促销、季节限定）';

-- 5. 位置表（展示位置定义） -- 原设计中的 Indexes 表，为避免与数据库索引关键字混淆，重命名为 positions CREATE TABLE positions ( position_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, index_val INTEGER NOT NULL, -- 位置排序值或权重 country_id BIGINT REFERENCES countries(country_id) ON DELETE CASCADE, category_id BIGINT REFERENCES categories(category_id) ON DELETE CASCADE, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );

COMMENT ON TABLE positions IS '展示位置表，定义商品在特定国家/品类下的展示排序'; COMMENT ON COLUMN positions.position_id IS '位置ID（主键）'; COMMENT ON COLUMN positions.index_val IS '位置值（如排序序号、优先级权重）'; COMMENT ON COLUMN positions.country_id IS '关联的国家ID，NULL表示不限国家'; COMMENT ON COLUMN positions.category_id IS '关联的品类ID，NULL表示不限品类';

-- 索引：外键列 CREATE INDEX idx_positions_country_id ON positions(country_id); CREATE INDEX idx_positions_category_id ON positions(category_id); -- 复合索引用于快速查询某个国家+品类下的位置列表 CREATE INDEX idx_positions_country_category ON positions(country_id, category_id);

-- 6. 商品表（核心表） CREATE TABLE goods ( good_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, origin_good_id BIGINT REFERENCES origin_goods(origin_good_id) ON DELETE RESTRICT, country_id BIGINT NOT NULL REFERENCES countries(country_id) ON DELETE RESTRICT, category_id BIGINT NOT NULL REFERENCES categories(category_id) ON DELETE RESTRICT, tag_id BIGINT REFERENCES tags(tag_id) ON DELETE SET NULL, position_id BIGINT REFERENCES positions(position_id) ON DELETE SET NULL, good_name TEXT NOT NULL, good_priority INTEGER NOT NULL DEFAULT 0 CHECK (good_priority >= 0), -- 优先级，数值越高越靠前 created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );

COMMENT ON TABLE goods IS '商品主表'; COMMENT ON COLUMN goods.good_id IS '商品ID（主键）'; COMMENT ON COLUMN goods.origin_good_id IS '原商品ID（关联外部来源）'; COMMENT ON COLUMN goods.country_id IS '国家ID（必填）'; COMMENT ON COLUMN goods.category_id IS '品类ID（必填）'; COMMENT ON COLUMN goods.tag_id IS '标签ID（可为空）'; COMMENT ON COLUMN goods.position_id IS '展示位置ID（可为空）'; COMMENT ON COLUMN goods.good_name IS '商品名称'; COMMENT ON COLUMN goods.good_priority IS '商品优先级（全局排序，越大越靠前）';

-- 外键索引（必须手动创建） CREATE INDEX idx_goods_origin_good_id ON goods(origin_good_id); CREATE INDEX idx_goods_country_id ON goods(country_id); CREATE INDEX idx_goods_category_id ON goods(category_id); CREATE INDEX idx_goods_tag_id ON goods(tag_id); CREATE INDEX idx_goods_position_id ON goods(position_id);

-- 常用查询索引 CREATE INDEX idx_goods_priority ON goods(good_priority DESC); -- 按优先级排序 CREATE INDEX idx_goods_country_priority ON goods(country_id, good_priority DESC); -- 按国家+优先级 CREATE INDEX idx_goods_category_country ON goods(category_id, country_id); -- 品类+国家过滤

-- 可选：部分索引，仅索引活跃商品（如果有软删除或状态字段） -- 当前设计无状态字段，暂不添加

-- 7. （可选）商品与标签的多对多关联表 -- 原设计中 goods 表仅有单一 tag_id，限制了多标签场景。 -- 若业务需要多标签，建议增加关联表，并移除 goods.tag_id 字段。 -- 以下为扩展设计（可根据实际需求决定是否启用）：

/* CREATE TABLE goods_tags ( goods_id BIGINT NOT NULL REFERENCES goods(good_id) ON DELETE CASCADE, tag_id BIGINT NOT NULL REFERENCES tags(tag_id) ON DELETE CASCADE, PRIMARY KEY (goods_id, tag_id) ); CREATE INDEX idx_goods_tags_tag_id ON goods_tags(tag_id); */

-- 注意：若使用 goods_tags 关联表，则应删除 goods 表中的 tag_id 列。 -- 保留原单标签设计还是采用多标签，请根据业务需求选择。

-- 8. 自动更新 updated_at 的触发器函数（可选） CREATE OR REPLACE FUNCTION update_updated_at_column() RETURNS TRIGGER AS $$ BEGIN NEW.updated_at = now(); RETURN NEW; END; $$ LANGUAGE plpgsql;

-- 为每个表应用自动更新 updated_at 的触发器 CREATE TRIGGER trigger_origin_goods_updated_at BEFORE UPDATE ON origin_goods FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER trigger_countries_updated_at BEFORE UPDATE ON countries FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER trigger_categories_updated_at BEFORE UPDATE ON categories FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER trigger_tags_updated_at BEFORE UPDATE ON tags FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER trigger_positions_updated_at BEFORE UPDATE ON positions FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

CREATE TRIGGER trigger_goods_updated_at BEFORE UPDATE ON goods FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();