ccdi/assets/implementation/scripts/README_staff_enterprise_relation_test.md

# 员工企业关系管理测试脚本使用说明

## 一、测试脚本文件

本项目提供了两个版本的测试脚本：

1. **Bash版本** (推荐用于Linux/Mac/Git Bash)
    - 文件: `test_staff_enterprise_relation_complete.sh`
    - 位置: `D:\ccdi\ccdi\doc\implementation\scripts\`

2. **Batch版本** (用于Windows CMD)
    - 文件: `test_staff_enterprise_relation_complete.bat`
    - 位置: `D:\ccdi\ccdi\doc\implementation\scripts\`

## 二、测试环境要求

### 1. 后端服务

- **后端服务必须启动**: Spring Boot应用运行在 `http://localhost:8080`
- **数据库连接正常**: MySQL数据库可访问
- **Redis服务正常**: Redis用于异步导入状态存储

### 2. 测试账号

- 用户名: `admin`
- 密码: `admin123`
- 接口: `/login/test`

## 三、测试脚本功能

### 测试覆盖的接口

| 序号 | 测试项    | 接口路径                                                      | 说明        |
|----|--------|-----------------------------------------------------------|-----------|
| 1  | 登录     | POST /login/test                                          | 获取Token   |
| 2  | 查询列表   | GET /ccdi/staffEnterpriseRelation/list                    | 分页查询      |
| 3  | 新增     | POST /ccdi/staffEnterpriseRelation                        | 新增记录      |
| 4  | 查询详情   | GET /ccdi/staffEnterpriseRelation/{id}                    | 根据ID查询    |
| 5  | 修改     | PUT /ccdi/staffEnterpriseRelation                         | 修改记录      |
| 6  | 删除     | DELETE /ccdi/staffEnterpriseRelation/{ids}                | 删除记录      |
| 7  | 下载模板   | POST /ccdi/staffEnterpriseRelation/importTemplate         | 下载Excel模板 |
| 8  | 导入数据   | POST /ccdi/staffEnterpriseRelation/importData             | 异步导入      |
| 9  | 查询导入状态 | GET /ccdi/staffEnterpriseRelation/importStatus/{taskId}   | 轮询状态      |
| 10 | 查询失败记录 | GET /ccdi/staffEnterpriseRelation/importFailures/{taskId} | 分页查询      |
| 11 | 导出数据   | POST /ccdi/staffEnterpriseRelation/export                 | 导出Excel   |

### 测试数据

**新增测试数据**:

```json
{
    "personId": "110101199001011234",
    "personName": "张三",
    "socialCreditCode": "91110000123456789X",
    "enterpriseName": "测试技术有限公司",
    "relationPersonPost": "技术总监",
    "isEmployee": 0,
    "isEmpFamily": 1,
    "isCustomer": 0,
    "isCustFamily": 0,
    "status": 1,
    "dataSource": "MANUAL",
    "remark": "测试新增"
}
```

## 四、使用方法

### 方法1: Bash版本 (推荐)

#### Windows (Git Bash)

```bash
# 进入脚本目录
cd D:/ccdi/ccdi/doc/implementation/scripts

# 添加执行权限（首次运行）
chmod +x test_staff_enterprise_relation_complete.sh

# 运行测试
./test_staff_enterprise_relation_complete.sh
```

#### Linux/Mac

```bash
# 进入脚本目录
cd /path/to/ccdi/doc/implementation/scripts

# 添加执行权限（首次运行）
chmod +x test_staff_enterprise_relation_complete.sh

# 运行测试
./test_staff_enterprise_relation_complete.sh
```

### 方法2: Batch版本 (Windows CMD)

```cmd
# 进入脚本目录
cd D:\ccdi\ccdi\doc\implementation\scripts

# 运行测试
test_staff_enterprise_relation_complete.bat
```

## 五、测试输出

### 1. 控制台输出

测试脚本会实时输出测试进度和结果：

```
========================================
员工企业关系管理完整测试
测试时间: 2026-02-09 16:30:00
========================================

[TEST] 登录获取Token...
[INFO] 登录成功，Token: eyJhbGciOiJIUzI1NiJ9...

[TEST] 测试1: 查询员工企业关系列表...
{"code":200,"msg":"查询成功",...}
[INFO] ✓ 测试通过: 查询列表成功

[TEST] 测试2: 新增员工企业关系...
{"code":200,"msg":"操作成功",...}
[INFO] ✓ 测试通过: 新增员工企业关系成功
[INFO] 获取到新增的记录ID: 123

...

========================================
测试总结
========================================
总测试数: 10
通过: 10
失败: 0
成功率: 100.00%
========================================

[INFO] 所有测试通过！
```

### 2. 测试报告文件

测试报告会保存在:

```
D:\ccdi\ccdi\doc\implementation\scripts\test_output\test_staff_enterprise_relation_YYYYMMDD_HHMMSS.txt
```

报告内容包含:

- 每个测试的详细响应
- 测试通过/失败统计
- 成功率计算
- 错误详情（如果有）

### 3. 下载的文件

测试过程中会下载以下文件到 `test_output` 目录:

| 文件名                        | 说明   | 测试项  |
|----------------------------|------|------|
| test6_import_template.xlsx | 导入模板 | 测试6  |
| test10_export.xlsx         | 导出数据 | 测试10 |

## 六、高级测试

### 测试导入功能

默认情况下，导入功能测试被注释掉了，因为需要准备Excel文件。要测试导入功能：

1. **准备测试Excel文件**

下载模板后，填充测试数据：

```bash
# 下载模板
./test_staff_enterprise_relation_complete.sh

# 编辑下载的模板文件
# doc/implementation/scripts/test_output/test6_import_template.xlsx
```

2. **启用导入测试**

编辑 `test_staff_enterprise_relation_complete.sh`，取消注释以下部分：

```bash
# 测试7-9: 导入功能（需要Excel文件）
EXCEL_FILE="doc/implementation/scripts/test_output/test_staff_enterprise_relation_import.xlsx"
TASK_ID=$(test_import "$TOKEN" "$EXCEL_FILE")
echo "" | tee -a "$REPORT_FILE"

# 等待导入完成
sleep 5

# 测试8: 查询导入状态
test_import_status "$TOKEN" "$TASK_ID"
echo "" | tee -a "$REPORT_FILE"

# 测试9: 查询导入失败记录
test_import_failures "$TOKEN" "$TASK_ID"
echo "" | tee -a "$REPORT_FILE"
```

3. **运行完整测试**

```bash
./test_staff_enterprise_relation_complete.sh
```

### 修改测试数据

编辑脚本中的测试数据：

```bash
# 测试2: 新增员工企业关系
local add_data=$(cat <<EOF
{
    "personId": "YOUR_PERSON_ID",
    "personName": "YOUR_NAME",
    "socialCreditCode": "YOUR_CREDIT_CODE",
    ...
}
EOF
)
```

### 修改服务器地址

如果后端服务不在 `localhost:8080`，修改脚本配置：

```bash
BASE_URL="http://your-server:port"
```

## 七、故障排查

### 问题1: 登录失败

**症状**: `[ERROR] 登录失败，无法获取Token`

**解决方案**:

1. 检查后端服务是否启动: `http://localhost:8080`
2. 检查登录接口是否可用: `/login/test`
3. 检查用户名密码是否正确: `admin/admin123`

### 问题2: 接口返回401

**症状**: `{"code":401,"msg":"请求访问：/ccdi/staffEnterpriseRelation/list，认证失败，无法访问系统资源"}`

**解决方案**:

1. 检查Token是否正确获取
2. 检查Token是否过期
3. 检查权限配置是否正确

### 问题3: 接口返回403

**症状**: `{"code":403,"msg":"没有权限，请联系管理员授权"}`

**解决方案**:

1. 检查用户是否有对应的权限
2. 检查菜单表中是否配置了该模块的权限
3. 检查角色权限分配

### 问题4: 导入测试失败

**症状**: 导入接口调用失败或状态查询失败

**解决方案**:

1. 检查Redis服务是否启动
2. 检查异步任务是否正常执行
3. 查看后端日志是否有异常
4. 确认Excel文件格式是否正确

### 问题5: Batch版本运行出错

**症状**: Windows批处理脚本运行异常

**解决方案**:

1. 建议使用Git Bash运行Bash版本
2. 或者使用PowerShell运行Bash版本
3. Batch版本功能有限，仅用于快速测试

## 八、注意事项

1. **测试数据清理**: 测试会创建真实数据，测试完成后建议手动清理
2. **并发限制**: 不要同时运行多个测试脚本
3. **数据库状态**: 确保数据库中没有与测试数据冲突的记录
4. **网络延迟**: 导入测试需要等待异步任务完成，脚本中设置了sleep时间
5. **文件权限**: 确保脚本有执行权限和文件写入权限

## 九、扩展测试

### 编写自定义测试

参考现有测试函数，编写新的测试函数：

```bash
test_custom() {
    local token=$1
    local param1=$2

    log_test "测试: 自定义测试..."

    local response=$(curl -s -X GET "$BASE_URL/ccdi/staffEnterpriseRelation/custom?param=$param1" \
        -H "Authorization: Bearer $token")

    echo "$response" | tee -a "$REPORT_FILE"

    if echo "$response" | grep -q '"code":200'; then
        record_pass "自定义测试成功"
    else
        record_fail "自定义测试失败"
    fi
}
```

### 集成到CI/CD

可以将测试脚本集成到CI/CD流程中：

```yaml
# .gitlab-ci.yml 示例
test:
  script:
    - cd doc/implementation/scripts
    - chmod +x test_staff_enterprise_relation_complete.sh
    - ./test_staff_enterprise_relation_complete.sh
  only:
    - dev
    - master
```

## 十、技术支持

如有问题，请查看：

1. **一致性校验报告**: `doc/implementation/reports/staff-enterprise-relation-consistency-check.md`
2. **API文档**: `doc/api-docs/api/`
3. **数据库文档**: `doc/database-docs/`
4. **后端日志**: 查看Spring Boot应用日志

---

**文档版本**: v1.0
**更新时间**: 2026-02-09
**维护人**: Claude Subagent