# 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

```bash
# 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

2. Create manager in `service/Mes[Entity]Manager.cs`
   - Define CRUD/business methods
   - Use `DbHelperSQL.Query()` or `DbHelperSQL.ExecuteSql()` for data access

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

4. Return `Task<ResponseResult>` for async endpoints

### Database Queries

Always use parameterized queries to prevent SQL injection:

```csharp
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:

```csharp
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)