TamaBox-v4 长期笔记（索引版）

明细已拆分到 topics/*.md（按需 Read 全文）： coop 协作 / build 构建测试 / embed 行尾·模板·embed / review 审核处置举报 / gorm GORM / style 前端样式 / theme 主题 / builder 主题生成器 / share 分享卡 / honeypot 蜜罐多家族伪装 / misc 其它约定。

协作

结论分级 P0/P1/P2；先根因取证 + 实测复现，别只静态推断。
改代码前先出变更清单；重大问题显式指出。用户常授权自主推进。
用户是运营者也是圈内人：处置必须可解释、可留痕、可申诉，不做自动级联封号。

构建与测试（详见 topics/build.md）

无 libwebp/GCC：internal/storage/s3.go 挡编译 → overlay 换桩 dev/s3stub/s3_stub.go。
「编译卡死」= proxy.golang.org 不可达。每条 go 命令前 export GOPROXY=https://goproxy.cn,direct GOSUMDB=off GOFLAGS=-mod=mod。
DB 测试：DB_TYPE=postgres DB_USER=postgres DB_PASSWORD=15207786347hXPm DB_HOST=127.0.0.1 DB_PORT=5432（DSN 不带库名）。
store 方法内用 NewXStore(db.DB)，别引用包级单例。
本沙箱起不了 TamaBox web（session 固定 redis，6379 未开）→ HTTP 端到端只能部署后做。
python urllib 不稳定（用 curl）；python 别用 /tmp；PIL 在 ~/.workbuddy/binaries/python/envs/default。

行尾 / 模板 / embed（topics/embed.md）

行尾混合不可推断，改前用 Python 数 b'\r\n'；gofmt 走 dev/gofmt_keep_crlf.py。
templates/embed.go 是显式清单：新增顶层模板必须加 //go:embed。
//go:embed 的 * 不匹配 _/. 开头文件。

审核 / 处置 / 举报（topics/review.md）

线上通道 = 七牛；裁决在 censor/policy.go + moderation.Check，新增调用点必须走 moderation.Check，不可用时 fail-closed。
严格度存 users.moderation_strictness；受处置用户强制 strict（moderation.EffectiveStrictness），查询失败回退用户设置。
同请求渲染只能用 ctx.SetError/SetInternalError，不能 *Flash。
处置四级 L1–L4；到期靠 expires_at 无 cron；restrict 是替换语义；比较用 RestrictionAtLeast。
L2 强制私密须在审核通过后、与写回答同一条 UPDATE（AnswerByIDPrivate）。
ListAPI 不经 Pager 中间件，L4 与页面密码须自校验；分享卡拦截须在缓存查询之前。
举报：免登录+验证码+限流；同 IP 同题唯一索引 → 幂等；箱主只看次数不给 IP。
告警 24h≥8 或 7d≥20 → 邮件；[security] security_alert_email 为空则静默跳过。

GORM（topics/gorm.md）

默认值必须带引号；事务里每句 tx.WithContext(ctx)；链式对象带状态，统计/更新各自重建 query。
软删除+唯一索引 = 槽位永久占用；级联删除一律 Unscoped()。

前端样式（topics/style.md）

static/css/base.css（?v= 取 conf.StaticVersion，改完 +1）。令牌在 :root + html[data-theme="dark"]，新样式一律 var(--tb-*)。
移动端（≤640px）语言/主题按钮在固定底栏 #tb-mobile-utils；箱主页有意无语言切换。
UIkit 3.3.3：.uk-flex::before/::after{display:none}；主色是编译期常量，需在 base.css 末尾映射。
视觉自检：TEST_PREVIEW=1 go test ./templates -run TestGenPreview；截图用 chrome --headless=old。

主题（topics/theme.md、topics/builder.md）

三个注入点按箱主/发布者的 Theme；投票页语言也跟发布者（applyOwnerLocale）。
一套主题 = static/css/themes/<slug>.css，只覆盖令牌；显示名用 {{ themeName ... }}，别直接 printf "theme.name.%s"。
[theme] available 是硬白名单（启动时读一次）；css 必须成对写亮/暗两个选择器。
装饰层固定 10 槽，三组 --tb-deco/-size/-position 必须等长；位置用两值 calc(0%|50%|100% ± N)。
主题生成器 dev/theme-builder/：非破坏性图片处理、layerSize/unitGeom 必须共用同一函数、 hideDeco 会把 @media 10 槽全写 none（窄屏素材消失的头号来源）。

其它约定（topics/misc.md）

校验用 valid:"required;maxlen:N" 标签。
只有箱主 /user 面板，无管理员角色、无站方后台（用户要求不要加）：站方动作只走 CLI / 邮件 / 改配置重启。
CLI 有两个构建入口必须同步：根 go build . 与 Dockerfile 的 ./cmd/。
现有 CLI：web censor uid ban restore reports restrict unrestrict hide-public。
git https://git.shiroko.one/tamakyi/tamabox（main），git push 可直推；outputs/ 已 gitignore。
ImageGen 的 background: "transparent" 至今不生效（返回 RGB、无 alpha 通道）。要透明素材：提示词把背景写成一个具体纯色（不要写 white，白衬衫/光环会被一起吃），再按该色值算 alpha：alpha = clip((maxChannelDiff - 6) / 12)，最后 MinFilter(3) 收 1px。闭合图形（如光环圆环）内部的白/底色用 floodfill 填不到，按色值抠才干净。
生成图的右下角有 "AI生成 WORKBUDDY" 水印，做素材时统一裁掉底部约 10%（切口平直，正好贴页面下沿）。

5.2 KiB Raw Blame History Unescape Escape