Files

万物街 127a4db1e3 feat: 完成sys模块迁移，对齐PHP/Java框架

- 重构sys模块架构，严格按admin/api/core分层
- 对齐所有sys实体与数据库表结构
- 实现完整的adminapi控制器，匹配PHP/Java契约
- 修复依赖注入问题，确保服务正确注册
- 添加自动迁移工具和契约验证
- 完善多租户支持和审计功能
- 统一命名规范，与PHP业务逻辑保持一致

2025-09-21 21:29:28 +08:00

5.4 KiB

Raw Blame History

Common层模块化设计标准

📋 概述

本文档定义了 wwjcloud/src/common/ 层的模块化设计标准，确保每个业务模块符合微服务导向的架构设计原则。

🏗️ 模块化设计原则

1. 模块完整性原则

每个业务模块必须包含完整的分层结构，为未来微服务拆分做准备。

2. 模块自治性原则

模块间通过明确的接口和事件进行通信，避免直接文件导入依赖。

3. 分层内聚原则

模块内部按照Spring Boot分层架构组织，确保职责清晰。

📁 标准目录结构

🎯 命名规范策略

文件名对齐PHP：所有业务文件名与PHP项目保持一致（如 User.ts, SysUser.ts, UserService.ts）
目录结构参考Java：采用Java/Spring Boot分层架构组织方式
避免NestJS文件命名风格：不使用 user.controller.ts 风格，使用 User.ts 风格

完整模块结构（必需）

src/common/{module-name}/
├── {module-name}.module.ts     # 模块定义文件（必需，NestJS特有）
├── controllers/                # 控制器层（必需）
│   ├── adminapi/              # 管理端控制器
│   │   └── {Name}.ts          # 对齐PHP: User.php → User.ts
│   └── api/                   # 前台控制器
│       └── {Name}.ts          # 对齐PHP: User.php → User.ts
├── services/                  # 服务层（必需）
│   ├── admin/                 # 管理端服务
│   │   └── {Name}Service.ts   # 对齐PHP: UserService.php → UserService.ts
│   ├── api/                   # 前台服务
│   │   └── {Name}Service.ts   # 对齐PHP: UserService.php → UserService.ts
│   └── core/                  # 核心业务服务
│       └── {Name}Service.ts   # 对齐PHP: UserService.php → UserService.ts
├── entity/                    # 实体层（必需）
│   └── {Name}.ts              # 对齐PHP: SysUser.php → SysUser.ts
├── dto/                       # 数据传输对象（必需）
│   ├── admin/
│   │   └── {Name}Dto.ts       # 对齐PHP验证器命名
│   └── api/
│       └── {Name}Dto.ts       # 对齐PHP验证器命名
├── interfaces/                # 接口定义（可选）
│   └── {Name}Interface.ts     # 对齐PHP接口命名
├── decorators/                # 装饰器（可选）
│   └── {Name}Decorator.ts     # 对齐PHP特性命名
├── guards/                    # 守卫（可选）
│   └── {Name}Guard.ts         # 对齐PHP中间件命名
└── enums/                     # 枚举（可选）
    └── {Name}Enum.ts          # 对齐PHP枚举命名

最小模块结构（基本要求）

src/common/{module-name}/
├── {module-name}.module.ts     # 模块定义文件
├── controllers/                # 至少包含一个控制器
├── services/                   # 至少包含一个服务
├── entity/                     # 至少包含一个实体（如果有数据库操作）
└── dto/                        # 至少包含一个DTO（如果有API接口）

🔍 当前模块分析结果

✅ 完整模块（26个）

符合标准的模块：

addon, agreement, aliapp, applet, auth, diy, member, niucloud, pay, poster, site, sys, user, weapp

⚠️ 不完整模块（11个）

需要修复的模块：

缺失DTO的模块（8个）

缺失Entity的模块（3个）

特殊模块（1个）

lang: 缺失所有核心层级（controllers, services, entity, dto）

🛠️ 整治计划

阶段1：修复不完整模块

为缺失DTO的模块添加DTO层
- 基于控制器方法分析所需的DTO
- 创建标准的admin和api DTO目录结构
为缺失Entity的模块添加Entity层
- 分析模块功能确定是否需要数据库实体
- 如不需要数据库操作，可创建接口或配置类
处理特殊模块
- lang模块：评估是否需要完整的模块结构，或作为配置模块处理

阶段2：标准化目录结构

统一命名规范
- 确保所有文件命名符合NestJS规范
- 统一目录组织方式
优化模块依赖
- 检查模块间的导入关系
- 确保通过接口和事件通信

阶段3：验证模块自治性

依赖关系检查
- 识别跨模块直接导入
- 重构为接口或事件通信
边界清晰化
- 明确模块职责边界
- 为微服务拆分做准备

📊 质量标准

模块完整性指标

✅ 必需文件存在率：100%
✅ 目录结构规范率：100%
✅ 命名规范符合率：100%

模块自治性指标

✅ 跨模块直接导入：0个
✅ 接口通信覆盖率：100%
✅ 事件通信覆盖率：100%

🔧 自动化检查

使用 auto-mapping-checker.js 进行自动化检查：

node auto-mapping-checker.js --check-common-structure

检查项目：

模块目录完整性
必需文件存在性
命名规范符合性
模块依赖关系
微服务边界清晰度

5.4 KiB Raw Blame History Unescape Escape