# 设计文档

## 概述

兵团训练物资管控系统是一个基于分层架构的Web管理平台，采用.NET 8后端、Vue3+ElementPlus前端和SQL Server数据库构建。系统实现了四级组织结构（师团→团→营→连），具备基于角色的访问控制、自动数据分发和审批工作流功能。

系统架构遵循自上而下分配和自下而上上报的模式，上级组织单位创建和分发资源配额，下级单位上报实际完成数据，数据通过组织层级向上流动。

## 架构设计

### 系统架构

```mermaid
graph TB
    subgraph "前端层"
        UI[Vue3 + ElementPlus 界面]
        Auth[认证模块]
        Router[Vue路由]
    end
    
    subgraph "后端层"
        API[ASP.NET Core Web API]
        Auth_BE[认证服务]
        Alloc[配额分配服务]
        Personnel[人员管理服务]
        Approval[审批工作流服务]
    end
    
    subgraph "数据层"
        DB[(SQL Server 数据库)]
        Audit[审计日志表]
    end
    
    UI --> API
    Auth --> Auth_BE
    API --> DB
    API --> Audit
```

### 组织层级模型

```mermaid
graph TD
    Division[师团] --> Regiment1[团1]
    Division --> Regiment2[团N]
    Regiment1 --> Battalion1[营1]
    Regiment1 --> Battalion2[营2]
    Battalion1 --> Company1[连1]
    Battalion1 --> Company2[连2]
```

### 数据流架构

```mermaid
sequenceDiagram
    participant D as 师团
    participant R as 团
    participant B as 营
    participant C as 连
    
    Note over D,C: 配额分配 (自上而下)
    D->>R: 创建并分发配额
    R->>B: 转发配额
    B->>C: 分发给连队
    
    Note over D,C: 上报流程 (自下而上)
    C->>B: 提交实际完成情况
    B->>R: 汇总并上报
    R->>D: 最终上报
```

## 组件和接口

### 核心组件

#### 1. 认证与授权模块
- **目的**: 管理用户认证和基于角色的访问控制
- **核心类**: `AuthenticationService`, `AuthorizationHandler`, `OrganizationalRole`
- **职责**:
  - 用户登录/登出
  - 基于角色的权限执行
  - 组织层级验证

#### 2. 组织管理模块
- **目的**: 管理四级组织结构
- **核心类**: `OrganizationService`, `OrganizationalUnit`, `HierarchyValidator`
- **职责**:
  - 组织单位创建和管理
  - 层级关系维护
  - 基于组织结构的账户生成

#### 3. 物资配额模块
- **目的**: 处理训练物资配额和分发
- **核心类**: `AllocationService`, `MaterialAllocation`, `AllocationDistributor`
- **职责**:
  - 物资类别管理
  - 配额创建和验证
  - 自动分发给下级单位

#### 4. 上报模块
- **目的**: 管理实际完成情况上报和数据汇总
- **核心类**: `ReportingService`, `CompletionReport`, `DataAggregator`
- **职责**:
  - 完成情况数据提交
  - 自动完成率计算
  - 跨组织层级数据汇总

#### 5. 人员管理模块
- **目的**: 处理人员信息和审批工作流
- **核心类**: `PersonnelService`, `Personnel`, `ApprovalWorkflow`
- **职责**:
  - 人员数据提交和存储
  - 照片和文档管理
  - 基于审批层级的人员等级分配

#### 6. 审批工作流模块
- **目的**: 管理修改和人员的审批流程
- **核心类**: `WorkflowService`, `ApprovalRequest`, `WorkflowState`
- **职责**:
  - 修改请求路由
  - 审批/拒绝处理
  - 审计跟踪维护

### API接口设计

#### 认证端点
```
POST /api/admin/auth/login
POST /api/admin/auth/logout
GET  /api/admin/auth/profile
```

#### 组织管理
```
GET    /api/admin/organizations
POST   /api/admin/organizations
GET    /api/admin/organizations/{id}/subordinates
POST   /api/admin/organizations/{id}/accounts
```

#### 物资配额
```
GET    /api/admin/allocations
POST   /api/admin/allocations
PUT    /api/admin/allocations/{id}
DELETE /api/admin/allocations/{id}
GET    /api/admin/allocations/{id}/distribution
```

#### 上报管理
```
GET    /api/admin/reports
POST   /api/admin/reports
PUT    /api/admin/reports/{id}
GET    /api/admin/reports/aggregated
```

#### 人员管理
```
GET    /api/admin/personnel
POST   /api/admin/personnel
PUT    /api/admin/personnel/{id}
POST   /api/admin/personnel/{id}/approve
POST   /api/admin/personnel/{id}/reject
```

## 数据模型

### 核心实体

#### 组织单位 (OrganizationalUnit)
```csharp
public class OrganizationalUnit
{
    public int Id { get; set; }
    public string Name { get; set; }
    public OrganizationalLevel Level { get; set; }
    public int? ParentId { get; set; }
    public OrganizationalUnit Parent { get; set; }
    public List<OrganizationalUnit> Children { get; set; }
    public List<UserAccount> Accounts { get; set; }
    public DateTime CreatedAt { get; set; }
}

public enum OrganizationalLevel
{
    Division = 1,    // 师团
    Regiment = 2,    // 团
    Battalion = 3,   // 营
    Company = 4      // 连
}
```

#### 物资配额 (MaterialAllocation)
```csharp
public class MaterialAllocation
{
    public int Id { get; set; }
    public string Category { get; set; }        // 类别
    public string MaterialName { get; set; }    // 弹药/器材名称
    public string Unit { get; set; }            // 计量单位
    public decimal TotalQuota { get; set; }     // 总训练指标
    public int CreatedByUnitId { get; set; }
    public OrganizationalUnit CreatedByUnit { get; set; }
    public List<AllocationDistribution> Distributions { get; set; }
    public DateTime CreatedAt { get; set; }
}
```

#### 配额分配 (AllocationDistribution)
```csharp
public class AllocationDistribution
{
    public int Id { get; set; }
    public int AllocationId { get; set; }
    public MaterialAllocation Allocation { get; set; }
    public int TargetUnitId { get; set; }
    public OrganizationalUnit TargetUnit { get; set; }
    public decimal UnitQuota { get; set; }          // 单位指标
    public decimal? ActualCompletion { get; set; }  // 单位完成
    public decimal CompletionRate => ActualCompletion.HasValue ? ActualCompletion.Value / UnitQuota : 0; // 完成率
    public DateTime? ReportedAt { get; set; }
    public int? ReportedByUserId { get; set; }
}
```

#### 人员 (Personnel)
```csharp
public class Personnel
{
    public int Id { get; set; }
    public string Name { get; set; }                    // 姓名
    public string PhotoPath { get; set; }               // 照片路径
    public string Position { get; set; }                // 职位
    public string Rank { get; set; }                    // 军衔
    public string Gender { get; set; }                  // 性别
    public string IdNumber { get; set; }                // 身份证号
    public string ProfessionalTitle { get; set; }       // 专业职位
    public string EducationLevel { get; set; }          // 文化程度
    public int Age { get; set; }                        // 年龄
    public decimal Height { get; set; }                 // 身高
    public string ContactInfo { get; set; }             // 联系方式
    public string Hometown { get; set; }                // 籍贯
    public string TrainingParticipation { get; set; }   // 参加培训情况
    public string Achievements { get; set; }            // 取得成绩
    public string SupportingDocuments { get; set; }     // 佐证材料
    public int SubmittedByUnitId { get; set; }
    public OrganizationalUnit SubmittedByUnit { get; set; }
    public PersonnelLevel? ApprovedLevel { get; set; }
    public int? ApprovedByUnitId { get; set; }
    public OrganizationalUnit ApprovedByUnit { get; set; }
    public PersonnelStatus Status { get; set; }
    public DateTime SubmittedAt { get; set; }
    public DateTime? ApprovedAt { get; set; }
}

public enum PersonnelLevel
{
    Company = 4,     // 连级人才
    Battalion = 3,   // 营级人才
    Regiment = 2,    // 团级人才
    Division = 1     // 师级人才
}

public enum PersonnelStatus
{
    Pending,    // 待审批
    Approved,   // 已批准
    Rejected    // 已拒绝
}
```

#### 审批请求 (ApprovalRequest)
```csharp
public class ApprovalRequest
{
    public int Id { get; set; }
    public ApprovalRequestType Type { get; set; }
    public int RequestedByUserId { get; set; }
    public UserAccount RequestedByUser { get; set; }
    public string Reason { get; set; }              // 修改原因
    public string OriginalData { get; set; }        // 原始数据
    public string RequestedChanges { get; set; }     // 请求的更改
    public ApprovalStatus Status { get; set; }
    public int? ReviewedByUserId { get; set; }
    public UserAccount ReviewedByUser { get; set; }
    public string ReviewComments { get; set; }       // 审批意见
    public DateTime RequestedAt { get; set; }
    public DateTime? ReviewedAt { get; set; }
}

public enum ApprovalRequestType
{
    AllocationModification,  // 配额修改
    ReportModification,      // 上报修改
    PersonnelModification    // 人员修改
}

public enum ApprovalStatus
{
    Pending,    // 待审批
    Approved,   // 已批准
    Rejected    // 已拒绝
}
```

### 数据库架构关系

```mermaid
erDiagram
    OrganizationalUnit ||--o{ OrganizationalUnit : "上下级关系"
    OrganizationalUnit ||--o{ UserAccount : "拥有账户"
    OrganizationalUnit ||--o{ MaterialAllocation : "创建配额"
    OrganizationalUnit ||--o{ Personnel : "提交人员"
    
    MaterialAllocation ||--o{ AllocationDistribution : "分配给"
    AllocationDistribution }o--|| OrganizationalUnit : "目标单位"
    
    Personnel }o--|| OrganizationalUnit : "审批单位"
    
    UserAccount ||--o{ ApprovalRequest : "发起请求"
    UserAccount ||--o{ ApprovalRequest : "审批请求"
```

## 正确性属性

*属性是系统所有有效执行中都应该保持为真的特征或行为——本质上是关于系统应该做什么的正式声明。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。*

### 属性反思

在分析所有验收标准后，可以合并几个属性以消除冗余：

- 与组织层级访问控制相关的属性（1.3、4.4、8.1、8.2、8.4）可以合并为综合的基于层级的访问控制属性
- 关于审计跟踪维护的属性（1.4、5.4、6.4）可以合并为通用的审计日志属性
- 关于数据显示要求的属性（3.1、4.1、4.2、8.3）可以合并为综合的数据可见性属性
- 关于工作流路由的属性（5.2、6.3）可以合并为通用的工作流路由属性

### 核心属性

**属性1：组织层级访问控制**
*对于任何*用户和任何数据资源，只有当用户的组织层级等于或高于资源的组织层级时，才应授予访问权限
**验证需求：需求1.3、4.4、8.1、8.2、8.4**

**属性2：配额总和验证**
*对于任何*带有单位配额的物资配额，所有单位配额的总和不应超过总配额指标
**验证需求：需求2.3**

**属性3：完成率计算一致性**
*对于任何*具有实际完成和单位指标的配额分配，完成率应等于实际完成除以单位指标
**验证需求：需求3.3**

**属性4：层级数据汇总**
*对于任何*组织单位，显示的汇总数据应等于所有直接下级单位数据的总和
**验证需求：需求3.4、4.1**

**属性5：工作流状态修改限制**
*对于任何*已提交的报告或人员记录，一旦被上级组织层级批准，应阻止直接修改
**验证需求：需求5.1、5.5**

**属性6：人员等级分配一致性**
*对于任何*已批准的人员记录，分配的人员等级应与批准单位的组织层级完全对应
**验证需求：需求7.2、7.3、7.5**

**属性7：必填字段验证**
*对于任何*数据提交（配额、报告或人员），所有必填字段必须存在且有效，才能接受提交
**验证需求：需求2.2、6.1**

**属性8：自动数据分发**
*对于任何*创建的配额，应自动为所有指定的目标组织单位创建分配记录
**验证需求：需求2.4**

**属性9：审计跟踪完整性**
*对于任何*修改数据的系统操作，应创建相应的审计日志条目，包含完整的操作详情
**验证需求：需求1.4、5.4、6.4**

**属性10：组织层级分类**
*对于任何*组织单位，应被分类为四个有效层级中的一个：师团、团、营或连
**验证需求：需求1.2**

## 错误处理

### 输入验证错误
- **无效组织结构**：当检测到组织层级违规时，返回结构化错误消息
- **配额验证失败**：当单位配额超过总配额指标时，提供清晰的反馈
- **缺少必填字段**：对不完整的提交返回字段特定的验证错误
- **无效文件格式**：拒绝不符合2寸格式要求的照片上传，并提供描述性错误消息

### 授权错误
- **权限不足**：当用户尝试未授权操作时，返回HTTP 403并说明具体权限要求
- **跨层级访问违规**：阻止并记录尝试访问组织层级外数据的行为
- **工作流状态违规**：阻止并报告尝试在没有适当工作流的情况下修改已批准记录的行为

### 业务逻辑错误
- **循环组织引用**：检测并防止组织单位成为自己的上级或下级
- **重复人员记录**：使用身份证号和其他唯一标识符验证现有人员
- **无效审批工作流**：确保审批请求路由到适当的上级单位

### 系统错误
- **数据库连接失败**：为数据库连接问题实施重试逻辑和优雅降级
- **文件上传失败**：处理照片和支持文档的存储失败，并进行适当的回滚
- **审计日志失败**：确保即使审计日志临时失败，系统操作也能继续，并具有恢复机制

## 测试策略

### 双重测试方法

系统将采用单元测试和基于属性的测试来确保全面覆盖：

- **单元测试**验证特定示例、边界情况和错误条件
- **属性测试**验证应在所有输入中保持的通用属性
- 两者结合提供全面覆盖：单元测试捕获具体错误，属性测试验证一般正确性

### 单元测试要求

单元测试将专注于：
- 演示每个组件正确行为的特定示例
- 组织层级和数据访问之间的集成点
- 具有已知输入和预期输出的错误处理场景
- 工作流状态转换和审批流程

### 基于属性的测试要求

**测试框架**：系统将使用**.NET的FsCheck**进行基于属性的测试，配置为每个属性测试运行最少100次迭代。

每个基于属性的测试将：
- 使用明确引用正确性属性的注释进行标记：`**功能：military-training-material-management，属性{编号}：{属性文本}**`
- 在域约束内生成随机但有效的测试数据
- 验证指定属性在所有生成的输入中都成立
- 专注于测试正确性属性部分中定义的通用属性

**属性测试实现要求**：
- 每个正确性属性必须由单个基于属性的测试实现
- 测试应生成现实的组织结构、配额和人员数据
- 智能生成器应将输入约束到有效的组织层级和业务规则
- 属性测试不应使用模拟，而应针对真实的业务逻辑实现进行测试

### 集成测试

集成测试将验证：
- 从配额创建到完成上报的端到端工作流
- 认证、授权和业务逻辑之间的跨模块交互
- 复杂操作中的数据库事务完整性
- 各种认证和授权场景下的API端点行为

### 性能测试

性能测试将验证：
- 大型组织结构中层级数据汇总的响应时间
- 复杂组织层级查询的数据库查询性能
- 人员照片和支持文档的文件上传性能
- 军事组织典型使用模式下的并发用户访问模式