21 五月

项目与户型的 XML 供稿

1. 数据源用途

XML 数据源用于传输房地产项目和典型户型的结构化数据。其目的是让接收系统能够自动创建和更新项目卡片，并展示开发商提供的价格、状态、图库、配套、付款计划、EOI 以及营销推广素材。

该数据源以汇总形式传输户型：一条户型记录描述一种典型户型及该类型可售单位数量。它不是具体公寓、办公室或地块的清单。

realty-feed: 整个 XML 数据源的根容器。主 ID：—
offers: 一个项目或综合体。主 ID：complex-id
layouts: 项目内的典型户型。主 ID：id
payment_plans: 一个项目的付款方案。主 ID：id
eoi_item: 一项 EOI 条件。主 ID：—
stock: 开发商的营销活动、新闻或推广信息。主 ID：—

1.1 什么是 XML 数据源

XML 数据源是一个结构化文件，包含房地产项目和典型户型的数据。它包括描述、照片、价格、地址、状态、规格、配套及其他在代理网站或目录中展示房源所需的数据。

简单来说，XML 数据源就是关于房地产的数据流，接收系统会定期下载、读取并用于自动更新房源卡片。

Alnair 提供数据。网站开发、目录开发、CRM 集成以及导入逻辑由客户或客户的技术团队负责。

1.2 代理机构需要什么

要使用 XML 数据源，代理机构需要具备自己的技术基础设施，能够定期下载 XML、解析其结构并在系统中更新数据。

网站或房产目录： 展示数据源中的项目和户型的位置。
技术团队或开发者： 负责 XML 下载、解析和导入的配置。
XML 解析器： 读取 XML 结构并转换为内部数据模型。
导入模块： 创建、更新并停用项目和户型。
任务调度器： 按计划定期执行导入，例如通过 cron 或 scheduler。
错误日志： 监控未知枚举值、空字段和加载错误。

1.3 代理机构如何使用 XML 数据源

典型流程如下：

代理机构系统从个人网页链接下载 XML。
XML 作为原始快照保存，用于诊断和重新处理。
解析器读取 realty-feed、offers、layouts 结构及其嵌套块。
导入模块创建新项目和户型，或更新已有项目和户型。
在新数据源中消失的对象会被标记为非活动。
代理机构网站展示最新的项目卡片、价格、图库和状态。

主要集成能力：

自动更新： 项目和户型无需人工干预即可更新。
房源页面创建： 数据源内容可用于项目和户型卡片。
最新价格与状态： 网站按计划接收 XML 更新。
筛选与搜索： 可按区域、价格、房产类型、房间数和面积进行筛选。
媒体图库： 可在界面中展示项目照片、主题图库和户型图片。

2. XML 总体结构

<realty-feed>
  <generation-date>2026-06-17T12:06:39+04:00</generation-date>
  <offers>...</offers>
  <offers>...</offers>
</realty-feed>

realty-feed: 对象。根数据块。
generation-date: 日期时间。XML 生成日期和时间。用于检查数据新鲜度。
offers: 对象[]。项目或综合体列表。每个 offers 块包含项目数据及其户型。

2.1 数据源访问与下载限制

数据源通过个人网页链接提供给客户。该链接对客户唯一，接收系统通过它自动下载 XML。

个人链接可在 Alnair 账户中由管理员获取。管理员可将该链接提供给客户的技术团队进行导入配置。

访问类型： 个人网页链接。客户专属 XML 数据源 URL。
链接获取位置： Alnair 账户。链接由客户管理员获取。
数据源更新频率： 每 4 小时。Alnair 侧每 4 小时更新一次 XML 数据。
最小下载间隔： 不得超过每小时一次。接收系统每小时最多访问一次数据源。
超出限制： 访问阻止。如果请求过于频繁，数据源访问可能会被临时阻止。

推荐的集成逻辑：通过 cron 或 scheduler 配置定时下载，保存最近接收的 XML，不要在每次网站页面加载时都请求数据源。最佳模式是每小时最多下载一次，同时考虑到新数据大约每 4 小时出现一次。

3. 项目：<offers>

offers 是数据源的主实体。它包含项目描述、开发商、位置、施工和销售状态、价格、媒体、配套、付款计划、EOI、营销活动以及典型户型。

<offers>
  <complex-id>5646</complex-id>
  <type>project</type>
  <logo>https://...</logo>
  <photo>https://...</photo>
  <title>...</title>
  <description>...</description>
  <price_on_request>1</price_on_request>
  <status>...</status>
  <construction_start_at>2025-01-01T00:00:00+04:00</construction_start_at>
  <construction_progress>15</construction_progress>
  <planned_completion_at>2027-12-31T00:00:00+04:00</planned_completion_at>
  <predicted_completion_at>2027-12-31T00:00:00+04:00</predicted_completion_at>
  <amenities>...</amenities>
  <developer>...</developer>
  <city>Dubai</city>
  <address>...</address>
  <latitude>25.000000</latitude>
  <longitude>55.000000</longitude>
  <districts>...</districts>
  <album>...</album>
  <albums>...</albums>
  <constructions_count>1</constructions_count>
  <for_sale_count>10</for_sale_count>
  <price>...</price>
  <br_prices>...</br_prices>
  <updated_at>2026-06-17T10:53:20+04:00</updated_at>
  <is_sold_out>0</is_sold_out>
  <payment_plans>...</payment_plans>
  <sales_status>...</sales_status>
  <stocks>...</stocks>
  <eoi>...</eoi>
  <service_charge>...</service_charge>
  <assignment>...</assignment>
  <is_limited_publication>0</is_limited_publication>
  <layouts>...</layouts>
</offers>

complex-id: 整数。Alnair 中唯一的项目 ID。作为外部项目 ID 用于 upsert。
type: 枚举。顶层实体类型：project 或 compound。保存原始值并按顶层项目导入。
logo: URL。项目标志。用于品牌展示，不作封面。
photo: URL。项目主图 / 封面。用于封面图和主视觉图。
title: 本地化对象。英文/俄文/阿文项目名称。根据界面语言显示。
description: 本地化 HTML。英文/俄文/阿文项目描述。安全渲染；HTML 位于 CDATA 中。
price_on_request: 0/1。隐藏价格标志。若为 1，显示“价格咨询”。
status: 对象。施工状态。不要与 sales_status 混淆。
construction_start_at: 日期时间。开工日期。如有值则显示。
construction_progress: 小数。施工完成百分比。以百分比形式显示。
planned_completion_at: 日期时间。计划竣工日期。作为交房日期使用。
predicted_completion_at: 日期时间。预计完工日期。可作为更新后的完工日期。
amenities: 对象。项目配套与特色。按 key 映射。
developer: 对象。项目开发商。保存名称和 logo。
city / address: 字符串。项目所在城市和地址。用于位置信息。
latitude / longitude: 小数。坐标。用于地图展示。
districts: 对象。项目区域。用于筛选和项目卡片。
album: 对象。项目主图库，无分类。作为通用图库展示。
albums: 对象。主题图库。按标题分组。
for_sale_count: 整数。项目可售单位数量。可显示为库存。
price: 对象。项目整体价格区间。若 price_on_request=1 则隐藏。
br_prices: 对象[]。按卧室数量或类别划分的价格。用于筛选和列表。
updated_at: 日期时间。项目更新时间。用于同步。
is_sold_out: 0/1。售罄标志。与 sales_status 一起使用。
payment_plans: 对象[]。开发商付款方案。作为付款选项展示。
sales_status: 本地化对象。项目销售状态。定义销售阶段。
stocks: 对象。开发商营销活动和推广信息。作为推广模块展示。
eoi: 对象。意向登记。仅在预售（EOI）时展示。
service_charge: 对象。物业费。若有值则显示。
assignment: 小数。转让条件。为空表示未说明。
is_limited_publication: 0/1。发布限制。若为 1，未经许可不公开发布。
layouts: 对象[]。项目典型户型。作为项目子实体导入。

4. 本地化字段

本地化字段结构相同：标签内传递英文、俄文和阿文值。

<title>
  <en>项目名称</en>
  <ru>Название проекта</ru>
  <ar>اسم المشروع</ar>
</title>

en: 英文值。建议作为默认回退。
ru: 俄文值。
ar: 阿文值。

回退规则：

如果界面语言有值，则使用该语言。
如果所需语言为空，则使用 en。
如果 en 为空，则使用 ru。
如果 ru 为空，则使用 ar。
如果所有值都为空，则不显示该字段。

5. 状态

5.1 施工状态：<status>

施工状态显示项目的实体建设阶段，不表示销售可用性。

<status>
  <key>development_stage_progress</key>
  <en>进行中</en>
  <ru>Строится</ru>
  <ar>قيد الإنشاء</ar>
</status>

Scheduled: 项目已规划。
In Progress: 正在施工中。
Ready: 项目已完工。
Stopped: 施工已停止。

5.2 销售状态：<sales_status>

销售状态显示项目的商业阶段：公告、预售、启动、热销或售罄。

Preliminary Info: 项目早期信息。
Announcement: 项目已发布公告。
Presale (EOI): 正在收集 EOI。
Launch: 销售启动。
On Sale: 项目可购买。
Sold Out: 项目已售罄。
Pending: 状态待更新。

6. 开发商与位置

这些块用于展示开发商品牌和项目地理位置。

<developer>
  <title>
    <en>Developer Name</en>
    <ru>Developer Name</ru>
    <ar>Developer Name</ar>
  </title>
  <logo>https://...</logo>
</developer>
<city>Dubai</city>
<address>Project Address, Dubai</address>
<latitude>25.01809076</latitude>
<longitude>55.13354525</longitude>
<districts>
  <district>Jumeirah Village Triangle (JVT)</district>
</districts>

developer.title: 本地化对象。开发商名称。
developer.logo: URL。开发商 logo。
city: 字符串。城市。
address: 字符串。地址。
latitude / longitude: 小数。地图坐标。
districts.district: 字符串[]。项目区域。

7. 价格

7.1 项目价格：<price>

项目级价格显示项目中可售房源的一般价格区间。

min: 小数。最低价格。
max: 小数。最高价格。
min_usd: 小数。美元最低价格。
max_usd: 小数。美元最高价格。
currency: 枚举。主货币，通常为 AED。

如果 price_on_request = 1，即使价格有值，也不会公开显示具体价格。

7.2 按类别价格：<br_prices>

br_prices 按卧室数量或房产类型对价格和面积进行分组。这适用于筛选和简版项目卡片。

<br_prices>
  <key>1</key>
  <count>7</count>
  <min_price>1070564</min_price>
  <max_price>1289674</max_price>
  <min_price_m2>17204</min_price_m2>
  <max_price_m2>18483</max_price_m2>
  <currency>AED</currency>
  <min_area><m2>57.92</m2><ft2>623.45</ft2></min_area>
  <max_area><m2>74.17</m2><ft2>798.36</ft2></max_area>
</br_prices>

studio: 开间。
1-6: 卧室数量。
villa: 别墅。
townhouse: 联排别墅。
n: 不适用 / 非住宅类别 / 其他。

8. 媒体

数据源中的媒体分为多种类型。不要忽略其用途而将它们合并到一个图库中：一张图可能是项目封面，一张是 logo，一张是推广图，还有一张是户型图。

logo: offers.logo。项目 logo。用于项目品牌展示；不要作为封面。
photo: offers.photo。项目主图 / 封面。用于卡片封面图和项目页主视觉图。
album.image: offers.album.image。项目主图库，无分类。用于项目通用图库。
albums.album.images.image: offers.albums.album.images.image。主题图库。按 albums.album.title 分组。
developer.logo: offers.developer.logo。开发商 logo。用于开发商模块。
stocks.stock.logo: offers.stocks.stock.logo。营销活动图片。用于推广模块内部。
layouts.album.image: offers.layouts.album.image。某一典型户型的图库。用于户型层级。
levels_photos.level_photo.image: offers.layouts.levels_photos.level_photo.image。按楼层的户型图片。用作户型平面图。

<photo>https://...</photo>
<album>
  <image>https://...</image>
</album>
<albums>
  <album>
    <title><en>基础设施</en><ru>Инфраструктура</ru><ar>...</ar></title>
    <images>
      <image>https://...</image>
    </images>
  </album>
</albums>

Project presentation: 项目展示图片。
Construction progress: 施工进度照片。
Finishing examples: 装修样板。
Infrastructure: 项目基础设施。
View: 景观与周边环境。

并非每个项目都必须包含所有类别。如果类别标题为空，图片可作为无分类导入，或放入通用图库。

当前结构中没有单独的 history/story XML 标签。新闻、推广消息和项目营销素材通过 stocks 传递。如有 albums 中的 Construction progress 类别，可用于施工历史。

9. 配套设施

amenities 描述项目的配套与特色。集成时最好使用 key，而显示时使用本地化值。

<amenities>
  <amenity>
    <key>project_facilities_gym</key>
    <en>健身房</en>
    <ru>Тренажёрный зал</ru>
    <ar>صالة رياضية</ar>
  </amenity>
</amenities>

amenities: 对象。配套容器。
amenity: 对象。单个配套。
key: 枚举。技术键。
en / ru / ar: 字符串。三种语言的配套名称。

键 projecet_hotel_license 含有拼写错误，但必须映射为 Hotel License。建议支持该别名，不要中断导入。

10. 营销推广：<stocks>

stocks 是开发商的营销活动、新闻和推广信息。它们可能包含特价、折扣、开盘条件、EOI 公告、临时付款优惠及广告素材。该块不是库存，也不定义单位可用性。

<stocks>
  <stock>
    <title>...</title>
    <description>...</description>
    <start_at>2025-06-26T00:00:00+04:00</start_at>
    <end_at/>
    <logo>https://...</logo>
  </stock>
</stocks>

stocks: 对象。营销信息容器。
stock: 对象。一项活动、新闻或推广公告。
title: 本地化对象。推广标题。
description: 本地化 HTML。推广描述。
start_at: 日期时间。开始日期。
end_at: 日期时间。结束日期；可为空。
logo: URL。推广图片。

房源可用性应使用 for_sale_count、layouts.sale_units_count 和 sales_status，而不是 stocks。

11. EOI

EOI 指 Expression of Interest。该块描述处于预售（EOI）状态项目的意向登记或定金条款。

<eoi>
  <is_eoi_return>0</is_eoi_return>
  <eoi_items>
    <eoi_item>
      <price>100000</price>
      <percent/>
      <description>
        <en>2 卧室的 EOI 金额</en>
        <ru>Сумма EOI для 2-комнатных</ru>
        <ar>...</ar>
      </description>
    </eoi_item>
  </eoi_items>
</eoi>

is_eoi_return: 0/1/空。0 = 不可退，1 = 可退，空 = 未说明。
eoi_items: 对象。EOI 条款容器。
eoi_item: 对象。一项 EOI 条件。
price: 小数。固定 EOI 金额。
percent: 小数。如适用，EOI 百分比。
description: 本地化对象。条件说明。

sales_status.en = Presale (EOI) 且 eoi_items 已填写： 显示 EOI。
其他任何 sales_status： 隐藏 EOI。

12. 物业费与转让

<service_charge>
  <value>172.22</value>
  <unit>sq. m</unit>
  <currency>AED</currency>
</service_charge>
<assignment>40.00</assignment>

service_charge.value: 物业费金额。如为空，不显示该模块。
service_charge.unit: 计费单位，通常为 sq. m。可为空。
service_charge.currency: 货币，通常为 AED。可为空。
assignment: 达到该百分比后可转让。为空 = 未说明，不代表限制。

13. 付款计划：<payment_plans>

payment_plans 描述开发商为房源提供的付款方式。一个项目可有多个付款计划。每个计划按阶段拆分付款：预订、施工、交房及交房后。费用和附加费用单独传递，因此总百分比可能超过 100%。例如，104% 可能表示房价的 100% + 4% DLD 费用。

Basic: id、title、currency。计划标识、标题和货币。title 为自由文本，不是枚举。
Booking: on_booking_percent、on_booking_fix、on_booking_payments_count、on_booking_fees。预订阶段的付款和费用。
Construction: on_construction_percent、on_construction_fix、on_construction_payments_count、on_construction_fees。施工期间付款。
Handover: on_handover_percent、on_handover_fix、on_handover_payments_count、on_handover_fees。交房时付款。
Post-handover: post_handover_percent、post_handover_fix、on_post_handover_payments_count、on_post_handover_fees。交房后付款。
ROI: roi_percent、roi_fix、roi_payments_count、roi_fees。用于 ROI 或保收益方案的字段。
Additional fees: additional、additional_percent、additional_fix、additional_fix_m2。附加付款，例如 DLD Fee。
Periods: period_after_handover、period_after_roi。周期性付款频率。
Totals: price_total、fees_included_total。计划总额及包含费用。

14. 户型：<layouts>

layouts 描述项目内的一种典型户型。它是汇总单位类型，不是具体公寓或办公室。

id: 整数。唯一户型 ID。作为外部户型 ID 使用。
title: 本地化对象。户型名称。根据界面语言显示。
project_id: 整数。父项目 ID。与 offers.complex-id 关联。
building_name: 本地化对象。楼栋名称。若为空则不显示。
price_on_request: 0/1。隐藏价格标志。若为 1，则不显示价格。
area_min / area_max: 对象。面积范围。m2 和 ft2。
area_balcony_min / area_balcony_max: 对象。阳台面积范围。可为空。
type: 本地化对象。房产类型。参见单位类型参考。
sale_units_count: 整数。该类型可售单位数量。不是地块列表。
album: 对象。户型图库。用于户型层级展示。
levels_photos: 对象。按楼层图片。用作平面图。
floors_count: 整数。楼层数。1、2、3 等。
rooms_count: 本地化对象。房间数量。参见房间数参考。
price: 对象。户型价格区间。若 price_on_request=1 则隐藏。
is_limited_publication: 0/1。发布限制。若为 1，则对公众隐藏。

15. 枚举值参考

Project type: project, compound.
Sales status: Preliminary Info, Announcement, Presale (EOI), Launch, On Sale, Sold Out, Pending.
Construction status: Scheduled, Ready, Stopped, In Progress.
Unit type: Apartment, Villa, Townhouse, Duplex, Triplex, Penthouse, Retail, Office, Suite.
Rooms count: Studio, 1 BR, 2 BR, 3 BR, 4 BR, 5 BR, 6 BR, 7 BR, 8 BR, NA.
BR price key: studio, 1, 2, 3, 4, 5, 6, villa, townhouse, n.
Gallery category: Project presentation, Construction progress, Finishing examples, Infrastructure, View.
Currency: AED.
Service charge unit: sq. m.
Boolean flags: 0, 1；部分字段允许为空。

如果数据源包含不在参考列表中的值，导入不得失败。该值必须按原始值保存，映射为未知，并记录供审核。

16. 空值

空值表示“未说明”，不是 0。空标签可写作 <field/> 或 <field></field>。

assignment: 未说明转让条件。
service_charge.value: 未说明物业费。
eoi.is_eoi_return: 未说明 EOI 是否可退。
area_balcony_min.m2: 未说明阳台面积。
description.en: 描述缺失。

17. 展示规则

隐藏价格： price_on_request = 1。显示“价格咨询”。
显示价格： price_on_request = 0。显示价格最小值/最大值。
EOI： sales_status.en = Presale (EOI) 且 EOI 已填写。显示 EOI。
EOI 不适用： sales_status.en != Presale (EOI)。隐藏 EOI。
售罄： is_sold_out = 1 或 sales_status.en = Sold Out。显示“已售罄”或从列表中隐藏。
限制发布： is_limited_publication = 1。不要公开发布。
assignment 为空： assignment 为空。不要显示转让模块。
service charge 为空： service_charge.value 为空。不要显示物业费。

18. 导入规则

项目： 按 complex-id 查找；找到则更新，未找到则创建。
户型： 按 layouts.id 查找；通过 project_id 关联项目。
删除： 如果对象从新数据源中消失，应标记为非活动，而不是立即删除。
未知枚举： 保存原始值，映射为未知，并记录日志。
空值： 不要在没有明确字段规则的情况下将其转换为 0。

19. 推荐数据结构

项目字段 → 来源

external_project_id: complex-id.
raw_offer_type: type.
title_*: title.
description_*: description.
developer_name: developer.title.
developer_logo_url: developer.logo.
city/address/coordinates: city, address, latitude, longitude.
districts: districts.district.
construction_status: status.en.
sales_status: sales_status.en.
price_min / price_max: price.
price_on_request: price_on_request.
galleries: photo, album, albums.
payment_plans: payment_plans.
eoi: eoi.
stocks: stocks.
source_updated_at: updated_at.

户型字段 → 来源

external_layout_id: layouts.id.
external_project_id: layouts.project_id.
title_*: layouts.title.
building_name_*: building_name.
unit_type: type.en.
rooms_count: rooms_count.en.
sale_units_count: sale_units_count.
area_min / area_max: area_min, area_max.
balcony_min / balcony_max: area_balcony_min, area_balcony_max.
floors_count: floors_count.
price_min / price_max: price.
layout_gallery: album.
levels_photos: levels_photos.
is_limited_publication: is_limited_publication.