AGENTS.md

Monorepo Layout

Two independent subsystems in one repo:

crm/ — Smart campus management (CRM / 智慧校园)
- crm/backend/ — Java 17+ backend, RuoYi-Vue-Plus 5.4.0 (Spring Boot 3.4.6, MyBatis-Plus, Sa-Token)
- crm/web/ — Vue 3 + TypeScript + Element Plus + Vite admin frontend
- crm/py-backend/ — Python FastAPI auxiliary service
bx/ — Expense reimbursement system (报销系统)
- bx/bx-backend/ — Python >=3.11, FastAPI + SQLAlchemy + Alembic
- bx/bx-web/ — Vue 3 + TypeScript + Vite admin frontend
- bx/bx-mobile/ — Vue 3 + Vant 4 mobile frontend

Do not assume web/ or backend/ exist at repo root — they are always under crm/ or bx/.

Dev Commands

CRM Java backend (from `crm/backend/`)

# Hot-start (dev, default profile: dev, port 8080)
./hot-start.sh

# Multi-service start
./start-all.sh          # all services
./start-main.sh         # main app only
./start-job.sh          # job scheduler
./start-monitor.sh      # monitor admin

# Maven (tests skipped by default via <skipTests>true</skipTests>)
mvn -DskipTests validate
mvn -DskipTests package

Entry class: ruoyi-admin/src/main/java/org/dromara/DromaraApplication.java

CRM frontend (from `crm/web/`)

npm run dev              # Vite dev server
npm run build:prod       # production build (8 GB heap)
npm run lint:eslint      # ESLint check
npm run lint:eslint:fix  # ESLint auto-fix
npm run prettier         # format all files

BX Python backend (from `bx/bx-backend/`)

# Dev (uses .venv)
./start.sh
# Prod
./start_prod.sh
# Tests
python run_tests.py
python run_e2e_tests.py

BX web (from `bx/bx-web/`)

npm run dev              # Vite dev server
npm run build            # vue-tsc typecheck + vite build
npm run build:prod:fast  # vite build only (no typecheck)

BX mobile (from `bx/bx-mobile/`)

npm run dev
npm run build            # vue-tsc --noEmit + vite build

Backend Architecture (CRM Java)

Multi-module Maven project under crm/backend/:

Module	Purpose
`ruoyi-admin`	App entrypoint, Spring Boot main
`ruoyi-common/`	Shared libs (core, mybatis, redis, satoken, web, excel, etc.)
`ruoyi-modules/ruoyi-xg`	学工管理 — primary business module
`ruoyi-modules/ruoyi-crm`	CRM business
`ruoyi-modules/ruoyi-system`	System management
`ruoyi-modules/ruoyi-workflow`	Workflow (Warm-Flow engine)
`ruoyi-modules/ruoyi-job`	Scheduled tasks (SnailJob)
`ruoyi-extend/`	Monitor admin, SnailJob server

Layered code pattern (ruoyi-xg example)

controller/  → REST endpoints (@SaCheckPermission, @Log, @RepeatSubmit)
service/     → IXgXxxService interface
  impl/      → XgXxxServiceImpl (uses LambdaQueryWrapper, MapstructUtils.convert)
mapper/      → extends BaseMapperPlus<Entity, Vo> (not plain BaseMapper)
domain/      → Entity (@TableName, extends TenantEntity, @TableId ASSIGN_ID, @TableLogic)
  bo/        → BO (extends BaseEntity, @AutoMapper, validation groups: AddGroup/EditGroup)
  vo/        → VO (@AutoMapper, @ExcelProperty for export)

Key conventions

Permission format: module:entity:action (e.g., xg:student:list)
All table names in xg module prefixed xg_
Entities use snowflake ID (@TableId(type = IdType.ASSIGN_ID)) and logical delete (@TableLogic)
Object mapping: MapstructUtils.convert(source, Target.class) — not manual setters
Pagination: PageQuery in, TableDataInfo<T> out; use baseMapper.selectVoPage()
Excel export: ExcelUtil.exportExcel(list, title, VoClass, response)
Validation: @Validated(AddGroup.class) / @Validated(EditGroup.class) on controller methods

Frontend Architecture (CRM Web)

Auto-import is enabled via unplugin-auto-import — ref, reactive, onMounted, computed, watch, nextTick, toRefs, useRouter, useRoute, etc. are available without explicit import.

Common framework utilities (auto-provided via proxy or global):

useDict('dict_type') — load dictionary data
v-hasPermi="['xg:xxx:add']" — button permission directive
proxy?.$modal.msgSuccess() / proxy?.$modal.confirm() — message dialogs
proxy?.$download(url, params, filename) — file export download
parseTime(date) — date formatting
<dict-tag :options="dict" :value="val" /> — dictionary display
<pagination> / <right-toolbar> — standard table pagination & toolbar components

API files go in src/api/xg/ (or src/api/crm/), pages in src/views/xg/ (or src/views/crm/). Routes are configured via backend menu management — no manual frontend route files needed.

BX Backend Architecture

bx/bx-backend/app/
  main.py        → FastAPI app factory (create_app())
  config.py      → pydantic-settings
  database.py    → SQLAlchemy setup
  models/        → SQLAlchemy models
  schemas/       → Pydantic schemas
  routers/       → API route modules (auth, user, role, expense_item, workflow, advance, reimburse, attachment, payment)
  services/      → Business logic
  utils/         → Shared utilities

Uses .venv/ (not managed by poetry/pipenv). Install: pip install -e ".[dev]".

UI Design System (BX only)

BX web and mobile follow the Fresh Mint design system:

Primary color: #10b981
Full spec docs: bx/docs/web-admin-ui-spec-fresh-mint.md and bx/docs/mobile-ui-spec-fresh-mint.md
Token variables defined in bx/bx-web/src/ CSS and bx/bx-mobile/src/styles/index.css
Do not hardcode colors; use design tokens

Existing Instruction Files

.cursorrules — comprehensive code generation templates (1387 lines), covers CRM backend/frontend patterns in detail including full code scaffolds. Consult it for exact boilerplate when generating new CRUD modules.

AGENTS.md 5.7 KB Vēsture Neapstrādāts