From d1e42ea18ae7b0df04a97ec8dd270ad080ee2bf6 Mon Sep 17 00:00:00 2001 From: toom1996 <23cm.cn@gmail.com> Date: Mon, 21 Sep 2026 15:56:29 +0800 Subject: [PATCH] update --- .../2026-09-20-ingest-idempotency-design.md | 32 +- .../2026-09-21-duplicate-review-design.md | 274 ++++++++++++++++++ .../2026-09-21-street-main-detail-design.md | 161 ++++++++++ internal/handler/backstage_handler.go | 1 + internal/handler/backstage_handler_test.go | 25 ++ 5 files changed, 472 insertions(+), 21 deletions(-) create mode 100644 docs/superpowers/specs/2026-09-21-duplicate-review-design.md create mode 100644 docs/superpowers/specs/2026-09-21-street-main-detail-design.md create mode 100644 internal/handler/backstage_handler_test.go diff --git a/docs/superpowers/specs/2026-09-20-ingest-idempotency-design.md b/docs/superpowers/specs/2026-09-20-ingest-idempotency-design.md index e53e9b1..9bd1e2a 100644 --- a/docs/superpowers/specs/2026-09-20-ingest-idempotency-design.md +++ b/docs/superpowers/specs/2026-09-20-ingest-idempotency-design.md @@ -181,28 +181,18 @@ SourceDraftExists(ctx context.Context, kind, source, sourceURL string) (bool, er **冲突时无需回滚已上传的图**：两张草稿的图片 URL 完全相同，sha1 内容寻址会推出同一个对象 key，属覆盖写，不产生孤儿文件。此点须在代码注释中写明，避免后来人误加 `cleanupUploads`。 -### 3.6 街拍实体键引入月份 +### 3.6 ~~街拍实体键引入月份~~（已作废） -街拍实体键由 `(city, year)` 改为 `(city, year, month)`。**该键共有 4 处落点，必须同时修改**，否则晋升与去重口径不一致会导致数据撕裂。 - -| # | 落点 | 改动 | -| --- | --- | --- | -| 1 | `ingest_repository.StreetSnapIDByEntity` | 增加 `month` 参数，查询加 `AND month = ?`；接口注释同步 | -| 2 | `ingest_service.processStreet` | 调用点传 `p.Month`；日志补上 month | -| 3 | `review_repository.SaveStreetSnapFromDraft` | 正式行查找 `WHERE city = ? AND year = ?` 增加 month | -| 4 | `review_repository.streetApprovedSiblingImages` | 兄弟草稿聚合查询增加 month 条件 | - -**第 4 处是最容易漏、后果最脏的一处**：它是「同 city+year 已 approved 的其他街拍草稿图」的聚合查询。若只改第 3 处而不改第 4 处，会出现**「正式行按月分开了、图片却跨月混在一起」**——2 月 Copenhagen 专辑里混进 8 月的图。晋升与去重口径必须完全一致。 - -其余改动： - -- **spider**：`Year` 与 `Month` 均取抓取时刻 `time.Now()`；删除 `(*TheImpressionSpider).parseYear`（失去调用方）。`yearRe` 被 `vogue.go` 共用，**保留**。 -- **写草稿**：`processStreet` 填 `Month: p.Month`。 -- **晋升写正式表**：`SaveStreetSnapFromDraft` 的 `common` map 增加 `"month": draft.Month`。 -- **后台可编辑**：`streetDraftEditable` 白名单放行 `month`；street 模块的 `Fields` 增加 `{month, 月份, number}`（与 `year` / `city` 一致——三者本就是键的一部分，后两者现已可编辑）；列表卡片副标题由 `city` 改为 `city · YYYY-MM`。 -- **公开 API 不动**：`PublicStreetSnap` / `PublicStreetSnapDetail` 目前连 `year`、`city` 都未暴露，加 `month` 无意义。前端确有需要时再单独加字段。 - -**残留代价（明确接受）**：同城、同年、同月内的不同文章，仍会在「首条晋升之后」被判重跳过。但同一批抓取会一起进草稿、并在晋升时聚合，实际影响很小。这是键粒度换来的必然取舍，「爬过即终态」的既定语义不变。 +> **本节已作废（2026-09-21）**，由 `2026-09-21-duplicate-review-design.md` §3.7 取代。 +> +> 原设计把街拍实体键改为 `(city, year, month)`（同城同月自动收敛成一张专辑）。用户随后取消了「按月区分」与「合并成一张专辑」两项需求，改为**一篇文章一张专辑**，实体键变为 `(source, source_url)`。 +> +> 影响： +> +> - 本节描述的全部改动**不再执行**（原实现计划的任务 6 已删除）。 +> - 但 §3.1（契约新增 `source` / `source_url`）**仍然有效、且更关键**——这两个字段现在直接充当街拍实体键。 +> - `Month` 字段不再需要（其唯一用途是月度分组）：`month` 列、spider 的 `Month` 填充、`streetDraftEditable` 放行 `month`、列表副标题加月份等一并取消。 +> - 街拍 `street_snaps` 正式表需新增 `source` / `source_url` 两列，见新规格 §3.7。 ### 3.7 明确不动的部分 diff --git a/docs/superpowers/specs/2026-09-21-duplicate-review-design.md b/docs/superpowers/specs/2026-09-21-duplicate-review-design.md new file mode 100644 index 0000000..72608d8 --- /dev/null +++ b/docs/superpowers/specs/2026-09-21-duplicate-review-design.md @@ -0,0 +1,274 @@ +# 重复检测与审核展示设计（含街拍实体键改为按文章） + +- 日期：2026-09-21 +- 状态：设计已确认，待用户审阅规格 +- 范围： + 1. 「重复图对」表 `image_duplicates` + 审核页展示（列表给数量、详情给标记） + 2. 街拍实体键由 `(city, year)` 改为 `(source, source_url)`——一篇文章一张专辑 +- **不含**：街拍主副图（已确认设计与交互，另立规格） + +--- + +## 1. 背景 + +### 1.1 现有的 `is_duplicate` / `dup_of` 为什么不能直接用 + +两者在入库时写入，但有两个硬缺陷： + +**缺陷一：`dup_of` 是「不带表名的裸行 id」，无法反查归属。** + +```go +DupOf: strconv.FormatUint(uint64(dupID), 10) +``` + +`FindNearDuplicateImage` 按「草稿表 → 正式表」顺序遍历，**命中哪张表就返回哪张表的 id**。拿到 `dup_of=264`，无法判断它是 `street_snap_draft_images` 的 264 还是 `street_snap_images` 的 264，更推不出它属于哪篇草稿。 + +**缺陷二：篇内重复完全检不到（结构性缺陷）。** + +草稿图片是**全部下载完之后一次性批量插入**的（`CreateStreetSnapDraftImages` 在 `fetchImages` 返回后才调用），而 `dedupImage` 是每张图下载后立刻查库——**那一刻本篇的行还不存在**，所以同一篇文章内部的近似重复根本没有比较对象。 + +**实测证据**（当前 5 篇街拍，1052 张图）： + +| 指标 | 值 | +| --- | --- | +| `is_duplicate = 1` 的行数 | **3** | +| 实际 hamming ≤ 10 的对数 | **10**（其中**篇内 6 对，一条都没标**） | + +篇内漏标的典型：行 id `1150`/`1151`（同一篇内前后相邻的两张，连拍），hamming = 5——这类最该被剔除的，入库标记完全看不见。 + +### 1.2 阈值实测（`phash.DefaultThreshold = 10` 明显过松） + +对 1052 张图做两两汉明距离统计（`L2² == 汉明距离`）： + +| 阈值 | 命中对数 | 效果 | +| --- | --- | --- | +| ≤4 | **0** | — | +| ≤5 | 1 | 唯一的真候选（行 1150/1151，篇内相邻） | +| ≤8 | 1 | 与 ≤5 相同 | +| ≤9 | 4 | 开始混入噪声 | +| **≤10（现值）** | **10** | 混入 9 对噪声 | + +距离分布（低尾）： + +``` +hamming | pairs + 5 | 1 + 9 | 3 + 10 | 6 + 11 | 7 + 12 | 13 + 13 | 40 + 14 | 85 + ... +平均 31.45 ≈ 32（64 位随机期望） +``` + +**关键判定**：9、10、11 三档的计数（3、6、7）平滑接进 12、13、40、85……**没有分离的簇**，说明 9~11 就是噪声分布的肩部。用户实际查看后确认：hamming = 10 的跨篇对（行 264 ↔ 1021）**目视完全不同**，是假阳性。 + +**根因**：dHash 只有 9×8 采样格、64 位，而这批图全是「竖构图的街头全身人像」，整体构图高度雷同，描述子被构图主导、内容差异被压缩。（描述子升级为更大网格 dHash / pHash-DCT 的方案已评估，另立规格处理。） + +--- + +## 2. 决策记录 + +| 决策点 | 结论 | 理由 | +| --- | --- | --- | +| 重复检测机制 | **读时预计算并落库到 `image_duplicates` 表**，不依赖 `is_duplicate`/`dup_of` | 现有字段无法反查归属且漏篇内重复（见 1.1） | +| 计算时机 | **草稿图片写完之后的 worker 里** | 入库每张图时本篇行还不存在，篇内比不到（见 1.1 缺陷二） | +| 计算算法 | 对新草稿每张图，用现成的 `_phash_hnsw` 索引做 LATERAL 近邻查询 | 复杂度 O(新增图数 × log N)，优于全表 O(n²) 自连接 | +| 比对范围 | **同 kind 的「草稿表 + 正式表」都比** | 用户选定：要能知道「这张图已经上线过了」 | +| 晋升镜像 | **跳过 `image` 相同的对** | 草稿晋升后同一张图在草稿表与正式表各存一行、phash 相同（hamming 0），那是镜像不是重复 | +| 阈值 | **4** | 用户指定。写入时应用（见 3.3） | +| 是否存汉明距离 | **不存** | 用户指定。代价：改阈值需重跑配对计算——但**只读库里的 phash，不需重新下图**，比换描述子便宜一个量级 | +| 列表页展示 | **不展示**（用户取消了「列表显示重复数量」这一需求） | 用户指定 | +| 详情页展示 | 给重复图**打标记** + 显示对手属于哪篇文章 | 用户指定 | +| 街拍实体键 | **`(source, source_url)`**——一篇文章一张专辑 | 用户指定；月/年不再参与区分 | +| 合并成一张专辑 | **取消** | 用户取消 | +| `month` 进实体键 | **取消** | 用户取消按月区分 | + +--- + +## 3. 详细设计 + +### 3.1 新表 `image_duplicates` + +```sql +CREATE TABLE IF NOT EXISTS image_duplicates ( + id BIGSERIAL PRIMARY KEY, + kind varchar(16) NOT NULL, -- runway | street + -- 本方（「这张图」） + image_id integer NOT NULL, -- 图片行 id（在 *_draft_images 或 *_images 中，由 owner_kind 决定） + owner_kind varchar(8) NOT NULL, -- draft | official + owner_id integer NOT NULL, -- 草稿 id 或正式表主键（brand_runways.id / street_snaps.id） + -- 对手（「和它重复的那张」） + peer_image_id integer NOT NULL, + peer_owner_kind varchar(8) NOT NULL, + peer_owner_id integer NOT NULL, + created_at integer NOT NULL DEFAULT 0 +); + +CREATE UNIQUE INDEX IF NOT EXISTS uq_image_dups_pair + ON image_duplicates (kind, owner_kind, image_id, peer_owner_kind, peer_image_id); +CREATE INDEX IF NOT EXISTS idx_image_dups_owner + ON image_duplicates (kind, owner_kind, owner_id); +``` + +唯一索引保证重复计算幂等；辅助索引服务读侧（按草稿批量取数）。 + +**不冗余存对手的标题**：读时按 `peer_owner_kind` join 对应表取（草稿 → `*_drafts.title_en` / `.title`；正式 → `brand_runways.title_en` / `street_snaps.title`）。避免标题被改后出现陈旧副本。 + +建表放在 `internal/database/postgres.go` 的 `EnsureDedupSchema`（该函数本就是「`AutoMigrate` 之外的索引与表补充」的既定位置，且全部幂等）。 + +### 3.2 写入时机与算法 + +**时机**：`processRunway` / `processStreet` 内，`Create*DraftImages` **成功之后**。失败仅记录日志、**不影响任务状态**（重复信息是审核辅助，不该让入库任务失败）；漏算可由回填命令补齐（3.6）。 + +**算法**：对本草稿的每一张图，用 `_phash_hnsw` 索引（`vector_l2_ops`）在对手池中取近邻。对手池 = 同 kind 的「草稿表 UNION 正式表」。 + +``` +L2 阈值 = sqrt(4) = 2.0 -- 与 phash 口径一致：phash 为 {0,1}^64，L2² == 汉明距离 +跳过条件：对手行的 image 与本方相同（晋升镜像） +``` + +结果以 `INSERT ... ON CONFLICT (kind, owner_kind, image_id, peer_owner_kind, peer_image_id) DO NOTHING` 入库——表内不存汉明距离，故命中已存在的对时**无需更新**，DO NOTHING 即幂等。 + +### 3.3 阈值 + +`4`，作为**配置项**（不入库汉明距离，故阈值在写入时生效）： + +``` +dup.hamming_threshold: 4 +``` + +**改阈值的代价**：需重跑配对计算。因为只读库里的 `phash`、不需要重新下载图片，这是一条纯数据库批处理（3.6 的回填命令可直接复用）。 + +### 3.4 读侧：审核列表 —— **不做** + +用户已取消「审核列表显示重复数量」这一需求：**列表页不加任何重复相关列**，`DraftCard` 也不增加字段。 + +因此 `image_duplicates` 的读侧只有**一处**消费方——审核详情页（见 3.5）。列表页保持原样。 + +> 说明：曾实现过一版读时自连接 + 列表列的过渡方案，因该需求取消而**整体移除**。详情页标记改由本规格的 `image_duplicates` 表实现。 + +### 3.5 读侧：审核详情 + +`DraftImageRef` 增加一个字段： + +```go +// DupPeers 与该图重复的对手；为空表示不重复。 +// 对手可能多于一个（同一张图在多篇文章里都出现过），故用切片而非 bool。 +type DupPeer struct { + OwnerKind string // draft | official + Title string // 对手所属文章 / 专辑标题 +} + +type DraftImageRef struct { + // ...既有字段... + DupPeers []DupPeer +} +``` + +「是否重复」直接由 `len(DupPeers) > 0` 判定，**不单设 bool**（避免两者不一致）。 + +详情模板对有对手的图加角标（复用现有 `.badge` 视觉语言，新增 `.badge.dup`），角标含对手文章标题；对手多于一个时全部列出。 + +对手文章标题的取法：按 `peer_owner_kind` 分别 join，读时组装。 + +### 3.6 存量回填 + +现有需回填规模： + +| 表 | 总行 | 存活行 | +| --- | --- | --- | +| `brand_runway_images` | 672 | 556 | +| `brand_runway_draft_images` | 556 | 556 | +| `street_snap_images` | 0 | 0 | +| `street_snap_draft_images` | 1052 | 1052 | + +去重后 **1608 张不同图**（走秀 556 张在两表重复出现）。 + +提供一个**可中断、可重入**的回填命令：按 kind 与 owner 分批处理，重复执行不产生重复行（靠唯一索引），支持从任意位置续跑。 + +### 3.7 街拍实体键改为按文章 + +街拍实体键由 `(city, year)` 改为 **`(source, source_url)`**，即一篇文章一张专辑。落点与 `2026-09-20-ingest-idempotency-design.md` §3.6 所列的 4 处一致，但键的构成改变： + +| # | 落点 | 改动 | +| --- | --- | --- | +| 1 | `ingest_repository.StreetSnapIDByEntity` | 改为按 `(source, source_url)` 查正式表 | +| 2 | `ingest_service.processStreet` | 调用点同步 | +| 3 | `review_repository.SaveStreetSnapFromDraft` | 正式行查找改为按 `(source, source_url)` | +| 4 | `review_repository.streetApprovedSiblingImages` | **对街拍变为空操作**（per-article 后不存在「兄弟草稿」） | + +⚠️ `street_snaps` 正式表需新增 `source` / `source_url` 两列（与草稿表同构），否则晋升时无法按该键 upsert。同时补一个与草稿表同形的**部分唯一索引**，从数据库层面保证同一篇文章不会产生两张正式专辑： + +```sql +CREATE UNIQUE INDEX IF NOT EXISTS uq_ss_source + ON street_snaps (source, source_url) WHERE source_url <> ''; +``` + +必须是部分索引，理由与 `2026-09-20-ingest-idempotency-design.md` §3.2 相同：存量行 `source_url` 为空串，全量唯一索引会因大量 `('','')` 冲突导致**建索引失败 → 启动崩溃**。 + +**关于 `month` 与 `year`**（用户只说「不按月区分」，未明确字段去留，此处为裁决）： + +- **不做 `month`**：它此前的唯一用途是月度分组，该需求已取消（YAGNI）。 +- **保留「year 取抓取年份」**（spider 侧 2 行改动）：`year=0` 是错误数据，且公开 API 支持按 year 过滤，`year=0` 的条目无法被正常筛选。注意实体键改为按文章后，`year=0` 已**不再造成静默丢数据**（原 `(city, 0)` 吸附桶问题随键变更消失）。 + +### 3.8 明确不动的部分 + +- `is_duplicate` / `dup_of` 两列**保留写入但不读**（纯历史留痕）。不删列，避免破坏性迁移。 +- 入库时的 `dedupImage` 逻辑不变。 +- runway 的 `(brand_id, season_code, collection_type)` 实体键与 sibling union **不变**（多来源聚合对走秀仍有意）。 + +--- + +## 4. 影响面 + +``` +internal/model/image_duplicate.go 新增（模型） +internal/database/postgres.go EnsureDedupSchema 建表与索引 +internal/repository/dup_repository.go 新增：写入 + 读取 + 回填 +internal/repository/ingest_repository.go StreetSnapIDByEntity 改键 +internal/repository/review_repository.go SaveStreetSnapFromDraft / streetApprovedSiblingImages 改键 +internal/service/ingest_service.go 草稿写入后触发配对计算；processStreet 调用点 +internal/service/review_service.go DraftImageRef 加重复对手字段（仅详情用） +internal/handler/backstage_handler.go 详情页加重复标记 +internal/model/street_snap.go +source / +source_url +cmd/dupbackfill（新） 存量回填命令 +configs/config.yml +dup.hamming_threshold +../spider/internal/spider/theimpression.go year 改取抓取年份 +``` + +--- + +## 5. 测试 + +### 5.1 单元测试（不依赖数据库） + +- 配对写入会**跳过 `image` 相同的对**（晋升镜像）。 +- 详情渲染：重复图被标记，并显示对手文章标题；无对手的图**不显示标记**。 + +### 5.2 集成测试（需 PostgreSQL） + +- 唯一索引生效：同一对重复写入只留一行。 +- 阈值语义：hamming 恰为 4 的对入表、为 5 的不入表。 +- 回填命令可重入：连跑两次行数不变。 +- 街拍实体键：不同 `source_url` 的两篇文章晋升后是**两张**正式专辑；相同 `source_url` 是**一张**。 + +--- + +## 6. 对既有规格与计划的影响 + +| 对象 | 影响 | +| --- | --- | +| `2026-09-20-ingest-idempotency-design.md` §3.6 | **作废**（月/年进键的部分）。§3.1–3.5（来源幂等）**仍然有效**，且其 `source` / `source_url` 字段正好成为街拍新实体键 | +| `2026-09-20-ingest-idempotency.md`（实现计划）**任务 6** | **删除**（实体键改动移入本规格） | +| 同上，任务 5（spider 填 source/source_url） | **保留**，但 `Month` 字段的填充与 `parseYear` 删除需按本规格 §3.7 调整 | + +--- + +## 7. 待确认 / 开放问题 + +1. **阈值 4 会让当前数据命中 0 对**，审核页该列为空。用户已指定 4；因它是配置项，改成 5 只改一行配置 + 重跑回填。 +2. 街拍主副图（含公开 API 分组化）**另立规格**，不在本文档范围。 +3. `image_duplicates` 的生命周期：草稿被软删 / 单图被审核删除后，表中会残留指向失效行 id 的记录。当前设计**读时靠 join `is_deleted = 0` 过滤**，不做主动清理；若日后数据量增大再考虑级联清理。 diff --git a/docs/superpowers/specs/2026-09-21-street-main-detail-design.md b/docs/superpowers/specs/2026-09-21-street-main-detail-design.md new file mode 100644 index 0000000..18011a2 --- /dev/null +++ b/docs/superpowers/specs/2026-09-21-street-main-detail-design.md @@ -0,0 +1,161 @@ +# 街拍主副图设计 + +- 日期：2026-09-21 +- 状态：设计已确认，待用户审阅规格 +- 范围：街拍图增加「主图 / 副图」分组——审核页人工指定、详情页按组折叠、公开 API 保守扩展 +- **不含**：重复检测（见 `2026-09-21-duplicate-review-design.md`）、来源幂等（见 `2026-09-20-ingest-idempotency-design.md`） + +--- + +## 1. 背景与目标 + +**现状**：街拍图是扁平列表。`street_snap_draft_images` / `street_snap_images` 都**没有** `is_detail` 之类字段，而走秀侧（`brand_runway_draft_images` / `brand_runway_images`）**已经有**「主图 + 细节图」模型（`is_detail` + `look_index`）。 + +**动机**（用户原话）：一个人可能被拍多张，平铺会很占位置。 + +**为什么只能人工指定**：源站不提供任何人物/分组信息。实测 theImpression 一篇文章： + +| 项 | 结果 | +| --- | --- | +| `
` 数量 | 167（就是街拍图本身） | +| `
` 数量 | **0** | +| 街拍图的 `alt` | **全空**（`alt=""`） | +| 非空 `alt` | 仅 11 个，且全是侧栏广告与无关标题（如 `Mugler Fall 2026 Ad Campaign`） | + +（文件名含摄影师帧号如 `milano-str-f26-0007-1`，帧号接近可能是连拍，但对「同一个人不同时间被拍」无效，不采用。） + +--- + +## 2. 决策记录 + +| 决策点 | 结论 | 理由 | +| --- | --- | --- | +| 主副如何确定 | **人工在审核页指定** | 源站无人物信息；用户选择纯人工 | +| 交互方式 | **不引入 JavaScript**：两阶段「先选定主图 → 勾选图片并入」+ 每张图的「并入上一张」快捷 | 后台目前**零 JS**（全仓 `internal/handler` 无 `