# CI 检查脚本规范

## 概述

本变更新增了自动化代码规范检查脚本，用于在 CI/CD 流程中检测规范违规。

## 检查脚本列表

### 1. Service 层错误处理检查

**文件**：`scripts/check-service-errors.sh`

**用途**：检查 Service 层是否使用 `fmt.Errorf` 对外返回错误

**检查范围**：
- 目录：`internal/service/**/*.go`
- 排除：测试文件（`*_test.go`）
- 排除：带有 `// whitelist:` 注释的行

**检查逻辑**：
```bash
FILES=$(find internal/service -name "*.go" -type f)
VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")

if [ -n "$VIOLATIONS" ]; then
    echo "❌ 发现 Service 层使用 fmt.Errorf"
    exit 1
fi
```

**退出码**：
- `0`：检查通过
- `1`：检查失败（发现违规）

**白名单机制**：

如果某处确实需要使用 `fmt.Errorf`（如内部调试），添加注释：

```go
// 特殊场景：内部日志调试
debugErr := fmt.Errorf("debug info: %v", data) // whitelist:
logger.Debug("调试信息", zap.Error(debugErr))
```

### 2. 注释路径一致性检查

**文件**：`scripts/check-comment-paths.sh`

**用途**：检查 Handler 层注释中是否残留已弃用的 `/api/v1` 路径

**检查范围**：
- 目录：`internal/handler/**/*.go`
- 排除：测试文件（`*_test.go`）

**检查逻辑**：
```bash
VIOLATIONS=$(grep -rn "/api/v1" internal/handler/ | grep -v "_test.go")

if [ -n "$VIOLATIONS" ]; then
    echo "❌ 发现残留的 /api/v1 路径注释"
    exit 1
fi
```

**退出码**：
- `0`：检查通过
- `1`：检查失败（发现残留路径）

**正确路径**：
- `/api/admin/*`：后台管理接口
- `/api/h5/*`：H5 端接口
- `/api/c/v1/*`：个人客户接口

### 3. 统一检查脚本

**文件**：`scripts/check-all.sh`

**用途**：运行所有代码规范检查

**检查流程**：
```bash
set -e  # 任何检查失败立即退出

bash scripts/check-service-errors.sh
bash scripts/check-comment-paths.sh
# 未来可添加更多检查...

echo "✅ 所有检查通过"
```

**使用场景**：
- 本地开发：提交代码前运行
- CI/CD：自动化检查流程
- Pre-commit hook：提交前自动检查（可选）

## 脚本规范

### 输出格式

所有检查脚本应遵循统一的输出格式：

```bash
# 1. 开始提示
echo "🔍 检查 [检查项名称]..."

# 2. 检查逻辑
VIOLATIONS=$(检查命令)

# 3. 结果输出
if [ -n "$VIOLATIONS" ]; then
    echo ""
    echo "❌ 发现违规："
    echo "$VIOLATIONS"
    echo ""
    echo "修复建议："
    echo "  - 建议1"
    echo "  - 建议2"
    exit 1
fi

echo "✅ [检查项名称]检查通过"
```

### 错误消息规范

错误消息应包含：
1. **问题描述**：明确说明发现了什么问题
2. **违规位置**：文件路径和行号
3. **修复建议**：如何修复这些问题
4. **白名单机制**：如何豁免特殊场景（如适用）

**示例**：
```
❌ 发现 Service 层使用 fmt.Errorf：
internal/service/shop.go:45:    return fmt.Errorf("店铺不存在")
internal/service/account.go:78: return fmt.Errorf("创建失败: %w", err)

请使用以下方式替代：
  - 业务错误：errors.New(code, msg)
  - 系统错误：errors.Wrap(code, err, msg)

如果某处确实需要使用 fmt.Errorf（如内部调试），请添加注释：// whitelist:
```

### 脚本权限

所有脚本应添加执行权限：

```bash
chmod +x scripts/check-service-errors.sh
chmod +x scripts/check-comment-paths.sh
chmod +x scripts/check-all.sh
```

### Shell 兼容性

脚本应使用 Bash 标准语法，兼容 Linux 和 macOS：
- 使用 `#!/bin/bash` 作为 shebang
- 避免使用非标准工具（仅依赖 grep、find、bash 等）
- 使用 `set -e` 确保错误自动退出

## CI 集成（可选）

### GitHub Actions 配置

**文件**：`.github/workflows/lint.yml`

```yaml
name: Code Quality Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.25'
      
      - name: Run Code Quality Checks
        run: bash scripts/check-all.sh
```

### 本地使用

开发者可以在本地运行检查：

```bash
# 运行所有检查
bash scripts/check-all.sh

# 运行单项检查
bash scripts/check-service-errors.sh
bash scripts/check-comment-paths.sh
```

### Pre-commit Hook（可选）

可以配置 Git pre-commit hook 在提交前自动检查：

**文件**：`.git/hooks/pre-commit`

```bash
#!/bin/bash

echo "运行代码规范检查..."
bash scripts/check-all.sh

if [ $? -ne 0 ]; then
    echo ""
    echo "代码规范检查失败，提交已取消"
    echo "请修复上述问题后重新提交"
    exit 1
fi

echo "代码规范检查通过，继续提交..."
```

## 扩展性设计

### 添加新的检查规则

添加新的检查规则的步骤：

1. **创建检查脚本**：`scripts/check-{name}.sh`
   ```bash
   #!/bin/bash
   echo "🔍 检查 [检查项名称]..."
   
   # 检查逻辑
   VIOLATIONS=$(检查命令)
   
   if [ -n "$VIOLATIONS" ]; then
       echo "❌ 发现违规"
       echo "$VIOLATIONS"
       exit 1
   fi
   
   echo "✅ 检查通过"
   ```

2. **添加执行权限**：
   ```bash
   chmod +x scripts/check-{name}.sh
   ```

3. **集成到统一脚本**：
   在 `scripts/check-all.sh` 中添加：
   ```bash
   bash scripts/check-{name}.sh
   ```

4. **测试脚本**：
   ```bash
   # 测试通过场景
   bash scripts/check-{name}.sh  # 应返回退出码 0
   
   # 测试失败场景（制造违规）
   # 验证能检测到违规并返回退出码 1
   ```

5. **更新文档**：
   在 `README.md` 和本规范文档中添加新检查的说明

### 检查规则示例

以下是一些可能添加的检查规则：

| 检查项 | 脚本名称 | 检查内容 |
|-------|---------|---------|
| 常量硬编码 | `check-constants.sh` | 检查代码中是否有硬编码的 magic numbers 和字符串 |
| 日志规范 | `check-logging.sh` | 检查日志是否使用结构化字段（zap.String、zap.Int 等） |
| TODO 标记 | `check-todos.sh` | 统计代码中的 TODO 数量，超过阈值时警告 |
| 导入路径 | `check-imports.sh` | 检查是否使用了禁止的包（如 `fmt.Println`） |
| 测试覆盖率 | `check-coverage.sh` | 检查测试覆盖率是否达标 |

## 性能考虑

### 检查耗时

所有检查脚本应在合理时间内完成：
- 单项检查：< 10 秒
- 统一检查：< 30 秒

### 优化建议

1. **并行执行**：多个独立检查可以并行运行
2. **缓存结果**：避免重复扫描相同文件
3. **增量检查**：仅检查变更的文件（CI 场景）

### 并行执行示例

```bash
#!/bin/bash
# scripts/check-all-parallel.sh

# 在后台运行检查
bash scripts/check-service-errors.sh &
PID1=$!

bash scripts/check-comment-paths.sh &
PID2=$!

# 等待所有检查完成
wait $PID1
RESULT1=$?

wait $PID2
RESULT2=$?

# 检查结果
if [ $RESULT1 -ne 0 ] || [ $RESULT2 -ne 0 ]; then
    echo "❌ 至少有一项检查失败"
    exit 1
fi

echo "✅ 所有检查通过"
```

## 测试策略

### 脚本测试清单

每个检查脚本应测试以下场景：

1. **通过场景**：无违规时返回 0
2. **失败场景**：有违规时返回 1 并输出错误
3. **白名单机制**：白名单注释生效（如适用）
4. **边界情况**：空目录、特殊字符等

### 测试示例

```bash
# 测试 Service 层错误检查

# 1. 通过场景
bash scripts/check-service-errors.sh
echo "退出码: $?"  # 应为 0

# 2. 失败场景
echo 'return fmt.Errorf("test")' >> internal/service/test_violation.go
bash scripts/check-service-errors.sh
echo "退出码: $?"  # 应为 1
rm internal/service/test_violation.go

# 3. 白名单机制
echo 'return fmt.Errorf("debug") // whitelist:' >> internal/service/test_whitelist.go
bash scripts/check-service-errors.sh
echo "退出码: $?"  # 应为 0
rm internal/service/test_whitelist.go
```

## 维护指南

### 定期维护

- **每月审查**：检查是否有新的规范需要自动化检查
- **每季度更新**：根据团队反馈优化错误消息和修复建议
- **每半年评估**：评估检查脚本的性能和有效性

### 处理误报

如果检查脚本产生误报：

1. **评估规则**：检查规则是否过于严格
2. **白名单机制**：考虑添加白名单支持
3. **改进检测**：优化正则表达式或检查逻辑
4. **文档说明**：在规范文档中说明特殊场景

### 版本控制

检查脚本应纳入版本控制：
- 脚本修改需要通过 Code Review
- 重大变更需要更新文档
- 保持脚本向后兼容（或提供迁移指南）

## 总结

本 CI 检查规范定义了：
1. **检查脚本列表**：Service 层错误检查、注释路径检查、统一检查
2. **脚本规范**：输出格式、错误消息、Shell 兼容性
3. **CI 集成**：GitHub Actions、本地使用、Pre-commit Hook
4. **扩展性设计**：添加新规则的步骤和示例
5. **性能优化**：并行执行、增量检查
6. **测试策略**：通过/失败/白名单/边界情况
7. **维护指南**：定期审查、处理误报、版本控制

这些脚本确保代码质量和规范一致性，支持自动化检查和团队协作。