dpz.core — Agent Guide

Project structure

• .NET 10 monorepo, ~30 projects under src/
• Solution file: src/Dpz.Core.slnx (modern .slnx format — pass it explicitly to dotnet)
• src/ is the working root for all dotnet/tool commands (see CSharpier note below)
• Sensitive secrets live in PRIVATE.md at the repo root — it is tracked by git, so never commit changes to it, never echo its contents
• Test project Dzp.Core.XunitBasic and shard impl Dzp.Core.Shard.Implement.Service have intentional typos ("Dzp" not "Dpz") — do not rename them

Quick commands

# Build (run from src/ or pass full path)
dotnet build ./Dpz.Core.slnx        # from src/
dotnet build src/Dpz.Core.slnx      # from repo root

# Test all / single project
dotnet test src/Dpz.Core.slnx
dotnet test src/Dpz.Core.Backup.Test/Dpz.Core.Backup.Test.csproj

# Format C# — tool manifest is at src/dotnet-tools.json (NOT standard .config/)
# These MUST be run from src/, not the repo root
dotnet tool restore     # in src/
dotnet csharpier .      # in src/  (config: src/.csharpierrc.yaml, csharpier 1.3.0)

# Frontend dev — run from src/Dpz.Core.Web/
.\build.ps1 init      # one-time: npm install + verify config + smoke-test prod build
.\build.ps1 dev       # watch mode — alias for npm run dev:app
.\build.ps1 build     # production bundle (CSS + JS + hash + manifest)
# clean-css-cli is a local devDependency (resolved from node_modules/.bin); no global install required

# Frontend lint/format (run from src/Dpz.Core.Web/ after `npm install`)
npm run lint
npm run format
npm run format:check

Architecture essentials

Entrypoints: Dpz.Core.Web/Program.cs, Dpz.Core.WebApi/Program.cs, Dpz.Core.Auth/Program.cs, Dpz.Core.Web.Jobs/Program.cs. Local dotnet run uses each project's launchSettings.json (NOT the container ports above). All apps call AddBusinessServices(configuration) + app-specific AddInject()/AddProjectServices()/etc.

An older instruction file exists at src/.github/copilot-instructions.md — prefer this file when they conflict.

Microsoft / OpenIddict package versions are centralized in src/Directory.Build.props — bump versions there, not per-csproj.

Coding conventions

• Indent: 4 spaces. Max line: 100 chars.
• File-scoped namespaces: namespace X.Y;
• Private fields: _camelCase prefix
• Braces always required (even single-line if/for/etc.)
• No trailing inline comments (var x = 1; // bad) — convention is review-only, no Roslyn analyzer enforces it
• No public fields — use properties
• Primary constructors when only one constructor
• Method names must not use the Ensure prefix — use more descriptive names that convey the method's purpose
• Async methods must end in Async, always accept CancellationToken cancellationToken = default
• Structured logging only — no string interpolation in Serilog calls
• Return empty collections, never null, for arrays/lists (byte[]? is ok)
• Parameters: as abstract as possible. Returns: as concrete as possible.
• Uses C# 14 extension method syntax (not traditional this parameter)
• Service public methods (and interface signatures) must never return entity types directly. Entities live in Dpz.Core.Public.Entity and are used only inside repositories/services; the public API of a service must return DTO / ViewModel / Response types from Dpz.Core.Public.ViewModel (e.g. VmVideo, MusicResponse, CommentViewModel). This isolates the persistence model from callers.
• Object mapping uses Mapster (IMapper / TypeAdapterConfig), not AutoMapper. Runtime type mapping must use the injected IMapper; do not call static Adapt<T>()/Adapt(...), because it bypasses DI-registered custom mappings.

Service DI registration (source-generator driven)

Dpz.Core.Service/ServiceDependencyInjection.cs exposes AddDefaultServices(), which calls AddGeneratedRepositoryServices() — a method generated at compile time by the Dpz.Core.SourceGenerator project. Do NOT hand-register domain services (no services.AddScoped<IFooService, FooService>() for interfaces in Dpz.Core.Service.RepositoryService).

The source generator:

• Scans all interfaces in Dpz.Core.Service.RepositoryService namespace
• Finds matching implementations in Dpz.Core.Service.RepositoryServiceImpl (convention-based: IFooService → FooService)
• Generates GeneratedServiceRegistration.g.cs with all AddScoped/AddSingleton/AddTransient/AddHttpClient calls
• Namespace pair is hardcoded in ServiceRegistrationProvider.cs:12-13 — not config-driven

Customize registration per service via attributes (from Dpz.Core.SourceGenerator.Attributes):

• [DependencyInjection(ServiceLifetime.Transient)] — change from default Scoped
• [DependencyInjection(Ignore = true)] — opt out of auto-registration
• [HttpClientDependencyInjection("https://api.example.com", TimeoutSeconds = 180)] — wire via AddHttpClient instead (e.g. ISteamGameService)

Implications when adding a new service:

• Drop the interface in Dpz.Core.Service.RepositoryService and its impl in Dpz.Core.Service.RepositoryServiceImpl — DI is automatic, no code change needed
• Service interfaces must start with I followed by a PascalCase name — the impl must match the part after I
• Putting the impl outside RepositoryServiceImpl will silently leave the service unregistered
• Only the first matching impl wins; if you need multiple, do NOT add a second — use manual registration in the app-specific DI extension

Mediator (martinothamar Mediator, NOT MediatR)

See .agent/skills/mediator/SKILL.md for full details. Key points:

• Package: Mediator by martinothamar v3.0.2 — source-generator based. Do NOT hand-register handlers; the generator wires them automatically.
• Registered via AddDpzMediator() called inside AddBusinessServices().
• Pipeline: MediatorLoggingBehavior → MediatorPerformanceBehavior (≥800 ms warning) → MediatorExceptionWrappingBehavior
• Handlers inject: IRepository<>, IFusionCache, IMessagePublisher<>, IMapper, IMediator, IHttpClientFactory, IConfiguration, ILogger<> — never business service interfaces from Dpz.Core.Service
• Return types: ResponseResult/ResponseResult<T> for API-boundary requests; DTO/ViewModel/nullable for queries; never Public.Entity.*
• Feature modules live in src/Dpz.Core.Service.Mediator/Features/: Article, Code, Health, Markdown, Media, Search, Storage, Video, plus Account, Auth, Mumble, Security, Sitemap, Timeline — check the folder before creating a new module
• Dependency direction: MongodbAccess → Mediator → Service → Application

Messaging (RabbitMQ + Outbox)

• All message types inherit MessageBase (from Dpz.Core.Entity.Base) and live in Dpz.Core.Public.ViewModel.Messages/
• Routing auto-derived from class name: e.g. NewsArticleMessage → exchange dpz.news.exchange, queue dpz.news.article.queue. Override with [MessageRoute].
• AddRabbitMQ(configuration) is called inside AddBusinessServices() — all apps get the publisher automatically
• Register consumers per-app with AddMessageConsumer<TMsg, THandler>()
• Consumers: ClearCacheMessage + RefreshUserProfileMessage (Web), NewsArticleMessage+BatchCompletionMessage (WebApi, plus MQ integration-test consumers + outbox retry worker under #if DEBUG), several email/media consumers (Web.Jobs)
• Outbox (AddMessageOutbox()) provides MongoDB-backed reliable delivery; retry jobs run every minute in Web.Jobs
• Config section: "RabbitMQ" with HostName, Port, UserName, Password, VirtualHost

Caching (FusionCache)

• Primary cache abstraction: ZiggyCreatures.FusionCache (L1 memory + L2 Redis + Redis backplane)
• Registered in AddBusinessServices() — inject IFusionCache directly
• Services that cache inherit AbstractCacheService which wraps GetOrSetAsync with tag-based invalidation (RemoveByTagAsync)
• Cache prefix key defaults to Type.FullName; override per service
• In dev: distributed lock via FileDistributedSynchronizationProvider (config key FileLockPath, default D:\backup\dpz.core.lock); production uses RedisDistributedSynchronizationProvider
• IP rate limiting also uses FusionCache+Redis (cache key: "RateLimit:IP:{IP}"); middleware order: UseIpRateLimit() before UseRejectBots()

Testing quirks

• xUnit + Microsoft.NET.Test.Sdk
• Integration tests (Backup.Test, ServiceTest, etc.) require MongoDB running; rely on appsettings.Test.json
• MongoDB single instance does NOT support transactions — must use replica set (--replSet rs0)
• Tests that use IUnitOfWork (transactions) only pass with MongoDB replica set
• CI (.github/workflows/build.yml) only runs dotnet restore + dotnet build — no tests run in CI yet

Config & prerequisites

Required at runtime (throw InvalidConfigurationException if absent in Web; checked in respective Program.cs):

• AgileConfig:appId, AgileConfig:secret, AgileConfig:nodes — central config server; valid AgileConfig:env values: DEV, TEST, STAGING, PROD
• ConnectionStrings:mongodb — main MongoDB
• ConnectionStrings:hangfireMongodb — separate connection string used exclusively for Hangfire storage
• ConnectionStrings:redis — Redis (SignalR backplane, FusionCache L2, distributed locks)
• LibraryHost, AssetsHost — required by Dpz.Core.Web
• Server:Issuer — required by Dpz.Core.WebApi (JWT authority URL, points to Auth server)
• WebApiHangfireCollectionPrefix — required by Dpz.Core.WebApi; STAGING uses "STAGING_WebAPI" to avoid MongoDB collection collision
• hangfireStatus:ItHomeDelete|ItHomeUpdate|SteamUpdate|Backup|CosDirCleanup — boolean flags to enable/disable recurring Web.Jobs jobs
• RabbitMQ:HostName|Port|UserName|Password|VirtualHost

NuGet feed: GitHub Packages at https://nuget.pkg.github.com/pengqian089/index.json (credentials embedded in src/NuGet.config)

Frontend (Dpz.Core.Web)

• TypeScript + esbuild 0.28.1 (pinned, not webpack/vite). ESM modules. esbuild configs in src/Dpz.Core.Web/esbuild/ (NOT under wwwroot/)
• Source TS lives in src/Dpz.Core.Web/wwwroot/scripts/ (entry: App.ts → app.min.js)
• Single entry bundle app — the old member bundle is gone. npm run build:app is the only prod build; npm run dev:app the only watch. build.ps1 dev-all is a renamed alias for the same app-only watch (no concurrently)
• CSS follows BEM naming. Shared partials prefixed _ (e.g. _pagination.css)
• Dev mode outputs plain .dev.js; production adds content-hash filenames (8-char base32 for JS, 8-char lowercase hex for CSS)
• Manifest: esbuild/.app.manifest.json → wwwroot/assets-manifest.json
• Production CSS pipeline uses clean-css-cli (local devDependency, resolved from node_modules/.bin/cleancss by build.ps1) to merge _IncludeCssFilePartial.cshtml references into global.min.css
• Pre-built frontend assets are committed to the repo; no frontend build step in CI or Docker builds
• jQuery + SignalR client for real-time features; supports MessagePack (application/x-msgpack) in WebApi

Deployment

All deploys are manual via GitHub Actions workflow_dispatch:

• deploy-core.yml — Docker build+deploy Dpz.Core.Web to two servers (SERVER_1 and SERVER_2)
• deploy-api.yml — Docker build+deploy Dpz.Core.WebApi to two servers (SERVER_1 and SERVER_2)
• deploy-job.yml — dotnet publish locally, rsync to HONGKONG_SERVER, restarts dpz-job.service via systemd (NOT Docker)
• STAGING-WEBAPI.yml — Docker staging WebApi on SERVER_1 only (port 3509, AgileConfig:env=STAGING)
• No GitHub Actions workflow exists for Dpz.Core.Auth — deploy is manual or via a separate pipeline

Docker build pattern (from src/ context):

cd src
docker build -t dpz.core -f Dpz.Core.Web/Dockerfile .
docker run --restart=always --name dpz.core -e TZ=Asia/Shanghai -p 2372:8080 -d dpz.core:latest

Use -e "AgileConfig:env=STAGING" for non-Prod environments.

Notable paths

• Hangfire dashboard — Web: /runtask (constant Program.HangfireDashboardPath); Web.Jobs: /jobs (constant Program.ConsoleUrl); WebApi: /jobs in DEBUG only
• Auth cookie name — Web: Dpz.Web.Core.Authoriza; WebApi: Dpz.Web.Api.Server.Authoriza
• API docs (Scalar): /scalar/v1 (theme: Saturn)
• Rate-limit policy name: "comment" (3 req/min, FixedWindow)
• EnumLibrary can be published as NuGet: dotnet pack -c Release then dotnet nuget push

Branch naming

<type>/<issue-id>-<short-description> — types: feature/, bugfix//fix/, hotfix/, release/, chore/, docs/, refactor/, test/

What CI does (and doesn't)

.github/workflows/build.yml (push/PR to master):

• dotnet restore → dotnet build — no lint, no format check, no tests
• Code formatting must be enforced locally: dotnet csharpier . (in src/) + npm run format:check (in src/Dpz.Core.Web/)