酒店房型基库

优先级: P0（核心基础模块）
开发周期: 2-3 周

目标

构建统一的酒店、房型基础数据仓库。将多供应商的异构数据标准化为统一格式，为下游的查价、匹配、搜索提供数据基础。

核心功能

功能	描述
酒店信息管理	酒店基础信息 CRUD：名称、地址、坐标、星级、设施、图片、描述
房型管理	标准房型库：房型名称、床型、面积、入住人数、设施
供应商数据接入	从各供应商 API 拉取/推送酒店数据，解析并入库
数据标准化	异构字段映射为标准字段（如供应商 A 的 "Deluxe Room" → 标准 "豪华房"）
批量操作	批量导入/导出、批量上下架
变更通知	酒店数据变更时通过 MQ 通知下游模块
数据质量检查	重复检测、缺失字段检查、图片有效性检查

数据模型

-- 酒店主表
CREATE TABLE hotels (
    id              BIGSERIAL PRIMARY KEY,
    hotel_code      VARCHAR(32) NOT NULL UNIQUE,     -- 平台统一编码 HPT-XXXXX
    name_en         VARCHAR(255) NOT NULL,            -- 英文名
    name_local      VARCHAR(255),                     -- 当地语言名
    country_code    VARCHAR(3) NOT NULL,              -- ISO 3166-1 alpha-3
    city_code       VARCHAR(8) NOT NULL,              -- 城市编码
    address         TEXT,
    latitude        DECIMAL(10, 7),
    longitude       DECIMAL(10, 7),
    star_rating     SMALLINT CHECK (star_rating BETWEEN 1 AND 5),
    chain_code      VARCHAR(16),                      -- 酒店集团编码
    geo_info        JSONB,                            -- 扩展地理信息
    facilities      JSONB,                            -- {"wifi":true,"pool":true,"parking":false}
    images          JSONB,                            -- 图片URL列表
    check_in_time   TIME DEFAULT '14:00:00',
    check_out_time  TIME DEFAULT '12:00:00',
    contact_info    JSONB,                            -- 电话、邮箱、网站
    status          VARCHAR(20) DEFAULT 'active',     -- active/inactive/pending
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    updated_at      TIMESTAMPTZ DEFAULT NOW(),
    source          VARCHAR(32) DEFAULT 'manual'      -- manual/api/import
);

CREATE INDEX idx_hotels_geo ON hotels USING GIST (
    ll_to_earth(latitude, longitude)
);
CREATE INDEX idx_hotels_city ON hotels (city_code);
CREATE INDEX idx_hotels_status ON hotels (status);
CREATE INDEX idx_hotels_facilities ON hotels USING GIN (facilities);
CREATE INDEX idx_hotels_chain ON hotels (chain_code);

-- 标准房型表
CREATE TABLE room_types (
    id              BIGSERIAL PRIMARY KEY,
    room_code       VARCHAR(32) NOT NULL UNIQUE,     -- 平台统一编码
    hotel_id        BIGINT REFERENCES hotels(id) ON DELETE CASCADE,
    name_en         VARCHAR(128) NOT NULL,
    name_local      VARCHAR(128),
    bed_type        VARCHAR(64),                     -- Double/Twin/King/Sofa
    max_adults      SMALLINT DEFAULT 2,
    max_children    SMALLINT DEFAULT 0,
    room_size_sqm   DECIMAL(6, 1),
    floor           VARCHAR(32),
    bed_count       SMALLINT DEFAULT 1,
    facilities      JSONB,                            -- 房间设施
    description     TEXT,
    images          JSONB,
    status          VARCHAR(20) DEFAULT 'active',
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    updated_at      TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_room_types_hotel ON room_types (hotel_id);

-- 供应商酒店映射源数据表
CREATE TABLE supplier_hotels (
    id              BIGSERIAL PRIMARY KEY,
    supplier_code   VARCHAR(32) NOT NULL,             -- 供应商编码
    supplier_hotel_id VARCHAR(64) NOT NULL,           -- 供应商侧酒店ID
    hotel_id        BIGINT REFERENCES hotels(id),     -- 映射到平台酒店(可为空=待匹配)
    raw_data        JSONB NOT NULL,                   -- 原始数据快照
    name            VARCHAR(255),                     -- 供应商侧名称
    city_code       VARCHAR(8),
    star_rating     SMALLINT,
    latitude        DECIMAL(10, 7),
    longitude       DECIMAL(10, 7),
    last_synced_at  TIMESTAMPTZ,
    match_status    VARCHAR(20) DEFAULT 'pending',    -- pending/matched/unmatched/manual_review
    match_confidence DECIMAL(5, 2),                   -- 匹配置信度 0-100
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    updated_at      TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(supplier_code, supplier_hotel_id)
);

CREATE INDEX idx_supplier_hotels_match ON supplier_hotels (match_status);
CREATE INDEX idx_supplier_hotels_supplier ON supplier_hotels (supplier_code);

-- 供应商房型映射源数据表
CREATE TABLE supplier_room_types (
    id                  BIGSERIAL PRIMARY KEY,
    supplier_code       VARCHAR(32) NOT NULL,
    supplier_room_code  VARCHAR(64) NOT NULL,
    supplier_hotel_id   VARCHAR(64) NOT NULL,
    room_type_id        BIGINT REFERENCES room_types(id),  -- 映射到平台房型
    raw_data            JSONB NOT NULL,
    name                VARCHAR(255),
    match_status        VARCHAR(20) DEFAULT 'pending',
    match_confidence    DECIMAL(5, 2),
    created_at          TIMESTAMPTZ DEFAULT NOW(),
    updated_at          TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(supplier_code, supplier_room_code, supplier_hotel_id)
);

-- 城市字典表
CREATE TABLE cities (
    code            VARCHAR(8) PRIMARY KEY,
    name_en         VARCHAR(128) NOT NULL,
    name_local      VARCHAR(128),
    country_code    VARCHAR(3) NOT NULL,
    latitude        DECIMAL(10, 7),
    longitude       DECIMAL(10, 7),
    timezone        VARCHAR(32),
    status          VARCHAR(20) DEFAULT 'active'
);

-- 设施字典表
CREATE TABLE facility_dict (
    id              SERIAL PRIMARY KEY,
    category        VARCHAR(32) NOT NULL,             -- general/room/dining/sports/business
    code            VARCHAR(32) NOT NULL UNIQUE,      -- wifi/pool/gym/spa/parking
    name_en         VARCHAR(64) NOT NULL,
    name_local      VARCHAR(128),
    icon            VARCHAR(64)
);

接口设计

# 酒店管理 API
GET    /api/v1/hotels                    # 酒店列表（分页+筛选+搜索）
GET    /api/v1/hotels/:id                # 酒店详情
POST   /api/v1/hotels                    # 创建酒店
PUT    /api/v1/hotels/:id                # 更新酒店
DELETE /api/v1/hotels/:id                # 下架酒店
GET    /api/v1/hotels/:id/room-types     # 酒店的房型列表
POST   /api/v1/hotels/batch              # 批量操作

# 房型管理 API
GET    /api/v1/room-types/:id            # 房型详情
POST   /api/v1/room-types                # 创建房型
PUT    /api/v1/room-types/:id            # 更新房型
DELETE /api/v1/room-types/:id            # 删除房型

# 供应商数据同步 API
POST   /api/v1/sync/suppliers/:code/hotels      # 触发供应商酒店数据同步
GET    /api/v1/sync/suppliers/:code/status       # 查看同步状态
POST   /api/v1/sync/suppliers/:code/hotels/diff # 查看数据差异

# 搜索 API（对接 ES）
GET    /api/v1/search/hotels?city=XXX&check_in=YYYY-MM-DD&check_out=YYYY-MM-DD&adults=2

与其他模块的关系

关联模块	关系
匹配管理	提供标准酒店/房型数据作为匹配目标
查价引擎	提供酒店基础信息用于搜索和展示
管理后台	提供酒店/房型管理界面
数据智能	提供酒店元数据用于分析

技术选型建议

PostgreSQL + PostGIS: 地理查询（附近酒店搜索）
Elasticsearch: 全文搜索 + 多条件筛选（后期引入）
Asynq: 定时全量/增量同步供应商数据
JSONB: 灵活存储异构字段，避免频繁 ALTER TABLE