# OMS 后端系统结构说明

> 项目路径：`C:\Users\wilso\Desktop\oms0414-后端`  
> 解决方案：`SimpleAdmin.sln`  
> 技术栈：**.NET 8**、**Fake 模块化框架**、**SqlSugar + MySQL**、**JWT/RBAC**、**Swagger**

---

## 1. 总体架构

系统采用 **DDD 分层 + 模块化** 结构：`ApplicationService` 通过 Fake 框架自动暴露为 HTTP API（无需手写 Controller）。

```mermaid
flowchart TB
    subgraph Host["SimpleAdmin.Api（宿主）"]
        Program["Program / Bootstrap"]
        Auth["AuthService 认证"]
        WeChat["微信登录/回调"]
    end

    subgraph App["Oms.Application（应用层）"]
        Services["Services 业务服务"]
        Dtos["Dtos 入参/出参"]
        Shared["Shared 工具类"]
    end

    subgraph Domain["Oms.Domain（领域层）"]
        Entities["Entities 实体"]
        Repos["Repositories 仓储接口"]
        Enums["Enums / Consts"]
    end

    subgraph Infra["Oms.SqlSugarCore（基础设施）"]
        DbCtx["OmsDbContext"]
        RepoImpl["Repository 实现"]
    end

  subgraph Test["测试"]
        Unit["Oms.Tests"]
        Integ["SimpleAdmin.Api.IntegrationTests"]
    end

    Host --> App
    App --> Domain
    App --> Infra
    Infra --> Domain
    Test --> Host
```

### 项目依赖关系

| 项目 | 职责 |
|------|------|
| **SimpleAdmin.Api** | Web 宿主：启动、中间件、认证、微信、Swagger |
| **Oms.Application** | 应用服务与 DTO，对外提供 `/customer`、`/order`、`/channel` 等 API |
| **Oms.Domain** | 领域实体、枚举、仓储接口（不含数据库实现） |
| **Oms.SqlSugarCore** | SqlSugar 仓储实现与 `OmsDbContext` |
| **Oms.Tests** | 单元测试（计重算价、工具类等） |
| **SimpleAdmin.Api.IntegrationTests** | API 集成测试 |

### API 路由前缀约定

| 前缀 | 来源 | 说明 |
|------|------|------|
| `/rbac/*` | Fake.Rbac + `AuthService` | 用户/角色/权限/登录 |
| `/customer/*`、`/order/*` 等 | `Oms.Application.Services.*` | OMS 业务接口 |
| `/wechat/*` | `SimpleAdmin.Api.WeChat` | 微信公众号与客户微信登录 |

JWT 中业务用户整数 ID 的 Claim 名为 **`mapId`**（对应 `user.userid` / `t_customer.UserId`）。

---

## 2. 根目录文件

| 文件/目录 | 作用 |
|-----------|------|
| `SimpleAdmin.sln` | Visual Studio 解决方案入口 |
| `Directory.Build.props` | 全解决方案 MSBuild 公共属性（目标框架、包版本等） |
| `NuGet.Config` | NuGet 源与包还原配置 |
| `db.sql` | 数据库建表/初始化 SQL |
| `sql/` | 补充 SQL 脚本目录 |
| `README.md` | 项目快速入门说明 |
| `SPEC.md` | 规格/约定文档 |
| `design.md` | 设计说明 |
| `开发复刻说明.md` | 开发复刻与环境说明 |
| `.github/workflows/` | CI/CD（构建、部署流水线） |
| `.dockerignore` | Docker 构建忽略规则 |

---

## 3. SimpleAdmin.Api（Web 宿主）

路径：`src/SimpleAdmin.Api/`

| 文件 | 作用 |
|------|------|
| `Program.cs` | 应用入口：调用 Bootstrap 创建并运行 Web 应用 |
| `SimpleAdminApiBootstrap.cs` | 统一构建器：Consul 配置、Serilog、Autofac、Fake 模块注册 |
| `SimpleAdminApiModule.cs` | 主模块：动态 API 扫描、CORS、Swagger、认证授权、静态文件、中间件管道 |
| `SimpleJwtService.cs` | 替换默认 JWT 服务：在 Token Claims 中写入 `mapId`（`user.userid`） |
| `SimpleOmsClaimTypes.cs` | OMS 自定义 Claim 类型常量 |

### Auth/（认证与客户登录）

| 文件 | 作用 |
|------|------|
| `AuthService.cs` | OMS 认证中心：`/rbac/auth/login`（管理员/客户）、微信登录、刷新 Token、当前用户、改密、头像上传 |
| `AuthRequestDtos.cs` | 登录相关 DTO（`OmsLoginInput`、`OmsLoginType` 等） |
| `CustomerRoleSeedContributor.cs` | 数据种子：启动时确保存在 `Customer` 角色 |

### WeChat/（微信公众号）

| 文件 | 作用 |
|------|------|
| `WeChatMpAppService.cs` | 公众号服务器验签、消息回调、登录二维码接口 |
| `WeChatCustomerAppService.cs` | 客户微信 OAuth 用户信息、注册、绑定 |
| `WeChatServiceExtensions.cs` | `AddOmsWeChat` DI 扩展注册 |
| `Dtos/WeChatDtos.cs` | 微信相关请求/响应 DTO |
| `Options/WeChatMpOptions.cs` | 公众号 AppId、Secret 等配置项 |
| `Services/IWeChatLoginSessionStore.cs` | 微信扫码登录会话存储接口 |
| `Services/WeChatLoginSessionStore.cs` | 内存/缓存实现：保存扫码 state 与 openId |
| `Services/WeChatMpApiClient.cs` | 调用微信开放平台 API（access_token、用户信息等） |
| `Services/WeChatEventHandler.cs` | 处理公众号推送事件（关注、扫码等） |
| `Services/WeChatSignatureHelper.cs` | 微信签名校验工具 |

---

## 4. Oms.Application（应用层）

路径：`src/Oms.Application/`

| 文件 | 作用 |
|------|------|
| `OmsApplicationModule.cs` | 应用模块：注册 AutoMapper Profile 扫描 |
| `GlobalUsings.cs` | 全局 using 声明 |
| `Profiles/OmsApplicationAutoMapperProfile.cs` | Entity ↔ DTO 映射配置 |

### Shared/（公共工具）

| 文件 | 作用 |
|------|------|
| `OmsDocHelper.cs` | 分页参数规范化、日期空值处理等文档约定工具 |
| `OmsPasswordHelper.cs` | 客户密码 MD5 哈希 |
| `OmsFileUploadHelper.cs` | 充值截图等文件上传至 `wwwroot/uploads` |
| `JsonStringArrayHelper.cs` | JSON 字符串数组序列化/反序列化辅助 |
| `PagingHelper.cs` | 分页计算辅助 |

---

### Services/Channels/（渠道与产品）

| 文件 | 主要 API | 作用 |
|------|----------|------|
| `AutoTriggerService.cs` | `/channel/auto-trigger/*` | 自动触发规则 CRUD、启停 |
| `KpiAreaService.cs` | `/channel/kpi-area/*` | KPI 分区及明细维护 |
| `LabelTemplateService.cs` | `/channel/label-template/save` | 面单模板保存 |
| `SalesProductService.cs` | `/channel/sales-product/*` | 销售产品 CRUD、价格、分配、发布/回滚 |
| `SalesProductService.Helpers.cs` | — | 销售产品服务私有辅助（映射、发布逻辑等） |
| `ServiceChannelService.cs` | `/channel/service-channel/*` | 服务渠道、分组、价格、发布/回滚 |
| `ServiceChannelService.Helpers.cs` | — | 服务渠道服务私有辅助 |
| `WeightRoundingService.cs` | `/channel/weight-rounding/*` | 重量进位规则及明细 |
| `WeightRuleService.cs` | `/channel/weight-rule/*` | 计重规则（材积系数等）及明细 |

### Services/Customers/

| 文件 | 主要 API | 作用 |
|------|----------|------|
| `CustomerService.cs` | `/customer/*` | 客户列表/详情/创建/子客户/更新/删除/重置密码；联动 RBAC 用户 |

### Services/Operations/（仓内作业）

| 文件 | 主要 API | 作用 |
|------|----------|------|
| `InboundRecordService.cs` | `/operation/inbound/*` | 入库登记与最近记录 |
| `OutboundRecordService.cs` | `/operation/outbound/*` | 出库登记与最近记录 |
| `LabelPrintService.cs` | `/operation/print-label/*` | 面单打印、模板下拉、打印记录 |

### Services/Orders/（订单）

| 文件 | 主要 API | 作用 |
|------|----------|------|
| `OrderService.cs` | `/order/*`（主文件） | 订单列表/详情/支付/申报/拦截/导出/模板/上传 |
| `OrderService.BatchJob.cs` | `/order/batch/*` | 批量任务列表/详情/子项/重试/取消 |
| `OrderService.ParcelBilling.cs` | `/order/parcel/*` | 小包创建、批量创建、计重算价、费用快照写入 |
| `OrderService.ParcelQuote.cs` | `/order/price-check` | 价格试算：匹配产品与分区报价 |
| `OrderService.Helpers.cs` | — | 订单通用辅助（导入、状态校验、映射等） |
| `Batch/OrderBatchJobCoordinator.cs` | — | 批量任务创建、幂等、同步/异步入队 |
| `Batch/OrderBatchJobProcessor.cs` | — | 批量子项消费与结果回写 |
| `Batch/OrderBatchJobItemFeedback.cs` | — | 子项成功/失败/重试反馈封装 |
| `ParcelBillingCalculator.cs` | — | 静态计重算价引擎：材积重、分区、卖价费用 |
| `ParcelQuoteContext.cs` | — | 报价上下文（国家、邮编、尺寸重量等） |
| `ParcelQuoteResult.cs` | — | 单产品报价结果模型 |

### Services/Recharge/（充值）

| 文件 | 主要 API | 作用 |
|------|----------|------|
| `RechargeService.cs` | `/recharge/*` | 提交充值、审核/驳回、记录列表、Excel 导出 |

### Services/System/（系统基础数据）

| 文件 | 主要 API | 作用 |
|------|----------|------|
| `CountryService.cs` | `/system/country/list` | 国家列表 |
| `DictService.cs` | `/system/dict/*` | 数据字典 CRUD |
| `NoticeService.cs` | `/system/notice/*` | 公告 CRUD、已读确认 |
| `WarehouseService.cs` | `/system/warehouse/*` | 仓库地址 CRUD |

---

### Dtos/（数据传输对象）

命名约定：

- `*Input` / `*SaveInput` / `*CreateInput`：请求入参  
- `*Output`：响应出参  
- `*PaginatedInput` / `*PaginatedOutput`：分页查询与列表项  
- `*ListInput` / `*ListOutput`：列表查询（部分渠道模块使用 POST list）

#### Dtos/Shared/

| 文件 | 作用 |
|------|------|
| `IdInput.cs` | 通用主键入参 `{ id }` |
| `OmsPageResult.cs` | 分页响应 `{ items, total }` |
| `OmsItemsResult.cs` | 无分页列表包装 |
| `ToggleStatusInput.cs` | 启停状态切换入参 |

#### Dtos/Channels/

| 文件 | 作用 |
|------|------|
| `AutoTriggerListInput.cs` / `AutoTriggerOutput.cs` / `AutoTriggerSaveInput.cs` | 自动触发规则 |
| `KpiAreaListInput.cs` / `KpiAreaOutput.cs` / `KpiAreaSaveInput.cs` | KPI 分区主表 |
| `KpiAreaInfoListInput.cs` / `KpiAreaInfoOutput.cs` / `KpiAreaInfoSaveInput.cs` | KPI 分区明细 |
| `LabelTemplateSaveInput.cs` / `LabelTemplateSaveOutput.cs` | 面单模板 |
| `SalesProductListInput.cs` / `SalesProductListOutput.cs` | 销售产品列表 |
| `SalesProductDetailOutput.cs` | 销售产品详情 |
| `SalesProductSaveInput.cs` | 销售产品保存 |
| `SalesProductPriceListOutput.cs` | 产品价格列表项 |
| `SalesProductPriceSaveInput.cs` / `SalesProductPriceSaveAllInput.cs` | 单条/批量保存价格 |
| `ChannelPriceDetailInput.cs` / `ChannelPriceDetailOutput.cs` | 价格明细行 |
| `ChannelPriceFactorInput.cs` / `ChannelPriceFactorOutput.cs` | 价格因子 |
| `SalesProductAllocationOutput.cs` | 产品分配方案 |
| `SalesProductAllocationProviderInput.cs` / `SalesProductAllocationProviderOutput.cs` | 分配供应商 |
| `SalesProductAllocationSaveInput.cs` | 保存分配配置 |
| `SalesProductPublishInput.cs` / `SalesProductRollbackInput.cs` | 发布/回滚 |
| `SalesProductPublishListInput.cs` / `SalesProductPublishRecordOutput.cs` | 发布记录 |
| `ServiceChannelListInput.cs` / `ServiceChannelListOutput.cs` | 服务渠道列表 |
| `ServiceChannelDetailOutput.cs` / `ServiceChannelSaveInput.cs` | 渠道详情与保存 |
| `ServiceChannelGroupListInput.cs` / `ServiceChannelGroupListOutput.cs` / `ServiceChannelGroupSaveInput.cs` | 渠道分组 |
| `ServiceChannelPriceListOutput.cs` / `ServiceChannelPriceSaveInput.cs` / `ServiceChannelPriceSaveAllInput.cs` | 渠道价格 |
| `ServiceChannelPublishInput.cs` / `ServiceChannelRollbackInput.cs` | 渠道发布/回滚 |
| `ServiceChannelPublishListInput.cs` / `ServiceChannelPublishRecordOutput.cs` | 渠道发布记录 |
| `WeightRuleListInput.cs` / `WeightRuleOutput.cs` / `WeightRuleSaveInput.cs` | 计重规则主表 |
| `WeightRuleInfoListInput.cs` / `WeightRuleInfoOutput.cs` / `WeightRuleInfoSaveInput.cs` | 计重规则明细 |
| `WeightRoundingListInput.cs` / `WeightRoundingOutput.cs` / `WeightRoundingSaveInput.cs` | 进位规则主表 |
| `WeightRoundingInfoListInput.cs` / `WeightRoundingInfoOutput.cs` / `WeightRoundingInfoSaveInput.cs` | 进位规则明细 |

#### Dtos/Customers/

| 文件 | 作用 |
|------|------|
| `CustomerPaginatedInput.cs` / `CustomerPaginatedOutput.cs` | 客户分页查询 |
| `CustomerOutput.cs` | 客户详情 |
| `CreateCustomerInput.cs` | 创建主客户 |
| `CreateSubCustomerInput.cs` | 创建子客户（含权限子集） |
| `UpdateCustomerInput.cs` | 更新客户 |
| `ResetCustomerPasswordInput.cs` | 重置密码 |

#### Dtos/Operations/

| 文件 | 作用 |
|------|------|
| `CreateInboundRecordInput.cs` / `InboundRecordOutput.cs` | 入库 |
| `CreateOutboundRecordInput.cs` / `OutboundRecordOutput.cs` | 出库 |
| `PrintLabelInput.cs` / `LabelPrintRecordOutput.cs` | 面单打印 |
| `LabelTemplateDropdownOutput.cs` | 打印模板下拉项 |

#### Dtos/Orders/

| 文件 | 作用 |
|------|------|
| `OrderPaginatedInput.cs` / `OrderPaginatedOutput.cs` / `OrderOutput.cs` | 订单列表与详情 |
| `OrderActionInput.cs` | 订单操作通用入参（支付/拦截等） |
| `OrderItemOutput.cs` / `OrderReceiverOutput.cs` / `OrderSenderOutput.cs` | 订单明细、收发件人 |
| `OrderWeightOutput.cs` | 订单重量信息 |
| `OrderExportInput.cs` / `OrderExportOutput.cs` | 订单导出 |
| `OrderPrintOutput.cs` | 打印数据 |
| `OrderPriceCheckInput.cs` / `OrderPriceCheckOutput.cs` | 价格试算 |
| `OrderParcelCreateInput.cs` / `OrderParcelCreateOutput.cs` | 单票小包创建 |
| `OrderParcelBatchCreateInput.cs` / `OrderParcelBatchCreateOutput.cs` / `OrderParcelBatchCreateItemOutput.cs` | 批量小包创建 |
| `OrderParcelItemInput.cs` / `OrderParcelReceiverInput.cs` / `OrderParcelSenderInput.cs` | 小包货品与地址 |
| `OrderTemplateListInput.cs` / `OrderTemplateOutput.cs` | 导入模板 |
| `OrderUploadInput.cs` / `OrderUploadOutput.cs` | Excel 批量上传（返回 jobId、async） |
| `OrderBatchJobListInput.cs` / `OrderBatchJobDtos.cs` | 批量任务列表/详情/子项 DTO |
| `ProductBillingSnapshotDtos.cs` | 计费快照（产品、价格、分区等）内部 DTO |

#### Dtos/Recharge/

| 文件 | 作用 |
|------|------|
| `SubmitRechargeFormInput.cs` | multipart 表单提交充值（含截图文件） |
| `SubmitRechargeInput.cs` | JSON 方式提交充值（备用） |
| `RechargeRecordOutput.cs` | 单条充值记录 |
| `RechargeRecordPaginatedInput.cs` / `RechargeRecordPaginatedOutput.cs` | 充值记录分页 |
| `ApproveRechargeInput.cs` / `RejectRechargeInput.cs` | 审核通过/驳回 |
| `RechargeExportInput.cs` | 充值导出筛选 |

#### Dtos/System/

| 文件 | 作用 |
|------|------|
| `CountryOutput.cs` | 国家 |
| `DictListInput.cs` / `DictOutput.cs` / `DictCreateInput.cs` / `DictUpdateInput.cs` | 字典 |
| `NoticeListInput.cs` / `NoticeOutput.cs` / `NoticeCreateInput.cs` / `NoticeUpdateInput.cs` | 公告 |
| `WarehousePaginatedInput.cs` / `WarehousePaginatedOutput.cs` / `WarehouseOutput.cs` | 仓库列表与详情 |
| `CreateWarehouseInput.cs` / `UpdateWarehouseInput.cs` | 仓库创建/更新 |

---

## 5. Oms.Domain（领域层）

路径：`src/Oms.Domain/`

| 文件 | 作用 |
|------|------|
| `OmsDomainModule.cs` | 领域模块（依赖 Fake DDD 模块） |

### Shared/

| 文件 | 作用 |
|------|------|
| `OmsAuditedAggregateRoot.cs` | 聚合根基类：int 主键、软删除、创建/更新人与时间 |
| `OmsAuditedEntity.cs` | 子实体审计基类 |
| `Enums/EnableStatus.cs` | 通用启用/禁用枚举 |

### CustomersAggregate/（客户）

| 文件 | 作用 |
|------|------|
| `Entities/Customer.cs` | 客户实体 `t_customer`（UserId、余额、分组、状态等） |
| `Enums/CustomerStatus.cs` | 客户状态：正常/禁用/冻结 |
| `Enums/CustomerGroup.cs` | 客户分组 |
| `Repositories/ICustomerRepository.cs` | 客户仓储接口（按编号/手机/邮箱查询等） |

### RechargeAggregate/（充值）

| 文件 | 作用 |
|------|------|
| `Entities/RechargeRecord.cs` | 充值记录 `t_recharge_record` |
| `Enums/PayType.cs` | 支付方式：微信/支付宝 |
| `Enums/RechargeStatus.cs` | 充值状态：待审核/通过/驳回 |
| `Repositories/IRechargeRecordRepository.cs` | 充值记录仓储接口 |

### OrdersAggregate/（订单）

| 文件 | 作用 |
|------|------|
| `Entities/Order.cs` | 订单主表 |
| `Entities/OrderRecipient.cs` | 收件人 |
| `Entities/OrderSender.cs` | 发件人 |
| `Entities/OrderDeclaration.cs` | 申报信息 |
| `Entities/OrderFee.cs` | 订单费用明细 |
| `Entities/OrderWeight.cs` | 重量尺寸（预报/复核等） |
| `Entities/OrderTemplate.cs` | 导入模板元数据 |
| `Entities/OrderBatchJob.cs` | 批量任务头（导入/支付/打印等） |
| `Entities/OrderBatchJobItem.cs` | 批量任务子项 |
| `Consts/OrderBatchJobStatusCodes.cs` | 批量任务状态常量 |
| `Consts/OrderStatusCodes.cs` | 订单状态常量 |
| `Consts/OrderFeeTypeCodes.cs` | 费用类型常量 |
| `Consts/OrderWeightTypeCodes.cs` | 重量类型常量 |
| `Consts/CargoAttributeCodes.cs` | 货物属性常量 |
| `Repositories/IOrderRepository.cs` | 订单仓储（含关联加载） |
| `Repositories/IOrderTemplateRepository.cs` | 模板仓储 |
| `Repositories/IOrderBatchJobRepository.cs` | 批量任务仓储 |

### ChannelsAggregate/（渠道/产品/计价）

| 文件 | 作用 |
|------|------|
| `Entities/SalesProduct.cs` | 销售产品 |
| `Entities/SalesProductPrice.cs` | 产品销售价格版本 |
| `Entities/SalesProductPriceDetail.cs` | 价格分区明细 |
| `Entities/SalesProductPriceFactor.cs` | 价格因子 |
| `Entities/SalesProductAllocationProvider.cs` | 产品分配供应商 |
| `Entities/SalesProductPublishRecord.cs` | 产品发布记录 |
| `Entities/ServiceChannel.cs` | 服务渠道 |
| `Entities/ServiceChannelGroup.cs` | 渠道分组 |
| `Entities/ServiceChannelPrice.cs` | 渠道价格版本 |
| `Entities/ServiceChannelPriceDetail.cs` | 渠道价格明细 |
| `Entities/ServiceChannelPriceFactor.cs` | 渠道价格因子 |
| `Entities/ServiceChannelPublishRecord.cs` | 渠道发布记录 |
| `Entities/KpiArea.cs` / `KpiAreaInfo.cs` | KPI 分区 |
| `Entities/WeightRule.cs` / `WeightRuleInfo.cs` | 计重规则 |
| `Entities/WeightRounding.cs` / `WeightRoundingInfo.cs` | 重量进位 |
| `Entities/AutoTrigger.cs` | 自动触发 |
| `Entities/LabelTemplate.cs` | 面单模板 |
| `Consts/AllocationSchemeCodes.cs` | 分配方案编码 |
| `Consts/AreaTypeCodes.cs` | 分区类型编码 |
| `Repositories/ISalesProductRepository.cs` | 销售产品仓储 |
| `Repositories/IServiceChannelRepository.cs` | 服务渠道仓储 |
| `Repositories/IServiceChannelGroupRepository.cs` | 渠道分组仓储 |
| `Repositories/IKpiAreaRepository.cs` | KPI 分区仓储 |
| `Repositories/IWeightRuleRepository.cs` | 计重规则仓储 |
| `Repositories/IWeightRoundingRepository.cs` | 进位规则仓储 |
| `Repositories/IAutoTriggerRepository.cs` | 自动触发仓储 |
| `Repositories/ILabelTemplateRepository.cs` | 面单模板仓储 |

### OperationsAggregate/（仓内作业）

| 文件 | 作用 |
|------|------|
| `Entities/InboundRecord.cs` | 入库记录 |
| `Entities/OutboundRecord.cs` | 出库记录 |
| `Entities/LabelPrintRecord.cs` | 面单打印记录 |
| `Repositories/IInboundRecordRepository.cs` | 入库仓储 |
| `Repositories/IOutboundRecordRepository.cs` | 出库仓储 |
| `Repositories/ILabelPrintRecordRepository.cs` | 打印记录仓储 |

### SystemAggregate/（系统）

| 文件 | 作用 |
|------|------|
| `Entities/Country.cs` | 国家 |
| `Entities/Dict.cs` | 数据字典 |
| `Entities/Notice.cs` | 系统公告 |
| `Entities/NoticeRead.cs` | 公告已读记录 |
| `Entities/WarehouseAddress.cs` | 仓库地址 |
| `Consts/WarehouseCodes.cs` | 仓库相关常量 |
| `Repositories/ICountryRepository.cs` | 国家仓储 |
| `Repositories/IDictRepository.cs` | 字典仓储 |
| `Repositories/INoticeRepository.cs` | 公告仓储 |
| `Repositories/INoticeReadRepository.cs` | 已读仓储 |
| `Repositories/IWarehouseAddressRepository.cs` | 仓库仓储 |

---

## 6. Oms.SqlSugarCore（基础设施层）

路径：`src/Oms.SqlSugarCore/`

| 文件 | 作用 |
|------|------|
| `OmsSqlSugarCoreModule.cs` | 注册 `OmsDbContext`、MySQL 连接 |
| `OmsDbContext.cs` | SqlSugar 数据库上下文 |
| `Repositories/OmsSqlSugarRepository.cs` | 通用仓储基类（审计聚合根 CRUD） |

各业务仓储实现（与 Domain 接口一一对应）：

| 文件 | 实现接口 | 作用 |
|------|----------|------|
| `Customers/CustomerRepository.cs` | `ICustomerRepository` | 客户表访问 |
| `Recharge/RechargeRecordRepository.cs` | `IRechargeRecordRepository` | 充值记录 |
| `Orders/OrderRepository.cs` | `IOrderRepository` | 订单及关联表 |
| `Orders/OrderTemplateRepository.cs` | `IOrderTemplateRepository` | 订单模板 |
| `Orders/OrderBatchJobRepository.cs` | `IOrderBatchJobRepository` | 批量任务及子项 |
| `Channels/SalesProductRepository.cs` | `ISalesProductRepository` | 销售产品 |
| `Channels/ServiceChannelRepository.cs` | `IServiceChannelRepository` | 服务渠道 |
| `Channels/ServiceChannelGroupRepository.cs` | `IServiceChannelGroupRepository` | 渠道分组 |
| `Channels/KpiAreaRepository.cs` | `IKpiAreaRepository` | KPI 分区 |
| `Channels/WeightRuleRepository.cs` | `IWeightRuleRepository` | 计重规则 |
| `Channels/WeightRoundingRepository.cs` | `IWeightRoundingRepository` | 进位规则 |
| `Channels/AutoTriggerRepository.cs` | `IAutoTriggerRepository` | 自动触发 |
| `Channels/LabelTemplateRepository.cs` | `ILabelTemplateRepository` | 面单模板 |
| `Operations/InboundRecordRepository.cs` | `IInboundRecordRepository` | 入库 |
| `Operations/OutboundRecordRepository.cs` | `IOutboundRecordRepository` | 出库 |
| `Operations/LabelPrintRecordRepository.cs` | `ILabelPrintRecordRepository` | 打印记录 |
| `System/CountryRepository.cs` | `ICountryRepository` | 国家 |
| `System/DictRepository.cs` | `IDictRepository` | 字典 |
| `System/NoticeRepository.cs` | `INoticeRepository` | 公告 |
| `System/NoticeReadRepository.cs` | `INoticeReadRepository` | 公告已读 |
| `System/WarehouseAddressRepository.cs` | `IWarehouseAddressRepository` | 仓库 |

---

## 7. Oms.Tests（单元测试）

路径：`src/Oms.Tests/`

| 文件 | 作用 |
|------|------|
| `GlobalUsings.cs` | 测试项目全局 using |
| `OmsDocHelperTests.cs` | `OmsDocHelper` 单元测试 |
| `OmsPasswordHelperTests.cs` | 密码哈希单元测试 |
| `ParcelBillingCalculatorTests.cs` | 小包计重算价逻辑测试 |
| `Support/ParcelBillingTestData.cs` | 算价测试夹具数据 |
| `Support/TestCurrentPrincipalAccessor.cs` | 模拟当前用户 Principal |

---

## 8. SimpleAdmin.Api.IntegrationTests（集成测试）

路径：`src/SimpleAdmin.Api.IntegrationTests/`

| 文件 | 作用 |
|------|------|
| `GlobalUsings.cs` | 集成测试全局 using |
| `Support/SimpleAdminApiTestHost.cs` | 内存 TestServer 宿主封装 |
| `AuthApiIntegrationTests.cs` | 认证 API 集成测试 |
| `CustomerApiIntegrationTests.cs` | 客户 API 集成测试 |
| `CountryApiIntegrationTests.cs` | 国家 API 集成测试 |
| `DictApiIntegrationTests.cs` | 字典 API 集成测试 |
| `WarehouseApiIntegrationTests.cs` | 仓库 API 集成测试 |

---

## 9. 业务模块速查

| 业务域 | 核心 Service | 主要数据表（实体） |
|--------|--------------|-------------------|
| 认证 | `AuthService` | RBAC `user` + `t_customer` |
| 客户 | `CustomerService` | `t_customer` |
| 充值 | `RechargeService` | `t_recharge_record` |
| 订单 | `OrderService` | `t_order` 及收发件人、费用、重量等 |
| 渠道 | `ServiceChannelService` | 服务渠道及价格、发布记录 |
| 产品 | `SalesProductService` | 销售产品及价格、分配、发布 |
| 计价规则 | `WeightRuleService`、`WeightRoundingService`、`KpiAreaService` | 计重/进位/KPI 分区 |
| 仓内 | `InboundRecordService` 等 | 入出库、打印记录 |
| 系统 | `DictService`、`NoticeService`、`WarehouseService` | 字典、公告、仓库 |
| 微信 | `WeChatMpAppService`、`WeChatCustomerAppService` | 会话存储（内存） |

---

## 10. 本地运行

```bash
cd src/SimpleAdmin.Api
dotnet run
```

默认通过 `appsettings.json` / Consul 读取 `ConnectionStrings:Default`（MySQL）。Swagger 在应用启动 URL 根路径可访问。

---

*文档根据仓库当前源码自动生成，如有新增 `.cs` 文件，请按相同分层规则补充到对应章节。*