# 诺税通对接数据库设计草案

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 项目名称 | 福建水务营收系统 |
| 文档类型 | 外部平台对接数据库设计草案 |
| 对接平台 | 诺税通 saas |
| 适用范围 | 销项开票、发票查询、文件获取、交付、作废、红字单据、设备与库存、企业开票配置 |
| 版本 | v1.0 |
| 日期 | 2026-03-24 |
| 状态 | 草案 |

## 适用说明

本文档用于支撑福建水务营收系统对接诺税通 saas 时的数据库落库设计。内容聚焦对接层数据承接，不直接替代正式业务数据库设计主文档，而是作为外部平台集成方案、领域建模和后续 DDL 细化的基础输入。

当前口径基于以下资料统一整理：
- `docs/guides/NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md`
- `docs/guides/NUOSHUITONG_INTERFACE_SPEC/`

## 设计目标

本设计用于支撑以下闭环：
- 开票申请与状态同步
- 发票票面文件获取
- 发票交付与补发
- 发票作废、重开、冲红
- 红字信息表与红字确认单管理
- 开票设备与票源库存管理
- 企业开票配置与规则缓存
- 平台回调与请求日志追踪

## 表清单总览

| 表名 | 说明 |
| --- | --- |
| `ns_invoice` | 发票主表 |
| `ns_invoice_item` | 发票明细表 |
| `ns_invoice_delivery` | 发票交付记录表 |
| `ns_invoice_reversal` | 发票逆向处理表 |
| `ns_red_document` | 红字单据主表 |
| `ns_red_document_item` | 红字单据明细表 |
| `ns_billing_device` | 开票设备表 |
| `ns_invoice_stock_snapshot` | 发票库存快照表 |
| `ns_enterprise_billing_config` | 企业开票配置表 |
| `ns_platform_event_log` | 平台回调事件表 |
| `ns_platform_request_log` | 平台请求响应日志表 |
| `ns_config_dictionary_cache` | 配置字典缓存表（可选） |

## 命名与通用约定

### 表命名
- 对接域表统一采用 `ns_` 前缀，表示 Nuoshuitong 集成域。
- 字段命名统一使用下划线命名法。

### 通用审计字段
除快照类或纯日志类表外，建议统一具备：
- `created_at`
- `updated_at`
- `created_by`
- `updated_by`

### 状态字段约定
建议状态类字段统一采用“编码 + 文本”双承接：
- `*_status`
- `*_status_text`

### JSON 字段约定
当平台返回结构复杂、且短期内不适合完全拆表时，可保留 JSON/TEXT 字段承接，例如：
- `specific_factor_json`
- `request_body`
- `response_body`
- `payload_json`

## 详细表结构草案

## `ns_invoice` 发票主表

### 用途
承接发票从申请、查询、回调、文件获取到交付的主生命周期。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `sys_request_no` | varchar(64) | 是 | 系统侧请求号，建议唯一 |
| `order_no` | varchar(64) | 否 | 业务订单号 |
| `source_business_type` | varchar(32) | 否 | 来源业务类型 |
| `source_business_id` | varchar(64) | 否 | 来源业务主键 |
| `platform_invoice_serial_num` | varchar(64) | 否 | 平台发票流水号 |
| `invoice_id` | varchar(64) | 否 | 平台发票 ID |
| `invoice_code` | varchar(32) | 否 | 发票代码 |
| `invoice_no` | varchar(32) | 否 | 发票号码 |
| `all_electronic_invoice_no` | varchar(64) | 否 | 数电票号码 |
| `seller_tax_no` | varchar(32) | 是 | 销方税号 |
| `buyer_name` | varchar(200) | 否 | 购方名称 |
| `buyer_tax_no` | varchar(64) | 否 | 购方税号 |
| `buyer_address` | varchar(255) | 否 | 购方地址 |
| `buyer_tel` | varchar(64) | 否 | 购方电话 |
| `buyer_account` | varchar(255) | 否 | 购方开户行及账号 |
| `invoice_type` | varchar(16) | 否 | 蓝票/红票 |
| `invoice_line` | varchar(16) | 否 | 发票票种 |
| `list_flag` | smallint | 否 | 清单标志 |
| `with_tax_flag` | smallint | 否 | 含税标志 |
| `notify_phone` | varchar(64) | 否 | 交付手机号 |
| `notify_email` | varchar(128) | 否 | 交付邮箱 |
| `cc_phone` | varchar(256) | 否 | 抄送手机号 |
| `cc_email` | varchar(256) | 否 | 抄送邮箱 |
| `total_amount` | decimal(18,2) | 否 | 含税总金额 |
| `amount_without_tax` | decimal(18,2) | 否 | 不含税总金额 |
| `tax_amount` | decimal(18,2) | 否 | 税额 |
| `request_status` | varchar(32) | 是 | 请求状态 |
| `invoice_status` | varchar(32) | 否 | 开票状态 |
| `invoice_status_text` | varchar(255) | 否 | 状态说明 |
| `invalid_state` | varchar(32) | 否 | 作废状态 |
| `delivery_status` | varchar(32) | 否 | 交付状态 |
| `sync_status` | varchar(32) | 否 | 平台同步状态 |
| `pdf_url` | varchar(1024) | 否 | PDF 地址 |
| `ofd_url` | varchar(1024) | 否 | OFD 地址 |
| `image_url` | varchar(1024) | 否 | 图片地址 |
| `paper_pdf_url` | varchar(1024) | 否 | 纸票 PDF 地址 |
| `invoice_time` | datetime | 否 | 开票时间 |
| `request_time` | datetime | 否 | 请求时间 |
| `invalid_time` | datetime | 否 | 作废时间 |
| `last_sync_time` | datetime | 否 | 最近同步时间 |
| `ori_invoice_code` | varchar(32) | 否 | 原发票代码 |
| `ori_invoice_no` | varchar(32) | 否 | 原发票号码 |
| `old_electronic_invoice_no` | varchar(64) | 否 | 原数电票号码 |
| `remark` | varchar(1000) | 否 | 备注 |
| `specific_factor_json` | text | 否 | 特殊因子 JSON |
| `latest_result` | varchar(1000) | 否 | 最近一次平台结果摘要 |
| `latest_error` | varchar(1000) | 否 | 最近一次错误摘要 |
| `try_count` | int | 否 | 同步/补偿次数 |
| `last_try_time` | datetime | 否 | 最近重试时间 |
| `next_try_time` | datetime | 否 | 下次重试时间 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |
| `created_by` | varchar(64) | 否 | 创建人 |
| `updated_by` | varchar(64) | 否 | 更新人 |

### 主键与唯一约束建议
- 主键：`id`
- 唯一约束：`sys_request_no`
- 可选唯一约束：`platform_invoice_serial_num`
- 可选业务唯一约束：`seller_tax_no + invoice_code + invoice_no`

### 索引建议
- `idx_ns_invoice_order_no`
- `idx_ns_invoice_status`
- `idx_ns_invoice_seller_tax_no`
- `idx_ns_invoice_invoice_time`
- `idx_ns_invoice_next_try_time`

### 状态字段建议
#### `request_status`
- `DRAFT`
- `PRECHECK_FAILED`
- `REQUESTED`
- `PROCESSING`
- `SUCCESS`
- `FAILED`

#### `invoice_status`
- `ISSUING`
- `ISSUED`
- `ISSUE_FAILED`
- `CANCELLED`
- `CANCEL_FAILED`
- `RED_PROCESSED`

#### `delivery_status`
- `NOT_DELIVERED`
- `DELIVERING`
- `DELIVERED`
- `DELIVERY_FAILED`

## `ns_invoice_item` 发票明细表

### 用途
保存开票请求与平台返回的发票明细。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `invoice_id` | bigint | 是 | 发票主表 ID |
| `line_no` | int | 是 | 行号 |
| `goods_name` | varchar(255) | 是 | 商品名称 |
| `goods_code` | varchar(64) | 否 | 税收分类编码 |
| `spec` | varchar(128) | 否 | 规格型号 |
| `unit` | varchar(64) | 否 | 单位 |
| `quantity` | decimal(18,6) | 否 | 数量 |
| `unit_price` | decimal(18,6) | 否 | 单价 |
| `amount_with_tax` | decimal(18,2) | 否 | 含税金额 |
| `amount_without_tax` | decimal(18,2) | 否 | 不含税金额 |
| `tax_rate` | decimal(8,4) | 否 | 税率 |
| `tax_amount` | decimal(18,2) | 否 | 税额 |
| `detail_type` | smallint | 否 | 行类型 |
| `favoured_policy_flag` | smallint | 否 | 优惠政策标志 |
| `zero_rate_flag` | smallint | 否 | 零税率标志 |
| `favoured_policy_name` | varchar(128) | 否 | 优惠政策名称 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

### 约束建议
- 外键：`invoice_id -> ns_invoice.id`
- 唯一约束：`invoice_id + line_no`

## `ns_invoice_delivery` 发票交付记录表

### 用途
记录首次交付、补发和交付失败结果。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `invoice_id` | bigint | 是 | 发票 ID |
| `delivery_type` | varchar(16) | 是 | `SMS` / `EMAIL` |
| `delivery_target` | varchar(256) | 是 | 发送目标 |
| `cc_target` | varchar(512) | 否 | 抄送目标 |
| `delivery_status` | varchar(32) | 是 | 交付状态 |
| `delivery_message` | varchar(1000) | 否 | 平台返回信息 |
| `delivery_attempt_no` | int | 是 | 第几次交付 |
| `is_retry` | smallint | 是 | 是否补发 |
| `response_code` | varchar(32) | 否 | 平台响应码 |
| `response_body` | text | 否 | 平台响应体 |
| `delivery_time` | datetime | 否 | 交付时间 |
| `created_at` | datetime | 是 | 创建时间 |

### 索引建议
- `idx_ns_invoice_delivery_invoice_id`
- `idx_ns_invoice_delivery_status`

## `ns_invoice_reversal` 发票逆向处理表

### 用途
记录作废、冲红、重开、空白票作废等逆向业务动作。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `invoice_id` | bigint | 是 | 原发票 ID |
| `reversal_type` | varchar(32) | 是 | `CANCEL` / `FAST_RED` / `REOPEN` / `BLANK_CANCEL` |
| `source_invoice_code` | varchar(32) | 否 | 原票代码 |
| `source_invoice_no` | varchar(32) | 否 | 原票号码 |
| `invalid_reason` | varchar(32) | 否 | 作废原因编码 |
| `specific_reason` | varchar(500) | 否 | 具体原因 |
| `request_status` | varchar(32) | 是 | 请求状态 |
| `reversal_status` | varchar(32) | 否 | 逆向状态 |
| `platform_result_code` | varchar(32) | 否 | 平台响应码 |
| `platform_result_msg` | varchar(1000) | 否 | 平台响应信息 |
| `target_invoice_id` | bigint | 否 | 新票 ID |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

### 状态建议
- `INIT`
- `CHECKING`
- `REQUESTED`
- `SUCCESS`
- `FAILED`
- `REJECTED`

## `ns_red_document` 红字单据主表

### 用途
统一承接红字信息表与红字确认单。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `invoice_id` | bigint | 否 | 关联蓝票 ID |
| `document_type` | varchar(16) | 是 | `RED_INFO` / `RED_CONFIRM` |
| `bill_no` | varchar(64) | 否 | 单据编号 |
| `bill_id` | varchar(64) | 否 | 平台单据 ID |
| `bill_info_no` | varchar(64) | 否 | 信息表编号 |
| `bill_confirm_no` | varchar(64) | 否 | 确认单编号 |
| `bill_uuid` | varchar(64) | 否 | 平台 UUID |
| `blue_invoice_code` | varchar(32) | 否 | 蓝票代码 |
| `blue_invoice_no` | varchar(32) | 否 | 蓝票号码 |
| `blue_invoice_number` | varchar(64) | 否 | 蓝票数电号 |
| `blue_invoice_line` | varchar(16) | 否 | 蓝票票种 |
| `bill_type` | varchar(32) | 否 | 红字业务类型 |
| `bill_status` | varchar(32) | 否 | 单据状态 |
| `bill_status_text` | varchar(255) | 否 | 状态说明 |
| `open_status` | varchar(32) | 否 | 开具状态 |
| `back_type` | varchar(16) | 否 | 回传类型 |
| `apply_source` | varchar(32) | 否 | 申请来源 |
| `red_reason` | varchar(255) | 否 | 红字原因 |
| `apply_remark` | varchar(1000) | 否 | 申请备注 |
| `pdf_url` | varchar(1024) | 否 | PDF 地址 |
| `callback_status` | varchar(32) | 否 | 回调处理状态 |
| `last_sync_time` | datetime | 否 | 最近同步时间 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

### 唯一约束建议
- `bill_no`
- 可选：`bill_id`

## `ns_red_document_item` 红字单据明细表

### 用途
承接红字申请与确认单明细。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `red_document_id` | bigint | 是 | 红字单据主表 ID |
| `line_no` | int | 是 | 行号 |
| `goods_name` | varchar(255) | 否 | 商品名称 |
| `model` | varchar(128) | 否 | 型号 |
| `unit` | varchar(64) | 否 | 单位 |
| `quantity` | decimal(18,6) | 否 | 数量 |
| `unit_price` | decimal(18,6) | 否 | 单价 |
| `amount` | decimal(18,2) | 否 | 金额 |
| `tax_rate` | decimal(8,4) | 否 | 税率 |
| `tax_amount` | decimal(18,2) | 否 | 税额 |
| `with_tax_flag` | smallint | 否 | 含税标志 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

## `ns_billing_device` 开票设备表

### 用途
承接设备主数据、运行态状态和设备能力。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `tax_num` | varchar(32) | 是 | 企业税号 |
| `company_id` | varchar(64) | 否 | 平台企业 ID |
| `extension_num` | varchar(32) | 否 | 分机号 |
| `machine_num` | varchar(64) | 否 | 机器编号 |
| `terminal_num` | varchar(64) | 否 | 终端号 |
| `server_type` | varchar(32) | 否 | 设备类型 |
| `invoice_type_list` | varchar(512) | 否 | 支持票种列表 |
| `login_account` | varchar(128) | 否 | 登录账号 |
| `equipment_cabinet_id` | varchar(64) | 否 | 机柜 ID |
| `device_status` | varchar(32) | 是 | 在线状态 |
| `report_tax_status` | varchar(32) | 否 | 抄报状态 |
| `clear_card_status` | varchar(32) | 否 | 清卡状态 |
| `lock_date` | varchar(32) | 否 | 锁死日期 |
| `single_billing_limit` | decimal(18,2) | 否 | 单笔限额 |
| `offline_amount` | decimal(18,2) | 否 | 离线金额 |
| `offline_time` | varchar(64) | 否 | 离线时间 |
| `last_status_sync_time` | datetime | 否 | 最近状态同步时间 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

### 唯一约束建议
- 保守建议：`tax_num + extension_num + machine_num`

## `ns_invoice_stock_snapshot` 发票库存快照表

### 用途
记录库存查询、刷新、下载、申领后的快照结果。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `device_id` | bigint | 否 | 设备 ID |
| `seller_tax_no` | varchar(32) | 是 | 销方税号 |
| `extension_num` | varchar(32) | 否 | 分机号 |
| `machine_num` | varchar(64) | 否 | 机器编号 |
| `terminal_num` | varchar(64) | 否 | 终端号 |
| `invoice_line` | varchar(16) | 否 | 票种 |
| `invoice_code` | varchar(32) | 否 | 发票代码 |
| `invoice_num_start` | varchar(32) | 否 | 起始号 |
| `invoice_num_end` | varchar(32) | 否 | 结束号 |
| `remain_num` | int | 否 | 剩余数量 |
| `is_default` | smallint | 否 | 是否默认 |
| `source_type` | varchar(16) | 是 | `QUERY` / `REFRESH` / `DOWNLOAD` / `APPLY` |
| `snapshot_time` | datetime | 是 | 快照时间 |
| `created_at` | datetime | 是 | 创建时间 |

## `ns_enterprise_billing_config` 企业开票配置表

### 用途
承接企业开票默认信息与认证状态。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `tax_num` | varchar(32) | 是 | 企业税号 |
| `company_id` | varchar(64) | 否 | 平台企业 ID |
| `use_scope` | varchar(32) | 否 | 使用范围 |
| `clerker` | varchar(128) | 否 | 开票员 |
| `seller_address` | varchar(255) | 否 | 销方地址 |
| `seller_tel` | varchar(64) | 否 | 销方电话 |
| `seller_bank` | varchar(255) | 否 | 销方开户行 |
| `seller_account` | varchar(255) | 否 | 销方账号 |
| `payee` | varchar(64) | 否 | 收款人 |
| `checker` | varchar(64) | 否 | 复核人 |
| `project_code` | varchar(64) | 否 | 项目编码 |
| `department_name` | varchar(128) | 否 | 部门名称 |
| `auth_status` | varchar(32) | 否 | 认证状态 |
| `last_auth_time` | datetime | 否 | 最近认证时间 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

### 唯一约束建议
- `tax_num`

## `ns_platform_event_log` 平台回调事件表

### 用途
保留平台回调原文和处理结果，实现幂等与可追踪。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `event_type` | varchar(32) | 是 | `INVOICE_CALLBACK` / `RED_CALLBACK` |
| `event_key` | varchar(128) | 是 | 幂等键 |
| `seller_tax_no` | varchar(32) | 否 | 销方税号 |
| `business_key` | varchar(128) | 否 | 业务主键 |
| `payload_json` | longtext | 是 | 回调原文 |
| `process_status` | varchar(32) | 是 | `INIT` / `SUCCESS` / `FAILED` / `IGNORED` |
| `process_message` | varchar(1000) | 否 | 处理说明 |
| `processed_at` | datetime | 否 | 处理时间 |
| `created_at` | datetime | 是 | 创建时间 |

### 唯一约束建议
- `event_key`

## `ns_platform_request_log` 平台请求响应日志表

### 用途
记录所有对诺税通平台的请求与响应，便于联调排障。

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `request_id` | varchar(64) | 是 | 请求 ID |
| `business_type` | varchar(32) | 否 | 业务类型 |
| `business_id` | varchar(64) | 否 | 业务 ID |
| `method_name` | varchar(128) | 否 | 平台方法名 |
| `request_headers_masked` | text | 否 | 脱敏请求头 |
| `request_body` | longtext | 否 | 请求体 |
| `response_body` | longtext | 否 | 响应体 |
| `response_code` | varchar(32) | 否 | 响应码 |
| `success_flag` | smallint | 否 | 成功标识 |
| `error_message` | varchar(1000) | 否 | 错误信息 |
| `created_at` | datetime | 是 | 创建时间 |

## `ns_config_dictionary_cache` 配置字典缓存表（可选）

### 用途
缓存平台字典项，如：
- `requestSrc`
- `invoiceLine`
- `organize`
- `dept`
- `clerk`
- `invalidSrc`

### 字段建议

| 字段名 | 类型建议 | 非空 | 说明 |
| --- | --- | --- | --- |
| `id` | bigint | 是 | 主键 |
| `dict_type` | varchar(64) | 是 | 字典类型 |
| `dict_key` | varchar(128) | 是 | 字典键 |
| `dict_name` | varchar(255) | 否 | 字典名称 |
| `company_id` | varchar(64) | 否 | 企业 ID |
| `company_name` | varchar(255) | 否 | 企业名称 |
| `extra_json` | text | 否 | 扩展 JSON |
| `last_sync_time` | datetime | 否 | 最近同步时间 |
| `created_at` | datetime | 是 | 创建时间 |
| `updated_at` | datetime | 是 | 更新时间 |

## 表关系建议

```mermaid
erDiagram
    ns_invoice ||--o{ ns_invoice_item : contains
    ns_invoice ||--o{ ns_invoice_delivery : delivers
    ns_invoice ||--o{ ns_invoice_reversal : reverses
    ns_invoice ||--o{ ns_red_document : relates
    ns_red_document ||--o{ ns_red_document_item : contains
    ns_billing_device ||--o{ ns_invoice_stock_snapshot : has
    ns_enterprise_billing_config ||--o{ ns_billing_device : configures
```

## 幂等与审计建议

### 回调幂等
必须依赖：
- `ns_platform_event_log.event_key`

建议 `event_key` 构成为：
- 发票回调：`sellerTaxNo + invoiceId + invoiceStatus`
- 红字回调：`backType + billNo + billStatus`

### 请求幂等
建议：
- `sys_request_no` 全局唯一
- 开票请求入库前先校验是否已存在同请求号记录

## 首期最小落表建议

若先追求最小可用，建议优先落以下 7 张表：
- `ns_invoice`
- `ns_invoice_item`
- `ns_invoice_delivery`
- `ns_invoice_reversal`
- `ns_billing_device`
- `ns_invoice_stock_snapshot`
- `ns_platform_request_log`

第二批补充：
- `ns_red_document`
- `ns_red_document_item`
- `ns_platform_event_log`
- `ns_enterprise_billing_config`

## 后续建议

本文档完成后，建议继续补充两项内容：
- 按表输出正式 DDL 草案
- 与 `docs/design/03_Technical_Design/01_Database_Design.md` 对齐，纳入正式专项设计口径