# WWJCloud-NestJS 开发约束规范

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

## 📋 开发规范声明

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

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

**主要数据库文件：**
- **WWJCloud 主数据库**：[/g:/wwjcloud-nestjs/sql/wwjcloud.sql](../sql/wwjcloud.sql)
- **WWJAuth 认证数据库**：[/g:/wwjcloud-nestjs/sql/wwjauth.sql](../sql/wwjauth.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 - 依赖关系图](../readme.md#L67-86)

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

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

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

### 3. 📁 目录结构规范

**标准目录结构：** [项目README - 目录结构](../readme.md#L155-210)

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

### 4. 💻 开发指南

**开发规范：** [项目README - 开发指南](../readme.md#L301-400)

**业务模块开发流程：**
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. 🔧 代码规范

**代码风格：** [项目自定义指令 - 代码风格指南](./project_rules.md)

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

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

### 6. 🔒 API 开发规范

**RESTful API 设计：** [项目README - API 开发规范](../readme.md#L340-365)

**控制器示例：**
```typescript
@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 - 测试](../readme.md#L370-400)

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

### 8. 🚀 部署规范

**构建和部署：** [项目README - 构建和部署](../readme.md#L410-450)

**环境配置：** [项目README - 配置说明](../readme.md#L460-520)

### 9. 📚 参考文档链接

**核心文档：**
- [项目主README](../readme.md) - 完整的项目介绍和使用指南
- [WWJCloud数据库结构](../sql/wwjcloud.sql) - 主数据库表结构
- [WWJAuth数据库结构](../sql/wwjauth.sql) - 认证服务数据库
- [项目代码规范](./project_rules.md) - 详细的代码风格和开发约束

**前端文档：**
- [前端开发指南](../admin/docs/src/guide/essentials/development.md)
- [前端目录说明](../admin/docs/src/guide/project/dir.md)

**参考实现：**
- [NiuCloud PHP实现](../reference/niucloud-php/) - 参考架构和最佳实践

---

## ⚠️ 重要提醒

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

---

## 📝 使用方式

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

```
请严格按照开发约束规范进行开发：
/g:/wwjcloud-nestjs/.trae/rules/development_constraints.md

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

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

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