wwjcloud-nest-v1/.trae/rules/development_constraints.md

WWJCloud-NestJS 开发约束规范

本文档整合了项目的所有开发规范和约束，确保开发过程中严格遵循项目架构和数据库设计。

📋 开发规范声明

请严格按照以下规范进行开发，不允许假设和自创：

1. 🗄️ 数据库表结构约束

主要数据库文件：

• WWJCloud 主数据库：./sql/wwjcloud.sql

核心表结构：

• sys_user - 系统用户表 (uid, username, password, real_name, last_ip, last_time, create_time, login_num, status, delete_time)
• sys_role - 系统角色表 (role_id, site_id, role_name, rules, status, create_time, update_time)
• sys_user_role - 用户角色关联表 (id, uid, site_id, role_ids, create_time, is_admin, status)
• site - 站点表 (site_id, site_name, group_id, app_type, logo, desc, status, expire_time, addons)
• member - 会员表 (member_id, username, mobile, password, nickname, headimg, member_level, member_label, wx_openid)

WWJAuth 认证服务表：

• wwjauth_admins - 管理员表
• wwjauth_roles - 角色表
• wwjauth_permissions - 权限表
• wwjauth_role_permissions - 角色权限关联表
• wwjauth_members - 会员表
• wwjauth_menus - 菜单表

2. 🏗️ 项目架构规范

架构文档： 项目README - 依赖关系图

分层架构约束：

┌─────────────────┐
│      App        │  ← 业务开发层（用户自定义业务模块）
│   (用户业务)     │    电商、CRM、ERP等具体业务逻辑
└─────────────────┘
         ↓
┌─────────────────┐
│     Common      │  ← 框架通用服务层（企业级通用功能）
│ (框架通用服务)   │    用户管理、权限管理、菜单管理
└─────────────────┘    文件上传、通知服务、系统设置
         ↓              数据字典、缓存服务、队列服务
┌─────────────────┐
│      Core       │  ← 核心基础设施层（底层基础设施）
│   (基础设施)     │    认证核心、数据库核心、验证核心
└─────────────────┘    HTTP核心、缓存核心、队列核心
         ↓
┌─────────────────┐
│     Vendor      │  ← 第三方服务适配层
│   (外部集成)     │    存储、支付、通信、云服务适配
└─────────────────┘

┌─────────────────┐
│     Addons      │  ← 插件扩展层（可插拔功能模块）
│   (插件扩展)     │    扩展框架功能，不影响核心稳定性
└─────────────────┘

依赖约束：

• ✅ 允许：App → Common → Core → Vendor（严格单向）
• ❌ 禁止：反向依赖、跨层耦合
• ❌ 禁止：Common → App、Core → App/Common、App/Common → Vendor

3. 📁 目录结构规范

标准目录结构： 项目README - 目录结构

src/
├── app/                          # 🏢 业务开发层
│   ├── demo/                     # Demo 模块（标准模板示例）
│   └── index.ts                  # App 层统一导出
├── common/                       # 🔧 框架通用服务层
│   ├── users/                    # 用户管理服务
│   ├── rbac/                     # 权限管理服务
│   ├── menu/                     # 菜单管理服务
│   ├── settings/                 # 系统设置服务
│   └── ...
├── core/                         # 🏗️ 核心基础设施层
│   ├── auth/                     # 认证核心
│   ├── database/                 # 数据库核心
│   ├── validation/               # 验证核心
│   └── ...
├── vendor/                       # 🔌 第三方服务适配层
│   ├── storage/                  # 存储服务适配
│   ├── payment/                  # 支付服务适配
│   └── ...
└── addons/                       # 🧩 插件扩展层

4. 💻 开发指南

开发规范： 项目README - 开发指南

业务模块开发流程：

1. 创建新模块：参考 src/app/demo 模块结构
2. 遵循分层架构：Controller → Service → Repository → Entity
3. 使用框架服务：充分利用 Common 层提供的通用服务
4. 统一错误处理：使用框架提供的异常处理机制
5. API 文档：使用 Swagger 注解生成 API 文档
6. 单元测试：编写完整的单元测试和集成测试

模块结构规范：

your-module/
├── your-module.module.ts         # 模块定义
├── controllers/                  # 控制器层
├── services/                     # 服务层
├── entities/                     # 实体层
├── dto/                          # 数据传输对象
├── repositories/                 # 仓储层（可选）
├── interfaces/                   # 接口定义（可选）
└── README.md                     # 模块文档

5. 🔧 代码规范

代码风格： 项目自定义指令 - 代码风格指南

核心约束：

• TypeScript 严格模式：启用所有严格类型检查
• ESLint + Prettier：遵循代码格式化和质量检查
• 命名规范：使用驼峰命名法和语义化命名
• 注释规范：使用 JSDoc 格式编写注释
• Git 提交规范：使用 Conventional Commits 规范

导入顺序：

1. Node.js 内置模块
2. 第三方依赖（npm 包）
3. 项目内部模块
4. 父级目录（../）
5. 同级目录（./）
6. 索引文件（index）

6. 🔒 API 开发规范

RESTful API 设计： 项目README - API 开发规范

控制器示例：

@Controller('users')
@ApiTags('用户管理')
export class UsersController {
  @Get()
  @ApiOperation({ summary: '获取用户列表' })
  @ApiResponse({ status: 200, description: '成功获取用户列表' })
  async findAll(@Query() query: QueryUserDto) {
    return this.usersService.findAll(query);
  }

  @Post()
  @ApiOperation({ summary: '创建用户' })
  @ApiResponse({ status: 201, description: '用户创建成功' })
  async create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }
}

7. 🧪 测试规范

测试指南： 项目README - 测试

测试要求：

• 单元测试：每个服务和控制器都应有对应的单元测试
• 集成测试：测试模块间的集成功能
• 端到端测试：测试完整的用户场景
• 测试覆盖率：保持 80% 以上的代码覆盖率

8. 🚀 部署规范

构建和部署： 项目README - 构建和部署

环境配置： 项目README - 配置说明

9. 📚 参考文档链接

核心文档：

• 项目主README - 完整的项目介绍和使用指南
• WWJCloud数据库结构 - 主数据库表结构
• WWJAuth数据库结构 - 认证服务数据库
• 项目代码规范 - 详细的代码风格和开发约束

前端文档：

• 前端开发指南
• 前端目录说明

参考实现：

• NiuCloud PHP实现 - 参考架构和最佳实践

---

⚠️ 重要提醒

1. 严格遵循数据库表结构：所有实体类必须与真实数据库表字段一一对应
2. 禁止假设和自创：不允许创建数据库中不存在的字段或表
3. 遵循分层架构：严格按照 App → Common → Core → Vendor 的依赖关系开发
4. 使用现有服务：优先使用 Common 层已有的通用服务，避免重复造轮子
5. 保持代码一致性：遵循项目既定的代码风格和命名规范

---

📝 使用方式

在每次开发对话开始时，请引用此文件：

请严格按照开发约束规范进行开发：
./.trae/rules/development_constraints.md

当前任务：[具体描述您的开发需求]

请确认您已理解上述规范，并严格按照真实的数据库表结构和项目架构进行开发。

通过引用此单一文件，AI助手将自动获取所有相关的开发约束和规范链接，确保开发过程的一致性和规范性。