API接口文档：费用支付接口（fee.payFee）

1. 接口名称

费用支付接口

2. 接口描述

该接口用于处理用户缴纳物业费用（如物业费、停车费、维修费等），支持现金、转账、账户抵扣等多种支付方式，并记录缴费明细。

3. 接口路径

http://{domain}/app/fee.payFee
（通过Java110Cmd的serviceCode = "fee.payFee"触发）

4. 请求方法

POST

5. 请求头

参数名称	必填	类型	描述
Authorization	是	String	用户认证Token（Base64编码）
app-id	是	String	应用ID（由系统分配）
transaction-id	是	String	请求流水号（格式：`1000000000+YYYYMMDDhhmmss+6位序列`）
sign	是	String	请求签名（防篡改校验）
req-time	是	String	请求时间（`YYYYMMDDhhmmss`）

6. 请求参数

6.1 请求体（JSON格式）

参数名称	必填	类型	描述
communityId	是	String	小区ID
feeId	是	String	费用ID（需唯一标识待缴费项）
cycles	是	String	缴费周期（单位：月，或特殊值`-105`表示自定义时间段）
receivedAmount	是	BigDecimal	实收金额（单位：元，精确到分）
primeRate	否	String	支付方式（如现金、微信、支付宝等）
custEndTime	条件	String	自定义结束时间（当`cycles=-105`时必填，格式：`yyyy-MM-dd HH:mm:ss`）
customStartTime	条件	String	自定义开始时间（当`cycles=-105`时必填）
selectDiscount	否	Array	优惠信息（见下方子字段）
selectUserAccount	否	Array	账户抵扣信息（见下方子字段）

子字段说明：

selectDiscount（优惠信息）：

[{
  "discountId": "优惠ID",
  "discountPrice": "优惠金额",
  "ardId": "空置房折扣申请ID（可选）"
}]

selectUserAccount（账户抵扣信息）：

[{
  "acctId": "账户ID",
  "amount": "抵扣金额"
}]

7. 返回值

7.1 响应格式（JSON）

参数名称	类型	描述
code	String	返回码（`0`成功，其他失败）
msg	String	返回消息（如失败原因）
data	Object	缴费明细数据（见下方）

data字段结构：

{
  "detailId": "缴费明细ID",
  "receiptCode": "收据编号",
  "startTime": "费用开始时间",
  "endTime": "费用结束时间",
  "receivedAmount": "实收金额"
}

7.2 状态码说明

状态码	含义	可能原因
0	成功	-
1001	参数校验失败	必填字段缺失或格式错误
2001	费用已结束	该费用项已无法再缴费
3001	账户余额不足	抵扣金额大于账户余额
5001	系统异常	数据库操作失败或分布式锁冲突

8. 示例请求

POST /app/fee.payFee
Headers:
  Authorization: Bearer xxxxxx
  app-id: hc_micro_community
  transaction-id: 100000000020240101120000000001
  sign: xxxxxx
  req-time: 20240101120000

Body:
{
  "communityId": "123456789",
  "feeId": "FEE_20240001",
  "cycles": "12",
  "receivedAmount": "3600.00",
  "primeRate": "CASH",
  "selectDiscount": [{
    "discountId": "DISC_001",
    "discountPrice": "200.00"
  }],
  "selectUserAccount": [{
    "acctId": "ACCT_001",
    "amount": "1000.00"
  }]
}

9. 示例响应

{
  "code": "0",
  "msg": "成功",
  "data": {
    "detailId": "DETAIL_20240001",
    "receiptCode": "RC20240001",
    "startTime": "2024-01-01 00:00:00",
    "endTime": "2025-01-01 23:59:59",
    "receivedAmount": "3600.00"
  }
}

10. 业务逻辑说明

校验阶段：
- 检查费用状态是否可缴费（非STATE_FINISH）。
- 验证缴费周期是否超过费用项截止时间。
- 校验优惠信息合法性（如折扣ID是否存在）。
核心操作：
- 生成缴费明细（PayFeeDetailPo）和更新费用时间（PayFeePo）。
- 处理账户抵扣（调用accountInnerServiceSMOImpl.withholdAccount）。
- 若为自定义时间段缴费（cycles=-105），自动生成欠费记录。
关联操作：
- 更新停车位/房屋的到期时间（通过finishFeeNotifyImpl）。
- 修改报修单状态（如维修费支付后标记为已完成）。

11. 注意事项

幂等性：接口通过分布式锁（DistributedLock）保证并发安全。
金额精度：所有金额字段需保留2位小数（BigDecimal.ROUND_HALF_UP）。
时间格式：日期时间需严格遵循yyyy-MM-dd HH:mm:ss格式。

基础接口

资产接口

业主接口

费用接口

工单接口