xiongyuxing/tiku-backend.net
1
0
Fork 1
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: 更新项目结构和模块组织说明，优化构建、测试和开发命令部分

Browse Source
This commit is contained in:
xiong
2026-08-03 10:19:33 +08:00
parent 9d576d2d79
commit 33a08bfaab
1 changed files with 14 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
AGENTS.md
View File

@@ -2,37 +2,32 @@
## Project Structure & Module Organization ## Project Structure & Module Organization
`TIKU-BACKEND.slnx` groups production projects under `src` and tests under `tests`. `Tiku.Api` contains controllers, middleware, authentication, OpenAPI setup, and hosted background processing. `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; PostgreSQL-backed background jobs run as hosted services in `Tiku.Api`. Tests live in `Tiku.UnitTests` and `Tiku.IntegrationTests`; architecture decisions and migration notes belong in `docs/`. `TIKU-BACKEND.slnx` is a .NET 10 modular monolith. `Tiku.Domain` holds entities; `Tiku.Application` defines use-case contracts; `Tiku.Infrastructure` contains EF Core, PostgreSQL, Redis, authentication, jobs, and external integrations. `Tiku.Api` and `Tiku.Worker` are independent runtimes; `Tiku.DbMigrator` owns migration and bootstrap work. Tests live in `Tiku.UnitTests` and `Tiku.IntegrationTests`. The React/TypeScript admin UI is in `Tiku.PlatformAdmin.Web`; documentation and deployment assets live under `docs/` and `deploy/`.
Keep dependencies pointed inward: Domain must remain infrastructure-free, Application expresses abstractions, and provider SDKs or secret access stay in Infrastructure. Keep dependencies flowing `Domain <- Application <- Infrastructure`. Database access, SDK integrations, and secret handling belong in Infrastructure, not controllers or domain types.
## Build, Test, and Development Commands ## Build, Test, and Development Commands
Run commands from the repository root: - `dotnet restore TIKU-BACKEND.slnx` — restore centrally managed NuGet packages.
- `dotnet build TIKU-BACKEND.slnx --no-restore` — compile the complete solution.
```bash - `ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator` — migrate and seed the local PostgreSQL database.
dotnet restore TIKU-BACKEND.slnx - `dotnet run --project Tiku.Api` / `dotnet run --project Tiku.Worker` — start the API or background processor.
dotnet build TIKU-BACKEND.slnx --no-restore - `dotnet test TIKU-BACKEND.slnx --no-build` — run all xUnit tests.
dotnet test TIKU-BACKEND.slnx --no-build - `dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore` — enforce C# formatting.
dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore - `npm --prefix Tiku.PlatformAdmin.Web run check` — type-check, build, and run Vitest tests.
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 ## 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. Use four-space indentation in C# and two spaces in TypeScript. Nullable reference types and implicit usings are enabled. Use PascalCase for public C# symbols, camelCase for locals, and `Async` for asynchronous methods. Prefer feature-oriented folders and focused services. Run `dotnet format` and `git diff --check` before review. Refresh generated OpenAPI clients with `npm --prefix Tiku.PlatformAdmin.Web run generate:api` when contracts change.
## Testing Guidelines ## 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. Name xUnit files `*Tests.cs`; descriptive underscore-style method names are established. Name frontend tests `*.test.ts`. Add unit tests for isolated rules and real PostgreSQL integration tests for migrations, transactions, constraints, authorization, and tenant isolation; EF InMemory is insufficient for PostgreSQL behavior. No fixed coverage threshold is configured, but every behavior change should include regression coverage.
## Commit & Pull Request Guidelines ## 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. History follows Conventional Commits, for example `feat(learning): ...`, `fix(auth): ...`, and `docs: ...`. Keep commits scoped and exclude secrets, build output, and unrelated generated files. Pull requests should explain intent and risk, link the issue, list executed validation, call out migrations or configuration changes, and include screenshots for UI changes.
## Agent-Specific Instructions ## Security & Configuration
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. Never commit connection strings, passwords, tokens, or production keys. Use environment variables such as `ConnectionStrings__Database`. API startup does not apply migrations; run `Tiku.DbMigrator` explicitly. Preserve Host-based tenant resolution and fail-closed authorization behavior when changing middleware or caching.