# 通用 Helper 函数

:::tip 说明
`src/common/utils/helpers.py` 提供项目中广泛使用的通用工具函数，包括 ID 解析、OS/浏览器检测、参数脱敏等。
:::

## parse_id_list — ID 列表解析

将逗号分隔的 ID 字符串解析为整数列表：

```python
from common.utils.helpers import parse_id_list

parse_id_list("1,2,3")
# 返回: [1, 2, 3]

parse_id_list("1,2,abc,3")
# 返回: [1, 2, 3]  # 自动跳过非数字项

parse_id_list("")
# 返回: []
```

## detect_os — 操作系统检测

从 User-Agent 字符串提取操作系统信息：

```python
from common.utils.helpers import detect_os

detect_os("Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...")
# 返回: "Windows 10.0"
```

支持 Windows、macOS、Android、iOS、Linux 等主流操作系统。

## detect_browser — 浏览器检测

从 User-Agent 字符串提取浏览器信息：

```python
from common.utils.helpers import detect_browser

detect_browser("Mozilla/5.0 ... Chrome/120.0.0.0 ...")
# 返回: "Chrome 120.0"
```

支持 Edge、Chrome、Firefox、Safari、IE 等主流浏览器。Edge 优先匹配，避免被误判为 Chrome。

## redact_params — 参数脱敏

对敏感参数进行脱敏处理，用于操作日志记录：

```python
from common.utils.helpers import redact_params

params = {"username": "admin", "password": "123456", "name": "张三"}
redact_params(params)
# 返回: {"username": "admin", "password": "******", "name": "张三"}
```

自动对 `password`、`salt`、`token`、`secret` 等敏感字段脱敏。

## 使用场景

| 函数 | 主要使用场景 |
|:-----|:------------|
| `parse_id_list` | 批量删除、批量状态变更 |
| `detect_os` | 操作日志、登录日志 |
| `detect_browser` | 操作日志、登录日志 |
| `redact_params` | 操作日志参数记录 |

## 总结

通用 Helper 函数覆盖了 ID 解析、设备检测、参数脱敏等常见场景。这些函数在各业务模块中广泛使用，是项目的基础工具集。