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

# 工程约定与踩坑

## Hard Constraints

- **未正式上线前禁止旧兼容冗余**：在用户明确告知「已正式部署到生产环境」之前，改 API / cookie / schema / 前端契约时直接改到位并删旧路径；禁止双写、双读、fallback、过渡字段、兼容旧 cookie Path、兼容旧客户端等垫片。源码保持干净、规范；生产上线后再谈兼容。
- 主评论计楼层，子评论不计；评论深度上限 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`
- 后端必须 `cd backend && go run ./cmd/jiang13`；cwd 错了会把头像写到 `cmd/jiang13/data`，规范目录只有 `backend/data`（详见 `jiang13-bbs-local-dev`）

## 用户偏好（自 Trae user_profile）

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