107 lines
3.2 KiB
Markdown
107 lines
3.2 KiB
Markdown
# API 文档：格式化数字接口
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-21-002-07-05
|
||
- **创建时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **父需求**：2026-01-21-002-07-数字格式化需求
|
||
|
||
## 接口概述
|
||
根据用户数字格式偏好格式化数字，返回格式化后的数字字符串。支持自定义数字格式，包括千分位分隔符、小数位格式化等。
|
||
|
||
## 接口详情
|
||
|
||
### 基本信息
|
||
- **接口名称**：格式化数字
|
||
- **接口描述**：根据用户数字格式偏好格式化数字
|
||
- **请求方式**：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
|
||
}
|
||
```
|
||
|
||
### 业务规则
|
||
1. 如果未指定数字格式，使用用户数字格式偏好
|
||
2. 如果未指定小数位，使用用户小数位偏好
|
||
3. 小数位四舍五入
|
||
4. 支持整数、浮点数、大数字格式化
|
||
5. 支持负数格式化
|
||
6. 支持百分比格式化
|
||
7. 数字格式化时间 < 1ms
|
||
|
||
### 性能要求
|
||
- **响应时间**：< 1ms
|
||
- **格式化精度**：支持最多 16 位小数
|
||
|
||
### 相关文档
|
||
- [需求文档](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)
|