city-life-line/.feisuan/rules/project_rule.md

城市生命线项目开发规范指南

为保证代码质量、可维护性、安全性与可扩展性，结合项目实际技术栈与目录结构，请在开发过程中严格遵循以下规范。

一、项目基本信息

• 项目名称：city-life-line
• 工作目录：E:\work\city-life-line
• 代码作者：Administrator
• 操作系统：Windows 10
• 构建工具：Maven (后端), Vite (前端)
• SDK版本：JDK 11.0.27

二、目录结构

项目采用前后端分离架构，以下为当前项目目录结构：

city-life-line
├── html
├── public
├── src
│   ├── api                  # 接口定义层
│   │   ├── monitor          # 监控相关接口
│   │   ├── pipeNetwork      # 管网相关接口
│   │   ├── smxyjldczxt      # 业务模块接口
│   │   ├── system           # 系统管理接口
│   │   ├── tool             # 工具接口
│   │   ├── warning          # 预警接口
│   │   └── work             # 工单接口
│   ├── assets               # 静态资源
│   ├── components           # 公共组件
│   ├── directive            # 自定义指令
│   ├── layout               # 布局组件
│   ├── plugins              # 插件
│   ├── router               # 路由配置
│   ├── store                # 状态管理
│   ├── utils                # 工具类
│   └── views                # 页面视图
│       ├── error            # 错误页面
│       ├── monitor          # 系统监控
│       ├── portal           # 门户
│       ├── subSystem        # 子系统业务模块
│       ├── system           # 系统管理
│       └── tool             # 系统工具
└── vite                     # Vite 配置

三、技术栈要求

根据项目环境与目录特征，确定技术栈如下：

• 前端框架：Vue 3 + Vite
• UI 组件：Element Plus (推测，基于 RuoYi-Vue 结构)
• 状态管理：Vuex / Pinia (位于 store 目录)
• 后端环境：JDK 11 + Maven
• 后端框架：Spring Boot (推荐版本 2.5+ 以适配 JDK 11)

四、分层架构规范

前端分层规范

目录	职责说明	开发约束与注意事项
views	页面结构与展示逻辑	仅负责页面渲染，业务逻辑应抽离至 API 或 Utils 中
api	接口请求定义	按业务模块划分文件（如 system/user.js）；统一使用封装后的请求工具
components	可复用 UI 组件	遵循单一职责原则；组件命名采用 PascalCase (如 UserInfo.vue)
store	全局状态管理	模块化管理状态；避免存储临时性或非共享数据
utils	通用工具函数	纯函数开发，避免副作用；添加清晰的 JSDoc 注释

后端分层规范

层级	职责说明	开发约束与注意事项
Controller	处理 HTTP 请求，响应前端调用	不包含业务逻辑，负责参数校验与结果封装
Service	核心业务逻辑处理	复杂业务需拆分方法；事务控制在此层处理
Repository/Mapper	数据库交互	禁止在代码中拼接 SQL；优先使用 ORM 框架特性
Entity/DO	数据库实体映射	禁止直接暴露给前端，需转换为 DTO/VO

五、代码风格规范

命名规范

类型	命名方式	示例	适用范围
文件/组件	PascalCase	UserProfile.vue	前端
变量/函数	lowerCamelCase	getUserList()	全栈
常量	UPPER_SNAKE_CASE	MAX_RETRY_COUNT	全栈
CSS 类名	kebab-case	user-container	前端
包名	全小写	com.city.lifeline	后端

注释规范

• 语言要求：注释内容必须使用中文（用户第一语言）。

• 类/方法注释：必须添加 Javadoc 或 JSDoc 注释，说明功能、参数及返回值。

  /**
  * 获取用户信息列表
  * @param query 查询条件
  * @return 用户列表
  */
  public List<UserVO> selectUserList(UserQuery query);
  

  /**
  * 获取用户列表
  * @param {Object} params - 查询参数
  * @returns {Promise} - 异步结果
  */
  export function listUser(params) {
  return request({ url: '/system/user/list', method: 'get', params })
  }
  

六、安全与性能规范

前端安全

• 路由守卫：在 router 中配置权限校验，防止未授权访问。
• XSS 防护：禁止使用 v-html 渲染用户输入内容，确需使用必须先进行转义。
• 敏感信息：禁止在前端代码中硬编码密钥、Token 等敏感信息。

后端安全

• 输入校验：使用 JSR-303 注解进行参数校验 (javax.validation.constraints.*)。
• SQL 注入：严禁拼接 SQL 字符串，必须使用预编译语句或 ORM 框架。
• 权限控制：关键接口必须添加权限注解（如 @PreAuthorize）。

七、编码原则总结

原则	说明
组件化	前端页面拆分为独立组件，提高复用性与可维护性
模块化	API、Store、Utils 按功能模块划分文件
RESTful	后端接口遵循 RESTful 设计风格
DRY	避免重复代码，公共逻辑封装为 Utils 或 Service
KISS	保持代码简洁，避免过度设计