Files
ccdi/docs/plans/2026-03-10-project-detail-transaction-query-backend-implementation.md

414 lines
15 KiB
Markdown
Raw Normal View History

# Project Detail Transaction Query Backend Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Build the backend query, filter options, detail, and export endpoints for the project detail bank statement page using local `ccdi_bank_statement` data.
**Architecture:** Extend the existing `ccdi-project` module with a dedicated bank statement controller and service, while reusing the current `CcdiBankStatementMapper` plus XML dynamic SQL. Keep DTO/VO layering strict, compute direction and display amount in the query layer, and export through `ruoyi-common` `ExcelUtil` so the page and export share one query contract.
**Tech Stack:** Java 21, Spring Boot 3, MyBatis Plus, MyBatis XML, Mockito + JUnit 5, RuoYi `ExcelUtil`
---
### Task 1: Scaffold DTO/VO contracts and the first failing service test
**Files:**
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/CcdiBankStatementQueryDTO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementOptionVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementFilterOptionsVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementListVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementDetailVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiBankStatementService.java`
- Create: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java`
**Step 1: Write the failing test**
```java
@ExtendWith(MockitoExtension.class)
class CcdiBankStatementServiceImplTest {
@InjectMocks
private CcdiBankStatementServiceImpl service;
@Mock
private CcdiBankStatementMapper bankStatementMapper;
@Test
void getFilterOptions_shouldReturnProjectWideOptions() {
CcdiBankStatementFilterOptionsVO options = new CcdiBankStatementFilterOptionsVO();
options.setOurSubjectOptions(List.of(new CcdiBankStatementOptionVO("主体A", "主体A")));
when(bankStatementMapper.selectFilterOptions(100L)).thenReturn(options);
CcdiBankStatementFilterOptionsVO result = service.getFilterOptions(100L);
assertEquals(1, result.getOurSubjectOptions().size());
}
}
```
**Step 2: Run test to verify it fails**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: FAIL with missing `CcdiBankStatementServiceImpl`, DTO, or mapper methods.
**Step 3: Write minimal implementation**
```java
public interface ICcdiBankStatementService {
CcdiBankStatementFilterOptionsVO getFilterOptions(Long projectId);
}
```
```java
@Data
public class CcdiBankStatementOptionVO {
private String label;
private String value;
public CcdiBankStatementOptionVO(String label, String value) {
this.label = label;
this.value = value;
}
}
```
Add the remaining DTO/VO classes with only the fields already confirmed in the design.
**Step 4: Run test to verify it still fails only on the missing service implementation**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: FAIL with `CcdiBankStatementServiceImpl` not found or method not implemented.
**Step 5: Commit**
```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/CcdiBankStatementQueryDTO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementOptionVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementFilterOptionsVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementListVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiBankStatementDetailVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiBankStatementService.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java
git commit -m "新增流水明细查询后端契约与测试骨架"
```
### Task 2: Implement mapper query methods for options, list, detail, and export
**Files:**
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankStatementMapper.java`
- Modify: `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml`
- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java`
**Step 1: Write the failing test**
Add tests that assert the service delegates to mapper methods with normalized arguments:
```java
@Test
void pageQuery_shouldNormalizeSortFieldAndDirection() {
Page<CcdiBankStatementListVO> page = new Page<>(1, 10);
CcdiBankStatementQueryDTO queryDTO = new CcdiBankStatementQueryDTO();
queryDTO.setProjectId(100L);
queryDTO.setOrderBy("amount");
queryDTO.setOrderDirection("desc");
service.selectStatementPage(page, queryDTO);
verify(bankStatementMapper).selectStatementPage(eq(page), same(queryDTO));
}
```
**Step 2: Run test to verify it fails**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: FAIL because mapper methods `selectStatementPage`, `selectStatementListForExport`, `selectStatementDetailById`, `selectFilterOptions` are missing.
**Step 3: Write minimal implementation**
In `CcdiBankStatementMapper.java`, add:
```java
Page<CcdiBankStatementListVO> selectStatementPage(Page<CcdiBankStatementListVO> page,
@Param("query") CcdiBankStatementQueryDTO query);
List<CcdiBankStatementListVO> selectStatementListForExport(@Param("query") CcdiBankStatementQueryDTO query);
CcdiBankStatementDetailVO selectStatementDetailById(@Param("bankStatementId") Long bankStatementId);
CcdiBankStatementFilterOptionsVO selectFilterOptions(@Param("projectId") Long projectId);
```
In `CcdiBankStatementMapper.xml`, add:
- a reusable SQL fragment for common filters
- a reusable expression for parsed transaction time
- a reusable expression for signed display amount
- separate selects for page, export, detail, and distinct project options
**Step 4: Run test to verify it passes or fails only on service logic**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: mapper-signature errors gone; remaining failures only relate to unimplemented service methods.
**Step 5: Commit**
```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankStatementMapper.java ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java
git commit -m "补充流水明细查询Mapper与动态SQL"
```
### Task 3: Implement service normalization, page query, and project-wide filter options
**Files:**
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java`
- Modify: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java`
**Step 1: Write the failing test**
Add focused service tests for:
- default `tabType=all`
- invalid `orderBy` falling back to `trxDate`
- invalid `orderDirection` falling back to `desc`
- blank string fields trimming to `null`
```java
@Test
void normalizeQuery_shouldFallbackToSafeDefaults() {
CcdiBankStatementQueryDTO queryDTO = new CcdiBankStatementQueryDTO();
queryDTO.setProjectId(100L);
queryDTO.setOrderBy("drop table");
queryDTO.setOrderDirection("sideways");
service.selectStatementPage(new Page<>(1, 10), queryDTO);
assertEquals("trxDate", queryDTO.getOrderBy());
assertEquals("desc", queryDTO.getOrderDirection());
assertEquals("all", queryDTO.getTabType());
}
```
**Step 2: Run test to verify it fails**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: FAIL because service normalization logic is missing.
**Step 3: Write minimal implementation**
In `CcdiBankStatementServiceImpl.java`:
```java
@Service
public class CcdiBankStatementServiceImpl implements ICcdiBankStatementService {
@Resource
private CcdiBankStatementMapper bankStatementMapper;
@Override
public Page<CcdiBankStatementListVO> selectStatementPage(Page<CcdiBankStatementListVO> page,
CcdiBankStatementQueryDTO queryDTO) {
normalizeQuery(queryDTO);
return bankStatementMapper.selectStatementPage(page, queryDTO);
}
}
```
Implement `normalizeQuery(queryDTO)` to enforce the white-listed sort fields and normalize blank strings and booleans before delegating to mapper.
**Step 4: Run test to verify it passes**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: PASS
**Step 5: Commit**
```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java
git commit -m "实现流水明细查询服务层规范化逻辑"
```
### Task 4: Add detail lookup and export model with a failing export test
**Files:**
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/excel/CcdiBankStatementExcel.java`
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiBankStatementService.java`
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java`
- Modify: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java`
**Step 1: Write the failing test**
Add a service test for export mapping:
```java
@Test
void selectStatementListForExport_shouldMapDisplayColumns() {
CcdiBankStatementListVO row = new CcdiBankStatementListVO();
row.setTrxDate("2024-02-01 10:33:44");
row.setLeAccountNo("6222");
row.setLeAccountName("张三");
row.setDisplayAmount(new BigDecimal("-8.00"));
when(bankStatementMapper.selectStatementListForExport(any())).thenReturn(List.of(row));
List<CcdiBankStatementExcel> result = service.selectStatementListForExport(new CcdiBankStatementQueryDTO());
assertEquals(1, result.size());
assertEquals("6222", result.get(0).getLeAccountNo());
}
```
**Step 2: Run test to verify it fails**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: FAIL because export model and export service method do not exist.
**Step 3: Write minimal implementation**
Create `CcdiBankStatementExcel.java` with `@Excel` annotations for:
- `trxDate`
- `leAccountNo`
- `leAccountName`
- `customerAccountName`
- `customerAccountNo`
- `userMemo`
- `cashType`
- `displayAmount`
Add service methods:
```java
List<CcdiBankStatementExcel> selectStatementListForExport(CcdiBankStatementQueryDTO queryDTO);
CcdiBankStatementDetailVO getStatementDetail(Long bankStatementId);
```
Map export rows from `CcdiBankStatementListVO` to `CcdiBankStatementExcel`.
**Step 4: Run test to verify it passes**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest`
Expected: PASS
**Step 5: Commit**
```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/excel/CcdiBankStatementExcel.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiBankStatementService.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java
git commit -m "实现流水明细导出模型与详情查询"
```
### Task 5: Add controller endpoints and the first failing controller test
**Files:**
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementController.java`
- Create: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementControllerTest.java`
**Step 1: Write the failing test**
```java
@ExtendWith(MockitoExtension.class)
class CcdiBankStatementControllerTest {
@InjectMocks
private CcdiBankStatementController controller;
@Mock
private ICcdiBankStatementService bankStatementService;
@Test
void options_shouldReturnAjaxResultSuccess() {
when(bankStatementService.getFilterOptions(100L)).thenReturn(new CcdiBankStatementFilterOptionsVO());
AjaxResult result = controller.getOptions(100L);
assertEquals(200, result.get("code"));
}
}
```
**Step 2: Run test to verify it fails**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementControllerTest`
Expected: FAIL because controller class and methods do not exist.
**Step 3: Write minimal implementation**
Add endpoints:
- `GET /ccdi/project/bank-statement/list`
- `GET /ccdi/project/bank-statement/options`
- `GET /ccdi/project/bank-statement/detail/{bankStatementId}`
- `POST /ccdi/project/bank-statement/export`
Use `TableSupport.buildPageRequest()` for paging and `ExcelUtil<CcdiBankStatementExcel>` for export:
```java
ExcelUtil<CcdiBankStatementExcel> util = new ExcelUtil<>(CcdiBankStatementExcel.class);
util.exportExcel(response, list, "流水明细");
```
Guard permissions with:
- query/list/detail/options: `ccdi:project:query`
- export: `ccdi:project:export`
**Step 4: Run test to verify it passes**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementControllerTest`
Expected: PASS
**Step 5: Commit**
```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementController.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementControllerTest.java
git commit -m "新增流水明细查询控制器接口"
```
### Task 6: Verify the backend end-to-end inside the module
**Files:**
- Modify if needed after failures: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementController.java`
- Modify if needed after failures: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java`
- Modify if needed after failures: `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml`
**Step 1: Run the focused backend tests**
Run: `mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest,CcdiBankStatementControllerTest`
Expected: PASS
**Step 2: Run the module compile**
Run: `mvn clean compile -pl ccdi-project -am`
Expected: BUILD SUCCESS
**Step 3: Smoke-check the mapper XML and endpoint contracts**
Run:
```bash
mvn test -pl ccdi-project -Dtest=CcdiBankStatementServiceImplTest -q
```
Expected: PASS without XML binding errors or missing mapper statements.
**Step 4: Fix any compile or binding failures with the smallest possible patch**
Typical fixes:
- wrong `@Param("query")` names
- missing VO field aliases in SQL
- `Page<>` generic mismatch
- `ExcelUtil` export field annotation issues
**Step 5: Commit**
```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementController.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImpl.java ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiBankStatementServiceImplTest.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiBankStatementControllerTest.java
git commit -m "完成流水明细查询后端实现与校验"
```