# CLAUDE.md

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

## Project

`abacus.springboot.example` 是 **Spring Boot Maven 微服务模板**（多数据库 + abacus 框架），父工程 `abacus.framework:abacus.springcloud.pom:1.5.0`。业务代码位于 `src/main/java/abacus/springboot.<应用名>.{api,controller,dao,esb,pi,impl,repository,wsi,config,util,vo}/`（参考模板：`example` 下的 JcBill 稽查示例，供复制改写）；配置位于 `src/main/resources/config/{dev,test,prod}/`，SQL 位于 `src/main/resources/sql/`。

- Entry point: `src/main/java/abacus/springboot/example/Application.java`
- **分层即契约**：`api(+api/view)` / `controller` / `dao`(Entity) / `esb`(Service 编排) / `pi`(数据访问 IF) / `impl`(原生 SQL 实现) / `repository`(Spring Data JPA) / `wsi`(ServiceIF) / `config` / `util` / `vo`；扫描配置 `springdoc.packages-to-scan=.api`、`abacus.entitypackages=.dao`、`abacus.controllerPackages=.controller`。
- **统一响应体**由 `abacus.commons` 的 `ResultResponseBodyWrapper` 包装（`Application.java` 注册 `@Bean`），Controller 直接 return 业务对象；业务异常统一抛 `BusinessException`。
- Known environment constraints: Nacos（bootstrap.yml 配置 server-addr/namespace，extension-configs 引入 abacus-database/discovery/acas/redis/actuator/xxljob 公共配置）；Maven profile `dev`（默认）/`test`/`prod` 决定加载 `config/<env>/`；多数据库驱动已内置（MySQL/jtds+mssql/Oracle/达梦）。

## Common commands

```sh
# Build（产出 target/*-bin.zip：jar + doc + sql + html）
mvn package -Pdev -DskipTests

# Run
mvn spring-boot:run

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

环境注意：Nacos 需可达（配置中心/注册中心）；构建依赖公司 Maven 私服（abacus 二方框架 jar）；`pom.xml` `<artifactId>` 建议为 `abacus.springboot.<应用名>`。

## Architecture

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

- **api / controller**：接口层（对外接口与前端/内部接口），Controller 只做参数校验与编排调用，直接 return 业务对象。
- **esb / wsi**：Service 编排层（@Service）与对外服务接口（*ServiceIF），只编排不做 SQL。
- **dao**：JPA 实体（表映射，含状态常量与 @Version 乐观锁）。
- **pi / impl**：数据访问接口与实现（原生 SQL 全量参数化）。
- **repository**：Spring Data JPA 仓储（派生查询 findByXxx）。
- **config**：@Configuration（DaoIdGenerator、AbacusConfigNote 等基础设施 Bean）与配置常量。
- 前后端共享约束见工作区 `docs/`（`../../../docs/coding-standards.md` §5 后端规范、§6 接口契约）。

## 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`（命名/风格/提交）。

- **源真相层级**（冲突时上游优先）：
  ```
  PRD.md > ARCHITECTURE.md > CONVENTIONS.md > 派生文档
  仓库级 CONVENTIONS 再下接共享 docs/coding-standards.md（仅作全仓公共约定引用）
  ```
  上游变更须在同 commit 内回写受影响的派生文档；代码与架构漂移不得超过 24 小时。

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