tamakyi
770e752a7a
R2 上的图怎么救：库里的行没了就只剩桶里有那些键，不列桶无从得知它们叫什么。
给 internal/media 加了 ListObjects（ListObjectsV2 + SigV4 + 自动翻页 + XML 解析）：
- 路径式访问、请求只到桶；查询串必须**先百分号编码再签名**（canonicalQuery 按原样取
RawQuery，两边得是同一份字节，prefix 里的 / 要写成 %2F）。
- ⚠️ R2 的 API Token 默认只给对象读写，没有 s3:ListBucket 就 403。列桶失败**不让整个
恢复失败**：本地那半照救，原因进 Warnings、页面用红色提示条显示（否则站长会以为恢复完了）。
- 候选对象 = 本地目录 ∪ 桶里 .webp（同键以本地为准）；行的 storage 按「对象实际在哪」写，
bytes 用桶里报的 Size。另加一条 warning：挂回了却没配 s3_public_base ⇒ 行有了页面空白，
这比「没恢复」更难懂。
专题（用户拍板「一并做」）：topics.dataset_id 同样带 CASCADE，删数据集带走专题，而专题
只存在这张表里、没有恢复来源。外键摘掉，所有查询 dataset_id → user_id（loadTopics、
topicPage、保存/删除/开关、pageBase.HasTopics）；**内容仍照当前生效数据集算**
（topicContent 不动）——变的是「这份定义归谁」。Dataset 补 UserID 供前台按属主定位
用户级数据；管理专题不再要求有生效数据集。
导出链路未改动：place_images / topics / Dataset.UserID 都不参与 .rondbackup 导出，
全量验收（含导出保真、ZRAW 夹取、编号对齐那批）PASS=331 FAIL=0 SKIP=0。
94 lines
11 KiB
Markdown
94 lines
11 KiB
Markdown
# rond-with-you 硬规矩（索引）
|
||
|
||
> 全文：`.workbuddy/memory/MEMORY-details.md`（36 节）；验证机制：技能 `rond-fix-verify`；备份包解析/导出：技能 `rond-backup-parse`。本文件只做关键词索引——**新规矩写 details，别堆这里**。
|
||
>
|
||
> ⚠️ 本文件**按字符数**注入，硬上限 `MAX_MEMORY_CHARS = 1e4`（WorkBuddy `app.asar` 里 `getWorkingMemoryContent`；中文 1 字算 1，不是按字节）。超了会被 `substring(0,1e4)` 截断并写明「先整理再干活」——即整段尾部静默丢失。日常日志与本 details **不参与注入**，可以随便写。现值见 `wc -m`，留 20% 余量。
|
||
|
||
## 落库 / 精度（details 一、四、五、十六、十九、廿八A）
|
||
- 建地点+到访**同一事务**；新行号只走 `nextSrcPK`+`clearStaleRaw`，**禁 `MAX(src_pk)+1`**。`seq_test.go`
|
||
- 行程派生列同导入（`validateMovementForm`）：`from/to_place_id`（留空=绕过区域过滤直露访客）、`distance_km`、`duration_min`。
|
||
- 表单精度低于真值 ⇒ 只改备注也**静默改时间/坐标**：`keepStoredTime`/`resolveMovementEnd`/`keepStoredCoord`；改到访时间须 `clampVisitMovements` 夹行程。
|
||
- `src_pk` 只单数据集内有效；跨备份键=`ZIDENTIFIER_`/`ZUID_`；`contentHash` 别用 `SrcPK|Arrival`。
|
||
- 坐标留档 `coord_source/coord_sys/src_lat/src_lon`；换算只走 geo 包与 `/api/coords`。
|
||
- 脏数据：`appleTime` 超范围浮点转 int64 **回绕非饱和**（先卡秒数）；`validCoord` 非法归 `(0,0)`。`dirty_test.go`
|
||
- 聚合刷新（`saveVisitTags`/`refreshPlaceAgg`/`refreshDatasetAgg`/`activityFlags`）**必须返回 error**。`agg_error_test.go`
|
||
- 收藏切换走单语句 `UPDATE … RETURNING bookmarked`。`visit_bookmark_test.go`
|
||
|
||
## rond 导出（details 二、廿六）
|
||
- 铁律：**PG 覆盖管理列、`entity_raw` 还原其余列**；基线已有行保真机原值（`keepNilCols`+`known[pk]`）。
|
||
- 新行只补 `ZRAWLATITUDE/LONGITUDE`、`ZVISIT.ZIDENTIFIER_`/`ZACTIVITY.ZUID_`（确定性=表名+src_pk）、`ZICON_`、`ZLASTARRIVALDATE_` 哨兵 `-63114076800`。
|
||
- `ZMOVEMENT.ZTYPE_` 不能 NULL、**别当管理列**（会洗掉 type=4）；`queryTransports` 必须 `GROUP BY transport_src`。
|
||
- rows 收尾必须 `drainRows`（先 `Err()` 再 `Close()`）。`parse_rows_test.go`
|
||
- **扫进裸 `bool` 的列必须先 `COALESCE`**：`weather.is_daylight` 漏写 ⇒ NULL ⇒ 整包拒收（details 卅C）。
|
||
- 核对导出包**别按留档 UUID 找行**：站点新建行会被补派生 UUID（`coreDataUUID`）。
|
||
- **换基线**（底座换代，`/admin/baseline`）：站点数据一行不动，只换底稿。判据=到访 UUID 重合率（`matched==0` 硬拒）+ 干跑导出；记档 `datasets.baseline_*`，`ensureBaseline` **必须先看记档**；留档名**必须防重名**（秒级时间戳会让回滚覆盖掉刚生成的留档）。`baseline_swap_test.go`（details 卅三）
|
||
|
||
## 迷雾 / 遮罩（details 三、九、十、廿二）
|
||
- `.fwss`=zip、条目 zlib；`Model/*/`=头 32768B+每块 515B；`Model/~/`、`Model/#/` 原样写回；清空/替换都要连 `fog_raw_files`。
|
||
- 导入三段式（preview 暂存 → 差异页现算 → `?stash=` 落地）；带 stash=urlencoded、无 stash=multipart 两条都留。
|
||
- `fog_masks` 圆心 GCJ-02+半径，判定前换 WGS-84 网格；遮罩只对访客；`stats.Filter` 有**两套 where**（`visitsWhere`+`movementsWhere`），漏一个=「到访藏了里程还在」。
|
||
- 瓦片须与底图同 `crs`；带地图页须 `p.HasMap=true`。
|
||
- `tileDigits` 补前导 0；`tileName` 尾缀 `len(s)-2` 单数字编号时为 -1 ⇒ panic；解码守卫 `len(name)<8`。
|
||
- `fogIndexV` 必须 `atomic.Pointer`（普通指针=真 data race）。`fog_race_test.go`（-race）
|
||
|
||
## 前端 / 模板 / CSS（details 六~八、十七、廿三、廿八D）
|
||
- 改 Go 必须重启；模板/CSS/JS 只在 `debug=true` 热加载（`AssetV` 启动哈希）。
|
||
- 拼查询串走返回 `template.URL` 的方法（`PlaceLink`/`EditPlaceLink`/`MapLink`/`EditLink`），勿手工转义。
|
||
- 窄屏覆盖写 `app.css` **末尾那块**；宽表堆叠类名**成对** `class="tb tb-stack"`；触控 44px。`tb_stack_test.go`
|
||
- 加表格列：`PlaceCols`/`scanPlace` **成对**、新列追加最后；CJK 挤换行只抬该表 `min-width`。
|
||
- ⚠️ 模板 JS 别用「heredoc+python」写 `\n`（`<script>` 语法错、交互全哑而模板测试照过）；用 Edit，改完 CDP 验 JS 报错为空。`inline_script_test.go`
|
||
- 只在访客复现的 bug：先比「无 cookie 原始 HTML vs CDP 后 DOM」；别让 JS 从 `{{if .IsAdmin}}` 块读 id。
|
||
- **异步回包一律发序号作废**：`var seq=++xxxSeq;` 在 `if(!on) return;` **之前**，回包首行 `if(seq!==xxxSeq) return;`。`map_async_cancel_test.go`
|
||
- `window.localStorage` 一律经 `lsGet`/`lsSet`（隐私模式裸访问会抛）；`previewQueue[id]` 须在 `if (live)` 之前排队、回调消费后删。
|
||
|
||
## 编辑页 / 重复到访（details 三十）
|
||
- 「重复到访」卡片：判定与 `tools/dedup_site_visits.py` 同语义、**UUID 是前提**、基线对不上就不给按钮；改指合并标记只动**本来就有**的键（`create_if_missing=false`）。`dup_visits_test.go`
|
||
- **已并入 / 子段（`ZMERGEDTO`/`ZPARENT`）只在读侧收口**，判据唯一一份 `stats.SoloVisitSQL`；天气与位移**不收口**；导出侧一字节不动。收口点清单见 details 卅G。
|
||
- 相对计数断言会**假绿**（变异让基准值一起膨胀），必须写定义性不变量；`render` 是流式直写，`code==200` 不等于渲染完。
|
||
- ⚠️ ingest 地点聚合回填必须排在 `insertEntityRaw` **之后**（判据读 entity_raw）。
|
||
|
||
## 活动 / 类别（details 廿四、廿五）
|
||
- **活动是表，类别不是**——类别只是 `places.poi_category` 字符串列；显示名**绝不写进该列**（`TestCategoryLabelNeverTouchesValue`），走 `categoryLabel(v,custom)`，Go 侧算好塞。
|
||
- 站内新建行 `entity_raw.raw IS NULL`；`ZCATEGORY_` 真机只有 `MKPOICategoryXxx` 枚举。
|
||
- 类别候选：编辑/照片页=库里在用 `GROUP BY`；补全页=在用 ∪ 静态表；下拉留「其它（自己写）」，默认「不动」。
|
||
|
||
## 跨备份 / 附属数据（details 十九~廿一、卅四）
|
||
- 预演按 `VisitUUID`/`ActivityUUID` 对齐、只读；`raw #>> '{ZIDENTIFIER_,$blob}'` 是 base64 须转 hex 比；地点只认坐标（`PlaceCoordKey` 6 位）。
|
||
- 附属数据（备注/投票/图片）主键=`place_key` 坐标键（非 dataset+src_pk）；Go 与 SQL 两套须逐位一致。
|
||
- ⚠️ **附属数据不能挂数据集外键**：`place_images` 曾按 `dataset_id` CASCADE ⇒ 删旧数据集=删图片行、**文件却留在盘上**（读取按坐标键、行按数据集级联，两套口径打架）。已摘掉外键；恢复走后台「图片挂载恢复」，认地点靠旧数据集留下的 `baselines/<id>.sqlite`（**别清 baselines 目录**）。`image_recovery_test.go`（details 卅四）
|
||
- ⚠️ 恢复**同时扫对象存储**（R2/S3）：`media.ListObjects`（ListObjectsV2 + SigV4，查询串先编码再签），
|
||
需 `s3:ListBucket` 权限；列不动时本地照救 + warning。**专题同理**：`topics` 已改成归人不归数据集
|
||
（`user_id` 过滤，内容仍照生效数据集算）。用户级数据靠 `Dataset.UserID` 定位。（details 卅四）
|
||
- ⚠️ `schema.sql` 迁移块必须收敛且排在依赖表之后（插在 `place_images` 前：开发库无症、**新库起不来**）。
|
||
- 合并 `backup_merge.go`：整个 `withTx`、不删除；新行 `*_visit_src` 写**库里的 src_pk**；必须 `writeRawRow`；删地点前先查有无到访（CASCADE）。
|
||
|
||
## 后端 / 性能（details 十、廿八C）
|
||
- `findSourceArchive` 先按 `size_bytes` 筛再算 sha256（`pickArchiveBySha`）。池 8/8 + `db.WarmUp(d,6)`；页面内查询 `runJobs`(≤6)；别用 `fog.Index.All()`；改遮罩须 `masks.invalidate()`+`fogTiles.clear()`。
|
||
- `placeCols` 子查询必须带 `vN.dataset_id=p.dataset_id`。`stats/placecols_test.go`（按子查询分段判）
|
||
- multipart handler 直接 `ParseMultipartForm`（`r.ParseForm()` 毒化字段）；**之前必须 `MaxBytesReader`**。五个上传口：备份/GPX/迷雾/照片/地点图片。
|
||
- 包了 `ResponseWriter` 必须实现 `Unwrap()`（`gzipWriter`/`headerSent`）；`recover` 写错误页前须看 `headerSent`。`server_error_test.go`
|
||
- 「先落盘再解析」的上传 handler，落盘后每条失败路径都要删半成品。`upload_cleanup_test.go`
|
||
- 批量勾选走 `*Bulk` + `p.src_pk = ANY($3::bigint[])`（pgx 直接吃 `[]int64`）；**全局内存缓存必须带上限**（`fillupCache` FIFO 淘汰最旧 1/4）；**同一查询别在一个 handler 里查两遍**。`admin_notes_bulk_test.go`+`fillup_cache_test.go`+`stats_weekday_once_test.go`
|
||
- 加 `setting` 字段改三处：`Default()`/`Load()`/`settingsSubmit()`。
|
||
|
||
## 安全 / 跳转（details 廿八B）
|
||
- 跳转唯一判据 `safeInternalPath`（`view.go`）；四处共用。`redirect_target_test.go`（含禁弱判据静态扫描）
|
||
- cookie `Secure` 按请求判断（`cookieSecure`），否则本机 http 与 CDP 都登不进。
|
||
- CSRF 只加同源 Origin/Referer 守卫（`csrf.go`）：仅写方法、`Origin: null` 拒、两头都缺放行。
|
||
- `clientIP` 只认 XFF **最后一段**（须 `netip.ParseAddr`）；⚠️ 投票匿名身份=`hash(cookie,IP)`⇒改取法即改身份。
|
||
- GPX 按属主收口：`/api/gpx` 取生效数据集 `user_id` 再 `WHERE user_id=$1`；`adminGpxDelete` 查 `RowsAffected()==0`。`gpx_owner_test.go`
|
||
- 下载名走 `downloadDisposition`（ASCII 兜底+`filename*=UTF-8''`）；四出口都经此。`download_name_test.go`
|
||
- `writeRawRow` 必须上抛错误让 `withTx` 回滚。**两步验证两闸都要**：`loginGuard`（键 `"2fa:"+用户名`）+`CodeReplay.Consume`。`twofa_guard_test.go`+`code_replay_test.go`
|
||
|
||
## 口径 / 404 / 验收（details 十一~十三、廿七、廿八E、卅二）
|
||
- ⚠️ **跑全量验收前**：① `VACUUM (FULL, ANALYZE)`（死元组涨到 3.3GB 后级联 DELETE 变 IO 爬虫，看着像 hang）；② 库内必须有 `is_active` 数据集，否则 `internal/stats` 6 用例**假 skip**。跑着时别并发跑定点测试。
|
||
- 区域判定**两端各过一遍再 AND**（同 `regionSQL`）；`movementsWhere` 也必须两端各判，不能用 `EXISTS(... IN (from,to) ...)`；比较列一律 `COALESCE(col,'')=$n`。`region_consistency_test.go`
|
||
- 其余（累计停留口径、`Filter.Verdict` 下沉、404 分档、验收四件套、覆盖率 `-coverpkg`）见 details 卅二。
|
||
|
||
## 备份合并 / 导出链路（details 卅一 + 廿一）
|
||
- 对齐键：到访=`ZIDENTIFIER_`、地点=`PlaceCoordKey`（坐标 6 位，**不认名称**）、活动=`ZUID_`；合并前必须**重算差异**。
|
||
- 地点配对只有一份实现 `rond.MatchPlaces`（差异与合并共用）；同名兜底必须有距离上限（`nameMatchMaxKm=1.0`）。
|
||
- 差异页默认 radio 是「**用实机**」；写合并测试要照这个提交（抓 `value="backup"`），否则测的不是真实点击行为。
|
||
- 自检不变量：合并后没有任何地点被搬动 >1km、也没有任何到访离它的实机地点 >1km。
|
||
- **三条铁律**：① app 只靠 `Z_PK` 解引用地点/活动 ⇒ 导出的编号必须与**数据集基线**同一套 ⇒ **基线必须是手机包**；② rond 导入是**整库替换** ⇒ 导入前先清空 app 数据；③ 站点数据是超集 ⇒ 用「手机导出作新数据集 + 旧站点导出当备份合并进去」对齐；`ZRAW` 这类从源包抄来的计数会越界，靠导出侧夹取兜住。
|