saas-mbr/abacus.springboot.example/.project.agents/docs/context/PRD.md

abacus.springboot.example — 产品需求文档（PRD）

行为与范围的唯一权威。功能的加/删/改必须先改本文，再动代码与下游文档。 本文回答"做什么 / 给谁 / 为什么"，不回答"怎么实现"（那是 ARCHITECTURE.md）。

1. 产品愿景

为 abacus 微服务体系提供可复用的 Spring Boot 微服务模板：业务团队（人 + AI）在本模板上按分层规范添加业务模块（Controller / Service / 数据访问 / Entity / SQL / 配置），即可获得统一响应体、异常体系、多数据库支持、Nacos 注册配置、定时任务与动静分离打包能力，实现跨系统一致的后端工程结构与低成本复制开发。

2. 目标用户与典型场景

• 用户画像：公司内部业务系统后端开发团队（后端开发、全栈、AI 辅助开发人员）。
• 场景 1：作为业务开发，我想复制本模板新建一个微服务，以便快速获得 Nacos / 多库 / 打包 / 日志等基础设施。
• 场景 2：作为 AI 助手，我想依据 docs/coding-standards.md §5/§7 把界面需求直接生成 Controller→Service→数据访问→SQL 全链路代码。
• 场景 3：作为发布负责人，我想让所有服务打出结构一致的 *-bin.zip（jar+doc+sql+html），以便统一发布流程。

3. 范围（Scope）

3.1 MVP 必含（In Scope）

• 分层骨架（api/controller/dao/esb/pi/impl/repository/wsi/config）与扫描配置（springdoc/entitypackages/controllerPackages）。
• 统一响应体包装（ResultResponseBodyWrapper）与业务异常（BusinessException）。
• 多数据库（MySQL / SQL Server / Oracle / 达梦）+ Druid + JPA；Nacos 注册/配置中心。
• SQL 三件套（table 双份 / upgrade.xml 版本化 / data 初始化）与动静分离打包（assembly.xml → *-bin.zip）。
• 示例业务纵切面（JcBill 稽查示例：Controller + BizService + Access + Repository + Entity + 升级 SQL）。

3.2 明确不做（Out of Scope）

• 不包含具体生产业务（业务模块由团队基于模板复制开发）。
• 不提供自动化测试框架与 CI（人工冒烟验证）。
• 不维护前端页面（前端属 abacus-static-framework 仓库）。

4. 核心功能定义

4.1 统一响应体与异常（【核心】）

• 用户故事：作为前端/调用方，我想所有接口返回一致的 {status, message, data, errorCode}，以便统一处理。
• 行为：Application.java 注册 ResultResponseBodyWrapper；Controller 直接 return 业务对象；参数空校验抛 BusinessException("参数[x]为空！")。
• 边界 / 异常：abacus.responseExcludePath 配置的 URI 不被包装；业务异常码首位 9、系统异常码首位 5（共享规范 §6.2）。

4.2 分层开发模型（【核心】）

• 用户故事：作为团队开发，我想按固定分层写代码，以便职责清晰、可评审、可复制。
• 行为：Controller（api/controller）→ esb 编排 → wsi/pi/repository 数据访问 → dao 实体；依赖单向。
• 边界 / 异常：Controller 不写 SQL、不碰 Repository；esb 只编排不做 SQL；原生 SQL 全量参数化。

4.3 数据库多库支持（【核心】）

• 用户故事：作为实施，我想同一套代码跑 MySQL 与 SQL Server，以便一套系统多客户部署。
• 行为：建表脚本 sql/table/{mysql,sqlserver}.sql 双份同步；历史变更 sql/upgrade.xml（translator="true" 以 SQL Server 语法书写由框架翻译）。
• 边界 / 异常：多数据源路由、真实迁移必须真机验证。

4.4 动静分离打包（【核心】）

• 用户故事：作为发布，我想一个发布包包含前后端全部产物，以便统一发版。
• 行为：前端产物输出到 resources/html/vue/<应用名>/，mvn package 经 assembly.xml 打出 *-bin.zip（jar+doc+sql+html）。
• 边界 / 异常：jar 内不含 html；pom.xml artifactId 建议 abacus.springboot.<应用名>。

5. 信息架构与导航

微服务间通过 Nacos 注册发现 + Feign 调用；接口文档由 springdoc 提供（扫描 api 包）；监控经 Actuator（base-path /services/actuator）暴露 Prometheus 指标；定时任务由 XXL-JOB（application-xxljob.yml）承载。

6. 数据模型（概念级）

业务数据实体集中在 dao/ 包（JPA 映射）；概念级实体清单由各业务模块在 ARCHITECTURE.md §1 维护。模板自带示例实体：jc_bill（稽查主单）及其明细/关联表（见 sql/upgrade.xml）。

7. 非功能性需求

• 多环境配置 config/{dev,test,prod}/ 三套同构；dev 端口 9060 / test、prod 9000（以实际为准）。
• 上传限制 50MB；Druid 连接池（初始 10 / 最大 60）；Feign 超时 10s 连接 / 30s 读取。
• JPA 与 Bean 延迟启动（lazy-initialization）以加速启动。

8. 国际化与文案语气

异常消息使用中文，直接面向用户可理解（如"参数[x]为空！"）；接口文档（@Operation summary）用中文。

9. 隐私与合规

• 数据库连接与 Nacos 凭据放在 config/<env>/ 配置文件（git 跟踪按团队约定）；不得新增明文密钥到非约定位置。
• 审计信息（菜单/模块/业务域）由前端 commonParam 提供，见共享规范 §6.7。

10. 风险与缓解

• APP_NAME 四处漏配静默失败：按共享规范 §3 四联检（bootstrap.yml / 扫描包 / URL 首段 / outDir）。
• 多库语法差异：新 SQL 以 SQL Server 语法编写并加 translator="true"，建表双份同步。
• 框架 jar 版本升级：pom.xml 依赖版本变更需在升级日志记录并回归验证。

11. 发布里程碑（建议，待路线图细化）

• M0：治理与规范落地（本次已完成）。
• M1+：按 ROADMAP.md 以新业务模块验证模板可复制性（界面→代码全链路）。

12. 假设与待澄清项（复核时请逐条回应）

• Q1. 新业务是否一律采用 abacus.springboot.<应用名>.<层> 包前缀？（默认：是）
• Q2. 是否引入后端单元测试（如 JUnit/Testcontainers）？（默认：否，人工冒烟 + 真机验证）
• Q3. util/、vo/ 包是否冻结不再新增？（默认：是，既有兼容、新增禁止）