# 组织机构导入验证设计方案

**日期**: 2026-02-07
**状态**: 设计完成
**目标**: 确保 org.yml 数据完整、准确地导入到 SQLite，支持幂等性和完整性验证

## 一、背景与目标

### 问题描述

项目完成了从 YAML/Excel 到 SQLite 的数据模型迁移，但缺乏完善的验证机制，无法确保：
1. **数量完整性** - YAML 中的数据是否全部导入
2. **关系正确性** - 时间范围内的关系状态是否正确
3. **数据去重** - 多次导入不会产生重复数据
4. **原子性** - 导入过程遇到错误能正确回滚

### 验证目标

- ✅ **数量验证**: 员工、部门、关系数量与 YAML 一致
- ✅ **关系验证**: 所有时间点的组织关系正确无误
- ✅ **幂等性**: 多次导入不会产生重复数据
- ✅ **冲突检测**: 数据不一致时报错而非静默覆盖
- ✅ **可视化报告**: 提供 Markdown + JSON 双格式报告

## 二、整体架构

### 核心组件

```
┌─────────────────────────────────────────────────────────────┐
│                         org.yml                              │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │ OrganizationImportService     │ 【增强幂等性】
         │ - 唯一性检查                    │
         │ - 冲突检测                      │
         │ - 事务保证                      │
         └───────────────┬───────────────┘
                         │
                         ▼
                 ┌───────────────┐
                 │  SQLite 数据库 │
                 └───────┬───────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │  OrganizationVerifier         │ 【新增验证器】
         │  - verifyEmployees()          │
         │  - verifyDepartments()        │
         │  - verifyDepartmentRelations()│
         │  - verifyEmployeeDeptRelations()│
         │  - verifyAtDate()             │
         └───────────────┬───────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │   VerificationReport          │ 【新增报告类】
         │   - CategoryResult × 4        │
         │   - Summary                   │
         └───────────────┬───────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │    ReportGenerator            │ 【新增生成器】
         │    - generateMarkdown()       │
         │    - generateJson()           │
         └───────────────────────────────┘
```

## 三、幂等性保证设计

### 3.1 唯一性判断规则

#### 员工（EmployeeEntity）
```
唯一性标识: 姓名 + 所有别名
判断逻辑: 如果姓名或任一别名匹配已有员工，视为同一人

示例:
  YAML: "潘力;潘总"
  数据库已有: name="潘力", aliases=["潘总"]
  结果: 视为同一人，跳过
```

#### 部门（DepartmentEntity）
```
唯一性标识: 部门名称
判断逻辑: 部门名称完全匹配

示例:
  YAML: "产品研发中心"
  数据库已有: name="产品研发中心"
  结果: 视为同一部门，跳过
```

#### 部门关系（DepartmentRelationEntity）
```
唯一性标识: 父部门 + 子部门 + 开始日期
判断逻辑: 三者都匹配视为同一关系

示例:
  YAML: "产品研发中心;测试部;2012-06-01"
  数据库已有: parent="产品研发中心", child="测试部", startDate="2012-06-01"
  结果: 视为同一关系

冲突检测:
  - 如果唯一性标识相同，但 endDate 不同 → 报错（数据冲突）
```

#### 人员部门关系（EmployeeDepartmentRelationEntity）
```
唯一性标识: 员工 + 部门 + 开始日期
判断逻辑: 三者都匹配视为同一关系

冲突检测:
  - 如果唯一性标识相同，但 endDate 不同 → 报错（数据冲突）
```

### 3.2 导入策略

```java
对于每条记录：
  1. 查询是否已存在（根据唯一性规则）

  2. 如果存在且完全一致：
     ✅ 跳过（记录到 skipped 计数）

  3. 如果存在但数据不一致：
     ❌ 报错（记录到 conflicts 列表）
     ❌ 事务回滚，停止导入

  4. 如果不存在：
     ✅ 插入新记录（记录到 inserted 计数）

遇到任何冲突立即停止，保证数据一致性
```

### 3.3 ImportResult 扩展

```java
@Data
@Builder
public class ImportResult {
    private boolean success;              // 是否成功
    private int insertedCount;            // 新插入的记录数
    private int skippedCount;             // 跳过的记录数（完全相同）
    private List<DataConflict> conflicts; // 数据冲突列表
    private List<String> errors;          // 其他错误信息
}

@Data
@Builder
public class DataConflict {
    private String type;        // 冲突类型: "DepartmentRelation" / "EmployeeDepartmentRelation"
    private String key;         // 唯一标识: "产品研发中心 -> 测试部, 2012-06-01"
    private String yamlValue;   // YAML 中的值
    private String dbValue;     // 数据库中的值
    private String field;       // 冲突字段: "endDate"
}
```

## 四、完整时间线验证设计

### 4.1 时间点提取策略

**从 YAML 和数据库中提取所有关键时间点**

```
关键时间点包括:
1. 所有关系的开始日期（startDate）
2. 所有关系的结束日期（endDate）
3. 开始日期的前一天（验证关系未生效）
4. 结束日期的后一天（验证关系已结束）
```

**示例**:
```
关系1: 产品研发中心 -> 测试部, 2012-06-01 ~ 无结束
提取时间点:
  - 2012-05-31 (前一天，关系应不存在)
  - 2012-06-01 (开始日期，关系应存在)

关系2: 产品研发中心 -> 大数据平台开发部, 2012-01-01 ~ 2023-12-17
提取时间点:
  - 2011-12-31 (前一天，关系应不存在)
  - 2012-01-01 (开始，关系应存在)
  - 2023-12-17 (结束，关系应存在)
  - 2023-12-18 (后一天，关系应不存在)
```

### 4.2 验证逻辑

```java
对于每个时间点 T:
  1. 查询 YAML: 哪些关系在 T 应该有效
     规则: startDate <= T && (endDate == null || endDate >= T)

  2. 查询数据库: 哪些关系在 T 实际有效
     使用同样的查询规则

  3. 对比结果:
     - 缺失 (Missing): YAML 有但数据库没有
     - 多余 (Extra): 数据库有但 YAML 没有
     - 匹配 (Match): 两边都有且一致

  4. 记录差异到报告
```

### 4.3 验证覆盖范围

```
验证项目:
✅ 部门关系在所有关键时间点的正确性
✅ 人员部门关系在所有关键时间点的正确性
✅ 关系的开始日期和结束日期准确性
✅ 边界条件（前一天、后一天）的正确性
```

## 五、验证报告设计

### 5.1 报告数据结构

```java
@Data
@Builder
public class VerificationReport {
    private LocalDateTime verificationTime;  // 验证时间
    private boolean overallSuccess;          // 总体是否通过

    // 四大类验证结果
    private CategoryResult employees;
    private CategoryResult departments;
    private CategoryResult departmentRelations;
    private CategoryResult employeeDepartmentRelations;

    // 汇总统计
    private Summary summary;
}

@Data
@Builder
public class CategoryResult {
    private String category;           // 类别名称
    private boolean passed;            // 是否通过

    // 数量统计
    private int yamlCount;             // YAML 中的数量
    private int dbCount;               // 数据库中的数量
    private boolean countMatch;        // 数量是否匹配

    // 差异明细
    private List<String> missing;      // 数据库缺失的记录
    private List<String> extra;        // 数据库多余的记录
    private List<FieldMismatch> mismatches; // 字段不匹配

    // 时间点验证结果（仅关系类）
    private List<TimePointIssue> timePointIssues;
}

@Data
@Builder
public class FieldMismatch {
    private String recordKey;          // 记录标识
    private String field;              // 字段名
    private String yamlValue;          // YAML 中的值
    private String dbValue;            // 数据库中的值
}

@Data
@Builder
public class TimePointIssue {
    private LocalDate date;            // 时间点
    private String issueType;          // "MISSING" / "EXTRA"
    private String relation;           // 关系描述
}

@Data
@Builder
public class Summary {
    private int totalChecks;           // 总检查项
    private int passedChecks;          // 通过的检查
    private int failedChecks;          // 失败的检查
    private List<String> criticalIssues; // 关键问题列表
}
```

### 5.2 Markdown 报告格式

```markdown
# 组织机构导入验证报告

**验证时间**: 2026-02-07 15:30:00
**总体结果**: ✅ 通过 / ❌ 失败

---

## 一、员工验证

- **YAML 数量**: 200
- **数据库数量**: 200
- **状态**: ✅ 通过

---

## 二、部门验证

- **YAML 数量**: 40
- **数据库数量**: 40
- **状态**: ✅ 通过

---

## 三、部门关系验证

- **YAML 数量**: 95
- **数据库数量**: 94
- **状态**: ❌ 失败

### 缺失记录
- 敏捷团队 -> 风暴队, 2025-11-17 ~ null

### 时间点验证问题
- **2025-11-17**: ❌ 缺少关系 "敏捷团队 -> 风暴队"
- **2025-11-18**: ❌ 缺少关系 "敏捷团队 -> 风暴队"

---

## 四、人员部门关系验证

- **YAML 数量**: 880
- **数据库数量**: 880
- **状态**: ✅ 通过

---

## 汇总统计

- **总检查项**: 1215
- **通过**: 1214
- **失败**: 1
- **通过率**: 99.92%

### 关键问题
1. 部门关系缺失: "敏捷团队 -> 风暴队, 2025-11-17 ~ null"
```

### 5.3 JSON 报告格式

```json
{
  "verificationTime": "2026-02-07T15:30:00",
  "overallSuccess": false,
  "employees": {
    "category": "员工",
    "passed": true,
    "yamlCount": 200,
    "dbCount": 200,
    "countMatch": true,
    "missing": [],
    "extra": [],
    "mismatches": []
  },
  "departmentRelations": {
    "category": "部门关系",
    "passed": false,
    "yamlCount": 95,
    "dbCount": 94,
    "countMatch": false,
    "missing": ["敏捷团队 -> 风暴队, 2025-11-17 ~ null"],
    "extra": [],
    "mismatches": [],
    "timePointIssues": [
      {
        "date": "2025-11-17",
        "issueType": "MISSING",
        "relation": "敏捷团队 -> 风暴队"
      }
    ]
  },
  "summary": {
    "totalChecks": 1215,
    "passedChecks": 1214,
    "failedChecks": 1,
    "criticalIssues": [
      "部门关系缺失: 敏捷团队 -> 风暴队, 2025-11-17 ~ null"
    ]
  }
}
```

## 六、测试策略

### 6.1 测试用例

#### 1. 基础导入测试
```java
@Test
void shouldImportOrganizationDataSuccessfully() {
    // 清空数据库
    cleanDatabase();

    // 执行导入
    ImportResult result = importService.importFromYaml("org.yml");

    // 验证结果
    assertThat(result.isSuccess()).isTrue();
    assertThat(result.getInsertedCount()).isGreaterThan(0);
    assertThat(result.getConflicts()).isEmpty();
}
```

#### 2. 幂等性测试
```java
@Test
void shouldBeIdempotentWhenImportingTwice() {
    // 第一次导入
    ImportResult result1 = importService.importFromYaml("org.yml");
    int firstInserted = result1.getInsertedCount();

    // 第二次导入（相同数据）
    ImportResult result2 = importService.importFromYaml("org.yml");

    // 验证幂等性
    assertThat(result2.getInsertedCount()).isEqualTo(0);
    assertThat(result2.getSkippedCount()).isEqualTo(firstInserted);
    assertThat(result2.isSuccess()).isTrue();

    // 验证数据库记录总数不变
    long totalEmployees = employeeRepository.count();
    assertThat(totalEmployees).isEqualTo(200); // 假设 YAML 有 200 个员工
}
```

#### 3. 数据冲突检测测试
```java
@Test
void shouldDetectConflictWhenEndDateDiffers() {
    // 导入原始数据
    importService.importFromYaml("org.yml");

    // 修改某个关系的结束日期
    String modifiedYaml = modifyRelationEndDate("org.yml",
        "产品研发中心;测试部;2012-06-01",
        "2023-12-31"); // 原本无结束日期

    // 再次导入
    ImportResult result = importService.importFromYaml(modifiedYaml);

    // 验证冲突检测
    assertThat(result.isSuccess()).isFalse();
    assertThat(result.getConflicts()).hasSize(1);

    DataConflict conflict = result.getConflicts().get(0);
    assertThat(conflict.getType()).isEqualTo("DepartmentRelation");
    assertThat(conflict.getField()).isEqualTo("endDate");
    assertThat(conflict.getYamlValue()).isEqualTo("2023-12-31");
    assertThat(conflict.getDbValue()).isEqualTo("null");
}
```

#### 4. 完整性验证测试
```java
@Test
void shouldVerifyAllDataCorrectness() {
    // 导入数据
    ImportResult importResult = importService.importFromYaml("org.yml");
    assertThat(importResult.isSuccess()).isTrue();

    // 执行验证
    VerificationReport report = verifier.verify("org.yml");

    // 验证四大类
    assertThat(report.getEmployees().isPassed()).isTrue();
    assertThat(report.getDepartments().isPassed()).isTrue();
    assertThat(report.getDepartmentRelations().isPassed()).isTrue();
    assertThat(report.getEmployeeDepartmentRelations().isPassed()).isTrue();

    // 验证总体结果
    assertThat(report.isOverallSuccess()).isTrue();

    // 生成报告文件
    reportGenerator.generateMarkdown(report, "target/verification-report.md");
    reportGenerator.generateJson(report, "target/verification-report.json");
}
```

#### 5. 时间点验证测试
```java
@Test
void shouldVerifyRelationsAtAllCriticalTimepoints() {
    // 导入数据
    importService.importFromYaml("org.yml");

    // 加载 YAML 数据
    OrganizationData yamlData = yamlDataLoader.load("org.yml");

    // 提取所有关键时间点
    Set<LocalDate> criticalDates = timelineExtractor.extractCriticalDates(yamlData);

    // 对每个时间点验证
    List<String> failures = new ArrayList<>();
    for (LocalDate date : criticalDates) {
        TimePointVerification result = verifier.verifyAtDate(date, yamlData);
        if (!result.isPassed()) {
            failures.add(String.format("%s: %s", date, result.getIssues()));
        }
    }

    // 验证所有时间点都通过
    assertThat(failures)
        .withFailMessage("以下时间点验证失败:\n" + String.join("\n", failures))
        .isEmpty();
}
```

### 6.2 测试数据准备

```java
@SpringBootTest
@Transactional
@TestPropertySource(properties = {
    "spring.datasource.url=jdbc:sqlite::memory:",
    "spring.jpa.hibernate.ddl-auto=create-drop"
})
class OrganizationImportTest {

    @Autowired
    private OrganizationImportService importService;

    @Autowired
    private OrganizationVerifier verifier;

    @Autowired
    private ReportGenerator reportGenerator;

    @BeforeEach
    void setup() {
        // 每个测试前清空数据库
        cleanDatabase();
    }

    private void cleanDatabase() {
        employeeDepartmentRelationRepository.deleteAll();
        departmentRelationRepository.deleteAll();
        employeeRepository.deleteAll();
        departmentRepository.deleteAll();
    }
}
```

## 七、实现计划

### 阶段 1: 增强导入服务
- [ ] 实现唯一性检查逻辑
- [ ] 实现数据冲突检测
- [ ] 扩展 ImportResult 类
- [ ] 添加事务注解

### 阶段 2: 创建验证器
- [ ] 创建 OrganizationVerifier 类
- [ ] 实现四大类验证方法
- [ ] 实现时间点提取逻辑
- [ ] 实现时间点验证方法

### 阶段 3: 创建报告组件
- [ ] 创建报告数据类
- [ ] 创建 ReportGenerator 类
- [ ] 实现 Markdown 生成
- [ ] 实现 JSON 生成

### 阶段 4: 编写测试
- [ ] 基础导入测试
- [ ] 幂等性测试
- [ ] 冲突检测测试
- [ ] 完整性验证测试
- [ ] 时间点验证测试

## 八、使用流程

### 开发阶段
```bash
# 1. 修改 org.yml

# 2. 运行测试
./gradlew test --tests OrganizationImportTest

# 3. 查看报告
cat build/reports/verification-report.md
```

### 手动验证
```java
@SpringBootTest
public class ManualVerification {

    @Autowired
    private OrganizationImportService importService;

    @Autowired
    private OrganizationVerifier verifier;

    @Autowired
    private ReportGenerator reportGenerator;

    @Test
    void manualVerify() {
        // 1. 导入
        ImportResult importResult = importService.importFromYaml("org.yml");
        System.out.println("导入结果: " + importResult);

        // 2. 验证
        VerificationReport report = verifier.verify("org.yml");

        // 3. 生成报告
        reportGenerator.generateMarkdown(report, "verification-report.md");
        reportGenerator.generateJson(report, "verification-report.json");

        // 4. 检查结果
        if (!report.isOverallSuccess()) {
            System.err.println("验证失败，请查看报告: verification-report.md");
        }
    }
}
```

## 九、成功标准

✅ **功能完整性**
- 支持 4 类数据验证（员工、部门、部门关系、人员部门关系）
- 支持完整时间线验证（所有关键时间点）
- 支持幂等性导入（多次导入不重复）
- 支持冲突检测（数据不一致时报错）

✅ **报告质量**
- Markdown 报告清晰易读
- JSON 报告结构完整
- 差异明细准确定位问题

✅ **测试覆盖**
- 单元测试覆盖所有核心逻辑
- 集成测试验证端到端流程
- 所有测试通过

✅ **代码质量**
- 符合项目编码规范
- 有完善的注释和文档
- 通过代码审查

---

**文档版本**: 1.0
**最后更新**: 2026-02-07
**维护者**: User & Claude