diff --git a/README.md b/README.md index 8af4aa8..a729463 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,61 @@ SimpleAdmin.Api/ └── README.md ``` +## 开发规范（强制） + +更完整的分层 / 路由 / DTO 约定见 `开发复刻说明.md`、`design.md`。下列为新增代码与合入共享分支的硬性标准，评审与上传前必须满足。 + +### 1. 写接口必须写注释 + +对外暴露的 Application API（`ApplicationService` 上的 `[HttpGet]` / `[HttpPost]` 等方法）**必须**有 XML / 中文注释，至少说明： + +- 接口用途（做什么） +- 关键入参含义与约束（可写在方法注释或 DTO 属性注释上） +- 关键返回语义或业务失败场景（如抛 `BusinessException` 的条件） + +DTO、领域常量、非显而易见的私有辅助方法也应补注释，避免「只有路由名能猜业务」。 + +```csharp +/// +/// 批量创建仓储代发订单：建单并绑定库存/包裹，产品须为分组 wms。 +/// +/// 仓库、产品编码与店铺订单绑定明细。 +[HttpPost("/order/platform-store-order/batch-create-fulfill-wms")] +public async Task BatchCreateFulfillWmsAsync( + PlatformStoreOrderBatchCreateFulfillInput input) +``` + +### 2. 写 SQL 必须走 ORM（SqlSugar） + +业务读写、列表筛选、联表、聚合、更新**一律通过 SqlSugar / Repository**，禁止在 Application / Domain 服务里手写拼装 SQL 字符串或 `Ado.SqlQuery` 作为常规实现。 + +| 允许 | 禁止（业务代码） | +|------|------------------| +| `Repository` / `ISugarQueryable` / 表达式 `Where` | 服务内大段 `"SELECT ... " +` 拼接 | +| 实体 + 仓储封装复杂查询 | 绕过仓储直接 ADO 执行业务 SQL | +| `sql/*.sql` 仅作建库 / 存量 DDL 迁移 | 用脚本替代日常业务 CRUD | + +存量 DDL、字典初始化等脚本放在 `sql/`（说明见 `sql/README.md`），与运行时 ORM 查询分离；**运行时查询与写入必须 ORM**。 + +### 3. 上传代码前先同步远端 + +`test`、`master` 等共享分支会有其他人提交。**推送前必须先拉取远端，再上传**，避免覆盖或漏掉别人的提交。 + +```bash +git fetch origin +git pull --ff-only origin <当前分支> +git push origin <当前分支> +``` + +- 工作区有未提交改动时，先暂存（stash）或提交，再同步，同步完成后再恢复。 +- 本地已有未推送提交、远端也有新提交时，先 rebase 或 merge 并解决冲突，确认与远端对齐后再 `push`。 +- 禁止在未同步远端的情况下直接 `push` 共享分支。 + +### 4. 相关约定速查 + +- **禁止**新建库级唯一索引（`UNIQUE KEY`）：见 `.cursor/rules/no-unique-indexes.mdc`，业务唯一性在 Application 校验。 +- 路由显式声明；分页统一 `totalCount` + `items`；勿把 Entity 直接返回前端。 + ## Fake 框架特性 ### 自动 API 生成 diff --git a/sql/README.md b/sql/README.md index 9d84b35..b691aa6 100644 --- a/sql/README.md +++ b/sql/README.md @@ -2,6 +2,16 @@ OMS / 共用库的建表脚本已统一到仓库根目录 `db.sql`。 +## 职责边界 + +本目录**只放 DDL / 存量迁移 / 字典种子**等库结构与一次性数据脚本。 + +- **运行时业务查询与写入必须走 SqlSugar ORM（仓储）**，不要在 Application 里用手写 SQL 替代 CRUD。 +- 完整编码标准见仓库根目录 `README.md` →「开发规范」。 + +## 使用说明 + - 新环境：直接执行 `db.sql`（会 DROP 后重建，勿在有生产数据的库上执行） - 已有库：用 diff 对比 `db.sql` 与现库结构后手工 ALTER；本目录 `migrate_all.sql` 为存量增量迁移合集（可重复执行段已做列/表存在判断；揽收 Direction / FeePush 为裸 ALTER，已执行过请跳过） - 数据权限表（`user_org_perm` 等）若 RBAC 与 OMS 分库，请只在 RBAC 库执行 `db.sql` 末尾对应段落 +- 单次增量迁移命名：`migrate_<主题>.sql`，尽量可重复执行（先判断列/表/字典是否已存在） diff --git a/src/Oms.Application/Dtos/Customers/UpdateCustomerInput.cs b/src/Oms.Application/Dtos/Customers/UpdateCustomerInput.cs index df706b0..2bd683d 100644 --- a/src/Oms.Application/Dtos/Customers/UpdateCustomerInput.cs +++ b/src/Oms.Application/Dtos/Customers/UpdateCustomerInput.cs @@ -15,67 +15,64 @@ public class UpdateCustomerInput public int Id { get; set; } /// - /// 客户编号。 + /// 客户编号；不传或空则保留原值（编辑页编号只读，允许局部更新省略）。 /// - [Required] [StringLength(32)] - public string CustomerCode { get; set; } = string.Empty; + public string? CustomerCode { get; set; } /// - /// 客户名称。 + /// 客户名称；不传或空则保留原值。 /// - [Required] [StringLength(128)] - public string CustomerName { get; set; } = string.Empty; + public string? CustomerName { get; set; } /// - /// 手机号。 + /// 手机号；不传或空则保留原值。 /// - [Required] [StringLength(16)] - public string Phone { get; set; } = string.Empty; + public string? Phone { get; set; } /// - /// 邮箱。 + /// 邮箱；不传则保留原值，传空串可清空。 /// [EmailAddress] [StringLength(64)] public string? Email { get; set; } /// - /// 微信头像地址。 + /// 微信头像地址；不传则保留原值，传空串可清空。 /// [StringLength(255)] public string? WechatAvatar { get; set; } /// - /// 微信昵称。 + /// 微信昵称；不传则保留原值，传空串可清空。 /// [StringLength(64)] public string? WechatNickname { get; set; } /// - /// 账户余额。 + /// 账户余额；不传则保留原值。 /// [Range(typeof(decimal), "0", "999999999999")] - public decimal Balance { get; set; } + public decimal? Balance { get; set; } /// - /// 总额度。 + /// 总额度；不传则保留原值。 /// [Range(typeof(decimal), "0", "999999999999")] - public decimal TotalQuota { get; set; } + public decimal? TotalQuota { get; set; } /// - /// 已用额度。 + /// 已用额度；不传则保留原值。 /// [Range(typeof(decimal), "0", "999999999999")] - public decimal UsedQuota { get; set; } + public decimal? UsedQuota { get; set; } /// - /// 状态。 + /// 状态；不传则保留原值。 /// - public CustomerStatus Status { get; set; } = CustomerStatus.Normal; + public CustomerStatus? Status { get; set; } /// /// 备注。 diff --git a/src/Oms.Application/Services/Customers/CustomerService.cs b/src/Oms.Application/Services/Customers/CustomerService.cs index 32cd9e8..02d8ab0 100644 --- a/src/Oms.Application/Services/Customers/CustomerService.cs +++ b/src/Oms.Application/Services/Customers/CustomerService.cs @@ -329,10 +329,17 @@ public class CustomerService : ApplicationService public async Task UpdateAsync(UpdateCustomerInput input) { var entity = await GetCustomerOrThrowAsync(input.Id); - var customerCode = NormalizeRequiredText(input.CustomerCode, "客户编号"); - var customerName = NormalizeRequiredText(input.CustomerName, "客户名称"); - var phone = NormalizeRequiredText(input.Phone, "手机号"); - var email = NormalizeOptionalText(input.Email); + // 未传字段保留原值，避免局部更新（如只改名称）把编号/余额/状态冲成空或默认值 + var customerCode = string.IsNullOrWhiteSpace(input.CustomerCode) + ? entity.CustomerCode + : NormalizeRequiredText(input.CustomerCode, "客户编号"); + var customerName = string.IsNullOrWhiteSpace(input.CustomerName) + ? entity.CustomerName + : NormalizeRequiredText(input.CustomerName, "客户名称"); + var phone = string.IsNullOrWhiteSpace(input.Phone) + ? entity.Phone + : NormalizeRequiredText(input.Phone, "手机号"); + var email = input.Email != null ? NormalizeOptionalText(input.Email) : entity.Email; await EnsureCustomerIdentityUniqueForUpdateAsync(entity.Id, customerCode, phone, email); @@ -340,18 +347,65 @@ public class CustomerService : ApplicationService entity.CustomerName = customerName; entity.Phone = phone; entity.Email = email; - entity.WechatAvatar = NormalizeOptionalText(input.WechatAvatar); - entity.WechatNickname = NormalizeOptionalText(input.WechatNickname); - entity.Balance = input.Balance; - entity.TotalQuota = input.TotalQuota; - entity.UsedQuota = input.UsedQuota; - entity.Status = input.Status; - entity.Remark = NormalizeOptionalText(input.Remark); - entity.Salesman = NormalizeOptionalText(input.Salesman); - entity.CustomerService = NormalizeOptionalText(input.CustomerService); - entity.CustomerGroup = input.CustomerGroup; - entity.MemberLevelId = await ResolveMemberLevelIdForSaveAsync(input.MemberLevelId); - entity.PriceTierKey = MarketingCustomerHelper.NormalizePriceTierKeyOrDefault(input.PriceTierKey); + if (input.WechatAvatar != null) + { + entity.WechatAvatar = NormalizeOptionalText(input.WechatAvatar); + } + + if (input.WechatNickname != null) + { + entity.WechatNickname = NormalizeOptionalText(input.WechatNickname); + } + + if (input.Balance.HasValue) + { + entity.Balance = input.Balance.Value; + } + + if (input.TotalQuota.HasValue) + { + entity.TotalQuota = input.TotalQuota.Value; + } + + if (input.UsedQuota.HasValue) + { + entity.UsedQuota = input.UsedQuota.Value; + } + + if (input.Status.HasValue && input.Status.Value != CustomerStatus.None) + { + entity.Status = input.Status.Value; + } + + if (input.Remark != null) + { + entity.Remark = NormalizeOptionalText(input.Remark); + } + + if (input.Salesman != null) + { + entity.Salesman = NormalizeOptionalText(input.Salesman); + } + + if (input.CustomerService != null) + { + entity.CustomerService = NormalizeOptionalText(input.CustomerService); + } + + if (input.CustomerGroup.HasValue) + { + entity.CustomerGroup = input.CustomerGroup; + } + + if (input.MemberLevelId.HasValue) + { + entity.MemberLevelId = await ResolveMemberLevelIdForSaveAsync(input.MemberLevelId); + } + + if (input.PriceTierKey != null) + { + entity.PriceTierKey = MarketingCustomerHelper.NormalizePriceTierKeyOrDefault(input.PriceTierKey); + } await CustomerRepository.UpdateAsync(entity); }