# 数字债权服务系统首页设计文档

## 概览

数字债权服务系统首页设计旨在创建一个现代化、响应式的业务仪表板，替换原有的若依框架通用首页。新首页将根据用户角色提供个性化的业务统计、快速操作入口和系统信息展示，突出数字债权服务平台的专业性和易用性。

## 架构

### 组件架构
```
HomePage (主容器)
├── HeaderSection (头部区域)
│   ├── PlatformTitle (平台标题)
│   ├── SystemVersion (系统版本)
│   └── UserWelcome (用户欢迎信息)
├── StatisticsSection (统计面板区域)
│   ├── RoleBasedStats (角色相关统计)
│   ├── BusinessMetrics (业务指标)
│   └── ChartComponents (图表组件)
├── QuickActionsSection (快速操作区域)
│   ├── RoleBasedActions (角色相关操作)
│   └── CommonActions (通用操作)
├── NotificationsSection (通知消息区域)
│   ├── AlertMessages (告警消息)
│   ├── BusinessUpdates (业务更新)
│   └── SystemNotices (系统通知)
└── FooterSection (底部区域)
    ├── TechnicalInfo (技术信息)
    ├── ContactInfo (联系信息)
    └── ResourceLinks (资源链接)
```

### 数据流架构
- **用户认证服务**: 获取当前用户角色和权限信息
- **业务统计服务**: 根据用户角色获取相应的业务数据
- **通知服务**: 获取用户相关的消息和提醒
- **权限控制服务**: 控制功能模块的显示和访问权限

## 组件和接口

### 核心组件

#### 1. HeaderSection 组件
```javascript
// Props 定义
{
  userInfo: {
    id: String,
    name: String,
    role: String,
    company: String,
    lastLoginTime: Date
  },
  systemVersion: String,
  platformTitle: String
}
```

#### 2. StatisticsSection 组件
```javascript
// Props 定义
{
  userRole: String,
  statisticsData: Object // 根据角色包含不同的统计数据
}
```

#### 3. QuickActionsSection 组件
```javascript
// Props 定义
{
  userRole: String,
  permissions: Array,
  actions: Array // QuickAction 对象数组
}

// QuickAction 对象结构
{
  id: String,
  title: String,
  description: String,
  icon: String,
  route: String,
  permission: String
}
```

### API 接口

#### 1. 用户信息接口（使用现有接口）
```javascript
GET /system/user/profile
Response: {
  code: Number,
  data: {
    // 现有用户信息结构，需要适配到首页需求
    userId: Number,
    userName: String,
    nickName: String,
    // 其他现有字段...
  },
  msg: String
}
```

#### 2. 业务统计接口
```javascript
GET /api/dashboard/statistics?role={userRole}
Response: {
  code: Number,
  data: Object, // 根据角色返回不同的统计数据结构
  message: String
}
```

#### 3. 通知消息接口
```javascript
GET /api/notifications/recent?limit=10
Response: {
  code: Number,
  data: Array, // Notification 对象数组
  message: String
}
```

## 数据模型

### 用户角色常量
```javascript
const UserRole = {
  SECURITY_COMPANY: 'security_company',
  CLIENT_COMPANY: 'client_company',
  FINANCIAL_INSTITUTION: 'financial_institution',
  ADMINISTRATOR: 'administrator'
}
```

### 统计数据模型
```javascript
// 安保公司统计数据
{
  totalCredits: Number,
  pendingContracts: Number,
  totalAmount: Number,
  financingApplications: Number,
  recentActivities: Array
}

// 甲方单位统计数据
{
  totalContracts: Number,
  pendingPayments: Number,
  paidAmount: Number,
  upcomingPayments: Array
}

// 金融机构统计数据
{
  pendingApplications: Number,
  approvedAmount: Number,
  riskDistribution: Array,
  marketIndicators: Array
}

// 管理员统计数据
{
  systemHealth: Object,
  userActivity: Object,
  transactionVolume: Object,
  securityEvents: Array
}
```

## 正确性属性

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

### 属性 1: 角色权限一致性
*对于任何*用户和首页显示内容，用户看到的所有功能模块和数据统计都应该与其角色权限完全匹配
**验证: 需求 7.1, 7.2, 7.4**

### 属性 2: 数据访问边界
*对于任何*用户角色和数据查询请求，返回的业务统计数据应该仅包含该用户有权访问的业务范围
**验证: 需求 2.1, 3.1, 4.1, 7.4**

### 属性 3: 响应式布局适配
*对于任何*屏幕尺寸和设备类型，首页布局应该自动调整并保持所有核心功能的可访问性
**验证: 需求 6.1, 6.4**

### 属性 4: 实时数据同步
*对于任何*用户权限变更操作，首页显示的功能模块和数据范围应该立即反映最新的权限状态
**验证: 需求 7.2**

### 属性 5: 安全访问控制
*对于任何*未授权访问尝试，系统应该阻止访问并记录相应的安全日志
**验证: 需求 7.3, 7.5**

### 属性 6: 性能加载要求
*对于任何*首页访问请求，核心内容应该在3秒内完成加载并显示给用户
**验证: 需求 6.5**

### 属性 7: 角色功能入口一致性
*对于任何*用户角色，显示的快速操作入口和功能模块应该与该角色的业务职责完全匹配
**验证: 需求 2.3, 3.3, 4.3, 5.3**

### 属性 8: 响应式交互反馈
*对于任何*用户交互操作，系统应该提供相应的视觉反馈和状态提示
**验证: 需求 6.2**

### 属性 9: 数据范围权限控制
*对于任何*用户查看统计数据的请求，返回的数据应该严格限制在该用户的权限范围内
**验证: 需求 2.1, 3.1, 4.1, 5.1, 7.4**

### 属性 10: 权限变更实时同步
*对于任何*用户权限变更事件，首页显示的功能模块和数据范围应该立即反映最新状态
**验证: 需求 7.2**

## 错误处理

### 1. 数据加载失败
- **场景**: API 请求超时或返回错误
- **处理**: 显示友好的错误提示，提供重试按钮
- **降级**: 显示缓存数据或默认占位内容

### 2. 权限验证失败
- **场景**: 用户权限不足或会话过期
- **处理**: 重定向到登录页面或显示权限不足提示
- **日志**: 记录安全事件日志

### 3. 网络连接异常
- **场景**: 网络中断或服务不可用
- **处理**: 显示离线模式提示，启用本地缓存
- **恢复**: 网络恢复后自动重新加载数据

### 4. 数据格式异常
- **场景**: 后端返回的数据格式不符合预期
- **处理**: 使用数据验证和默认值填充
- **监控**: 发送异常报告给开发团队

## 测试策略

### 单元测试
- 组件渲染测试：验证各个组件能够正确渲染
- 数据处理测试：验证统计数据的计算和格式化
- 权限控制测试：验证基于角色的内容显示逻辑
- API 调用测试：验证接口调用和错误处理

### 集成测试
- 用户角色切换测试：验证不同角色登录后的页面内容
- 数据流测试：验证从 API 获取数据到页面显示的完整流程
- 权限验证测试：验证权限变更后页面内容的实时更新
- 响应式布局测试：验证在不同设备上的显示效果

### 端到端测试
- 用户登录流程测试：验证从登录到首页显示的完整用户体验
- 快速操作测试：验证快速操作按钮的跳转和功能
- 通知消息测试：验证消息提醒的显示和交互
- 性能测试：验证页面加载时间和响应速度

### 属性基础测试
使用 Vitest 和 Vue Test Utils 进行属性基础测试，每个测试运行最少 100 次迭代以确保属性在各种输入下都成立。每个属性基础测试必须使用注释明确引用设计文档中的正确性属性。