CLAUDE.md

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

Project Overview

LB_PdaService (蓝宝PDA后台) is a .NET 8 Web API service for PDA (Personal Digital Assistant) backend operations in a MES (Manufacturing Execution System). The service provides REST APIs for warehouse management, production order management, quality control, and ERP integration.

Quick Start Commands

# Restore dependencies
dotnet restore

# Build the project
dotnet build NewPdaSqlServer.csproj -c Debug

# Run in development (watches appsettings.Development.json)
dotnet run --project NewPdaSqlServer.csproj --launch-profile Development

# Format code before committing
dotnet format

# Publish for production
dotnet publish -c Release -o bin/Publish/net8.0

Development server runs on https://localhost:5001 with Swagger at /swagger.

Architecture Overview

Request Flow & Data Access

The application follows a layered architecture with direct SQL access (no ORM):

HTTP Request → Controllers/ → service/ → DbHelperSQL → SQL Server
                   ↓
              RequestInfo (scoped)

Key insights:
- RequestInfo is injected via BaseController as a scoped service in DI (see Startup.cs:33). All controllers inherit from BaseController to access request context.
- RequestInfo is a DynamicObject that extracts HTTP headers (like OrgId) and stores them as dynamic properties for use throughout the request lifecycle.
- DbHelperSQL is a static utility class in util/ that wraps ADO.NET for direct SQL Server access via System.Data.SqlClient.

Folder Organization

• Controllers/: HTTP endpoints organized by domain (Warehouse, QC, Wom, JJGZ, Kingdee, AGV)
• BaseController.cs: Provides scoped RequestInfo access to all controllers
• base/: Shared endpoints like WmsBaseController.cs

• service/: Business logic following manager pattern

• Names match controller structure: MesWarehouseManager, MesQcManager, etc.
• Encapsulates SQL queries and business rules
• Base services in service/base/ (e.g., LoginService.cs, MesDepotsManager.cs)

• entity/: Data models organized by domain

• Base/: Shared entities like RequestInfo
• Database entities for mapping (not full ORM)

• Dto/: Request/response transfer objects

• Mirror service structure

• util/: Core utilities

• DbHelperSQL.cs: Static helper for SQL execution with parameterized queries, transactions, and stored procedure calls
• ResponseResult.cs: Unified response wrapper (status: 0=success, 1=error)
• AppsettingsUtility.cs: Configuration initialization
• AppSettings.cs: Configuration container
• BillNo.cs: Sequential number generation
• LogUtil.cs: Logging helper
• UserUtil.cs, StringUtil.cs, CollectionUtil.cs: Common utilities

Data Access Pattern

Direct ADO.NET via DbHelperSQL static methods:
- Query execution: DbHelperSQL.Query(sql) returns DataSet
- Scalar: DbHelperSQL.GetSingle(sql) returns object
- Execute: DbHelperSQL.ExecuteSql(sql) returns affected rows
- Transactions: DbHelperSQL.ExecuteSqlTran(Hashtable) for multi-statement ACID operations
- Stored procedures: DbHelperSQL.RunProcedure() and variants

All methods support parameterized queries via SqlParameter[] to prevent SQL injection.

Configuration & Dependencies

• Startup.cs: Configures services, middleware, Swagger, CORS, JSON serialization
• RequestInfo injected as scoped service (line 33)
• HttpContextAccessor registered to enable RequestInfo header extraction
• Newtonsoft.Json configured for camelCase output
• DateTime format: "yyyy-MM-dd HH:mm:ss"
• CORS allows any origin and common HTTP methods (GET, POST, PUT, DELETE, HEAD, OPTIONS)

• appsettings.json / appsettings.Development.json:

• AppSettings:DataBaseConn: SQL Server connection string (accessed by DbHelperSQL)
• AppSettings:TestErpUrl and AppSettings:ProductionErpUrl: ERP WebService endpoints
• Use dotnet user-secrets in development to avoid committing sensitive connection strings

• Program.cs: Standard .NET 8 entry point using Host.CreateDefaultBuilder() with Startup class

• Key NuGet Dependencies (from NewPdaSqlServer.csproj):

• SqlSugarCore 5.1.4.169: Referenced but not actively used; DbHelperSQL handles data access
• System.Data.SqlClient 4.8.6: ADO.NET provider for SQL Server
• Microsoft.AspNetCore.Mvc.NewtonsoftJson 8.0.8: JSON serialization
• Swashbuckle.AspNetCore 6.8.0: Swagger/OpenAPI documentation
• Masuit.Tools.Core 2024.5.8: Utility library
• Portable.BouncyCastle 1.9.0: Cryptography support

Development Patterns

Adding a New API Endpoint

1. Create controller in Controllers/[Domain]/[Entity]Controller.cs

• Inherit from BaseController
• Access request context via RequestInfo property

1. Create manager in service/Mes[Entity]Manager.cs

• Define CRUD/business methods
• Use DbHelperSQL.Query() or DbHelperSQL.ExecuteSql() for data access

1. Use ResponseResult for all responses:
   csharp return new ResponseResult { status = 0, data = result };

2. Return Task<ResponseResult> for async endpoints

Database Queries

Always use parameterized queries to prevent SQL injection:

var param = new[] {
    new SqlParameter("@id", id),
    new SqlParameter("@name", name)
};
var ds = DbHelperSQL.Query("SELECT * FROM Table WHERE id=@id AND name=@name", param);

Error Handling

Use ResponseResult.ResponseError(exception) for exception wrapping:

catch (Exception ex)
{
    return ResponseResult.ResponseError(ex);
}

Coding Standards (from AGENTS.md)

• Naming: PascalCase for types, camelCase for locals/parameters; append Controller to controller classes
• Async: Methods returning Task/Task<T> must end with Async suffix; never use async void except event hooks
• Format: Run dotnet format before committing
• Commits: Use imperative subjects like "Warehouse: validate transfer-out request" with module summary in body

Testing

No automated test framework currently wired into the solution. To add testing:
1. Create Tests/ directory and add xUnit project
2. Name test files <Feature>Tests.cs with methods named Method_Scenario_ExpectedResult
3. Run with dotnet test
4. Reference tests in PR descriptions with coverage notes

Domain-Specific Controllers

Controllers are organized into these business domains:

• Warehouse/ (库存管理): Stock queries, in/out operations, transfers, barcode tracking
• Examples: MesInvItemInCDetailsController, MesDbckController, TransferOutController
• QC/ (质检): IPQC, inspection records, quality control workflows
• Examples: IpqcController, LljController, OaToMesController
• Wom/ (工单管理): Work orders, production reporting, process progress
• Examples: MesWorkProdController, WomdaaController, WwGdController
• base/: Shared base functionality across domains
• Examples: WmsBaseController, MesDepotsController, MessageCenterController
• Kingdee/: ERP integration endpoints (金蝶)
• JJGZ/: OA-to-MES integration (金蝶工作流)

Known Technical Debt

• Custom SQL data access layer (DbHelperSQL) instead of modern ORM—SqlSugarCore is referenced but not actively used
• No automated tests (see Testing section)
• CORS policy allows any origin—tighten for production
• Secrets stored in appsettings.json (use dotnet user-secrets instead)