60 lines
4.5 KiB
Markdown
60 lines
4.5 KiB
Markdown
# 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/` 模板写执行日志。
|