10KB

Ham Kalıcı Bağlantı Suçlama Geçmiş

project_name: ‘Campaign_Tracker App’ user_name: ‘Daniel’ date: ‘2026-05-07’ sections_completed: [‘discovery’, ‘technology_stack’, ‘language_specific_rules’, ‘framework_specific_rules’, ‘testing_rules’, ‘code_quality_style_rules’, ‘development_workflow_rules’, ‘critical_dont_miss_rules’] existing_patterns_found: 16 status: ‘complete’ rule_count: 78 optimized_for_llm: true

Project Context for AI Agents

This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss.

Technology Stack & Versions

Backend is ASP.NET Core on .NET 10 with nullable reference types and implicit usings enabled.
Backend and frontend are separate applications in one repo: Campaign_Tracker.Server/ and campaign-tracker-client/.
Backend authentication uses JWT Bearer with Keycloak/OIDC integration; agents must reuse existing auth options, role normalization, and authorization policies.
Server-side RBAC is mandatory. Frontend permission checks are UX only and must not replace backend [Authorize] policies.
Legacy Access integration uses System.Data.OleDb; live OleDb access is Windows-only.
Legacy Access tables are immutable. New behavior belongs in extension-layer models/repositories and read models.
Development can use in-memory/test data access when legacy connection config is absent; non-development must require explicit legacy configuration and must not silently fall back.
Frontend is React 19 + TypeScript 6 + Vite 8.
UI implementation uses Ant Design 5 and @ant-design/icons.
Frontend app code should call relative /api/... URLs; Vite proxies /api to https://localhost:7244 in development.
Do not hard-code localhost API origins in React app code.
Do not start duplicate backend processes on port 7244; stop the existing server or use the configured launch profile.
Keep React component modules separate from shared helper/contract modules when exports would violate react-refresh/only-export-components.
Frontend tests live under src, so test files must also satisfy TypeScript build constraints.
Backend tests use xUnit plus ASP.NET Core integration testing via WebApplicationFactory.
Frontend tests use Vitest; production validation uses tsc -b && vite build.
Standard validation commands are dotnet test campaign-tracker.sln, npm test, npm run lint, and npm run build.
Vite's current large-chunk build warning is known and non-blocking unless a story specifically requires bundle optimization.

Critical Implementation Rules

Language-Specific Rules

C# code uses nullable reference types; do not suppress nullability warnings casually. Model optional data explicitly with nullable types.
Prefer immutable record types for DTOs, read models, and value-style domain data, matching existing controller/read-model patterns.
Async repository/controller APIs should accept and pass through CancellationToken where existing patterns do.
Keep backend errors explicit: return typed validation/problem responses or appropriate HTTP status codes instead of throwing for expected user/data validation cases.
TypeScript uses strict build settings with noUnusedLocals, noUnusedParameters, verbatimModuleSyntax, and bundler module resolution.
Use import type for type-only imports when needed by TypeScript/ESLint.
Frontend contract modules should own API DTO types, fetch helpers, validation error classes, and pure helpers.
React component files should export components only when React Fast Refresh lint rules would otherwise fail.
Test files under src are included in TypeScript build; avoid Node-only APIs unless the test has explicit Node type support.

Framework-Specific Rules

Backend endpoints should be controller-based and placed under Campaign_Tracker.Server/Controllers.
Protect role-specific backend endpoints with existing ApplicationPolicy constants; do not create one-off role string checks in controllers.
Register backend services in Program.cs using existing DI patterns: singleton in-memory stores/read models for current extension-layer features unless persistence is introduced by a story.
Legacy Access reads must go through ILegacyDataAccess or schema/link abstractions; do not query OleDb directly from controllers.
React feature code should live under feature folders such as municipalities, electionCycles, admin, workspace, and auth.
Workspace views should integrate through WorkspaceShell navigation and permission checks rather than creating separate top-level app shells.
Use Ant Design components and tokens for workspace UI; avoid bespoke controls when Ant Design has an equivalent.
Use @ant-design/icons for icon buttons/actions.
Frontend fetch helpers should accept an optional fetcher parameter for tests and authenticated fetch injection.
Authenticated frontend calls should flow through existing authenticatedFetch / session patterns rather than direct token handling in feature components.
Keep Vite dev proxy assumptions localized to config and relative /api frontend URLs.

Testing Rules

Add or update backend xUnit tests for every backend behavior change; use repository/unit tests for business logic and WebApplicationFactory tests for endpoint/RBAC behavior.
Integration tests should use AuthIntegrationTestFactory and AuthIntegrationTestFactory.CreateToken(...) for authenticated requests.
Backend authorization changes must include 401/403 coverage where practical.
Legacy compatibility changes must include tests proving legacy Access tables remain read-only or that writes occur only through extension-layer abstractions.
Frontend API contract helpers need Vitest coverage for success and non-OK responses.
Frontend UI/view behavior should be tested with existing lightweight patterns; do not add new browser/E2E dependencies unless the story requires them.
For React view tests rendered with server/static markup, also test pure helper functions for keyboard/windowing logic when DOM interaction libraries are not present.
Run focused tests red/green during implementation, then run full validation before marking BMad story tasks complete.
Required validation before review: dotnet test campaign-tracker.sln, npm test, npm run lint, and npm run build.

Code Quality & Style Rules

Keep changes scoped to the active story; avoid opportunistic refactors outside the story acceptance criteria.
Follow existing folder naming: backend feature folders are PascalCase; frontend feature folders are camelCase.
Backend controllers and repositories should use clear domain names matching existing patterns (Municipality..., ElectionCycle..., Legacy...).
Prefer small, stable DTO/read-model contracts because later stories depend on field names.
Do not place generated build output, audit logs, temp files, bin, obj, or frontend dist content in story file lists.
Use concise comments only for non-obvious domain or integration rules, especially legacy/extension boundary decisions.
Frontend CSS should use existing workspace variables/tokens where available.
Avoid new UI palettes or decorative styling that conflicts with the Ant Design workspace foundation.
Keep React component text compact and operational; this is a dense internal line-of-business workspace, not a marketing page.
Maintain accessible focus styles for keyboard-operable workspace controls.
Do not silence ESLint or TypeScript errors unless the story explicitly requires an exception and the reason is documented.

Development Workflow Rules

BMad story implementation must update only permitted story sections: task checkboxes, Dev Agent Record, File List, Change Log, and Status.
Do not mark story tasks complete until implementation exists, related tests pass, and acceptance criteria are satisfied.
Keep _bmad-output/implementation-artifacts/sprint-status.yaml in sync when moving a story from ready-for-dev to in-progress to review.
When adding files, update the story File List with source/test/config files that changed, not generated artifacts.
Before running or starting local servers, check whether required ports are already in use.
Vite dev normally uses 5173; backend HTTPS profile uses 7244 and HTTP uses 5254.
If port 7244 is in use, do not start a duplicate backend; stop the existing Campaign_Tracker.Server process or use a different launch profile intentionally.
Use focused tests while developing, then run full backend/frontend validations before setting a story to review.
Preserve user or prior-agent changes in the worktree; do not revert unrelated edits.

Critical Don't-Miss Rules

Never mutate original legacy Access schema or tables. All new operational data belongs in extension-layer storage and is joined back to legacy data by stable keys.
Treat JCode / JurisCode, ID, and KitID as critical deterministic join keys; do not normalize them in ways that break legacy joins.
Do not bypass LegacyLinkValidator, legacy schema compatibility checks, or link integrity services when adding extension records tied to legacy data.
Do not move Story 2.2+ behavior into Story 2.1-style route stubs; respect story boundaries and acceptance criteria.
Do not trust frontend permissions as security. Backend policies must enforce role access.
Do not create new auth, audit, or RBAC mechanisms when existing infrastructure already exists.
Do not directly couple React views to raw backend implementation details; keep stable frontend contract helpers.
Do not assume all municipalities have active cycle jobs, contacts, addresses, or prior-cycle defaults; empty states are required.
Do not remove keyboard access or visible focus indicators from workspace controls.
Do not ignore production environment differences: live OleDb requires Windows and explicit legacy configuration.
Do not treat known Vite large-chunk warnings as a failure unless bundle optimization is in scope.

Usage Guidelines

For AI Agents:

Read this file before implementing any code.
Follow all rules as documented.
When in doubt, prefer the more restrictive option.
Update this file if new project patterns emerge.

For Humans:

Keep this file lean and focused on agent needs.
Update it when the technology stack or implementation patterns change.
Review periodically for outdated rules.
Remove rules that become obvious or no longer prevent mistakes.

Last Updated: 2026-05-07

10KB Ham Kalıcı Bağlantı Suçlama Geçmiş