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 (计件工资)

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 (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 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