npm package: @hucl111111/code-generator
Description: 代码生成工具集
Author: ms-member team
Latest version: 1.0.1

# 代码生成

基于 OpenSpec 规范文档构建的智能开发工具集，帮助开发者快速生成标准代码、验证代码规范性。

## 🚀 功能特性

### ✅ 已完成功能

1. **code-validator 代码验证器**
   - 50 条验证规则覆盖 Entity、DAO、Service、Controller 层
   - 支持文件、目录批量验证
   - 实时错误报告和修复建议

2. **code-generator 代码生成器**
   - 9 个标准代码模板
   - 支持完整 CRUD 一键生成
   - 自动生成符合规范的代码框架

3. **spec-formatter 规范格式化器**
   - Markdown 文档解析
   - 知识库构建
   - HTML 导出

4. **learning-assistant 学习助手**
   - 智能问答系统
   - 关键词搜索
   - 内容推荐

5. **CLI 工具**
   - 命令行界面
   - 集成所有功能

## 🔗 OpenSpec 集成

### ✅ 深度集成

**完全支持 OpenSpec 规范驱动开发流程:**

1. **提案驱动生成**: 从 `proposal.md` 自动提取字段定义，一键生成完整 CRUD 代码
2. **工作流钩子**: 在提案创建、审批、实施、归档各阶段自动调用工具
3. **规范同步**: 从 `openspec/rule/` 规范文档自动提取和更新验证规则
4. **统一命令**: 在 `openspec` 命令中直接使用 `generate`、`check`、`guide` 等子命令

### 集成命令

```bash
# 从 OpenSpec 提案生成代码
openspec generate crud --from-proposal

# 验证 OpenSpec 变更的代码
openspec check --change-id <change-id>

# 查看当前提案的规范信息
openspec guide --proposal

# 同步验证规则
openspec rules sync --from-docs
```

### 使用示例

```bash
# 1. 创建 OpenSpec 提案
openspec proposal create add-user-module -d "新增用户管理模块"

# 2. 编辑提案，添加核心字段定义
# openspec/changes/add-user-module/proposal.md

# 3. 自动生成代码
ms-tools openspec generate crud --from-proposal

# 4. 验证代码
ms-tools openspec check --change-id add-user-module

# 5. 查看规范
ms-tools openspec guide --proposal
```

**详细说明**: [OPENSPEC_INTEGRATION.md](./OPENSPEC_INTEGRATION.md) | [使用示例](./examples/USAGE_EXAMPLE.md)

## 📦 安装

```bash
# 克隆项目
cd /Users/hucl/yhsp/dev/ms-member/tools/skill-tools

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 链接为全局命令
npm link
```

## 🛠️ 使用方法

### 1. 验证代码

```bash
# 验证单个文件
ms-tools validate src/main/java/com/rlbsx/member/model/user/User.java

# 验证整个目录
ms-tools validate src/main/java/

# 指定文件模式
ms-tools validate src/ -p "**/*.java"
```

### 2. 生成代码

```bash
# 生成完整 CRUD（推荐）
ms-tools generate crud -m user -n User -f "name:String:50,age:Integer,email:String:100" -d "用户实体"

# 生成单个类型
ms-tools generate entity -m user -n User -f "name:String:50,age:Integer"
ms-tools generate dto -m user -n User -f "name:String:50,age:Integer"
ms-tools generate dao -m user -n User
ms-tools generate service -m user -n User
ms-tools generate controller -m user -n User
```

### 3. 查看规范

```bash
# 列出所有验证规则
ms-tools list-rules

# 查看特定规范（开发中）
ms-tools guide entity naming
ms-tools guide dao method
```

## 📋 验证规则

### Entity 层（12 条）

| 规则ID | 检查点 | 严重级别 |
|--------|--------|----------|
| **E001** | 继承 OperateBaseModel | ERROR |
| **E002** | @EntitySync 注解 | ERROR |
| **E003** | @Data 注解 | ERROR |
| **E004** | @EqualsAndHashCode(callSuper = true) | ERROR |
| **E005** | @Table(value, desc) 注解 | ERROR |
| **E006** | 表名规范（小写+下划线，CRM加crm_前缀） | ERROR |
| **E007** | 字段类型检查 | WARNING |
| **E008** | @ColumnDesc 注解 | WARNING |
| **E009** | 主键命名（id） | ERROR |
| **E010** | 包路径规范 | ERROR |
| **E011** | 审计字段继承 | INFO |
| **E012** | 方法长度检查 | WARNING |

### DAO 层（15 条）

| 规则ID | 检查点 | 严重级别 |
|--------|--------|----------|
| **DA001** | DAO 包路径 | ERROR |
| **DA002** | 接口命名 {Entity}Dao | ERROR |
| **DA003** | queryById 方法 | ERROR |
| **DA004** | listPage 方法 | ERROR |
| **DA005** | listExportPage 方法 | ERROR |
| **DA006** | listNextPage 方法 | ERROR |
| **DA007** | add 方法返回 String | ERROR |
| **DA008** | update 方法返回 boolean | ERROR |
| **DA009** | deleteById 方法返回 boolean | ERROR |
| **DA010** | 实现类包路径 | ERROR |
| **DA011** | 实现类命名 {Entity}DaoImpl | ERROR |
| **DA012** | @Autowired 注入 | WARNING |
| **DA013** | @Transactional 注解 | ERROR |
| **DA014** | @Slf4j 日志 | WARNING |
| **DA015** | FS 构建器使用 | ERROR |

### Service 层（10 条）

| 规则ID | 检查点 | 严重级别 |
|--------|--------|----------|
| **S001** | Service 包路径 | ERROR |
| **S002** | 接口命名 {Entity}Service | ERROR |
| **S003** | 7 个标准方法 | ERROR |
| **S004** | 实现类命名 {Entity}ServiceImpl | ERROR |
| **S005** | @Service 注解 | ERROR |
| **S006** | @Autowired 注入 | ERROR |
| **S007** | VoAdapterFactory 转换 | WARNING |
| **S008** | 返回类型规范 | ERROR |
| **S009** | @Transactional 事务 | WARNING |
| **S010** | 代码简洁性 | WARNING |

### Controller 层（12 条）

| 规则ID | 检查点 | 严重级别 |
|--------|--------|----------|
| **C001** | Controller 包路径 | ERROR |
| **C002** | @RestController 注解 | ERROR |
| **C003** | @RequestMapping 路径 | ERROR |
| **C004** | @Api 注解 | WARNING |
| **C005** | @ApiOperation 注解 | ERROR |
| **C006** | HTTP 方法注解 | ERROR |
| **C007** | Resp<VO> 返回类型 | ERROR |
| **C008** | Resp.success() 使用 | ERROR |
| **C009** | 参数注解规范 | ERROR |
| **C010** | @Autowired 注入 | ERROR |
| **C011** | 异常处理 | WARNING |
| **C012** | JavaDoc 注释 | WARNING |

### DTO/VO/Query 层（8 条）

| 规则ID | 检查点 | 严重级别 |
|--------|--------|----------|
| **D001** | DTO 命名 {Entity}DTO | ERROR |
| **D002** | VO 命名 {Entity}VO | ERROR |
| **D003** | Query 命名 {Entity}Query | ERROR |
| **D004** | @EqualsAndHashCode(callSuper = true) | ERROR |
| **D005** | DTO 包路径 | ERROR |
| **D006** | VO 包路径 | ERROR |
| **D007** | Query 包路径 | ERROR |
| **D008** | 序列化检查 | WARNING |

### OpenSpec 提案格式（8 条）

| 规则ID | 检查点 | 严重级别 |
|--------|--------|----------|
| **O001** | 文档结构 | ERROR |
| **O002** | 标题格式 | ERROR |
| **O003** | 核心字段定义 | ERROR |
| **O004** | 字段定义表格 | ERROR |
| **O005** | 验收标准 | ERROR |
| **O006** | 变更内容格式 | WARNING |
| **O007** | 影响范围 | WARNING |
| **O008** | 技术细节 | INFO |

## 🎨 代码模板

### 生成的代码结构

```
ms-member-model/src/main/java/com/rlbsx/member/model/{module}/
└── {Entity}.java                    # Entity

ms-member-protocol/src/main/java/com/rlbsx/member/{module}/
├── dto/
│   └── {Entity}DTO.java             # DTO
├── vo/
│   └── {Entity}VO.java              # VO
└── query/
    └── {Entity}Query.java           # Query

ms-member-service/src/main/java/com/rlbsx/member/{module}/
├── dao/
│   ├── {Entity}Dao.java             # DAO 接口
│   └── impl/
│       └── {Entity}DaoImpl.java     # DAO 实现
├── service/
│   ├── {Entity}Service.java         # Service 接口
│   └── impl/
│       └── {Entity}ServiceImpl.java # Service 实现
└── controller/
    └── {Entity}Controller.java      # Controller
```

### 字段定义格式

字段定义使用 `name:type:length` 格式，多个字段用逗号分隔：

```bash
# 示例
name:String:50,age:Integer,email:String:100,createTime:Date

# 支持的类型
- String
- Integer
- Long
- Double
- Boolean
- BigInteger
- Date
- LocalDateTime
- LocalDate
```

## 📖 示例

### 示例 1：生成用户模块 CRUD

```bash
# 生成用户模块完整 CRUD
ms-tools generate crud -m user -n User -f "name:String:50,age:Integer,email:String:100,mobile:String:20" -d "用户实体"
```

**生成的文件:**

1. `ms-member-model/src/main/java/com/rlbsx/member/model/user/User.java`
2. `ms-member-protocol/src/main/java/com/rlbsx/member/user/dto/UserDTO.java`
3. `ms-member-protocol/src/main/java/com/rlbsx/member/user/vo/UserVO.java`
4. `ms-member-protocol/src/main/java/com/rlbsx/member/user/query/UserQuery.java`
5. `ms-member-service/src/main/java/com/rlbsx/member/user/dao/UserDao.java`
6. `ms-member-service/src/main/java/com/rlbsx/member/user/dao/impl/UserDaoImpl.java`
7. `ms-member-service/src/main/java/com/rlbsx/member/user/service/UserService.java`
8. `ms-member-service/src/main/java/com/rlbsx/member/user/service/impl/UserServiceImpl.java`
9. `ms-member-service/src/main/java/com/rlbsx/member/user/controller/UserController.java`

### 示例 2：验证代码规范性

```bash
# 验证整个项目
ms-tools validate src/
```

**输出示例:**

```
=== 验证报告 ===

总计文件: 156
通过文件: 142
失败文件: 14
错误数量: 23
警告数量: 31

文件: /Users/hucl/yhsp/dev/ms-member/src/main/java/com/rlbsx/member/model/user/User.java
类型: entity
状态: ✗ 失败
  - 错误: 2
  - 警告: 1
  - 信息: 0

  ✗ [ERROR] Entity 必须继承 OperateBaseModel
    -> 行 8
  ✗ [ERROR] @Table 注解必须包含 desc 属性
    -> 行 10
  ⚠ [WARNING] 建议包含 @ColumnDesc 注解
    -> 行 15
```

### 示例 3：查看验证规则

```bash
ms-tools list-rules
```

**输出示例:**

```
📋 验证规则列表:

Entity 层验证规则 (12 条):
  E001: 继承基类检查
  E002: @EntitySync 注解检查
  E003: @Data 注解检查
  E004: @EqualsAndHashCode 注解检查
  E005: @Table 注解检查
  E006: 表名规范检查
  E007: 字段类型检查
  E008: @ColumnDesc 注解检查
  E009: 主键命名检查
  E010: 包路径检查
  E011: 审计字段检查
  E012: 方法长度检查

...
```

## 🔧 高级用法

### 1. 集成到 Git Hooks

在 `.git/hooks/pre-commit` 中添加:

```bash
#!/bin/sh
echo "🔍 运行代码规范检查..."
ms-tools validate src/
if [ $? -ne 0 ]; then
  echo "❌ 代码不符合规范，请修复后重新提交"
  exit 1
fi
```

### 2. 集成到 CI/CD

在 GitHub Actions 或 Jenkins 中添加:

```yaml
- name: 代码规范检查
  run: |
    npm install
    npm run build
    npx ms-tools validate src/
```

### 3. 批量生成

创建脚本批量生成多个模块:

```bash
#!/bin/bash
# generate-modules.sh

modules=(
  "user:User:name:String:50,age:Integer,email:String:100"
  "member:Member:name:String:50,level:Integer,points:Long"
  "order:Order:orderNo:String:50,amount:Double,status:String:20"
)

for module in "${modules[@]}"; do
  IFS=':' read -r moduleName entityName fields <<< "$module"
  echo "生成模块: $moduleName"
  ms-tools generate crud -m "$moduleName" -n "$entityName" -f "$fields"
done
```

## 📊 项目统计

- **验证规则**: 50 条
- **代码模板**: 9 个
- **支持类型**: Entity, DTO, VO, Query, DAO, Service, Controller
- **文件覆盖率**: 100% 的项目代码

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支
3. 提交变更
4. 创建 Pull Request

## 📝 更新日志

### v1.0.0 (2025-11-24)

- ✅ 完成 code-validator 代码验证器
- ✅ 完成 code-generator 代码生成器
- ✅ 完成 spec-formatter 规范格式化器
- ✅ 完成 learning-assistant 学习助手
- ✅ 完成 CLI 工具
- ✅ 集成 50 条验证规则
- ✅ 集成 9 个代码模板

## 📄 许可证

MIT License

## 👥 作者

ms-member 开发团队

## 🙏 致谢

感谢 OpenSpec 规范文档提供的基础，为本工具的实现提供了详尽的规范依据。