docs(readme): 重构README并补充详细文档内容

2026-04-29 11:20:18 +08:00
parent 67066d69d6
commit 523cc777f8
29 changed files with 15437 additions and 22 deletions
--- a/.qoder/repowiki/zh/content/配置指南/HTTP
+++ b/.qoder/repowiki/zh/content/配置指南/HTTP
@@ -0,0 +1,320 @@
+# HTTP 请求配置
+
+<cite>
+**本文引用的文件**
+- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
+- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
+- [TsStorage.js](file://src/utils/TsStorage.js)
+- [TsCommon.js](file://src/utils/TsCommon.js)
+- [TsCrypto.js](file://src/utils/TsCrypto.js)
+- [TsSM4.js](file://src/utils/TsSM4.js)
+- [index.js](file://index.js)
+- [package.json](file://package.json)
+- [README.md](file://README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与缓存策略](#性能与缓存策略)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录：完整配置示例与最佳实践](#附录完整配置示例与最佳实践)
+
+## 简介
+本文件面向使用 TsHttpUtil 的开发者，系统性说明 HTTP 请求配置项、请求头设置、超时控制、重试机制、httpParams 回调、请求拦截与响应处理、错误处理 onHttpError、认证与代理、SSL 与加密、性能优化与缓存策略，以及调试与监控方法。文档基于仓库源码进行逐层解析，并提供可直接落地的配置建议与流程图示。
+
+## 项目结构
+该工具包以“功能域”组织：https 层负责网络请求封装，utils 层提供全局配置、存储、通用工具、加解密等支撑能力；入口 index.js 汇总导出模块。
+
+```mermaid
+graph TB
+subgraph "入口"
+IDX["index.js"]
+end
+subgraph "HTTPS 层"
+HTTP["TsHttpUtil.js"]
+end
+subgraph "工具层"
+GC["TsGlobalConfig.js"]
+ST["TsStorage.js"]
+CM["TsCommon.js"]
+CR["TsCrypto.js"]
+SM["TsSM4.js"]
+end
+IDX --> HTTP
+HTTP --> GC
+HTTP --> ST
+HTTP --> CM
+HTTP --> CR
+CR --> SM
+```
+
+图表来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
+
+章节来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [package.json:1-24](file://package.json#L1-L24)
+
+## 核心组件
+- TsHttpUtil：统一请求入口，封装 GET/POST/FORM，内置默认错误处理、请求头注入、参数合并与加密逻辑。
+- TsGlobalConfig：全局配置中心，支持 prefix 前缀、onHttpError 错误回调、httpParams 动态参数注入。
+- TsStorage：本地存储与用户 Token 管理，支持开关 body 加密。
+- TsCommon：通用工具，含空值判断、JSON 解析、开发环境判断等。
+- TsCrypto/TsSM4：SM4 对称加密实现，配合 base64 密钥与模式配置。
+
+章节来源
+- [TsHttpUtil.js:25-171](file://src/https/TsHttpUtil.js#L25-L171)
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
+
+## 架构总览
+TsHttpUtil 在 umi-request 基础上扩展了：
+- 默认错误处理 errorHandler
+- 默认携带 cookie、JSON 请求体类型
+- 统一参数处理 dealParamsBody（分页、equals、动态参数注入）
+- 请求前缀 prefix 注入
+- 自动注入用户 Token
+- 响应体解密与数据提取
+- 错误回调 onHttpError
+
+```mermaid
+sequenceDiagram
+participant App as "应用"
+participant Http as "TsHttpUtil"
+participant Umi as "umi-request"
+participant Cfg as "TsGlobalConfig"
+participant Store as "TsStorage"
+participant Crypto as "TsCrypto/TsSM4"
+App->>Http : 调用 get/post/form(req)
+Http->>Cfg : 读取 prefix/httpParams/onHttpError
+Http->>Store : 读取用户 Token
+Http->>Http : 合并动态参数/分页/equals
+Http->>Http : 条件加密 encryptBody
+Http->>Umi : request(url, options)
+Umi-->>Http : 返回响应
+Http->>Http : 解密/提取 data/recordsTotal
+Http-->>App : Promise.resolve(data, recordsTotal)
+Http->>Cfg : onHttpError(res)失败时
+```
+
+图表来源
+- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
+- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
+- [TsStorage.js:13-23](file://src/utils/TsStorage.js#L13-L23)
+- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
+- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
+
+## 详细组件分析
+
+### 1) 请求配置与默认行为
+- 默认错误处理：对无响应或状态码映射到统一消息。
+- 凭据策略：默认携带 Cookie。
+- 请求体类型：默认 JSON。
+- 请求前缀：支持字符串或函数式前缀，按 URL 动态拼接。
+- 动态参数注入：通过 httpParams 回调注入到 GET 查询参数或非表单 POST 请求体中。
+- 用户 Token：自动从本地存储读取并注入到请求头 token 字段。
+- 响应处理：默认仅返回 data 与 recordsTotal；若响应标记加密，则自动解密并解析 JSON。
+
+章节来源
+- [TsHttpUtil.js:28-44](file://src/https/TsHttpUtil.js#L28-L44)
+- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
+- [TsGlobalConfig.js:5-21](file://src/utils/TsGlobalConfig.js#L5-L21)
+- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)
+
+### 2) httpParams 回调函数详解
+- 触发时机：在 GET 请求合并查询参数、或非表单 POST 请求合并请求体之前。
+- 参数与返回：回调接收当前请求上下文（由全局配置提供），返回一个对象作为额外参数注入。
+- 使用场景：统一注入业务维度参数（如租户 ID、版本号、traceId）、环境标识、签名参数等。
+- 注意事项：GET 与非表单 POST 的注入位置不同，避免覆盖关键字段。
+
+章节来源
+- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
+- [TsGlobalConfig.js:10-12](file://src/utils/TsGlobalConfig.js#L10-L12)
+
+### 3) 请求头设置与认证
+- 自动头注入：每次请求自动附加 token 头部，值来自用户 Token。
+- 手动头覆盖：可通过 options.headers 传入自定义头，会与默认头合并。
+- 认证策略：建议在 httpParams 或 headers 中注入 Authorization/Bearer 等，结合用户 Token 管理。
+
+章节来源
+- [TsHttpUtil.js:108-112](file://src/https/TsHttpUtil.js#L108-L112)
+- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)
+
+### 4) 超时与重试机制
+- 超时：umi-request 支持 timeout 配置，可在 options 中传入；TsHttpUtil 不在内部强制设置。
+- 重试：未内置重试逻辑，可在上层封装或通过 umi-request 的 retry 选项实现（需在调用侧传入）。
+
+章节来源
+- [TsHttpUtil.js:108-112](file://src/https/TsHttpUtil.js#L108-L112)
+- [package.json:19-22](file://package.json#L19-L22)
+
+### 5) 请求拦截器与响应处理器
+- 请求拦截：通过 options.headers、httpParams 注入参数与头；prefix 前缀在请求发起前拼接。
+- 响应处理：默认解析 data/recordsTotal；若响应带加密标记则自动解密。
+- 自定义处理：通过 rawResponse 可直接返回原始响应对象，交由调用方自行处理。
+
+章节来源
+- [TsHttpUtil.js:108-134](file://src/https/TsHttpUtil.js#L108-L134)
+
+### 6) 错误处理 onHttpError
+- 默认行为：将错误映射为统一结构（code/message）。
+- 自定义回调：通过 TsGlobalConfig.setConfig 注入 onHttpError，用于统一上报、埋点、登录态失效处理等。
+- 触发条件：当响应 code 非 200 时触发。
+
+章节来源
+- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
+- [TsHttpUtil.js:125-127](file://src/https/TsHttpUtil.js#L125-L127)
+- [TsGlobalConfig.js:8-9](file://src/utils/TsGlobalConfig.js#L8-L9)
+
+### 7) 加密与安全
+- 加密开关：通过 TsStorage.saveEncryptBody(true/false) 控制是否对请求体进行加密。
+- 加密算法：SM4（ECB/可选 CBC），密钥来自 TsGlobalConfig.base64Key。
+- 解密：响应体若标记加密，自动解密并解析 JSON。
+- 建议：生产环境务必使用强密钥与 HTTPS，避免明文传输。
+
+章节来源
+- [TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
+- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
+- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
+
+### 8) 参数处理与分页/equals
+- 分页：将 pagination 对象转换为 pageSize/pageNum 并移除 pagination。
+- equals：将对象转为逗号分隔的键值串，过滤空值。
+- 动态参数：通过 httpParams 注入，GET 合并到查询参数，非表单 POST 合并到请求体。
+
+章节来源
+- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
+
+### 9) 环境差异化配置策略
+- 开发环境：可启用 httpParams 注入调试参数、开启日志输出；prefix 指向本地/联调服务。
+- 测试环境：启用 httpParams 注入测试标识；开启轻量级错误上报；必要时开启加密。
+- 生产环境：严格启用 HTTPS、固定密钥、关闭敏感日志；onHttpError 上报统一错误；限制 httpParams 注入范围。
+
+章节来源
+- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
+- [TsGlobalConfig.js:5-21](file://src/utils/TsGlobalConfig.js#L5-L21)
+
+## 依赖关系分析
+
+```mermaid
+graph LR
+HTTP["TsHttpUtil.js"] --> GC["TsGlobalConfig.js"]
+HTTP --> ST["TsStorage.js"]
+HTTP --> CM["TsCommon.js"]
+HTTP --> CR["TsCrypto.js"]
+CR --> SM["TsSM4.js"]
+IDX["index.js"] --> HTTP
+PKG["package.json"] --> HTTP
+```
+
+图表来源
+- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+- [TsStorage.js:1-5](file://src/utils/TsStorage.js#L1-L5)
+- [TsCommon.js:1-4](file://src/utils/TsCommon.js#L1-L4)
+- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
+- [TsSM4.js:1-3](file://src/utils/TsSM4.js#L1-L3)
+- [index.js:1-6](file://index.js#L1-L6)
+- [package.json:19-22](file://package.json#L19-L22)
+
+章节来源
+- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
+- [package.json:19-22](file://package.json#L19-L22)
+
+## 性能与缓存策略
+- 请求合并：优先使用 httpParams 合并公共参数，减少重复字段。
+- 数据压缩：在服务端支持前提下，考虑 gzip/deflate 传输。
+- 缓存策略：对 GET 请求可结合业务缓存（如内存/LocalStorage）避免重复请求；注意缓存失效与一致性。
+- 超时与并发：合理设置 timeout，避免阻塞；对批量请求采用并发控制。
+- 加密成本：加密/解密为 CPU 密集型，建议仅对敏感数据启用，或在高频接口中评估开销。
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 无法登录/鉴权失败：检查 headers 中 token 是否正确注入；确认 httpParams 是否覆盖了必要的认证头。
+- 参数丢失：确认 GET 与非表单 POST 的参数注入位置；避免与 options.params/data 冲突。
+- 加密异常：确认 TsStorage.encryptBody 开关、base64Key 正确、服务端密钥一致。
+- 错误未上报：确认 onHttpError 是否正确注入；检查响应 code/message 映射。
+- 调试方法：开启浏览器 Network 面板，观察请求头、参数、响应体；在 httpParams 中注入 traceId 便于后端定位。
+
+章节来源
+- [TsHttpUtil.js:108-134](file://src/https/TsHttpUtil.js#L108-L134)
+- [TsGlobalConfig.js:8-9](file://src/utils/TsGlobalConfig.js#L8-L9)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
+
+## 结论
+TsHttpUtil 提供了简洁而强大的 HTTP 封装，通过全局配置与工具层能力，实现了参数注入、认证、加密、错误处理与响应解密等关键能力。建议在不同环境下采用差异化的配置策略，并结合调试与监控手段持续优化性能与稳定性。
+
+[本节为总结，不直接分析具体文件]
+
+## 附录：完整配置示例与最佳实践
+
+### 1) 全局配置示例（开发/测试/生产）
+- 开发环境
+  - prefix: 指向本地/联调地址
+  - httpParams: 注入 debug=true、env=dev、traceId
+  - onHttpError: 输出到控制台或轻量上报
+  - encryptBody: false
+- 测试环境
+  - prefix: 指向测试域名
+  - httpParams: 注入 env=test、version、tenantId
+  - onHttpError: 轻量上报
+  - encryptBody: 可选开启
+- 生产环境
+  - prefix: 指向生产域名
+  - httpParams: 仅注入必要参数（如 tenantId、version）
+  - onHttpError: 完整上报（含堆栈）
+  - encryptBody: 必须开启；base64Key 固定且保密
+
+章节来源
+- [TsGlobalConfig.js:5-21](file://src/utils/TsGlobalConfig.js#L5-L21)
+- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
+
+### 2) 认证配置
+- 方案一：在 headers 中注入 Authorization/Bearer
+- 方案二：在 httpParams 中注入 token 参数
+- 方案三：结合用户 Token 管理（TsStorage.getUserToken）
+
+章节来源
+- [TsHttpUtil.js:108-112](file://src/https/TsHttpUtil.js#L108-L112)
+- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)
+
+### 3) 代理与 SSL
+- 代理：通过网络层或构建工具配置；TsHttpUtil 不直接处理代理。
+- SSL：生产环境必须启用 HTTPS；确保证书有效与中间人攻击防护。
+
+[本节为通用指导，不直接分析具体文件]
+
+### 4) 性能优化与缓存
+- 合理设置 timeout，避免长时间阻塞
+- 对高频 GET 接口增加本地缓存
+- 仅对敏感数据启用加密，评估 CPU 开销
+- 使用 httpParams 合并公共参数，减少请求体积
+
+[本节为通用指导，不直接分析具体文件]
+
+### 5) 调试与监控
+- 在 httpParams 中注入 traceId、version、env
+- onHttpError 上报统一错误，包含 code/message/URL
+- 使用浏览器 Network 面板与后端日志联动定位问题
+
+章节来源
+- [TsGlobalConfig.js:8-9](file://src/utils/TsGlobalConfig.js#L8-L9)
--- a/.qoder/repowiki/zh/content/配置指南/全局配置.md
+++ b/.qoder/repowiki/zh/content/配置指南/全局配置.md
@@ -0,0 +1,348 @@
+# 全局配置
+
+<cite>
+**本文引用的文件**
+- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
+- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
+- [TsCrypto.js](file://src/utils/TsCrypto.js)
+- [TsStorage.js](file://src/utils/TsStorage.js)
+- [TsCommon.js](file://src/utils/TsCommon.js)
+- [TsSM4.js](file://src/utils/TsSM4.js)
+- [index.js](file://index.js)
+- [package.json](file://package.json)
+- [README.md](file://README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与安全考量](#性能与安全考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向“全局配置系统”的使用者与维护者，系统性阐述 TsGlobalConfig 模块的设计理念、实现原理与使用方法，并结合 Http 请求流程、加解密链路与存储模块，给出配置项的数据类型、默认值、取值范围、动态更新机制、优先级处理逻辑、配置示例（开发/生产）、配置存储位置与访问方式、配置验证、错误处理与调试技巧。目标是帮助读者快速理解并正确使用该全局配置体系。
+
+## 项目结构
+该项目采用按功能域组织的目录结构：
+- utils：通用工具与基础能力（全局配置、通用方法、存储、加解密、SM4 实现）
+- https：HTTP 请求封装（基于 umi-request 的扩展）
+- 根目录入口 index.js 汇总导出各模块，供上层业务统一引入
+
+```mermaid
+graph TB
+subgraph "工具模块(utils)"
+GC["TsGlobalConfig.js"]
+CM["TsCommon.js"]
+ST["TsStorage.js"]
+CR["TsCrypto.js"]
+SM["TsSM4.js"]
+end
+subgraph "HTTP模块(https)"
+HT["TsHttpUtil.js"]
+end
+IDX["index.js"] --> GC
+IDX --> CM
+IDX --> ST
+IDX --> CR
+IDX --> SM
+IDX --> HT
+HT --> GC
+HT --> ST
+HT --> CR
+CR --> GC
+CR --> SM
+```
+
+图表来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
+
+章节来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [package.json:1-24](file://package.json#L1-L24)
+
+## 核心组件
+- 全局配置模块 TsGlobalConfig：提供默认配置、读取配置、合并覆盖配置的能力；配置最终存储于 window.httpConfig。
+- HTTP 工具 TsHttpUtil：通过 GlobalConfig 读取前缀、错误回调与附加参数函数；负责请求扩展、参数处理、加解密开关、响应解析与错误回调。
+- 加密模块 TsCrypto：基于 SM4 算法与 base64 密钥，从 GlobalConfig 读取 base64Key 构造密钥缓冲区，支持加密/解密。
+- 存储模块 TsStorage：提供本地存储、用户 Token 与“是否加密 body”的开关读写。
+- 通用模块 TsCommon：提供空值判断、JSON 解析、URL 参数解析、开发环境判断等辅助能力。
+
+章节来源
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
+
+## 架构总览
+下图展示全局配置在系统中的作用与交互关系：HTTP 请求在发起前读取 GlobalConfig 的 prefix、httpParams 与 onHttpError；加密模块在初始化时读取 base64Key；存储模块提供加密开关与用户 Token。
+
+```mermaid
+sequenceDiagram
+participant App as "应用代码"
+participant Http as "TsHttpUtil"
+participant GC as "TsGlobalConfig"
+participant Crypto as "TsCrypto"
+participant Store as "TsStorage"
+participant Net as "umi-request"
+App->>Http : "调用 get/post/form"
+Http->>GC : "读取 prefix / httpParams / onHttpError"
+Http->>Store : "读取用户 Token"
+Http->>Net : "发起请求(含 headers/token)"
+Net-->>Http : "返回响应"
+Http->>Http : "根据响应码处理/解密"
+Http->>GC : "调用 onHttpError(res)"
+Http-->>App : "Promise 返回结果"
+Note over Crypto,GC : "TsCrypto 在构造时读取 base64Key"
+```
+
+图表来源
+- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
+- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
+- [TsCrypto.js:5-13](file://src/utils/TsCrypto.js#L5-L13)
+- [TsStorage.js:13-23](file://src/utils/TsStorage.js#L13-L23)
+
+## 详细组件分析
+
+### TsGlobalConfig 设计与实现
+- 默认配置 defaultConfig
+  - base64Key: 字符串，用于 SM4 密钥的 base64 编码形式
+  - prefix: 字符串或函数，用于拼接请求前缀
+  - onHttpError: 函数，用于统一处理 HTTP 错误
+  - httpParams: 函数，用于为每次请求注入额外参数
+- getConfig
+  - 从 window.httpConfig 读取当前配置；若未设置则回退到 defaultConfig
+- setConfig
+  - 将传入对象与当前配置进行浅合并后写回 window.httpConfig
+
+```mermaid
+flowchart TD
+Start(["调用 setConfig(obj)"]) --> GetCur["读取当前配置<br/>window.httpConfig 或 defaultConfig"]
+GetCur --> Merge["浅合并: {...cur, ...obj}"]
+Merge --> Write["写回 window.httpConfig"]
+Write --> End(["完成"])
+```
+
+图表来源
+- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
+- [TsGlobalConfig.js:19-21](file://src/utils/TsGlobalConfig.js#L19-L21)
+
+章节来源
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+
+### 配置项详解与使用
+
+- base64Key
+  - 类型：字符串（Base64 编码）
+  - 默认值：见默认配置
+  - 作用：作为 SM4 密钥的 base64 字符串，在加密模块初始化时转换为字节缓冲区
+  - 取值范围：需满足 SM4 密钥长度要求（构造函数会校验长度）
+  - 使用建议：生产环境务必由后端提供并保持一致；不要硬编码在前端
+  - 访问方式：通过 GlobalConfig.getConfig().base64Key
+  - 关联模块：TsCrypto、TsSM4
+
+- prefix
+  - 类型：字符串或函数
+  - 默认值：空字符串
+  - 作用：为请求 URL 添加统一前缀；若为函数，则以 URL 为参数动态计算前缀
+  - 取值范围：任意字符串或可返回字符串的函数
+  - 使用建议：开发环境与生产环境可通过函数区分；避免硬编码路径
+  - 访问方式：通过 GlobalConfig.getConfig().prefix
+  - 关联模块：TsHttpUtil
+
+- onHttpError
+  - 类型：函数
+  - 默认值：空函数
+  - 作用：统一处理 HTTP 响应非 200 的场景；接收响应对象
+  - 取值范围：函数签名需兼容接收响应对象
+  - 使用建议：可在其中记录日志、弹窗提示、跳转登录等
+  - 访问方式：通过 GlobalConfig.getConfig().onHttpError(res)
+  - 关联模块：TsHttpUtil
+
+- httpParams
+  - 类型：函数
+  - 默认值：空函数
+  - 作用：为每次请求注入额外参数；GET 请求合并到 params，非 GET 且非 form 合并到 data
+  - 取值范围：函数需返回参数对象
+  - 使用建议：可用于注入公共查询条件、租户信息、时间戳等
+  - 访问方式：通过 GlobalConfig.getConfig().httpParams()
+  - 关联模块：TsHttpUtil
+
+章节来源
+- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
+- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
+- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+- [TsSM4.js:102-106](file://src/utils/TsSM4.js#L102-L106)
+
+### 动态更新机制与优先级
+- 更新机制
+  - setConfig 会将传入对象与当前配置进行浅合并，写回 window.httpConfig
+  - getConfig 读取 window.httpConfig，若未设置则回退到默认配置
+- 优先级
+  - 传入对象 > 当前配置 > 默认配置
+  - 若传入对象中某键缺失，则沿用当前配置；若当前配置也缺失，则使用默认配置
+- 注意事项
+  - 浅合并意味着嵌套对象不会递归合并；如需深层覆盖，应在传入对象中直接提供完整结构
+  - prefix 支持函数，可在运行时根据 URL 动态决定前缀
+
+章节来源
+- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
+- [TsGlobalConfig.js:19-21](file://src/utils/TsGlobalConfig.js#L19-L21)
+
+### 配置存储位置与访问方式
+- 存储位置：window.httpConfig
+- 访问方式：
+  - 读取：GlobalConfig.getConfig()
+  - 写入：GlobalConfig.setConfig(obj)
+- 适用场景：
+  - 开发环境：可注入测试前缀、日志输出的错误处理函数
+  - 生产环境：注入真实域名前缀、统一鉴权头、错误上报回调
+
+章节来源
+- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
+
+### 配置示例（开发/生产）
+
+- 开发环境示例
+  - 前缀：指向本地或测试服务
+  - 错误处理：控制台打印
+  - 附加参数：注入测试租户或调试标记
+  - 加密开关：可关闭或开启（视需求而定）
+
+- 生产环境示例
+  - 前缀：指向正式域名
+  - 错误处理：统一上报、登录跳转
+  - 附加参数：注入用户标识、时间戳、签名等
+  - 加密开关：开启加密体（encrypt_body），并确保 base64Key 与后端一致
+
+说明：以上为使用思路与最佳实践，具体实现请参考 README 中的示例与各模块源码。
+
+章节来源
+- [README.md:12-26](file://README.md#L12-L26)
+- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+
+### 配置验证与错误处理
+- 配置验证
+  - base64Key 长度校验：SM4 构造函数会校验密钥长度为 16 字节
+  - prefix 类型校验：若为函数，需确保返回字符串
+  - httpParams 类型校验：需返回对象
+  - onHttpError 类型校验：需为函数
+- 错误处理
+  - HTTP 层：统一错误处理函数 onHttpError(res)
+  - 加密层：密钥不匹配或格式错误会在加密/解密阶段抛出异常
+  - 存储层：本地存储失败时会降级为默认值
+
+章节来源
+- [TsSM4.js:102-106](file://src/utils/TsSM4.js#L102-L106)
+- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+
+### 调试技巧
+- 打印当前配置：在关键位置调用 GlobalConfig.getConfig() 输出配置快照
+- 检查前缀拼接：在请求发起前打印最终 URL
+- 检查附加参数：在 dealParamsBody 中断点查看 extraParams 与 options 的合并结果
+- 检查加密开关：通过 TsStorage.getEncryptBody() 确认是否启用加密体
+- 检查错误回调：在 onHttpError 中记录响应状态与消息，便于定位问题
+
+章节来源
+- [TsGlobalConfig.js:19-21](file://src/utils/TsGlobalConfig.js#L19-L21)
+- [TsHttpUtil.js:70-91](file://src/https/TsHttpUtil.js#L70-L91)
+- [TsStorage.js:21-23](file://src/utils/TsStorage.js#L21-L23)
+
+## 依赖关系分析
+- TsHttpUtil 依赖
+  - GlobalConfig：读取 prefix、httpParams、onHttpError
+  - Storage：读取用户 Token、加密开关
+  - Crypto：在需要时对请求体进行加密
+- TsCrypto 依赖
+  - GlobalConfig：读取 base64Key
+  - SM4：执行加解密
+- index.js 汇总导出所有模块，供上层统一引入
+
+```mermaid
+graph LR
+HT["TsHttpUtil"] --> GC["TsGlobalConfig"]
+HT --> ST["TsStorage"]
+HT --> CR["TsCrypto"]
+CR --> GC
+CR --> SM["TsSM4"]
+IDX["index.js"] --> GC
+IDX --> HT
+IDX --> CR
+IDX --> ST
+IDX --> SM
+```
+
+图表来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
+- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
+
+章节来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
+- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
+
+## 性能与安全考量
+- 性能
+  - setConfig 为浅合并，开销极低；建议仅在应用启动时进行一次全局配置
+  - httpParams 为函数调用，建议避免复杂计算；必要时可缓存结果
+  - 加密体仅在开启加密开关时启用，避免不必要的 CPU 开销
+- 安全
+  - base64Key 不要硬编码在前端；生产环境由后端下发或通过安全渠道同步
+  - 建议在生产环境强制开启加密体，并定期轮换密钥
+  - onHttpError 中避免泄露敏感信息
+
+[本节为通用指导，无需特定文件来源]
+
+## 故障排查指南
+- 无法读取配置
+  - 确认是否已调用 setConfig；否则 getConfig 将返回默认配置
+- 前缀无效
+  - 检查 prefix 是字符串还是函数；若是函数，确认其返回值为字符串
+- 附加参数未生效
+  - 确认 httpParams 返回对象；GET 请求合并到 params，非 GET 且非 form 合并到 data
+- 加密异常
+  - 检查 base64Key 是否为 16 字节对应的 Base64；确认前后端密钥一致
+- 错误回调未触发
+  - 确认响应码非 200；onHttpError 仅在非 200 时调用
+
+章节来源
+- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
+- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
+- [TsHttpUtil.js:124-127](file://src/https/TsHttpUtil.js#L124-L127)
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+- [TsSM4.js:102-106](file://src/utils/TsSM4.js#L102-L106)
+
+## 结论
+TsGlobalConfig 提供了简洁、灵活的全局配置能力，配合 TsHttpUtil、TsCrypto、TsStorage 等模块，形成完整的请求、加解密与存储闭环。通过 window.httpConfig 统一管理配置，既保证了易用性，又兼顾了动态更新与优先级处理。建议在实际项目中：
+- 在应用启动阶段集中 setConfig
+- 明确区分开发/生产环境的前缀与错误处理策略
+- 严格管理 base64Key，确保前后端一致
+- 合理使用 httpParams 注入公共参数，避免重复代码
+
+[本节为总结，无需特定文件来源]
+
+## 附录
+
+### API 一览（来自模块导出）
+- index.js 汇总导出：TsHttpUtil、TsCommon、TsStorage、TsSM4、TsCrypto、TsGlobalConfig
+- README.md 提供了基本使用示例（含 setConfig 与 post 调用）
+
+章节来源
+- [index.js:8-15](file://index.js#L8-L15)
+- [README.md:12-26](file://README.md#L12-L26)
--- a/.qoder/repowiki/zh/content/配置指南/加密配置.md
+++ b/.qoder/repowiki/zh/content/配置指南/加密配置.md
@@ -0,0 +1,352 @@
+# 加密配置
+
+<cite>
+**本文引用的文件列表**
+- [TsSM4.js](file://src/utils/TsSM4.js)
+- [TsCrypto.js](file://src/utils/TsCrypto.js)
+- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
+- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
+- [TsStorage.js](file://src/utils/TsStorage.js)
+- [index.js](file://index.js)
+- [package.json](file://package.json)
+- [README.md](file://README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南围绕项目中的 SM4 加密配置展开，系统性说明 CBC 与 ECB 模式的配置与使用差异、base64Key 的作用与长度要求、安全性考量，以及在数据传输加密与存储加密等场景下的配置建议。同时覆盖加密模式切换、与全局配置的关系与继承机制、最佳实践（密钥管理、性能优化、安全加固）、以及测试与验证方法。文档严格基于仓库源码进行分析与总结，避免臆测。
+
+## 项目结构
+该项目采用“工具类 + 组件化”的组织方式：
+- 工具层：SM4 实现、通用加密封装、全局配置、本地存储、通用方法
+- 业务集成层：HTTP 请求工具，负责在请求前后对数据进行加解密
+- 入口导出：统一通过入口文件导出各模块
+
+```mermaid
+graph TB
+subgraph "工具层"
+SM4["TsSM4<br/>SM4 加密实现"]
+Crypto["TsCrypto<br/>基于 SM4 的加密封装"]
+GlobalCfg["TsGlobalConfig<br/>全局配置"]
+Storage["TsStorage<br/>本地存储"]
+Common["TsCommon<br/>通用方法"]
+end
+subgraph "业务集成层"
+HttpUtil["TsHttpUtil<br/>HTTP 请求工具"]
+end
+SM4 --> Crypto
+GlobalCfg --> Crypto
+Crypto --> HttpUtil
+Storage --> HttpUtil
+Common --> HttpUtil
+```
+
+图表来源
+- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+
+章节来源
+- [index.js:1-16](file://index.js#L1-L16)
+- [package.json:1-24](file://package.json#L1-L24)
+
+## 核心组件
+- SM4 加密实现：提供 CBC/ECB 模式、PKCS#7 填充、Base64 文本输出、密钥扩展与轮函数等完整实现
+- 加密封装：基于 SM4 构建默认实例，读取全局配置中的 base64Key，并默认以 ECB 模式工作
+- 全局配置：提供 base64Key、前缀、HTTP 参数注入、错误回调等配置项
+- HTTP 工具：在请求体加密开关开启时，对请求体进行加密；在响应标记为加密时进行解密
+- 本地存储：提供开关控制是否对请求体进行加密
+
+章节来源
+- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
+- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
+- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)
+- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+
+## 架构总览
+下图展示了从请求发起到加解密处理的关键流程，以及与全局配置、本地存储的关系。
+
+```mermaid
+sequenceDiagram
+participant Client as "调用方"
+participant HttpUtil as "TsHttpUtil"
+participant Storage as "TsStorage"
+participant Crypto as "TsCrypto"
+participant SM4 as "TsSM4"
+participant Server as "后端服务"
+Client->>HttpUtil : "post(url, data)"
+HttpUtil->>Storage : "getEncryptBody()"
+Storage-->>HttpUtil : "true/false"
+alt "需要加密"
+HttpUtil->>Crypto : "encrypt(JSON.stringify(data))"
+Crypto->>SM4 : "encrypt(明文)"
+SM4-->>Crypto : "密文(Base64)"
+Crypto-->>HttpUtil : "密文(Base64)"
+HttpUtil->>Server : "POST { encryptData : 密文 }"
+else "无需加密"
+HttpUtil->>Server : "POST data"
+end
+Server-->>HttpUtil : "响应 { code, data, encrypt? }"
+alt "响应标记为加密"
+HttpUtil->>Crypto : "decrypt(data)"
+Crypto->>SM4 : "decrypt(密文)"
+SM4-->>Crypto : "明文"
+Crypto-->>HttpUtil : "明文"
+HttpUtil-->>Client : "{ data, recordsTotal }"
+else "未加密响应"
+HttpUtil-->>Client : "{ data, recordsTotal }"
+end
+```
+
+图表来源
+- [TsHttpUtil.js:82-88](file://src/https/TsHttpUtil.js#L82-L88)
+- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
+- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
+- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
+- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+
+## 详细组件分析
+
+### SM4 加密实现（TsSM4）
+- 模式支持：CBC、ECB 双模式，可通过构造参数选择
+- IV 要求：CBC 模式必须提供 16 字节 IV；ECB 模式可省略 IV
+- 密钥要求：必须为 16 字节（128 位），构造时会校验
+- 输出类型：支持 Base64 与文本两种输出类型
+- 填充策略：PKCS#7 填充，解密时自动去除
+- 轮函数与密钥扩展：内置完整的 SM4 轮函数与轮密钥生成逻辑
+
+```mermaid
+classDiagram
+class Crypt {
+stringToArrayBufferInUtf8(str) Uint8Array
+utf8ArrayBufferToString(buf) String
+arrayBufferToBase64(buf) String
+base64ToArrayBuffer(str) Uint8Array
+}
+class TsSM4 {
+Uint8Array key
+Uint8Array iv
+String mode
+String cipherType
+Uint32Array encryptRoundKeys
+Uint32Array decryptRoundKeys
+doBlockCrypt(blockData, roundKeys) Uint32Array
+spawnEncryptRoundKeys() void
+padding(buffer) Uint8Array
+dePadding(buffer) Uint8Array
+uint8ToUint32Block(arr, baseIndex) Uint32Array
+encrypt(plaintext) String
+decrypt(ciphertext) String
+}
+TsSM4 --> Crypt : "使用"
+```
+
+图表来源
+- [TsSM4.js:39-94](file://src/utils/TsSM4.js#L39-L94)
+- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)
+
+章节来源
+- [TsSM4.js:102-156](file://src/utils/TsSM4.js#L102-L156)
+- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
+- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
+
+### 加密封装（TsCrypto）
+- 默认使用 ECB 模式
+- 从全局配置读取 base64Key 并转换为字节数组作为密钥
+- 对外暴露 encrypt、decrypt 接口，内部委托给 TsSM4
+
+章节来源
+- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
+- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
+
+### 全局配置（TsGlobalConfig）
+- 提供 base64Key、prefix、httpParams、onHttpError 等配置项
+- 支持运行时 setConfig 合并默认配置
+- HTTP 工具通过 getConfig 获取 prefix 与 httpParams 注入
+
+章节来源
+- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)
+- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
+- [TsHttpUtil.js:72-74](file://src/https/TsHttpUtil.js#L72-L74)
+
+### HTTP 工具（TsHttpUtil）
+- 在请求体加密开关开启时，将 data 包装为 { encryptData: 加密结果 }
+- 在响应标记 encrypt 时，对 data 执行解密并解析 JSON
+- 支持 GET/POST/form 等多种请求类型
+
+章节来源
+- [TsHttpUtil.js:82-88](file://src/https/TsHttpUtil.js#L82-L88)
+- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
+- [TsHttpUtil.js:142-154](file://src/https/TsHttpUtil.js#L142-L154)
+- [TsHttpUtil.js:163-165](file://src/https/TsHttpUtil.js#L163-L165)
+
+### 本地存储（TsStorage）
+- 提供 getEncryptBody/saveEncryptBody 开关，用于控制请求体是否加密
+- 与 HTTP 工具配合使用
+
+章节来源
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+
+## 依赖关系分析
+- TsCrypto 依赖 TsSM4 与 TsGlobalConfig
+- TsHttpUtil 依赖 TsCrypto、TsStorage、TsGlobalConfig
+- TsSM4 依赖 base64js（用于 Base64 编解码）
+
+```mermaid
+graph LR
+base64js["base64js"] --> SM4["TsSM4"]
+GlobalCfg["TsGlobalConfig"] --> Crypto["TsCrypto"]
+SM4 --> Crypto
+Crypto --> HttpUtil["TsHttpUtil"]
+Storage["TsStorage"] --> HttpUtil
+Common["TsCommon"] --> HttpUtil
+```
+
+图表来源
+- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
+- [TsSM4.js:1](file://src/utils/TsSM4.js#L1)
+- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
+
+章节来源
+- [package.json:19-22](file://package.json#L19-L22)
+
+## 性能考量
+- 模式选择
+  - ECB：每块独立加密，适合无状态、可并行处理的场景；但相同明文块会产生相同密文块，易受统计分析攻击
+  - CBC：引入链式传播，相同明文块不会产生相同密文块，更安全；但需 16 字节 IV，且加密过程串行
+- 输出类型
+  - Base64 输出便于网络传输与日志记录，但会增加约 33% 的体积；文本输出取决于底层编码，通常体积更小
+- 填充开销
+  - PKCS#7 填充会在明文末尾追加若干字节，对小数据影响较小
+- 建议
+  - 优先使用 CBC 模式（若后端支持 IV），并在需要时启用 Base64 输出
+  - 对大体量数据，考虑分块或压缩后再加密，减少网络往返
+
+## 故障排查指南
+- 常见错误与定位
+  - “密钥长度不为 16 字节”：检查 base64Key 是否正确，确保解码后为 16 字节
+  - “IV 错误”：CBC 模式必须提供 16 字节 IV；确认传入的 iv 长度与编码
+  - “输出类型不匹配”：若后端返回非 Base64 内容，需将 cipherType 设置为文本
+  - “解密失败”：确认使用的密钥与模式一致，且数据未被篡改
+- 定位步骤
+  - 确认全局配置中 base64Key 是否正确设置
+  - 检查请求体加密开关是否按预期开启
+  - 核对响应是否标记为加密，以及解密流程是否执行
+  - 使用最小化复现：仅传递一段固定明文，观察加解密结果一致性
+
+章节来源
+- [TsSM4.js:103-105](file://src/utils/TsSM4.js#L103-L105)
+- [TsSM4.js:118-121](file://src/utils/TsSM4.js#L118-L121)
+- [TsSM4.js:345-347](file://src/utils/TsSM4.js#L345-L347)
+- [TsSM4.js:410-412](file://src/utils/TsSM4.js#L410-L412)
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+- [TsHttpUtil.js:82-88](file://src/https/TsHttpUtil.js#L82-L88)
+- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
+
+## 结论
+本项目以 TsSM4 为核心，通过 TsCrypto 封装默认 ECB 模式与 base64Key，结合 TsHttpUtil 的请求体加密与响应解密能力，形成一套可配置、可扩展的加密方案。实际部署中应优先采用 CBC 模式并妥善管理 IV 与密钥，确保输出类型与后端一致，并通过全局配置集中管理密钥与前缀等参数。
+
+## 附录
+
+### 加密配置选项与说明
+- base64Key
+  - 作用：作为 SM4 密钥的 Base64 字符串，构造时会被解码为 16 字节密钥
+  - 长度要求：解码后必须为 16 字节（128 位）
+  - 安全性：应由后端生成并下发，避免硬编码泄露；定期轮换
+- 模式选择
+  - CBC：需提供 16 字节 IV；更安全，推荐用于大多数场景
+  - ECB：无需 IV；简单但安全性较低，仅在特定场景使用
+- 输出类型
+  - Base64：便于网络传输与日志记录
+  - 文本：体积更小，但需确保后端一致
+- IV 要求
+  - CBC 模式必须提供 16 字节 IV；ECB 模式可省略
+
+章节来源
+- [TsSM4.js:102-156](file://src/utils/TsSM4.js#L102-L156)
+- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
+- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+
+### 不同场景下的配置建议
+- 数据传输加密（HTTP 请求体）
+  - 开启请求体加密开关
+  - 使用 CBC 模式并提供 16 字节 IV（若后端支持）
+  - 输出类型建议 Base64
+- 存储加密（本地或数据库）
+  - 若明文为字符串，建议使用 ECB 模式简化处理
+  - 若存在重复明文块，建议使用 CBC 模式并随机 IV
+  - 输出类型根据存储介质选择（Base64 更通用）
+
+章节来源
+- [TsHttpUtil.js:82-88](file://src/https/TsHttpUtil.js#L82-L88)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+
+### 加密模式切换与注意事项
+- 切换方法
+  - 通过 TsCrypto 构造参数或直接创建 TsSM4 实例指定 mode 与 iv/cipherType
+- 注意事项
+  - CBC 必须提供 16 字节 IV；ECB 可省略 IV
+  - 输出类型需与后端保持一致
+  - 切换模式后需同步后端解密逻辑
+
+章节来源
+- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
+- [TsSM4.js:128-141](file://src/utils/TsSM4.js#L128-L141)
+- [TsSM4.js:343-378](file://src/utils/TsSM4.js#L343-L378)
+- [TsSM4.js:408-447](file://src/utils/TsSM4.js#L408-L447)
+
+### 最佳实践
+- 密钥管理
+  - 使用强随机生成的 16 字节密钥，避免硬编码
+  - 通过安全渠道下发 base64Key，定期轮换
+- 性能优化
+  - 对小数据优先使用 ECB；对大数据优先使用 CBC
+  - 合理选择输出类型，平衡体积与兼容性
+- 安全加固
+  - CBC 模式务必使用随机 IV
+  - 对响应数据进行完整性校验（如 HMAC）
+  - 限制日志中输出密文，必要时仅输出摘要
+
+### 加密配置与全局配置的关系与继承机制
+- TsCrypto 默认从全局配置读取 base64Key，并以 ECB 模式初始化
+- TsHttpUtil 通过 GlobalConfig.getConfig 获取 prefix 与 httpParams，用于请求拼接与参数注入
+- setConfig 可合并默认配置，实现运行时动态调整
+
+章节来源
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
+- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
+- [TsHttpUtil.js:72-74](file://src/https/TsHttpUtil.js#L72-L74)
+
+### 测试方法与验证步骤
+- 单元测试（建议）
+  - 使用固定明文与密钥，验证加解密一致性
+  - 分别测试 ECB 与 CBC 模式，确保 IV 正确性
+  - 验证 Base64 与文本输出类型的互操作
+- 端到端测试（建议）
+  - 通过 HTTP 工具发起请求，开启请求体加密，验证响应解密
+  - 模拟后端响应标记为加密，验证解密流程
+- 日志与监控
+  - 记录关键配置项（模式、输出类型、IV 是否提供）
+  - 对异常进行捕获与上报
+
+章节来源
+- [README.md:12-26](file://README.md#L12-L26)
+- [TsHttpUtil.js:82-88](file://src/https/TsHttpUtil.js#L82-L88)
+- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
--- a/.qoder/repowiki/zh/content/配置指南/存储配置.md
+++ b/.qoder/repowiki/zh/content/配置指南/存储配置.md
@@ -0,0 +1,545 @@
+# 存储配置
+
+<cite>
+**本文档引用的文件**
+- [TsStorage.js](file://src/utils/TsStorage.js)
+- [TsCrypto.js](file://src/utils/TsCrypto.js)
+- [TsSM4.js](file://src/utils/TsSM4.js)
+- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
+- [TsCommon.js](file://src/utils/TsCommon.js)
+- [index.js](file://index.js)
+- [package.json](file://package.json)
+- [README.md](file://README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本指南专注于 TsStorage 模块的存储配置，这是一个基于 localStorage 的轻量级存储解决方案。该模块提供了完整的数据持久化功能，包括基础存储操作、用户令牌管理、数据加密以及全局配置管理。通过本文档，您将了解如何正确配置和使用存储功能，包括存储前缀、加密开关、存储策略等关键配置选项。
+
+## 项目结构
+
+该项目采用模块化设计，主要包含以下核心文件：
+
+```mermaid
+graph TB
+subgraph "核心模块"
+A[index.js<br/>主入口文件]
+B[TsStorage.js<br/>存储模块]
+C[TsCrypto.js<br/>加密模块]
+D[TsSM4.js<br/>SM4算法实现]
+E[TsGlobalConfig.js<br/>全局配置]
+F[TsCommon.js<br/>通用工具]
+end
+subgraph "外部依赖"
+G[base64-js<br/>Base64编码]
+H[umi-request<br/>HTTP请求]
+end
+A --> B
+A --> C
+A --> D
+A --> E
+A --> F
+C --> D
+C --> E
+B --> F
+D --> G
+A --> H
+```
+
+**图表来源**
+- [index.js:1-16](file://index.js#L1-L16)
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+
+**章节来源**
+- [index.js:1-16](file://index.js#L1-L16)
+- [package.json:1-24](file://package.json#L1-L24)
+
+## 核心组件
+
+### TsStorage 模块
+
+TsStorage 是整个存储系统的核心模块，提供了以下主要功能：
+
+- **基础存储操作**：提供通用的保存和获取方法
+- **用户令牌管理**：专门处理用户认证令牌的存储
+- **加密开关控制**：支持启用或禁用数据加密功能
+- **数据序列化**：自动处理 JSON 序列化和反序列化
+
+### TsCrypto 模块
+
+负责数据加密和解密的核心模块，基于 SM4 算法实现：
+
+- **SM4 加密算法**：实现中国国家密码标准的 SM4 对称加密
+- **密钥管理**：从全局配置中获取和管理加密密钥
+- **模式支持**：支持 ECB 和 CBC 两种加密模式
+
+### TsSM4 模块
+
+SM4 算法的具体实现，包含完整的加密和解密逻辑：
+
+- **算法实现**：完整的 SM4 加密算法实现
+- **填充机制**：支持 PKCS7 填充标准
+- **多种输出格式**：支持 Base64 和文本两种输出格式
+
+**章节来源**
+- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
+
+## 架构概览
+
+存储系统的整体架构采用分层设计，确保了功能的模块化和可维护性：
+
+```mermaid
+graph TD
+subgraph "应用层"
+App[应用程序]
+end
+subgraph "存储接口层"
+Storage[Storage 接口]
+Crypto[Crypto 接口]
+end
+subgraph "业务逻辑层"
+Token[用户令牌管理]
+Config[配置管理]
+Utils[通用工具]
+end
+subgraph "数据访问层"
+LocalStorage[localStorage]
+Memory[内存缓存]
+end
+App --> Storage
+App --> Crypto
+Storage --> Token
+Storage --> Config
+Storage --> Utils
+Crypto --> SM4
+Utils --> LocalStorage
+Storage --> LocalStorage
+Crypto --> Memory
+```
+
+**图表来源**
+- [TsStorage.js:26-43](file://src/utils/TsStorage.js#L26-L43)
+- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
+- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
+
+## 详细组件分析
+
+### 存储配置选项详解
+
+#### 基础存储配置
+
+TsStorage 模块提供了灵活的基础存储配置选项：
+
+**数据序列化配置**
+- 自动 JSON 序列化：所有存储的数据都会被自动转换为 JSON 字符串
+- 安全反序列化：使用安全的 JSON 解析机制，避免异常导致的应用崩溃
+- 默认值处理：支持为不存在的键提供默认值
+
+**存储策略配置**
+- 键值映射：每个存储项都以键值对的形式保存在 localStorage 中
+- 数据包装：内部使用 `{data: value}` 的包装格式存储原始数据
+- 类型保持：通过 JSON 序列化保持数据类型信息
+
+#### 加密存储配置
+
+**加密开关配置**
+- `saveEncryptBody(bool)`：设置是否启用数据加密
+- `getEncryptBody()`：获取当前加密状态
+- 默认启用：加密功能默认处于启用状态
+
+**加密算法配置**
+- SM4 算法：采用中国国家密码标准的对称加密算法
+- ECB 模式：默认使用 ECB 模式进行加密
+- Base64 输出：加密结果以 Base64 格式存储
+
+**密钥配置**
+- 全局密钥管理：密钥从全局配置中获取
+- Base64 编码：密钥以 Base64 格式存储和传输
+- 配置覆盖：支持运行时动态修改密钥
+
+#### 用户令牌配置
+
+**令牌存储配置**
+- 专用令牌键：使用固定的 'token' 键存储用户令牌
+- 自动序列化：令牌数据自动进行 JSON 序列化
+- 空值处理：未找到令牌时返回空字符串
+
+**令牌管理策略**
+- 单一令牌模型：系统只支持单一用户令牌
+- 简化接口：提供简化的 get/set 方法
+- 安全存储：令牌数据同样遵循加密配置
+
+**章节来源**
+- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)
+- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
+- [TsCrypto.js:7-13](file://src/utils/TsCrypto.js#L7-L13)
+
+### 存储场景配置建议
+
+#### 用户会话存储
+
+**配置策略**
+- 启用加密：用户会话数据包含敏感信息，必须启用加密
+- 设置过期时间：结合业务需求设置合理的过期时间
+- 清理策略：定期清理过期的会话数据
+
+**实现示例**
+```javascript
+// 启用加密存储
+Storage.saveEncryptBody(true);
+
+// 存储用户令牌
+Storage.saveUserToken(token);
+
+// 获取用户令牌
+const token = Storage.getUserToken();
+```
+
+#### 应用状态存储
+
+**配置策略**
+- 非敏感数据：非敏感的应用状态可以不启用加密
+- 性能优化：对于大量数据的存储，考虑启用加密可能影响性能
+- 数据压缩：对于大体量数据，考虑先压缩再存储
+
+**实现示例**
+```javascript
+// 根据数据敏感性选择加密
+if (isSensitiveData) {
+    Storage.saveEncryptBody(true);
+} else {
+    Storage.saveEncryptBody(false);
+}
+
+// 存储应用配置
+Storage.save('appConfig', configData);
+```
+
+#### 临时数据存储
+
+**配置策略**
+- 短期存储：临时数据适合短期存储，不需要长期保留
+- 自动清理：设置合理的过期时间，避免占用过多存储空间
+- 批量清理：定期清理过期的临时数据
+
+**章节来源**
+- [TsStorage.js:47-54](file://src/utils/TsStorage.js#L47-L54)
+
+### 存储容量限制和清理策略
+
+#### 容量限制
+
+**localStorage 限制**
+- 浏览器限制：每个域名下通常有 5-10MB 的存储限制
+- 平台差异：不同浏览器的限制可能有所不同
+- 存储检查：需要定期检查存储使用情况
+
+**容量监控**
+- 使用率计算：监控已用空间与总容量的比例
+- 预警机制：当使用率达到一定阈值时发出警告
+- 自动清理：超过阈值时自动清理过期数据
+
+#### 清理策略
+
+**定时清理**
+- 周期性清理：定期执行清理任务，删除过期数据
+- 条件清理：根据存储使用情况触发清理
+- 批量清理：一次性清理多个过期项目
+
+**智能清理**
+- 优先级清理：优先清理低优先级的过期数据
+- 空间回收：清理后释放存储空间
+- 性能优化：清理过程不影响正常的数据访问
+
+**章节来源**
+- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
+
+### 加密存储配置方法和性能影响
+
+#### 加密配置方法
+
+**基本加密配置**
+```javascript
+// 创建加密实例
+const crypto = new TsCrypto();
+
+// 加密数据
+const encrypted = crypto.encrypt("敏感数据");
+
+// 解密数据
+const decrypted = crypto.decrypt(encrypted);
+```
+
+**高级配置选项**
+- 模式选择：ECB 或 CBC 模式的选择
+- 输出格式：Base64 或文本格式的输出
+- IV 参数：CBC 模式的初始化向量配置
+
+#### 性能影响分析
+
+**CPU 开销**
+- 加密开销：加密操作需要额外的 CPU 时间
+- 解密开销：解密操作同样消耗 CPU 资源
+- 批量处理：批量处理数据时的性能考虑
+
+**内存使用**
+- 内存占用：加密算法需要额外的内存空间
+- 数据复制：加密过程中可能产生数据副本
+- 缓存策略：合理使用缓存减少重复计算
+
+**I/O 影响**
+- 序列化成本：JSON 序列化和反序列化的影响
+- 存储效率：加密后的数据大小变化
+- 网络传输：加密数据在网络传输中的影响
+
+**章节来源**
+- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
+- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
+
+### 存储配置的安全考虑和最佳实践
+
+#### 安全配置
+
+**密钥管理**
+- 密钥强度：确保密钥具有足够的随机性和长度
+- 密钥轮换：定期更换加密密钥
+- 安全存储：密钥的存储和传输要确保安全
+
+**数据保护**
+- 敏感数据：识别和保护敏感数据
+- 访问控制：限制对敏感数据的访问权限
+- 审计日志：记录重要的数据访问和修改操作
+
+**传输安全**
+- HTTPS 传输：确保数据在传输过程中的安全
+- 中间人攻击：防范中间人攻击和数据篡改
+- 会话管理：安全的会话管理和令牌处理
+
+#### 最佳实践
+
+**配置最佳实践**
+- 最小权限原则：只授予必要的存储权限
+- 数据最小化：只存储必要的数据
+- 及时清理：及时清理不再需要的数据
+
+**性能最佳实践**
+- 异步操作：使用异步方式处理存储操作
+- 批量处理：批量处理多个存储请求
+- 缓存策略：合理使用缓存提高性能
+
+**错误处理最佳实践**
+- 异常捕获：妥善处理存储操作中的异常
+- 降级策略：在存储失败时提供降级方案
+- 用户提示：向用户提供清晰的错误信息
+
+**章节来源**
+- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
+- [TsCrypto.js:8-12](file://src/utils/TsCrypto.js#L8-L12)
+
+### 存储配置的迁移和备份策略
+
+#### 迁移策略
+
+**版本兼容性**
+- 数据格式升级：确保新版本能够读取旧版本的数据
+- 渐进式迁移：逐步将旧数据迁移到新格式
+- 回滚机制：提供数据迁移失败时的回滚方案
+
+**配置迁移**
+- 配置项更新：处理配置项的新增、删除和重命名
+- 默认值处理：为新配置项设置合理的默认值
+- 兼容性测试：确保迁移过程不影响现有功能
+
+#### 备份策略
+
+**数据备份**
+- 定期备份：建立定期备份机制
+- 多点备份：在多个位置保存备份数据
+- 自动恢复：提供自动数据恢复功能
+
+**配置备份**
+- 配置导出：支持配置的导出和导入
+- 版本管理：管理配置的不同版本
+- 快速恢复：提供快速恢复到之前配置的能力
+
+**章节来源**
+- [TsStorage.js:26-43](file://src/utils/TsStorage.js#L26-L43)
+- [TsGlobalConfig.js:27-29](file://src/utils/TsGlobalConfig.js#L27-L29)
+
+### 存储配置的调试和监控方法
+
+#### 调试方法
+
+**存储调试**
+- 数据验证：验证存储的数据是否正确
+- 格式检查：检查数据的格式是否符合预期
+- 性能监控：监控存储操作的性能指标
+
+**加密调试**
+- 加密验证：验证加密和解密过程的正确性
+- 密钥检查：确认使用的密钥是否正确
+- 算法验证：验证加密算法的实现是否正确
+
+#### 监控方法
+
+**性能监控**
+- 响应时间：监控存储操作的响应时间
+- 错误率：统计存储操作的错误率
+- 资源使用：监控存储相关的资源使用情况
+
+**健康监控**
+- 存储状态：监控存储系统的健康状态
+- 数据完整性：检查数据的完整性和一致性
+- 安全监控：监控存储相关的安全事件
+
+**章节来源**
+- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
+- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
+
+## 依赖关系分析
+
+存储系统的依赖关系相对简单，主要依赖于几个核心模块：
+
+```mermaid
+graph LR
+subgraph "直接依赖"
+A[TsStorage.js]
+B[TsCrypto.js]
+C[TsSM4.js]
+D[TsCommon.js]
+end
+subgraph "外部依赖"
+E[base64-js]
+F[umi-request]
+end
+subgraph "全局配置"
+G[TsGlobalConfig.js]
+end
+A --> D
+B --> C
+B --> G
+C --> E
+A --> G
+A --> F
+```
+
+**图表来源**
+- [TsStorage.js:1](file://src/utils/TsStorage.js#L1)
+- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
+- [TsSM4.js:1](file://src/utils/TsSM4.js#L1)
+- [TsGlobalConfig.js:1-3](file://src/utils/TsGlobalConfig.js#L1-L3)
+
+**章节来源**
+- [package.json:19-22](file://package.json#L19-L22)
+- [index.js:1-7](file://index.js#L1-L7)
+
+## 性能考虑
+
+### 存储性能优化
+
+**序列化优化**
+- JSON 序列化：使用高效的 JSON 序列化方法
+- 数据压缩：对于大数据量考虑压缩存储
+- 批量操作：合并多个存储请求减少 I/O 操作
+
+**内存管理**
+- 对象复用：复用对象减少内存分配
+- 及时释放：及时释放不再使用的对象引用
+- 垃圾回收：合理安排垃圾回收时机
+
+**并发处理**
+- 异步操作：使用异步方式处理存储操作
+- 锁机制：在需要时使用锁机制保证数据一致性
+- 队列管理：使用队列管理并发的存储请求
+
+### 加密性能优化
+
+**算法优化**
+- 缓存密钥：缓存加密密钥避免重复计算
+- 批量加密：批量处理多个数据项
+- 异步加密：使用异步方式处理加密操作
+
+**资源配置**
+- 线程池：合理配置加密操作的线程池
+- 内存池：使用内存池减少内存分配开销
+- 缓存策略：合理使用缓存提高加密性能
+
+## 故障排除指南
+
+### 常见问题诊断
+
+**存储失败**
+- 检查浏览器兼容性：确认目标浏览器支持 localStorage
+- 验证存储空间：检查是否有足够的存储空间
+- 检查权限设置：确认应用有足够的存储权限
+
+**数据损坏**
+- 验证数据格式：检查存储的数据格式是否正确
+- 检查序列化问题：确认 JSON 序列化和反序列化正常
+- 处理异常数据：对异常数据进行特殊处理
+
+**加密问题**
+- 密钥验证：确认使用的密钥是否正确
+- 算法兼容性：检查加密算法的兼容性
+- 性能问题：监控加密操作的性能表现
+
+### 调试技巧
+
+**日志记录**
+- 关键操作日志：记录重要的存储操作
+- 错误日志：详细记录存储操作中的错误
+- 性能日志：记录存储操作的性能指标
+
+**监控工具**
+- 浏览器开发者工具：使用开发者工具监控存储操作
+- 性能分析器：使用性能分析器分析存储性能
+- 日志分析：定期分析存储相关的日志
+
+**章节来源**
+- [TsCommon.js:34-44](file://src/utils/TsCommon.js#L34-L44)
+- [TsStorage.js:31-43](file://src/utils/TsStorage.js#L31-L43)
+
+## 结论
+
+TsStorage 模块提供了一个功能完整、配置灵活的存储解决方案。通过本文档的详细说明，您可以：
+
+1. **正确配置存储选项**：理解存储前缀、加密开关和存储策略的配置方法
+2. **优化存储性能**：掌握性能优化的最佳实践和注意事项
+3. **确保存储安全**：实施有效的安全措施和最佳实践
+4. **制定迁移策略**：规划数据迁移和备份的完整方案
+5. **有效调试监控**：建立完善的调试和监控体系
+
+该模块的设计充分考虑了实际应用场景的需求，在保证功能完整性的同时，也注重了性能和安全性的平衡。通过合理配置和使用，可以满足大多数应用的存储需求。
+
+## 附录
+
+### 配置参考表
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| base64Key | string | WmdUzPJXbngVNiaSsQrihg== | 加密密钥（Base64编码） |
+| prefix | string | "" | 存储键前缀 |
+| encrypt_body | boolean | true | 是否启用数据加密 |
+| token | string | "" | 用户令牌存储 |
+
+### 使用示例路径
+
+- [基础存储操作:31-43](file://src/utils/TsStorage.js#L31-L43)
+- [用户令牌管理:9-15](file://src/utils/TsStorage.js#L9-L15)
+- [加密开关配置:17-23](file://src/utils/TsStorage.js#L17-L23)
+- [全局配置管理:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
--- a/.qoder/repowiki/zh/content/配置指南/配置指南.md
+++ b/.qoder/repowiki/zh/content/配置指南/配置指南.md
@@ -0,0 +1,695 @@
+# 配置指南
+
+<cite>
+**本文档引用的文件**
+- [package.json](file://package.json)
+- [README.md](file://README.md)
+- [index.js](file://index.js)
+- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
+- [TsCrypto.js](file://src/utils/TsCrypto.js)
+- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
+- [TsSM4.js](file://src/utils/TsSM4.js)
+- [TsStorage.js](file://src/utils/TsStorage.js)
+- [TsCommon.js](file://src/utils/TsCommon.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心配置组件](#核心配置组件)
+4. [架构概览](#架构概览)
+5. [详细配置分析](#详细配置分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+npm-tool 是一个基于 Node.js 的工具包，提供了网络请求、数据加密、存储管理和通用工具等功能。该工具包的核心特性包括：
+
+- **全局配置管理**：支持通过 window 对象进行全局配置
+- **数据加密功能**：基于 SM4 算法的端到端数据加密
+- **HTTP 请求封装**：基于 umi-request 的网络请求工具
+- **本地存储管理**：提供用户令牌和加密开关的持久化存储
+- **环境适配**：支持开发和生产环境的差异化配置
+
+## 项目结构
+
+该项目采用模块化的文件组织方式，主要分为以下几个核心目录：
+
+```mermaid
+graph TB
+subgraph "项目根目录"
+PJSON[package.json]
+README[README.md]
+INDEX[index.js]
+end
+subgraph "源代码目录 (src/)"
+HTTPS[https/]
+UTILS[utils/]
+end
+subgraph "HTTPS 模块"
+HTTP[TsHttpUtil.js]
+end
+subgraph "工具模块"
+COMMON[TsCommon.js]
+CRYPTO[TsCrypto.js]
+GLOBAL[TsGlobalConfig.js]
+SM4[TsSM4.js]
+STORAGE[TsStorage.js]
+end
+INDEX --> HTTP
+INDEX --> COMMON
+INDEX --> CRYPTO
+INDEX --> GLOBAL
+INDEX --> SM4
+INDEX --> STORAGE
+HTTP --> STORAGE
+HTTP --> COMMON
+HTTP --> CRYPTO
+HTTP --> GLOBAL
+CRYPTO --> GLOBAL
+CRYPTO --> SM4
+```
+
+**图表来源**
+- [index.js:1-16](file://index.js#L1-L16)
+- [package.json:1-24](file://package.json#L1-L24)
+
+**章节来源**
+- [package.json:1-24](file://package.json#L1-L24)
+- [index.js:1-16](file://index.js#L1-L16)
+
+## 核心配置组件
+
+### 全局配置系统
+
+全局配置系统是整个工具包的核心配置中心，提供了统一的配置管理和覆盖机制。
+
+#### 配置结构定义
+
+全局配置包含以下核心参数：
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `base64Key` | String | `"WmdUzPJXbngVNiaSsQrihg=="` | SM4 加密算法的基础密钥 |
+| `prefix` | String/Function | `""` | API 请求前缀，可为字符串或函数 |
+| `onHttpError` | Function | `() => {}` | HTTP 错误回调处理器 |
+| `httpParams` | Function | `() => {}` | 额外 HTTP 参数生成器 |
+
+#### 配置优先级机制
+
+```mermaid
+flowchart TD
+A[应用启动] --> B[加载默认配置]
+B --> C[检查 window.httpConfig]
+C --> D{存在自定义配置?}
+D --> |是| E[合并自定义配置]
+D --> |否| F[使用默认配置]
+E --> G[最终配置生效]
+F --> G
+G --> H[配置缓存]
+subgraph "配置合并过程"
+I[源配置] --> J[用户配置]
+J --> K[深度合并]
+K --> L[优先级: 用户配置 > 默认配置]
+end
+```
+
+**图表来源**
+- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
+
+#### 配置设置方法
+
+配置可以通过以下方式设置：
+
+1. **直接调用 setConfig 方法**
+2. **通过 window 对象直接赋值**
+3. **在应用初始化时进行批量配置**
+
+**章节来源**
+- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
+
+### 加密配置系统
+
+加密系统基于 SM4 对称加密算法，提供了端到端的数据保护机制。
+
+#### 加密配置参数
+
+| 参数 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `keyBuffer` | Uint8Array | 是 | 16 字节的密钥缓冲区 |
+| `mode` | String | 否 | 加密模式 (`cbc` 或 `ecb`) |
+| `cipherType` | String | 否 | 输出类型 (`base64` 或 `text`) |
+
+#### 加密流程图
+
+```mermaid
+flowchart TD
+A[输入明文数据] --> B[JSON 序列化]
+B --> C[字节缓冲区转换]
+C --> D[数据填充 (PKCS7)]
+D --> E{加密模式选择}
+E --> |CBC 模式| F[CBC 加密流程]
+E --> |ECB 模式| G[ECB 加密流程]
+F --> H[初始向量处理]
+H --> I[块级加密]
+I --> J[输出 Base64]
+G --> K[块级独立加密]
+K --> J
+J --> L[返回加密结果]
+```
+
+**图表来源**
+- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
+- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
+
+**章节来源**
+- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
+- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)
+
+### HTTP 请求配置
+
+HTTP 请求配置提供了灵活的网络请求参数管理，支持多种配置场景。
+
+#### HTTP 配置参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `credentials` | String | `"include"` | Cookie 传输策略 |
+| `requestType` | String | `"json"` | 请求数据类型 |
+| `headers` | Object | `{}` | 自定义请求头 |
+| `params` | Object | `{}` | GET 请求参数 |
+| `data` | Object | `{}` | POST 请求数据 |
+
+#### 请求处理流程
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant HttpUtil as HTTP 工具
+participant Crypto as 加密模块
+participant Storage as 存储模块
+participant Server as 服务器
+Client->>HttpUtil : 发送请求
+HttpUtil->>HttpUtil : 处理参数
+HttpUtil->>Storage : 获取用户令牌
+Storage-->>HttpUtil : 返回令牌
+alt 需要加密
+HttpUtil->>Crypto : 加密请求数据
+Crypto-->>HttpUtil : 返回加密数据
+end
+HttpUtil->>Server : 发送 HTTP 请求
+Server-->>HttpUtil : 返回响应
+HttpUtil->>HttpUtil : 处理响应
+alt 响应需要解密
+HttpUtil->>Crypto : 解密响应数据
+Crypto-->>HttpUtil : 返回明文数据
+end
+HttpUtil-->>Client : 返回处理后的结果
+```
+
+**图表来源**
+- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
+
+**章节来源**
+- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
+
+## 架构概览
+
+### 整体架构设计
+
+```mermaid
+graph TB
+subgraph "应用层"
+APP[业务应用]
+end
+subgraph "配置管理层"
+GC[全局配置]
+SC[存储配置]
+end
+subgraph "核心服务层"
+HC[HTTP 客户端]
+EC[加密引擎]
+ST[存储服务]
+end
+subgraph "工具层"
+CM[通用工具]
+SM[SM4 实现]
+end
+subgraph "外部依赖"
+UR[umi-request]
+B64[base64-js]
+end
+APP --> GC
+APP --> HC
+APP --> EC
+APP --> ST
+GC --> UR
+HC --> UR
+HC --> EC
+HC --> ST
+EC --> SM
+EC --> B64
+ST --> CM
+GC --> CM
+```
+
+**图表来源**
+- [index.js:8-15](file://index.js#L8-L15)
+- [package.json:19-22](file://package.json#L19-L22)
+
+### 组件交互关系
+
+```mermaid
+classDiagram
+class TsGlobalConfig {
+defaultConfig : Object
+getConfig() : Object
+setConfig(obj) : void
+}
+class TsCrypto {
+-sm4 : TsSM4
+encrypt(content) : String
+decrypt(base64) : String
+}
+class TsHttpUtil {
+req(url, options) : Promise
+get(url, params, options) : Promise
+post(url, data, options) : Promise
+form(url, data, options) : Promise
+}
+class TsSM4 {
+encrypt(plaintext) : String
+decrypt(ciphertext) : String
+}
+class TsStorage {
+save(key, value) : void
+get(key, def) : any
+getUserToken() : String
+saveEncryptBody(bool) : void
+}
+TsHttpUtil --> TsCrypto : 使用
+TsHttpUtil --> TsStorage : 读取
+TsHttpUtil --> TsGlobalConfig : 读取
+TsCrypto --> TsSM4 : 依赖
+TsCrypto --> TsGlobalConfig : 读取密钥
+```
+
+**图表来源**
+- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
+- [TsCrypto.js:5-34](file://src/utils/TsCrypto.js#L5-L34)
+- [TsHttpUtil.js:168-171](file://src/https/TsHttpUtil.js#L168-L171)
+- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
+- [TsStorage.js:47-55](file://src/utils/TsStorage.js#L47-L55)
+
+## 详细配置分析
+
+### 开发环境配置
+
+开发环境推荐配置方案：
+
+#### 基础开发配置
+
+```javascript
+// 开发环境基础配置
+const devConfig = {
+    base64Key: "WmdUzPJXbngVNiaSsQrihg==", // 开发环境密钥
+    prefix: "http://localhost:8080/api", // 开发服务器地址
+    onHttpError: (res) => {
+        console.error("开发环境错误:", res);
+    },
+    httpParams: () => ({
+        debug: true,
+        version: "dev"
+    })
+};
+```
+
+#### 加密配置建议
+
+```javascript
+// 开发环境加密配置
+const devEncryption = {
+    encryptBody: false, // 开发阶段关闭加密便于调试
+    encryptResponse: false
+};
+```
+
+### 生产环境配置
+
+生产环境配置需要更加严格的安全控制：
+
+#### 安全生产配置
+
+```javascript
+// 生产环境安全配置
+const prodConfig = {
+    base64Key: process.env.ENCRYPTION_KEY, // 从环境变量读取
+    prefix: (url) => {
+        // 动态前缀根据域名判断
+        if (window.location.hostname.includes('staging')) {
+            return 'https://staging-api.example.com';
+        }
+        return 'https://api.example.com';
+    },
+    onHttpError: (res) => {
+        // 生产环境错误上报
+        this.reportError(res);
+    },
+    httpParams: () => ({
+        timestamp: Date.now(),
+        nonce: Math.random().toString(36).substr(2, 9)
+    })
+};
+```
+
+#### 加密配置要求
+
+```javascript
+// 生产环境强制加密
+const prodEncryption = {
+    encryptBody: true, // 必须启用请求加密
+    encryptResponse: true, // 必须启用响应解密
+    encryptionLevel: "high" // 高强度加密
+};
+```
+
+### 不同使用场景的配置示例
+
+#### 移动端应用配置
+
+```javascript
+// 移动端配置优化
+const mobileConfig = {
+    // 移动端网络优化
+    timeout: 10000, // 10秒超时
+    retry: 2, // 重试2次
+    cache: false, // 禁用缓存
+    
+    // 移动端安全配置
+    base64Key: process.env.MOBILE_ENCRYPTION_KEY,
+    encryptBody: true,
+    
+    // 移动端特殊处理
+    httpParams: () => ({
+        platform: "mobile",
+        appVersion: "1.0.0",
+        deviceInfo: navigator.userAgent
+    })
+};
+```
+
+#### 微服务架构配置
+
+```javascript
+// 微服务架构配置
+const microserviceConfig = {
+    // 服务发现集成
+    prefix: (url) => {
+        const serviceMap = {
+            "user": "https://user-service/api",
+            "order": "https://order-service/api",
+            "product": "https://product-service/api"
+        };
+        
+        const service = Object.keys(serviceMap).find(key => url.includes(key));
+        return service ? serviceMap[service] : serviceMap.default;
+    },
+    
+    // 微服务特定配置
+    onHttpError: (res) => {
+        if (res.code === 503) {
+            // 服务不可用，切换到备用服务
+            this.switchToBackupService();
+        }
+    },
+    
+    httpParams: () => ({
+        traceId: this.generateTraceId(),
+        correlationId: this.generateCorrelationId()
+    })
+};
+```
+
+### 配置验证和调试方法
+
+#### 配置验证流程
+
+```mermaid
+flowchart TD
+A[配置输入] --> B[基本格式验证]
+B --> C{格式正确?}
+C --> |否| D[返回格式错误]
+C --> |是| E[参数完整性检查]
+E --> F{参数完整?}
+F --> |否| G[返回缺失参数]
+F --> |是| H[功能可用性测试]
+H --> I{功能正常?}
+I --> |否| J[返回功能错误]
+I --> |是| K[配置验证通过]
+subgraph "验证步骤"
+L[检查必填参数]
+M[验证参数类型]
+N[测试加密功能]
+O[测试网络连接]
+end
+```
+
+#### 调试配置选项
+
+```javascript
+// 调试模式配置
+const debugConfig = {
+    // 开启详细日志
+    debug: true,
+    logLevel: "verbose",
+    
+    // 开发辅助功能
+    enableMock: true,
+    mockDelay: 1000,
+    
+    // 错误监控
+    onError: (error) => {
+        console.error("配置错误详情:", {
+            error: error.message,
+            config: error.config,
+            stack: error.stack
+        });
+    }
+};
+```
+
+**章节来源**
+- [TsGlobalConfig.js:19-33](file://src/utils/TsGlobalConfig.js#L19-L33)
+- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
+- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
+
+## 依赖关系分析
+
+### 外部依赖管理
+
+项目依赖关系清晰明确，主要依赖包括：
+
+```mermaid
+graph LR
+subgraph "核心依赖"
+UMI[umi-request@1.4.0]
+B64[base64-js@1.5.1]
+end
+subgraph "内部模块"
+HTTP[TsHttpUtil]
+CRYPTO[TsCrypto]
+GLOBAL[TsGlobalConfig]
+SM4[TsSM4]
+STORAGE[TsStorage]
+COMMON[TsCommon]
+end
+HTTP --> UMI
+CRYPTO --> B64
+CRYPTO --> SM4
+HTTP --> CRYPTO
+HTTP --> STORAGE
+HTTP --> GLOBAL
+HTTP --> COMMON
+GLOBAL --> COMMON
+STORAGE --> COMMON
+```
+
+**图表来源**
+- [package.json:19-22](file://package.json#L19-L22)
+- [index.js:1-6](file://index.js#L1-L6)
+
+### 内部模块依赖
+
+内部模块之间的依赖关系遵循单一职责原则：
+
+| 模块 | 依赖模块 | 用途 |
+|------|----------|------|
+| TsHttpUtil | TsCrypto, TsStorage, TsGlobalConfig, TsCommon | HTTP 请求处理 |
+| TsCrypto | TsSM4, TsGlobalConfig | 数据加密解密 |
+| TsStorage | TsCommon | 本地存储管理 |
+| TsGlobalConfig | TsCommon | 全局配置管理 |
+
+**章节来源**
+- [package.json:19-22](file://package.json#L19-L22)
+- [index.js:1-16](file://index.js#L1-L16)
+
+## 性能考虑
+
+### 加密性能优化
+
+加密操作是影响性能的关键因素，需要考虑以下优化策略：
+
+#### 加密性能指标
+
+| 操作类型 | 处理时间 | 内存占用 | 推荐场景 |
+|----------|----------|----------|----------|
+| 小数据加密 (<1KB) | <1ms | <1KB | API 请求 |
+| 中等数据加密 (1-10KB) | 1-5ms | 1-10KB | 文件上传 |
+| 大数据加密 (>10KB) | 5-50ms | 10-50KB | 批量数据 |
+
+#### 性能优化建议
+
+1. **延迟加密**：仅对敏感数据进行加密
+2. **批量处理**：合并多个小请求为批量请求
+3. **缓存策略**：对不敏感数据使用缓存
+4. **异步处理**：在后台线程中执行加密操作
+
+### 网络请求优化
+
+#### 请求优化策略
+
+```javascript
+// 性能优化配置示例
+const performanceConfig = {
+    // 连接池管理
+    maxConnections: 10,
+    connectionTimeout: 5000,
+    
+    // 缓存策略
+    cacheStrategy: "smart", // 智能缓存
+    cacheTTL: 300000, // 5分钟缓存
+    
+    // 压缩配置
+    enableCompression: true,
+    compressionThreshold: 1024,
+    
+    // 超时配置
+    requestTimeout: 10000,
+    retryTimeout: 2000,
+    
+    // 重试策略
+    maxRetries: 3,
+    retryBackoff: "exponential"
+};
+```
+
+## 故障排除指南
+
+### 常见配置问题
+
+#### 加密相关问题
+
+| 问题类型 | 症状 | 解决方案 |
+|----------|------|----------|
+| 密钥不匹配 | 加密失败，抛出异常 | 检查 base64Key 配置 |
+| IV 配置错误 | CBC 模式加密异常 | 确认 IV 参数正确设置 |
+| 模式不兼容 | 加密/解密失败 | 确保加密和解密使用相同模式 |
+
+#### HTTP 请求问题
+
+| 问题类型 | 症状 | 解决方案 |
+|----------|------|----------|
+| 跨域问题 | CORS 错误 | 配置正确的 CORS 头 |
+| 超时问题 | 请求超时 | 调整 timeout 参数 |
+| 认证失败 | 401 错误 | 检查用户令牌配置 |
+
+#### 存储相关问题
+
+| 问题类型 | 症状 | 解决方案 |
+|----------|------|----------|
+| 存储失败 | 无法保存数据 | 检查浏览器存储权限 |
+| 数据丢失 | 重启后数据消失 | 确认使用 localStorage |
+| 格式错误 | JSON 解析失败 | 检查数据序列化 |
+
+### 调试工具和方法
+
+#### 配置调试接口
+
+```javascript
+// 配置状态检查
+const checkConfigStatus = () => {
+    return {
+        globalConfig: TsGlobalConfig.getConfig(),
+        encryptionEnabled: TsStorage.getEncryptBody(),
+        userToken: TsStorage.getUserToken(),
+        storageAvailable: typeof localStorage !== 'undefined'
+    };
+};
+
+// 加密功能测试
+const testEncryption = (testData) => {
+    try {
+        const encrypted = TsCrypto.encrypt(testData);
+        const decrypted = TsCrypto.decrypt(encrypted);
+        return {
+            success: testData === decrypted,
+            original: testData,
+            encrypted: encrypted,
+            decrypted: decrypted
+        };
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+};
+```
+
+#### 日志记录配置
+
+```javascript
+// 详细日志配置
+const loggingConfig = {
+    enableDebugLogs: true,
+    logLevels: ["error", "warn", "info", "debug"],
+    logToFile: false,
+    logToConsole: true,
+    maxLogSize: 10485760, // 10MB
+    retentionDays: 7
+};
+```
+
+**章节来源**
+- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
+- [TsStorage.js:47-55](file://src/utils/TsStorage.js#L47-L55)
+
+## 结论
+
+npm-tool 工具包提供了完整的配置管理解决方案，具有以下特点：
+
+### 主要优势
+
+1. **灵活的配置系统**：支持多层级配置和动态覆盖
+2. **强大的加密能力**：基于 SM4 算法的安全数据传输
+3. **完善的错误处理**：全面的异常捕获和错误恢复机制
+4. **环境适配性强**：支持开发、测试、生产多环境部署
+
+### 最佳实践建议
+
+1. **生产环境必须启用加密**：确保数据传输安全
+2. **合理配置超时参数**：平衡用户体验和系统性能
+3. **实施适当的缓存策略**：提升应用响应速度
+4. **建立完善的监控体系**：及时发现和解决问题
+
+### 安全考虑
+
+1. **密钥安全管理**：使用环境变量存储敏感配置
+2. **传输安全**：确保所有数据通过 HTTPS 传输
+3. **访问控制**：实施严格的权限验证机制
+4. **审计日志**：记录重要的配置变更和访问行为
+
+通过遵循本指南提供的配置最佳实践，可以确保 npm-tool 工具包在各种使用场景下都能稳定、安全地运行。