# 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

```sh
# 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/` 模板写执行日志。