92 lines
6.2 KiB
Markdown
92 lines
6.2 KiB
Markdown
# 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/` 包是否冻结不再新增？（默认：是，既有兼容、新增禁止）
|