tangweijie 3fee9a2c18 docs: add Nuoshuitong integration design pack

Add a Nuoshuitong documentation set covering the implementation checklist, split interface spec notes, normalized enums, and database/DDL guidance so follow-on integration can start from a consistent source of truth.

Constraint: Current phase is documentation-first and must not require backend/frontend code changes
Rejected: Merge the material directly into formal master design docs now | would broaden scope before the integration model and dialect strategy are reviewed
Directive: Treat these guides as integration-layer inputs until they are reconciled with formal technical design masters
Confidence: high
Scope-risk: moderate

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

2026-03-24 17:50:46 +08:00

19 KiB

Raw Blame History

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

文档信息

项目	内容
项目名称	福建水务营收系统
文档类型	外部平台对接数据库设计草案
对接平台	诺税通 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	是	更新时间

表关系建议

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 对齐，纳入正式专项设计口径

19 KiB Raw Blame History

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

文档信息

适用说明

设计目标

表清单总览

命名与通用约定

表命名

通用审计字段

状态字段约定

JSON 字段约定

详细表结构草案

ns_invoice 发票主表

用途

字段建议

主键与唯一约束建议

索引建议

状态字段建议

request_status

invoice_status

delivery_status

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 配置字典缓存表（可选）

用途

字段建议

表关系建议

幂等与审计建议

回调幂等

请求幂等

首期最小落表建议

后续建议

19 KiB

Raw Blame History

`ns_invoice` 发票主表

`request_status`

`invoice_status`

`delivery_status`

`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` 配置字典缓存表（可选）