---
title: 开发规范
created: 2026-04-13
updated: 2026-04-13
type: concept
tags: [convention, backend, frontend, database]
sources: [CLAUDE.md]
---

# 开发规范

项目统一的编码约定和开发流程。

## 后端规范

| 规则 | 说明 |
|------|------|
| 文件名 | 下划线法：`model_channel.ts`、`time_log.ts` |
| Entity 字段 | 驼峰法：`sessionId`、`createTime` |
| Controller | 使用 `@CoolController` 自动生成 CRUD |
| 业务逻辑 | 放 Service 层，不在 Controller |
| 响应格式 | `this.ok(data)` 或 `this.fail('message')` |
| API 路径 | `POST /admin/{module}/{entity}/{action}` |
| Entity 注册 | 在 `src/entities.ts` 中添加 import |

## 前端规范

| 规则 | 说明 |
|------|------|
| 模块配置 | 必须有 `config.ts` 导出 `ModuleConfig` |
| Service 调用 | 使用 `useCool()` 的 service 代理 |
| 组件风格 | Vue 3 Composition API + `<script lang="ts" setup>` |
| 样式 | Sass scoped |
| 菜单 | 通过 `base_sys_menu` 表配置，不硬编码 |
| 路由 | 动态路由由菜单驱动 |

## 数据库规范

| 规则 | 说明 |
|------|------|
| 自动建表 | 开发环境 `synchronize: true`，生产禁用 |
| 索引 | 关键查询字段加 `@Index()` |
| JSON 字段 | 用 `type: 'json'` 存储配置和元数据 |
| 多租户 | 自动填充 `tenantId`（来自 JWT） |
| 时间戳 | 自动填充 `createTime`、`updateTime` |

## 相关页面

- [[cool-admin-framework]] — 框架约定
- [[project-overview]] — 项目总览
- [[frontend-architecture]] — 前端架构