# Repository Guidelines

AGENTS.md is the cross-vendor contributor guide (Claude, Codex, and others read it). Keep it in English by convention. It overlaps CLAUDE.md on purpose — this is the canonical version for non-Claude agents.

## Authority & Required Reading
Rules in `.project.agents/CLAUDE.md` apply to every agent working here. Direct user instructions still take precedence.

The canonical contributor guide is `.project.agents/AGENTS.md`. Do not create or maintain a root-level `AGENTS.md` unless the user explicitly asks for one.

Before any code-changing task, read `.project.agents/SELF_CONSTRAINTS.md` and `.project.agents/VIBECODING_GUIDE.md`, then run `git status --short`. For product work, also read the relevant sections of `PRD.md`, `ARCHITECTURE.md`, `ROADMAP.md`, and `CONVENTIONS.md` under `.project.agents/docs/context/`. Shared front-backend constraints live in the workspace-level `docs/` (see `../../../docs/coding-standards.md`) — read the referenced sections instead of duplicating them here.

## Project Structure & Module Organization
`abacus-static-framework` is an enterprise Vue 3 + TypeScript microservice front-end base (menu framework) built with Vue 3.5, TypeScript 5, Vite 6, Element Plus, vxe-table, Pinia, axios. Business code lives in `src/subsystem/**` (reference template: the `sms` examples, copy-and-rewrite); `src/framework/**` is READ-ONLY shared framework. No automated tests.

Target architecture is documented in `ARCHITECTURE.md`: framework (shared, read-only) / subsystem (business writable) / dynamic menu-permission routing.

## Source-of-Truth Rules
`PRD.md` defines behavior and scope.
`UIUX.md` defines visual and interaction rules.
`ARCHITECTURE.md` is the authority for modules, dependencies, contracts, and directory layout. Derived documents follow upstream changes, not the other way around.

Feature changes must update `PRD.md`. Module, dependency, entity, or invariant changes must update `ARCHITECTURE.md` in the same commit. Do not let code and architecture drift for more than 24 hours.

## Build, Test, and Development Commands

```sh
# Build (output goes straight to the target microservice's resources/html/vue/<app>/)
npm run build:prod

# Run
npm run dev

# Test
No automated tests (manual smoke only)
```

Environment: Node 18.20.7, npm mirror `https://registry.npmmirror.com`. Before local integration, adjust `vite.config.ts` (`build.outDir` → target service's `resources/html/vue/<app>/`; `server.proxy` → target backend) and `public/data/data.js` (`currentSubsystem`). After a framework upgrade, run `npm install`; never overwrite `public`, `vite.config.ts`, or `src/subsystem`.

## Architecture & Coding Style
Use TypeScript, 2-space indentation. Kebab-case files, PascalCase component names (must equal the route `name`), `getXxx`/`saveXxx` API function names. Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies and no cross-module private access. Avoid empty names such as `Manager`, `Helper`, `Util`, `Common`, `Misc`, or `Tools`.

UI/presentation code should consume state and send intents only — business logic goes into hooks/services; keep data-model types thin. Data access must go through the `request` wrapper (`src/framework/utils/request.ts`) — never raw `axios`/`fetch`; the wrapper handles service-alias mapping, token refresh, commonParam header, and response unwrapping (see shared spec §6).

## Testing Guidelines
No automated test framework. Required validation from `ARCHITECTURE.md`: manual smoke per page flow (list / query / create / edit / export). Multi-datasource routing, Kafka consumption, XXL-JOB scheduling, Nacos config pull, and real database migrations require real-environment validation; mock/simulator-only evidence is not enough for those claims.

## Git, Logs, and PRs
Do not pile new work onto unrelated dirty changes without calling it out. Prefer Conventional Commits such as `feat: ...`, `fix: ...`, `docs: ...`. This repository is part of a single git repo rooted at the workspace (`D:\workBuddySpace\member`); commit scope should stay within this subproject unless the change is cross-project (docs/).

Each independently verifiable feature, milestone, non-trivial fix, or refactor needs an execution log in `.project.agents/log/YYYY-MM-DD-<slug>.md` unless it is only a minor documentation edit. Logs must include what changed, relevant commits (or "uncommitted" with reason), verification performed, and next steps.

Pull requests should include scope, linked issues, screenshots for UI changes, environment/device coverage, and any documentation updates.

## Security & Configuration
Do not commit secrets, credentials, build output, or personal IDE files. Agent configuration and generated agent notes belong under `.project.agents/`, not the repository root, `.claude/`, or a global home directory.