saas-mbr/abacus.springboot.example/.project.agents/CLAUDE.md

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

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