Instruction file imported from uuice/crispy (.cursor/rules/crispy-core.mdc). Copyright stays with the author.

Crispy 3 Core

Crispy 3.0 = Payload CMS 3 + Next.js 16 App Router，greenfield 重写，与 2.x 无代码继承。main 为稳定主线；v3-payload 用于开发/测试/修 bug；2.x 归档在 crispy-2x。

Stack

• CMS: Payload 3.85+（@payloadcms/* 版本须一致）
• DB: 本地 SQLite（.data/payload.db），生产 PostgreSQL + pnpm cli db:migrate
• 包管理: pnpm；端口 3333
• 生产: DATABASE_PUSH=false，禁止 schema push

目录要点

• src/collections/ — 业务 Collection（含 Roles、AuthzCache）
• src/access/ — RBAC：permissions.ts / can.ts / authzCache.ts
• src/plugins/ — 官方 + 自建 Plugin 聚合（index.ts）
• src/ai/ — 字段 AI、后台 Agent、前台只读助手、embedding
• src/themes/ — 前台可插拔主题（blog / cms / kb）
• src/app/(payload)/admin/ — Admin Custom Views
• src/app/(frontend)/ — 前台 SSR/RSC
• src/admin-stats/、src/openapi/ — 产品层模块
• 二次开发文档: docs/dev-docs.md（含 #permissions）

通用原则

• 最小 diff：只改任务相关文件，不顺手重构
• 不 fork Payload，不改 node_modules
• 不自动 git commit，除非用户明确要求
• 代码注释用英语；与用户沟通用中文
• 新增 Collection → payload.config.ts → pnpm cli generate:types；Postgres schema 变更 → pnpm cli db:create <name>

常用命令

pnpm cli · pnpm cli dev:dev · pnpm cli quality:ci · pnpm cli db:migrate · pnpm cli generate:types · pnpm cli generate:importmap