feat(financial): 新增凭证分录科目明细字段

云

2026-06-08 2c19f00b211b7ffb1a265d67991d92f2b194b1f5

feat(financial): 新增凭证分录科目明细字段

- 在数据库表 fin_voucher_entry 中添加 subject_detail 字段
- 更新应用开发环境配置中的数据库连接URL
- 在 FinLedgerEntryRecordVo 和 FinLedgerRowVo 中添加 subjectDetail 属性
- 在 FinVoucherEntry 实体类中添加 subjectDetail 字段和注解
- 更新 MyBatis 映射文件以包含 subject_detail 字段映射
- 在 FinLedgerServiceImpl 中设置科目明细数据
- 创建凭证分录科目明细字段前端联调文档

 doc/20260512_create_financial_management_tables.sql

@@ -92,6 +92,7 @@
  `auxiliary_type` varchar(32) DEFAULT NULL COMMENT '辅助核算类型',
  `auxiliary_id` varchar(64) DEFAULT NULL COMMENT '辅助核算对象ID',
  `auxiliary_name` varchar(128) DEFAULT NULL COMMENT '辅助核算对象名称',
  `subject_detail` varchar(255) DEFAULT NULL COMMENT '科目明细',
  `create_user` varchar(64) DEFAULT NULL COMMENT '创建人',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_user` varchar(64) DEFAULT NULL COMMENT '修改人',

 doc/20260608_ƾ֤·Ö¼¿ÆÄ¿Ã÷ϸ×Ö¶ÎÇ°¶ËÁªµ÷Îĵµ.md

¶Ô±ÈÐÂÎļþ
@@ -0,0 +1,275 @@
# å‡­è¯åˆ†å½•ç§‘目明细字段前端联调文档

> æ–‡æ¡£æ—¥æœŸï¼š2026-06-08
> å…³è”模块：财务管理 - å‡­è¯ / ç§‘目明细账

---

## 1. å˜æ›´æ¦‚è¿°

在**凭证分录**中新增 `subjectDetail`（科目明细）字段，字符串类型，由用户在前端输入，随凭证保存/修改接口传入后端，并在以下场景反显：

1. **凭证详情** (`GET /financial/voucher/detail/{id}`)
2. **科目明细账查询** (`GET /financial/ledger/detail`)

---

## 2. æ•°æ®åº“变更

### 2.1 æ–°å¢žå­—段

```sql
ALTER TABLE fin_voucher_entry
ADD COLUMN subject_detail VARCHAR(255) DEFAULT NULL COMMENT '科目明细' AFTER auxiliary_name;
```

---

## 3. æŽ¥å£å˜æ›´

### 3.1 å‡­è¯æ–°å¢ž /financial/voucher/add

**Method**: `POST`

**Request Body** ç¤ºä¾‹ï¼š

```json
{
  "voucherNo": "è®°-0001",
  "voucherDate": "2026-06-08",
  "summary": "采购原材料",
  "creator": "张三",
  "attachmentCount": 0,
  "remark": "",
  "entries": [
    {
      "subjectCode": "1403",
      "subjectName": "原材料",
      "summary": "采购A材料",
      "debit": 5000.00,
      "credit": 0,
      "subjectDetail": "A材料-规格型号001"
    },
    {
      "subjectCode": "1002",
      "subjectName": "银行存款",
      "summary": "支付货款",
      "debit": 0,
      "credit": 5000.00,
      "subjectDetail": "工商银行-基本户"
    }
  ]
}
```

**变更说明**：
- `entries` æ•°ç»„中每条分录对象新增 `subjectDetail` å­—段（可选，字符串）。
- å‰ç«¯åœ¨åˆ†å½•è¡Œä¸­å¢žåŠ è¾“入框，供用户填写科目明细。

---

### 3.2 å‡­è¯ä¿®æ”¹ /financial/voucher/update

**Method**: `PUT`

**Request Body** ç¤ºä¾‹ï¼š

```json
{
  "id": 1,
  "voucherNo": "è®°-0001",
  "voucherDate": "2026-06-08",
  "summary": "采购原材料",
  "creator": "张三",
  "attachmentCount": 0,
  "remark": "",
  "entries": [
    {
      "subjectCode": "1403",
      "subjectName": "原材料",
      "summary": "采购A材料",
      "debit": 5000.00,
      "credit": 0,
      "subjectDetail": "A材料-规格型号001"
    },
    {
      "subjectCode": "1002",
      "subjectName": "银行存款",
      "summary": "支付货款",
      "debit": 0,
      "credit": 5000.00,
      "subjectDetail": "工商银行-基本户"
    }
  ]
}
```

**变更说明**：
- åŒæ–°å¢žæŽ¥å£ï¼Œ`entries` ä¸­æ¯æ¡åˆ†å½•æ”¯æŒ `subjectDetail`。
- ä¿®æ”¹æ—¶å‰ç«¯éœ€å°†åŽŸæœ‰ `subjectDetail` å€¼å›žæ˜¾åˆ°è¾“入框中。

---

### 3.3 å‡­è¯è¯¦æƒ… /financial/voucher/detail/{id}

**Method**: `GET`

**Response** ç¤ºä¾‹ï¼š

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "voucherNo": "è®°-0001",
    "voucherDate": "2026-06-08",
    "summary": "采购原材料",
    "creator": "张三",
    "status": "unposted",
    "attachmentCount": 0,
    "remark": "",
    "entries": [
      {
        "id": 1,
        "voucherId": 1,
        "rowNo": 1,
        "subjectCode": "1403",
        "subjectName": "原材料",
        "summary": "采购A材料",
        "debit": 5000.00,
        "credit": 0.00,
        "auxiliaryType": null,
        "auxiliaryId": null,
        "auxiliaryName": null,
        "subjectDetail": "A材料-规格型号001",
        "createUser": "admin",
        "createTime": "2026-06-08T10:00:00",
        "updateUser": "admin",
        "updateTime": "2026-06-08T10:00:00",
        "deptId": 1
      },
      {
        "id": 2,
        "voucherId": 1,
        "rowNo": 2,
        "subjectCode": "1002",
        "subjectName": "银行存款",
        "summary": "支付货款",
        "debit": 0.00,
        "credit": 5000.00,
        "auxiliaryType": null,
        "auxiliaryId": null,
        "auxiliaryName": null,
        "subjectDetail": "工商银行-基本户",
        "createUser": "admin",
        "createTime": "2026-06-08T10:00:00",
        "updateUser": "admin",
        "updateTime": "2026-06-08T10:00:00",
        "deptId": 1
      }
    ]
  }
}
```

**变更说明**：
- `entries` æ•°ç»„中每条分录对象新增 `subjectDetail` å­—段。
- å‰ç«¯åœ¨è¯¦æƒ…页分录列表中增加一列显示 `subjectDetail`。

---

### 3.4 ç§‘目明细账查询 /financial/ledger/detail

**Method**: `GET`

**Query å‚æ•°**：
- `subjectCode`（必填）
- `auxiliaryType`（可选）
- `auxiliaryId`（可选）
- `startMonth`（YYYY-MM）
- `endMonth`（YYYY-MM）

**Response** ç¤ºä¾‹ï¼š

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "rowType": "opening",
      "date": "2026-06-01",
      "voucherNo": "-",
      "summary": "期初余额",
      "debit": 0.00,
      "credit": 0.00,
      "direction": "借",
      "balance": 10000.00
    },
    {
      "rowType": "entry",
      "date": "2026-06-08",
      "voucherNo": "è®°-0001",
      "summary": "采购A材料",
      "subjectDetail": "A材料-规格型号001",
      "debit": 5000.00,
      "credit": 0.00,
      "direction": "借",
      "balance": 15000.00
    },
    {
      "rowType": "monthly_total",
      "date": "2026-06-30",
      "voucherNo": "-",
      "summary": "本月合计",
      "debit": 5000.00,
      "credit": 0.00,
      "direction": "借",
      "balance": 15000.00
    },
    {
      "rowType": "yearly_total",
      "date": "2026-06-30",
      "voucherNo": "-",
      "summary": "合计",
      "debit": 5000.00,
      "credit": 0.00,
      "direction": "借",
      "balance": 15000.00
    }
  ]
}
```

**变更说明**：
- å½“ `rowType` ä¸º `entry`（分录行）时，新增 `subjectDetail` å­—段返回。
- `opening`、`monthly_total`、`yearly_total` è¡Œä¸è¿”回 `subjectDetail`（字段为 `null`，JSON ä¸­ä¸æ˜¾ç¤ºï¼‰ã€‚
- å‰ç«¯åœ¨ç§‘目明细账表格中，分录行增加一列显示 `subjectDetail`。

---

## 4. å‰ç«¯ä¿®æ”¹ç‚¹æ±‡æ€»

| é¡µé¢/组件 | ä¿®æ”¹å†…容 |
|-----------|----------|
| å‡­è¯æ–°å¢žé¡µ | åˆ†å½•è¡¨æ ¼æ¯è¡Œå¢žåŠ ã€Œç§‘目明细」输入框，字段名 `subjectDetail` |
| å‡­è¯ä¿®æ”¹é¡µ | åŒä¸Šï¼Œä¸”需从详情接口回显 `subjectDetail` å€¼ |
| å‡­è¯è¯¦æƒ…页 | åˆ†å½•åˆ—表增加「科目明细」展示列 |
| ç§‘目明细账页 | åˆ†å½•è¡Œï¼ˆ`rowType=entry`）增加「科目明细」展示列；期初/合计行不显示 |

---

## 5. å­—段说明

| å­—段名 | ç±»åž‹ | å¿…å¡« | è¯´æ˜Ž |
|--------|------|------|------|
| `subjectDetail` | String | å¦ | ç§‘目明细，用户自定义输入，最大长度 255 å­—符 |

---

## 6. æ³¨æ„äº‹é¡¹

1. `subjectDetail` ä¸ºå¯é€‰å­—段，不传或传空字符串均可正常保存。
2. å‡­è¯è¿‡è´¦/作废状态不影响 `subjectDetail` çš„读取，已过账凭证的 `subjectDetail` ä»å¯åœ¨æ˜Žç»†è´¦ä¸­æŸ¥è¯¢ã€‚
3. ç§‘目明细账中仅 `rowType=entry` çš„行携带 `subjectDetail`，其余合计/期初行不携带该字段。

 src/main/java/com/ruoyi/account/bean/vo/financial/FinLedgerEntryRecordVo.java

@@ -37,6 +37,11 @@
    private BigDecimal credit;

    /**
     * ç§‘目明细。
     */
    private String subjectDetail;

    /**
     * è¡Œå·ï¼ˆæŽ’序字段）。
     */
    private Integer rowNo;

 src/main/java/com/ruoyi/account/bean/vo/financial/FinLedgerRowVo.java

@@ -34,6 +34,11 @@
    private String summary;

    /**
     * ç§‘目明细。
     */
    private String subjectDetail;

    /**
     * å€Ÿæ–¹é‡‘额。
     */
    private BigDecimal debit;

 src/main/java/com/ruoyi/account/pojo/financial/FinVoucherEntry.java

@@ -63,6 +63,9 @@
    @ApiModelProperty("辅助核算对象名称")
    private String auxiliaryName;

    @ApiModelProperty("科目明细")
    private String subjectDetail;

    @ApiModelProperty("创建人")
    @TableField(fill = FieldFill.INSERT)
    private String createUser;

 src/main/java/com/ruoyi/account/service/impl/financial/FinLedgerServiceImpl.java

@@ -101,6 +101,7 @@
                row.setDate(entry.getVoucherDate());
                row.setVoucherNo(entry.getVoucherNo());
                row.setSummary(StringUtils.isNotEmpty(entry.getSummary()) ? entry.getSummary() : "");
                row.setSubjectDetail(entry.getSubjectDetail());
                row.setDebit(debit);
                row.setCredit(credit);
                row.setBalance(money(runningBalance));

 src/main/resources/application-dev.yml

@@ -74,7 +74,7 @@
    druid:
      # ä¸»åº“数据源
      master:
        url: jdbc:mysql://localhost:3306/product-inventory-management-new-pro?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        url: jdbc:mysql://localhost:3306/product-inventory-management-bdpro?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
        username: root
        password: 123456
      # ä»Žåº“数据源

 src/main/resources/mapper/account/financial/FinVoucherEntryMapper.xml

@@ -14,6 +14,7 @@
        <result column="auxiliary_type" property="auxiliaryType"/>
        <result column="auxiliary_id" property="auxiliaryId"/>
        <result column="auxiliary_name" property="auxiliaryName"/>
        <result column="subject_detail" property="subjectDetail"/>
        <result column="create_user" property="createUser"/>
        <result column="create_time" property="createTime"/>
        <result column="update_user" property="updateUser"/>
@@ -31,6 +32,7 @@
            END AS summary,
            e.debit AS debit,
            e.credit AS credit,
            e.subject_detail AS subjectDetail,
            e.row_no AS rowNo
        FROM fin_voucher_entry e
        INNER JOIN fin_voucher v ON e.voucher_id = v.id
@@ -57,6 +59,7 @@
            END AS summary,
            e.debit AS debit,
            e.credit AS credit,
            e.subject_detail AS subjectDetail,
            e.row_no AS rowNo
        FROM fin_voucher_entry e
        INNER JOIN fin_voucher v ON e.voucher_id = v.id