datai-vue/docs/api-docs/system/2026-01-21-002-07-api-数字格式化.md

# API 文档：数字格式化接口

## 元数据
- **需求编号**：2026-01-21-002-07
- **创建时间**：2026-01-26
- **创建人**：SSOT 架构师
- **父需求**：2026-01-21-002-项目国际化需求

## API 概述
数字格式化接口提供了千分位分隔符、小数位格式化、自动选择格式、自定义格式、后端数字格式化（NumberFormat 和 DecimalFormat）、AOP 自动格式化、Redis 缓存机制、配置管理等功能。通过 AOP 在 Service 层统一处理数字格式化，根据用户数字格式偏好自动格式化数字数据。

## 接口列表

---

### 接口 1：获取数字格式列表

#### 功能描述
获取系统支持的数字格式列表，包括数字格式代码、数字格式名称、千分位分隔符、小数位等信息。

#### 请求方式
GET

#### 请求路径
`/system/numberFormat/list`

#### 权限要求
- 无（通常公开或需登录）

#### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|--------|------|------|------|
| formatCode | String | 否 | 数字格式代码（如 COMMA、DOT、SPACE） |
| status | String | 否 | 状态（0正常 1停用） |

#### 请求示例
```bash
curl -X GET 'http://localhost:8080/system/numberFormat/list?status=0' \
  -H 'Authorization: Bearer {token}'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| msg | String | 提示信息 |
| data | Array | 数字格式列表 |
| data[].formatCode | String | 数字格式代码（如 COMMA、DOT、SPACE） |
| data[].formatName | String | 数字格式名称（如 逗号分隔） |
| data[].formatNameEn | String | 数字格式英文名称（如 Comma Separator） |
| data[].thousandsSeparator | String | 千分位分隔符（如 ,、.、 ） |
| data[].decimalSeparator | String | 小数分隔符（如 .、,） |
| data[].decimalPlaces | Integer | 小数位（如 2、3、4） |
| data[].isDefault | Boolean | 是否默认格式 |
| data[].sortOrder | Integer | 排序 |
| data[].status | String | 状态（0正常 1停用） |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "formatCode": "COMMA",
      "formatName": "逗号分隔",
      "formatNameEn": "Comma Separator",
      "thousandsSeparator": ",",
      "decimalSeparator": ".",
      "decimalPlaces": 2,
      "isDefault": true,
      "sortOrder": 1,
      "status": "0"
    },
    {
      "formatCode": "DOT",
      "formatName": "点分隔",
      "formatNameEn": "Dot Separator",
      "thousandsSeparator": ".",
      "decimalSeparator": ",",
      "decimalPlaces": 2,
      "isDefault": false,
      "sortOrder": 2,
      "status": "0"
    },
    {
      "formatCode": "SPACE",
      "formatName": "空格分隔",
      "formatNameEn": "Space Separator",
      "thousandsSeparator": " ",
      "decimalSeparator": ".",
      "decimalPlaces": 2,
      "isDefault": false,
      "sortOrder": 3,
      "status": "0"
    }
  ]
}
```

**失败响应：**
```json
{
  "code": 500,
  "msg": "获取数字格式列表失败",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 获取成功 |
| 500 | 获取失败 |

#### 业务规则
1. 数字格式列表从配置文件读取
2. 数字格式列表固定，后续不允许用户调整
3. 数字格式列表使用 Redis 缓存，缓存时间 24 小时
4. 返回的数字格式列表按排序字段排序
5. 只返回状态为正常（0）的数字格式

---

### 接口 2：获取当前用户数字格式偏好

#### 功能描述
获取当前登录用户的数字格式偏好，返回用户的数字格式代码、千分位分隔符、小数位等信息。如果用户未设置数字格式，返回系统默认数字格式。

#### 请求方式
GET

#### 请求路径
`/system/user/numberFormat`

#### 权限要求
- 无（需要登录）

#### 请求参数
无

#### 请求示例
```bash
curl -X GET 'http://localhost:8080/system/user/numberFormat' \
  -H 'Authorization: Bearer {token}'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| msg | String | 提示信息 |
| data | Object | 数字格式信息 |
| data.numberFormat | String | 数字格式代码（如 COMMA、DOT、SPACE） |
| data.formatName | String | 数字格式名称（如 逗号分隔） |
| data.formatNameEn | String | 数字格式英文名称（如 Comma Separator） |
| data.thousandsSeparator | String | 千分位分隔符（如 ,、.、 ） |
| data.decimalSeparator | String | 小数分隔符（如 .、,） |
| data.decimalPlaces | Integer | 小数位（如 2、3、4） |
| data.isDefault | Boolean | 是否系统默认格式 |

#### 响应示例

**成功响应（用户已设置数字格式）：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "formatName": "逗号分隔",
    "formatNameEn": "Comma Separator",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2,
    "isDefault": false
  }
}
```

**成功响应（用户未设置数字格式，返回系统默认格式）：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "formatName": "逗号分隔",
    "formatNameEn": "Comma Separator",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2,
    "isDefault": true
  }
}
```

**失败响应：**
```json
{
  "code": 500,
  "msg": "获取当前用户数字格式偏好失败",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 获取成功 |
| 500 | 获取失败或未找到用户信息 |

#### 业务规则
1. 优先级：用户数字格式偏好 > 系统默认格式
2. 如果用户未设置数字格式，返回系统默认数字格式
3. 用户数字格式偏好使用 Redis 缓存，缓存时间 24 小时
4. 需要用户登录才能获取数字格式信息

---

### 接口 3：切换数字格式

#### 功能描述
切换当前登录用户的数字格式偏好，更新用户数字格式设置，清除相关缓存，返回切换结果。数字格式切换后，前端需要刷新页面重新加载数字数据。

#### 请求方式
POST

#### 请求路径
`/system/user/switchNumberFormat`

#### 权限要求
- 无（需要登录）

#### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|--------|------|------|------|
| numberFormat | String | 是 | 数字格式代码（如 COMMA、DOT、SPACE） |
| decimalPlaces | Integer | 否 | 小数位（如 2、3、4），不传则使用默认值 2 |

#### 请求示例
```bash
curl -X POST 'http://localhost:8080/system/user/switchNumberFormat' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "numberFormat": "DOT",
    "decimalPlaces": 3
  }'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，400/500 失败） |
| msg | String | 提示信息 |
| data | Object | 数据对象（通常为 null） |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "数字格式切换成功",
  "data": null
}
```

**失败响应（无效的数字格式代码）：**
```json
{
  "code": 400,
  "msg": "无效的数字格式代码",
  "data": null
}
```

**失败响应（未找到用户信息）：**
```json
{
  "code": 500,
  "msg": "未找到用户信息",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 切换成功 |
| 400 | 无效的数字格式代码 |
| 500 | 切换失败或未找到用户信息 |

#### 业务规则
1. 验证数字格式代码的有效性
2. 更新用户数字格式偏好到数据库
3. 清除用户数字格式缓存
4. 清除相关数据缓存（如数字数据缓存等）
5. 数字格式切换后，前端需要刷新页面重新加载数字数据
6. 数字格式切换记录审计日志
7. 数字格式切换响应时间 < 100ms

---

### 接口 4：获取系统默认数字格式

#### 功能描述
获取系统默认数字格式配置，返回系统默认数字格式的详细信息。系统默认数字格式用于用户未设置数字格式时的回退格式。

#### 请求方式
GET

#### 请求路径
`/system/numberFormat/default`

#### 权限要求
- 无（通常公开或需登录）

#### 请求参数
无

#### 请求示例
```bash
curl -X GET 'http://localhost:8080/system/numberFormat/default' \
  -H 'Authorization: Bearer {token}'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| msg | String | 提示信息 |
| data | Object | 数字格式信息 |
| data.numberFormat | String | 数字格式代码（如 COMMA、DOT、SPACE） |
| data.formatName | String | 数字格式名称（如 逗号分隔） |
| data.formatNameEn | String | 数字格式英文名称（如 Comma Separator） |
| data.thousandsSeparator | String | 千分位分隔符（如 ,、.、 ） |
| data.decimalSeparator | String | 小数分隔符（如 .、,） |
| data.decimalPlaces | Integer | 小数位（如 2、3、4） |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "numberFormat": "COMMA",
    "formatName": "逗号分隔",
    "formatNameEn": "Comma Separator",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2
  }
}
```

**失败响应：**
```json
{
  "code": 500,
  "msg": "获取默认数字格式失败",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 获取成功 |
| 500 | 获取失败或未找到默认数字格式 |

#### 业务规则
1. 系统必须有默认数字格式配置
2. 默认数字格式从配置文件读取
3. 默认数字格式使用 Redis 缓存，缓存时间 24 小时
4. 默认数字格式用于用户未设置数字格式时的回退格式

---

### 接口 5：格式化数字

#### 功能描述
根据用户数字格式偏好格式化数字，返回格式化后的数字字符串。支持自定义数字格式，包括千分位分隔符、小数位格式化等。

#### 请求方式
POST

#### 请求路径
`/system/numberFormat/format`

#### 权限要求
- 无（需要登录）

#### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|--------|------|------|------|
| number | Number | 是 | 数字（如 1234.5678） |
| numberFormat | String | 否 | 数字格式代码（如 COMMA、DOT、SPACE），不传则使用用户数字格式偏好 |
| decimalPlaces | Integer | 否 | 小数位（如 2、3、4），不传则使用用户小数位偏好 |
| usePercentage | Boolean | 否 | 是否使用百分比格式（默认 false） |

#### 请求示例
```bash
curl -X POST 'http://localhost:8080/system/numberFormat/format' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": 1234.5678,
    "numberFormat": "COMMA",
    "decimalPlaces": 2,
    "usePercentage": false
  }'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，400/500 失败） |
| msg | String | 提示信息 |
| data | Object | 格式化结果 |
| data.formattedNumber | String | 格式化后的数字（如 1,234.57） |
| data.numberFormat | String | 数字格式代码（如 COMMA、DOT、SPACE） |
| data.thousandsSeparator | String | 千分位分隔符（如 ,、.、 ） |
| data.decimalSeparator | String | 小数分隔符（如 .、,） |
| data.decimalPlaces | Integer | 小数位（如 2、3、4） |
| data.usePercentage | Boolean | 是否使用百分比格式 |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "格式化成功",
  "data": {
    "formattedNumber": "1,234.57",
    "numberFormat": "COMMA",
    "thousandsSeparator": ",",
    "decimalSeparator": ".",
    "decimalPlaces": 2,
    "usePercentage": false
  }
}
```

**失败响应（无效的数字）：**
```json
{
  "code": 400,
  "msg": "无效的数字",
  "data": null
}
```

**失败响应（无效的数字格式代码）：**
```json
{
  "code": 400,
  "msg": "无效的数字格式代码",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 格式化成功 |
| 400 | 无效的数字或数字格式代码 |
| 500 | 格式化失败 |

#### 业务规则
1. 如果未指定数字格式，使用用户数字格式偏好
2. 如果未指定小数位，使用用户小数位偏好
3. 小数位四舍五入
4. 支持整数、浮点数、大数字格式化
5. 支持负数格式化
6. 支持百分比格式化
7. 数字格式化时间 < 1ms

---

### 接口 6：刷新数字格式缓存

#### 功能描述
刷新数字格式缓存，清除所有数字格式相关的缓存数据，使最新的数字格式数据立即生效。

#### 请求方式
DELETE

#### 请求路径
`/system/numberFormat/refreshCache`

#### 权限要求
- `system:numberFormat:refresh`

#### 请求参数
无

#### 请求示例
```bash
curl -X DELETE 'http://localhost:8080/system/numberFormat/refreshCache' \
  -H 'Authorization: Bearer {token}'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| msg | String | 提示信息 |
| data | Object | 数据对象（通常为 null） |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "数字格式缓存刷新成功",
  "data": null
}
```

**失败响应：**
```json
{
  "code": 500,
  "msg": "数字格式缓存刷新失败",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 刷新成功 |
| 500 | 刷新失败 |

#### 业务规则
1. 清除数字格式列表缓存（sys:numberFormat:list）
2. 清除用户数字格式缓存（sys:numberFormat:{userId}）
3. 刷新后，下次查询时重新加载数字格式数据

---

## 数据库表结构

### sys_user 表修改（用户表）
```sql
ALTER TABLE `sys_user` 
ADD COLUMN `number_format` varchar(50) DEFAULT NULL COMMENT '数字格式（COMMA、DOT、SPACE）' AFTER `date_format_pattern`,
ADD COLUMN `decimal_places` int DEFAULT NULL COMMENT '小数位（2、3、4）' AFTER `number_format`;
```

---

## 常用数字格式列表

| 数字格式代码 | 数字格式名称 | 数字格式英文名称 | 千分位分隔符 | 小数分隔符 | 小数位 | 是否默认 |
|-------------|-------------|-----------------|-------------|-----------|-------|---------|
| COMMA | 逗号分隔 | Comma Separator | , | . | 2 | 是 |
| DOT | 点分隔 | Dot Separator | . | , | 2 | 否 |
| SPACE | 空格分隔 | Space Separator |   | . | 2 | 否 |

---

## 数字格式化说明

### 数字格式化流程
```
数字格式化
  ├─ 读取用户数字格式偏好（number_format）
  ├─ 读取用户小数位偏好（decimal_places）
  ├─ 读取系统默认数字格式配置
  ├─ 根据用户数字格式偏好格式化数字
  │  ├─ 使用 NumberFormat 进行标准格式化
  │  ├─ 使用 DecimalFormat 进行自定义格式化
  │  ├─ 添加千分位分隔符
  │  ├─ 格式化小数位（四舍五入）
  │  └─ 支持负数格式化
  └─ 返回格式化后的数字
```

### 数字格式化示例
```java
// 示例：格式化数字
double number = 1234.5678;
String numberFormat = "COMMA";
int decimalPlaces = 2;

// 创建 DecimalFormat
DecimalFormatSymbols symbols = DecimalFormatSymbols.getInstance();
symbols.setGroupingSeparator(',');
symbols.setDecimalSeparator('.');

String pattern = "#,##0." + String.format("%0" + decimalPlaces + "d", 0).replace("0", "0");
DecimalFormat decimalFormat = new DecimalFormat(pattern, symbols);

// 格式化数字
String formattedNumber = decimalFormat.format(number);

// 结果：1,234.57
```

---

## 多语言数字显示说明

### 多语言数字显示流程
```
多语言数字显示
  ├─ 读取用户语言偏好（lang_code）
  ├─ 读取系统默认语言配置
  ├─ 根据用户语言偏好显示数字
  │  ├─ 中文：逗号分隔（1,234.56）
  │  ├─ 英文：逗号分隔（1,234.56）
  │  ├─ 德文：点分隔（1.234,56）
  │  └─ 法文：空格分隔（1 234,56）
  └─ 返回格式化后的数字
```

### 多语言数字显示示例
```java
// 示例：多语言数字显示
double number = 1234.5678;
String locale = "zh_CN";
int decimalPlaces = 2;

// 创建 NumberFormat
NumberFormat numberFormat = NumberFormat.getNumberInstance(Locale.forLanguageTag(locale));
numberFormat.setMinimumFractionDigits(decimalPlaces);
numberFormat.setMaximumFractionDigits(decimalPlaces);

// 格式化数字
String formattedNumber = numberFormat.format(number);

// 中文：1,234.57
// 英文：1,234.57
// 德文：1.234,57
// 法文：1 234,57
```

---

## 缓存策略

### 缓存键格式
- 数字格式列表：`sys:numberFormat:list`
- 用户数字格式：`sys:numberFormat:{userId}`

### 缓存时间
- 数字格式列表缓存：24 小时
- 用户数字格式缓存：24 小时

### 缓存刷新规则
1. 数字格式列表更新时，清除数字格式列表缓存
2. 数字格式切换时，清除用户数字格式缓存
3. 手动刷新数字格式缓存时，清除所有数字格式相关缓存

---

## AOP 统一处理说明

### AOP 切面设计
```java
@Aspect
@Component
public class NumberFormatAspect {
    
    @Autowired
    private NumberFormatService numberFormatService;
    
    @AfterReturning(pointcut = "@annotation(com.datai.common.annotation.NumberFormat)", returning = "result")
    public void formatNumber(JoinPoint joinPoint, Object result) {
        if (result == null) {
            return;
        }
        
        Object formattedResult = numberFormatService.formatObject(result);
        return formattedResult;
    }
}
```

### AOP 使用示例
```java
@Service
public class OrderServiceImpl implements IOrderService {
    
    @NumberFormat
    @Override
    public Order getOrderById(Long orderId) {
        Order order = orderMapper.selectOrderById(orderId);
        return order;
    }
}
```

---

## 注意事项

1. **数字格式验证**：切换数字格式时，必须验证数字格式代码的有效性
2. **数字格式化**：数字格式化在 Service 层通过 AOP 统一处理
3. **数字存储**：所有数字字段使用 BigDecimal 类型存储，避免精度丢失
4. **小数位四舍五入**：数字小数位四舍五入
5. **缓存管理**：数字格式和用户数字格式需要缓存，提高性能
6. **页面刷新**：数字格式切换后立即刷新页面，重新加载数字数据
7. **数字格式列表**：数字格式列表固定存储在配置文件中，后续不允许用户调整
8. **多语言数字显示**：根据用户语言偏好显示数字（如中文逗号分隔、德文点分隔、法文空格分隔）
9. **权限控制**：所有用户都可以设置和切换数字格式
10. **审计日志**：记录数字格式设置变更日志
11. **线程安全**：NumberFormat 和 DecimalFormat 是线程安全的，可以在多线程环境下安全使用
12. **格式验证**：用户输入的数字格式必须经过验证，防止注入攻击

---

## 性能要求

- **数字格式化时间**：< 1ms
- **数字格式切换响应时间**：< 100ms
- **缓存命中率**：≥ 90%

---

## 相关文档

- [需求文档](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/reference-code/2026-01-25-002-07-code-数字格式化功能.md)
- [实施方案](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/implementation/2026-01-25-002-07-implementation-数字格式化功能.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)