11

tjx

2025-10-17 8d0da03dcfde27e5316a09f9b639dca31aa385a5

11

 CLAUDE.md

@@ -4,75 +4,183 @@

## Project Overview

LB_PdaService (蓝宝PDA后台) is a .NET 8 Web API service designed 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.
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.

## Build and Run Commands
## Quick Start Commands

```bash
# Build the project
dotnet build
# Restore dependencies
dotnet restore

# Run the project in development
dotnet run
# 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
dotnet publish -c Release -o bin/Publish/net8.0
```

The application runs on ASP.NET Core 8.0 and exposes Swagger documentation at `/swagger` in development mode.
Development server runs on `https://localhost:5001` with Swagger at `/swagger`.

## Architecture and Code Structure
## Architecture Overview

### Core Components
### Request Flow & Data Access

- **Controllers/**: REST API endpoints organized by functional domains
  - `BaseController.cs`: Base class providing RequestInfo injection for all controllers
  - Domain-specific folders: `Warehouse/`, `QC/`, `Wom/`, `JJGZ/`, `Kingdee/`
  - `LoginController.cs` and `AuthController.cs`: Authentication endpoints
The application follows a layered architecture with direct SQL access (no ORM):

- **service/**: Business logic managers following a manager pattern
  - Organized by functional domains matching controller structure
  - Each manager handles specific entity operations and business rules
  - Names follow pattern `Mes[Entity]Manager.cs`
```
HTTP Request → Controllers/ → service/ → DbHelperSQL → SQL Server
                   ↓
              RequestInfo (scoped)
```

- **entity/**: Data models and DTOs
  - Domain entities for database mapping
  - Extensive collection of MES-related entities (inventory, production, quality control)
  - `Base/`: Shared base entities like `RequestInfo`
**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`.

- **util/**: Utility classes and helpers
  - `DbHelperSQL.cs`: Database access abstraction layer
  - `AppsettingsUtility.cs`: Configuration management
  - Various helpers for logging, string operations, and API communication
### 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

The application uses a custom database access layer (`DbHelperSQL`) rather than Entity Framework. Database connections are managed through the `AppSettings.DataBaseConn` configuration value.
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

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

- `appsettings.json`: Contains database connection strings and ERP service URLs
- Configuration is injected through `AppsettingsUtility` and accessed via `AppSettings` class
- Database connection string format: SQL Server with encryption enabled
### Configuration & Dependencies

### Key Architectural Patterns
- **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)

1. **Manager Pattern**: Business logic is encapsulated in manager classes in the `service/` directory
2. **Base Controller Pattern**: Common functionality shared through `BaseController`
3. **Custom Data Access**: Direct SQL execution through `DbHelperSQL` utility
4. **Configuration Injection**: Settings injected through custom utility class
5. **Domain Separation**: Code organized by business domains (Warehouse, Production, QC, etc.)
- **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

### Integration Points
- **Program.cs**: Standard .NET 8 entry point using `Host.CreateDefaultBuilder()` with `Startup` class

- **ERP Integration**: Service communicates with external ERP systems via configured URLs
- **Database**: SQL Server database with MES schema
- **CORS**: Configured to allow cross-origin requests for API consumers
- **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 Notes
## Development Patterns

- The codebase uses Chinese comments and naming conventions
- Swagger is enabled in development for API documentation
- JSON responses use camelCase naming convention
- DateTime format: "yyyy-MM-dd HH:mm:ss"
- No built-in test framework detected in the project structure
### 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)