feat: 添加仓库指南文档,包含项目结构、构建命令、编码风格及测试规范

This commit is contained in:
2026-07-28 12:28:53 +08:00
parent a537fee613
commit 747ff59d76

38
AGENTS.md Normal file
View File

@@ -0,0 +1,38 @@
# Repository Guidelines
## Project Structure & Module Organization
`TIKU-BACKEND.slnx` groups production projects under `src` and tests under `tests`. `Tiku.Api` contains controllers, middleware, authentication, and OpenAPI setup. `Tiku.Application` defines use cases and provider interfaces; `Tiku.Domain` owns entities and enums; `Tiku.Infrastructure` implements EF Core persistence and external providers. Use `Tiku.DbMigrator` for schema changes and `Tiku.Worker` for background processing. Tests live in `Tiku.UnitTests` and `Tiku.IntegrationTests`; architecture decisions and migration notes belong in `docs/`.
Keep dependencies pointed inward: Domain must remain infrastructure-free, Application expresses abstractions, and provider SDKs or secret access stay in Infrastructure.
## Build, Test, and Development Commands
Run commands from the repository root:
```bash
dotnet restore TIKU-BACKEND.slnx
dotnet build TIKU-BACKEND.slnx --no-restore
dotnet test TIKU-BACKEND.slnx --no-build
dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore
dotnet run --project Tiku.Api
dotnet run --project Tiku.DbMigrator
```
The API and migrator require PostgreSQL through `ConnectionStrings:Database` or `DATABASE_URL`. Generate reviewable migration SQL with `dotnet ef migrations script --project Tiku.Infrastructure --startup-project Tiku.DbMigrator`. Also run `git diff --check` before committing.
## Coding Style & Naming Conventions
Use standard C# formatting: four-space indentation, file-scoped namespaces, nullable reference types, and implicit usings. Use PascalCase for types and public members, camelCase for locals and parameters, and prefix interfaces with `I`. Keep async methods suffixed `Async`. Database identifiers are mapped to `snake_case`; do not bypass centralized EF configurations or tenant safeguards.
## Testing Guidelines
Tests use xUnit and follow `*Tests.cs`; test methods use descriptive behavior names such as `Password_login_can_access_current_user_and_tenant`. Add focused unit tests for isolated logic and integration tests for API, EF model, migration, authorization, and tenant-isolation behavior. PostgreSQL-specific invariants must be proven against real PostgreSQL, not only the in-memory provider. No numeric coverage threshold is configured, but every behavior change needs regression coverage.
## Commit & Pull Request Guidelines
History follows Conventional Commit subjects such as `feat:`, `fix:`, `refactor(api):`, `docs:`, and `chore:`. Keep commits narrow and imperative. Pull requests should explain the behavior and architectural impact, link the issue or migration phase, identify schema/configuration changes, and list verification commands. Include screenshots only for generated API documentation or other visible output; never commit credentials or temporary bootstrap passwords.
## Agent-Specific Instructions
When `.codegraph/` exists, use `codegraph explore "<question or symbol>"` before text search for code discovery. Treat tenant context, authorization, migrations, and provider boundaries as security-sensitive changes requiring targeted integration tests.