# 财务管理后端文档（仅负责模块）

更新时间：2026-05-12  
适用范围（仅以下 6 个模块）：
1. 固定资产（`/financial/fixed-assets`）
2. 无形资产（`/financial/intangible-assets`）
3. 总账科目（`/financial/general-ledger`）
4. 凭证（`/financial/voucher`）
5. 科目总账（`/financial/voucher-general-ledger`）
6. 科目明细账（`/financial/voucher-detail-ledger`）

---

## 1. 统一约定

### 1.1 响应结构
```json
{
  "code": 200,
  "msg": "success",
  "data": {}
}
```

### 1.2 分页结构（如果是分页接口）
请求参数建议：
- `current`（页码）
- `size`（每页条数）

响应建议：
```json
{
  "code": 200,
  "data": {
    "records": [],
    "total": 0
  }
}
```

### 1.3 金额与精度
- 金额字段建议 `decimal(18,2)`。
- 前后端统一保留两位小数。

---

## 2. 模块一：总账科目（已接真实 API）

前端文件：`src/views/financialManagement/generalLedger/index.vue`  
API 文件：`src/api/financialManagement/accountSubject.js`

### 2.1 接口现状
- `GET /accountSubject/list`
- `POST /accountSubject/add`
- `PUT /accountSubject/edit`
- `DELETE /accountSubject/remove/{ids}`
- `POST /accountSubject/export`

### 2.2 字段模型
- `id`
- `subjectCode`（科目编码）
- `subjectName`（科目名称）
- `subjectType`（科目类型）
- `balanceDirection`（余额方向：借方/贷方）
- `status`（0 启用，1 禁用）
- `remark`

### 2.3 业务规则
- `subjectCode`、`subjectName`、`subjectType` 必填。
- 删除需要做引用校验（若已被凭证分录引用，不允许删除）。

---

## 3. 模块二：固定资产（当前前端为 mock，待后端实现）

前端文件：`src/views/financialManagement/assets/fixedAssets.vue`

### 3.1 建议接口
- `GET /financial/fixedAsset/page`
- `POST /financial/fixedAsset/add`
- `PUT /financial/fixedAsset/update`
- `DELETE /financial/fixedAsset/delete`
- `POST /financial/fixedAsset/depreciate`（按月计提）

### 3.2 字段模型
- `id, assetCode, assetName, category, specification`
- `purchaseDate, originalValue, usefulLife, residualRate`
- `accumulatedDepreciation, netValue`
- `location, department, keeper, status, remark`

### 3.3 核心公式（必须一致）
- `monthlyDepreciation = originalValue * (1 - residualRate/100) / (usefulLife*12)`
- `accumulatedDepreciation += monthlyDepreciation`
- `netValue = originalValue - accumulatedDepreciation`

### 3.4 状态建议
- `in_use`（在用）
- `idle`（闲置）
- `repair`（维修中）
- `scrapped`（报废）

---

## 4. 模块三：无形资产（当前前端为 mock，待后端实现）

前端文件：`src/views/financialManagement/assets/intangibleAssets.vue`

### 4.1 建议接口
- `GET /financial/intangibleAsset/page`
- `POST /financial/intangibleAsset/add`
- `PUT /financial/intangibleAsset/update`
- `DELETE /financial/intangibleAsset/delete`
- `POST /financial/intangibleAsset/amortize`（按月摊销）

### 4.2 字段模型
- `id, assetCode, assetName, category, certificateNo`
- `acquisitionDate, originalValue, amortizationPeriod, residualRate`
- `accumulatedAmortization, netValue`
- `validityDate, status, description, remark`

### 4.3 核心公式（必须一致）
- `monthlyAmortization = originalValue * (1 - residualRate/100) / (amortizationPeriod*12)`
- `accumulatedAmortization += monthlyAmortization`
- `netValue = originalValue - accumulatedAmortization`
- 当 `netValue <= 0`：
  - `netValue = 0`
  - `status = amortized`

### 4.4 状态建议
- `in_use`（在用）
- `expired`（到期）
- `amortized`（已摊销完）

---

## 5. 模块四：凭证（当前前端为 mock，待后端实现）

前端文件：`src/views/financialManagement/voucher/index.vue`

### 5.1 建议接口
- `GET /financial/voucher/page`
- `POST /financial/voucher/add`
- `PUT /financial/voucher/update`
- `POST /financial/voucher/post`（过账）
- `POST /financial/voucher/cancel`（作废）
- `GET /financial/voucher/detail/{id}`

### 5.2 主表字段
- `id, voucherNo, voucherDate, summary`
- `debit, credit, creator, status, attachmentCount, remark`

### 5.3 分录字段
- `subjectCode, subjectName, summary, debit, credit`

### 5.4 关键校验
- 分录至少一条有效行（科目不空，且借方或贷方 > 0）。
- 借贷平衡：`sum(debit) == sum(credit)` 且 > 0，不满足禁止保存。

### 5.5 状态流转
- `unposted -> posted`
- `unposted -> cancelled`

---

## 6. 模块五：科目总账（当前前端为 mock，待后端实现）

前端文件：`src/views/financialManagement/voucher/generalLedger.vue`

### 6.1 建议接口
- `GET /financial/ledger/general`

### 6.2 请求参数
- `subjectCode`（末级或指定科目）
- `startMonth`（YYYY-MM）
- `endMonth`（YYYY-MM）

### 6.3 响应字段
- `date, voucherNo, summary`
- `debit, credit, direction, balance`

### 6.4 规则
- 仅在选择科目后返回数据。
- 支持“期初余额 / 本月合计 / 本年累计”行（可通过 `rowType` 字段区分）。

---

## 7. 模块六：科目明细账（当前前端为 mock，待后端实现）

前端文件：`src/views/financialManagement/voucher/detailLedger.vue`

### 7.1 建议接口
- `GET /financial/ledger/detail`

### 7.2 请求参数
- `subjectCode`
- `auxiliaryType`（customer/supplier/department/employee/project）
- `auxiliaryId`
- `startMonth`（YYYY-MM）
- `endMonth`（YYYY-MM）

### 7.3 响应字段
- `date, voucherNo, summary`
- `debit, credit, direction, balance`

### 7.4 规则
- 先选科目，再查明细。
- 辅助核算条件为可选，但建议后端支持维度过滤。

---

## 8. 推荐最小表设计（仅本范围）

- `fin_account_subject`
- `fin_fixed_asset`
- `fin_intangible_asset`
- `fin_voucher`
- `fin_voucher_entry`
- `fin_ledger_snapshot_general`（可选，做性能优化）
- `fin_ledger_snapshot_detail`（可选，做性能优化）

---

## 9. AI 生成后端任务顺序（建议）

1. 先完成 **总账科目**（已有 API，最稳定）。  
2. 完成 **凭证 + 分录 + 借贷平衡校验 + 状态流转**。  
3. 实现 **科目总账 / 科目明细账** 查询。  
4. 实现 **固定资产折旧** 与 **无形资产摊销**。  
5. 补测试：  
   - 借贷平衡校验  
   - 折旧/摊销公式  
   - 科目被引用禁止删除