diff --git a/agileboot-admin/src/main/java/com/agileboot/admin/controller/ab98/UserBalanceController.java b/agileboot-admin/src/main/java/com/agileboot/admin/controller/ab98/UserBalanceController.java
index b59b769..c51e216 100644
--- a/agileboot-admin/src/main/java/com/agileboot/admin/controller/ab98/UserBalanceController.java
+++ b/agileboot-admin/src/main/java/com/agileboot/admin/controller/ab98/UserBalanceController.java
@@ -51,14 +51,14 @@ public class UserBalanceController extends BaseController {
     }
 
     @Operation(summary = "根据企业微信ID和汇邦云用户ID查询用户余额")
-    @GetMapping("/by-corpid-ab98")
+    @GetMapping("/byCorpidAb98")
     public ResponseDTO<UserBalanceDTO> getByCorpidAndAb98UserId(String corpid, Long ab98UserId) {
         UserBalanceDTO userBalanceDTO = userBalanceApplicationService.getByCorpidAndAb98UserId(corpid, ab98UserId);
         return ResponseDTO.ok(userBalanceDTO);
     }
 
     @Operation(summary = "根据openid查询用户余额")
-    @GetMapping("/by-openid")
+    @GetMapping("/byOpenid")
     public ResponseDTO<UserBalanceDTO> getByOpenid(String openid) {
         UserBalanceDTO userBalanceDTO = userBalanceApplicationService.getByOpenid(openid);
         return ResponseDTO.ok(userBalanceDTO);
@@ -99,7 +99,7 @@ public class UserBalanceController extends BaseController {
 
     @Operation(summary = "增加用户余额")
     @AccessLog(title = "用户余额管理", businessType = BusinessTypeEnum.MODIFY)
-    @PostMapping("/add-balance")
+    @PostMapping("/addBalance")
     public ResponseDTO<String> addBalance(@Validated @RequestBody AddBalanceCommand command) {
         boolean success = userBalanceApplicationService.addBalance(command);
         return success ? ResponseDTO.ok("增加用户余额成功") : ResponseDTO.fail("增加用户余额失败");
@@ -107,7 +107,7 @@ public class UserBalanceController extends BaseController {
 
     @Operation(summary = "减少用户余额")
     @AccessLog(title = "用户余额管理", businessType = BusinessTypeEnum.MODIFY)
-    @PostMapping("/subtract-balance")
+    @PostMapping("/subtractBalance")
     public ResponseDTO<String> subtractBalance(@Validated @RequestBody SubtractBalanceCommand command) {
         boolean success = userBalanceApplicationService.subtractBalance(command);
         return success ? ResponseDTO.ok("减少用户余额成功") : ResponseDTO.fail("减少用户余额失败");
@@ -115,7 +115,7 @@ public class UserBalanceController extends BaseController {
 
     @Operation(summary = "插入或更新用户余额")
     @AccessLog(title = "用户余额管理", businessType = BusinessTypeEnum.MODIFY)
-    @PostMapping("/insert-or-update")
+    @PostMapping("/insertOrUpdate")
     public ResponseDTO<UserBalanceDTO> insertOrUpdate(@Validated @RequestBody AddUserBalanceCommand command) {
         UserBalanceDTO userBalanceDTO = userBalanceApplicationService.insertOrUpdate(command);
         return ResponseDTO.ok(userBalanceDTO);
diff --git a/agileboot-domain/src/main/java/com/agileboot/domain/ab98/user_balance/db/UserBalanceServiceImpl.java b/agileboot-domain/src/main/java/com/agileboot/domain/ab98/user_balance/db/UserBalanceServiceImpl.java
index 8bb5ebc..01d3b4a 100644
--- a/agileboot-domain/src/main/java/com/agileboot/domain/ab98/user_balance/db/UserBalanceServiceImpl.java
+++ b/agileboot-domain/src/main/java/com/agileboot/domain/ab98/user_balance/db/UserBalanceServiceImpl.java
@@ -39,9 +39,19 @@ public class UserBalanceServiceImpl extends ServiceImpl<UserBalanceMapper, UserB
         if (existing != null) {
             // 更新
             entity.setUserBalanceId(existing.getUserBalanceId());
+            if (entity.getBalanceLimit() != null) {
+                if (entity.getUseBalance() != null) {
+                    entity.setBalance(entity.getBalanceLimit() - entity.getUseBalance());
+                } else {
+                    entity.setBalance(entity.getBalanceLimit() - existing.getUseBalance());
+                }
+            }
             return updateById(entity);
         } else {
             // 插入
+            if (entity.getBalanceLimit() != null) {
+                entity.setBalance(entity.getBalanceLimit());
+            }
             return save(entity);
         }
     }
diff --git a/doc/UserBalanceController接口文档.md b/doc/UserBalanceController接口文档.md
new file mode 100644
index 0000000..69db47f
--- /dev/null
+++ b/doc/UserBalanceController接口文档.md
@@ -0,0 +1,522 @@
+# UserBalanceController 接口文档
+
+## 概述
+
+`UserBalanceController` 提供用户余额管理的RESTful接口，包括用户余额的查询、新增、更新、删除以及余额的增减操作。
+
+**基础路径**: `/ab98/balance`
+
+---
+
+## 接口列表
+
+### 1. 用户余额列表查询
+
+**接口地址**: `GET /ab98/balance`
+
+**接口描述**: 分页查询用户余额列表
+
+**请求参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| corpid | String | 否 | 企业微信ID | ww1234567890 |
+| openid | String | 否 | 微信openid | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
+| ab98UserId | Long | 否 | 汇邦云用户ID | 10001 |
+| qyUserId | Long | 否 | 企业用户ID | 20001 |
+| pageNum | Integer | 否 | 页码（默认1） | 1 |
+| pageSize | Integer | 否 | 每页条数（默认10） | 10 |
+
+**返回结果**: `ResponseDTO<PageDTO<UserBalanceDTO>>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "records": [
+      {
+        "userBalanceId": 1,
+        "corpid": "ww1234567890",
+        "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+        "ab98UserId": 10001,
+        "qyUserId": 20001,
+        "balance": 100000,
+        "useBalance": 95000,
+        "balanceLimit": 500000,
+        "creatorId": 1,
+        "updaterId": 1
+      }
+    ],
+    "total": 100,
+    "pageNum": 1,
+    "pageSize": 10,
+    "pages": 10
+  }
+}
+```
+
+---
+
+### 2. 用户余额详情
+
+**接口地址**: `GET /ab98/balance/{id}`
+
+**接口描述**: 根据主键ID查询用户余额详情
+
+**路径参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| id | Long | 是 | 主键ID | 1 |
+
+**返回结果**: `ResponseDTO<UserBalanceDTO>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userBalanceId": 1,
+    "corpid": "ww1234567890",
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+    "ab98UserId": 10001,
+    "qyUserId": 20001,
+    "balance": 100000,
+    "useBalance": 95000,
+    "balanceLimit": 500000,
+    "creatorId": 1,
+    "updaterId": 1
+  }
+}
+```
+
+---
+
+### 3. 根据企业微信ID和汇邦云用户ID查询用户余额
+
+**接口地址**: `GET /ab98/balance/byCorpidAb98`
+
+**接口描述**: 根据企业微信ID和汇邦云用户ID查询用户余额
+
+**请求参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| corpid | String | 是 | 企业微信ID | ww1234567890 |
+| ab98UserId | Long | 是 | 汇邦云用户ID | 10001 |
+
+**返回结果**: `ResponseDTO<UserBalanceDTO>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userBalanceId": 1,
+    "corpid": "ww1234567890",
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+    "ab98UserId": 10001,
+    "qyUserId": 20001,
+    "balance": 100000,
+    "useBalance": 95000,
+    "balanceLimit": 500000,
+    "creatorId": 1,
+    "updaterId": 1
+  }
+}
+```
+
+---
+
+### 4. 根据openid查询用户余额
+
+**接口地址**: `GET /ab98/balance/byOpenid`
+
+**接口描述**: 根据微信openid查询用户余额
+
+**请求参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| openid | String | 是 | 微信openid | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
+
+**返回结果**: `ResponseDTO<UserBalanceDTO>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userBalanceId": 1,
+    "corpid": "ww1234567890",
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+    "ab98UserId": 10001,
+    "qyUserId": 20001,
+    "balance": 100000,
+    "useBalance": 95000,
+    "balanceLimit": 500000,
+    "creatorId": 1,
+    "updaterId": 1
+  }
+}
+```
+
+---
+
+### 5. 新增用户余额
+
+**接口地址**: `POST /ab98/balance`
+
+**接口描述**: 新增用户余额记录
+
+**请求体** (JSON对象):
+
+| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
+|--------|------|----------|------|------|
+| corpid | String | 是 | 企业微信ID | 不能为空 |
+| openid | String | 否 | 微信openid | - |
+| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
+| qyUserId | Long | 否 | 企业用户ID | - |
+| balance | Long | 否 | 用户余额(分) | 金额单位为分 |
+| useBalance | Long | 否 | 可用余额(分) | 金额单位为分 |
+| balanceLimit | Long | 否 | 余额限制(分) | 金额单位为分 |
+
+**请求示例**:
+```json
+{
+  "corpid": "ww1234567890",
+  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+  "ab98UserId": 10001,
+  "qyUserId": 20001,
+  "balance": 100000,
+  "useBalance": 95000,
+  "balanceLimit": 500000
+}
+```
+
+**返回结果**: `ResponseDTO<UserBalanceDTO>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userBalanceId": 1,
+    "corpid": "ww1234567890",
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+    "ab98UserId": 10001,
+    "qyUserId": 20001,
+    "balance": 100000,
+    "useBalance": 95000,
+    "balanceLimit": 500000,
+    "creatorId": 1,
+    "updaterId": 1
+  }
+}
+```
+
+**操作日志**: 记录新增操作
+
+---
+
+### 6. 修改用户余额
+
+**接口地址**: `PUT /ab98/balance/{id}`
+
+**接口描述**: 修改用户余额记录
+
+**路径参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| id | Long | 是 | 主键ID | 1 |
+
+**请求体** (JSON对象):
+
+| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
+|--------|------|----------|------|------|
+| corpid | String | 是 | 企业微信ID | 不能为空 |
+| openid | String | 否 | 微信openid | - |
+| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
+| qyUserId | Long | 否 | 企业用户ID | - |
+| balance | Long | 否 | 用户余额(分) | 金额单位为分 |
+| useBalance | Long | 否 | 可用余额(分) | 金额单位为分 |
+| balanceLimit | Long | 否 | 余额限制(分) | 金额单位为分 |
+
+**请求示例**:
+```json
+{
+  "corpid": "ww1234567890",
+  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+  "ab98UserId": 10001,
+  "qyUserId": 20001,
+  "balance": 100000,
+  "useBalance": 95000,
+  "balanceLimit": 500000
+}
+```
+
+**返回结果**: `ResponseDTO<UserBalanceDTO>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userBalanceId": 1,
+    "corpid": "ww1234567890",
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+    "ab98UserId": 10001,
+    "qyUserId": 20001,
+    "balance": 100000,
+    "useBalance": 95000,
+    "balanceLimit": 500000,
+    "creatorId": 1,
+    "updaterId": 1
+  }
+}
+```
+
+**操作日志**: 记录修改操作
+
+---
+
+### 7. 删除用户余额
+
+**接口地址**: `DELETE /ab98/balance/{id}`
+
+**接口描述**: 删除用户余额记录
+
+**路径参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| id | Long | 是 | 主键ID | 1 |
+
+**返回结果**: `ResponseDTO<Void>`
+
+**操作日志**: 记录删除操作
+
+---
+
+### 8. 批量删除用户余额
+
+**接口地址**: `DELETE /ab98/balance/batch/{ids}`
+
+**接口描述**: 批量删除用户余额记录
+
+**路径参数**:
+
+| 参数名 | 类型 | 是否必填 | 描述 | 示例 |
+|--------|------|----------|------|------|
+| ids | List<Long> | 是 | 主键ID列表 | 1,2,3 |
+
+**返回结果**: `ResponseDTO<Void>`
+
+**操作日志**: 记录删除操作
+
+---
+
+### 9. 增加用户余额
+
+**接口地址**: `POST /ab98/balance/addBalance`
+
+**接口描述**: 增加用户余额
+
+**请求体** (JSON对象):
+
+| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
+|--------|------|----------|------|------|
+| corpid | String | 是 | 企业微信ID | 不能为空 |
+| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
+| amount | Long | 是 | 增加金额(分) | 金额单位为分，不能为空 |
+
+**请求示例**:
+```json
+{
+  "corpid": "ww1234567890",
+  "ab98UserId": 10001,
+  "amount": 10000
+}
+```
+
+**返回结果**: `ResponseDTO<String>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "增加用户余额成功",
+  "data": null
+}
+```
+
+**失败响应示例**:
+```json
+{
+  "code": 500,
+  "msg": "增加用户余额失败",
+  "data": null
+}
+```
+
+**操作日志**: 记录修改操作
+
+---
+
+### 10. 减少用户余额
+
+**接口地址**: `POST /ab98/balance/subtractBalance`
+
+**接口描述**: 减少用户余额
+
+**请求体** (JSON对象):
+
+| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
+|--------|------|----------|------|------|
+| corpid | String | 是 | 企业微信ID | 不能为空 |
+| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
+| amount | Long | 是 | 减少金额(分) | 金额单位为分，不能为空 |
+
+**请求示例**:
+```json
+{
+  "corpid": "ww1234567890",
+  "ab98UserId": 10001,
+  "amount": 5000
+}
+```
+
+**返回结果**: `ResponseDTO<String>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "减少用户余额成功",
+  "data": null
+}
+```
+
+**失败响应示例**:
+```json
+{
+  "code": 500,
+  "msg": "减少用户余额失败",
+  "data": null
+}
+```
+
+**操作日志**: 记录修改操作
+
+---
+
+### 11. 插入或更新用户余额
+
+**接口地址**: `POST /ab98/balance/insertOrUpdate`
+
+**接口描述**: 插入或更新用户余额（如果存在则更新，不存在则新增）
+
+**请求体** (JSON对象):
+
+| 参数名 | 类型 | 是否必填 | 描述 | 备注 |
+|--------|------|----------|------|------|
+| corpid | String | 是 | 企业微信ID | 不能为空 |
+| openid | String | 否 | 微信openid | - |
+| ab98UserId | Long | 是 | 汇邦云用户ID | 不能为空 |
+| qyUserId | Long | 否 | 企业用户ID | - |
+| balance | Long | 否 | 用户余额(分) | 金额单位为分 |
+| useBalance | Long | 否 | 可用余额(分) | 金额单位为分 |
+| balanceLimit | Long | 否 | 余额限制(分) | 金额单位为分 |
+
+**请求示例**:
+```json
+{
+  "corpid": "ww1234567890",
+  "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+  "ab98UserId": 10001,
+  "qyUserId": 20001,
+  "balance": 100000,
+  "useBalance": 95000,
+  "balanceLimit": 500000
+}
+```
+
+**返回结果**: `ResponseDTO<UserBalanceDTO>`
+
+**成功响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userBalanceId": 1,
+    "corpid": "ww1234567890",
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
+    "ab98UserId": 10001,
+    "qyUserId": 20001,
+    "balance": 100000,
+    "useBalance": 95000,
+    "balanceLimit": 500000,
+    "creatorId": 1,
+    "updaterId": 1
+  }
+}
+```
+
+**操作日志**: 记录修改操作
+
+---
+
+## 数据结构
+
+### UserBalanceDTO（用户余额DTO）
+
+| 字段名 | 类型 | 描述 | 示例 |
+|--------|------|------|------|
+| userBalanceId | Long | 主键ID | 1 |
+| corpid | String | 企业微信ID | ww1234567890 |
+| openid | String | 微信openid | oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
+| ab98UserId | Long | 汇邦云用户ID | 10001 |
+| qyUserId | Long | 企业用户ID | 20001 |
+| balance | Long | 用户余额(分) | 100000 |
+| useBalance | Long | 可用余额(分) | 95000 |
+| balanceLimit | Long | 余额限制(分) | 500000 |
+| creatorId | Long | 创建者ID | 1 |
+| updaterId | Long | 更新者ID | 1 |
+
+**说明**: 余额相关字段单位均为**分**，例如100元 = 10000分
+
+---
+
+## 注意事项
+
+1. **金额单位**: 所有余额相关字段（balance、useBalance、balanceLimit、amount）单位均为**分**，而非元
+2. **必填参数**: 标有"不能为空"的参数为必填项，请求时必须提供
+3. **操作日志**: 新增、修改、删除操作会自动记录操作日志
+4. **唯一性**: corpid + ab98UserId 组合应保证唯一性
+5. **分页查询**: list接口支持分页，默认pageNum=1，pageSize=10
+6. **批量操作**: 批量删除支持一次性删除多个记录，ID之间用逗号分隔
+
+---
+
+## 错误码说明
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 操作成功 |
+| 400 | 请求参数错误 |
+| 500 | 服务器内部错误 |
+
+---
+
+**生成时间**: 2025-11-24
+**文档版本**: v1.0
+**控制器**: com.agileboot.admin.controller.ab98.UserBalanceController
diff --git a/sql/20251124_user_balance.sql b/sql/20251124_user_balance.sql
index 2baac4d..0b22a61 100644
--- a/sql/20251124_user_balance.sql
+++ b/sql/20251124_user_balance.sql
@@ -11,9 +11,13 @@ CREATE TABLE `user_balance` (
   `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
   `updater_id` bigint NULL DEFAULT 0 COMMENT '更新者ID',
   `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '删除标志（0存在 1删除）',
   PRIMARY KEY (`user_balance_id`),
   KEY `idx_openid` (`openid`),
   KEY `idx_ab98_user_id` (`ab98_user_id`),
   KEY `idx_corpid` (`corpid`),
   UNIQUE KEY `uk_corpid_user` (`corpid`, `ab98_user_id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户余额表';
+
+-- 添加 deleted 字段的 ALTER 语句
+ALTER TABLE `user_balance` ADD COLUMN `deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '删除标志（0存在 1删除）';