Landlord API — Slice 3: Media Sync
A declarative PUT keeps a property's photo gallery in step with a listing site: each Source owns only its own photos, fetches run outside the database lock behind a public-IP-only SSRF guard, and every URL gets its own result. API keys can also upload and list ownership proofs, but never download them.
- Predecessor Slice 2 — Idempotent Sync (2026-09-22)
- New ADR 0065
- Status Approved
Slice 3 让房东的同步任务通过一个声明式 PUT,把房源相册与房源网站保持一致;并允许 API 密钥上传(但永不下载)产权证明。每个 Source 只拥有自己的照片;下载在数据库锁之外进行,并受严格的"仅公网 IP" SSRF 防护;每个 URL 都有自己的结果。
拷问结果
2026-09-23 完成拷问。所有决策均已确定,列在拷问决策表(§3.5)中。所有权规则(D38、D39、Q5、Q1)记录在 ADR-0065。
为什么
Slice 2 让房源和刊登的写入可以安全重复。照片被刻意留到后面:在弄清同步如何工作之前就发布上传格式,会冻结错误的契约。
没有照片的房源租不出去。Slice 3 让同步任务把相册与源网站保持一致,并让密钥上传解锁提交所需的产权文件。
现有基础
已于 2026-09-23 在仓库中核实。
| 事实 | 证据 | 为什么重要 |
|---|---|---|
PhotoRepository 没有删除方法,只有 Create、CountByProperty、ListByProperty、UpdatePosition | ports.go:123-135 | 声明式相册必须能删除照片;面板也不能删除照片 |
PhotoStore 只有 Put 和 PublicURL,"没有签名 URL" | ports.go:141-150 | 预签名需要修改端口 |
共享 Storage 端口刻意保持最小:"没有签名 URL、列举或 stat 接口" | storage.go:28 | D37 不去动它;没有列举调用就没法做孤儿清扫 |
Storage.RemoveObject 已存在 | storage.go:24 | 删除只需一行包装 |
| 通过 S3 协议和 AWS4-HMAC-SHA256 访问 SeaweedFS | seaweedfs_storage_test.go:50 | 以后做预签名可行 |
| 每个房源最多 10 张照片,每张 5 MB,仅 jpeg/png | ports.go:71-74 | 这个上限让同步下载可行(D40) |
rental_property_photos 有 position 和 deleted_at,没有哈希和 URL | migrator_rental.go:79-88 | 需要新列 |
面板的 SetPosition 交换存在已知竞态;没有唯一的 (property_id, position) | photo.go:55-64 | 既有问题,只标记不修复 |
SetPosition 用 FOR UPDATE 锁房源行;Upload 不加锁(先计数,再插入) | photo.go:66-110, photo.go:153-200 | 并发上传和 PUT 可能超出上限(Q2) |
| 照片上限映射为 400,这是有意的:"其他所有租赁业务拒绝都用 400" | property_handler.go:398-410 | 不新增 409(Q4) |
全局 30 秒 TimeoutMiddleware 包裹每个请求 | cmd/server/main.go:382 | 下载预算必须给存储和应用留出时间(Q15) |
| v1 有按密钥的每小时限流 | v1_routes.go:46 | 限制对外下载量(Q26) |
IdempotencyUseCase.Execute 在一个事务中执行工作,重放时重新读取 | idempotent_executor.go:51-183 | 这是 Q3 不简单的原因 |
ProofUseCase.Upload 已校验 pdf/jpeg/png 和 5 MB 上限 | proof.go:74-157 | 证明 API 只需挂载,不需新建 |
ProofRepository 没有删除;CountByProperty 统计已设置 verified_at 的行 | proof_repository.go:78-85 | 证明上限(Q16)是每个房源的终身上限 |
证明上的 verified_at 表示"对象写入已完成",而不是"人工核实了所有权" | proof_repository.go:123-127 | API 上传不会增加新的欺诈面 |
| Outbox、relay 和调度器已存在 | internal/shared/infrastructure/outbox/ | 曾考虑用于异步下载,在 D40 下不需要 |
决策
沿用 Slice 2 的编号。
| # | 决策 | 选择 |
|---|---|---|
| D37 | 现在上线哪些上传方式 | 现在做按 URL 下载;预签名上传推迟到 Slice 5 |
| D38 | 声明式 PUT 拥有什么 | 只拥有调用方自己的 Source(source = X,任意来源渠道)。无主照片不动 |
| D39 | 排序 | 一个 Source 排序自己的区块,追加在它不拥有的照片之后 |
| D40 | 下载方式 | 在请求内并行下载,不在任何事务中。没有 worker、没有状态模型、没有重试表 |
| D41 | SSRF 策略 | 只连接公网 IP,按解析后的地址检查,并固定连接 |
| D42 | 哈希和 URL 带来什么 | 条件请求跳过、内容变化时替换(新键)、每个房源一份副本。不跨房源共享对象 |
| D43 | 通过 API 处理证明 | 上传和列出元数据。任何密钥都不能下载 |
| D44 | v1 中的传输方式 | 照片和证明用 multipart;按 URL 下载只用于照片 |
D37 · 现在按 URL 下载,以后预签名
上线按 URL 下载;预签名上传推迟到 Slice 5。
预签名和按 URL 下载为不同调用方解决同一个问题。房源网站已经把图片放在 URL 上,所以按 URL 下载只需一次调用,集成方无需写上传代码。预签名主要服务于推送本地文件的 CLI,那是 Slice 5——在那里做,就有真实的调用方可测试。推迟它也让刻意最小的 Storage 端口保持不变。
否决:一个 slice 同时做两种方式——三条交付路径加上相册语义,slice 半途停滞的风险最高。
D38 · PUT 只拥有自己 Source 的照片
同步任务绝不能破坏人做出的选择。
把声明限定在调用方自己的 Source,对应 Slice 2 的 D14(每个 Source 保留自己的 external_ref)。所有权只由 source 决定,绝不由 origin_channel 决定(Q5):Slice 5 的 CLI 以 origin_channel = 'cli' 写入,仍拥有它声明的照片。source = NULL 的照片是无主的:任何同步都不能删除它。
否决:PUT 替换整个相册;可选的"API 管理全部照片"开关;按 origin_channel = 'api' AND source = X 判断所有权。
D40 · 请求内下载,不在事务中
在请求内并行下载,不打开任何事务。
每个房源最多 10 张照片。5 个并行下载、每个 URL 超时 10 秒,最坏约 20 秒完成,在 20 秒下载预算内;全局 30 秒中间件还剩约 10 秒用于存储和加锁应用(Q15)。因为 PUT 是声明式且幂等的,重试失败的照片就是再发一次同样的 PUT——没有 worker、没有单张照片状态、没有轮询接口、没有重试策略,也不会有待处理照片泄露到公开相册。下载绝不在数据库事务中进行(Q2):在等待陌生人的 CDN 时持有行锁和连接,会把面板阻塞最多 20 秒。
否决:带单张照片状态的后台 worker;在加锁事务中下载。
被否决的方案
| # | 否决 | 原因 |
|---|---|---|
| D37 | 一个 slice 同时做两种方式 | 三条交付路径加上相册语义;slice 半途停滞的风险最高 |
| D38 | PUT 替换整个相册 | 手动上传照片的房东会在下次同步时毫无提示地失去这些照片 |
| D38 | 每个房源可选"API 管理全部照片" | 一个开关、一个 UI 切换、两种行为要测试,却没人提出过这种需求 |
| D38 | 按 origin_channel = 'api' AND source = X 判断所有权 | cli 写入方永远删不掉自己的照片(Q5) |
| D39 | 绝对位置,最后写入者胜 | 两个来源会每晚互相打乱顺序,没有人参与 |
| D39 | 面板可以隐藏、移动或删除有主照片 | 同步必须记住人工覆盖:需要新表结构和规则。以后可叠加(Q1) |
| D39 | 单独的 is_cover 列 | 模型最干净,但要一次迁移和面板 UI 修改,而 D39 已解决这个问题 |
| D40 | 带单张照片状态的后台 worker | 一整个子系统,只有上限高得多时才值得 |
| D40 | 在加锁事务中下载 | 持有行锁和数据库连接最多 20 秒(Q2) |
| D41 | 每个密钥的域名白名单 | 房源网站一换 CDN 主机名就失效,且每个房东都要配置 |
| D41 | 固定的私有网段黑名单 | 漏掉 0.0.0.0/8、fe80::/10、IPv4 映射的 IPv6、NAT64 等(Q6) |
| D41 | 从混合 DNS 结果中丢弃坏 IP,连接其余的 | 真实 CDN 不会混入私有地址;混合结果是攻击或配置错误(Q21) |
| D42 | 带引用计数的跨房源对象共享 | 删除时释放了另一个房源仍在显示的对象,是可见的缺陷 |
| D42 | (property_id, sha256) 唯一索引 | 若面板照片字节相同,每次同步都会永久硬失败 |
| D42 | 内容变化时覆盖同一个存储键 | CDN 和浏览器会继续显示旧图(Q7) |
| D43 | 完整证明访问,包括下载 | 泄露的密钥会变成身份文件泄露 |
| D44 | 证明也按 URL 下载 | 我们会凭 API 调用方一句话,把经过第三方的地契存进私有桶 |
| — | 新的 409 photo_limit_exceeded | 现有上限已映射为 400;同一个限制不能有两种答案(Q4) |
| — | 现在做孤儿清扫器 | 需要在最小存储端口上加列举调用;窗口期崩溃很少见(Q18) |
拷问决策(2026-09-23)——Q1–Q26、F1–F6 及各自应用位置
| # | 决策 | 位置 |
|---|---|---|
| Q1 | 有主照片在面板中只读:不能移动、不能删除,由服务器强制,每张都显示说明原因的提示。只要存在无主照片,封面就总是无主照片 | §4.4, §10, §12, ADR-0065 |
| Q2 | 三个阶段:规划、在事务外下载、然后加锁重读、检查上限并应用。删除未用对象。multipart 使用同一把锁 | §4.2, §4.7, §8.2 |
| Q3 | 相册 PUT 接受 Idempotency-Key 但忽略;在 rental-v1.yaml 中说明 | §8.4 |
| Q4 | PUT 和 POST 都用现有的 400 上限映射 | §4.6, §8.3 |
| Q5 | "我的" = source = X,任意来源渠道;source = NULL 是无主的 | §3.2, §4.2 |
| Q6 | 仅公网 IP 固定连接;先解除 IPv4 映射;拒绝 CGNAT、NAT64、基准测试网段;Proxy: nil | §5.2 |
| Q7 | 字节变化使用新键;提交后尽力删除旧对象 | §4.3, §6.5 |
| Q8, Q10 | 响应 = GET photos 格式的完整相册,加上每个输入 URL 一个结果,按请求顺序 | §4.5 |
| Q9 | 变化后的字节与我不拥有的照片冲突:删除我的行,保留对方的,duplicate_image | §4.3 |
| Q11 | 在跨所有者去重之前,把哈希相同、正被丢弃的我的行重新绑定到新 URL。查询字符串原样保留 | §4.3 |
| Q12 | 同一个 PUT 中出现两次相同 URL:下载前返回 400 | §4.1 |
| Q13 | [] 只清除此 Source 的照片 | §4.1 |
| Q14 | 刷新失败时保留现有行并报告原因 | §4.3 |
| Q15 | 下载阶段上限 20 秒,在全局 30 秒中间件之内 | §5.2, §5.4 |
| Q16 | 每个房源最多 10 份证明,面板和 API 一样,沿用现有 400 风格 | §7 |
| Q17 | 应用阶段在锁内用已下载的对象重新规划;最后提交者胜 | §4.2 |
| Q18 | 孤儿对象记日志;清理任务作为后续;现在不做清扫器 | §6.5, §11 |
| Q19 | multipart:锁前 Put,然后加锁检查上限并插入;失败时清理 | §8.2 |
| Q20 | 本 slice 中 multipart 没有 source | §8.2 |
| Q21 | 任一解析 IP 非公网即拒绝该 URL | §5.2 |
| Q22 | 封闭的 results 状态词表;duplicate_image 不算失败 | §5.5 |
| Q23 | 即使每个 URL 都失败也返回 200 | §4.5 |
| Q24 | 替换时更新宽和高 | §6.4 |
| Q25 | source 暴露给房东面板和 v1 密钥;source_url 仅内部;公开 JSON 不变 | §8.5 |
| Q26 | 沿用现有密钥限流;上限写在 ponytail: 注释中 | §5.4 |
| F1 | 重复 URL 每次同步都重新下载;接受这一有界成本 | §4.3, §5.3 |
| F2 | 同一 Source 内,数组中靠前的 URL 胜出 | §4.3 |
| F3 | 下载前的上限检查按声明的 URL 数计算 | §4.6 |
| F4 | 清理在 context.WithoutCancel 上运行,带短期限 | §6.5 |
| F5 | 拒绝非 HTTPS 的重定向 | §5.2 |
| F6 | 缺失/null 与 [] 区分;URL 限 2048 字符;刷新失败但保留的行带 photo_id;上限错误码由 golden 固定 | §4.1, §4.5, §8.3 |
相册 PUT
请求
PUT /api/v1/rental/properties/:id/photos
{ "source": "propertyguru",
"photos": [ {"url": "https://cdn.pg.com/a.jpg"},
{"url": "https://cdn.pg.com/b.jpg"} ] }
数组顺序就是照片顺序。没有 position 字段。
请求校验,全部在任何下载之前:
| 情况 | 结果 |
|---|---|
缺少 source | 400 validation_failed |
photos 缺失或为 null | 400 validation_failed |
photos: [] | 有效:删除此 Source 拥有的所有照片,其他不动(Q13) |
| 同一 URL 出现两次 | 400 validation_failed(Q12) |
| URL 超过 2048 字符 | 400 validation_failed(F6) |
| 声明的 URL 超出上限允许数 | 400,现有的上限错误(§4.6) |
URL 按发送时的原样比较。查询字符串是 URL 的一部分,永不规范化(Q11)。
对账
三个阶段(Q2)。只有最后一个持有事务。
- 规划(短读取,不加锁)
像
Upload一样检查房东和密钥模式。加载现有照片。分成我的(source = <declared>,任意来源渠道)和其他。执行上限检查(§4.6)。逐个 URL 决定下载什么。 - 下载(无事务)
并行下载(§5)、计算哈希、把新对象存到新键下。
- 应用(房源行
FOR UPDATE加锁)重新读取现有照片,按新读取的数据重新规划,复用已下载的对象——绝不重新下载(Q17)。再次检查上限;若此时失败,返回 400、不应用任何更改,并删除已下载的对象。否则应用逐 URL 规则,删除 URL 不在列表中的我的照片,并重写位置:先其他,再按数组顺序排我的。
- 清理(提交后)
删除不再被引用的对象(§6.5)。
同一个 Source 同时发两个 PUT:最后提交的胜出。每个都是完整声明,所以这是正确的。
逐 URL 规则
按以下顺序匹配。
| 情况 | 动作 | 状态 |
|---|---|---|
URL 已是我的,来源返回 304 | 保留,不下载 | unchanged |
| URL 已是我的,哈希相同 | 保留 | unchanged |
| URL 已是我的,哈希不同 | 存到新键下,原地更新该行,保留位置(Q7) | replaced |
| URL 已是我的,刷新失败(超时、5xx 等) | 保留现有行和位置(Q14) | 失败原因,带 photo_id |
| URL 还不是我的,哈希与我正被丢弃的某行相同 | 把该行重新绑定到新 URL;保留键和位置(Q11) | unchanged |
| URL 还不是我的,新字节 | 下载、校验、存储、插入 | created |
| 此 Source 的两个 URL 最终哈希相同 | 数组中靠前的 URL 保留该行;靠后 URL 若有行则删除(F2) | 靠后 URL:duplicate_image |
| 字节已存在于此 Source 不拥有的照片中 | 不插入;若该 URL 有我的行,删除它并保留另一张照片(Q9) | duplicate_image |
| 新 URL 失败 | 不存储任何内容 | 失败原因 |
duplicate_image 的 URL 没有自己的行。图片已在相册中,所以没有出错,但调用方会被告知,而不是猜测为什么它的列表和相册不一致。
排序(D39)
无主区块永不移动,所以房东的封面照片在每次同步后都保留。
每张有主照片都显示只读提示,让缺少的控件有解释,而不是凭空消失。文本是经过翻译的面板消息;{source} 是照片的 Source 标识符,按存储原样显示。
只读:由 propertyguru 管理。在这里的修改会被下次同步覆盖。请更新数据源后再同步。
如果某个数据源永久停止,它的照片仍保持只读。房东的任何密钥都能对该 Source 发送 photos: [] 来删除它们(Q13),因为 Source 由调用方声明,不绑定到某个密钥。
响应
一个失效的 URL 不会让请求失败。能应用的都会应用。
200 {
"photos": [ ... the whole gallery, final order, same shape as GET .../photos ... ],
"results": [ { "url": "https://cdn.pg.com/a.jpg", "status": "unchanged", "photo_id": "…" },
{ "url": "https://cdn.pg.com/b.jpg", "status": "fetch_timeout" } ]
}
results每个输入 URL 恰好一条,按请求顺序(Q10)。- 只要该 URL 有对应的行就带
photo_id,包括刷新失败但保留的行(F6)。 - 状态词表是封闭的(§5.5)。
- 即使每个 URL 都失败,响应也是 200(Q23)。请求本身有效,
results说明全部情况。 - 重试就是再发一次同样的 PUT。已存储的 URL 每个只花一次条件请求。
- 下载失败时删除照常发生:是否删除由列表决定,而不是由下载决定。仍在列表中的 URL 绝不会因为刷新失败而被删除。
上限
锁和位置
- 应用阶段在现有的加锁事务模式(
GetByIDForUpdate)中运行,位置用一条UPDATE ... FROM (VALUES ...)重写。 - multipart 上传的上限检查和插入使用同一把房源锁(Q2, §8.2),所以 PUT 和上传加起来不会超出上限。
- 不新增唯一约束。Postgres 中部分唯一索引不能延迟检查,行锁才是真正的保护。
- 面板
SetPosition的交换竞态是既有问题,这里不处理。
安全下载
规则(D41)
| 规则 | 原因 |
|---|---|
仅 https | 明文 HTTP 会泄露,也极易伪造 |
| 自己解析 DNS,检查每个解析出的 IP | 主机名说明不了任何事 |
| 任一解析 IP 非公网,就拒绝该 URL(Q21) | 混合结果是攻击或配置错误 |
| 连接已检查的 IP,而不是主机名 | 否则 DNS 可能在检查和连接之间改变 |
允许:先解除 IPv4 映射的 IPv6,再判断 IsGlobalUnicast() && !IsPrivate() | "公网"白名单不会像黑名单那样漏掉网段 |
另外拒绝:100.64/10(CGNAT)、198.18/15(基准测试)、64:ff9b::/96(NAT64) | 看起来像公网、却能到达内网的网段 |
传输层设置 Proxy: nil | HTTP_PROXY 会完全绕过固定的拨号器 |
最多 3 次重定向,每一跳重新检查;任何非 https 跳转都拒绝(F5) | 只要一跳没检查,就可能落到任何地方 |
Content-Type 必须是 jpeg 或 png | 与现有上传规则一致 |
| 用魔数确认,而不是头部 | 头部是服务器随便声称的 |
| 在 5 MB 处截断流 | Content-Length 可能撒谎 |
| 每个 URL 10 秒,整个下载阶段 20 秒(Q15) | 在全局 30 秒中间件下留出余量 |
| 绝不发送我们的认证头或 cookie | 请求不携带任何我们的东西 |
固定连接通过 HTTP 客户端上的自定义 DialContext 实现,所以检查和连接不会不一致。重定向规则放在 CheckRedirect 中。
条件请求(D42)
每张有主照片存储 source_url、etag、last_modified 和 sha256。
GET https://cdn.pg.com/a.jpg
If-None-Match: "abc123"
If-Modified-Since: Tue, 16 Sep 2026 03:00:00 GMT
304 -> keep the photo, no download
200 -> hash the body
same hash -> keep
different hash -> store under a new key, update the row in place
每晚同步十张未变化的有主照片,只需十个小请求,而不是五十兆字节。duplicate_image 的 URL 是例外:它们没有行,所以每次都完整下载(F1)。
并发和总量
- 最多同时 5 个下载。上限 10 张照片时,最坏情况是两轮各 10 秒,在 20 秒下载预算内。预算用完时仍未完成的 URL 报告
fetch_timeout。 - 对外下载总量受现有按密钥每小时限流乘以 10 个 URL 上限约束(Q26)。
ponytail:一个 PUT 无论下载多少 URL 都只算一次请求;若有滥用报告,把一个 PUT 计为 N 个单位。
结果状态词表
每条 results 恰好带其中一个状态,绝不带原始错误字符串——原始错误会向调用方泄露我们的网络结构。列表是封闭的,并在 rental-v1.yaml 中作为枚举说明(Q22)。
成功
4created- 存储了一张新照片
unchanged304、哈希相同,或重新绑定的行replaced- 新字节、新键、位置不变
duplicate_image- 字节已在此相册中;没有自己的行。不算失败
失败
7url_not_https- 协议被拒绝,包括重定向中的某一跳
url_blocked- 某个解析 IP 不是公网
too_many_redirects- 超过 3 跳
fetch_timeout- 超过 10 秒,或下载预算用完
fetch_failed- 连接被拒、4xx、5xx
unsupported_media_type- 按魔数判断不是 jpeg 或 png
too_large- 内容超过 5 MB
表结构
变更:rental_property_photos
| 列 | 类型 | 原因 |
|---|---|---|
origin_channel | TEXT NOT NULL DEFAULT 'panel' | panel | api | cli,对应 Slice 2 的 D34。记录"怎么来的",从不表示"谁拥有" |
source | TEXT | 拥有它的 Source;NULL = 无主 |
source_url | TEXT | 对账键。仅内部:任何路由都不返回(Q25) |
sha256 | TEXT | 变化检测和房源内去重 |
etag | TEXT | 条件请求 |
last_modified | TEXT | 按原始头部值存储 |
- 不新增索引
- 对账本来就会加载房源的全部现有照片,且上限是 10。URL 匹配、哈希去重和分组都在内存中完成。
- 没有
is_test列 - 照片随房源级联,Slice 2 已把测试房源从公开路径中过滤掉。Slice 2 的清除会连同测试房源的照片一起删除。
PhotoRepository 新增三个方法
| 方法 | 原因 |
|---|---|
Delete(ctx, photoID) | 软删除;端口目前没有 |
UpdatePositions(ctx, propertyID, pairs) | 在加锁事务内用一条语句完成 |
UpdateContent(ctx, photoID, key, sha256, etag, lastModified, width, height) | 原地替换或重新绑定,保留位置。宽高来自 image.DecodeConfig,与 Upload 相同(Q24) |
重新绑定时也更新 source_url。PhotoStore 新增 Remove(ctx, key),是对现有 Storage.RemoveObject 的一行包装。共享存储端口不变。
对象清理
| 时机 | 删除什么 |
|---|---|
| 成功提交后 | 被替换照片的旧键、被删除照片的对象、应用阶段未使用的已下载对象(Q7, Q2) |
| 应用失败后(上限复查、数据库错误) | 本次请求下载的所有对象 |
| multipart 上传的加锁上限检查失败 | 它刚存入的对象(Q19) |
清理是尽力而为的。它在 context.WithoutCancel(ctx) 上运行,带短期限(约 5 秒),所以请求上下文因超时被取消后仍会执行(F4)。删除失败会记日志,孤儿对象留在原处。
产权证明
ProofUseCase.Upload 已校验 pdf/jpeg/png 和 5 MB 上限。本 slice 只是挂载它。
POST /api/v1/rental/properties/:id/proofs
multipart, scope proofs:write
-> 201 { id, created_at }
GET /api/v1/rental/properties/:id/proofs
scope proofs:read
-> [ { id, created_at } ]
列表只返回 id 和日期。没有 URL、没有文件名、没有字节。
证明上限(Q16)
一个房源最多 10 份证明。面板和 API 规则相同,因为都调用 ProofUseCase.Upload。第 11 次上传以现有 proofRejected 风格返回 400,并说明上限,与照片上限一样。没有它,出错的循环或泄露的密钥可以无限往私有桶里上传。
检查贴合现有上传流程(proof.go:74-157),而不是改变它:
- 提前检查
在存储任何字节之前,紧挨现有的管理员冻结检查。达到 10 份就拒绝。这一步阻止循环的密钥塞满存储桶。
- 权威检查
在标记证明已验证的现有加锁步骤(
applyReviewedEdit)中。达到 10 份就拒绝,不验证。
在第 2 步被拒绝,会留下一行未验证记录和它的对象,与该步骤现有的失败情况完全一样。该行记录了密钥,所以没有东西无人追踪,而未验证的证明永远不算证据。只有两次上传竞争时才会走到第 2 步。
契约
新的 v1 接口
| 方法 | 路径 | 权限范围 | 类型 |
|---|---|---|---|
PUT | /api/v1/rental/properties/:id/photos | media:write | 声明式 |
POST | /api/v1/rental/properties/:id/photos | media:write | multipart |
POST | /api/v1/rental/properties/:id/proofs | proofs:write | multipart |
GET | /api/v1/rental/properties/:id/proofs | proofs:read | 仅元数据 |
GET .../photos已在 Slice 1 上线。- 没有
DELETE接口:声明式 PUT 删除自己的照片,而无主照片刻意不允许密钥删除。 - 没有位置接口:顺序来自 PUT 的数组(D39)。
multipart 照片上传没有 source
POST /api/v1/rental/properties/:id/photos
-> 201, appended, origin_channel = 'api', source NULL
这样上传的照片不属于任何 Source(Q20)。它的行为和面板照片一样,任何同步都不能删除它。这是 D38 的直接结果,也是安全的结果。multipart 是否可以指定 Source,由 Slice 5 与预签名一起决定。
处理顺序(Q19),面板和 v1 共用,因为都调用 Upload:
- 校验类型和大小。
- 存入对象(不持有锁)。
- 锁房源行、计数、检查上限、插入。
- 若上限检查失败,删除对象(§6.5)。
错误
没有新错误码。照片上限在 PUT 和 multipart POST 上都返回现有的 400 拒绝(Q4)。其确切的 v1 错误码由 golden 测试固定(F6)。逐 URL 问题不是错误:它们出现在 results 中,请求仍是 200。
Idempotency-Key
相册 PUT 接受它,但忽略(Q3)。带它的请求不会被拒绝,响应永远不带 Idempotent-Replay。rental-v1.yaml 在该接口上说明这一点。
IdempotencyUseCase.Execute 在一个事务中执行工作,重放时重新读取而不是重新执行。把这个 PUT 接入它,会让下载回到事务中(与 D40 矛盾),而且用同一个键重试永远不会重新下载失败的 URL。声明式 PUT 本身已可安全重复:再发一次就是重试。
multipart POST photos 和 POST proofs 保持 Slice 2 D36 的行为。
字段暴露(Q25)
| 字段 | 房东面板 | v1 密钥 API | 公开 JSON |
|---|---|---|---|
source | 是 | 是 | 否 |
source_url | 否 | 否 | 否 |
公开照片 JSON 不变,其 golden 测试保持原样。原始来源 URL 可能带有签名查询令牌;调用方已从 results 知道自己的 URL。
测试
| 内容 | 类型 | 失败条件 |
|---|---|---|
| 拒绝协议 | 单元 | 下载了 http:// |
| 非公网网段 | 单元,表驱动 | 任何私有、回环、链路本地、元数据、CGNAT、基准测试或 NAT64 IP 能连上 |
| IPv4 映射的 IPv6 | 单元 | ::ffff:169.254.169.254 能连上 |
| 混合 DNS 结果 | 单元,桩解析器 | 一个公网加一个私有结果没有被拒绝 |
| DNS 重绑定 | 单元,桩解析器 | 先返回公网、再连接私有地址成功 |
| 代理环境变量 | 单元 | 设置 HTTP_PROXY 后下载绕过固定拨号器 |
| 重定向到私有 IP | 单元 | 第一跳之后的某跳没检查 |
重定向到 http:// | 单元 | 跟随了非 HTTPS 跳转 |
虚假的 Content-Type | 单元 | 非图片仅凭头部通过 |
虚假的 Content-Length | 单元 | 缓冲了超过 5 MB |
| 条件请求 304 | 单元 | 304 重新下载或丢掉照片 |
| 同一 URL 哈希变化 | 单元 | 照片位置变了,或保留了旧键或旧尺寸 |
| CDN URL 轮换,字节相同 | 单元 | 照片被删除或重新插入,而不是重新绑定 |
| 自己的两个 URL 哈希相同 | 单元 | 靠后的 URL 保留了该行 |
| 保留的 URL 刷新失败 | 单元 | 行被删除,或缺少 photo_id |
| 请求校验 | 单元 | 接受了缺少 source、缺失/null 的 photos、重复 URL 或 2049 字符的 URL |
| 超时后清理 | 单元 | 因请求上下文被取消而跳过删除 |
| 字节已在相册中 | 集成 | 插入了第二行,或缺少 duplicate_image |
| 面板照片不受影响 | 集成 | 同步 PUT 删除了无主照片 |
| 两个来源共存 | 集成 | 一个 Source 的 PUT 删除了另一个的照片 |
| 空列表 | 集成 | [] 动到了此 Source 照片以外的东西 |
| 排序 | 集成 | 无主区块移动了 |
| 面板有主照片控件 | 渲染 | 有主照片提供了移动或设为封面,或缺少只读提示 |
有主照片 SetPosition | 集成 | 有主照片被移动,或无主照片被换进有主区块 |
| 上限检查先于下载 | 集成 | 被拒绝的 PUT 仍然下载,或返回的不是现有的 400 |
| 并发上传和 PUT | 集成 | 相册最终超过 10 张照片 |
| 部分失败 | 集成 | 一个失效 URL 让整个相册丢失,或响应不是 200 |
| 结果格式 | 集成 | results 不是每个 URL 一条、按请求顺序 |
| 证明内容不可访问 | 集成 | 任何 v1 路由返回了证明字节 |
| 证明上限 | 集成 | 第 11 份证明被验证,或在提前检查能看到上限时其字节仍被存储,无论经面板还是 API |
PUT 上的 Idempotency-Key | 集成 | 重复的键触发重放而不是重新执行,或该头被拒绝 |
| 公开 JSON 格式 | golden | 照片字段被改名或缺失,或出现 source / source_url |
| 上限错误码 | golden | v1 上限错误码改变 |
集成测试沿用现有做法:pg-test 在 :55432,迁移从没有 .env 的目录运行,因为 backend/go/.env 指向 UAT。
任务
| # | 任务 | 验证 |
|---|---|---|
| 1 | 重新记录租赁测试基线 | 记下数字 |
| 2 | 迁移:照片列 | 迁移测试 |
| 3 | PhotoRepository 的 Delete、UpdatePositions、UpdateContent(含宽高) | 单元 |
| 4 | PhotoStore.Remove 包装和尽力清理辅助函数(WithoutCancel) | 单元 |
| 5 | 安全下载器:仅公网固定连接、Proxy: nil、重定向、魔数、大小截断 | 单元 |
| 6 | 条件请求和哈希比较 | 单元 |
| 7 | 相册对账用例:规划、下载、加锁应用 | 单元 |
| 8 | PUT photos 处理器、校验和响应格式 | 集成 |
| 9 | Upload 获取房源锁;SetPosition 拒绝有主照片和移入有主区块;v1 中的 multipart POST photos | 集成 |
| 10 | 证明上限:提前检查加加锁验证步骤中的检查;v1 中的证明 POST 和 GET | 集成 |
| 11 | rental-v1.yaml(状态枚举、字段暴露、PUT 忽略 Idempotency-Key)和 golden 重新固定 | golden |
| 12 | 面板:有主照片隐藏移动和封面控件,显示翻译后的只读提示 | 渲染测试 |
| 13 | 端到端双来源相册 | 集成 |
不在范围内
- 预签名上传和 CLI(Slice 5)。
- 对外 webhook(Slice 4)。
- 跨房源对象共享(已否决,D42)。
- 修复面板
SetPosition竞态(既有问题,已标记)。 - 孤儿对象清扫器(后续,Q18)。
- 按 URL 计算限流成本(Q26)。
- "已知重复"记录(F1)。
- multipart 的
source(Q20)。
未决风险
| 风险 | 缓解 |
|---|---|
| 主机名在连接时解析到不同地址导致 SSRF | 固定连接到已检查的公网 IP、Proxy: nil、每一跳重定向重新检查;重绑定和代理测试把关 |
| 慢速来源让请求一直挂着 | 每个 URL 10 秒、下载预算 20 秒、同时 5 个;下载不持有锁 |
| 同步悄悄删除房东自己的照片 | D38 把删除限定在调用方自己的 Source;集成测试断言无主照片保留 |
| CDN 每晚轮换签名 URL | 按哈希重新绑定,保留照片(Q11) |
| 通过 multipart 上传的 API 照片永远无法被上传者删除 | 接受。它是无主的,所以任何密钥都删不掉,面板目前也没有照片删除。面板删除是单独的功能 |
| 重复 URL 每次同步都完整下载 | 接受,受 10 张照片上限约束(F1) |
| 崩溃或删除失败后的孤儿对象 | 记日志;清理任务作为后续(Q18) |
| 对外下载被用来攻击第三方 | 现有按密钥每小时限流 × 10 个 URL 上限(Q26) |
| 泄露的密钥外泄身份文件 | 任何 v1 路由都不返回证明内容(D43) |
| 泄露的密钥用证明塞满私有桶 | 每个房源 10 份证明上限(Q16) |
| 房东触及终身证明上限 | 接受;目前没有证明删除,由管理员处理 |