YouduWiki/AGENTS.md

# AGENTS.md

This file is for coding agents working in `PandaWiki`.
Prefer small, targeted changes that match the repository's existing patterns.
Communicate with the user in Chinese unless they explicitly ask otherwise.

## Source Of Truth

- There is no existing `AGENTS.md` in this repository.
- No Cursor rules were found in `.cursor/rules/` or `.cursorrules`.
- No Copilot instructions were found in `.github/copilot-instructions.md`.
- Root `CLAUDE.md` exists and should be treated as repository guidance.
- Key note from `CLAUDE.md`: respect backend layer boundaries and use Chinese for communication.

## Repository Layout

- `backend/`: Go backend services, APIs, workers, migrations, docs.
- `web/`: pnpm workspace for frontend apps.
- `web/admin/`: React + Vite admin console.
- `web/app/`: Next.js user-facing web app.
- `sdk/`: SDK-related code.

## Architecture Expectations

- Backend follows a layered structure.
- Put business logic in `backend/usecase/`.
- Keep HTTP-specific logic in `backend/handler/`.
- Keep persistence and external data access in `backend/repo/`.
- Put shared request/response and domain models in `backend/domain/` and `backend/api/`.
- Do not move business rules into handlers just to finish a feature quickly.

## Tooling Versions And Basics

- Go version: `1.24.3` from `backend/go.mod`.
- Frontend package manager: `pnpm` only.
- Admin app build tool: Vite.
- User app build tool: Next.js.
- Backend formatting/linting is driven by `gofmt`, `goimports`, and `golangci-lint`.
- Frontend formatting is primarily Prettier.

## Install Commands

Run these from the repository root unless noted otherwise.

### Backend

- Install Go dependencies: `cd backend && go mod tidy`
- Build all backend packages: `cd backend && go build ./...`

### Frontend

- Install web dependencies: `cd web && pnpm install`
- Start both frontend apps: `cd web && pnpm dev`

## Build Commands

### Backend

- Build all packages: `cd backend && go build ./...`
- Build one package: `cd backend && go build ./usecase`
- Generate swagger/wire code: `cd backend && make generate`
- Generate pro swagger/wire code: `cd backend && make generate_pro`

### Frontend

- Build all web apps: `cd web && pnpm build`
- Build admin only: `cd web/admin && pnpm build`
- Build app only: `cd web/app && pnpm build`
- Analyze admin build: `cd web/admin && pnpm build:analyze`

## Test Commands

### Backend

- Run all tests: `cd backend && go test ./...`
- Run one package: `cd backend && go test ./usecase`
- Run one test by name in one package: `cd backend && go test ./usecase -run TestName`
- Run one test with verbose output: `cd backend && go test ./usecase -run TestName -v`
- Run one package with race detector when needed: `cd backend && go test -race ./usecase`

### Frontend

- `web/admin` currently has no dedicated test script in `package.json`.
- `web/app` currently has no dedicated test script in `package.json`.
- For frontend verification, use lint, typecheck, and build as the practical test substitute.
- Admin typecheck via build pipeline: `cd web/admin && pnpm build`
- App lint: `cd web/app && pnpm lint`

## Lint And Format Commands

### Backend

- Lint backend: `cd backend && golangci-lint run`
- Full backend lint target: `cd backend && make lint`
- Format one file/package: `cd backend && gofmt -w path/to/file.go && goimports -w path/to/file.go`
- `cd backend && make lint` is required before commit for any backend code change.

Notes:

- `make lint` also runs generation steps and `go mod tidy`; it is heavier than `golangci-lint run`.
- `make lint` already covers backend formatting via configured formatters, so agents should treat it as the required backend verification step before commit.
- `backend/.golangci.toml` enables standard linters and formatters.

### Frontend

- Root formatting: `cd web && pnpm exec prettier --write .`
- Admin lint one file or folder: `cd web/admin && pnpm exec eslint src/path/to/file.tsx`
- App format: `cd web/app && pnpm format`
- App format check: `cd web/app && pnpm format:check`
- App lint: `cd web/app && pnpm lint`

## Code Style: Go

- Use `gofmt`/`goimports`; do not hand-format imports.
- Keep imports grouped by standard library, third-party, then local modules.
- Use tabs and standard Go formatting.
- Exported names use Go PascalCase; unexported names use camelCase.
- Receiver names should be short and consistent, usually `u`, `h`, `r`.
- Keep functions focused; prefer extracting domain logic into `usecase` over large handlers.
- Return wrapped errors with context using `fmt.Errorf("...: %w", err)`.
- Use `errors.Is` for sentinel checks.
- Log internal details, but return user-facing messages from handlers.
- Follow existing pattern: log with `u.logger.Error(...)` or `h.NewResponseWithError(...)` rather than panicking.
- Prefer explicit structs over untyped maps unless responding with a tiny ad hoc payload.
- Respect context propagation. Use `c.Request().Context()` in handlers.
- For streaming/SSE paths, preserve existing event shapes and flushing behavior.

## Code Style: TypeScript / React

- Follow Prettier formatting and the existing single-quote style.
- Use path aliases like `@/request/...` and `@/store` in admin code.
- Prefer explicit types for props and request payloads.
- Avoid `any`; lint only warns today, but new code should use concrete types where practical.
- Use `type` for simple object aliases and event payloads; use `interface` for component props when already idiomatic nearby.
- Components are function components with hooks.
- Keep state local unless it is shared across routes or features.
- Clean up subscriptions/AbortControllers/SSE clients in `useEffect` cleanup or modal close handlers.
- Reuse generated request types from `@/request/types` when available.
- Do not edit generated swagger client files unless absolutely necessary; prefer wrappers like `nodeStream.ts` for special protocols.
- Match existing UI libraries: MUI plus `@ctzhian/ui`.

## Naming Conventions

- Backend request structs end with `Req`, response structs with `Resp`.
- Usecase methods are verbs or verb phrases, e.g. `SummaryNode`, `MoveNode`.
- Frontend modal and page components use PascalCase filenames and component names.
- Request helpers in admin use verb-based names from generated swagger files or descriptive wrapper names.

## Error Handling Expectations

- Never swallow backend errors silently.
- If an error is user-actionable, return a clear message from the handler.
- If an error is for diagnostics only, log the wrapped error and return a generic message.
- In frontend code, surface actionable failures with `message.error(...)`.
- For async UI actions, always stop loading state in both success and error paths.
- For streaming flows, handle both transport errors and protocol-level `error` events.

## Generated Code And API Clients

- `web/admin/src/request/*` contains generated swagger client code.
- Generated files use disabled linting and should generally not be hand-edited.
- If an endpoint needs non-JSON behavior, create a thin wrapper alongside generated code instead of forcing the generated client.
- Backend swagger generation uses `swag`; if handler docs change significantly, regenerate docs with `cd backend && make generate`.
- If swagger files change, run `cd web && pnpm api` before committing frontend code so generated request clients stay in sync.

## Practical Guidance For Agents

- Read the nearby code before changing patterns.
- Prefer the smallest correct change.
- Preserve existing protocol contracts unless the task explicitly changes them.
- If the user asks for a review, only produce a review report; do not modify code as part of the review task.
- If changing an HTTP contract, search for every caller first.
- When touching backend request flows, verify both handler behavior and frontend request wrappers.
- When touching frontend request code, check interceptors and special transports like SSE.
- Do not introduce a new abstraction unless the same logic clearly repeats.

## Verification Checklist

- Backend change: run `go test` on the affected package at minimum.
- Any backend code change requires `cd backend && make lint` before commit.
- API contract change: search for all callers and update them together.
- If swagger files were modified, run `cd web && pnpm api` before committing any related frontend changes.
- Frontend admin change: run targeted `eslint` and, if feasible, `pnpm build` in `web/admin`.
- Frontend app change: run `pnpm lint` or `pnpm build` in `web/app` as appropriate.
- If full builds fail because of pre-existing unrelated issues, say so explicitly.