docs: 完善sqlsugar文档

2025-09-18 17:48:01 +08:00 · 2025-05-08 14:54:03 +08:00
parent 6ae0c4b9b2
commit 6ef7c91896
4 changed files with 156 additions and 121 deletions
--- a/OpenAuth.App/WmsInbound/WmsInboundOrderDtblApp.cs
+++ b/OpenAuth.App/WmsInbound/WmsInboundOrderDtblApp.cs
@@ -6,9 +6,7 @@ using OpenAuth.App.Interface;
 using OpenAuth.App.Request;
 using OpenAuth.App.Response;
 using OpenAuth.Repository.Domain;
-
 using SqlSugar;
-
 namespace OpenAuth.App
 {
    public class WmsInboundOrderDtblApp : SqlSugarBaseApp<WmsInboundOrderDtbl>
@@ -18,13 +16,11 @@ namespace OpenAuth.App
        /// </summary>
        public async Task<TableData> Load(QueryWmsInboundOrderDtblListReq request)
        {
-
            var loginContext = _auth.GetCurrentUser();
            if (loginContext == null)
            {
                throw new CommonException("登录已过期", Define.INVALID_TOKEN);
            }
-
            var properties = loginContext.GetTableColumns("WmsInboundOrderDtbl");
            if (properties == null || properties.Count == 0)
            {
@@ -36,12 +32,10 @@ namespace OpenAuth.App
            {
                objs = objs.Where(u => u.OrderId == request.InboundOrderId);
            }
-
            if (!string.IsNullOrEmpty(request.key))
            {
                objs = objs.Where(u => u.GoodsId.Contains(request.key));
            }
-
            var propertyStr = string.Join(',', properties.Select(u => u.ColumnName));
            result.columnFields = properties;
            result.data = objs.OrderBy(u => u.Id)
@@ -50,17 +44,9 @@ namespace OpenAuth.App
            result.count = await objs.CountAsync();
            return result;
        }
-
-        public void Add(AddOrUpdateWmsInboundOrderDtblReq req)
+        public void Add(AddOrUpdateWmsInboundOrderDtblReq request)
        {
-            SugarClient.Ado.BeginTran();
-            AddNoSave(req);
-            SugarClient.Ado.CommitTran();
-        }
-
-        public void AddNoSave(AddOrUpdateWmsInboundOrderDtblReq req)
-        {
-            var obj = req.MapTo<WmsInboundOrderDtbl>();
+            var obj = request.MapTo<WmsInboundOrderDtbl>();
            //todo:补充或调整自己需要的字段
            obj.CreateTime = DateTime.Now;
            var user = _auth.GetCurrentUser().User;
@@ -69,36 +55,33 @@ namespace OpenAuth.App
            obj.CreateUserName = user.Name;
            SugarClient.Insertable(obj).ExecuteCommand();
        }
-
-        public void Update(AddOrUpdateWmsInboundOrderDtblReq obj)
+        public void Update(AddOrUpdateWmsInboundOrderDtblReq request)
        {
            var user = _auth.GetCurrentUser().User;
            Repository.Update(u => new WmsInboundOrderDtbl
            {
-                Price = obj.Price,
-                PriceNoTax = obj.PriceNoTax,
-                InStockStatus = obj.InStockStatus,
-                AsnStatus = obj.AsnStatus,
-                GoodsId = obj.GoodsId,
-                GoodsBatch = obj.GoodsBatch,
-                QualityFlg = obj.QualityFlg,
-                OrderNum = obj.OrderNum,
-                InNum = obj.InNum,
-                LeaveNum = obj.LeaveNum,
-                HoldNum = obj.HoldNum,
-                ProdDate = obj.ProdDate,
-                ExpireDate = obj.ExpireDate,
-                TaxRate = obj.TaxRate,
-                OwnerId = obj.OwnerId,
-                Remark = obj.Remark,
+                Price = request.Price,
+                PriceNoTax = request.PriceNoTax,
+                InStockStatus = request.InStockStatus,
+                AsnStatus = request.AsnStatus,
+                GoodsId = request.GoodsId,
+                GoodsBatch = request.GoodsBatch,
+                QualityFlg = request.QualityFlg,
+                OrderNum = request.OrderNum,
+                InNum = request.InNum,
+                LeaveNum = request.LeaveNum,
+                HoldNum = request.HoldNum,
+                ProdDate = request.ProdDate,
+                ExpireDate = request.ExpireDate,
+                TaxRate = request.TaxRate,
+                OwnerId = request.OwnerId,
+                Remark = request.Remark,
                UpdateTime = DateTime.Now,
                UpdateUserId = user.Id,
                UpdateUserName = user.Name
                //todo:补充或调整自己需要的字段
-            }, u => u.Id == obj.Id);
-
+            }, u => u.Id == request.Id);
        }
-
        public WmsInboundOrderDtblApp(ISqlSugarClient client, IAuth auth) : base(client, auth)
        {
        }
--- a/OpenAuth.App/WmsInbound/WmsInboundOrderTblApp.cs
+++ b/OpenAuth.App/WmsInbound/WmsInboundOrderTblApp.cs
@@ -7,14 +7,11 @@ using OpenAuth.App.Request;
 using OpenAuth.App.Response;
 using OpenAuth.Repository.Domain;
 using SqlSugar;
-
-
 namespace OpenAuth.App
 {
    public class WmsInboundOrderTblApp : SqlSugarBaseApp<WmsInboundOrderTbl>
    {
        private WmsInboundOrderDtblApp _wmsInboundOrderDtblApp;
-
        /// <summary>
        /// 加载列表
        /// </summary>
@@ -25,29 +22,22 @@ namespace OpenAuth.App
            {
                throw new CommonException("登录已过期", Define.INVALID_TOKEN);
            }
-
-
            var columns = loginContext.GetTableColumns("WmsInboundOrderTbl");
            if (columns == null || columns.Count == 0)
            {
                throw new Exception("请在代码生成界面配置WmsInboundOrderTbl表的字段属性");
            }
-
            var result = new TableData();
-
            result.columnFields = columns;
-
            var objs = GetDataPrivilege("u");
            if (!string.IsNullOrEmpty(request.key))
            {
                objs = objs.Where(u => u.Id.Contains(request.key));
            }
-
            if (!string.IsNullOrEmpty(request.sqlWhere))
            {
                objs = objs.Where(request.sqlWhere);
            }
-
            var propertyStr = string.Join(',', columns.Select(u => u.ColumnName));
            result.data = objs.OrderBy(u => u.Id)
                .Skip((request.page - 1) * request.limit)
@@ -55,88 +45,81 @@ namespace OpenAuth.App
            result.count = await objs.CountAsync();
            return result;
        }
-
-        public void Add(AddOrUpdateWmsInboundOrderTblReq req)
+        public void Add(AddOrUpdateWmsInboundOrderTblReq request)
        {
-            var obj = req.MapTo<WmsInboundOrderTbl>();
+            var obj = request.MapTo<WmsInboundOrderTbl>();
            //todo:补充或调整自己需要的字段
            obj.CreateTime = DateTime.Now;
            var user = _auth.GetCurrentUser().User;
            obj.CreateUserId = user.Id;
            obj.CreateUserName = user.Name;
-            SugarClient.Ado.BeginTran();
-            SugarClient.Insertable(obj).ExecuteCommand();
-            if (req.WmsInboundOrderDtblReqs != null && req.WmsInboundOrderDtblReqs.Any())
+            if(obj.KeyIsNull())  //如果主键为空，则生成默认值
            {
-                foreach (var detail in req.WmsInboundOrderDtblReqs)
-                {
-                    detail.OrderId = obj.Id;
-                    _wmsInboundOrderDtblApp.AddNoSave(detail);
-                }
+                obj.GenerateDefaultKeyVal();
            }

-            SugarClient.Ado.CommitTran();
-        }
-
-        public void Update(AddOrUpdateWmsInboundOrderTblReq obj)
-        {
-            var user = _auth.GetCurrentUser().User;
-
            SugarClient.Ado.BeginTran();
-
-
-            if (obj.WmsInboundOrderDtblReqs != null && obj.WmsInboundOrderDtblReqs.Any())
+            SugarClient.Insertable(obj).ExecuteCommand();
+            if (request.WmsInboundOrderDtblReqs != null && request.WmsInboundOrderDtblReqs.Any())
            {
-                //id为空的添加
-                foreach (var detail in obj.WmsInboundOrderDtblReqs.Where(u => string.IsNullOrEmpty(u.Id)))
+                foreach (var detail in request.WmsInboundOrderDtblReqs)
                {
                    detail.OrderId = obj.Id;
-                    _wmsInboundOrderDtblApp.AddNoSave(detail);
+                    _wmsInboundOrderDtblApp.Add(detail);
+                }
+            }
+            SugarClient.Ado.CommitTran();
+        }
+        public void Update(AddOrUpdateWmsInboundOrderTblReq request)
+        {
+            var user = _auth.GetCurrentUser().User;
+            SugarClient.Ado.BeginTran();
+            if (request.WmsInboundOrderDtblReqs != null && request.WmsInboundOrderDtblReqs.Any())
+            {
+                //id为空的添加
+                foreach (var detail in request.WmsInboundOrderDtblReqs.Where(u => string.IsNullOrEmpty(u.Id)))
+                {
+                    detail.OrderId = request.Id;
+                    _wmsInboundOrderDtblApp.Add(detail);
                }
-
                //id比数据库少的，删除
-                var containids = obj.WmsInboundOrderDtblReqs.Select(u => u.Id)
+                var containids = request.WmsInboundOrderDtblReqs.Select(u => u.Id)
                    .Where(u => !string.IsNullOrEmpty(u)).ToList();
                if (containids.Any())
                {
-                    SugarClient.Deleteable<WmsInboundOrderDtbl>(u => (!containids.Contains(u.Id)) && u.OrderId == obj.Id).ExecuteCommand();
+                    SugarClient.Deleteable<WmsInboundOrderDtbl>(u => (!containids.Contains(u.Id)) && u.OrderId == request.Id).ExecuteCommand();
                }
-
                //更新id相同的
-                foreach (var detail in obj.WmsInboundOrderDtblReqs.Where(u => !string.IsNullOrEmpty(u.Id)))
+                foreach (var detail in request.WmsInboundOrderDtblReqs.Where(u => !string.IsNullOrEmpty(u.Id)))
                {
                    _wmsInboundOrderDtblApp.Update(detail);
                }
            }
-
            Repository.Update(u => new WmsInboundOrderTbl
            {
-                ExternalNo = obj.ExternalNo,
-                ExternalType = obj.ExternalType,
-                Status = obj.Status,
-                OrderType = obj.OrderType,
-                GoodsType = obj.GoodsType,
-                PurchaseNo = obj.PurchaseNo,
-                StockId = obj.StockId,
-                OwnerId = obj.OwnerId,
-                ShipperId = obj.ShipperId,
-                SupplierId = obj.SupplierId,
-                ScheduledInboundTime = obj.ScheduledInboundTime,
-                Remark = obj.Remark,
-                Enable = obj.Enable,
-                TransferType = obj.TransferType,
-                InBondedArea = obj.InBondedArea,
-                ReturnBoxNum = obj.ReturnBoxNum,
+                ExternalNo = request.ExternalNo,
+                ExternalType = request.ExternalType,
+                Status = request.Status,
+                OrderType = request.OrderType,
+                GoodsType = request.GoodsType,
+                PurchaseNo = request.PurchaseNo,
+                StockId = request.StockId,
+                OwnerId = request.OwnerId,
+                ShipperId = request.ShipperId,
+                SupplierId = request.SupplierId,
+                ScheduledInboundTime = request.ScheduledInboundTime,
+                Remark = request.Remark,
+                Enable = request.Enable,
+                TransferType = request.TransferType,
+                InBondedArea = request.InBondedArea,
+                ReturnBoxNum = request.ReturnBoxNum,
                UpdateTime = DateTime.Now,
                UpdateUserId = user.Id,
                UpdateUserName = user.Name
                //todo:补充或调整自己需要的字段
-            }, u => u.Id == obj.Id);
-
+            }, u => u.Id == request.Id);
            SugarClient.Ado.CommitTran();
-
        }
-
        public WmsInboundOrderTblApp(ISqlSugarClient client, IAuth auth,
            WmsInboundOrderDtblApp wmsInboundOrderDtblApp) : base(client, auth)
        {
--- a/newdocs/docs/notes/core/sqlsugar.md
+++ b/newdocs/docs/notes/core/sqlsugar.md
@@ -74,3 +74,45 @@ public class ResourceApp:SqlSugarBaseApp<Resource>
    }
 ```

+## 事务
+
+SqlSugar提供了强大的事务功能，在OpenAuth.Net中，只需要在业务开始时，调用`SugarClient.Ado.BeginTran()`开启事务，在业务结束时，调用`SugarClient.Ado.CommitTran()`提交事务，即可使用事务。
+
+比如一个复杂的主从表业务，无论中间过程使用的是SugarClient还是Repository，都可以用这种方式来实现事务：
+```csharp
+SugarClient.Ado.BeginTran();
+
+// 更新从表中的字段
+if (obj.SubTableReqs != null && obj.SubTableReqs.Any())
+{
+    //id为空时添加
+    foreach (var detail in obj.SubTableReqs.Where(u => string.IsNullOrEmpty(u.Id)))
+    {
+        _subTableApp.Add(detail);
+    }
+
+    //id比数据库少的，删除
+    var containids = obj.SubTableReqs.Select(u => u.Id)
+        .Where(u => !string.IsNullOrEmpty(u)).ToList();
+    if (containids.Any())
+    {
+        SugarClient.Deleteable<SubTable>(u => !containids.Contains(u.Id) && u.MainTableId == obj.Id).ExecuteCommand();
+    }
+
+    //更新id相同的
+    foreach (var detail in obj.SubTableReqs.Where(u => !string.IsNullOrEmpty(u.Id)))
+    {
+        _subTableApp.Update(detail);
+    }
+}
+
+// 更新主表中的字段
+Repository.Update(u => new MainTable
+{
+    NeedUpdateField = obj.NeedUpdateField,
+    //todo:补充或调整自己需要的字段
+}, u => u.Id == obj.Id);
+
+SugarClient.Ado.CommitTran();
+
+```
--- a/newdocs/docs/notes/pro/printerplan.md
+++ b/newdocs/docs/notes/pro/printerplan.md
@@ -4,59 +4,86 @@ createTime: 2025/04/23 23:43:26
 permalink: /pro/printerplan/
 ---

-OpenAuth.Pro提供灵活无代码（可能需要写SQL）的打印解决方案，无需开发人员参与即可配置自己需要的打印。
+OpenAuth.Pro提供强大且灵活的低代码打印方案，企业用户仅需进行简单配置（可能需要编写SQL查询）即可实现个性化打印需求，无需开发人员参与即可快速部署各类打印模板。

-打印模板设计界面如下：
+## 系统界面展示
+
+### 打印模板设计界面
+
+专业的设计工作台，支持拖拽式操作与精确配置：

 ![sysprinterplan](http://img.openauth.net.cn/sysprinterplan.png)

-挂载到业务系统中效果：
+### 业务系统集成效果
+
+无缝集成到各类业务功能模块中：

 ![20231002114914](http://img.openauth.net.cn/20231002114914.png)


-## 使用指南
+## 详细使用指南

-### 设计打印模版
+### 创建与设计打印模版

-在打印中心-打印模版功能新增打印模版。设计界面说明如下：
+在【打印中心】-【打印模版】功能中新增打印模版。设计界面布局如下：

 ![20231004165652](http://img.openauth.net.cn/20231004165652.png)

-左边为设计工具栏，中间为画布，右边为属性框。可以根据自己需要调整打印界面。
+界面分为三大区域：
+- 左侧：设计工具栏，提供各类控件与格式设置工具
+- 中间：设计画布，实时预览打印效果
+- 右侧：属性配置区，精确调整各元素参数与样式

-### 设置数据源
+用户可根据实际需求，通过拖拽与配置快速构建专业打印模板。

-打印模版的核心是设计数据源。用户通过设计数据源，实现无开发打印。如下：
+### 配置数据源
+
+数据源是打印模版的核心，通过合理设计数据源，实现真正的低代码打印解决方案：

 ![20231004165939](http://img.openauth.net.cn/20231004165939.png)

-1. 数据源：用于查询打印打印数据。 
+关键配置项说明：

-2. Id:由数据源中的SQL自动生成的参数文本框。
+1. **数据源**：用于查询打印数据的SQL语句，支持复杂查询与条件筛选
   
-3. 分组字段：如果配置了`分组字段`，则默认对应列表式打印模版。否则，可以看做卡片式。
+2. **Id参数**：系统根据数据源SQL自动生成的参数文本框，用于动态传递查询条件
   
-* 【卡片式】用于打印一页只有一条数据的情况。比如快递的标签、用户名片等。
+3. **分组字段**：决定打印模版的类型与数据结构处理方式
+   - 配置分组字段：生成列表式打印模版（一对多数据结构）
+   - 不配置分组字段：生成卡片式打印模版（单条数据记录）
+
+### 打印模式类型说明
+
+系统支持两种主要打印模式，适应不同业务场景：
+
+* **卡片式打印**：适用于单条记录的打印场景，如快递标签、会员卡、用户名片等
  ![20231004164125](http://img.openauth.net.cn/20231004164125.png)
-* 【列表式】用于打印一页有多条数据的情况，通常是主从结构的表，同时打印主表及从表详情。如客户的发货清单。
-![20231004164203](http://img.openauth.net.cn/20231004164203.png)

-::: warning 注意
+* **列表式打印**：适用于主从结构数据的打印场景，一页包含多条关联数据，如销售订单、发货清单等
+  ![20231004164203](http://img.openauth.net.cn/20231004164203.png)

-两种模版类型没有严格的区分。在后端返回相同的数据情况下，如果配置了`分组字段`，后端返回的数据会被转化成主从结构。上图即为官网【入库随货同行单（列表式）【带参数】】按OrderId进行分组后的数据。
+::: warning 特别说明
+
+两种模版类型在底层处理上存在灵活性。当配置了`分组字段`时，后端将自动将数据按该字段进行分组，转化为主从结构。例如，上图展示的【入库随货同行单（列表式）【带参数】】正是通过按OrderId分组后生成的数据结构。

 :::

-### 功能模块挂载打印方案
+### 打印方案与功能模块关联

-制作完打印方案后，在【模块管理】功能里面，把刚刚打印方案与功能关联。
+完成打印方案设计后，需在【模块管理】功能中将打印方案与业务功能关联，实现功能集成：

 ![20231004173811](http://img.openauth.net.cn/20231004173811.png)


-### 使用打印
+### 实际打印操作

-最后就可以在功能里面使用打印了。
+完成上述配置后，用户可在相应业务功能中直接调用打印方案，实现一键打印：

 ![20231002114914](http://img.openauth.net.cn/20231002114914.png)
+
+## 最佳实践建议
+
+1. 设计数据源时，建议先测试SQL查询结果，确保数据结构符合预期
+2. 打印模板设计时注意适配不同纸张规格，预留适当边距
+3. 对于复杂报表，可考虑使用分组字段实现数据的合理组织
+4. 利用系统提供的预览功能，及时调整布局与样式