Home Explore Help
Register Sign In
wuzilong
/
shanxia
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: master
Branches Tags
shanxia
/
AGENTS.md

AGENTS.md 13 KB
Permalink History Raw

AGENTS.md — 杭州第一技师学院智慧校园管理系统

Monorepo Structure

Multi-project workspace. No monorepo tool — each sub-project is independent.

Directory Stack Framework Port Notes
crm/backend/ Java 17, Maven RuoYi-Vue-Plus 5.4.0, Spring Boot 3.4.6 8080 Main backend; Sa-Token auth, MyBatis-Plus ORM
crm/web/ Node 18.18+, npm Vue 3.5 + TypeScript 5.8 + Vite 6.3 + Element Plus 2.9 80 Main admin frontend; auto-imports Vue APIs
crm/py-backend/ Python FastAPI / scripts — 主工程侧 Python 服务（若使用）
crm/mobile/ Node, pnpm uni-app Vue 2.6 + uview-ui 2.0 + vue-cli-service 8081 (H5) 主工程移动端（纳入仓库时使用该路径）
bx/bx-backend/ Python 3.11+ FastAPI + SQLAlchemy 2 + Uvicorn 8011 报销(expense) sub-system backend
bx/bx-web/ Node, npm Vue 3.5 + TypeScript + Vite 6.3 + Element Plus — 报销 sub-system admin frontend
bx/bx-mobile/ Node, npm Vue 3.4 + TypeScript + Vite 5 + Vant 4 — 报销 sub-system mobile frontend
crm/ — — — 主工程（智慧校园 / RuoYi）根：crm/backend、crm/web、crm/sql、文档与原型等
bx/docs/ — — — 报销子系统规范与计划（含 UI 规范、superpowers 计划）

Non-app under crm/: crm/sql/、crm/yuanxing/、crm/graphify-out/、crm/docs/、crm/*.md 等；报销文档在 bx/docs/；另有 ui-ux-pro-max-skill-main/ 等工具目录。

Developer Commands

Backend (Java)

cd crm/backend

# Build (skips tests by default — <skipTests>true</skipTests> in pom.xml)
mvn clean package -DskipTests

# Start all services in order (monitor → job → main app)
bash start-all.sh

# Or start individually (MUST follow this order):
bash start-monitor.sh     # Monitor center → port 9090
bash start-job.sh          # SnailJob scheduler → port 8800
bash hot-start.sh          # Main app → port 8080 (interactive, supports hot-reload)

# Maven profiles: local, dev (default), prod, prod-local
# (prod-9900 is a Spring profile only, not a Maven profile)
mvn clean package -P dev

hot-start.sh compiles ruoyi-modules/ with mvn clean install first, then ruoyi-admin/. Supports flags: -p <profile>, -P <port>, -c (clean), -d (debug on port 5005), --no-hot.

Web Frontend (Vue 3)

cd crm/web
npm install --registry=https://registry.npmmirror.com
npm run dev              # Dev server on port 80, proxies /prod-api → localhost:8080
npm run build:prod       # Production build (increases heap to 8GB)
npm run lint:eslint      # Lint
npm run lint:eslint:fix  # Lint fix
npm run prettier         # Format

Vitest is installed as devDependency but no test script is defined in package.json.

Mobile (uni-app)

cd crm/mobile
pnpm install             # Has .npmrc with shamefully-hoist=true; pnpm-lock.yaml present
pnpm run dev:h5          # H5 development (vue-cli-service uni-serve)
pnpm run dev:mp-weixin   # WeChat miniprogram development
pnpm run build:h5        # H5 production build

CRM Python backend (optional)

cd crm/py-backend
bash start.sh            # Uses .venv + uvicorn per project script

BX Backend (Python/FastAPI)

cd bx/bx-backend
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
bash start.sh            # Reads .env, runs uvicorn on port 8011 (default)
# With debug reload: set DEBUG=true in .env
# Tests: pytest (httpx + pytest in dev deps)

BX Web & Mobile

cd bx/bx-web && npm install && npm run dev   # Proxies /api → localhost:8011
cd bx/bx-mobile && npm install && npm run dev

Architecture Notes

Backend Module Layout

crm/backend/
├── ruoyi-admin/              # App entry point (SpringApplication.run)
├── ruoyi-common/             # Shared library modules (20+)
│   ├── ruoyi-common-core/
│   ├── ruoyi-common-mybatis/
│   ├── ruoyi-common-redis/
│   ├── ruoyi-common-satoken/
│   ├── ruoyi-common-web/
│   ├── ruoyi-common-excel/
│   └── ...
├── ruoyi-modules/            # Business modules
│   ├── ruoyi-system/         # System management (users, roles, menus)
│   ├── ruoyi-xg/             # 学工管理 (student affairs) ⭐ main custom module
│   ├── ruoyi-crm/            # CRM module
│   ├── ruoyi-workflow/       # Workflow (warm-flow engine)
│   ├── ruoyi-job/            # Scheduled tasks
│   ├── ruoyi-generator/      # Code generator
│   └── ruoyi-demo/           # Demo/examples
└── ruoyi-extend/
    ├── ruoyi-monitor-admin/  # Spring Boot Admin → port 9090
    └── ruoyi-snailjob-server/ # SnailJob scheduler → port 8800

BX Backend Layout

bx/bx-backend/app/
├── main.py          # FastAPI entry (app.main:app)
├── config.py        # Settings via pydantic-settings
├── database.py      # SQLAlchemy engine/session
├── models/          # SQLAlchemy ORM models
├── schemas/         # Pydantic request/response schemas
├── routers/         # API route handlers
├── services/        # Business logic
└── utils/           # Helpers

Key Backend Conventions

  • Package: org.dromara.{module} — e.g. org.dromara.xg, org.dromara.system
  • Auth: Sa-Token with JWT, permission format {module}:{entity}:{action} (e.g. xg:student:list)
  • ORM: MyBatis-Plus with BaseMapperPlus<Entity, VO> — provides selectVoPage, selectVoList etc.
  • Object mapping: MapStruct-Plus 1.5.0 (@AutoMapper annotation on BO/VO classes)
  • Multi-tenant: Entities extend TenantEntity, tenant filtering is automatic
  • ID strategy: Snowflake (ASSIGN_ID) — NOT auto-increment
  • Logical delete: del_flag field with @TableLogic
  • API docs: SpringDoc auto-generated at /swagger-ui/index.html (uses javadoc comments, no annotations needed)
  • Excel: FastExcel with @ExcelProperty on VO fields for export
  • Validation groups: AddGroup / EditGroup for create vs update validation
  • Key deps: Hutool 5.8, Redisson 3.45, Warm-Flow 1.7.3, SnailJob 1.5.0

Backend Layer Pattern (ruoyi-xg as reference)

controller/  → REST endpoints, @SaCheckPermission, @Log, @RepeatSubmit
service/     → Interface (IXgXxxService)
service/impl → Implementation with LambdaQueryWrapper + MapstructUtils.convert
mapper/      → BaseMapperPlus<Xxx, XxxVo> (XML only for custom SQL)
domain/      → Entity (@TableName, extends TenantEntity)
domain/bo/   → Business Object (@AutoMapper(target=Entity), validation groups)
domain/vo/   → View Object (@AutoMapper(target=Entity), @ExcelProperty)

Frontend Conventions (crm/web/)

  • Style: <script setup lang="ts"> with Composition API
  • Auto-import: Vue APIs (ref, reactive, onMounted etc.) are auto-imported via unplugin-auto-import
  • Path alias: @ → src/
  • API layer: src/api/{module}/xxx.ts — each file defines Query, Form, VO interfaces + CRUD functions
  • Views: src/views/{module}/xxx/index.vue — standard CRUD page (query form → toolbar → table → dialog)
  • Auth directive: v-hasPermi="['xg:student:add']" for button-level permission control
  • Dict: useDict('dict_type') returns reactive dict data; <dict-tag> renders dict labels
  • Proxy: Vite dev server proxies VITE_APP_BASE_API (/prod-api) → http://localhost:8080
  • API encryption: Enabled by default (VITE_APP_ENCRYPT=true), RSA key pair in .env
  • Extra libs: vxe-table 4.13, UnoCSS 66, echarts 5.6, vue-i18n 11, TinyMCE/WangEditor rich text

Mobile Conventions

  • uni-app Vue 2 with uview-ui component library (NOT Vue 3)
  • Uses pnpm (not npm); .npmrc sets shamefully-hoist=true
  • Uses @vue/cli-service (webpack-based), NOT Vite
  • Pages configured in src/pages.json
  • API utilities in src/common/

Environment & Prerequisites

  • JDK: 17 (required; 21 also supported)
  • Maven: 3.8.8+
  • Node.js: 18.18+ (web), compatible version for mobile
  • Python: 3.11+ (bx/bx-backend 报销；若使用主工程 Python 则为 crm/py-backend/)
  • MySQL: 5.7+ or 8.0+ (can use remote instance)
  • Redis: 5.0+ (can use remote instance)
  • Database name: sx (shared across all Spring profiles)
  • Encoding: All Java/Maven processes use UTF-8 + Asia/Shanghai timezone (set by start scripts)

Gotchas

  • Backend startup order matters: monitor (9090) → job (8800) → main app (8080). Use start-all.sh for correct ordering.
  • hot-start.sh builds ruoyi-modules/ before ruoyi-admin/: If you get compile errors in admin, check that ruoyi-modules installed first.
  • Tests skipped by default: <skipTests>true</skipTests> in pom.xml
  • No .env files in git: application-local.yml, .env.*.local are gitignored. Only crm/web/.env (production defaults) is tracked.
  • Mobile is Vue 2, web is Vue 3: Completely different ecosystems. Mobile uses pnpm + webpack; web uses npm + Vite.
  • Code generator: Available at system tools menu — generates full CRUD scaffolding from DB table definitions.
  • Sensitive data: Student PII (ID numbers, phone numbers) uses data masking annotations.
  • Warm-flow workflow: Enabled by default; workflow definitions managed via built-in designer at /warm-flow-ui.
  • bx/ is independent: The 报销 (expense) sub-system has its own Python backend on port 8011, separate from the main Java backend on 8080. No shared code.
  • bx-web proxies /api → localhost:8011: Not the same proxy path as main web (/prod-api → localhost:8080).
  • Main stack paths: Java backend crm/backend/, admin UI crm/web/, optional Python crm/py-backend/ — run Maven/npm from these directories (not repo-root backend/ / web/).

Existing Instruction Files

  • .cursorrules — Comprehensive code generation rules (Chinese), full-stack conventions, layer patterns, complete code templates. High-value reference for any code generation task.
  • crm/README.md — 主工程目录约定；仓库根 scripts/crm.sh 可在不先 cd 时在 crm/backend|web|py-backend 下执行命令
  • crm/工程本地启动指导.md — Local setup and startup guide with environment installation steps
  • crm/docs/backend/README-热启动脚本.md — Hot-reload startup script documentation
  • .github/workflows/crm-backend-validate.yml — CI：在 crm/backend 下执行 mvn validate（推送/PR 触及后端时触发）

bx-web (报销子系統前端) Conventions

Applies to bx/bx-web/ — Vue 3.5 + TypeScript + Element Plus project.

Component Architecture

  • Page pattern: Each page uses useServerPaged hook + ListPageScaffold (or FilterBlock + DataTablePanel + ListToolbar) for standard CRUD layout.
  • Base components: BaseDialog.vue, BaseButton.vue, BaseInput.vue, BaseSelect.vue, BaseTable.vue, BaseTag.vue, BaseOpButton.vue, BaseClampText.vue, BaseDetailTableSection.vue, ApprovalFlowView.vue
  • Template components: ListPageScaffold.vue, FilterBlock.vue, DataTablePanel.vue, ListToolbar.vue

Dialog Rules (强约束)

  • All dialogs must be centered (horizontal + vertical) via align-center prop on el-dialog / BaseDialog. Never use top offset.
  • Dialog submit buttons must have :loading bound to a loading state variable.
  • Use loadingMap: Record<string, boolean> pattern to track loading state per action.

Search/Filter Rules (强约束)

  • Filter params must be passed to API: When search is triggered, pass filterForm values to pager.search({ ...filterForm }). Never call refresh() without filter params.
  • Use search() not refresh() for user-triggered search: search() resets page to 1 before fetching. refresh() keeps current page.
  • Reset must clear form + reload: handleReset() should clear filterForm fields then call pager.search().
  • Search/Reset buttons must show loading: Bind :loading="pager.loading" (or equivalent).

Button Loading Rules (强约束)

  • Every async button must have :loading: Including query, reset, save, submit, delete, approve, reject, export, etc.
  • Pattern: const loadingMap = reactive<Record<string, boolean>>({}), then :loading="loadingMap.xxx" on button, loadingMap.xxx = true/false around async call.

Table Action Column Rules (强约束)

  • 操作列必须固定右侧: 所有 <el-table-column label="操作"> 必须设置 fixed="right" + class-name="col-actions"。
  • 操作列宽度必须容纳所有按钮: 宽度按按钮数量和文案长度设定，不得出现按钮被截断或换行。
    • 1 个按钮：width="120" | 2 个按钮：width="200" | 3 个按钮：width="280" | 4 个按钮：width="360"
    • 含 3-4 字文案时加 40-60px。
  • 表格支持横向滚动: 使用 .table-scroll 包裹 el-table，设置 overflow-x: auto。
  • 操作列单元格禁止换行: class-name="col-actions" 配合 CSS .col-actions .cell { white-space: nowrap; }。