---
description: jiang13-bbs 工程硬约束与历史踩坑（自 Trae 记忆）
alwaysApply: true
---

# 工程约定与踩坑

## Hard Constraints

- 主评论计楼层，子评论不计；评论深度上限 10
- 详情页三栏宽度与首页统一：`max-w-[1440px]`、`gap-6` / `xl:gap-7`
- 禁止操作自己的管理员账号；至少保留一名未封禁管理员；角色白名单
- 封禁/降级事务内 `token_version++` + 撤销 refresh；`/api/logout` 在 RequireAuth 外
- 确认弹窗用站点化设计，禁止 `window.confirm`；封禁模态挂 root layout

## 常见坑

- GORM bool `default:true` 会把 `false` 当零值省略 → 布尔默认用 `false` + `Select` 强制写
- pending 帖详情 SSR **必须转发 cookie**，否则作者打开 404/500
- GORM 指针关联会建 DB FK：`LastMessage`/`Notification.Room` 必须 `constraint:-`
- Avatar 所有调用必须 `src={xxx.avatar || undefined}`
- CSRF cookie 是 URLEncoding（含 `=`），解析勿用 `split('=')[1]`
- PowerShell 5.1 中文脚本需 UTF-8 BOM；npx/npm 用 `npx.cmd`/`npm.cmd`

## 用户偏好（自 Trae user_profile）

- 沟通用中文；重视真 SSR、信息密度、WCAG（正文 ≥4.5:1）
- 纯 SSR 站不要骨架屏；少用滚动快照恢复（最后手段）
- 配色只改 CSS 令牌（见 skill `theme-recolor-workflow`）