chore: 纳入 Cursor 项目规则并忽略本地运行时数据

补充 .cursor 规则/技能与记忆;gitignore 排除 backend/cmd/jiang13/data 与调试日志。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-09-16 00:25:34 +08:00
parent 8c5de13899
commit 11548eec97
7 changed files with 444 additions and 0 deletions

View File

@@ -0,0 +1,28 @@
---
description: jiang13-bbs 认证 Cookie 方案与公共 WebSocket 实时总线约定
alwaysApply: true
---
# 认证与实时总线
## Cookie 认证(禁止 localStorage token)
- `j13_token` HttpOnly 15m;`j13_refresh` HttpOnly 7d Path=/;`j13_csrf` 非 HttpOnly
- 客户端 `/api/*` + `credentials:'include'`;写请求带 `X-CSRF-Token`
- `fetchWithRefresh`:401 自动 refresh 重试;`TokenVersion` 封禁/改密/改角色后使 JWT 失效
- SSR:middleware 过期可续 refresh;layout 直出 Header 登录态,避免 F5 闪游客
## WebSocket(全站一条连接)
- `GET /api/ws`;dev 直连 `ws://hostname:3001/api/ws`(Next rewrite 不透传 Upgrade)
- 事件:`hello` / `pong` / `settings:changed` / `presence:update` / `chat:*` / `notification:new` / `feed:changed` / `moderation:changed`
- 消息铁律:**先落库再 WS 广播**;WS 不可靠投递;未读靠 HTTP 对账
- 角标优先推送:通知落库统一 `OnNotifyNew`;待审变化推 staff `moderation:changed`;**禁止**再恢复 30s 轮询未读/待审
- ThemeSync:推送优先 + visibility/focus 校准,**无定时轮询**
- 主题 DOM:禁止对 SSR `#j13-accent-vars` 做 `remove()`;热换肤只用 `#j13-accent-runtime`
## Git
- remote:`https://git.iioio.com/freefire/jiang13-bbs.git`,分支 `main`
- 自建 Gitea 偶发不稳:`git push` 失败则**原样重试一次**;勿改 remote / 勿反复重试
- 勿提交 `node_modules`、`.next`、`backend/cmd/jiang13/data`(含 `.jwt_secret`)、真实 `app.ini`

View File

@@ -0,0 +1,43 @@
---
description: jiang13-bbs 核心铁律(自 Trae 项目记忆导入):技术栈、Next/Go 约束、SEO、权限
alwaysApply: true
---
# jiang13-bbs 核心铁律
详细原文见 [`.cursor/project_memory.md`](../project_memory.md)(自 Trae `project_memory.md` 导入并持续更新)。
## 记忆初始化指令(必须遵守)
1. 项目使用 Go 1.27 + Next.js 16,禁止生成旧版本惯用代码
2. Next.js 16 的 params 等必须 await,这是最高频错误,每次生成后自查
3. 如果部署环境涉及 Cloudflare Workers,middleware.ts 不能改名为 proxy.ts
4. 所有 SEO 关键内容必须在初始 HTML 中,不接受客户端注入
5. 权限逻辑只在 Go 端,前端不做权限判定
6. 遇到不确定的 Next.js 16 或 Go 1.27 特性,先查官方文档再生成代码
## 技术栈
- Go 1.27 + Gin;Next.js 16 (App Router) + TypeScript + Tailwind CSS;PostgreSQL
## Next.js 16
- `params` / `searchParams` / `cookies()` / `headers()` / `draftMode()` **必须 await**
- Cloudflare Workers:保持 `middleware.ts`(OpenNext 不识别 `proxy.ts`)
- 所有 `@folder` 必须有 `default.tsx`;用 Metadata API,禁止 `next/head`
- 交互组件必须 `'use client'`
- 纯 SSR:禁止骨架屏闪动(无 `app/loading.tsx` / Skeleton)
## Go 1.27
- 优先泛型方法;`encoding/json/v2`;标准库 uuid;嵌入字段可直接初始化
## SEO
- 公开页 SSR/ISR;title/description/OG/JSON-LD 必须在初始 HTML
- 帖子详情 `DiscussionForumPosting` JSON-LD;必须有 `sitemap.ts` / `robots.ts`
## 权限
- 校验只在 Go;受保护 API 走 RBAC;登录 20/分、注册 10/分、新用户发帖 24h 冷静期
- 角色:owner > super_admin > admin > board_admin > user;前端 `lib/roles.ts` 只控制 UI 显隐

View File

@@ -0,0 +1,29 @@
---
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`)