补充项目的说明文档

tjx

2025-10-12 7db777a85e53e04b701c6a31f0aec0a197dc0150

补充项目的说明文档

 README.md

@@ -1,4 +1,46 @@
## LB_MesService
# GS MES æœåŠ¡

蓝宝PC后端
## é¡¹ç›®æ¦‚览
GS MES Service åŸºäºŽ ASP.NET Core 8.0 æž„建，`Gs.HostIIS` è´Ÿè´£æ‰˜ç®¡ Web API、加载配置并暴露分组化 Swagger æ–‡æ¡£ã€‚各业务模块（BaseInfo、Sales、Warehouse ç­‰ï¼‰ä»¥ `Gs.<Module>` é¡¹ç›®å­˜åœ¨ï¼ŒæŽ§åˆ¶å™¨æ”¾åœ¨ `Services/`，数据模型位于 `Models/`，共享实体和 DTO é›†ä¸­åœ¨ `Gs.Entity`。通用组件（授权、Excel、HTTP、依赖注入扩展等）统一封装在 `Gs.Toolbox`。

## ç›®å½•ç»“æž„
- `GsMesSolution.sln`：解决方案入口，统一执行构建、测试。
- `Gs.HostIIS/`：宿主项目，包含 `Program.cs`、`appsettings*.json`、Swagger é…ç½®ä»¥åŠ `/down`、`/upload` é™æ€èµ„源映射。
- `Gs.<Module>/`：业务模块（如 `Gs.BaseInfo`、`Gs.Sales`、`Gs.Warehouse`），遵循 `Models/` + `Services/` æ–‡ä»¶å¤¹å¸ƒå±€ã€‚
- `Gs.Entity/`：SqlSugar å®žä½“与跨模块共享的 DTO。
- `Gs.Toolbox/`：依赖注入扩展、API çº¦å®šã€æ—¥å¿—、Excel å·¥å…·ç­‰åŸºç¡€è®¾æ–½èƒ½åŠ›ã€‚
- `Gs.HostIIS/.config/`：部署阶段使用的环境配置转换文件。

## å¿«é€Ÿå¼€å§‹
1. å®‰è£… .NET SDK 8.0，确认数据库连接信息与 `appsettings.json` å¯¹åº”。
2. æ¢å¤ä¾èµ–：
   ```bash
   dotnet restore GsMesSolution.sln
   ```
3. æž„建项目：
   ```bash
   dotnet build GsMesSolution.sln -c Release
   ```
4. å¯åŠ¨ API：
   ```bash
   dotnet run --project Gs.HostIIS/Gs.HostIIS.csproj
   ```
   å¯åŠ¨åŽè®¿é—® `http://localhost:<端口>/swagger` æŸ¥çœ‹åˆ†ç»„ API æ–‡æ¡£ã€‚静态下载目录映射 `/down`，上传目录映射 `/upload`，路径由配置中的 `DownPath`、`UploadPath` æŽ§åˆ¶ã€‚

## æµ‹è¯•è¯´æ˜Ž
仓库暂未引入自动化测试。新增功能时请在相应模块旁创建 xUnit é¡¹ç›®ï¼ˆç¤ºä¾‹ï¼š`Gs.Sales.Tests`），测试文件统一命名为 `*Tests.cs`。Mock SqlSugar ä¾èµ–保持测试可重复，并在解决方案根目录执行：
```bash
dotnet test
```
提交变更前记录手工冒烟结果（Swagger å¯ç”¨æ€§ã€æ ¸å¿ƒæŽ¥å£ã€å…³é”®å­˜å‚¨è¿‡ç¨‹ï¼‰å¹¶å†™å…¥ PR。

## é…ç½®ä¸Žå®‰å…¨
- ç¦æ­¢æäº¤ä»»ä½•ç¡¬ç¼–码的连接字符串或密码，开发阶段通过 User Secrets æˆ–环境变量注入。
- çŽ¯å¢ƒå·®å¼‚配置放入 `.config` ç›®å½•ï¼Œå‘布时执行转换，不直接修改基础配置。
- è°ƒæ•´ SqlSugar æ•°æ®ç»“构前务必在预发布环境验证，并在公开部署前检查 Swagger æš´éœ²èŒƒå›´ã€‚

## è´¡çŒ®æŒ‡å—
- éµå¾ªå››ç©ºæ ¼ç¼©è¿›ã€ç±»åž‹ `PascalCase`、局部变量 `camelCase`、常量 `ALL_CAPS` çš„命名规范，保持可空引用启用。
- æ–°å¢žæœåŠ¡é€šè¿‡ `Gs.Toolbox` çš„扩展方法注册，确保 `builder.AddCustomInject()` æµç¨‹å®šä¹‰ç»Ÿä¸€ã€‚
- æäº¤ä¿¡æ¯æ²¿ç”¨åŽ†å²é£Žæ ¼ï¼šç®€æ´çš„中文单行说明，例如 `Baobiao: ä¿®å¤å¯¼å‡ºå¼‚常`。
- PR ä¸­éœ€åˆ—出受影响模块、配置或数据库变更、自动化测试与手工冒烟结果，并附上示例请求或截图。

 WebApi/MODULES.md

¶Ô±ÈÐÂÎļþ
@@ -0,0 +1,152 @@
# æ¨¡å—详解指南

本指南汇总 GS MES Service è§£å†³æ–¹æ¡ˆå†…各项目/模块的职责、核心接口以及与其他模块的依赖关系，供开发、测试与运维人员快速定位代码位置与业务边界。

## é€šç”¨åŸºç¡€ç»„件
- **Gs.HostIIS**（`Gs.HostIIS/Program.cs`、`Gs.HostIIS/RequestAuthorizeAttribute.cs`）  
  - æ‰¿è½½ ASP.NET Core ä¸»æœºï¼Œç»Ÿä¸€æ³¨å†Œ MVC、全局授权过滤、CORS、Swagger åˆ†ç»„及静态目录。  
  - é€šè¿‡ `builder.AddCustomInject()` å’Œ `app.AddCustomController()` æ‰«ææ‰€æœ‰å¼•ç”¨ç¨‹åºé›†çš„服务，实现模块级热插拔。  
  - è§£æžé…ç½®é¡¹ `ServicesPath`、`DownPath`、`UploadPath`，对应 Swagger XML、下载与上传目录。
- **Gs.Toolbox**（如 `Gs.Toolbox\Repository.cs`、`Gs.Toolbox\ApiCore\Extensions`）  
  - æä¾› SqlSugar ä»“储基类、统一返回模型、Excel/日志/HTTP å·¥å…·ä»¥åŠ DI æ ‡è®°æŽ¥å£ï¼ˆ`ISingleton`、`IScope`、`ITransient`）。  
  - `ApplicationBuilderExtension` æ ¹æ®æŽ¥å£æ ‡è®°è‡ªåŠ¨æ³¨å…¥ï¼Œå®žçŽ°æ¨¡å—零散类的集中注册。  
  - `ApplicationExtension` ä¸Ž `CustomControllerFeatureProvider` ååŠ©æŒ‰æ¨¡å—动态装配控制器。
- **Gs.Entity**  
  - é›†ä¸­ç»´æŠ¤ SqlSugar å®žä½“、DTO åŠå…¬å…±æžšä¸¾ï¼Œä¾›æ‰€æœ‰ä¸šåŠ¡æ¨¡å—复用，减少重复定义。

## ä¸šåŠ¡é¢†åŸŸæ¨¡å—
### Gs.BaseInfo
- è´£ä»»ï¼šç»´æŠ¤ä¸»æ•°æ®ï¼Œå¦‚物料、供应商、工位、部门等，为仓储、销售、生产模块提供基础信息。  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.BaseInfo\Services\MesItemsManager.cs`：物料档案分页查询、映射单位/仓库/物料组等关联信息。  
  - `Gs.BaseInfo\Services\MesSupplierManager.cs`、`MesCustomerManager.cs`：供应商/客户资料增删改查。  
  - `Gs.BaseInfo\Services\PrintInfoManager.cs`、`PrintUserManager.cs`：打印模板及用户设备信息。  
  - `Gs.BaseInfo\Services\SysDepartmentManager.cs`、`MesPositionManager.cs`：组织及岗位管理。  
- ä¾èµ–：大量复用 `Repository<T>` æä¾›çš„通用分页、事务封装，并读取 `UtilityHelper` ä¸­çš„用户上下文数据。

### Gs.Sales
- è´£ä»»ï¼šé”€å”®è®¢å•ã€å‘货、退货等销售履约流程的对接与查询。  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.Sales\SalesManager.cs`：销售订单分页、条件过滤、调用存储过程。  
  - `Gs.Sales\SalesDeliverManager.cs`、`SalesDeliverDjManager.cs`：发货单及其明细、单据打印/审核。  
  - `Gs.Sales\SalesReturnManager.cs`、`SalesReturnDjManager.cs`：销售退货申请、执行及单据管理。  
- ç‰¹ç‚¹ï¼šä»¥ `ApiGroup(ApiGroupNames.XS)` æ ‡è¯†ï¼Œåœ¨ Swagger ä¸­å½’于销售分组，接口多返回动态对象，依赖 SqlClient è°ƒç”¨å­˜å‚¨è¿‡ç¨‹æ»¡è¶³å¤æ‚报表需求。

### Gs.Warehouse
- è´£ä»»ï¼šä»“储管理与库存处理，覆盖收发存、调拨、盘点、条码与自动入库。  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.Warehouse\Services\MesInvItemOutsManager.cs`：核心出库逻辑（成品、半成品、原材料），支持分页、批量操作、状态回写。  
  - `MesInvItemArnManager.cs`、`MesInvItemArnDetailManager.cs`：到货通知、验收入库、异常处理。  
  - `MesInvItemMovesManager.cs`、`MesInvItemMovesDjManager.cs`：仓库调拨及调拨单追踪。  
  - `MesInvItemBarcodesManager.cs`、`VArrivalBarcodeManager.cs`：条码生成、校验与追溯。  
  - `MesShouTuoManager.cs`、`MesShouTuoDjManager.cs`：收托、退托业务。  
  - `MesAutoRkController.cs`：自动入库接口，与设备/产线集成。  
- ä¾èµ–：与 `Gs.BaseInfo` çš„仓库、物料信息紧密关联；多处调用 `InitialBarcode` DTO；部分逻辑包含事务 `UseTransaction`。

### Gs.Report
- è´£ä»»ï¼šæŠ¥è¡¨æŸ¥è¯¢ã€å¯¼å‡ºä¸Žçœ‹æ¿å‘ˆçŽ°ï¼Œè¦†ç›–生产、质量、仓储等多场景。  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.Report\ReportController.cs`：通用报表入口，按报表代码调度不同查询。  
  - `Gs.Report\XlsInOutController.cs`：出入库统计 Excel å¯¼å‡ºï¼Œå¤§é‡ä½¿ç”¨ `ExcelHelper`。  
  - `Gs.Report\CkController.cs`、`QLController.cs`：仓库库存、质量统计。  
  - `Gs.Report\WOTraceCodes.cs`、`BTDetails.cs`：工单追踪与条码明细。  
  - `YS_*` ç³»åˆ—：以 `YS` å‰ç¼€å‘½åçš„专用报表（设备保养、进货检验、首检巡检等），多返回 DataTable/Excel æ–‡ä»¶ã€‚  
- ç‰¹ç‚¹ï¼šå¤šæ•°æŽ¥å£ä¸º POST，接受动态条件、分页及导出标记；深度依赖 SQL å­˜å‚¨è¿‡ç¨‹å’Œè§†å›¾ã€‚

### Gs.Sys
- è´£ä»»ï¼šç³»ç»Ÿé…ç½®ä¸Žæƒé™ç®¡ç†ã€‚  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.Sys\Services\UserController.cs`：用户维护、角色绑定、登录校验。  
  - `RoleController.cs`、`MenuActionController.cs`：角色与菜单权限配置，支持树形结构返回。  
  - `OrganizationController.cs`：组织架构维护，供其他模块按组织过滤数据。  
  - `DocNoRuleController.cs`：单号规则管理，生成业务单据编号。  
  - `MesConfigController.cs`, `MesFileController.cs`：系统通用配置、文件管理。  
  - `MesSysPageviewManager.cs`：门户页面访问统计。  
  - `SysLogController.cs`：操作日志查询。  
- æ¨¡åž‹ï¼š`Gs.Sys\Models` åŒ…含 `SysRole`, `SysUserRole`, `SysDocRule` ç­‰å®žä½“，对应数据库权限表。  
- ä¾èµ–：为全局认证和授权服务，其他模块通过 `_userGuid`、`_orgFids` æŽ§åˆ¶æ•°æ®æƒé™ã€‚

### GS.QC
- è´£ä»»ï¼šè´¨é‡ç®¡ç†ï¼ˆæ¥æ–™ã€åˆ¶ç¨‹ã€å‡ºè´§æ£€éªŒï¼‰åŠç¼ºé™·åº“管理。  
- ä¸»è¦æœåŠ¡ï¼š  
  - `GS.QC\Service\FqcManager.cs`、`FqcItemsManager.cs`：成品终检任务、抽样结果、判定。  
  - `IpqcShouManager.cs`、`IpqcXunManager.cs`：制程首检、巡检流程。  
  - `MesQaItemsDetect01Manager.cs`：来料检验明细处理。  
  - `MesDefectCodeManager.cs` ä¸Žæ¨¡åž‹ `MesDefectCode.cs`：缺陷代码维护与层级关系。  
  - `RkqcManager.cs`、`RkqcSqManager.cs`、`RkqcfaManager.cs`：入库质检申请、方案及执行。  
  - `MesQmCheckitemManager.cs` åŠ `MesQmCheckitemDtManager.cs`：检验项目及明细维护。  
- ç‰¹ç‚¹ï¼šå¤§é‡ä½¿ç”¨æŠ½æ ·æ–¹æ¡ˆæ¨¡åž‹ `MesQmAql*`；与仓储模块共享条码及到货单数据。

### Gs.JJGZ
- è´£ä»»ï¼šè®¡ä»¶è®¡ä»·ã€å·¥æ—¶ä¸Žè€ƒå‹¤ç»Ÿè®¡ã€‚  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.JJGZ\MesJjgzScheduleController.cs`：排班计划、产线班组排程。  
  - `MesJjgzTimeTypeController.cs`：工时类型定义（加班、请假等）。  
  - `MesJjgzJjsalaryController.cs`、`MesJjgzJssalaryController.cs`：计件、计时薪资计算。  
  - `MesJjgzErrorJsController.cs`：计薪异常处理与调整。  
  - `MesAttanConController.cs`、`MesDeToLineController.cs`：考勤、岗位到线关系维护。  
- ä¾èµ–：需要来自生产、工单、人员模块的数据；可能调用存储过程生成薪资报表。

### Gs.Wom
- è´£ä»»ï¼šè½¦é—´åˆ¶é€ æ‰§è¡Œä¸Žå·¥åºé‡‡é›†ã€‚  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.Wom\Service\MesProcInfoController.cs`：工序工艺信息、节点维护。  
  - `MesProdGx0Controller.cs`, `WompbaManager.cs`, `WompbaGxManager.cs`：工单排产、工序分配、生产工艺路线。  
  - `MesWorkProdManager.cs`、`MesScrkDjManager.cs`：生产上线、入库单据。  
  - `FanGongManager.cs`、`MesBackFlashController.cs`：返工／回冲流程。  
  - `WorkService\WorkCollectController.cs`、`WorkTechniqueController.cs`：产线看板、工艺资料查询、工序扫码采集。  
  - `WorkProController.cs`、`WorkRepairController.cs`、`WorkWeightController.cs`：生产进度、维修、称重等现场操作接口。  
- ä¾èµ–：与条码、仓储、工单、人员信息紧密耦合，是 MES æ‰§è¡Œå±‚的核心。

### Gs.Ww
- è´£ä»»ï¼šå§”外加工业务（外协生产）。  
- ä¸»è¦æœåŠ¡ï¼š  
  - `Gs.Ww\WWBlManager.cs`、`WWBlDJManager.cs`：委外补料申请与单据。  
  - `WWLLDJManager.cs`、`WWTBlDJManager.cs`：委外领料、退料单据。  
  - `WWTblManager.cs`：委外退补料处理。  
  - `ProductionOrderManager.cs`、`WWPCManager.cs`：委外生产订单及排产控制。  
- ç‰¹ç‚¹ï¼šä¸Žä»“储共享领退料逻辑，与销售/采购模块共享供应商等基础资料。

### Gs.QiTaRk & Gs.QiTaCk
- **Gs.QiTaRk**：处理其他入库类业务。  
  - `MesItemQtrkManager.cs`、`MesItemQtrkDjManager.cs`：其他入库单据及明细。  
  - `MesItemTblManager.cs`、`MesItemTblRkManager.cs`：调整/补录入库。  
- **Gs.QiTaCk**：处理其他出库类业务。  
  - `MesItemQtManager.cs`、`MesItemQtDJManager.cs`：其他出库单据与明细。  
  - `MesItemBlManager.cs`、`MesItemBlDJManager.cs`：报溢/报损出库。  
  - `MesCgthSqManager.cs`、`MesCgthSqDjManager.cs`：采购退货申请。  
  - `MesSctkSqManager.cs`、`MesSctkSqDjManager.cs`：生产退库申请。  
- è¿™äº›æ¨¡å—为仓储提供补充业务口径，通常与会计系统或手工单据对接。

### Gs.Warehouse é™„属：`Gs.Warehouse\Dto\InitialBarcode.cs`
- ä¸ºæ¡ç ç”Ÿæˆã€åˆå§‹å¯¼å…¥æä¾› DTO，供 `MesInvItemBarcodesManager` ç­‰æœåŠ¡åºåˆ—化/反序列化。

### Gs.Pda
- è´£ä»»ï¼šä¸º PDA/手持终端提供轻量接口。  
  - `Gs.Pda\Service\PqcManager.cs`：生产巡检相关 PDA æ“ä½œã€‚  
  - `IqcManager.cs`：来料检验 PDA ç«¯ã€‚  
- ç‰¹ç‚¹ï¼šæŽ¥å£å‚数通常更精简，返回 PDA å‹å¥½çš„结构，复用主系统的权限校验。

### Gs.OpenApi
- è´£ä»»ï¼šå¯¹å¤–开放接口，与 ERP ç­‰å¤–部系统同步关键数据。  
  - `Gs.OpenApi\Services\ErpMesController.cs`：提供 ERP è°ƒç”¨å…¥å£ï¼Œæ‰§è¡Œç‰©æ–™ã€åº“存、订单等数据的推送/回传。  
- ç‰¹ç‚¹ï¼šå¯èƒ½éœ€è¦é¢å¤–的安全策略（如 IP ç™½åå•ã€ç­¾åï¼‰ï¼Œå¹¶å¯¹æŽ¥æ¶ˆæ¯é˜Ÿåˆ—或定时任务（可在拓展时加入）。

### è¾…助项目
- **Gs.JJGZ**（已说明）：与薪资、考勤相关。  
- **TemplateEngineHost**：提供模板渲染或报表生成辅助服务，常与 `Gs.Report` è”动。  
- **Gs.HostIIS\.config**：按环境拆分的发布配置，用于 Dev/Test/Prod å‚数覆盖。

## æ¨¡å—间典型流程示例
1. **销售发货**：`Gs.Sales\SalesDeliverManager` ä¾æ® `Gs.BaseInfo` çš„客户/物料数据生成发货单，同时调用 `Gs.Warehouse\MesInvItemOutsManager` æ‰£å‡åº“存。  
2. **生产上线与入库**：`Gs.Wom\WorkProController` è®°å½•å·¥åºæ•°æ®ï¼Œç”Ÿæˆæ¡ç åŽç”± `Gs.Warehouse\MesInvItemArnManager` å…¥åº“，并在 `GS.QC\IpqcXunManager` åšå·¡æ£€ã€‚  
3. **质量异常处理**：`GS.QC\MesQcExceptionalManager` è®°å½•å¼‚常，触发 `Gs.Warehouse\MesInvItemMovesManager` è¿›è¡Œä¸è‰¯å“è½¬åº“，最后在 `Gs.Report\ReportController` æä¾›ç»Ÿè®¡ã€‚  
4. **计薪数据采集**：`Gs.Wom\WorkCollectController` ä¸Šä¼ çš„工序完成量传给 `Gs.JJGZ\MesJjgzJjsalaryController` è®¡ç®—计件工资。  

## æ‰©å±•å¼€å‘建议
- å¼•å…¥æ–°æ¨¡å—时，创建 `Gs.NewModule` é¡¹ç›®ï¼Œéµå¾ª `Models/` + `Services/` ç»“构，并在类上应用 `ApiGroup` ä¸Ž DI æ ‡è®°æŽ¥å£ã€‚`builder.AddCustomInject()` ä¼šè‡ªåŠ¨æ³¨å†Œï¼Œå®žçŽ°é›¶é…ç½®æŽ¥å…¥ã€‚  
- è·¨æ¨¡å—调用时优先通过仓储或接口返回 DTO，避免直接访问其他模块数据库表；如需共享实体，请放入 `Gs.Entity`。  
- æŠ¥è¡¨å¯¼å‡ºç»Ÿä¸€å¤ç”¨ `Gs.Toolbox\ExcelHelper`，日志及 HTTP è°ƒç”¨å§”托 `LogHelper`、`InterfaceUtil`。  
- æ‰€æœ‰æŽ¥å£é»˜è®¤å¯ç”¨ `ApiAuthorizeAttribute`，新增匿名接口需显式加 `[AllowAnonymous]` å¹¶è¯„估安全风险。

以上内容可作为模块划分审阅、需求拆解和新成员培训的参考。如果需要进一步的数据库结构、存储过程说明，可在各控制器中搜索对应的 SQL/存储过程名称，与 DBA åä½œç»´æŠ¤è¡¥å……文档。*** End Patch

 WebApi/help.md

¶Ô±ÈÐÂÎļþ
@@ -0,0 +1,95 @@
# GS MES æœåŠ¡å¸®åŠ©æ–‡æ¡£

## 1. é¡¹ç›®æ€»ä½“概览
GS MES Service æ˜¯ä¸€å¥— MES（制造执行系统）后端接口，采用 ASP.NET Core 8.0 ä½œä¸ºå®¿ä¸»æ¡†æž¶ã€‚入口项目 `Gs.HostIIS` è´Ÿè´£æ³¨å†ŒæŽ§åˆ¶å™¨ã€åŠ è½½é…ç½®å’Œå¯ç”¨ Swagger，同时通过 `builder.AddCustomInject()` è‡ªåŠ¨å‘现并注册各模块中的业务服务。功能按领域拆分为 `Gs.BaseInfo`、`Gs.Sales`、`Gs.Warehouse`、`Gs.Report` ç­‰é¡¹ç›®ï¼Œæ¯ä¸ªæ¨¡å—通过 `Services/`（控制器）和 `Models/`（领域模型）向外暴露 API。

## 2. æ ¸å¿ƒæž¶æž„与运行机制
- **启动流程**：`Program.cs` å»ºç«‹ WebApplication，配置 JSON åºåˆ—化（全量 Unicode、Newtonsoft.Json）、全局授权过滤、CORS、Swagger åŠé™æ€æ–‡ä»¶ç›®å½•ï¼Œç„¶åŽè°ƒç”¨ `app.AddCustomController()` ä¸Ž `builder.AddCustomInject()` æ‰©å±•ã€‚
- **自动依赖注入**：`Gs.Toolbox.ApiCore.Extensions.ApplicationBuilderExtension` ä¼šæ‰«æå…¥å£ç¨‹åºé›†åŠå…¶å¼•ç”¨ï¼Œè¯†åˆ«å®žçŽ°äº† `ISingleton`、`IScope`、`ITransient` ç­‰æ ‡è®°æŽ¥å£æˆ–标注了 `ExposeAttribute` çš„类，并按约定注入容器。
- **控制器加载**：`CustomControllerFeatureProvider` ä¸Ž `CustomApplicationModelConvention` ç»“合 `ApiGroup` ç‰¹æ€§ï¼Œå®žçŽ°æŒ‰æ¨¡å—分组的路由与 Swagger æ–‡æ¡£åˆ’分。
- **授权机制**：`ApiAuthorizeAttribute` æ‹¦æˆªæ‰€æœ‰æœªæ ‡è®° `[AllowAnonymous]` çš„请求，检查请求头 `token` æ˜¯å¦åŒ…含形如 `token <guid>` çš„值（长度至少 5）。
- **静态资源**：根据配置项 `DownPath` ä¸Ž `UploadPath` æ˜ å°„ `/down`、`/upload` é™æ€ç›®å½•ï¼Œç”¨äºŽæ–‡ä»¶ä¸‹è½½ä¸Žä¸Šä¼ ã€‚

## 3. ä¸»è¦é¡¹ç›®ä¸Žæ–‡ä»¶å¤¹èŒè´£
- `GsMesSolution.sln`：解决方案根入口。
- `Gs.HostIIS/`：主机项目，包含配置文件、Swagger è®¾ç½®ã€è‡ªå®šä¹‰æŽˆæƒå±žæ€§ã€‚
- `Gs.<Module>/`：领域模块，示例：
  - `Gs.BaseInfo`：基础资料维护，`MesItemsManager` ç­‰æŽ§åˆ¶å™¨ç»§æ‰¿ `Repository<T>` å¹¶ä½¿ç”¨ SqlSugar æŸ¥è¯¢ã€‚
  - `Gs.Warehouse`：仓储相关接口。
  - `Gs.Report`：报表与导出功能。
- `Gs.Entity/`：集中存放 SqlSugar å®žä½“、枚举、DTO。
- `Gs.Toolbox/`：通用工具，包括配置读取（`AppSettingsHelper`）、仓储基类（`Repository<T>`）、Excel å¯¼å‡ºã€æ—¥å¿—、ApiCore æ‰©å±•ç­‰ã€‚
- `TemplateEngineHost/`：模版引擎集成（若需生成报表/文档）。
- `.config/`：部署阶段使用的环境配置转换文件。

## 4. å¼€å‘环境准备
1. å®‰è£… .NET SDK 8.0（`dotnet --version` éªŒè¯ï¼‰ã€‚
2. å‡†å¤‡æ•°æ®åº“访问账号，与 `ConnectionStrings` ä¸­çš„目标库一致；敏感字段通过 User Secrets æˆ–环境变量注入。
3. é…ç½® Git、PowerShell/Bash、SQL å®¢æˆ·ç«¯åŠå¸¸ç”¨è°ƒè¯•å·¥å…·ï¼ˆPostman、curl）。
4. è‹¥éœ€å‰ç«¯è”调，确认本地端口（默认在 `appsettings*.json` ä¸­è®¾ç½®ï¼‰åŠè·¨åŸŸç­–略（`AllowAnyOrigin`）。

## 5. æž„建、运行与调试
```bash
dotnet restore GsMesSolution.sln        # å®‰è£…所有 NuGet ä¾èµ–（SqlSugar、Swashbuckle ç­‰ï¼‰
dotnet build GsMesSolution.sln -c Release
dotnet run --project Gs.HostIIS/Gs.HostIIS.csproj
```
启动后访问 `http://localhost:<端口>/swagger`，可见按照 `ApiGroupNames` åˆ†ç»„的接口文档。调用需要授权的接口时，在请求头添加 `token: token 3fa85f64-5717-4562-b3fc-2c963f66afa6`（示例）。

### å¸¸è§è°ƒè¯•æŠ€å·§
- ä½¿ç”¨ `?trace=true` ç­‰çº¦å®šå‚数（若控制器支持）定位日志。
- å…³æ³¨æŽ§åˆ¶å°è¾“出的 SqlSugar SQL æ—¥å¿—（`Repository<T>` é€šè¿‡ `Db.Aop.OnLogExecuting` è¾“出格式化语句）。
- è‹¥éœ€è¦ä¸´æ—¶å…³é—­æŽˆæƒï¼Œå¯åœ¨æµ‹è¯•çŽ¯å¢ƒå¯¹ `ApiAuthorizeAttribute` åšæ¡ä»¶çŸ­è·¯æˆ–在控制器方法上加 `[AllowAnonymous]`（上线前务必移除）。

## 6. é…ç½®ç®¡ç†
- **基础配置**：`Gs.HostIIS/appsettings.json`、`appsettings.Development.json` å­˜å‚¨è·¯å¾„、Swagger åˆ†ç»„ XML è·¯å¾„等；`ServicesPath` ç”¨äºŽæ‰«æç”Ÿæˆçš„ XML æ³¨é‡Šã€‚
- **敏感信息**：使用 `dotnet user-secrets`（开发环境）或系统环境变量注入 `ConnectionStrings` ç­‰æ•æ„Ÿå­—段，切勿提交到版本库。
- **环境转换**：生产/测试环境配置放入 `Gs.HostIIS/.config/*.json`，通过发布流程或 CI/CD åœ¨éƒ¨ç½²é˜¶æ®µè¦†ç›–。
- **文件目录**：确认 `DownPath`、`UploadPath` å¯¹åº”的物理目录权限；服务启动会尝试自动创建缺失目录。

## 7. ä¸šåŠ¡æ¨¡å—开发模式
- æŽ§åˆ¶å™¨é€šå¸¸ç»§æ‰¿ `Repository<T>`，直接复用 SqlSugarScope（支持事务、通用分页 `CommonPage`）。
- é€šè¿‡ `ApiGroup(ApiGroupNames.XXX)` å£°æ˜Ž Swagger åˆ†ç»„；使用 `RequestMethod` ç‰¹æ€§æŒ‡å®š HTTP æ–¹æ³•ï¼ˆç³»ç»Ÿè‡ªå¸¦çš„ `RequestMethods` æžšä¸¾ï¼‰ã€‚
- ä¾èµ–注入：在构造函数中声明所需服务（如 `IHttpContextAccessor`、仓储接口），并确保实现类实现对应生命周期接口以被自动注入。
- ç”¨æˆ·èº«ä»½ï¼šä½¿ç”¨ `UtilityHelper.GetUserGuidAndOrgGuid()` ä»Žè¯·æ±‚上下文提取用户标识，常用于数据隔离。
- å“åº”格式：封装在 `ResponseResult`、`ReturnDto<T>` ç­‰ç»Ÿä¸€è¿”回对象中，保持前端体验一致。

## 8. æ•°æ®è®¿é—®ä¸ŽåŸºç¡€å·¥å…·
- **SqlSugar ä»“储**：`Repository<T>` é»˜è®¤è¿žæŽ¥ `AppSettingsHelper.getValueByKey("ConnectionStrings")`，支持 `UseTransaction` åŒ…装事务块、`CommonPage` å¿«é€Ÿåˆ†é¡µã€‚
- **Excel å¯¼å‡º**：`ExcelHelper` æä¾›å¯¼å‡ºåŠŸèƒ½ï¼Œé€šå¸¸åœ¨æŠ¥è¡¨æ¨¡å—使用。
- **HTTP è¾…助**：`InterfaceUtil`、`UtilityHelper` ç­‰å°è£…跨系统调用、用户上下文解析。
- **日志**：`LogHelper` å°è£…常规日志记录；需要时可扩展现有实现接入集中式日志平台。

## 9. å®‰å…¨ä¸ŽæŽˆæƒ
- æ‰€æœ‰æŽ¥å£é»˜è®¤ç»è¿‡ `ApiAuthorizeAttribute` æ ¡éªŒ `token`。生产环境应替换长度校验逻辑为真实身份认证（JWT、单点登录等）。
- Swagger UI æš´éœ²åœ¨ `/swagger`，上线前需确认是否限制外网访问或启用认证。
- è¯·å‹¿åœ¨ä»“库中存储真实密钥、数据库账号或生产配置；`.config` ç›®å½•ä»…存放模板/转换文件。
- æ•°æ®æƒé™ï¼šæ¨¡å—内可根据 `_orgFids`、`_userGuid` ç­‰å­—段控制查询范围。

## 10. æµ‹è¯•ä¸Žè´¨é‡ä¿è¯
- å»ºè®®ä¸ºæ¯ä¸ªé¢†åŸŸæ¨¡å—创建对应的 xUnit æµ‹è¯•é¡¹ç›®ï¼ˆå¦‚ `Gs.BaseInfo.Tests`），测试文件命名统一为 `*Tests.cs`。
- æµ‹è¯•ä¸­é€šè¿‡æ¨¡æ‹Ÿä»“储或 SqlSugar å®¢æˆ·ç«¯ï¼Œé¿å…ä¾èµ–真实数据库；可利用 `ISqlSugarClient` æŽ¥å£å®žçŽ°è‡ªå®šä¹‰ Fake。
- æ‰§è¡Œæµ‹è¯•ï¼š`dotnet test`（在解决方案根目录），并将结果写入 PR æè¿°ã€‚
- åœ¨è‡ªåŠ¨åŒ–覆盖完善之前，需在 PR ä¸­è®°å½•æ‰‹å·¥å†’烟步骤（Swagger åŠ è½½ã€æ ¸å¿ƒæŽ¥å£ã€å…³é”®å­˜å‚¨è¿‡ç¨‹æ‰§è¡Œæƒ…况）。

## 11. å¸¸è§é—®é¢˜æŽ’查
- **Swagger æ–‡æ¡£ç¼ºå¤±**：确认 `ServicesPath` æŒ‡å‘的目录存在 XML æ–‡ä»¶ï¼Œå¯é‡æ–°æ‰§è¡Œ `dotnet build` ç”Ÿæˆæ³¨é‡Šæ–‡ä»¶ã€‚
- **静态文件 404**：核查物理目录路径是否正确，或日志中是否提示访问权限问题。
- **token è¢«æ‹’绝**：检查请求头格式是否为 `token: token <值>`；如需调试，可在本地将最小长度改为 0。
- **SqlSugar è¿žæŽ¥å¤±è´¥**：确保环境变量中配置正确连接字符串，并验证数据库服务器可达。
- **依赖注入找不到实现**：确认实现类引用了标记接口或 `ExposeAttribute`，且所在程序集已被 `Gs.HostIIS` å¼•ç”¨ã€‚
- **跨域请求失败**：默认策略允许所有来源；如仍报错，检查浏览器请求头或是否有代理层拦截。

## 12. è´¡çŒ®ä¸Žåä½œæµç¨‹
1. ä»Žæœ€æ–°ä¸»å¹²åˆ›å»ºåŠŸèƒ½åˆ†æ”¯ï¼Œä¿æŒæœ¬åœ°çŽ¯å¢ƒä¸Žè¿œç«¯åŒæ­¥ã€‚
2. æŒ‰è§„范编写代码：四空格缩进、`PascalCase` ç±»åž‹ã€`camelCase` å˜é‡ã€å¼€å¯å¯ç©ºå¼•ç”¨ã€‚
3. æ–°å¢žæˆ–修改模块时，同步更新文档（README、help、模块说明）以及 `.config` è½¬æ¢æ–‡ä»¶ï¼ˆå¦‚有配置变更）。
4. æœ¬åœ°æ‰§è¡Œ `dotnet build`、`dotnet test`（若存在测试），并完成关键 API çš„手工冒烟。
5. ä½¿ç”¨ç®€æ´ä¸­æ–‡å•è¡Œä½œä¸ºæäº¤è¯´æ˜Žï¼ˆç¤ºä¾‹ï¼š`BaseInfo: è°ƒæ•´ç‰©æ–™åˆ†é¡µæŸ¥è¯¢`）。
6. æäº¤ PR æ—¶åˆ—出受影响模块、配置/数据库变更、自动化测试结果、手工验证结果及必要的请求/响应示例或截图。

## 13. å‚考资料
- SqlSugar å®˜æ–¹æ–‡æ¡£ï¼šhttps://www.donet5.com/Home/Doc
- ASP.NET Core å®˜æ–¹æ–‡æ¡£ï¼šhttps://learn.microsoft.com/aspnet/core
- Swashbuckle.AspNetCore æ–‡æ¡£ï¼šhttps://github.com/domaindrivendev/Swashbuckle.AspNetCore
- .NET ç”¨æˆ·å¯†é’¥ç®¡ç†ï¼šhttps://learn.microsoft.com/aspnet/core/security/app-secrets