从0到1完整开发Smartshell最后沉淀出的Cursor开发规则

Cursor 开发规范总览（按功能维度）

分享一次使用VibeCoding工具开发一个完整项目后，添加的一些规则

这些规则并不是Alibaba Java规范或者其他什么规范文件，而是实在的项目经验

特别说明：不承诺可以直接使用，其中一些涉及项目名称和敏感数据已进行脱敏处理，只作为经验分享

如果对项目感兴趣可以浏览：SmartShell：为运维与研发打造的下一代智能运维工作台

总览

#mermaid-svg-UTWhHKNp4uXRvU3g{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-UTWhHKNp4uXRvU3g .error-icon{fill:#552222;}#mermaid-svg-UTWhHKNp4uXRvU3g .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-UTWhHKNp4uXRvU3g .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-UTWhHKNp4uXRvU3g .marker{fill:#333333;stroke:#333333;}#mermaid-svg-UTWhHKNp4uXRvU3g .marker.cross{stroke:#333333;}#mermaid-svg-UTWhHKNp4uXRvU3g svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-UTWhHKNp4uXRvU3g p{margin:0;}#mermaid-svg-UTWhHKNp4uXRvU3g .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g .cluster-label text{fill:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g .cluster-label span{color:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g .cluster-label span p{background-color:transparent;}#mermaid-svg-UTWhHKNp4uXRvU3g .label text,#mermaid-svg-UTWhHKNp4uXRvU3g span{fill:#333;color:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g .node rect,#mermaid-svg-UTWhHKNp4uXRvU3g .node circle,#mermaid-svg-UTWhHKNp4uXRvU3g .node ellipse,#mermaid-svg-UTWhHKNp4uXRvU3g .node polygon,#mermaid-svg-UTWhHKNp4uXRvU3g .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-UTWhHKNp4uXRvU3g .rough-node .label text,#mermaid-svg-UTWhHKNp4uXRvU3g .node .label text,#mermaid-svg-UTWhHKNp4uXRvU3g .image-shape .label,#mermaid-svg-UTWhHKNp4uXRvU3g .icon-shape .label{text-anchor:middle;}#mermaid-svg-UTWhHKNp4uXRvU3g .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-UTWhHKNp4uXRvU3g .rough-node .label,#mermaid-svg-UTWhHKNp4uXRvU3g .node .label,#mermaid-svg-UTWhHKNp4uXRvU3g .image-shape .label,#mermaid-svg-UTWhHKNp4uXRvU3g .icon-shape .label{text-align:center;}#mermaid-svg-UTWhHKNp4uXRvU3g .node.clickable{cursor:pointer;}#mermaid-svg-UTWhHKNp4uXRvU3g .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-UTWhHKNp4uXRvU3g .arrowheadPath{fill:#333333;}#mermaid-svg-UTWhHKNp4uXRvU3g .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-UTWhHKNp4uXRvU3g .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-UTWhHKNp4uXRvU3g .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UTWhHKNp4uXRvU3g .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-UTWhHKNp4uXRvU3g .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UTWhHKNp4uXRvU3g .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-UTWhHKNp4uXRvU3g .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-UTWhHKNp4uXRvU3g .cluster text{fill:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g .cluster span{color:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-UTWhHKNp4uXRvU3g .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-UTWhHKNp4uXRvU3g rect.text{fill:none;stroke-width:0;}#mermaid-svg-UTWhHKNp4uXRvU3g .icon-shape,#mermaid-svg-UTWhHKNp4uXRvU3g .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UTWhHKNp4uXRvU3g .icon-shape p,#mermaid-svg-UTWhHKNp4uXRvU3g .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-UTWhHKNp4uXRvU3g .icon-shape .label rect,#mermaid-svg-UTWhHKNp4uXRvU3g .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UTWhHKNp4uXRvU3g .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-UTWhHKNp4uXRvU3g .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-UTWhHKNp4uXRvU3g :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 部署与工程
交付拓扑
迁移与重启
AI 协作流程
前端
视觉与布局
列表与表格
交互与权限
后端
校验与参数
SQL 与查询
异步与工具类
接口输出
架构与分层
包结构与接口契约
目录约定

功能领域	主要内容
架构与分层	后端包结构、跨层接口、工程目录划分
后端	参数校验、SQL 实现、异步线程、JSON/Bean、系统字段、错误键
前端	页面风格、左树右表、列表交互、权限禁用、确认文案
列表与数据	分页上限、导入导出、大字段裁剪、Long ID、表头中文
数据库与 SQL	禁止拼接/IGNORE、Flyway 迁移提示
安全与体验	重要操作确认、右键菜单视口、前后端校验一致
部署与交付	Nginx、JAR 加密启动、官网/业务静态资源
AI 协作流程	本地优先、方案备选、Plan 存放、收尾提示

一、架构与分层

1.1 后端包结构与职责

com.***.dao：与单表、资源域强绑定------实体、Mapper、单表 Service 接口与实现。
com.***.service：跨表、复杂业务流程的应用层 Service。
禁止同一业务能力在 dao 与 service 各写一套 ServiceImpl。
跨层调用 （Controller → Service、Service → 另一模块对外能力）必须依赖接口，由 Spring 注入实现类。
同层内部私有协作可直接用具体类，不强制再抽象接口。

1.2 Controller / Service 契约

应用层 Service 接口命名、VO/DTO、entities 辅助类型放置遵循既有约定。
对外响应优先用 VO/DTO 控制字段，避免直接暴露实体。

1.3 工程目录约定

目录	用途
`website/`	仅官网静态站点（HTML、样式、脚本、素材）
`nginx/`	仅最前端 Nginx 配置（反向代理、缓存、HTTPS 模板等）
`frontend/`	业务工作台 SPA
`backend/`	Spring Boot API 与领域逻辑
`.cursor/plans/`	可执行迭代 Plan（不放 `docs/` 作唯一副本）

二、后端

2.1 参数与校验

方法参数尽量不超过 5 个，超出时封装为 Bean/VO/DTO。
Controller 入参统一用 Validate 注解 （@Validated、@Valid、@NotBlank 等），禁止在方法体内手工判空。
每个约束必须带 message ，优先使用 MessageConstant 的 ERR_* 键。
业务「记录不存在」等可保留业务异常；基础格式/必填校验不走 if 分支。

2.2 SQL 与数据访问

禁止在 Java 中拼接 SQL（含 wrapper.apply、last 内嵌片段）。
业务查询、分页、筛选下沉 Mapper XML ，参数一律 #{} 预编译绑定。
${} 仅用于结构位且可白名单约束的场景（如固定排序字段映射）。
发现存量 Java 内 SQL 片段，优先迁移到 XML并保持语义一致。

2.3 异步与并发

禁止 new Thread(...) 及在业务类中 Executors.new* 建池。
线程池在 config 下集中声明 Bean，名称使用 AsyncExecutorConstant。
@Async 必须显式指定线程池名；定时/延迟任务注入已注册的 ScheduledExecutorService Bean。

2.4 工具类与传值类型

JSON 转换优先 JsonUtil，不足时在其上扩展，不引入新 JSON 库。
请求/响应传值使用普通 class Bean ；禁止 public record。

2.5 接口输出与系统字段

以下字段为系统字段 ，对外列表/详情/分页 默认不返回：

remark、isDeleted、tenantId

前端不得将其作为业务展示字段依赖；确需透出须在接口注释标明「系统字段透出」。

2.6 错误与文案

后端业务异常优先返回稳定 ERR_* 键，不写死自然语言提示。
前端在 errorMessageMap.js 映射展示文案；页面提示由前端实现。

2.7 列表查询性能（后端侧）

分页列表 不 SELECT TEXT/LONGTEXT 及与展示无关的超大 VARCHAR（约 >1000 字符 视为大字段）。
完整内容通过 详情接口（按主键 ID）单独查询。
导出如需大字段，使用专用导出 SQL，与列表分页 SQL 分离。

2.8 分页与导入导出（后端侧）

全局分页 pageSize 最大 1000。
导入条数、文件大小受 sys_property 系统参数约束（默认 100 条 / 10MB）。
导出强约束最多 1000 条。
初始化参数变更合并到 V2__add_init_data.sql（开发阶段不做向前兼容旧数据迁移）。

2.9 缓存模块

缓存相关代码已人为调整，以当前工作区实现为基线。
修改前必须先读取最新文件，不得恢复已移除能力或擅自改变 API 契约。

2.10 加密与 Spring 扫描

mvn package 对 com.haiwei/service 核心类加密是正当需求。
不以「跳过加密」作为默认方案来回避 Spring 组件扫描问题；须从启动链路与扫描配置正面解决。

三、前端

3.1 视觉与品牌基调

整体风格：安全、智能、科技、商务、正式。
中低饱和、稳重配色；强调信息用品牌蓝/科技青；危险操作用克制风险色。
按钮、卡片、表格、弹窗：圆角、轻阴影、清晰边界、可读性优先。
主按钮文字对比度充足；操作区命名简洁一致（如「导入/导出」）。

3.2 布局：左树右表

左侧树/筛选 + 右侧主内容的分栏页，必须支持拖拽调宽 （col-resize 手柄，最小/最大宽度限制）。
左树容器、右侧列表卡片、分隔条样式在同类页面保持一致。
搜索区、筛选摘要、按钮摆放、表格表头/行 hover、分页区对齐标杆页（Linux 资源、用户管理等）。

3.3 列表页通用能力

标杆参考：

布局与筛选：LinuxResource.vue（页头统计、搜索栏、当前筛选摘要）
列配置、折叠搜索、导出：OperationLog.vue
搜索区与主表视觉：User.vue + 根节点 class list-page-unified （list-page-unified.css）

必须具备的能力：

能力	要求
页头统计	当前页条数、已选、符合条件总数等
搜索栏	与标杆页一致的 `query-form` 布局；搜索按钮带图标
筛选摘要	有条件时展示「当前筛选」+ 清空入口
列配置	操作列齿轮：显隐、拖拽排序、列宽，持久化到 DB
表头拖拽	整段列名可拖排序，与列配置一致并持久化
折叠搜索	显隐列旁切换，隐藏页头/搜索/筛选摘要以扩大表格区
操作列	按钮带图标；高频靠前；危险与低频进「更多」
「更多」入口	统一 `>>` 图标，与同行动按钮垂直/水平对齐
表头中文	可配置列表默认简体中文；文案分层到常量/工具文件

3.4 导入导出（前端侧）

导入：弹窗 + 文件选择 + CSV/Excel 模板下载；须先展示预检查结果（新增/更新/异常/超限）再允许提交。
导出：弹窗选择「导出选中」或「导出符合条件前 1000 条」+ 文件类型；展示已选条数与上限；未选中时阻止「导出选中」。

3.5 权限与按钮

绑定 button:* 权限的按钮、行内操作、「更多」下拉项 、弹窗确定/保存：渲染时即 v-perm-disable + disabled。
禁止可点击后才因 403 或保存失败首次提示无权限。

3.6 重要操作确认

适用于：删除、撤销授权、状态变更、SSH/数据库连接登录等。

确认文案须包含操作对象主标识 （推荐书名号：确认删除用户组「xxx」？）。
禁止仅写「确认删除该 xxx？」等无对象文案。
批量操作至少展示条数；单条须展示主标识；可列举前 1～3 条摘要。
连接类操作在确认区展示连接摘要（资源名、IP/主机、端口、凭据用户、操作类型等，不展示密码）。
推荐使用 confirmTargetLabel 处理过长名称。

3.7 右键与上下文菜单

position: fixed 自定义菜单（含 Teleport、标签页右键、DB 控制台等）须完整落在视口内。
使用 scheduleClampFixedMenu （clampFixedMenuToViewport.js）：nextTick + 双 requestAnimationFrame 测量修正。
样式兜底：max-height/width: calc(100vh/vw - 16px)，项多内部滚动。

3.8 前后端校验一致

VO 新增的长度、正则、必填等约束，前端提交前须做同等或更严校验。
新增 ERR_* 键须同步 errorMessageMap.js。

四、前后端共通

4.1 Long / 雪花 ID 精度

后端：Long / BIGINT 序列化为 JSON 字符串 （JacksonConfig + 可选 @JsonSerialize）。
前端：禁止对大 ID 使用 Number() / parseInt；id、parentId、树/下拉 value 统一 String(...)。
提交后端：顶层 0 可用数字；非 0 的 Long 字段用字符串 ，避免 JSON.stringify 前精度丢失。
el-tree-select 的 value 与 v-model 类型须一致（通常为 string）。

4.2 列表大字段策略（全栈）

复制代码

列表分页 ──► 裁剪字段 / 预览截断
     │
     ├─► 详情弹窗 ──► GET /{id} 拉完整内容
     └─► 导出 ──► 专用全列 SQL（可与列表 SQL 分离）

已落地示例：操作日志、SQL 执行日志管理端列表。

五、数据库与 SQL

5.1 INSERT 规范

禁止 INSERT IGNORE 及等价「忽略错误」写法。
使用普通 INSERT，让主键/唯一/非空/外键违反时立即报错。
幂等需求用 WHERE NOT EXISTS、拆分迁移版本等显式设计，不靠 IGNORE 掩盖。

5.2 迁移与本地库

迁移脚本目录：backend/src/main/resources/db/migration/
开发阶段初始化数据合并：V2__add_init_data.sql
修改库结构或初始化 SQL 后，须在任务收尾提醒：本地库需通过 Flyway（或常用迁移方式）重新执行/校验。

六、部署与交付

6.1 典型拓扑

最前层：Nginx（或等价反向代理）→ 容器/进程承载业务与站点。
业务系统（管理端前端 + API）与官网可拆分部署。
使用本仓库 build/Dockerfile 时：官网可在站点根 /，业务 SPA 常在子路径（如 /***/）。

6.2 交付单元

后端统一为可执行 Spring Boot JAR；容器化时在 JAR 外包 Docker。
内置流程：ClassEncryptor 加密 → Manifest 主类 SecureLauncher → 运行时解密启动 Application。
变更加密/启动链须同步 docs/部署方案.md。

6.3 静态资源落点

官网源码：website/；与 JAR 一体交付时可输出到 backend/src/main/resources/static/。
业务前端 Vite 默认 outDir 也指向 static/；官网与业务 SPA 同时打进同一 JAR 时须明确构建顺序与 base，避免互相覆盖。

七、AI 协作与研发流程

7.1 以工作区为准

用户声明「本地已改 / 以本地为准」时，工作区源码优先于历史对话、过时文档或规则中的旧表述。
改 pom.xml、启动类、加密相关代码前必须先 Read 真实文件。

7.2 方案与备选

编码、选型、设计时若存在更稳妥/可维护/更安全做法，须主动说明备选与权衡，由用户决策。
即使用户已指定技术栈，仍应简要给出风险或更优路径（如有）。

7.3 任务收尾提示

场景	是否提示重启/重跑
`application.yml`、`pom.xml`、Flyway 新迁移、`vite.config.js` 等非 HMR 配置	需要
纯 Vue/CSS/普通业务 Java（热更新或自动重启）	不需要例行提示
仅文档/注释/格式化	不需要

7.4 文档分工

类型	存放位置
可执行迭代 Plan	`.cursor/plans/`
正式架构、部署、环境变量	`docs/`
Cursor 规范摘要	本文档

八、自检清单（按角色）

后端开发

跨层注入接口；单表在 dao、复杂业务在 service
Controller VO 校验带 message（ERR_*）
查询在 Mapper XML，无 Java SQL 拼接
列表 SQL 不含大字段；有独立详情查询
分页/导出 ≤1000；无 INSERT IGNORE
系统字段默认不出现在对外 VO
异步走统一线程池

前端开发

页面风格与标杆列表一致；左树右表可拖拽
标准列表具备列配置、折叠搜索、筛选摘要
「更多」为 >>；无权限前置 disabled
删除/撤销等 confirm 含对象主标识
大 ID 全程字符串；树/select value 类型一致
导入导出走弹窗 + 预检查/条数提示
自定义右键菜单已做视口夹紧

全栈 / 运维

改 SQL 后提醒 Flyway
改部署/加密链同步 docs/部署方案.md
website / nginx 目录未混放业务代码

维护说明

新增或调整开发约束时，按功能章节更新本文档，而非堆砌规则文件名。
与 docs/技术架构.md 冲突时，以工作区代码 + 正式架构文档为准；本文档侧重日常协作速查。
新工程初始化可复制 docs/Cursor规则初始化模板.md 与 docs/cursor-rule-templates/ 下的通用模板。