68 lines
4.6 KiB
Markdown
68 lines
4.6 KiB
Markdown
# TamaBox-v4 长期笔记（索引版）
|
||
|
||
明细已拆分到 `topics/*.md`（按需 Read 全文）：
|
||
`coop` 协作 / `build` 构建测试 / `embed` 行尾·模板·embed / `review` 审核处置举报 /
|
||
`gorm` GORM / `style` 前端样式 / `theme` 主题 / `builder` 主题生成器 / `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。
|