saas-mbr/abacus-static-framework/.project.agents/AGENTS.md

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

# 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.