CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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

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: Miscellaneous in/out operations (其它出库/其它入库)
Gs.Ww: Outsourcing management (委外)
Gs.JJGZ: Piece-rate wage management (计件工资)
Gs.OpenApi: External API integration and open interfaces

Development Commands

Build and Run

# 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

API runs on http://localhost:5263 (default Project profile) or http://localhost:37005 (IIS Express)
Ports configured in Gs.HostIIS/Properties/launchSettings.json
Swagger UI: http://localhost:5263/swagger (always enabled, not just in Development)
CORS configured to allow all origins via "AllowAll" policy

Testing

No automated tests currently exist in the solution
Manual testing via Swagger UI at /swagger endpoint
Test ERP integration endpoints configured in appsettings.json (TestErpUrl, TestErpUrl2)

Architecture Details

Custom API Framework

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

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

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

Response Format

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 }

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

Create new class library project targeting .NET 8.0
Reference required projects:
xml <ProjectReference Include="..\Gs.Entity\Gs.Entity.csproj" /> <ProjectReference Include="..\Gs.Toolbox\Gs.Toolbox.csproj" />
Configure output path in .csproj:
xml <BaseOutputPath>..\Gs.HostIIS\bin</BaseOutputPath> <OutputPath>..\Gs.HostIIS\bin\Debug\</OutputPath> <GenerateDocumentationFile>True</GenerateDocumentationFile>
Create Services folder for controller classes
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) { ... } }
Add to solution and build (DLL auto-discovered at runtime)

Common Patterns

Creating API Endpoints

[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

var affectedRows = UseTransaction(db => {
    db.Insertable(entity).ExecuteCommand();
    db.Updateable(otherEntity).ExecuteCommand();
    return db.Ado.AffectedRows;
});

Development Notes

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