From 75ff22c91d7710573231ba3ed75259f3d1477cc8 Mon Sep 17 00:00:00 2001
From: tjx <t2856754968@163.com>
Date: 星期六, 11 十月 2025 16:15:48 +0800
Subject: [PATCH] 发送接口的底层调整

---
 WebApi/CLAUDE.md |  215 +++++++++++++++++++++++++++++++++++++++--------------
 1 files changed, 156 insertions(+), 59 deletions(-)

diff --git a/WebApi/CLAUDE.md b/WebApi/CLAUDE.md
index 15fb77b..ecac9ef 100644
--- a/WebApi/CLAUDE.md
+++ b/WebApi/CLAUDE.md
@@ -4,92 +4,189 @@
 
 ## Project Overview
 
-This is a .NET 8 MES (Manufacturing Execution System) solution built with ASP.NET Core Web API. The system is organized as a modular monolith with domain-separated projects for different business areas.
+This is a .NET 8 MES (Manufacturing Execution System) solution built with ASP.NET Core Web API. The system uses a custom API framework with modular architecture, organizing business functionality into domain-separated projects.
 
 ## Solution Structure
 
-The solution follows a modular architecture with these main projects:
-
-- **Gs.HostIIS**: Main Web API host application with Swagger documentation
-- **Gs.Entity**: Data entities organized by business domains (BaseInfo, QC, Sys, Warehouse)
-- **Gs.Toolbox**: Core utilities, API framework, and dependency injection infrastructure
-- **Business Modules**:
-  - **Gs.BaseInfo**: Basic information management (items, customers, suppliers, staff, etc.)
-  - **Gs.Warehouse**: Inventory and warehouse management
-  - **GS.QC**: Quality control functionality
+- **Gs.HostIIS**: Main Web API host application (targets .NET 8.0)
+- **Gs.Toolbox**: Core framework with custom DI, controller discovery, and utilities (targets .NET 6.0)
+- **Gs.Entity**: Data entity models organized by domain (BaseInfo, QC, Sys, Warehouse)
+- **Business Modules** (all target .NET 8.0):
+  - **Gs.BaseInfo**: Basic information (items, customers, suppliers, staff, departments)
+  - **Gs.Warehouse**: Inventory and warehouse operations
+  - **GS.QC**: Quality control and inspection
   - **Gs.Sys**: System administration and user management
   - **Gs.Report**: Reporting functionality
   - **Gs.Wom**: Work order management
   - **Gs.Sales**: Sales management
   - **Gs.Pda**: Mobile/handheld device support
-  - **Gs.QiTaCk** / **Gs.QiTaRk**: Additional business modules (鍏跺畠鍑哄簱/鍏跺畠鍏ュ簱)
+  - **Gs.QiTaCk** / **Gs.QiTaRk**: Miscellaneous in/out operations (鍏跺畠鍑哄簱/鍏跺畠鍏ュ簱)
   - **Gs.Ww**: Outsourcing management (濮斿)
   - **Gs.JJGZ**: Piece-rate wage management (璁′欢宸ヨ祫)
 
 ## Development Commands
 
 ### Build and Run
-- Build entire solution: `dotnet build GsMesSolution.sln`
-- Run main API: `dotnet run --project Gs.HostIIS`
-- Build specific project: `dotnet build Gs.ProjectName/Gs.ProjectName.csproj`
+```bash
+# Build entire solution
+dotnet build GsMesSolution.sln
+
+# Run main API (starts on http://localhost:5263 by default)
+dotnet run --project Gs.HostIIS
+
+# Build specific module
+dotnet build Gs.BaseInfo/Gs.BaseInfo.csproj
+```
 
 ### Development Server
-- The API runs on default ports (check launchSettings.json for specific ports)
-- Swagger UI is available at `/swagger` endpoint
-- CORS is configured to allow all origins for development
+- API runs on `http://localhost:5263` (Project profile) or `http://localhost:37005` (IIS Express)
+- Swagger UI: `http://localhost:5263/swagger`
+- CORS configured to allow all origins in development
 
 ## Architecture Details
 
 ### Custom API Framework
-The solution uses a custom API framework built in `Gs.Toolbox`:
-- Custom dependency injection with lifecycle attributes (`ITransient`, `IScope`, `ISingleton`)
-- Custom controller convention via `CustomApplicationModelConvention`
-- API grouping for Swagger documentation via `ApiGroupAttribute`
-- Custom authorization with `ApiAuthorizeAttribute`
+
+The solution uses a custom framework in `Gs.Toolbox` that replaces standard ASP.NET Core conventions:
+
+#### Controller Discovery
+- Controllers are discovered by implementing the `IRomteService` interface (not by inheriting `ControllerBase`)
+- `CustomControllerFeatureProvider` scans assemblies and the `Services` folder for classes implementing `IRomteService`
+- Controllers are automatically registered without `[ApiController]` or `[Route]` attributes
+- Business logic classes in `Services/` folders act as controllers
+
+#### Routing Convention
+- Routes automatically generated as `/{ControllerName}/{ActionName}` by `CustomApplicationModelConvention`
+- HTTP methods specified via `[RequestMethod(RequestMethods.POST)]` attribute (not standard `[HttpPost]`)
+- Parameter binding: non-primitive types automatically bound from request body for POST/PUT/PATCH
+
+#### Dependency Injection
+- Custom DI system using lifecycle marker interfaces:
+  - `ITransient`: Transient lifetime (new instance per request)
+  - `IScope`: Scoped lifetime (one instance per request)
+  - `ISingleton`: Singleton lifetime (one instance for application)
+- Classes implementing these interfaces are auto-registered
+- Use `[Expose(typeof(IYourInterface))]` attribute to specify service interface explicitly
+- Auto-injection scans all referenced assemblies via `builder.AddCustomInject()`
+
+#### API Grouping
+- Swagger groups defined via `[ApiGroup(ApiGroupNames.BaseInfo)]` attribute on controller classes
+- Groups defined in `ApiGroupNames` enum (BaseInfo, QC, PerMission, WOM, ErpMes, etc.)
+- Each group generates separate Swagger document for organization
 
 ### Data Access
-- Uses SqlSugar ORM for database operations
-- Connection string configured in `appsettings.json`
-- Repository pattern implemented in `Gs.Toolbox/Repository.cs`
 
-### Configuration
-- Database: SQL Server (connection string in appsettings.json)
-- External services: ERP integration endpoints configured
-- File paths: Services, logs, upload, and download paths configured
-- Custom JSON serialization with Newtonsoft.Json
+#### SqlSugar ORM
+- Base repository: `Repository<T>` in `Gs.Toolbox/Repository.cs`
+- Connection string: `appsettings.json` 鈫� `ConnectionStrings` key
+- Static `SqlSugarScope Db` instance provides database context
+- Business classes inherit from `Repository<TEntity>` for data access
+- Transaction support via `UseTransaction()` method
 
-### Key Components
-- **CustomContractResolver**: Custom JSON property naming (converts to camelCase)
-- **ReturnDto<T>**: Standardized API response format with RtnCode, RtnData, RtnMsg
-- **PageList<T>** and **PageQuery**: Pagination support
-- **ExcelHelper**: Excel import/export functionality
-- **LogHelper**: Logging utilities
-- **DbHelperSQL**: Additional database utilities
+#### Pagination
+- Standard pagination using `PageQuery` (input) and `PageList<T>` (output)
+- `PageQuery` fields: `currentPage`, `everyPageSize`, `sortName`, `sortOrder`, `keyWord`, `keyWhere`, `keyType`
+- `CommonPage()` methods provide built-in pagination logic
 
-### Framework Features
-- Custom controller discovery via `CustomControllerFeatureProvider`
-- Module system with `IModule` interface for extensibility
-- Dependency injection container with custom lifecycle management
-- API grouping system for organized Swagger documentation
+### Response Format
 
-## Business Domains
+All API responses use `ReturnDto<T>` wrapper:
+```csharp
+{
+  "rtnCode": 1,        // ReturnCode enum: Success=1, Default=-100, Unauthorized=-101, Exception=-102
+  "rtnData": {...},    // Generic data payload
+  "rtnMsg": "..."      // Optional message
+}
+```
 
-The system handles typical MES functionality organized by API groups:
-- Base information (BaseInfo): Items, customers, suppliers, departments, staff
-- Quality control (QC): Inspection projects and quality management
-- Warehouse (PerMission): Inventory and warehouse operations
-- Work orders (WOM): Manufacturing execution
-- ERP integration (ErpMes): Data exchange with ERP systems
-- Reporting (Report/Rport): Various business reports
-- Mobile support (PDA): Handheld device operations
-- Additional modules: Sales (XS), Outsourcing (WW), etc.
+### JSON Serialization
+- Uses Newtonsoft.Json with custom `CustomContractResolver`
+- Property naming: Converts to camelCase (first letter lowercase)
+- Handles underscore-separated names (e.g., `USER_NAME` 鈫� `userName`)
+- Date format: `"yyyy-MM-dd HH:mm:ss"`
+- Reference loop handling: Ignore
+
+### Authorization
+- Custom `ApiAuthorizeAttribute` filter validates `token` header
+- Token format: `"token {guid}"` in request header
+- Use `[AllowAnonymous]` to bypass authorization
+- User context extraction via `UtilityHelper.GetUserGuidAndOrgGuid(IHttpContextAccessor)`
+
+### Configuration (appsettings.json)
+- `ConnectionStrings`: SQL Server connection string
+- `TestErpUrl`, `TestErpUrl2`, `ProductionErpUrl`: ERP integration endpoints
+- `ServicesPath`: Path to compiled DLLs for controller discovery (default: "Services")
+- `LogPath`: Log file directory (default: "logs")
+- `UploadPath`: File upload directory (mapped to `/upload` endpoint)
+- `DownPath`: File download directory (mapped to `/down` endpoint)
+
+### Project Output Configuration
+Business modules use custom output paths:
+- Compiled DLLs output to `Gs.HostIIS/bin/Debug/` (BaseOutputPath configured in .csproj)
+- XML documentation files generated automatically for Swagger
+- Framework scans `Services/` folder at runtime for controller DLLs
+
+## Creating New Business Modules
+
+1. **Create new class library project** targeting .NET 8.0
+2. **Reference required projects**:
+   ```xml
+   <ProjectReference Include="..\Gs.Entity\Gs.Entity.csproj" />
+   <ProjectReference Include="..\Gs.Toolbox\Gs.Toolbox.csproj" />
+   ```
+3. **Configure output path** in .csproj:
+   ```xml
+   <BaseOutputPath>..\Gs.HostIIS\bin</BaseOutputPath>
+   <OutputPath>..\Gs.HostIIS\bin\Debug\</OutputPath>
+   <GenerateDocumentationFile>True</GenerateDocumentationFile>
+   ```
+4. **Create Services folder** for controller classes
+5. **Implement controller** by inheriting `Repository<TEntity>` and `IRomteService`:
+   ```csharp
+   [ApiGroup(ApiGroupNames.YourGroup)]
+   public class YourManager : Repository<YourEntity>, IRomteService
+   {
+       [RequestMethod(RequestMethods.POST)]
+       public ReturnDto<PageList<YourEntity>> GetListPage(PageQuery query) { ... }
+   }
+   ```
+6. **Add to solution** and build (DLL auto-discovered at runtime)
+
+## Common Patterns
+
+### Creating API Endpoints
+```csharp
+[ApiGroup(ApiGroupNames.BaseInfo)]
+public class MesItemsManager : Repository<MesItems>, IRomteService
+{
+    private readonly IHttpContextAccessor _http;
+
+    public MesItemsManager(IHttpContextAccessor httpContextAccessor)
+    {
+        _http = httpContextAccessor;
+    }
+
+    [RequestMethod(RequestMethods.POST)]
+    public ReturnDto<PageList<MesItems>> GetListPage(PageQuery query)
+    {
+        // Business logic using Db property from Repository<T>
+    }
+}
+```
+
+### Using Transactions
+```csharp
+var affectedRows = UseTransaction(db => {
+    db.Insertable(entity).ExecuteCommand();
+    db.Updateable(otherEntity).ExecuteCommand();
+    return db.Ado.AffectedRows;
+});
+```
 
 ## Development Notes
 
-- All projects target .NET 8.0 (except Gs.Toolbox which targets .NET 6.0)
-- Nullable reference types are enabled
-- The system uses a Chinese interface (comments and some naming in Chinese)
-- Custom API framework provides dependency injection and controller conventions
-- Swagger documentation is automatically generated with XML comments from Services folder
-- Response format follows ReturnDto pattern with standardized error codes
-- File upload/download paths are configured and served as static files
\ No newline at end of file
+- The system uses Chinese for business domain comments and naming
+- Gs.Toolbox targets .NET 6.0 for compatibility; all other projects target .NET 8.0
+- Controllers are discovered at runtime from `Services/` folder - no need to manually register
+- Swagger automatically includes all controllers with their XML documentation
+- Static files (uploads/downloads) served from paths configured in appsettings.json
\ No newline at end of file

--
Gitblit v1.9.3