diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 1531876..a3e9101 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -114,6 +114,7 @@ > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。 +| 2026-03-12 | `03_Interface_Design` 补齐 SYS-002 高优先接口字段定义 | 对 `docs/design/03_Technical_Design/03_Interface_Design.md` 补齐本周开发所需的高优先 `SYS-002` 接口定义：1）新增 `IF-REV-007/009/012`、`IF-CS-001/002/004`、`IF-METER-001/003/004`、`IF-INST-001/002/004/005` 的关键接口说明；2）补齐上述接口的字段级请求/响应定义；3）统一请求字段、响应字段、主表映射和结果状态口径；4）将主文档 `last_reviewed` 更新为 `2026-03-12`。 | 用户明确要求优先补齐 `SYS-002` 文档内容，以便本周直接启动开发。 | 正面影响，接口主文档从“模块说明齐全但字段定义局部缺失”提升为“开发可直接参照”的状态；开发时能直接按接口字段、状态枚举和主表映射拆分 Controller/Service/VO，减少反复追问和返工。 | | 2026-03-12 | `15_INST_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/15_INST_Detailed.md` 执行与 `REV/CS/METER` 同步的结构化补完：1）新增“报装模块统一约束”与“接口与数据追溯矩阵”；2）为 `INST-001~INST-005` 补充核心数据、接口映射与落地边界；3）为 `INST-001/002/003` 增加申请、踏勘、施工验收流程图；4）明确 `biz_process*`/`biz_content*` 为当前实现态口径，`installation_*` 为专题扩展口径。 | 用户要求优先补齐 `SYS-002` 文档内容，形成本周可直接支撑开发的闭环模块。 | 正面影响，`SYS-002` 四大业务模块正文结构统一，报装链路从受理到归档的开发边界更清晰；实现态与设计态口径分离后，可减少开发阶段对专题扩展表的误读。 | | 2026-03-11 | `14_METER_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/14_METER_Detailed.md` 执行与 REV/CS 同步的结构化补完：1）新增“表务模块统一约束”与“接口与数据追溯矩阵”；2）为 `METER-001~METER-004` 补充核心数据、接口映射与落地边界；3）为 `METER-002` 增加工单处理流程图；4）为 `METER-004` 补充关键规则，明确 IoT 数据进入营收开账链路前的校验与异常处理边界。 | 用户要求继续同步分模块正文模板，提升表务模块评审可读性与跨文档追溯一致性。 | 正面影响，表务模块从简要提纲升级为可交付的结构化详细设计，设备档案、工单、库存、物联网接入与营收系统的协同边界更清晰，可降低联调与后续维护中的口径偏差。 | | 2026-03-11 | `13_CS_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/13_CS_Detailed.md` 执行与 REV 同步的结构化补完：1）新增“客户服务模块统一约束”与“接口与数据追溯矩阵”；2）为 `CS-001~CS-007` 全模块补充“接口映射”；3）补充 `CS-005`、`CS-006` 核心数据与各模块落地边界；4）为 `CS-003`、`CS-007` 增加支付相关流程图，强化渠道侧到营收侧的协同链路表达。 | 用户要求继续将“统一约束 + 追溯矩阵 + 接口映射”模板同步到 `13_CS_Detailed.md`。 | 正面影响，客户服务模块文档结构与营收模块保持一致，接口追溯与评审路径更清晰；渠道受理与 `SYS-002/008/009/010` 协同边界明确，可降低后续改稿与联调阶段的口径偏差。 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 5233e59..6fb95e6 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -138,6 +138,15 @@ ## ✅ 最新完成任务 (持续更新) +### 📋 `03_Interface_Design` 高优先接口字段补完 + +- [x] **完成 `SYS-002` 本周开发高优先接口字段定义补齐** ✅ (2026-03-12) + - [x] 新增 `IF-REV-007/009/012` 的关键接口说明与字段级请求/响应定义 ✅ + - [x] 新增 `IF-CS-001/002/004` 的关键接口说明与字段级请求/响应定义 ✅ + - [x] 新增 `IF-METER-001/003/004` 的关键接口说明与字段级请求/响应定义 ✅ + - [x] 新增 `IF-INST-001/002/004/005` 的关键接口说明与字段级请求/响应定义 ✅ + - [x] 统一主表映射、状态口径与 `last_reviewed` 日期 ✅ + ### 📋 `15_INST_Detailed` 模板同步补完 - [x] **完成报装与签章模块结构与追溯增强** ✅ (2026-03-12) diff --git a/docs/design/03_Technical_Design/03_Interface_Design.md b/docs/design/03_Technical_Design/03_Interface_Design.md index eb37956..34c78b4 100644 --- a/docs/design/03_Technical_Design/03_Interface_Design.md +++ b/docs/design/03_Technical_Design/03_Interface_Design.md @@ -4,7 +4,7 @@ doc_role: master_document authority: primary scope: 接口设计 source_of_truth: true -last_reviewed: 2026-03-11 +last_reviewed: 2026-03-12 retrieval_priority: P0 --- @@ -384,6 +384,17 @@ retrieval_priority: P0 | 功能描述 | 处理柜台收费、预存抵扣、渠道收款确认与账单核销 | | 核心表 | `biz_collection`、`biz_charge`、`bk_transaction` | +### IF-REV-007 账务调整接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-REV-007 | +| 归属模块 | REV-004 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/revenue/accounting/adjust` | +| 功能描述 | 发起金额调整、水量调整、退款、冲正、坏账等账务处理 | +| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` | + ### IF-REV-008 发票申请接口 | 项目 | 说明 | @@ -399,6 +410,17 @@ retrieval_priority: P0 - 发票开具、作废、红冲能力由 `SYS-008` 统一承接。 - `SYS-002` 仅负责业务单据归集、申请发起与结果落账。 +### IF-REV-009 催缴任务接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-REV-009 | +| 归属模块 | REV-006 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/revenue/arrears/remind-task/create` | +| 功能描述 | 生成催缴名单、调用消息服务并回写催缴任务执行结果 | +| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` | + ### IF-REV-011 银行代收协同接口 | 项目 | 说明 | @@ -410,6 +432,39 @@ retrieval_priority: P0 | 功能描述 | 创建代扣批次、发起对账、接收结算回写 | | 核心表 | `biz_withholding`、`bk_withholding_batch`、`bk_reconcile_batch`、`bk_settlement_batch` | +### IF-REV-012 业务参数配置接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-REV-012 | +| 归属模块 | REV-009 | +| 请求方式 | GET / POST | +| 请求路径 | `/admin-api/revenue/parameter/config` | +| 功能描述 | 查询与维护价格模板、业务参数、页面参数与规则配置 | +| 核心表 | `biz_parameter_settings`、`biz_price_*`、`biz_page_settings*` | + +### IF-CS-001 账户绑定接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-CS-001 | +| 归属模块 | CS-001 | +| 请求方式 | POST | +| 请求路径 | `/app-api/customer/account/bind` | +| 功能描述 | 绑定、解绑、切换默认客户账户，并校验渠道身份与客户关系 | +| 核心表 | `biz_cust_app_binds`、`biz_cust`、`biz_account` | + +### IF-CS-002 历史账单查询接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-CS-002 | +| 归属模块 | CS-002 | +| 请求方式 | GET | +| 请求路径 | `/app-api/customer/bill/history` | +| 功能描述 | 查询账单、欠费、缴费、用水历史及发票摘要 | +| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_reading_data`、`biz_invoice` | + ### IF-CS-003 在线支付下单接口 | 项目 | 说明 | @@ -425,6 +480,17 @@ retrieval_priority: P0 - 支付通道、支付回调、对账流水由 `SYS-009` 负责。 - `SYS-002` 负责校验待缴账单、生成业务订单、更新核销结果。 +### IF-CS-004 发票申请接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-CS-004 | +| 归属模块 | CS-004 | +| 请求方式 | POST | +| 请求路径 | `/app-api/customer/invoice/apply` | +| 功能描述 | 面向客户渠道提交电子发票申请并查询开票状态 | +| 核心表 | `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate` | + ### IF-CS-006 业务办理进度接口 | 项目 | 说明 | @@ -447,6 +513,17 @@ retrieval_priority: P0 | 功能描述 | 柜台生成扫码订单，接收支付结果并回写收费状态 | | 核心表 | `biz_collection`、`bk_transaction`、`biz_charge` | +### IF-METER-001 水表档案查询接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-METER-001 | +| 归属模块 | METER-001 | +| 请求方式 | GET | +| 请求路径 | `/admin-api/meter/archive/{id}` | +| 功能描述 | 查询水表档案、状态、参数与生命周期信息 | +| 核心表 | `biz_meter`、`biz_meter_model`、`biz_meter_caliber`、`biz_meter_range` | + ### IF-METER-002 表务工单处理接口 | 项目 | 说明 | @@ -458,6 +535,50 @@ retrieval_priority: P0 | 功能描述 | 提交换表、移表、校表、维修等工单处理结果并回写设备状态 | | 核心表 | `biz_meter_log`、`biz_process`、`biz_process_transfer` | +### IF-METER-003 库存出入库接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-METER-003 | +| 归属模块 | METER-003 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/meter/stock/in-out` | +| 功能描述 | 处理领用、退库、报废等库存动作并更新生命周期状态 | +| 核心表 | `biz_meter_in_out`、`biz_meter_in_out_rel`、`biz_meter` | + +### IF-METER-004 集抄数据接收接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-METER-004 | +| 归属模块 | METER-004 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/meter/iot/reading/receive` | +| 功能描述 | 接收远传抄表、设备状态和异常告警并同步读数状态 | +| 核心表 | `biz_reading_data`、`biz_meter_read`、`biz_last_reading` | + +### IF-INST-001 报装申请提交接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-INST-001 | +| 归属模块 | INST-001 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/installation/apply/create` | +| 功能描述 | 提交报装申请、基础资料与附件，并创建流程实例 | +| 核心表 | `biz_process`、`biz_content`、`biz_content_attach` | + +### IF-INST-002 踏勘结果回填接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-INST-002 | +| 归属模块 | INST-002 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/installation/survey/result` | +| 功能描述 | 回填现场踏勘结果、方案版本和审核结论 | +| 核心表 | `biz_process_transfer`、`biz_business_datas` | + ### IF-INST-003 合同签署发起接口 | 项目 | 说明 | @@ -469,6 +590,28 @@ retrieval_priority: P0 | 功能描述 | 发起报装合同签署流程，并与 CA 系统协同处理签章、时间戳和存证 | | 核心表 | `installation_contract`、`installation_signature`、`installation_evidence` | +### IF-INST-004 签章回执接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-INST-004 | +| 归属模块 | INST-004 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/installation/contract/sign/callback` | +| 功能描述 | 回写签章结果、时间戳、存证回执与签章文件地址 | +| 核心表 | `installation_signature`、`installation_evidence` | + +### IF-INST-005 报装归档接口 + +| 项目 | 说明 | +|------|------| +| 接口编号 | IF-INST-005 | +| 归属模块 | INST-005 | +| 请求方式 | POST | +| 请求路径 | `/admin-api/installation/archive/submit` | +| 功能描述 | 归档申请资料、验收附件、合同文件与签章回执 | +| 核心表 | `biz_content_attach`、`installation_evidence`、`biz_process` | + ## 字段级请求与响应定义 > 说明：以下字段级定义服务于接口设计说明，重点体现业务含义、来源对象与跨系统协同所需关键字段，不等同于数据库表的完整字段清单。 @@ -583,6 +726,33 @@ retrieval_priority: P0 | tradeNo | String | 渠道交易流水号 | `bk_transaction.trade_no` | | invoiceAvailable | Boolean | 是否可发起开票 | 业务判断 | +### IF-REV-007 账务调整接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| chargeId | Long | 是 | 目标账单 ID | `biz_charge.id` | +| adjustType | String | 是 | 调整类型：`USAGE`、`AMOUNT`、`REFUND`、`REVERSE`、`BAD_DEBT` | 业务类型 | +| adjustAmount | Decimal | 否 | 调整金额 | `biz_charge_detail` / 业务计算 | +| adjustUsage | Decimal | 否 | 调整水量 | 业务计算 | +| sourceTradeNo | String | 否 | 原交易流水号，退款/冲正场景使用 | `bk_transaction.trade_no` | +| reasonCode | String | 是 | 调整原因编码 | 业务字典 | +| remark | String | 否 | 调整说明 | `biz_operat_log.remark` | +| attachmentList | Array | 否 | 依据附件 | 附件系统 | +| operatorId | Long | 是 | 操作人 ID | 操作上下文 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| adjustmentNo | String | 调整业务编号 | 业务流水 | +| chargeId | Long | 目标账单 ID | `biz_charge.id` | +| resultStatus | String | 处理状态：`SUCCESS`、`PENDING_APPROVAL`、`FAIL` | 业务状态 | +| writeBackStatus | String | 账单回写状态 | 业务状态 | +| approvalRequired | Boolean | 是否进入审批 | 流程判断 | +| msg | String | 处理说明 | 返回消息 | + ### IF-REV-008 发票申请接口 #### 请求参数 @@ -609,6 +779,32 @@ retrieval_priority: P0 | fileUrl | String | 发票文件地址，成功后返回 | 结果回写 | | msg | String | 处理说明 | 返回消息 | +### IF-REV-009 催缴任务接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| taskType | String | 是 | 任务类型：`AUTO`、`MANUAL` | 任务参数 | +| billPeriod | String | 否 | 账期范围 | `biz_charge.bill_period` | +| minArrearsAmount | Decimal | 否 | 最小欠费金额 | 任务筛选条件 | +| overdueDays | Integer | 否 | 最小逾期天数 | 任务筛选条件 | +| templateCode | String | 是 | 消息模板编码 | 模板参数 | +| channelList | Array | 是 | 发送渠道列表，如 `SMS`、`WECHAT`、`APP` | 消息参数 | +| customerScope | Array | 否 | 指定客户范围 | `biz_charge.cust_id` | +| operatorId | Long | 否 | 发起人 ID | 操作上下文 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| taskNo | String | 催缴任务编号 | 业务流水 | +| generateCount | Integer | 生成催缴对象数量 | 汇总结果 | +| sendCount | Integer | 已发送数量 | 消息结果 | +| failCount | Integer | 发送失败数量 | 消息结果 | +| pendingReviewCount | Integer | 待人工复核数量 | 业务判断 | +| msg | String | 处理说明 | 返回消息 | + ### IF-REV-011 银行代收协同接口 #### 请求参数 @@ -636,6 +832,104 @@ retrieval_priority: P0 | settlementStatus | String | 结算状态 | `bk_settlement_batch.status` | | diffList | Array | 差异清单摘要 | `bk_reconcile_diff` | +### IF-REV-012 业务参数配置接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| action | String | 是 | 动作：`QUERY`、`CREATE`、`UPDATE` | 配置动作 | +| configType | String | 是 | 配置类型：`PRICE`、`RULE`、`PAGE`、`NOTICE` | `biz_parameter_settings.config_type` | +| configCode | String | 否 | 配置编码 | `biz_parameter_settings.config_code` | +| configValue | String | 否 | 配置值或 JSON 内容 | `biz_parameter_settings.config_value` | +| deptId | Long | 否 | 生效单位 | 作用域参数 | +| effectiveDate | Date | 否 | 生效日期 | 生效控制 | +| operatorId | Long | 否 | 操作人 ID | 操作上下文 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| configId | Long | 配置主键 | `biz_parameter_settings.id` | +| configCode | String | 配置编码 | `biz_parameter_settings.config_code` | +| configVersion | String | 配置版本 | 版本信息 | +| effectScope | String | 生效范围 | 作用域结果 | +| effectStatus | String | 生效状态：`DRAFT`、`ACTIVE`、`EXPIRED` | 业务状态 | +| msg | String | 处理说明 | 返回消息 | + +### IF-CS-001 账户绑定接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| action | String | 是 | 动作：`BIND`、`UNBIND`、`SET_DEFAULT` | 绑定动作 | +| channelType | String | 是 | 渠道类型：`WECHAT`、`ALIPAY`、`MINIAPP` | 渠道上下文 | +| channelUserId | String | 是 | 渠道用户标识，如 OpenId | 渠道上下文 | +| custId | Long | 是 | 客户 ID | `biz_cust.id` | +| accountId | Long | 否 | 账户 ID | `biz_account.id` | +| verifyCode | String | 否 | 验证码或身份校验码 | 安全校验 | +| defaultFlag | Boolean | 否 | 是否设为默认账户 | `biz_cust_app_binds.is_default` | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| bindId | Long | 绑定关系 ID | `biz_cust_app_binds.id` | +| bindStatus | String | 绑定状态：`BOUND`、`UNBOUND` | 业务状态 | +| defaultFlag | Boolean | 是否默认账户 | `biz_cust_app_binds.is_default` | +| custSummary | Object | 客户摘要信息 | `biz_cust` | +| msg | String | 处理说明 | 返回消息 | + +### IF-CS-002 历史账单查询接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| custId | Long | 是 | 客户 ID | 客户上下文 | +| queryType | String | 是 | 查询类型：`BILL`、`PAYMENT`、`USAGE`、`ARREARS`、`INVOICE` | 查询控制 | +| billPeriod | String | 否 | 账期，如 `2026-03` | `biz_charge.bill_period` | +| chargeStatus | String | 否 | 账单状态筛选 | `biz_charge.status` | +| pageNo | Integer | 否 | 页码 | 分页参数 | +| pageSize | Integer | 否 | 每页数量 | 分页参数 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| total | Integer | 总记录数 | 分页结果 | +| list | Array | 查询结果列表 | 聚合结果 | +| list[].chargeId | Long | 账单 ID | `biz_charge.id` | +| list[].billPeriod | String | 账期 | `biz_charge.bill_period` | +| list[].usageAmount | Decimal | 用量 | `biz_reading_data.usage_amount` | +| list[].payStatus | String | 缴费状态 | 业务状态 | +| list[].invoiceStatus | String | 开票状态 | `biz_invoice.invoice_status` | + +### IF-CS-004 发票申请接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| custId | Long | 是 | 客户 ID | `biz_invoice.cust_id` | +| chargeIds | Array | 是 | 开票关联账单 ID | 业务单据关联 | +| invoiceTitle | String | 是 | 发票抬头 | `biz_cust_invoice.invoice_title` | +| taxNo | String | 否 | 税号 | `biz_cust_invoice.tax_no` | +| email | String | 否 | 电子发票邮箱 | `biz_cust_invoice.email` | +| mobile | String | 否 | 接收手机号 | `biz_cust_invoice.mobile` | +| invoiceType | String | 否 | 默认 `ELECTRONIC` | `biz_invoice.invoice_type` | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| invoiceId | Long | 发票申请 ID | `biz_invoice.id` | +| invoiceCode | String | 发票申请编号 | `biz_invoice.code` | +| invoiceStatus | String | 当前状态 | `biz_invoice.invoice_status` | +| fileUrl | String | 发票下载地址 | 结果回写 | +| msg | String | 处理说明 | 返回消息 | + ### IF-CS-003 在线支付下单接口 #### 请求参数 @@ -710,6 +1004,171 @@ retrieval_priority: P0 | writeBackStatus | String | 营收状态回写结果 | 业务状态 | | msg | String | 处理说明 | 返回消息 | +### IF-METER-001 水表档案查询接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源 | +|------|------|------|------|----------| +| id | Long | 否 | 水表主键 ID，与 `code` 二选一 | `biz_meter.id` | +| code | String | 否 | 水表编号，与 `id` 二选一 | `biz_meter.code` | +| queryType | String | 否 | 查询类型：`base`、`status`、`lifeCycle`、`all` | 查询控制参数 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| id | Long | 水表主键 ID | `biz_meter.id` | +| code | String | 水表编号 | `biz_meter.code` | +| meterStatus | String | 水表状态 | `biz_meter.status` | +| modelCode | String | 型号编码 | `biz_meter.model_code` | +| caliberCode | String | 口径编码 | `biz_meter.caliber_code` | +| rangeCode | String | 量程编码 | `biz_meter.range_code` | +| installAddress | String | 安装地址 | `biz_meter.install_address` | +| lastReading | Decimal | 最近有效读数 | `biz_last_reading.last_reading` | + +### IF-METER-003 库存出入库接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| action | String | 是 | 动作：`IN`、`OUT`、`RETURN`、`SCRAP` | 库存动作 | +| batchNo | String | 是 | 批次号 | `biz_meter_in_out.batch_no` | +| warehouseCode | String | 否 | 仓库编码 | 仓储参数 | +| meterIds | Array | 是 | 水表 ID 列表 | `biz_meter.id` | +| remark | String | 否 | 出入库说明 | `biz_meter_in_out.remark` | +| operatorId | Long | 是 | 操作人 ID | 操作上下文 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| inOutId | Long | 出入库主记录 ID | `biz_meter_in_out.id` | +| batchNo | String | 批次号 | `biz_meter_in_out.batch_no` | +| actionStatus | String | 处理状态：`SUCCESS`、`PARTIAL`、`FAIL` | 业务状态 | +| successCount | Integer | 成功处理数量 | 汇总结果 | +| failCount | Integer | 失败数量 | 汇总结果 | +| msg | String | 处理说明 | 返回消息 | + +### IF-METER-004 集抄数据接收接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| meterCode | String | 是 | 水表编号 | `biz_meter.code` | +| readTime | Datetime | 是 | 采集时间 | `biz_reading_data.read_time` | +| currentReading | Decimal | 是 | 当前读数 | `biz_reading_data.current_reading` | +| deviceStatus | String | 否 | 设备状态：`ONLINE`、`OFFLINE`、`ALARM` | 设备状态 | +| alarmList | Array | 否 | 告警编码列表 | 告警结果 | +| fileSerialNo | String | 否 | 上送批次或文件序列号 | 幂等辅助键 | +| sourceSystem | String | 是 | 来源系统：`IOT`、`MDC` | 来源标识 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| readingId | Long | 读数记录 ID | `biz_reading_data.id` | +| meterReadId | Long | 对应抄表任务 ID | `biz_meter_read.id` | +| acceptStatus | String | 接收状态：`SUCCESS`、`WARN`、`REJECT` | 处理状态 | +| abnormalFlag | Boolean | 是否异常 | 过程判断 | +| nextAction | String | 后续动作：`BILLING`、`RECHECK`、`MANUAL_REVIEW` | 流程控制 | +| msg | String | 处理说明 | 返回消息 | + +### IF-INST-001 报装申请提交接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| applyType | String | 是 | 报装类型：`NEW`、`REBUILD`、`ONE_METER_ONE_HOME` | 业务类型 | +| applicantName | String | 是 | 申请人姓名 | 申请资料 | +| mobile | String | 是 | 联系手机号 | 申请资料 | +| address | String | 是 | 申请地址 | 申请资料 | +| waterUseType | String | 是 | 用水性质 | 业务字典 | +| sourceChannel | String | 是 | 来源渠道：`COUNTER`、`MINIAPP`、`GOV` | 来源标识 | +| attachmentList | Array | 否 | 申请附件列表 | `biz_content_attach` | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| processId | Long | 流程实例 ID | `biz_process.id` | +| processCode | String | 报装流程编号 | `biz_process.code` | +| processStatus | String | 当前状态：`INIT`、`ACCEPTED`、`SURVEYING` | `biz_process.process_status` | +| acceptStatus | String | 受理结果 | 业务状态 | +| msg | String | 处理说明 | 返回消息 | + +### IF-INST-002 踏勘结果回填接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| processId | Long | 是 | 报装流程 ID | `biz_process.id` | +| schemeVersion | String | 是 | 方案版本号 | `biz_business_datas` | +| surveyResult | String | 是 | 踏勘结论 | `biz_business_datas` | +| estimateAmount | Decimal | 否 | 预估费用 | `biz_business_datas` | +| attachmentList | Array | 否 | 现场照片与方案附件 | `biz_content_attach` | +| auditResult | String | 否 | 审核结果：`PASS`、`REJECT` | 审核结果 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| transferId | Long | 流转记录 ID | `biz_process_transfer.id` | +| processStatus | String | 当前流程状态 | `biz_process.process_status` | +| nextNode | String | 下一节点 | 流程控制 | +| msg | String | 处理说明 | 返回消息 | + +### IF-INST-004 签章回执接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| contractId | Long | 是 | 合同 ID | `installation_contract.id` | +| requestNo | String | 是 | 签章请求号 | 协同流水 | +| signStatus | String | 是 | 签章状态：`SUCCESS`、`FAIL`、`CANCEL` | `installation_signature.signature_status` | +| signerId | String | 否 | 签署人标识 | `installation_signature.signer_id` | +| signatureTime | Datetime | 否 | 签章时间 | `installation_signature.signature_time` | +| evidenceNo | String | 否 | 存证编号 | `installation_evidence.evidence_no` | +| fileUrl | String | 否 | 已签文件地址 | 结果回写 | +| hashValue | String | 否 | 存证哈希 | `installation_evidence.hash_value` | +| resultMsg | String | 否 | 结果说明 | 返回消息 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| signatureId | Long | 签章记录 ID | `installation_signature.id` | +| evidenceId | Long | 存证记录 ID | `installation_evidence.id` | +| writeBackStatus | String | 回写状态：`SUCCESS`、`IGNORE_REPEAT`、`FAIL` | 业务状态 | +| msg | String | 处理说明 | 返回消息 | + +### IF-INST-005 报装归档接口 + +#### 请求参数 + +| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 | +|------|------|------|------|---------------| +| processId | Long | 是 | 报装流程 ID | `biz_process.id` | +| archiveType | String | 是 | 归档类型：`APPLY`、`ACCEPT`、`CHECK`、`CONTRACT`、`FINISH` | 归档分类 | +| attachmentList | Array | 是 | 归档附件列表 | `biz_content_attach` | +| contractId | Long | 否 | 合同 ID | `installation_contract.id` | +| evidenceId | Long | 否 | 存证记录 ID | `installation_evidence.id` | +| operatorId | Long | 否 | 归档操作人 | 操作上下文 | + +#### 响应参数 + +| 字段 | 类型 | 说明 | 主要来源 | +|------|------|------|----------| +| archiveBatchNo | String | 归档批次号 | 业务流水 | +| archiveStatus | String | 归档状态：`SUCCESS`、`PARTIAL`、`FAIL` | 业务状态 | +| archiveCount | Integer | 已归档文件数量 | 汇总结果 | +| msg | String | 处理说明 | 返回消息 | + ## 关键接口时序图 > 说明：以下时序图用于说明 SYS-002 与客户渠道、外部协同子系统之间的交互边界，重点体现业务校验、协同调用、结果回写与状态更新链路。