fix(publish): 最终审查修复波——迁移索引口径 / 入库计数 / 仓储证据

C1（关键）：2026-09-22-03 的街拍实体键索引改用最终表达式
(city, year, COALESCE(title, ''))，与体检及 StreetSnapEntityState 口径一致。
此前索引按 (city, year) 比体检更窄，同城同年多专题的合法数据会通过体检、
再由索引抛原生 23505；04 退化为幂等兜底并在注释说明真正常态由 03 承载。
新增 db/migrations/README.md，写清迁移链执行顺序与各步前提/不可逆点。

I1：processRunway 的 image_count 改为按实际落库主图行数（countMainImages），
不再用 len(p.Looks)（空主图 / sha1 重复会被跳过，导致计数偏大且不再自愈）。
补 service 单测与「入库后 image_count == 存活主图行数」的 DB 断言。

I2：三个迁移文件不再把已删除的一次性搬迁脚本写成硬前置，改为写明取回方式
（git show c4bafc5:scripts/migrate_single_table/main.go，并须在旧代码树上运行）。

I3：新增 SetRecordStatus / SetStreetRecordStatus 仓储集成测试：
pending 经仓储通过后在公开视图可见、驳回后不可见、不存在的 id 返回 ErrNotFound。

Minor：修正锁不住口径的走秀 image_count 测试（改为删主图、留细节图）；
修正去重注释与事实不符（含 FindNearDuplicateImage 注释）；
ListRecords / ListStreetRecords 改用 Scope 杜绝 Count 后复用 *gorm.DB；
dbtool 视图改 CREATE OR REPLACE 并重跑 dump（仍 4 视图、无草稿表）；
删除挂在 Popular 上的「IDs 返回…」注释；README 改为单表 + status 现状；
SetRecordStatus 注释写明有意不校验前置状态；规格补两条已知不一致。

db/migrations/2026-09-22-01-single-table-publish.sql

@@ -1,7 +1,9 @@
 -- 单表发布模型（方案 2）：取消草稿表，审核态由 status 承载，公开读走只读视图。
 --
 -- 本文件只做三件事：加列 / 存量行置已发布 / 建视图。幂等，可重复执行。
--- 数据搬迁见 scripts/migrate_single_table；删草稿表见 2026-09-22-02-drop-draft-tables.sql。
+-- 数据搬迁由一次性脚本 scripts/migrate_single_table/main.go 完成。该脚本已随本次改造从工作树删除
+--（它 import 已删除的草稿模型，无法在改造后的代码树上编译）；取回方式与执行顺序见本目录 README.md。
+-- 删草稿表见 2026-09-22-02-drop-draft-tables.sql。
 
 -- 1) 正式表补审核态与溯源列。默认 'pending' 是刻意的（fail-closed）：
 --    任何漏赋值的行默认不可见，而不是意外对外发布。
@@ -19,7 +21,7 @@ ALTER TABLE street_snaps
 
 -- 2) 存量行置已发布**不在本文件里**：它是数据变更且只能执行一次，见同目录
 --    2026-09-22-01b-publish-existing-rows.sql。
---    为什么必须拆开：数据搬迁（scripts/migrate_single_table）会把 pending 草稿连原 created_at
+--    为什么必须拆开：数据搬迁（scripts/migrate_single_table/main.go）会把 pending 草稿连原 created_at
 --    一起搬进正式表；若本文件含那条 UPDATE 且被重复执行（测试每次都会跑），
 --    这些待审内容会被误刷成已发布 —— 恰好是本设计要防的泄漏。
 

db/migrations/2026-09-22-01b-publish-existing-rows.sql

@@ -1,6 +1,8 @@
 -- 一次性数据迁移：把存量正式行视为已发布。
 --
--- ⚠️ 只执行一次；必须在部署本计划的新代码之前、且在 scripts/migrate_single_table 之前执行。
+-- ⚠️ 只执行一次；必须在部署本计划的新代码之前、且在一次性搬迁脚本
+--    scripts/migrate_single_table/main.go 之前执行。
+--    该脚本已随本次改造从工作树删除（它 import 已删除的草稿模型）；取回方式见本目录 README.md。
 -- 为什么单独成文件而不放进可重复执行的 2026-09-22-01：
 --   数据搬迁会把 pending 草稿连同旧的 created_at 一起搬进正式表；
 --   若这条 UPDATE 可被重复执行（集成测试每次都会跑 01 号文件），

db/migrations/2026-09-22-02-drop-draft-tables.sql

@@ -1,6 +1,7 @@
 -- 单表发布模型收尾：删除 4 张草稿表。
 --
--- ⚠️ 执行前置条件：scripts/migrate_single_table 已跑完且校验通过（否则草稿数据会丢失）。
+-- ⚠️ 执行前置条件：一次性搬迁脚本 scripts/migrate_single_table/main.go（已随本次改造从工作树删除，
+--    取回方式见本目录 README.md）已跑完且校验通过 —— 否则草稿数据会丢失。
 -- 本迁移不可逆：执行前请确认 db/backups 有可用备份。
 
 DROP TABLE IF EXISTS brand_runway_draft_images;

db/migrations/2026-09-22-03-entity-key-unique.sql

@@ -35,5 +35,13 @@ END $$;
 CREATE UNIQUE INDEX IF NOT EXISTS uq_br_entity
   ON brand_runways (brand_id, season_code, collection_type) WHERE is_deleted = 0;
 
+-- 索引表达式必须与上面的体检、以及 StreetSnapEntityState 的查重口径**逐字一致**：
+-- (city, year, COALESCE(title, ''))。早期版本这里误建成 (city, year) —— 比体检更窄，
+-- 于是体检放行「同城同年不同专题」的合法数据后，建索引才抛原生 23505
+-- （could not create unique index ... duplicate key）。COALESCE(title, '') 的取舍见 2026-09-22-04。
+--
+-- ⚠️ CREATE UNIQUE INDEX IF NOT EXISTS 只检查**索引名**是否存在：若库里已有一个同名的
+-- 旧 (city, year) 索引，本句会静默跳过、留下错误结构（这正是它一度掩盖问题的原因）。
+-- 纠正这类存量库由 2026-09-22-04 承担；全新库 / 重复执行由本文件承载最终表达式。
 CREATE UNIQUE INDEX IF NOT EXISTS uq_ss_entity
-  ON street_snaps (city, year) WHERE is_deleted = 0;
+  ON street_snaps (city, year, COALESCE(title, '')) WHERE is_deleted = 0;

db/migrations/2026-09-22-04-street-entity-key-title.sql

@@ -1,5 +1,11 @@
 -- 街拍实体键细化：由 (city, year) 改为 (city, year, title)。
 --
+-- ⚠️ 本文件是**幂等兜底**，最终表达式的常态承载在 2026-09-22-03（它已直接建同一表达式索引）。
+-- 之所以必须保留：03 的 `CREATE UNIQUE INDEX IF NOT EXISTS` 只按**索引名**判断存在性，
+-- 遇到「同名但口径更窄的旧 (city, year) 索引」会静默跳过、留下错误结构 ——
+-- 只有本文件的 `DROP INDEX IF EXISTS` + 重建能纠正这类存量库。
+-- 全新库上重跑本文件也只是 DROP 后原样重建，幂等无害。
+--
 -- 背景：同城同年可能有多个专题（如 London 2027 Day 2 / Day 3），原键把它们判为同一实体，
 -- 导致唯一索引不允许共存、且入库查重把第二个专题当成重复直接放弃。
 --

db/migrations/README.md

@@ -0,0 +1,55 @@
+# 数据库迁移
+
+本目录的 `.sql` 是**手工一次性迁移**（服务启动不做 DDL，结构由 `dbtool` 导出的 `db_dump.sql` 维护）。
+命名规则 `日期-序号-主题.sql`，**按文件名顺序执行**。
+
+- 全新库：直接用 `db_dump.sql` 建库（见根目录 `README.md`「数据库」一节），**不需要**跑这些迁移。
+- 存量库升级：按下文顺序执行；大多语句幂等，但**数据变更类不可重放**（见各步说明）。
+
+---
+
+## 一、2026-09-21 系列（街拍主副图 / 重复检测 / 来源幂等）
+
+| 顺序 | 文件 | 说明 |
+| --- | --- | --- |
+| 1 | `2026-09-21-01-street-main-detail.sql` | 草稿表与正式图片表加 `is_detail` / `parent_image_id`。全 `IF NOT EXISTS`，幂等。 |
+| 2 | `2026-09-21-02-duplicate-review.sql` | 新建 `image_duplicates`，街拍正式表加 `source` / `source_url` 及部分唯一索引 `uq_ss_source`。幂等。 |
+| 3 | `2026-09-21-03-ingest-source-idempotency.sql` | 两张**草稿表**加 `source` / `source_url` 及部分唯一索引。幂等。这些列会随 2026-09-22-02 删草稿表一并消失。 |
+
+这三步属于更早的改造；对已经过它们的库重放无害。
+
+---
+
+## 二、2026-09-22 单表发布（草稿表 → 单表 + `status` + 公开只读视图）
+
+**执行顺序：`01 → 01b → 搬迁脚本 → 02 → 03 → 04`**
+
+| 顺序 | 对象 | 前提 / 幂等 / 不可逆点 |
+| --- | --- | --- |
+| 1 | `2026-09-22-01-single-table-publish.sql` | 给 `brand_runways` / `street_snaps` 加 `status` 等列、建状态索引、建 4 个 `public_*` 视图。**幂等**，可重复执行（集成测试每次都会跑它）。 |
+| 2 | `2026-09-22-01b-publish-existing-rows.sql` | 把存量正式行置 `published`。**只能执行一次**；且必须在新代码部署**之前**、搬迁脚本**之前**执行。理由：搬迁会把 pending 草稿连同旧 `created_at` 一起搬进来，若这条 UPDATE 可重放，待审内容会被误刷成已发布（本设计要防的就是这个泄漏）。 |
+| 3 | 搬迁脚本 `<见下>` | 把草稿表数据搬进正式表。**一次性**；先 `-dry-run` + 守恒校验，**校验不过绝不进入第 4 步**。 |
+| 4 | `2026-09-22-02-drop-draft-tables.sql` | 删除 4 张草稿表。**不可逆**；前提是第 3 步校验通过，且 `db/backups/` 有可用备份。 |
+| 5 | `2026-09-22-03-entity-key-unique.sql` | 实体键部分唯一索引 `uq_br_entity` / `uq_ss_entity`（街拍为最终表达式 `(city, year, COALESCE(title,''))`）。**幂等**；建索引前先体检，有重复就报可读错误而非原生 23505。 |
+| 6 | `2026-09-22-04-street-entity-key-title.sql` | 街拍索引的**幂等兜底**：`DROP INDEX IF EXISTS uq_ss_entity` 后按最终表达式重建。常态由 03 承载；本文件专治「库里已有同名旧 `(city, year)` 索引、03 因 `IF NOT EXISTS` 静默跳过」的存量库。 |
+
+### 搬迁脚本的取回方式
+
+`scripts/migrate_single_table/main.go` 是一次性工具，已随本次改造从工作树删除（它 `import` 了同批删除的
+草稿模型，无法在改造后的代码树上编译）。如需重放，从**它被删除前的最后一个提交**取回：
+
+```bash
+# 取回脚本源码（c4bafc5 是删除提交 d68a570 的父提交，即脚本最后一次存在的版本）
+git show c4bafc5:scripts/migrate_single_table/main.go
+```
+
+注意：脚本依赖草稿模型，必须在该提交（或更早）的代码树上运行，**不能**直接放进当前树。
+真正需要重放时，建议 `git worktree add ../old c4bafc5` 切出旧树再跑。
+
+### 索引口径的一个坑
+
+`CREATE UNIQUE INDEX IF NOT EXISTS` 只按**索引名**判断存在性，不比对表达式。因此：
+
+- 若库里已有同名但口径更窄的旧 `uq_ss_entity (city, year)`，03 会静默跳过、留下错误结构；
+  这时必须跑 04 纠正（04 的 `DROP` 正是为此）。
+- 反过来，若只跑 03 而库里已存在正确的同名索引，跳过是无害的。