# API 文档：数字格式化功能

## 元数据
- API 文档编号：2026-01-25-002-07-api
- 需求编号：2026-01-21-002-07
- 功能名称：数字格式化功能
- 版本：3.8.5
- 发布日期：2026-01-25
- 状态：已完成
- 阶段：阶段 9：复盘与接口

## API 概述

数字格式化功能提供了用户数字格式偏好管理和系统默认数字格式查询的 API 接口，支持用户设置和切换数字格式偏好，获取系统默认数字格式和常用数字格式列表。

## API 列表

### 1. 获取当前用户数字格式偏好

#### 接口信息
- **接口路径**：/system/user/numberFormat
- **请求方法**：GET
- **接口描述**：获取当前用户数字格式偏好
- **权限要求**：需要登录
- **接口分类**：用户管理

#### 请求参数
无

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "numberFormat": "COMMA",
    "decimalPlaces": 2
  }
}
```

#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码，200 表示成功 |
| msg | String | 响应消息 |
| data | Object | 响应数据 |
| data.userId | Long | 用户 ID |
| data.numberFormat | String | 数字格式（COMMA、DOT、SPACE、CUSTOM） |
| data.decimalPlaces | Integer | 小数位偏好（0-10） |

#### 错误响应
```json
{
  "code": 401,
  "msg": "用户未登录"
}
```

### 2. 切换用户数字格式偏好

#### 接口信息
- **接口路径**：/system/user/switchNumberFormat
- **请求方法**：POST
- **接口描述**：切换用户数字格式偏好
- **权限要求**：需要登录
- **接口分类**：用户管理

#### 请求参数
```json
{
  "numberFormat": "COMMA",
  "decimalPlaces": 2
}
```

#### 请求字段说明
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| numberFormat | String | 是 | 数字格式（COMMA、DOT、SPACE、CUSTOM） |
| decimalPlaces | Integer | 是 | 小数位偏好（0-10） |

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

#### 错误响应
```json
{
  "code": 500,
  "msg": "数字格式不能为空"
}
```

```json
{
  "code": 500,
  "msg": "小数位偏好不能为空"
}
```

```json
{
  "code": 500,
  "msg": "小数位偏好必须在 0-10 之间"
}
```

### 3. 获取系统默认数字格式

#### 接口信息
- **接口路径**：/system/config/defaultNumberFormat
- **请求方法**：GET
- **接口描述**：获取系统默认数字格式
- **权限要求**：需要登录
- **接口分类**：配置管理

#### 请求参数
无

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "decimalPlaces": 2
  }
}
```

#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码，200 表示成功 |
| msg | String | 响应消息 |
| data | Object | 响应数据 |
| data.numberFormat | String | 系统默认数字格式 |
| data.decimalPlaces | Integer | 系统默认小数位 |

#### 错误响应
```json
{
  "code": 500,
  "msg": "获取系统默认数字格式失败"
}
```

### 4. 获取常用数字格式列表

#### 接口信息
- **接口路径**：/system/config/commonNumberFormats
- **请求方法**：GET
- **接口描述**：获取常用数字格式列表
- **权限要求**：需要登录
- **接口分类**：配置管理

#### 请求参数
无

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormats": {
      "COMMA": "1,000.00",
      "DOT": "1.000,00",
      "SPACE": "1 000.00"
    }
  }
}
```

#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码，200 表示成功 |
| msg | String | 响应消息 |
| data | Object | 响应数据 |
| data.numberFormats | Object | 常用数字格式列表 |

#### 数字格式说明
| 格式代码 | 示例 | 说明 |
|---------|------|------|
| COMMA | 1,000.00 | 逗号分隔符（美国、中国等） |
| DOT | 1.000,00 | 点分隔符（德国、法国等） |
| SPACE | 1 000.00 | 空格分隔符（瑞士等） |
| CUSTOM | 自定义 | 自定义格式 |

#### 错误响应
```json
{
  "code": 500,
  "msg": "获取常用数字格式列表失败"
}
```

## 使用示例

### 示例 1：获取当前用户数字格式偏好

#### 请求
```http
GET /system/user/numberFormat
Authorization: Bearer {token}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "numberFormat": "COMMA",
    "decimalPlaces": 2
  }
}
```

### 示例 2：切换用户数字格式偏好为点分隔符

#### 请求
```http
POST /system/user/switchNumberFormat
Authorization: Bearer {token}
Content-Type: application/json

{
  "numberFormat": "DOT",
  "decimalPlaces": 2
}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 示例 3：切换用户数字格式偏好为空格分隔符

#### 请求
```http
POST /system/user/switchNumberFormat
Authorization: Bearer {token}
Content-Type: application/json

{
  "numberFormat": "SPACE",
  "decimalPlaces": 3
}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 示例 4：获取系统默认数字格式

#### 请求
```http
GET /system/config/defaultNumberFormat
Authorization: Bearer {token}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "decimalPlaces": 2
  }
}
```

### 示例 5：获取常用数字格式列表

#### 请求
```http
GET /system/config/commonNumberFormats
Authorization: Bearer {token}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormats": {
      "COMMA": "1,000.00",
      "DOT": "1.000,00",
      "SPACE": "1 000.00"
    }
  }
}
```

## 注意事项

### 1. 数字格式
- 数字格式必须是预定义的格式之一（COMMA、DOT、SPACE、CUSTOM）
- 小数位偏好必须在 0-10 之间
- 数字格式和小数位偏好不能为空

### 2. 缓存机制
- 用户数字格式偏好使用 Redis 缓存，TTL 为 24 小时
- 用户切换数字格式偏好时，缓存会立即清除
- 获取用户数字格式偏好时，会优先从缓存中读取

### 3. 权限控制
- 所有接口都需要登录
- 用户只能设置和获取自己的数字格式偏好
- 系统默认数字格式和常用数字格式列表对所有登录用户可见

### 4. 错误处理
- 数字格式不能为空时，返回错误提示
- 小数位偏好不能为空时，返回错误提示
- 小数位偏好必须在 0-10 之间，否则返回错误提示
- 用户未登录时，返回 401 错误码

### 5. 多语言支持
- 数字格式化支持多语言数字显示（根据用户语言偏好自动选择语言）
- 千分位分隔符和小数分隔符会根据用户语言偏好自动调整

### 6. AOP 自动格式化
- 数字格式化使用 AOP 切面实现，在 Service 层自动进行数字格式化
- 数字格式化切面（NumberFormatAspect）的执行顺序在时区转换切面（TimeZoneConvertAspect）和日期格式化切面（DateFormatAspect）之后

## 相关文档

- [需求文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-01-21-002-07-数字格式化需求.md)
- [设计文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/design/2026-01-21-002-07-数字格式化设计.md)
- [架构决策记录](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/2026-01-25-002-07-ADR-数字格式化技术选型.md)
- [SQL 脚本](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/sql/2026-01-25-002-07-数字格式化.sql)
- [提示词文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/prompts/2026-01-25-002-07-prompt-数字格式化功能.md)
- [会话记录](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/sessions/2026-01-25-002-07-session.md)
- [变更日志](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-01-25-002-07-changelog.md)
- [复盘文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-01-25-002-07-retro.md)

## 更新记录

| 版本 | 日期 | 更新内容 | 更新人 |
|------|------|---------|--------|
| 3.8.5 | 2026-01-25 | 初始版本 | SSOT 架构师 |