f

docs/api/statistics/api_documentation.md

@@ -0,0 +1,603 @@
+# 统计功能API文档
+
+## 概述
+
+统计功能API提供了完整的统计数据分析和管理功能，包括指标管理、实时统计、历史统计、仪表板管理、报告生成、数据导出等功能。
+
+## 基础信息
+
+- **基础URL**: `/api/v1/statistics`
+- **认证方式**: Bearer Token
+- **内容类型**: `application/json`
+- **字符编码**: `UTF-8`
+
+## 认证和权限
+
+### 认证方式
+所有API请求都需要在请求头中包含有效的JWT令牌：
+```
+Authorization: Bearer <your-jwt-token>
+```
+
+### 权限级别
+- **公开访问**: 无需认证的接口
+- **用户权限**: 需要用户或管理员权限
+- **管理员权限**: 仅管理员可访问
+
+## API接口
+
+### 1. 指标管理
+
+#### 1.1 创建统计指标
+- **URL**: `POST /api/v1/statistics/metrics`
+- **权限**: 管理员
+- **描述**: 创建新的统计指标
+
+**请求体**:
+```json
+{
+  "metric_type": "api_calls",
+  "metric_name": "total_count",
+  "dimension": "realtime",
+  "value": 100.0,
+  "metadata": "{\"source\": \"api_gateway\"}",
+  "date": "2024-01-01T00:00:00Z"
+}
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "指标创建成功",
+  "data": {
+    "id": "uuid",
+    "metric_type": "api_calls",
+    "metric_name": "total_count",
+    "dimension": "realtime",
+    "value": 100.0,
+    "metadata": "{\"source\": \"api_gateway\"}",
+    "date": "2024-01-01T00:00:00Z",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+#### 1.2 更新统计指标
+- **URL**: `PUT /api/v1/statistics/metrics`
+- **权限**: 管理员
+- **描述**: 更新现有统计指标的值
+
+**请求体**:
+```json
+{
+  "id": "uuid",
+  "value": 150.0
+}
+```
+
+#### 1.3 删除统计指标
+- **URL**: `DELETE /api/v1/statistics/metrics`
+- **权限**: 管理员
+- **描述**: 删除指定的统计指标
+
+**请求体**:
+```json
+{
+  "id": "uuid"
+}
+```
+
+#### 1.4 获取单个指标
+- **URL**: `GET /api/v1/statistics/metrics/{id}`
+- **权限**: 用户
+- **描述**: 根据ID获取指定的统计指标
+
+#### 1.5 获取指标列表
+- **URL**: `GET /api/v1/statistics/metrics`
+- **权限**: 用户
+- **描述**: 根据条件获取统计指标列表
+
+**查询参数**:
+- `metric_type` (string): 指标类型
+- `metric_name` (string): 指标名称
+- `dimension` (string): 统计维度
+- `start_date` (string): 开始日期 (YYYY-MM-DD)
+- `end_date` (string): 结束日期 (YYYY-MM-DD)
+- `limit` (int): 限制数量 (默认20, 最大1000)
+- `offset` (int): 偏移量 (默认0)
+- `sort_by` (string): 排序字段 (默认created_at)
+- `sort_order` (string): 排序顺序 (默认desc)
+
+### 2. 实时统计
+
+#### 2.1 获取实时指标
+- **URL**: `GET /api/v1/statistics/realtime`
+- **权限**: 公开
+- **描述**: 获取指定类型的实时统计指标
+
+**查询参数**:
+- `metric_type` (string, 必需): 指标类型
+- `time_range` (string): 时间范围 (last_hour, last_day, last_week)
+- `dimension` (string): 统计维度
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "获取实时指标成功",
+  "data": {
+    "metric_type": "api_calls",
+    "metrics": {
+      "total_count": 1000,
+      "success_count": 950,
+      "failed_count": 50,
+      "success_rate": 95.0
+    },
+    "timestamp": "2024-01-01T12:00:00Z",
+    "metadata": {
+      "time_range": "last_hour",
+      "dimension": "realtime"
+    }
+  }
+}
+```
+
+### 3. 历史统计
+
+#### 3.1 获取历史指标
+- **URL**: `GET /api/v1/statistics/historical`
+- **权限**: 公开
+- **描述**: 获取指定时间范围的历史统计指标
+
+**查询参数**:
+- `metric_type` (string, 必需): 指标类型
+- `metric_name` (string): 指标名称
+- `dimension` (string): 统计维度
+- `start_date` (string, 必需): 开始日期 (YYYY-MM-DD)
+- `end_date` (string, 必需): 结束日期 (YYYY-MM-DD)
+- `period` (string): 统计周期
+- `limit` (int): 限制数量 (默认20)
+- `offset` (int): 偏移量 (默认0)
+- `aggregate_by` (string): 聚合维度
+- `group_by` (string): 分组维度
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "获取历史指标成功",
+  "data": {
+    "metric_type": "api_calls",
+    "metric_name": "total_count",
+    "dimension": "daily",
+    "data_points": [
+      {
+        "date": "2024-01-01T00:00:00Z",
+        "value": 1000,
+        "label": "total_count"
+      }
+    ],
+    "summary": {
+      "total": 30000,
+      "average": 1000,
+      "max": 1500,
+      "min": 500,
+      "count": 30,
+      "growth_rate": 5.2,
+      "trend": "increasing"
+    },
+    "metadata": {
+      "period": "daily",
+      "aggregate_by": "day",
+      "group_by": "metric_name"
+    }
+  }
+}
+```
+
+### 4. 仪表板管理
+
+#### 4.1 创建仪表板
+- **URL**: `POST /api/v1/statistics/dashboards`
+- **权限**: 管理员
+- **描述**: 创建新的统计仪表板
+
+**请求体**:
+```json
+{
+  "name": "用户仪表板",
+  "description": "普通用户专用仪表板",
+  "user_role": "user",
+  "layout": "{\"columns\": 2, \"rows\": 3}",
+  "widgets": "[{\"type\": \"api_calls\", \"position\": {\"x\": 0, \"y\": 0}}]",
+  "settings": "{\"theme\": \"light\", \"auto_refresh\": false}",
+  "refresh_interval": 600,
+  "access_level": "private",
+  "created_by": "user_id"
+}
+```
+
+#### 4.2 获取仪表板列表
+- **URL**: `GET /api/v1/statistics/dashboards`
+- **权限**: 用户
+- **描述**: 根据条件获取统计仪表板列表
+
+**查询参数**:
+- `user_role` (string): 用户角色
+- `is_default` (bool): 是否默认
+- `is_active` (bool): 是否激活
+- `access_level` (string): 访问级别
+- `created_by` (string): 创建者ID
+- `name` (string): 仪表板名称
+- `limit` (int): 限制数量 (默认20)
+- `offset` (int): 偏移量 (默认0)
+- `sort_by` (string): 排序字段 (默认created_at)
+- `sort_order` (string): 排序顺序 (默认desc)
+
+#### 4.3 获取单个仪表板
+- **URL**: `GET /api/v1/statistics/dashboards/{id}`
+- **权限**: 用户
+- **描述**: 根据ID获取指定的统计仪表板
+
+#### 4.4 获取仪表板数据
+- **URL**: `GET /api/v1/statistics/dashboards/data`
+- **权限**: 公开
+- **描述**: 获取指定角色的仪表板数据
+
+**查询参数**:
+- `user_role` (string, 必需): 用户角色
+- `period` (string): 统计周期 (today, week, month)
+- `start_date` (string): 开始日期 (YYYY-MM-DD)
+- `end_date` (string): 结束日期 (YYYY-MM-DD)
+- `metric_types` (string): 指标类型列表
+- `dimensions` (string): 统计维度列表
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "获取仪表板数据成功",
+  "data": {
+    "api_calls": {
+      "total_count": 10000,
+      "success_count": 9500,
+      "failed_count": 500,
+      "success_rate": 95.0,
+      "avg_response_time": 150.5
+    },
+    "users": {
+      "total_count": 1000,
+      "certified_count": 800,
+      "active_count": 750,
+      "certification_rate": 80.0,
+      "retention_rate": 75.0
+    },
+    "finance": {
+      "total_amount": 50000.0,
+      "recharge_amount": 60000.0,
+      "deduct_amount": 10000.0,
+      "net_amount": 50000.0
+    },
+    "period": {
+      "start_date": "2024-01-01",
+      "end_date": "2024-01-01",
+      "period": "today"
+    },
+    "metadata": {
+      "generated_at": "2024-01-01 12:00:00",
+      "user_role": "user",
+      "data_version": "1.0"
+    }
+  }
+}
+```
+
+### 5. 报告管理
+
+#### 5.1 生成报告
+- **URL**: `POST /api/v1/statistics/reports`
+- **权限**: 管理员
+- **描述**: 生成指定类型的统计报告
+
+**请求体**:
+```json
+{
+  "report_type": "summary",
+  "title": "月度汇总报告",
+  "period": "month",
+  "user_role": "admin",
+  "start_date": "2024-01-01T00:00:00Z",
+  "end_date": "2024-01-31T23:59:59Z",
+  "filters": {
+    "metric_types": ["api_calls", "users"],
+    "dimensions": ["daily", "weekly"]
+  },
+  "generated_by": "admin_id"
+}
+```
+
+#### 5.2 获取报告列表
+- **URL**: `GET /api/v1/statistics/reports`
+- **权限**: 用户
+- **描述**: 根据条件获取统计报告列表
+
+**查询参数**:
+- `report_type` (string): 报告类型
+- `user_role` (string): 用户角色
+- `status` (string): 报告状态
+- `period` (string): 统计周期
+- `start_date` (string): 开始日期 (YYYY-MM-DD)
+- `end_date` (string): 结束日期 (YYYY-MM-DD)
+- `limit` (int): 限制数量 (默认20)
+- `offset` (int): 偏移量 (默认0)
+- `sort_by` (string): 排序字段 (默认created_at)
+- `sort_order` (string): 排序顺序 (默认desc)
+- `generated_by` (string): 生成者ID
+
+#### 5.3 获取单个报告
+- **URL**: `GET /api/v1/statistics/reports/{id}`
+- **权限**: 用户
+- **描述**: 根据ID获取指定的统计报告
+
+### 6. 统计分析
+
+#### 6.1 计算增长率
+- **URL**: `GET /api/v1/statistics/analysis/growth-rate`
+- **权限**: 用户
+- **描述**: 计算指定指标的增长率
+
+**查询参数**:
+- `metric_type` (string, 必需): 指标类型
+- `metric_name` (string, 必需): 指标名称
+- `current_period` (string, 必需): 当前周期 (YYYY-MM-DD)
+- `previous_period` (string, 必需): 上一周期 (YYYY-MM-DD)
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "计算增长率成功",
+  "data": {
+    "growth_rate": 15.5,
+    "current_value": 1150,
+    "previous_value": 1000,
+    "period": "daily"
+  }
+}
+```
+
+#### 6.2 计算趋势
+- **URL**: `GET /api/v1/statistics/analysis/trend`
+- **权限**: 用户
+- **描述**: 计算指定指标的趋势
+
+**查询参数**:
+- `metric_type` (string, 必需): 指标类型
+- `metric_name` (string, 必需): 指标名称
+- `start_date` (string, 必需): 开始日期 (YYYY-MM-DD)
+- `end_date` (string, 必需): 结束日期 (YYYY-MM-DD)
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "计算趋势成功",
+  "data": {
+    "trend": "increasing",
+    "trend_strength": 0.8,
+    "data_points": 30,
+    "correlation": 0.75
+  }
+}
+```
+
+### 7. 数据导出
+
+#### 7.1 导出数据
+- **URL**: `POST /api/v1/statistics/export`
+- **权限**: 管理员
+- **描述**: 导出指定格式的统计数据
+
+**请求体**:
+```json
+{
+  "format": "excel",
+  "metric_type": "api_calls",
+  "start_date": "2024-01-01T00:00:00Z",
+  "end_date": "2024-01-31T23:59:59Z",
+  "dimension": "daily",
+  "group_by": "metric_name",
+  "filters": {
+    "status": "success"
+  },
+  "columns": ["date", "metric_name", "value"],
+  "include_charts": true,
+  "exported_by": "admin_id"
+}
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "message": "数据导出成功",
+  "data": {
+    "download_url": "https://api.example.com/downloads/export_123.xlsx",
+    "file_name": "api_calls_export_20240101_20240131.xlsx",
+    "file_size": 1024000,
+    "expires_at": "2024-01-02T12:00:00Z"
+  }
+}
+```
+
+### 8. 定时任务管理
+
+#### 8.1 手动触发小时聚合
+- **URL**: `POST /api/v1/statistics/cron/hourly-aggregation`
+- **权限**: 管理员
+- **描述**: 手动触发指定时间的小时级数据聚合
+
+**查询参数**:
+- `target_hour` (string, 必需): 目标小时 (YYYY-MM-DDTHH:MM:SSZ)
+
+#### 8.2 手动触发日聚合
+- **URL**: `POST /api/v1/statistics/cron/daily-aggregation`
+- **权限**: 管理员
+- **描述**: 手动触发指定时间的日级数据聚合
+
+**查询参数**:
+- `target_date` (string, 必需): 目标日期 (YYYY-MM-DD)
+
+#### 8.3 手动触发数据清理
+- **URL**: `POST /api/v1/statistics/cron/data-cleanup`
+- **权限**: 管理员
+- **描述**: 手动触发过期数据清理任务
+
+## 错误码
+
+| 错误码 | HTTP状态码 | 描述 |
+|--------|------------|------|
+| 400 | 400 Bad Request | 请求参数错误 |
+| 401 | 401 Unauthorized | 未认证或认证失败 |
+| 403 | 403 Forbidden | 权限不足 |
+| 404 | 404 Not Found | 资源不存在 |
+| 422 | 422 Unprocessable Entity | 参数验证失败 |
+| 429 | 429 Too Many Requests | 请求频率过高 |
+| 500 | 500 Internal Server Error | 服务器内部错误 |
+
+## 响应格式
+
+### 成功响应
+```json
+{
+  "success": true,
+  "message": "操作成功",
+  "data": {
+    // 响应数据
+  }
+}
+```
+
+### 错误响应
+```json
+{
+  "success": false,
+  "message": "错误描述",
+  "error": "详细错误信息"
+}
+```
+
+### 列表响应
+```json
+{
+  "success": true,
+  "message": "查询成功",
+  "data": [
+    // 数据列表
+  ],
+  "pagination": {
+    "page": 1,
+    "page_size": 20,
+    "total": 100,
+    "pages": 5,
+    "has_next": true,
+    "has_prev": false
+  }
+}
+```
+
+## 数据模型
+
+### 统计指标 (StatisticsMetric)
+```json
+{
+  "id": "string",
+  "metric_type": "string",
+  "metric_name": "string",
+  "dimension": "string",
+  "value": "number",
+  "metadata": "string",
+  "date": "string",
+  "created_at": "string",
+  "updated_at": "string"
+}
+```
+
+### 统计报告 (StatisticsReport)
+```json
+{
+  "id": "string",
+  "report_type": "string",
+  "title": "string",
+  "content": "string",
+  "period": "string",
+  "user_role": "string",
+  "status": "string",
+  "generated_by": "string",
+  "generated_at": "string",
+  "expires_at": "string",
+  "created_at": "string",
+  "updated_at": "string"
+}
+```
+
+### 统计仪表板 (StatisticsDashboard)
+```json
+{
+  "id": "string",
+  "name": "string",
+  "description": "string",
+  "user_role": "string",
+  "is_default": "boolean",
+  "is_active": "boolean",
+  "layout": "string",
+  "widgets": "string",
+  "settings": "string",
+  "refresh_interval": "number",
+  "created_by": "string",
+  "access_level": "string",
+  "created_at": "string",
+  "updated_at": "string"
+}
+```
+
+## 使用示例
+
+### 获取今日API调用统计
+```bash
+curl -X GET "https://api.example.com/api/v1/statistics/realtime?metric_type=api_calls&time_range=last_hour" \
+  -H "Authorization: Bearer your-jwt-token"
+```
+
+### 获取历史用户数据
+```bash
+curl -X GET "https://api.example.com/api/v1/statistics/historical?metric_type=users&start_date=2024-01-01&end_date=2024-01-31" \
+  -H "Authorization: Bearer your-jwt-token"
+```
+
+### 生成月度报告
+```bash
+curl -X POST "https://api.example.com/api/v1/statistics/reports" \
+  -H "Authorization: Bearer your-jwt-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "report_type": "summary",
+    "title": "月度汇总报告",
+    "period": "month",
+    "user_role": "admin",
+    "generated_by": "admin_id"
+  }'
+```
+
+## 注意事项
+
+1. **日期格式**: 所有日期参数都使用 `YYYY-MM-DD` 格式
+2. **时间戳**: 所有时间戳都使用 ISO 8601 格式
+3. **分页**: 默认每页20条记录，最大1000条
+4. **限流**: API有请求频率限制，超出限制会返回429错误
+5. **缓存**: 部分接口支持缓存，响应头会包含缓存信息
+6. **权限**: 不同接口需要不同的权限级别，请确保有相应权限
+7. **数据量**: 查询大量数据时建议使用分页和日期范围限制
+

docs/swagger/README.md

@@ -0,0 +1,253 @@
+# HYAPI Server Swagger 文档
+
+## 📖 概述
+
+本项目使用 [Swaggo](https://github.com/swaggo/swag) 自动生成 Swagger/OpenAPI 文档，提供完整的 API 接口文档和在线测试功能。
+
+## 🚀 快速开始
+
+### 1. 启动服务器
+
+```bash
+# 开发模式启动
+make dev
+
+# 或者直接运行
+go run cmd/api/main.go
+```
+
+### 2. 访问文档
+
+启动服务器后，可以通过以下地址访问 API 文档：
+
+-   **Swagger UI**: http://localhost:8080/swagger/index.html
+-   **API 文档信息**: http://localhost:8080/api/docs
+-   **重定向地址**: http://localhost:8080/docs
+
+## 📝 文档更新
+
+### 自动更新
+
+使用提供的脚本快速更新文档：
+
+```powershell
+# Windows PowerShell
+.\scripts\update-docs.ps1
+
+# 更新文档并重启服务器
+.\scripts\update-docs.ps1 -Restart
+
+# 查看帮助
+.\scripts\update-docs.ps1 -Help
+```
+
+### 手动更新
+
+```bash
+# 使用 Makefile
+make docs
+
+# 或者直接使用 swag 命令
+swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal
+```
+
+## 🔧 开发指南
+
+### 添加新的 API 接口
+
+1. **在 Handler 方法上添加 Swagger 注释**：
+
+```go
+// @Summary 接口简短描述
+// @Description 接口详细描述
+// @Tags 标签分组
+// @Accept json
+// @Produce json
+// @Security Bearer  # 如果需要认证
+// @Param request body dto.RequestStruct true "请求参数描述"
+// @Param id path string true "路径参数描述"
+// @Param page query int false "查询参数描述"
+// @Success 200 {object} dto.ResponseStruct "成功响应描述"
+// @Failure 400 {object} map[string]interface{} "错误响应描述"
+// @Router /api/v1/your-endpoint [post]
+func (h *YourHandler) YourMethod(c *gin.Context) {
+    // Handler实现
+}
+```
+
+2. **为 DTO 结构体添加注释和示例**：
+
+```go
+// @Description 请求参数描述
+type RequestStruct struct {
+    Name string `json:"name" example:"张三"`
+    Age  int    `json:"age" example:"25"`
+}
+
+// @Description 响应参数描述
+type ResponseStruct struct {
+    ID   string `json:"id" example:"123e4567-e89b-12d3-a456-426614174000"`
+    Name string `json:"name" example:"张三"`
+}
+```
+
+3. **重新生成文档**：
+
+```bash
+make docs
+```
+
+### Swagger 注释语法
+
+#### 基础注释
+
+-   `@Summary`: 接口摘要（在文档列表中显示）
+-   `@Description`: 详细描述（支持多行）
+-   `@Tags`: 标签分组（用于在 UI 中分组显示）
+
+#### 请求/响应格式
+
+-   `@Accept`: 接受的内容类型（json, xml, plain, html, mpfd, x-www-form-urlencoded）
+-   `@Produce`: 响应的内容类型（json, xml, plain, html）
+
+#### 安全认证
+
+-   `@Security Bearer`: JWT 认证
+-   `@Security ApiKeyAuth`: API Key 认证
+
+#### 参数定义
+
+-   `@Param`: 定义请求参数
+    -   路径参数：`@Param id path string true "用户ID"`
+    -   查询参数：`@Param page query int false "页码"`
+    -   请求体：`@Param request body dto.RequestStruct true "请求参数"`
+
+#### 响应定义
+
+-   `@Success`: 成功响应
+-   `@Failure`: 错误响应
+
+## 📋 API 分组
+
+当前文档按以下标签分组：
+
+### 🔐 用户认证
+
+-   用户注册
+-   用户登录（密码/短信验证码）
+-   发送验证码
+
+### 👤 用户管理
+
+-   获取用户信息
+-   修改密码
+
+### 👨‍💼 管理员认证
+
+-   管理员登录
+
+### 🏢 管理员管理
+
+-   创建管理员
+-   更新管理员信息
+-   修改管理员密码
+-   获取管理员列表
+-   获取管理员详情
+-   删除管理员
+-   获取管理员统计
+
+### 🏢 企业认证
+
+-   创建认证申请
+-   上传营业执照
+-   获取认证状态
+-   获取进度统计
+-   提交企业信息
+-   发起人脸验证
+-   申请合同
+-   获取认证详情
+-   重试认证步骤
+
+### 💰 钱包管理
+
+-   创建钱包
+-   获取钱包信息
+-   更新钱包信息
+-   钱包充值
+-   钱包提现
+-   钱包交易
+-   获取钱包统计
+
+### 🔑 用户密钥管理
+
+-   创建用户密钥
+-   获取用户密钥
+-   重新生成访问密钥
+-   停用用户密钥
+
+## 🔐 认证说明
+
+### JWT 认证
+
+大部分 API 接口需要 JWT 认证，在 Swagger UI 中：
+
+1. 点击右上角的 "Authorize" 按钮
+2. 在 "Bearer" 输入框中输入 JWT Token
+3. 点击 "Authorize" 确认
+
+JWT Token 格式：`Bearer <your-jwt-token>`
+
+### 获取 Token
+
+通过以下接口获取 JWT Token：
+
+-   **用户登录**: `POST /api/v1/users/login-password`
+-   **用户短信登录**: `POST /api/v1/users/login-sms`
+-   **管理员登录**: `POST /api/v1/admin/login`
+
+## 🛠️ 故障排除
+
+### 常见问题
+
+1. **文档生成失败**
+
+    - 检查 Swagger 注释语法是否正确
+    - 确保所有引用的类型都已定义
+    - 检查 HTTP 方法是否正确（必须小写）
+
+2. **模型没有正确显示**
+
+    - 确保结构体有正确的 `json` 标签
+    - 确保包被正确解析
+    - 使用 `--parseDependency --parseInternal` 参数
+
+3. **认证测试失败**
+    - 确保安全定义正确
+    - 检查 JWT Token 格式是否正确
+    - 确认 Token 未过期
+
+### 调试命令
+
+```bash
+# 详细输出生成过程
+swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal -v
+
+# 检查 swag 版本
+swag version
+
+# 重新安装 swag
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+
+## 📚 相关资源
+
+-   [Swaggo 官方文档](https://github.com/swaggo/swag)
+-   [Swagger UI 文档](https://swagger.io/tools/swagger-ui/)
+-   [OpenAPI 规范](https://swagger.io/specification/)
+
+## 🤝 贡献指南
+
+1. 添加新接口时，请同时添加完整的 Swagger 注释
+2. 确保所有参数都有合适的 `example` 标签
+3. 使用中文描述，符合项目的中文化规范
+4. 更新文档后，请运行 `make docs` 重新生成文档

docs/领域服务层设计.md

@@ -0,0 +1,373 @@
+# 领域服务层设计文档
+
+## 概述
+
+本文档描述了认证域和用户域的领域服务层设计，包括核心业务逻辑、服务接口和职责分工。
+
+## 认证域领域服务 (CertificationService)
+
+### 服务职责
+
+认证域领域服务负责管理企业认证流程的核心业务逻辑，包括：
+
+-   认证申请的生命周期管理
+-   状态机驱动的流程控制
+-   人脸识别验证流程
+-   合同申请和审核流程
+-   认证完成和失败处理
+-   进度跟踪和状态查询
+
+### 核心方法
+
+#### 1. 认证申请管理
+
+-   `CreateCertification(ctx, userID)` - 创建认证申请
+-   `GetCertificationByUserID(ctx, userID)` - 根据用户 ID 获取认证申请
+-   `GetCertificationByID(ctx, certificationID)` - 根据 ID 获取认证申请
+-   `GetCertificationWithDetails(ctx, certificationID)` - 获取认证申请详细信息（包含关联记录）
+
+#### 2. 企业信息提交
+
+-   `SubmitEnterpriseInfo(ctx, certificationID)` - 提交企业信息，触发状态转换
+
+#### 3. 人脸识别验证
+
+-   `InitiateFaceVerify(ctx, certificationID, realName, idCardNumber)` - 发起人脸识别验证
+-   `CompleteFaceVerify(ctx, faceVerifyID, isSuccess)` - 完成人脸识别验证
+-   `RetryFaceVerify(ctx, certificationID)` - 重试人脸识别
+
+#### 4. 合同流程管理
+
+-   `ApplyContract(ctx, certificationID)` - 申请合同
+-   `ApproveContract(ctx, certificationID, adminID, signingURL, approvalNotes)` - 管理员审核通过
+-   `RejectContract(ctx, certificationID, adminID, rejectReason)` - 管理员拒绝
+-   `CompleteContractSign(ctx, certificationID, contractURL)` - 完成合同签署
+
+#### 5. 认证完成
+
+-   `CompleteCertification(ctx, certificationID)` - 完成认证流程
+-   `RestartCertification(ctx, certificationID)` - 重新开始认证流程
+
+#### 6. 记录查询
+
+-   `GetFaceVerifyRecords(ctx, certificationID)` - 获取人脸识别记录
+-   `GetContractRecords(ctx, certificationID)` - 获取合同记录
+
+#### 7. 进度和状态管理
+
+-   `GetCertificationProgress(ctx, certificationID)` - 获取认证进度信息
+-   `UpdateOCRResult(ctx, certificationID, ocrRequestID, confidence)` - 更新 OCR 识别结果
+
+### 状态机集成
+
+认证服务与状态机紧密集成，所有状态转换都通过状态机进行：
+
+-   确保状态转换的合法性
+-   自动更新相关时间戳
+-   记录状态转换日志
+-   支持权限控制（用户/管理员）
+
+## 认证状态机 (CertificationStateMachine)
+
+### 状态机职责
+
+认证状态机负责管理认证流程的状态转换，包括：
+
+-   状态转换规则定义
+-   转换验证和权限控制
+-   时间戳自动更新
+-   元数据管理
+-   流程完整性验证
+
+### 核心方法
+
+#### 1. 状态转换管理
+
+-   `CanTransition(from, to, isUser, isAdmin)` - 检查是否可以转换到指定状态
+-   `TransitionTo(ctx, certificationID, targetStatus, isUser, isAdmin, metadata)` - 执行状态转换
+-   `GetValidNextStatuses(currentStatus, isUser, isAdmin)` - 获取当前状态可以转换到的下一个状态列表
+
+#### 2. 转换规则管理
+
+-   `GetTransitionAction(from, to)` - 获取状态转换对应的操作名称
+-   `initializeTransitions()` - 初始化状态转换规则
+
+#### 3. 流程验证和历史
+
+-   `GetTransitionHistory(ctx, certificationID)` - 获取状态转换历史
+-   `ValidateCertificationFlow(ctx, certificationID)` - 验证认证流程的完整性
+
+### 状态转换规则
+
+#### 正常流程转换
+
+-   `PENDING` → `INFO_SUBMITTED` (用户提交企业信息)
+-   `INFO_SUBMITTED` → `FACE_VERIFIED` (人脸识别成功)
+-   `FACE_VERIFIED` → `CONTRACT_APPLIED` (申请合同)
+-   `CONTRACT_APPLIED` → `CONTRACT_PENDING` (系统处理)
+-   `CONTRACT_PENDING` → `CONTRACT_APPROVED` (管理员审核通过)
+-   `CONTRACT_APPROVED` → `CONTRACT_SIGNED` (用户签署)
+-   `CONTRACT_SIGNED` → `COMPLETED` (系统完成)
+
+#### 失败和重试转换
+
+-   `INFO_SUBMITTED` → `FACE_FAILED` (人脸识别失败)
+-   `FACE_FAILED` → `FACE_VERIFIED` (重试人脸识别)
+-   `CONTRACT_PENDING` → `REJECTED` (管理员拒绝)
+-   `REJECTED` → `INFO_SUBMITTED` (重新开始流程)
+-   `CONTRACT_APPROVED` → `SIGN_FAILED` (签署失败)
+-   `SIGN_FAILED` → `CONTRACT_SIGNED` (重试签署)
+
+## 用户域领域服务
+
+### 用户基础服务 (UserService)
+
+#### 服务职责
+
+用户基础服务负责用户核心信息的管理，包括：
+
+-   用户基础信息的 CRUD 操作
+-   用户密码管理
+-   用户状态验证
+-   用户统计信息
+
+#### 核心方法
+
+-   `IsPhoneRegistered(ctx, phone)` - 检查手机号是否已注册
+-   `GetUserByID(ctx, userID)` - 根据 ID 获取用户信息
+-   `GetUserByPhone(ctx, phone)` - 根据手机号获取用户信息
+-   `GetUserWithEnterpriseInfo(ctx, userID)` - 获取用户信息（包含企业信息）
+-   `UpdateUser(ctx, user)` - 更新用户信息
+-   `ChangePassword(ctx, userID, oldPassword, newPassword)` - 修改用户密码
+-   `ValidateUser(ctx, userID)` - 验证用户信息
+-   `GetUserStats(ctx)` - 获取用户统计信息
+
+### 企业信息服务 (EnterpriseService)
+
+#### 服务职责
+
+企业信息服务专门负责企业信息的管理，包括：
+
+-   企业信息的创建、更新和查询
+-   企业认证状态管理
+-   数据验证和业务规则检查
+-   认证状态跟踪
+
+#### 核心方法
+
+##### 1. 企业信息管理
+
+-   `CreateEnterpriseInfo(ctx, userID, companyName, unifiedSocialCode, legalPersonName, legalPersonID)` - 创建企业信息
+-   `GetEnterpriseInfo(ctx, userID)` - 获取企业信息
+-   `UpdateEnterpriseInfo(ctx, userID, companyName, unifiedSocialCode, legalPersonName, legalPersonID)` - 更新企业信息
+-   `GetEnterpriseInfoByUnifiedSocialCode(ctx, unifiedSocialCode)` - 根据统一社会信用代码获取企业信息
+
+##### 2. 认证状态管理
+
+-   `UpdateOCRVerification(ctx, userID, isVerified, rawData, confidence)` - 更新 OCR 验证状态
+-   `UpdateFaceVerification(ctx, userID, isVerified)` - 更新人脸识别验证状态
+-   `CompleteEnterpriseCertification(ctx, userID)` - 完成企业认证
+
+##### 3. 数据验证和查询
+
+-   `CheckUnifiedSocialCodeExists(ctx, unifiedSocialCode, excludeUserID)` - 检查统一社会信用代码唯一性
+-   `ValidateEnterpriseInfo(ctx, userID)` - 验证企业信息完整性
+-   `IsEnterpriseCertified(ctx, userID)` - 检查用户是否已完成企业认证
+-   `GetEnterpriseCertificationStatus(ctx, userID)` - 获取企业认证状态
+
+##### 4. 用户信息集成
+
+-   `GetUserWithEnterpriseInfo(ctx, userID)` - 获取用户信息（包含企业信息）
+
+### 短信验证码服务 (SMSCodeService)
+
+#### 服务职责
+
+短信验证码服务负责短信验证码的完整生命周期管理，包括：
+
+-   验证码生成和发送
+-   验证码验证
+-   频率限制控制
+-   安全策略执行
+
+#### 核心方法
+
+-   `SendCode(ctx, phone, scene, clientIP, userAgent)` - 发送验证码
+-   `VerifyCode(ctx, phone, code, scene)` - 验证验证码
+-   `CanResendCode(ctx, phone, scene)` - 检查是否可以重新发送
+-   `GetCodeStatus(ctx, phone, scene)` - 获取验证码状态
+-   `CheckRateLimit(ctx, phone, scene)` - 检查发送频率限制
+
+## 服务协作模式
+
+### 服务依赖关系
+
+```
+CertificationService
+├── 依赖 CertificationRepository
+├── 依赖 FaceVerifyRecordRepository
+├── 依赖 ContractRecordRepository
+├── 依赖 LicenseUploadRecordRepository
+├── 依赖 CertificationStateMachine
+└── 提供认证流程管理功能
+
+CertificationStateMachine
+├── 依赖 CertificationRepository
+├── 管理状态转换规则
+└── 提供流程验证功能
+
+UserService
+├── 依赖 EnterpriseService (用于获取包含企业信息的用户数据)
+└── 依赖 UserRepository
+
+EnterpriseService
+├── 依赖 UserRepository (用于验证用户存在性)
+├── 依赖 EnterpriseInfoRepository
+└── 提供企业信息相关功能
+
+SMSCodeService
+├── 依赖 SMSCodeRepository
+├── 依赖 AliSMSService
+├── 依赖 CacheService
+└── 独立运行，不依赖其他领域服务
+```
+
+### 跨域调用
+
+1. **认证域调用用户域**
+
+    - 认证服务在需要企业信息时调用企业服务
+    - 通过依赖注入获取企业服务实例
+    - 保持领域边界清晰
+
+2. **应用服务层协调**
+    - 应用服务层负责协调不同领域服务
+    - 处理跨域事务和一致性
+    - 发布领域事件
+
+### 事件驱动
+
+1. **领域事件发布**
+
+    - 认证状态变更时发布事件
+    - 企业信息创建/更新时发布事件
+    - 用户注册/更新时发布事件
+    - 支持异步处理和集成
+
+2. **事件处理**
+    - 事件处理器响应领域事件
+    - 执行副作用操作（如通知、日志）
+    - 维护数据一致性
+
+## 业务规则
+
+### 企业信息只读规则
+
+-   认证完成后企业信息不可修改
+-   通过 `IsReadOnly()` 方法检查
+-   在更新操作中强制执行
+
+### 统一社会信用代码唯一性
+
+-   每个统一社会信用代码只能对应一个用户
+-   更新时排除当前用户 ID
+-   支持并发检查
+
+### 认证完成条件
+
+-   OCR 验证必须通过
+-   人脸识别验证必须通过
+-   两个条件都满足才能完成认证
+
+### 状态转换规则
+
+-   严格按照状态机定义的转换规则执行
+-   支持用户和管理员权限控制
+-   自动记录转换历史和时间戳
+
+### 短信验证码规则
+
+-   支持多种场景（注册、登录、修改密码等）
+-   频率限制（最小间隔、每小时限制、每日限制）
+-   开发模式跳过验证
+-   自动过期和清理
+
+## 错误处理
+
+### 业务错误
+
+-   使用有意义的错误消息
+-   包含业务上下文信息
+-   支持错误分类和处理
+
+### 日志记录
+
+-   记录关键业务操作
+-   包含操作上下文（用户 ID、操作类型等）
+-   支持问题排查和审计
+
+## 性能考虑
+
+### 数据库查询优化
+
+-   合理使用索引
+-   避免 N+1 查询问题
+-   支持分页和缓存
+
+### 并发控制
+
+-   使用乐观锁或悲观锁
+-   防止数据竞争条件
+-   保证数据一致性
+
+## 扩展性设计
+
+### 新功能扩展
+
+-   通过接口扩展新功能
+-   保持向后兼容性
+-   支持插件化架构
+
+### 多租户支持
+
+-   预留租户字段
+-   支持数据隔离
+-   便于未来扩展
+
+## 测试策略
+
+### 单元测试
+
+-   测试核心业务逻辑
+-   模拟外部依赖
+-   覆盖边界条件
+
+### 集成测试
+
+-   测试服务间协作
+-   验证数据一致性
+-   测试完整业务流程
+
+## 总结
+
+领域服务层设计遵循 DDD 原则，实现了：
+
+1. **职责分离**:
+
+    - 认证域负责流程管理和状态控制
+    - 用户域分为基础服务和企业服务，各司其职
+    - 短信服务独立运行
+
+2. **业务封装**: 核心业务逻辑封装在相应的领域服务中
+
+3. **状态管理**: 通过状态机管理复杂流程，支持历史追踪和流程验证
+
+4. **数据一致性**: 通过业务规则保证数据完整性
+
+5. **可扩展性**: 支持未来功能扩展和架构演进
+
+6. **服务协作**: 通过依赖注入实现服务间的松耦合协作
+
+7. **流程完整性**: 通过状态机验证和流程完整性检查确保业务逻辑正确性
+
+这种设计为应用服务层提供了清晰的接口，便于实现复杂的业务流程协调，同时保持了良好的可维护性和可测试性。