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

CLAUDE.md

This file guides Claude Code (and other agents) when working in this repository. 保持本文件最新：它是项目级入口——项目是什么、怎么构建、门控一切变更的规则。

Project

abacus-static-framework 是企业级 Vue 3 + TypeScript 微服务前端底座（菜单框架），基于 Vue 3.5 / TypeScript 5 / Vite 6 / Element Plus / vxe-table / Pinia / axios。业务代码位于 src/subsystem/**（参考模板：subsystem 下的 sms 示例，供复制改写）；src/framework/** 为只读共享框架，业务不得修改。

• Entry point: src/main.ts
• 只读/可写分区：src/framework/** 只读；业务开发只写 src/subsystem/**（api / router / views / extend 及自建 components / hooks / store / styles / types / utils）。
• 接口契约（统一响应体、服务别名映射、token 自动刷新、commonParam）由 src/framework/utils/request.ts 强制实现，业务无感；共享约束详见 ../../../docs/coding-standards.md（§6 接口契约、§4 前端规范）。
• Known environment constraints: Node 18.20.7 + npm 淘宝镜像；vite.config.ts 的 build.outDir 与 server.proxy 需按目标微服务修改后才能联调/发布；public/data/data.js 的 currentSubsystem/currentSubsystemName 声明当前子系统。

Common commands

# Build（产物直出目标微服务 resources/html/vue/<应用名>/）
npm run build:prod

# Run（本地开发，Vite 反代后端）
npm run dev

# Test
无自动化测试（人工冒烟验证）

环境注意：首次使用需 npm install --registry=https://registry.npmmirror.com（或已配置镜像则 npm install）。框架升级后需重新 npm install；升级不得覆盖 public、vite.config.ts、src/subsystem。

Architecture

实现遵循 .project.agents/docs/context/ARCHITECTURE.md 的模块边界；模块清单（职责一句话）：

• framework/（只读共享框架）：api（框架级后端接口）、components/standard（标准组件：AbForm/AbQueryForm/vxe 表格等 10 项）、hooks（useVxeTableHandle 等通用组合式函数）、layout（菜单布局）、router（静态路由）、store（settings/permission/user 等 Pinia 状态）、styles、types、utils（standard 5 项 + request 请求管线）、views、directives（v-debounce/v-throttle）。
• subsystem/（业务可写区）：api/<服务别名>（按 Controller 分 ts）、router/dynamicRouter.ts（菜单路由唯一注册点）、views/<一级>/<二级>（页面）、extend（框架扩展钩子）、以及业务自建 components/hooks/store/styles/types/utils。
• 动态权限：permissionStore.filterAsyncRoutes 按 url === path 匹配后端菜单与 dynamicRouter 后 addRoute。

Project-level rules

• 动手前必读两文件——它们编码了本项目所有门控决策的经验：

  • .project.agents/VIBECODING_GUIDE.md — 实践指南（为什么 & 怎么做）
  • .project.agents/SELF_CONSTRAINTS.md — 硬约束（什么禁止、什么必须、何时停下）

  任何非平凡任务，编辑前先跑 SELF_CONSTRAINTS.md §A（开工前自检）。

• 共享约束单一来源：前后端共享的编码规范/接口契约/命名纪律，只存在于工作区 docs/（../../../docs/coding-standards.md、../../../docs/architecture.md、../../../docs/agent-guide.md）；本仓库 .project.agents/docs/context/ 只写本仓库特有内容与指针，禁止复制 docs/ 正文。改共享内容先改 docs/ 再同步指针。

• Agent 配置一律写在 .project.agents/ 下（或子目录），禁止写到仓库根、.claude/ 或全局目录。

• 项目文档位于 .project.agents/docs/context/（单层目录）：PRD.md（行为权威）、ARCHITECTURE.md（模块/依赖/契约）、ROADMAP.md（里程碑）、CONVENTIONS.md（命名/风格/提交）、UIUX.md（视觉与交互）。

• 源真相层级（冲突时上游优先）：

  PRD.md > ARCHITECTURE.md > UIUX.md > CONVENTIONS.md > 派生文档
  仓库级 CONVENTIONS 再下接共享 docs/coding-standards.md（仅作全仓公共约定引用）
  

  上游变更须在同 commit 内回写受影响的派生文档；代码与架构漂移不得超过 24 小时。

• 路线图执行规则：按 .project.agents/docs/context/ROADMAP.md 顺序推进，勾选与完成同 commit；milestone 级/多文件任务先写 plan/spec 再动手；每个 milestone 后按 .project.agents/log/ 模板写执行日志。