文旅社区 · 开发说明

先把要做什么、怎么调、出错怎么办说清楚。

这份文档给产品、前端和后端一起看：先按角色和用户旅程理解业务，再逐模块看起点、主流程、完成标志和异常，最后才进入接口、字段和上线检查。还没定下来的地方单独列出来，不混在已确定的方案里。

这页包含M00 — M15业务流程、接口、字段、状态、权限和上线检查

阅读方法先看流程，再看接口不确定的内容放在“待确认事项”，不会假装已经定了。

本期暂停开发：特产商城、附近商家、财付兔接入、门票。页面中相关模块、流程、接口和字段仅作为历史方案留档，本期不开发、不联调、不建表、不做占位能力，也不进入排期、搜索推荐和上线验收。

列表、推荐与搜索边界：GET /app/community/search 是独立搜索接口；取消独立推荐/热门内容列表接口。推荐算法通过可插拔内部 Provider 嵌入 GET /app/community/feed 的列表查询，和列表共用分页、过滤与卡片协议；算法关闭或失败时同一 Feed 返回规则列表。

16业务模块（M00—M15）

—候选 HTTP 接口

—字段说明条数

1可直接打开的 HTML 页面

01 / 先看规则

先把容易出错的地方说清楚

下面四条是所有模块都要遵守的基本规则。它们决定接口怎么写、数据怎么留，以及出问题后能不能查回来。

接口不暴露数据库 ID

接口使用 noteKey、specialtyKey、ticketKey、nearbyMerchantKey、groupKey 这类业务 Key。数据库 ID、证件原文、密钥和永久链接都不能返回。

重复请求不能重复扣钱

创建、支付回调、状态变更和补偿都要带幂等键。网络重试时，接口返回第一次的结果，不能重复下单、扣库存或记账。

状态不能随便改

订单、审核、入驻、账务和发布都要经过业务服务和权限检查。Controller、脚本和人工 SQL 不能直接把状态改掉。

订单要留当时的资料

下单时保存商品、价格、商家、成员、房源和结算信息。以后主数据变了，历史订单仍然能按当时的内容解释。

02 / 建议顺序

建议按这个顺序开发

先把公共接口定下来，再做内容和商品，最后接交易和上线治理。民宿进件、账务和商家结算要在交易联调前定稿。

先定公共接口

先确定 OSS、业务 Key、统一响应、错误码、幂等键和版本字段。

M00 / 公共接口

再做内容

首页、地点、Feed、详情、发文、审核、商品引用和挂载先跑通。

M01—M05

接上交易

互动、搜索、推荐、房叮咚特产商城和订单一起联调；门票只留位置，不进首期交易。

M06—M12

最后做上线准备

通知、IM、监控、数据修复、压测、灰度和回滚逐项验证。

M13—M15

03 / 业务全景

先看清用户为什么来、业务怎么闭环

文旅社区不是一组互不相关的增删改查。运营先配置入口，作者生产内容，系统把内容分发给用户；用户互动产生反馈，也可能从文章中的特产或民宿卡片进入交易。搜索、推荐、奖励和通知都围绕这条主链路工作。

角色 → 场景 → 结果

内容供给：运营和作者把“可看的东西”准备好

M00 处理媒体，M01 配首页入口、频道和地点，M03 负责草稿、卡片挂载、审核与发布。完成标志不是“保存成功”，而是生成一个审核通过、资源可用、可以公开分发的内容版本。

内容发现：用户找到感兴趣的笔记和文旅资源

M02 提供唯一 Feed 和详情，M07 提供作者/商品/地点反向笔记流，M09 提供搜索，M10 给 M02 提供推荐候选。无论从哪里进入，最终都要经过公开状态、城市、权限和内容版本校验。

互动与反馈：用户行为反过来改善内容分发

M06 保存点赞、收藏、关注、评论和举报，M08 接收曝光、点击、停留与交易事件。互动结果进入通知，行为事件用于搜索热度、推荐效果和奖励判断，但不能由客户端直接修改权威计数。

交易转化：从内容卡片进入真实履约

M04 管房叮咚特产商品、SKU、价格、库存和商家经营；M11 做核价、库存预占、订单、支付衔接、售后，以及民宿入驻和自助入住。门票 M05 首期仅占位，不允许误入下单链路。

运营准备入口

配置首页、城市频道、轮播和快捷按钮，发布后用户才能看到稳定入口。

M01

作者生产内容

上传媒体、保存草稿、选择地点并插入特产/民宿等卡片，送审通过后生成公开版本。

M00 / M03

系统分发内容

M02 根据城市和频道读取内容；推荐模式向 M10 要候选，失败仍在同一 Feed 回落规则流。

M02 / M10

用户消费和互动

用户看详情、点赞、收藏、评论或举报；个人状态和公共计数分开处理。

M06 / M07

产生搜索、推荐和奖励反馈

曝光、点击、停留、发布和成交事件幂等入库，再驱动索引、热度、推荐评估和奖励流水。

M08 / M09 / M12

进入交易或持续触达

可交易卡片进入核价、下单、支付、履约和售后；非交易结果通过通知或 IM 继续触达用户。

M04 / M11 / M13 / M14

判断业务是否完成：接口返回成功不一定代表业务完成。草稿保存成功不等于发布，推荐候选返回不等于内容可展示，订单创建不等于支付成功，开锁请求受理不等于门锁已打开，回调收件成功也不等于业务状态已经推进。每个模块卡片会单独说明自己的完成标志和失败分支。

业务设计

先看通用首页装修和动态子页面，再看身份、房叮咚特产商城、门票预留和民宿入驻。

M01 / 页面装修协议

首页和子页面统一使用“页面 → 组件 → 元素 → 动作”

接口返回组件类型和结构化字段，前端按 componentCode 选择渲染器。按钮可以跳到另一个装修页面，子页面继续配置轮播图、按钮等组件；页面、资源和跳转字段关系化落库，不把整页塞进 config_json。

通用动态页面

定义页面

HOME 和 CUSTOM 共用 pageKey/pageType/routePath，不同城市按区域配置并支持默认回落。

PAGE

组合组件

页面按顺序挂载注册组件，componentCode 决定前端渲染器，layoutCode 只选择白名单布局。

COMPONENT

配置元素

轮播项和按钮分别保存图片、图标、背景、标题、排序等明确字段，媒体只引用 assetKey。

ITEM

结构化跳转

PAGE 动作保存 routePath + targetPageKey；业务详情保存目标类型和业务 Key，外链校验域名白名单。

ACTION

原子发布

首页与被引用子页面进入同一 releaseKey，发布前校验资源、组件协议、循环引用和客户端版本。

RELEASE

componentCode	用途	组件级字段	元素级字段
`HEADER`	顶部区域	标题、副标题、背景图/色、文字色	无
`CATEGORY_TABS`	图文/视频分类	布局、选中样式	channelKey、名称、图标、排序、是否显示
`BANNER_CAROUSEL`	轮播宣传位	自动播放间隔、圆角、宽高比、背景	图片、标题、副标题、结构化动作
`ACTION_GRID`	快捷按钮	每行列数、间距、整体背景	按钮名称、图标、背景图/色、结构化动作

actionType	结构化目标	行为
`PAGE`	`routePath + targetPageKey`	打开另一个装修页面，例如首页按钮进入“周末游”，目标页继续返回轮播组件。
`ROUTE`	`routePath`	打开 App 已注册原生页面。
`CONTENT`	`targetType + targetKey + routePath`	打开频道、笔记、商品、酒店等业务详情。
`URL`	`externalUrl`	打开经过域名白名单校验的外部页面。
`NONE`	无	只展示，不可点击。

接口返回有类型结构

GET /app/community/home 和 GET /app/community/pages/{pageKey} 返回相同页面协议：页面信息、schemaVersion/configVersion 和有序 components。

关系型结构落库

页面、版本、组件、元素、动作、动作参数和发布批次分别建表；图片、图标、背景、路径和目标 Key 都是明确字段。

禁止任意 JSON

extJson 只允许保存不参与查询、权限和路由的低频展示属性，并按 componentCode + schemaVersion 校验；禁止任意 CSS/JavaScript。

按钮进入子页面：按钮动作使用统一动态路由并携带 targetPageKey。前端请求对应页面 Key 后仍按同一组件协议渲染，因此子页面配置轮播图不需要新增写死页面或专用接口。

角色和权限

商户只登录财付兔，房叮咚验证身份和权限

财付兔登录身份、房叮咚内部商家主体和具体资源是三回事。每次请求都要查清楚：请求是否来自财付兔、当前是谁、属于哪个商家，以及能操作哪家店、哪个商品或哪笔订单。

财付兔登录

商户和员工只在财付兔登录。MALL_MERCHANT、MALL_MERCHANT_EMPLOYEE 是房叮咚自动映射的内部授权主体，不是要求商户重新注册的账号。

业务主体

商场商家、民宿总账号、民宿集体、民宿成员和账务主体都是独立对象，不把它们塞进一个 role 字段。

操作范围

每次都要从 tenant 查到 merchantKey、storeKey、specialtyKey / skuKey。只判断“他是商家”还不够。

主体/角色	可以做什么	明确不能做什么	授权依据
普通用户 / 内容作者	浏览、互动、创建本人草稿、提交审核、下单和查看本人奖励	不能调用商家经营接口，不能改他人内容、商品、库存、账务或审核结果	房叮咚登录用户 + 资源本人关系；不承担财付兔商户登录
财付兔商户负责人（内部映射为 MALL_MERCHANT）	从财付兔页面或免登经营台维护房叮咚商店、特产、SKU、价格、库存、订单、售后和评价回复	不需要注册或登录房叮咚；不能审核自己的商品、查看其他商家、直接改销量/评分/订单状态，也不能使用酒店商家权限	财付兔应用签名 + 一次性授权码换取的 Token/会话 + merchantKey/storeKey/scope
财付兔商户员工（内部映射为 MALL_MERCHANT_EMPLOYEE）	按财付兔员工授权维护指定商店的商品、价格、库存、发货、售后或评价回复	不创建房叮咚员工登录账号；不能越过员工 scope，不能修改结算主体、平台审核结果或其他员工权限	财付兔 employeeId 可信声明 + 内部 principalKey + scopeType/scopeKey + tokenVersion
民宿总账号	完成一次主进件，管理旗下全部集体、成员、房源、订单和统一结算	不能绕过状态机、风控和审计直接改状态或收款主体	masterAccountKey + primaryApplication + 总账号权限
民宿成员	扫码关联后维护自己的房源、商品和订单，查看自己的经营台账	不能因为加入同一总账号查看其他成员数据，也没有独立收款权	memberKey + listingKey + masterAccountKey
平台运营 / 财务 / 审核	按最小权限审核、对账、修复和查看授权范围内数据	不能默认全量；高危修复不能绕过预览、确认和审计	Sa-Token 权限 + tenant/data scope

模块总览

M00—M15 各模块要做什么

先用这张总表找模块，再进入商家、民宿、接口或字段章节看细节。每张卡片都能下载包含本模块全部业务章节、接口和字段的 Markdown，方便交给 AI 单独阅读。

可搜索可下载 MD16 / 16

没有匹配的模块，请换一个关键词。

M04 / 本期不开发

特产商城与财付兔内容仅作历史方案留档

本期不开发、不联调、不建表，也不开放特产商城、财付兔授权、OpenAPI、回调、身份映射或免登经营台。以下内容不属于当前交付和验收。

主数据在房叮咚

只登录财付兔

商户在财付兔完成登录和进件；房叮咚不提供重复注册、账号密码登录或人工账号绑定。

CAIFUTU LOGIN

双层鉴权

财付兔应用签名证明调用方，一次性 authorizationCode 证明当前商户；房叮咚服务端回查后自动映射 merchantKey。

APP + MERCHANT AUTH

获得短时授权

财付兔后端取得 merchantAccessToken；若打开房叮咚经营台，则一次性码换短时会话，不在 URL 传长期 Token。

TOKEN · SSO SESSION

经营同一份数据

商户在财付兔页面或免登经营台建店、维护商品并送审，接口内部仍走房叮咚权限、领域服务和状态机。

OPEN API · DOMAIN SERVICE

下单和履约

下单实时核价、验库存和运费，订单工厂建单；支付、发货、退款、退货复用现有能力。

ORDER FACTORY

评价和统计

订单事件更新销量和付款人数；已购用户评价，公开评价参与评分，商家只能回复不能改用户评分。

REVIEW · SALES

房叮咚是商品主系统

商品新增、编辑、SKU、价格、库存、上下架、评价和销量全部在房叮咚落库并留版本，财付兔不保存权威副本。

不建第二套登录账号

财付兔身份只映射为房叮咚内部权限主体。OpenAPI 与免登经营台共享权限、校验、库存流水、幂等、审计和订单工厂。

卡片数字不能随便写

售价用分；销量来自已支付件数，付款人数按用户去重，评分只算公开的已购评价。展示“500+”的分档规则单独配置。

财付兔 ↔ 房叮咚

应用鉴权和商户鉴权必须同时通过

无需房叮咚注册登录

阶段	请求凭证	房叮咚处理	安全边界
应用鉴权	appKey、signature、timestamp、nonce、requestId，可叠加 IP 白名单或 mTLS	校验应用状态、签名串、时间窗、防重放、版本、限流和密钥版本	只证明“请求来自财付兔”，不能据此操作任意商户。
商户授权交换	财付兔一次性 authorizationCode + requestedScopes + returnRouteCode	服务端回查/验签取得 caifutuMerchantId、employeeId、商户状态和 scope，自动创建或更新内部 merchantKey/principalKey 映射	authorizationCode 短时、单次、绑定应用和场景；手机号、商户名、merchantKey 均不能代替授权码。
经营调用	应用签名 + Bearer merchantAccessToken + 请求级 requestId	交叉校验 appKey、merchantKey、storeKeys、scopes、expireAt 和 tokenVersion，再进入领域服务	Token 只在服务端传递，不放 URL、日志或普通用户浏览器存储。
免登经营台	财付兔登录态下签发的一次性码	POST 换取房叮咚短时会话，映射内部权限主体；后续商家端接口按会话数据范围执行	不创建房叮咚用户名/密码；退出、冻结、解绑、员工离职和撤权立即失效旧会话。

页面/对象	必须返回的关键字段	口径	开发注意
商品卡片	specialtyKey、title、cover、storeName、salePrice、marketPrice、salesQuantity、paidBuyerCount、recentPaidBuyerCount、ratingScore、reviewCount	价格单位分；销量是付款件数；付款人数是去重用户数；评分只算公开已购评价	卡片可以显示“团购”“本周 800+ 人已买”等文案，但原始数值和统计时间必须同时可追溯。
商品详情	mediaList、detailBlocks、skuSpecTree、skuList、priceSummary、stockSummary、freightSummary、afterSaleRules、storeSummary、reviewSummary	详情是当前展示值；下单确认仍实时核价、验库存和配送范围	SKU 使用稳定 specialtySkuKey；已产生订单的 SKU 只能停用，不能物理删除。
库存	totalStock、availableStock、reservedStock、soldStock、afterSaleLockedStock、stockVersion	总量 = 可售 + 预占 + 已售/售后占用的可解释组合，按实际库存模型冻结公式	人工调整带原因、业务单号、版本和幂等键，并写库存流水；禁止直接更新可售数。
商品评价	reviewKey、orderItemKey、rating、content、mediaList、anonymous、reviewStatus、contentReviewStatus、merchantReply、createTime	一条已完成订单明细一条主评价；追评规则另配；待审和隐藏评价不进汇总	独立于文章评论，提供评价开关和审核开关；审核关闭时不调用内容安全。
财付兔 OpenAPI	appKey、signature、timestamp、nonce、requestId、merchantAccessToken、merchantKey/storeKey、scope、apiVersion	应用、商户 Token、商店资源和接口范围逐层授权，写接口还要业务幂等和乐观锁	不能只传 merchantKey 冒充商户，不能直连库、越权切店、传浮点金额或绕过审核和状态机。

M05 / 本期不开发

门票与附近商家内容仅作历史方案留档

本期不开发、不联调，也不预留门票 Key、供应商、交易入口，以及附近商家 Provider、同步、页面、挂载、索引或推荐召回。以下内容不属于当前交付和验收。

门票不进入首期联调

保留门票模型

先冻结景区 POI、票种、日期/场次、实名和退改等平台字段名，不写供应商字段。

CONTRACT_RESERVED

门票不可交易

候选列表/详情接口明确标成预留，返回 tradeSupported=false，不创建 Provider、采购单或回调。

PROVIDER_NOT_SELECTED

附近商家单独接

保存 nearbyMerchantKey、来源地点 ID、POI、分类、位置、营业信息和受控跳转。

NEARBY_MERCHANT

来源确定后再冻结

供应商选型后重新评审鉴权、同步、限流、回调、SLA 和数据授权，不能沿用占位字段直接开发。

RESEARCH → REVIEW

门票只做预留

保留 TICKET 卡片和 ticketKey，方便以后扩展；首期 M11 拒绝门票下单，页面不能显示虚假价格、库存或“可预订”。

附近商家是地点资源

附近商家有独立 nearbyMerchantKey、第三方地点 ID、坐标、分类、营业信息和详情路由，不等同于商城商店。

不能混进特产

门票和附近商家不能写入 specialty、SKU 或特产库存流水，也不能因为接了数据就获得商场商家身份或结算主体。

当前门票结论：供应商已取消，首期只预留业务位置。供应商、商务模式、资源范围、实时价库、出票核销、退改、采购资金和客服责任全部列入待调研，确认前不建设真实交易链路。

M06 / M09 / M15 · 基础设施约束

评论先审核，搜索接阿里云 Serverless ES

评论审核默认开启；关闭租户级开关后，新发、修改、恢复的评论和回复不调用内容安全服务，基础校验通过后直接发布。搜索使用阿里云 Elasticsearch Serverless 版，MySQL 仍然是权威库。

方案已定 · 细节待调研

评论公开条件和开关

默认只有 contentReviewStatus=PASS 且 status=PUBLISHED 才公开。关闭租户级 commentReviewEnabled 后，新发、修改、恢复的评论和回复为 PUBLISHED + SKIPPED，不创建审核任务。

阿里云内容安全

审核开启时业务层才调用 ContentSafetyProvider，首期预留阿里云内容安全 Adapter。超时、限流、异常或结果不确定时保持待审或转人工，不能默认放行。

ES 不是业务主库

阿里云 Elasticsearch Serverless 只存可重建的查询索引。客户端不接触 ES 地址和密钥；搜索故障不能回源 MySQL 做全表 LIKE。

读取审核开关

按租户读取 commentReviewEnabled。开启时进入 PENDING；关闭时通过基础校验后直接 PUBLISHED + SKIPPED。

ENABLED / DISABLED

内容审核

调用 Provider Adapter 做文本审核；通过进入发布，风险内容进入人工复核、拒绝或封禁。

REVIEWING → PASS / MANUAL_REVIEW / REJECT

索引同步

内容、商品、POI 和词条以 MySQL 为准，通过 RabbitMQ 增量同步到阿里云 ES Serverless。

MYSQL → MQ → ALIYUN ES

版本切换和降级

重建完成、对账通过后切 alias；ES 异常返回降级标识，不做全表回源。

INDEX_VERSION · ALIAS · DEGRADED

事项	开发约束	故障时怎么做	还要调研
评论/回复文本	审核开启时新发、修改、恢复都重新审核；关闭时写入 PUBLISHED + SKIPPED；公开列表只读已发布且通过或跳过审核的内容。	开启时内容安全超时、限流或返回不确定时保持待审；关闭时不调用 Provider，后台仍可显式封禁或删除。	阿里云内容安全具体产品、API、地域、标签、保存期限、配额和人工复核流程。
评论审核开关	租户级 `commentReviewEnabled` 默认 true；关闭后新发、修改、恢复的评论/回复写入 PUBLISHED + SKIPPED，不创建审核任务、不调用内容安全。	按请求时的配置版本执行；旧的 PENDING/REVIEWING 不因关闭自动放行，重新开启也不自动补审。	是否需要频道/场景级开关、配置生效延迟、历史评论补审范围和开关操作权限。
审核记录	记录 provider、requestId、风险等级、命中标签、规则版本、处理人和审计时间；原始报文受控保存。	重复结果按 requestId 幂等；供应商回放不能重复发布或重复通知。	合规留存期限、谁可以查看原始报文、申诉和解封时限。
搜索索引	MySQL 权威；阿里云 ES Serverless 用版本索引和 alias，不能让业务方直接写物理索引。	增量失败进重试/死信；全量重建和差异修复由 SnailJob 执行。	地域、网络和鉴权、分词/分析器、容量、费用、SLA、配额、生命周期和灾备。
搜索请求	接口返回 `searchVersion` 和 `degraded`/`fallbackReason`，不返回 ES 连接信息。	ES 不可用时有限降级或明确失败，禁止 MySQL 全表 `LIKE`。	降级时的产品提示、可接受的结果范围和告警阈值。

服务端 Adapter 契约

厂商参数不能散落在业务代码里

内部接口

Adapter	请求参数	返回参数	实现要求
`ContentSafetyProvider.check`	`commentKey`：评论 Key；`contentVersion`：正文版本；`content`：待审核文本；`contentType`：COMMENT/REPLY；`tenantId`：租户；`userKey`：作者；`idempotencyKey`：本次检测幂等键。	`decision`：PASS/REJECT/MANUAL_REVIEW/UNKNOWN；`riskLevel`：平台风险等级；`labels[]`：平台标签；`providerRequestId`：厂商请求号；`providerVersion`：规则版本；`retryable`：是否可重试；`rawPayloadRef`：受控原文引用。	仅当租户 `commentReviewEnabled=true` 时调用；关闭时不创建审核任务、不调用厂商、不写审核结果。开启后 UNKNOWN、超时、限流和异常不能自动发布；同一评论版本重复检测必须幂等。
`SearchIndexProvider`	`logicalIndex`：逻辑索引白名单；`indexVersion`：构建版本；`operation`：UPSERT/DELETE；`documentKey`：业务 Key；`document`：已脱敏索引文档；`eventId`：变更事件 ID；`sourceVersion`：MySQL 数据版本。	`accepted`：是否接收；`providerRequestId`：服务请求号；`retryable`：是否可重试；`providerErrorCode`：稳定错误码；`aliasStatus`：当前别名状态。	只允许访问阿里云 Elasticsearch Serverless 的逻辑索引；物理索引、Endpoint、账号和密钥由服务端配置管理，重建校验通过后才能切 alias。

M11 / 硬约束

订单和支付必须走现有系统

文旅社区负责房叮咚特产核价、库存、逐明细归因和成交快照。真实订单、订单状态、支付、退款、分账和支付回调，全部接入项目现有订单工厂和支付链路；门票当前不进入交易。

R18 已确认约束

下单确认

立即购买传商品明细，购物车结算传勾选项。服务端逐项重读商品、SKU、价格、库存、规则、履约要求和文章归因，首期允许同店多个 SKU，返回短时 quoteToken；这一步不创建订单。

CONFIRM · QUOTE

消费报价并建单

创建订单时再次校验报价和状态，再按订单类型调用 OrderTypeHandlerFactory.getHandler(type)，由现有 Handler 创建真实平台订单。

ORDER_HANDLER

使用现有状态机

取消、支付成功、履约、入住和补偿都走正式 Handler 或 AppOrderStateMachineService.fireEvent，不直接改状态字段。

STATE_MACHINE

调用现有支付

客户端拿平台订单号调用 POST /app/pay/order；支付服务按订单、渠道和场景选择现有策略并保存支付流水。

PAY_SERVICE

统一回调和退款

支付回调进入现有 /app/pay/notify/*，退款、分账、结算和对账继续使用现有服务；社区保存特产订单明细、库存流水、归因和展示快照。

CALLBACK · REFUND

社区可以做

房叮咚商品/库存、成员/房源前置校验，文章 POI 归因，订单明细快照，状态展示和补偿任务编排；民宿进件、智能锁等确有需要的外部能力通过 Adapter 接入。

社区不能做

不能新建 CommunityOrderService、社区订单状态机、社区支付单、社区支付回调或社区退款实现，也不能直接写订单和支付流水。

当前代码要补的地方

现有 AppOrderType 目前是 HOTEL、BOX。新增特产订单类型时，要一并核对 Handler 是否支持同店多明细，以及支付处理器、网关策略、状态机、库存事件、退款/分账和对账覆盖。门票不新增订单类型。

当前订单粒度：完整商城必须有购物车，首期先支持“同一家店、多个 SKU、一个真实 orderCode、多条订单明细”。order/confirm 支持立即购买和购物车勾选两种方式。跨店时如何拆成父子单或订单组、能否合并支付、运费和退款怎么分摊列为 R21；未确认前服务端明确拒绝跨店一次提交，不能让前端做出能合并支付的假象。

环节	现有代码入口	社区接入要求	禁止做法
订单类型路由	`OrderTypeHandlerFactory` `OrderTypeHandlerConfig`	按已注册的特产或酒店/民宿订单类型获取 Handler；特产 Handler 要支持同店多条订单明细，并遵循 create/detail/cancel/list/page 契约。	在社区 Controller 里按目标类型写 if/else 并直接插入订单表，或为门票预留对象创建订单。
订单状态	`AppOrderStateMachineService.fireEvent(...)`	订单取消、支付成功、履约、入住和补偿都走现有事件/Handler，保存版本和审计。	Controller、回调、任务或人工 SQL 直接改订单状态。
发起支付	`AppOrderPayServiceImpl.orderPay` `PayService.pay`	用真实平台 orderCode 准备支付参数，支付流水进入现有 `app_order_pay`。	社区生成 paymentKey 作为第二套支付单，或自行保存支付结果。
支付策略	`PayStrategyFactory.getStrategy(channel, provider, scene)`	沿用现有 channel/provider/scene 路由和支付网关；provider 由服务端配置/处理器决定。	社区私接支付厂商、客户端指定未授权 provider、绕过现有网关。
支付回调与退款	`AppPayController` `PayService.callBack/refund`	回调验签、幂等、补偿；退款回到原支付流水，来源取消结果只作为适配器处理结果。	回调直接改社区状态，或按社区快照重新发起一笔退款。

现有接口复用

社区下单后怎么支付

只使用 GET / POST

接口	请求参数	返回/回调	对接说明
POST `/app/pay/order`	`orderCode` 必填：真实平台订单号；`channel` 必填：支付渠道；`scene` 必填：支付场景；`code`、`goodsTag`、`roomIds[]`、`isCashier` 按场景选填。请求没有社区自定义的 provider 字段。	`PayRespDTO`：`orderCode`、`payType`、`payData`、`payProvider`、`actualChannel`、`actualScene`、`payRoute`、`orderType`、`orderSource` 等；敏感商户信息不应下发。	社区 `POST /app/community/trade/order` 返回的 `paymentRoute` 只是提示下一步，不是社区支付单。前端必须拿真实 `orderCode` 调这个现有接口。
GET `/app/pay/hf/wechat/app/params`	`orderCode` 必填：需要查询支付参数的真实平台订单号。	`HfPayParamsDTO`，由现有支付服务按订单状态和缓存有效期返回。	订单已取消或支付参数过期时按现有错误返回，不能在社区重新拼参数。
POST `/app/pay/notify/{orderType}/{channel}/{provider}/{scene}/{source}`	Path：`orderType`、`channel`、`provider`、`scene`、`source`；Body：支付厂商回调原文。需按现有入口验签和解析。	`R<String>`；现有服务通过策略解析订单号、确认支付流水并做业务补偿。	社区供应商回调不能代替支付回调；支付成功后的订单推进仍由现有订单/支付链路完成。
POST 现有退款回调	`/app/pay/lklRefundNotify`、`/app/pay/notify/lkl/refund`、`/app/pay/notify/hf/refund` 等现有入口接收厂商回调。	更新原支付流水退款状态，并按现有规则通知订单和账务。	社区售后接口只能发起现有订单/支付退款流程，不能自己落一条退款流水。

M11 / 重点流程

民宿入驻、多方账号、统一结算与无前台自助入住

总账号只做一次主进件，旗下民宿扫码关联并统一结算；民宿主人、运营方和投资方按身份、操作权限和房源范围分权，入住后由订单信息卡受控展示定位地址、房号、临时密码和开锁按钮。

总账号主进件

总账号创建旗下集体/民宿，完成一次主进件，结算卡绑定这个主进件。

MASTER_ACTIVE

平台审核激活

供应商回调只更新进件结果；总账号和集体审核通过后才允许生成专属码。

ACTIVE 才能发码

生成一次性专属码

一个码只能成功关联一次；明文只展示一次，支持撤销、轮换和异常告警。

ONE_TIME · EXHAUSTED

民宿扫码关联

民宿登录、实名、风控校验后直接跳过重复进件；风险命中则人工审核或封禁。

ASSOCIATED / RISK_REVIEW

多方账号分权

为成员标记主人、运营方或投资方身份，再配置操作权限、集体/房源范围、字段级别和有效期；关联成功不自动获得经营数据。

OWNER · OPERATOR · INVESTOR

住客自助入住

订单满足入住条件后展示精确定位、房号和密码入口；开锁请求经过二次校验并以锁厂商真实结果为准。

STAY_ACCESS_READY

可以共享

共享总账号主进件、集体名称、经营区域和统一结算主体。成员不用重复走支付机构进件。

必须分开

成员身份、房源、商品、订单责任、经营台账、冻结和退出状态单独保存；总账号统一收款，但不能抹掉成员维度。

不能跳过

专属码可以跳过重复进件，但不能跳过登录、实名、风控、一次性消费和封禁校验；不能把扫码人变成总账号管理员。

敏感信息不能泄露

普通订单详情不返回明文开锁密码；精确地址、房号、查看密码和远程开锁都要按订单本人、入住时间窗、设备风险和凭证版本重新校验并审计。

多方账号权限

角色只是身份，最终权限由可配置数据边界决定

默认最小权限

账号身份	默认范围	默认能力	默认禁止
民宿主人	本人被确认拥有的集体/房源	维护房源、看经营与结算摘要、委托运营方	其他业主房源、平台审核、修改主进件/收款主体、越级授权
民宿运营方	被委托房源的单笔订单、收入、退款、费用和结算进度	查看订单与财务明细、筛选统计和脱敏导出	默认只读；不接单/取消/退款，不改房态/价格，不办理入住/售后
民宿投资方	被授权项目的订单统计、脱敏订单摘要、收入、成本、收益和对账汇总	查看项目报表、趋势、收益和对账摘要	默认只读；不看住客敏感资料/完整履约信息，不执行订单或财务操作

组合授权：最终权限 = 登录状态 ∩ 租户 ∩ 参与方身份 ∩ 操作权限包 ∩ 总账号/集体/房源范围 ∩ 字段级别 ∩ 有效期。投资方和运营方默认只读。
读写分离：订单查询与订单处理、财务查询与退款调账/结算配置必须使用不同权限；能看数据不代表能执行操作。
统一过滤：列表、详情、统计、导出、批量操作、异步任务使用同一数据范围；客户端业务 Key 只能定位，不能扩大权限。
冲突与撤权：冻结/显式拒绝优先；撤销、到期或房源冻结后新请求和未执行高风险任务立即失效，历史订单和账务责任保留。
敏感能力：住客证件/手机号、完整结算账户、敏感导出、明文入住凭证和远程开锁独立授权、二次确认并审计。

产品能力已确认

无前台民宿入住信息卡与智能锁联动

供应商协议待确认

订单确认且满足入住条件：展示民宿定位地址、导航、实际房号和受控密码入口，并通过锁厂商或 PMS Adapter 给对应房间下发临时密码或电子钥匙。
查看密码或点击开锁：独立校验订单归属、实名/风控、入住时间窗、房间与门锁绑定、凭证版本和一次性挑战；每次操作都记录审计。
客人第一次成功开锁：以锁/PMS 回调为准，幂等推进订单到“入住中”，不能由客户端直接改订单状态。
订单取消：尚未使用的临时密码销毁或撤销；已经开始入住的订单按取消/退房规则处理，不能简单改回“未入住”。
异常兜底：回调重复、顺序错乱、锁离线、改期、换房、NoShow、提前入住和延迟退房进入补偿/人工处理，信息卡提供客服电话和可重试提示。

信息/动作	普通订单详情	专用入住接口	安全约束
定位地址	仅返回可见状态和摘要	满足入住条件后返回地址、经纬度、坐标系和到店指引	按订单本人和时间窗分阶段可见
房号	不提前泄露实际房号	返回当前 roomNo 与 roomVersion	换房后旧房号和旧凭证失效
开锁密码	只返回掩码和是否允许查看	用户主动调用 password/reveal 后短时返回	禁止日志、埋点和长期缓存明文
开锁按钮	只返回是否可操作	提交 unlock，按 unlockRequestKey 查询最终结果	受理不等于成功，厂商回调才是事实

开发对接

这部分给前端和后端使用：先查接口，再查字段；长表默认按模块筛选。

接口契约

先认清接口性质，再按清单开发

这里把现有复用、社区新接口、第三方回调和内部能力分开。接口卡片里会说明谁调用、需要什么身份、使用哪种响应外壳、字段怎么传，以及失败后能不能重试。

先说明文档状态：下面的社区接口目前都是“设计待评审”，不是已经上线的地址。现有订单、支付接口会明确标成“现有复用”；财付兔开放接口、IM、民宿进件等外部对接在拿到正式资料前标成“待调研”。门票只保留业务位置，不建设供应商接口、同步、下单或回调。

接口组	固定前缀	谁调用	鉴权和数据范围	默认响应
C 端 App	`/app/community/**`	游客、普通登录用户，以及尚未取得商家身份的入驻申请人	默认登录；只有明确公开的查询允许匿名。商家/民宿入驻在身份激活前按申请人本人隔离，不能反过来要求先有商家身份	详情/动作使用 `R<T>`；分页直接返回 `TableDataInfo<T>`
商场商家端	`/app/merchant/community/**`	从财付兔免登进入、已映射为 `MALL_MERCHANT` 或员工内部主体的商户	不提供房叮咚账号密码登录；校验财付兔一次性码换取的短时会话、tokenVersion、员工 scope 和商家/门店资源范围	`R<T>` 或 `TableDataInfo<T>`
运营后台	`/system/community/**`	平台运营、审核、财务、运维	登录 + `@SaCheckPermission` + 租户/数据权限；高风险操作留审计	详情/动作 `R<T>`；页码分页直接返回 `TableDataInfo<T>`
财付兔 OpenAPI	`/open/community/v1/**`	财付兔服务端	先校验 appKey + 签名 + 时间窗 + nonce + requestId，再校验 Bearer merchantAccessToken + 商户/商店 scope + tokenVersion；所有写操作仍走房叮咚领域服务	详情/动作使用约定的 OpenAPI 外壳；分页仍直接返回项目 `TableDataInfo<T>`
第三方回调	`/callback/community/**`	财付兔进件、民宿进件、IM 等供应商	不使用用户 Token；按供应商验签、时间窗、nonce、事件唯一键和来源白名单校验	按供应商协议返回 ACK，不强行套平台 `R<T>`
内部能力	没有 HTTP 地址	Service、Adapter、MQ、SnailJob	模块依赖、事件契约和任务权限	Java DTO / 事件对象；不为了凑接口暴露 Controller

普通返回

项目真实外壳只有 code、msg、data。接口卡片列出的业务字段位于 data。

R<NoteDetailVO>

分页请求

所有分页查询统一继承项目 PageQuery，默认 pageNum=1、pageSize=10；排序字段必须经过接口白名单校验。

pageNum / pageSize / orderByColumn / isAsc

分页返回

分页接口直接返回 TableDataInfo<T>，列表固定使用 rows；额外汇总和版本信息放入有明确 VO 的 statistics。

total / rows / code / msg / current / pageSize / statistics

BO/VO 怎么看：每张接口卡都会给出建议的请求模型和响应模型；卡片下方列出的字段、类型、必填条件和校验规则才是契约正文。出现 object/array<object> 时必须继续展开到前端实际消费的子字段；只写对象名、items[] 或“见 Schema”不算完成契约。评审通过后，Java BO/VO、SpringDoc Schema 和这份清单必须同名同义，不能实现时再改成通用 Map。

接口怎么拆

按业务承诺拆接口，但可维护资源仍要有完整 CRUD

GET / POST / PUT / DELETE

类型	接口承诺	必须带什么	不能怎么做
GET 查询	只读取当前有权看到的结果，不产生业务副作用	公开业务 Key、筛选条件；分页时使用项目 `PageQuery`	不能自造游标分页外壳，也不能用 GET 审核、发码、消耗 Token、创建异步任务或推进状态
POST 保存	创建草稿或保存某个明确资源	`clientRequestId`；更新时再带 `version/baseVersion`	不能让一个“save”同时猜创建、审核、发布和下架
PUT 修改	按写入返回的同一业务 Key 修改可维护主数据	Path 业务 Key、`version/baseVersion`、`clientRequestId`和明确可改字段	不能改用数据库自增 ID，不能覆盖不在本请求中的旧字段
DELETE 删除	删除未发布/未被引用的可维护资源，默认为逻辑删除	Path 业务 Key、`version/baseVersion`、原因和 `clientRequestId`	订单、流水、事件、快照等不提供通用删除；改用取消、撤回、下线或冲正
POST 状态动作	审核、发布、取消、冻结等一个明确动作	当前版本、动作/结果、原因、幂等键	不能直接更新状态字段；必须经过领域服务和现有状态机
POST 预览/确认	先计算影响范围、成交价或售后资格，不立即执行最终副作用	返回短时 `previewKey/quoteToken`，绑定用户、范围、版本和有效期	不能把预览成功显示成执行成功，也不能信任客户端回传的金额或范围
POST 异步任务	只承诺任务已受理，后续可查状态、失败项和重试结果	`taskKey`、`accepted/status`、预估范围	不能刚入队就返回“处理完成”
第三方回调	验签后先收件去重，再异步映射业务状态	服务端白名单 Provider、时间窗、nonce、供应商事件唯一键	不能让对方自报身份，不能用“收到回调”代替“业务处理完成”

CRUD / 查询基线

写入返回的标识，必须就是详情、修改和删除使用的标识

只增加契约

基线	必须具备	例外 / 替代语义
可维护主数据	新增、Key 详情、分页筛选、修改、逻辑删除/停用；缺一项必须写明理由	已发布、被引用或存在历史版本时先下线，不破坏旧版本
标识一致	创建/保存返回 `Key`；详情、修改、删除继续使用该 `Key`	复合作用域不全局唯一时，写入响应同时返回区域定位字段
查询筛选	保留原 Query，按适用性追加 Key、关键词、状态、类型/归属、地域、创建/更新/业务时间区间和白名单排序	权限和租户范围仍从可信上下文取得，不能把筛选字段当成越权入口
流程 / append-only	详情、分页筛选、显式状态动作或重放/冲正/补偿	订单、售后、审核、事件、流水、快照和任务不强行凑物理删除

兼容性：本轮不删除、改名或改变任何已列请求/响应字段的含义；新筛选字段和新接口都是增量候选契约。

字段归属：specialty 是房叮咚维护的特产 SPU，specialtySku 是可售规格，store 是房叮咚商城店铺；财付兔只拿授权调用这些数据。ticket 当前只是门票业务占位，nearbyMerchant 是单独的附近商家资源，mount 是文章卡位关系，quoteToken 是短时报价凭证，orderCode 是现有订单工厂生成的真实订单号。

文章发布

建草稿 → 保存版本 → 提交审核 → 后台审核 → 发布后进入 Feed。保存成功不等于发布成功。

评论发布

发表评论 → 读取租户审核开关 → 开启时走内容安全/人工审核，关闭时直接公开且标记 SKIPPED。内容安全 Adapter 不是前端 HTTP 接口。

特产成交

商家在房叮咚建店和维护 SPU/SKU → 后台审核并上架 → App/文章卡片/财付兔读取同一份商品 → 购物车或立即购买 → 下单确认拿 quoteToken → 现有订单工厂建单并支付 → 库存、销量、付款人数、发货、售后和评价按订单事件更新。

民宿关联

总账号主进件 → 审核激活 → 生成一次性码 → 扫码预校验 → 提交关联 → 风控/审核 → 成员管理自己的房源，总账号统一结算。

没有匹配的接口，请调整筛选条件。

字段说明

每个字段是什么意思

字段表默认收起，点开需要的模块即可。每个字段都写了放在哪里、是什么类型、什么时候必填、后端怎么校验、前端拿它做什么。

没有匹配的字段，请换一个关键词。

上线准备

把容易漏掉的异常、权限、数据修复和待确认事项集中放在这里。

上线检查

上线前逐项检查什么

接口能返回 200 只是开始。这里按 M00—M15 列出正常流程之外还要测的权限、重复请求、并发、回调失败、数据修复和回滚。

模块	必须覆盖的场景	一致性 / 状态	权限 / 审计	异常 / 补偿
M00	大文件、断点、重复上传、媒体安全拦截	上传会话与处理状态分离，完成幂等	租户/场景/用户归属，访问审计	过期清理、孤儿文件、处理重试
M01	城市回落、首页组件、按钮跳转、动态子页面轮播、批次预览/发布/回滚	页面/组件/元素/动作关系化；首页与子页面按 releaseKey 原子发布	组件注册表、资源归属、路由白名单、业务目标和发布审计	版本冲突、循环引用、目标页缺失、未知组件跳过、缓存刷新失败
M02	匿名/登录、下架、热点、PageQuery 分页、详情降级	内容公开状态与 viewerState 分离；分页直接返回 TableDataInfo	公开性、租户、作者权限复核	缓存击穿、来源超时、局部降级
M03	草稿列表/回显、自动保存、并发编辑、送审撤回、驳回修改、作者下架、定时发布	草稿/审核/发布版本不可混用；退出页面后可按 draftKey + version 恢复	作者、运营、审核人分离，禁止自审和跨作者读取草稿	冲突回放、流程撤回边界、任务重试、缓存/索引/消息补偿
M04	商家/店铺、分类、SPU/SKU、价格库存、上下架、购物车、订单履约、售后、评价、销量付款人数和财付兔 OpenAPI	房叮咚是商品主库；库存预占/扣减/释放、订单状态、退款冲减和评价统计可重放可对账	商家、员工、店铺数据范围分开；财付兔按 appKey、商家授权和 scope 访问	防超卖、重复下单、重复发货、部分退款、库存流水、统计重算、OpenAPI 幂等限流和密钥轮换
M05	门票业务占位、附近商家展示和受控跳转	门票固定 `contractStatus=RESERVED`、`tradeSupported=false`；附近商家不进入特产店铺和订单	门票没有供应商权限；附近商家按来源授权、租户和地域范围隔离	门票入口明确不可交易；附近商家来源超时、数据陈旧、下架和投诉均可降级处理
M06	重复互动、我的收藏、租户审核开关、评论/回复审核、举报提交/处理、软删除、恢复	关系唯一键，计数最终一致可重算；审核开启时 PASS + PUBLISHED 才公开，关闭时 SKIPPED + PUBLISHED 才公开；举报工单状态与目标状态分开	目标可见性、评论/举报权限、开关版本、Provider requestId、风险标签和处理审计	关闭时不调用内容安全；开启时超时不自动放行；举报跨域动作走目标领域服务；MQ 重试、计数重建、审核回放、人工复核
M07	作者停用、商品/地点反向流、关联变化	反向索引不做主库，结果带版本	作者隐私和内容公开状态复核	索引延迟、脏关系清理、缓存降级
M08	离线埋点、批量重复、乱序、重放、业务事件失败	eventId 去重，事件状态可重试	采集授权、脱敏、查询范围	死信、重放上限、重建和对账
M09	联想、零结果、敏感词、阿里云 ES Serverless 索引切换、对账、降级	MySQL 权威，阿里云 ES Serverless 索引版本/alias 原子切换	词条、干预、基础设施配置和导出操作审计	增量失败、全量重建、差异修复；ES 不可用不回源全表 LIKE
M10	冷启动、重复内容、置顶/屏蔽、策略灰度回滚	召回/排序/干预版本可解释	策略发布和人工干预分级审计	超时降级、榜单重算、规则 Feed
M11	商家下单、支付、库存、履约、售后、退款、结算、回调、民宿入驻	订单/支付/履约/售后/结算拆分状态	商家/成员/房源/账务主体/来源隔离	回调幂等、主动查询、补偿、对账、冻结退出
M12	多政策、重复事件、冻结、撤销、退款联动	政策版本和奖励流水快照	政策发布、财务和反作弊审计	冲正、失败重试、对账、人工复核
M13	聚合通知、未读一致、账号切换、失效跳转	通知唯一键，已读幂等	只读本人，模板和发送记录审计	重复消费、积压、过期清理
M14	消息重试、回调乱序、媒体失败、撤回、拉黑	clientMessageId/providerMessageId 去重	会话成员、内容安全、媒体权限	发送状态补偿、回调重放、Provider 降级
M15	健康、指标、内容安全 Provider、阿里云 ES Serverless、修复预览、重放、重建、灰度、回滚	任务范围、状态和进度可查询；依赖异常有明确降级	最小权限、二次确认、Provider/索引版本和完整审计	失败项重试、熔断、回滚、灾备演练；评论不自动放行，搜索不全表回源

上线治理

出了问题怎么查、怎么修

监控、任务、修复、重放和回滚都要有入口、有权限、有记录，不能临时改库解决问题。

接口具备中文 SpringDoc summary；关键请求字段补充 Schema 说明；新 Controller 包纳入 springdoc.group-configs。
无 Token、无权限、跨租户、跨集体、跨成员和跨房源访问均失败；日志脱敏，接口不返回证件、银行卡、密钥和永久签名。
写接口、回调、消息、任务和补偿均可幂等；重复请求不重复创建订单、账务分录、奖励、通知或审核任务。
房叮咚商城要验收商家/店铺、分类、SPU/SKU、价格库存、审核上下架、购物车、订单、支付、发货、售后、评价、销量和付款人数；所有经营写操作只有一套领域服务，App、商家端、后台和财付兔 OpenAPI 不能各写一套状态。
特产价格和库存必须做并发与幂等测试；支付成功响应超时、重复通知、库存不足、部分发货、部分退款、售后处理中和统计延迟都要有可恢复结果。门票首期不得创建订单或占库存。
Feed、搜索、推荐、特产详情和财付兔 OpenAPI 异常时可降级；门票始终返回预留/不可交易状态；高副作用修复任务支持 preview → confirm → execute → progress。
审核开关开启时，评论和评论回复必须先经过内容安全检查；阿里云内容安全超时、限流、异常或结果不确定时不能自动公开，必须进入待审、重试或人工复核。开关关闭时新评论标记 SKIPPED，不创建审核任务、不调用内容安全，开关本身必须有版本和审计。
阿里云 Elasticsearch Serverless 的连接、鉴权、容量、索引 alias、增量同步、全量重建和对账都有监控；ES 故障不能回源 MySQL 做全表 LIKE。
M11 订单创建前校验成员、房源和账务主体均为 ACTIVE；随后通过现有 OrderTypeHandlerFactory 创建真实平台订单，支付通过现有 PayService / PayStrategyFactory；创建后固化 groupKey、memberKey、listingKey、accountingSubjectKey 和 settlementMode。
业务指标、依赖健康、队列堆积、回调失败、索引差异、账务差异和入驻码异常可观测、可告警、可追溯。

确认进度

哪些已经定了，哪些还要查

这份清单已经把本轮回复标成“已确认、部分确认、待调研”。已确认内容已经回填到模块流程、接口和字段；剩下的内容继续按“方案预留”处理，不能当成已上线能力。

R01 · 商场商家身份【已确认】：MALL_MERCHANT / MALL_MERCHANT_EMPLOYEE 仅是房叮咚内部授权主体，由财付兔可信商户/员工身份自动映射，与酒店商家身份、菜单、权限和资源隔开；不创建可用账号密码登录房叮咚的重复账号。
R02 · 财付兔鉴权与本地身份【部分确认】：商场商家只在财付兔登录和进件。财付兔应用签名证明系统身份，一次性 authorizationCode 证明当前商户/员工；房叮咚自动映射 merchantKey/principalKey 并签发短时 merchantAccessToken 或免登会话。授权码回查、Token 刷新/撤销、冻结回调和员工声明以正式协议为准。
R03 · 商城范围【已确认】：商城首期只卖特产。店铺、分类、SPU、SKU、价格、库存、上下架、购物车、订单、发货、售后、评价、销量和付款人数都由房叮咚保存并负责业务规则；财付兔只是被授权调用房叮咚 OpenAPI，不能成为商品主库，也不能维护一套镜像主数据。
R04 · 特产发布与渠道范围【部分确认】：房叮咚负责商品审核和上下架，并控制商品是否进入 App、首页、频道、文章卡片、搜索、推荐和财付兔渠道。各渠道首期是否默认开放、审核岗位、强制下架后的申诉流程和历史卡片怎么显示还要确认。
R05 · 规则、库存、履约和售后【部分确认】：价格、库存、运费和售后规则由房叮咚后台或商家端维护，订单和支付复用现有订单工厂。库存在哪个节点预占、超卖怎么处理、多久自动关单、是否支持部分发货、退货怎么验收、补发和平台介入时限仍要确认。门票不进入首期交易。
R06 · POI 主数据【已确认首期方向】：文章插入 POI 卡片时调用高德搜索，由用户选择；服务端保存高德来源 ID 和本地 poiKey，高德是首期来源，其他地图来源预留。POI 合并、改名、停用和历史引用治理还要确认。
R07 · 文章卡片与 POI 关系【已确认首期方向】：文章可在任意可视光标位置插入 POI、特产、门票、附近商家、酒店和民宿卡片；段落中间插入时先拆分文本块，再插入稳定 MOUNT_SLOT。位置以 contentBlocks[] + slotKey 为权威，禁止字符偏移和新版本尾挂回退。每项至少保存 noteKey、noteVersionId、contentVersion、mountKey、mountType、目标业务 Key、poiKey 和 slotKey；民宿再保存集体、成员和房源。
R08 · 民宿主进件【部分确认】：总账号只做一次主进件，旗下集体/民宿通过专属码关联；成员可以跳过重复进件，但不能跳过登录、实名、房源证明和风控。支付/进件供应商、材料、回调协议和关联范围还要确认。
R09 · 民宿入驻码安全【已确认核心规则】：一个专属码只能成功使用一次，成功后立即失效。冒领或异常时进入人工审核、冻结或封禁。现有代码已经有后台 SysUserController#changeOperationStatus 和 sys_user.operation_status 的操作限制，但 app_user 不走同一拦截，所以不能直接当成民宿成员封禁能力；成员对象的映射、设备风控和人工解锁流程仍要确认。
R10 · 集体与成员账务【已确认首期模型】：总账号负责主进件、旗下全部数据和统一结算；成员/民宿管理自己的资料、房源和经营台账。订单保留总账号、集体、成员和房源维度，但结算统一到总账号主进件对应的卡/主体，成员首期不建独立收款主体。
R11 · 订单归因与激励【部分确认】：文章发布以及文章关联的特产或民宿成交后可以触发激励，规则必须后台配置、版本化、可预览、可撤销和冲正。到底按支付成功、履约完成还是结算完成算“售出”，归因优先级、金额上限和退款/拒付怎么处理还要确认。
R12 · 内容与交易合规【待调研】：要确认哪些文章、POI、特产、门票和附近商家需要本地审核；评论和回复哪些风险转人工；审核开关由谁审批、按租户还是频道生效、历史待审怎么处理；实名游客、订单和第三方回调原文保存多久、谁能看、何时脱敏或删除。审核开启时评论公开前必须明确通过；关闭时新评论标记 SKIPPED，不调用内容安全。
R13 · 第三方 IM【待调研】：服务商和能力尚未确定；一对一/群聊、撤回、举报、拉黑、客服转接、离线推送、保存期限、价格、QPS、SLA、数据地域和故障切换完成选型与 POC 前，只保留 Provider Adapter，不开发自建 IM。
R14 · 搜索与推荐【已确认首期方向】：搜索底座确定使用阿里云 Elasticsearch Serverless 版；MySQL 做权威库，RabbitMQ 做增量同步，SnailJob 做重建/对账，索引通过版本号和 alias 切换，接口返回 searchVersion 和降级标识。基础搜索、联想、规则召回、排序、热门和版本化策略发布仍按首期范围建设；地域、网络和鉴权、分词/分析器、容量/费用、SLA、配额、索引生命周期和压测指标还要确认。
R15 · 通知与消息【已确认首期方向】：优先复用现有通知系统，社区只接入事件、模板、结构化跳转和幂等适配；现有系统缺能力时才补适配层，渠道和退订/频控细节以盘点结果为准。
R16 · 智能锁联动【产品能力已确认】：无前台民宿订单必须有受控定位地址、房号、开锁密码和开锁按钮。普通订单详情不返回明文密码，查看密码与远程开锁使用独立接口并重新校验订单本人、入住时间窗、设备风险和凭证版本。改期、换房、NoShow、离线兜底和 PMS/厂商协议还要确认。
R17 · 商用指标与灾备【已确认原则】：按大型系统标准和《阿里巴巴 Java 开发手册》执行分层、幂等、权限、审计、错误码、超时重试、敏感数据保护和可观测性；具体 P95、可用性、峰值并发、RTO/RPO 和审计留存数字在压测、合规和灾备评审后固化。
R18 · 订单工厂与支付链路【已确认硬约束】：所有特产和民宿订单都进入现有 OrderTypeHandlerFactory / OrderTypeHandler；状态变更使用 AppOrderStateMachineService.fireEvent 或现有 Handler；用户支付使用 AppOrderPayServiceImpl / PayService / PayStrategyFactory；支付回调继续使用现有 /app/pay/notify/*。当前 AppOrderType 只有 HOTEL、BOX，新增订单类型、Handler、退款、分账和状态机覆盖要在联调前确认，不能另建一套社区订单或支付。门票供应商和交易范围未确认前不生成订单。
R19 · 内容安全与搜索基础设施【方向已确认，细节待调研】：审核开关开启时评论和评论回复必须先经过内容审核；关闭时新评论标记 SKIPPED，不创建审核任务、不调用 Provider。内容安全通过 Provider Adapter 预留阿里云内容安全，机审异常不得自动放行，风险内容可转人工或封禁。搜索使用阿里云 Elasticsearch Serverless 版，MySQL 是权威库，索引可重建、可对账、可通过 alias 切换，ES 故障不回源全表 LIKE。仍需确认开关权限/生效范围/历史补审，以及内容安全产品/API、地域、数据留存和标签映射、ES Serverless 网络/鉴权、分词、版本、容量、费用、SLA、配额和灾备方案。
R20 · HTTP 契约冻结【开发前确认】：逐条确认游客接口、后台权限码、商家员工数据范围、BO/VO 名称、错误枚举和第三方 ACK；评审通过后才把“设计待评审”改成“已冻结”，实现后回填 SpringDoc 和代码入口。
R21 · 购物车与多店订单【部分确认】：首期要有购物车，并支持同店多个 SKU 生成一个真实订单和多条订单明细；结算时必须重新校验 SKU 状态、现价、库存、限购和运费。跨店拆单、父子单或订单组、合并支付、运费/优惠分摊、部分退款和部分失败回滚怎么落到现有订单工厂仍待确认，确认前一次提交只允许一家店。
R22 · 收货地址与实物物流【新增待确认】：项目已有 /app/orderAddress/** 和 BOX 订单地址能力，但当前接口使用内部数字 ID，复用前要逐条核对本人归属、跨租户、删除方式、脱敏和公开 Key。还要确认特产的运费模板、配送范围、承运商、物流单回传、拒收/退货和异常件处理。
R23 · 特产评价与投诉【部分确认】：特产详情必须有评价、评分和数量，采用已购评价、独立评价表、商家回复和独立审核开关。追评次数和时间窗、匿名展示、图片评价、默认好评、差评申诉、是否与文章评论共用阿里云内容安全配置、投诉举证和处理时限还要确认。商品评价不能混进文章评论表。
R24 · 营销与开票【新增待确认】：满减、优惠券、活动价、会员价、佣金和发票是否进入首期尚未确定。若进入，必须在报价阶段返回规则版本和金额分摊，并在退款、激励、结算和对账中按订单快照冲正，不能只在前端减一个展示金额。
R25 · 财付兔正式接入【待调研】：已确认商户只登录财付兔，房叮咚不提供重复注册或密码登录。双方仍需冻结 authorizationCode 的签发与回查、appKey/签名算法、merchantAccessToken/refreshToken、免登会话、tokenVersion、刷新/撤销/冻结回调、员工与商店 scope、密钥轮换、限流、SLA、版本兼容和错误码，并确认财付兔可代商家操作的具体范围。
R26 · 门票供应商与范围【待调研】：已取消原定供应商，当前只保留 ticketKey、页面位置和候选字段。需要重新确认供应商、商务模式、资源范围、是否首期上线、是否在房叮咚内交易。选型完成前不做数据同步、采购、出票、回调或订单。
R27 · 门票采购和资金【待调研】：供应商选定后再确认库存占位、采购节点、采购价和售价、预充值或账期、出票核销、退改、退款回账、账单和差异处理。这些内容当前不能写成已实现能力。
R28 · 附近商家来源【待调研】：需要确认数据源、商家授权、类目、坐标系、营业时间、更新频率、距离计算、联系方式展示、受控跳转、下架和投诉处理。首期按只展示/跳转、不下单设计，不能直接复用房叮咚商城店铺身份。
R29 · 门票客服和售后责任【待调研】：供应商确定后再确认客服工作台、出票失败通知、入园问题、退改审核、供应商响应 SLA、节假日值守、赔付责任、发票和用户协议。门票预留阶段不承诺这些能力。
R30 · 商店模型【待确认】：需要确认一个商家能开几家店、一个员工能否跨店、店名和品牌名怎么审核、关店后历史订单和评价怎么展示，以及财付兔授权按商家还是按店铺。接口已经按 merchantKey + storeKey 分层预留。
R31 · 销量和付款人数展示【待确认】：需要产品确认商品卡片显示累计、近 30 天还是本周数据；salesQuantity 是否扣除部分退款，paidBuyerCount 在全额退款后何时冲减；是否允许“500+”这类模糊文案以及分档规则。数据库只保存可审计的真实统计，运营不能直接改原数。
R32 · 商品评价审核开关【待确认】：已预留 specialtyReviewEnabled 和 specialtyReviewModerationEnabled。要确认是否按租户或店铺分级；关闭审核后是否完全不调用阿里云内容安全；图片评价怎么审；历史待审怎么处理；商家回复是否用同一开关；谁有权修改开关。

这是文旅社区 M00—M15 的开发草案。可以直接放到 Nginx 或对象存储上查看，不依赖构建工具。接口上线前仍要和实际代码、/v3/api-docs 逐项核对。