diff --git a/CLAUDE.md b/CLAUDE.md index 737f187..51f7d8e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,42 @@ # CLAUDE.md -本文件用于指导 Claude Code 在本仓库中的工作方式。 +本文件用于指导 Claude Code 及通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。 + +## Workspace Coordination + +本仓库现在是 `water-workspace` 下的文档总控仓，默认作为正式规格、计划、任务、验收与治理台账的单一入口。 + +### 邻接仓库 + +- `../water-backend/`：后端实现仓，默认主开发分支为 `develop` +- `../water-frontend/`：前端实现仓，默认主开发分支为 `develop` + +### 启动规则 + +- 需要运行 `/speckit.specify`、`/speckit.plan`、`/speckit.tasks`、正式文档修订、治理台账更新、验收结论汇总时，必须从 `water-docs` 根目录启动代理。 +- 需要检查正式规格、计划、任务、基线、evidence 时，以 `water-docs/specs/` 与 `water-docs/docs/` 为准。 +- 未经用户明确要求，不在本仓库直接修改 `../water-backend/` 或 `../water-frontend/` 中的业务代码。 + +### 多仓协作规则 + +- 本仓库中的 `.specify/` 是唯一正式流程入口，backend/frontend 不复制第二套 `.specify/`。 +- backend/frontend 仓内实现结论，必须回写到本仓库的正式文档或 `specs/` 工件，不能仅停留在代码仓口头说明。 +- 重要 feature 默认记录代码基线： + - backend commit SHA + - frontend commit SHA + - 验证日期 + +### Worktree 约定 + +- 推荐在 `../worktrees/` 下按 feature 建立平铺 worktree： + - `docs-` + - `backend-` + - `frontend-` + - `verify-` +- 文档 lane 只改 `water-docs` +- backend lane 只改 `water-backend` +- frontend lane 只改 `water-frontend` +- verify lane 负责样本、日志、验收结论和基线固定 ## 项目定位 @@ -20,14 +56,17 @@ ```text / ├── docs/design/00_Management/ # 项目管理、进度跟踪、交付规范、编写指南 -├── docs/design/01_Overview/ # 总体设计：系统概述、系统架构、概要设计、系统图谱 -├── docs/design/02_Detailed_Design/ # 详细设计：主详设、模块设计、CA 安装设计 -├── docs/design/03_Technical_Design/ # 技术专项：数据库、表结构、接口、安全、部署、加密 -├── docs/design/04_Appendix/ # 附录与归档资料 -├── assets/ # 图片、模板等静态资源 -├── docs/ # 研究资料、映射文档、使用指南 -├── scripts/ # 文档处理与导出脚本 -└── infra/ # 辅助基础设施 +├── docs/design/01_Overview/ # 总体设计：系统概述、系统架构、概要设计、系统图谱 +├── docs/design/02_Detailed_Design/ # 详细设计：主详设、模块设计、CA 安装设计 +├── docs/design/03_Technical_Design/ # 技术专项：数据库、表结构、接口、安全、部署、加密 +├── docs/design/04_Appendix/ # 附录与归档资料 +├── .claude/ # Claude Code 相关配置 +├── .omc/ # 项目记忆与代理状态 +├── .zed/ # Zed 项目配置 +├── assets/ # 图片、模板等静态资源 +├── docs/ # 研究资料、映射文档、使用指南 +├── scripts/ # 文档处理与导出脚本 +└── infra/ # 辅助基础设施 ``` ## 当前文档组织原则 @@ -193,6 +232,9 @@ make export-word make export-pdf make export-html make unified-export +npm run check:marksman +npm run marksman:help +npm run marksman:server ``` 如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。 @@ -256,11 +298,13 @@ make unified-export - 归档整理与信息整编助手 - 基于现有资料进行保守补完的编辑者 -不是： +而不是： - 擅自扩展需求的产品经理 - 无依据发明实现细节的方案生成器 -- 动辄新建文件的“版本制造机” +- 动辄新建文件的”版本制造机” + +本文件用于指导通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。 ## 最终目标 diff --git a/docs/README.md b/docs/README.md index eeecbe0..84236fc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,9 +18,11 @@ ## 推荐阅读顺序 -1. `guides/BACKEND_CURRENT_STATUS.md` -2. `guides/BACKEND_TABLE_MAPPING.md` -3. 其他辅助资料 +1. `guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md` +2. `guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md` +3. `guides/BACKEND_CURRENT_STATUS.md` +4. `guides/BACKEND_TABLE_MAPPING.md` +5. 其他辅助资料 ## 维护原则 diff --git a/docs/api/openapi/README.md b/docs/api/openapi/README.md new file mode 100644 index 0000000..ce432d4 --- /dev/null +++ b/docs/api/openapi/README.md @@ -0,0 +1,96 @@ +# 营收系统银行缴费接口文档 + +本目录包含营收系统与银行/第三方支付机构之间的接口 OpenAPI 规范文档。 + +## 目录结构 + +``` +docs/api/openapi/ +├── main/ +│ ├── openapi.yaml # OpenAPI 3.0.3 主文档入口 +│ ├── components/ # 可复用组件定义 +│ │ ├── schemas.yaml # 数据模型定义 +│ │ ├── responses.yaml # 响应定义 +│ │ ├── parameters.yaml # 参数定义 +│ │ ├── headers.yaml # 头部定义 +│ │ ├── security.yaml # 安全定义 +│ │ └── index.yaml # 组件索引 +│ └── paths/ # API 路径定义 +│ ├── bill-query.yaml # 账单查询 +│ ├── bill-pay.yaml # 账单缴费 +│ ├── pay-invalid.yaml # 账单红冲 +│ ├── withholding-signing.yaml # 代扣签约 +│ ├── withholding-termination.yaml # 代扣解约 +│ ├── withholding-send-disc.yaml # 代扣送盘 +│ └── withholding-back-disc.yaml # 代扣回盘 +├── generated/ # 生成的代码（保留参考） +├── validate.js # 文档验证脚本 +└── serve.js # 本地预览服务器 + +scripts/api-tools/ +└── validate-all.js # 批量验证工具 +``` + +## 接口清单 + +| 接口名称 | 路径 | 交易码 | 描述 | +|---------|------|--------|------| +| 账单查询 | `/api/app/payCeb/getChargeSearch` | Query/QueryRes | 查询客户账单信息 | +| 账单缴费 | `/api/app/payCeb/getChargeOffs` | Pay/PayRes | 处理账单缴费 | +| 账单红冲 | `/api/app/payInvalid/payInvalid` | PayInvalid/PayInvalidRes | 红冲缴费记录 | +| 代扣签约 | `/api/app/bankWithholding/signing` | Signing/SigningRes | 银行代扣签约 | +| 代扣解约 | `/api/app/bankWithholding/termination` | Termination/TerminationRes | 银行代扣解约 | +| 代扣送盘 | `/api/app/bankWithholding/sendDisc` | SendDisc/SendDiscRes | 批量代扣送盘 | +| 代扣回盘 | `/api/app/bankWithholding/backDisc` | BackDisc/BackDiscRes | 接收银行回盘 | + +## 核心特性 + +### 数据格式支持 +- **XML格式**：GBK编码，符合传统银行系统规范 +- **JSON格式**：UTF-8编码，适合现代化系统集成 +- **双格式支持**：同时支持XML和JSON请求响应 + +### 安全加密 +- **3DES加密**：ECB模式，PKCS7填充（默认） +- **SM2加密**：支持C1C3C2和C1C2C3模式 +- **SM4加密**：支持ECB和CBC模式 +- **Base64编码**：加密后数据进行Base64编码传输 + +## 使用指南 + +### 1. 验证文档 + +```bash +cd docs/api/openapi +node validate.js +``` + +### 2. 启动本地预览服务 + +```bash +cd docs/api/openapi +node serve.js +``` + +访问 http://localhost:3000 查看 API 文档 + +### 3. 导入到开发工具 + +#### Swagger Editor +1. 打开 [Swagger Editor](https://editor.swagger.io/) +2. 导入 `docs/api/openapi/main/openapi.yaml` 文件 + +#### Postman +1. 打开 Postman +2. 点击 Import +3. 选择 `docs/api/openapi/main/openapi.yaml` 文件导入 + +## 相关文档 + +- [接口规范设计文档](../../design/04_Appendix/Archive/银行缴费接口规范设计文档.md) +- [接口说明文档](../../design/04_Appendix/Archive/银行缴费接口说明.md) +- [主接口设计文档](../../design/03_Technical_Design/03_Interface_Design.md) + +## 来源 + +本文档从 `water-bank-api-doc` 仓库迁移而来，原始文档基于营收系统缴费接口规范 v1.5。 diff --git a/docs/api/openapi/main/components/headers.yaml b/docs/api/openapi/main/components/headers.yaml new file mode 100644 index 0000000..ad3e003 --- /dev/null +++ b/docs/api/openapi/main/components/headers.yaml @@ -0,0 +1,32 @@ +components: + headers: + # 响应内容类型 + ContentType: + description: 响应内容类型 + schema: + type: string + enum: + - "application/xml; charset=GBK" + - "application/json; charset=UTF-8" + + # 响应时间戳 + ResponseTime: + description: 服务端响应时间戳 + schema: + type: string + format: date-time + example: "2024-01-01T12:00:00.000Z" + + # 请求追踪ID + RequestId: + description: 请求追踪标识 + schema: + type: string + example: "req_123456789012" + + # 服务版本 + ServiceVersion: + description: 服务端版本号 + schema: + type: string + example: "1.0.1" \ No newline at end of file diff --git a/docs/api/openapi/main/components/index.yaml b/docs/api/openapi/main/components/index.yaml new file mode 100644 index 0000000..8662672 --- /dev/null +++ b/docs/api/openapi/main/components/index.yaml @@ -0,0 +1,288 @@ +components: + # 数据模型 + schemas: + # 基础请求模型 + BaseRequest: + type: object + required: + - Version + - InstId + - TranCode + - TranDate + - TranSeq + properties: + Version: + type: string + description: 版本号 + example: "1.0.1" + InstId: + type: string + description: 机构编码 + example: "00001" + maxLength: 30 + TranCode: + type: string + description: 交易码 + example: "Query" + maxLength: 20 + TranDate: + type: string + description: 交易日期 + pattern: '^\d{8}$' + example: "20240101" + TranSeq: + type: string + description: 交易流水号（银行生成的唯一标识） + example: "123456789012" + maxLength: 40 + + # 基础响应模型 + BaseResponse: + type: object + required: + - Version + - InstId + - TranCode + - TranDate + - TranSeq + - RespCode + - RespMessage + properties: + Version: + type: string + description: 版本号 + example: "1.0.1" + InstId: + type: string + description: 机构编码 + example: "00001" + TranCode: + type: string + description: 交易码 + example: "QueryRes" + TranDate: + type: string + description: 交易日期 + pattern: '^\d{8}$' + example: "20240101" + TranSeq: + type: string + description: 交易流水号 + example: "123456789012" + RespCode: + type: string + description: 返回码 + enum: + - "AAAAAAA" # 成功 + - "DEF0001" # 无相应记录 + - "DEF0002" # 缴费金额不匹配 + - "SYS1001" # 系统异常 + - "SEC2001" # 加密错误 + example: "AAAAAAA" + RespMessage: + type: string + description: 返回消息 + example: "成功" + maxLength: 60 + + # 错误详情 + ErrorDetail: + type: object + properties: + ErrorCode: + type: string + description: 错误码 + example: "DEF0001" + ErrorMsg: + type: string + description: 错误消息 + example: "用户编号123456不存在" + ErrorTime: + type: string + format: date-time + description: 错误时间 + example: "2024-01-01T12:00:00.000Z" + + # 其他数据模型引用原有文件 + BillQueryRequest: + $ref: './schemas.yaml#/components/schemas/BillQueryRequest' + + BillQueryResponse: + $ref: './schemas.yaml#/components/schemas/BillQueryResponse' + + BillPayRequest: + $ref: './schemas.yaml#/components/schemas/BillPayRequest' + + BillPayResponse: + $ref: './schemas.yaml#/components/schemas/BillPayResponse' + + # 响应组件 + responses: + # 业务错误响应 + BusinessError: + description: 业务处理错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 系统错误响应 + SystemError: + description: 系统异常错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 安全错误响应 + SecurityError: + description: 安全验证错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 网络错误响应 + NetworkError: + description: 网络通信错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 参数组件 + parameters: + ContentTypeHeader: + name: Content-Type + in: header + required: true + description: 请求内容类型 + schema: + type: string + enum: + - application/xml + - application/json + example: "application/xml" + + EncryptTypeHeader: + name: X-Encrypt-Type + in: header + required: false + description: 加密算法类型 + schema: + type: string + enum: + - "3DES" + - "SM2" + - "SM4" + example: "3DES" + + EncryptModeHeader: + name: X-Encrypt-Mode + in: header + required: false + description: 加密模式 + schema: + type: string + enum: + - "ECB" + - "CBC" + example: "ECB" + + DataTypeHeader: + name: X-Data-Type + in: header + required: false + description: 数据格式类型 + schema: + type: string + enum: + - "XML" + - "JSON" + example: "XML" + + # 响应头组件 + headers: + ContentType: + description: 响应内容类型 + schema: + type: string + example: "application/xml; charset=GBK" + + ResponseTime: + description: 响应时间（毫秒） + schema: + type: integer + example: 150 + + RequestId: + description: 请求唯一标识 + schema: + type: string + example: "req-123456789012" + + # 安全认证组件 + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + description: API密钥认证 + + EncryptedData: + type: http + scheme: bearer + bearerFormat: encrypted + description: 加密数据传输认证 \ No newline at end of file diff --git a/docs/api/openapi/main/components/parameters.yaml b/docs/api/openapi/main/components/parameters.yaml new file mode 100644 index 0000000..7f56970 --- /dev/null +++ b/docs/api/openapi/main/components/parameters.yaml @@ -0,0 +1,67 @@ +components: + parameters: + # 内容类型参数 + ContentTypeHeader: + name: Content-Type + in: header + required: true + description: 内容类型 + schema: + type: string + enum: + - "application/xml; charset=GBK" + - "application/json; charset=UTF-8" + default: "application/xml; charset=GBK" + + # 加密类型参数 + EncryptTypeHeader: + name: EncryptType + in: header + required: false + description: 加密类型 + schema: + type: string + enum: + - "3DES" + - "SM2" + - "SM4" + example: "3DES" + + # 加密模式参数 + EncryptModeHeader: + name: EncryptMode + in: header + required: false + description: 加密模式 + schema: + type: string + enum: + - "ECB" + - "CBC" + - "C1C3C2" + - "C1C2C3" + example: "ECB" + + # 数据类型参数 + DataTypeHeader: + name: DataType + in: header + required: false + description: 数据类型 + schema: + type: string + enum: + - "XML" + - "JSON" + example: "XML" + + # 版本号参数 + VersionParam: + name: version + in: query + required: false + description: API版本号 + schema: + type: string + default: "1.0.1" + example: "1.0.1" \ No newline at end of file diff --git a/docs/api/openapi/main/components/responses.yaml b/docs/api/openapi/main/components/responses.yaml new file mode 100644 index 0000000..f180a11 --- /dev/null +++ b/docs/api/openapi/main/components/responses.yaml @@ -0,0 +1,227 @@ +components: + responses: + # 成功响应 + Success: + description: 操作成功 + content: + application/xml: + schema: + $ref: './schemas.yaml#/components/schemas/BaseResponse' + example: | + + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + AAAAAAA + 成功 + + application/json: + schema: + $ref: './schemas.yaml#/components/schemas/BaseResponse' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "QueryRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "AAAAAAA" + RespMessage: "成功" + + # 业务错误响应 + BusinessError: + description: 业务处理错误 + content: + application/xml: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: | + + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + DEF0001 + 无相应记录 + + DEF0001 + 用户编号123456不存在 + 2024-01-01 12:00:00 + + + application/json: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "QueryRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "DEF0001" + RespMessage: "无相应记录" + ErrorDetail: + ErrorCode: "DEF0001" + ErrorMsg: "用户编号123456不存在" + ErrorTime: "2024-01-01T12:00:00.000Z" + + # 系统错误响应 + SystemError: + description: 系统异常错误 + content: + application/xml: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: | + + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + SYS1001 + 系统异常 + + SYS1001 + 数据库连接失败 + 2024-01-01 12:00:00 + + + application/json: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "QueryRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "SYS1001" + RespMessage: "系统异常" + ErrorDetail: + ErrorCode: "SYS1001" + ErrorMsg: "数据库连接失败" + ErrorTime: "2024-01-01T12:00:00.000Z" + + # 安全错误响应 + SecurityError: + description: 安全验证错误 + content: + application/xml: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: | + + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + SEC2001 + 加密验证失败 + + SEC2001 + 数据解密失败 + 2024-01-01 12:00:00 + + + application/json: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "QueryRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "SEC2001" + RespMessage: "加密验证失败" + ErrorDetail: + ErrorCode: "SEC2001" + ErrorMsg: "数据解密失败" + ErrorTime: "2024-01-01T12:00:00.000Z" + + # 网络错误响应 + NetworkError: + description: 网络通信错误 + content: + application/xml: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: | + + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + NET3001 + 网络超时 + + NET3001 + 请求超时，请稍后重试 + 2024-01-01 12:00:00 + + + application/json: + schema: + allOf: + - $ref: './schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: './schemas.yaml#/components/schemas/ErrorDetail' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "QueryRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "NET3001" + RespMessage: "网络超时" + ErrorDetail: + ErrorCode: "NET3001" + ErrorMsg: "请求超时，请稍后重试" + ErrorTime: "2024-01-01T12:00:00.000Z" \ No newline at end of file diff --git a/docs/api/openapi/main/components/schemas.yaml b/docs/api/openapi/main/components/schemas.yaml new file mode 100644 index 0000000..a414330 --- /dev/null +++ b/docs/api/openapi/main/components/schemas.yaml @@ -0,0 +1,1003 @@ +components: + schemas: + # 基础请求模型 + BaseRequest: + type: object + xml: + name: "in" + namespace: "" + prefix: "" + required: + - Version + - InstId + - TranCode + - TranDate + - TranSeq + properties: + Version: + type: string + description: 版本号 + example: "1.0.1" + InstId: + type: string + description: 机构编码 + example: "00001" + maxLength: 30 + TranCode: + type: string + description: 交易码 + example: "Query" + maxLength: 20 + TranDate: + type: string + description: 交易日期 + pattern: '^\d{8}$' + example: "20240101" + TranSeq: + type: string + description: 交易流水号（银行生成的唯一标识） + example: "123456789012" + maxLength: 40 + + # 基础响应模型 + BaseResponse: + type: object + xml: + name: "out" + namespace: "" + prefix: "" + required: + - Version + - InstId + - TranCode + - TranDate + - TranSeq + - RespCode + - RespMessage + properties: + Version: + type: string + description: 版本号 + example: "1.0.1" + InstId: + type: string + description: 机构编码 + example: "00001" + TranCode: + type: string + description: 交易码 + example: "QueryRes" + TranDate: + type: string + description: 交易日期 + pattern: '^\d{8}$' + example: "20240101" + TranSeq: + type: string + description: 交易流水号 + example: "123456789012" + RespCode: + type: string + description: 返回码 + enum: + - "AAAAAAA" # 成功 + - "DEF0001" # 无相应记录 + - "DEF0002" # 缴费金额不匹配 + - "SYS1001" # 系统异常 + - "SEC2001" # 加密错误 + example: "AAAAAAA" + RespMessage: + type: string + description: 返回消息 + example: "成功" + maxLength: 60 + + # 错误详情 + ErrorDetail: + type: object + xml: + name: "ErrorDetail" + properties: + ErrorCode: + type: string + description: 错误码 + example: "DEF0001" + ErrorMsg: + type: string + description: 错误消息 + example: "用户编号123456不存在" + ErrorTime: + type: string + format: date-time + description: 错误时间 + example: "2024-01-01T12:00:00.000Z" + + # 客户信息 + Customer: + type: object + xml: + name: "Customer" + properties: + BillKey: + type: string + description: 客户编号（缴费号） + example: "123456" + maxLength: 35 + CustomerName: + type: string + description: 客户姓名 + example: "张三" + maxLength: 150 + ContractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 30 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + + # 账单信息 + Bill: + type: object + xml: + name: "Bill" + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + PayAmount: + type: number + format: decimal + description: 缴费金额（单位：元） + example: 150.00 + minimum: 0.01 + Balance: + type: number + format: decimal + description: 余额（单位：元） + example: 0.00 + BeginDate: + type: string + format: date + description: 账单开始日期 + example: "2024-01-01" + EndDate: + type: string + format: date + description: 账单结束日期 + example: "2024-01-31" + BillStatus: + type: integer + description: 账单状态 + enum: [0, 1] # 0:未缴费 1:已缴费 + example: 0 + + # 交易记录 + Transaction: + type: object + xml: + name: "Transaction" + properties: + TranSeq: + type: string + description: 交易流水号 + example: "TXN123456789012" + maxLength: 40 + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + TranCode: + type: string + description: 交易码 + example: "Pay" + maxLength: 20 + PayAmount: + type: number + format: decimal + description: 交易金额 + example: 150.00 + PayDate: + type: string + format: date-time + description: 交易时间 + example: "2024-01-01T12:00:00.000Z" + SubChannel: + type: integer + description: 二级渠道 + enum: [1, 2, 6] # 1:支付宝 2:微信 6:其它 + example: 1 + TranStatus: + type: integer + description: 交易状态 + enum: [0, 1, 2] # 0:处理中 1:成功 2:失败 + example: 1 + RespCode: + type: string + description: 返回码 + example: "AAAAAAA" + RespMessage: + type: string + description: 返回消息 + example: "成功" + + # 代扣协议 + WithholdingAgreement: + type: object + xml: + name: "WithholdingAgreement" + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + AccountName: + type: string + description: 开户名 + example: "张三" + maxLength: 150 + AccountNo: + type: string + description: 开户账号 + example: "6222001234567890" + maxLength: 30 + BankName: + type: string + description: 银行名称 + example: "中国工商银行" + maxLength: 150 + ContractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 150 + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + maxLength: 150 + BankType: + type: integer + description: 银行类型 + enum: [0, 1] # 0:本行 1:他行 + example: 0 + AgreementStatus: + type: integer + description: 协议状态 + enum: [0, 1, 2] # 0:未签约 1:已签约 2:已解约 + example: 1 + SigningDate: + type: string + format: date + description: 签约日期 + example: "2024-01-01" + TerminationDate: + type: string + format: date + description: 解约日期 + example: "2024-12-31" + + # 账单查询请求 + BillQueryRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - BillKey + - CompanyId + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + + # 账单查询响应 + BillQueryResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + Data: + type: object + xml: + name: "Data" + properties: + Customer: + $ref: '#/components/schemas/Customer' + Bills: + type: array + xml: + name: "Bills" + wrapped: true + items: + $ref: '#/components/schemas/Bill' + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 账单缴费请求 + BillPayRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - BillKey + - CompanyId + - PayAmount + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + PayAmount: + type: number + format: decimal + description: 缴费金额 + example: 150.00 + minimum: 0.01 + SubChannel: + type: integer + description: 二级渠道 + enum: [1, 2, 6] + example: 1 + + # 账单缴费响应 + BillPayResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + Data: + type: object + xml: + name: "Data" + properties: + Transaction: + $ref: '#/components/schemas/Transaction' + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 对账请求 + PayCheckRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - CompanyId + - PayDate + - PayCount + - PayMoney + - FileName + properties: + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + PayDate: + type: string + description: 对账日期 + pattern: '^\d{8}$' + example: "20240101" + PayCount: + type: string + description: 交易总笔数 + example: "100" + maxLength: 8 + PayMoney: + type: string + description: 交易总金额（单位：分） + example: "15000" + maxLength: 10 + FileName: + type: string + description: 对账文件名 + example: "654321_20240101.txt" + maxLength: 100 + + # 对账响应 + PayCheckResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + CompanyId: + type: string + description: 机构编码 + example: "654321" + PayDate: + type: string + description: 对账日期 + example: "20240101" + PayAmount: + type: number + format: decimal + description: 交易总金额 + example: 15000.00 + + # 取消代扣请求 + CancelDiscRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - BatchNo + - BillKey + - CompanyId + - AgreementNo + properties: + BatchNo: + type: string + description: 原批次号 + example: "BATCH20240101001" + maxLength: 50 + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + maxLength: 150 + + # 代扣状态查询请求 + WithholdingStatusRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - BatchNo + - CompanyId + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + maxLength: 50 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + QueryDate: + type: string + description: 查询日期 + pattern: '^\d{8}$' + example: "20240101" + + # 代扣状态查询响应 + WithholdingStatusResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + Data: + type: object + xml: + name: "Data" + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + BatchStatus: + type: string + description: 批次状态 + enum: ["PROCESSING", "SUCCESS", "FAILED", "PARTIAL"] + example: "SUCCESS" + TotalCount: + type: integer + description: 总笔数 + example: 10 + SuccessCount: + type: integer + description: 成功笔数 + example: 8 + FailCount: + type: integer + description: 失败笔数 + example: 2 + ProcessTime: + type: string + format: date-time + description: 处理时间 + example: "2024-01-01T12:00:00.000Z" + + # 客户基本信息查询请求 + CustomerCheckRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - billKey + - companyId + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + companyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + queryType: + type: string + description: 查询类型（0：基本信息，1：详细信息） + enum: ["0", "1"] + example: "0" + contractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 30 + filed1: + type: string + description: 备用字段1 + maxLength: 100 + filed2: + type: string + description: 备用字段2 + maxLength: 100 + + # 客户基本信息查询响应 + CustomerCheckResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + companyId: + type: string + description: 机构编码 + example: "654321" + contractNo: + type: string + description: 合同号 + example: "CONTRACT001" + customerName: + type: string + description: 客户姓名 + example: "张三" + customerPhone: + type: string + description: 客户电话 + example: "13812345678" + customerAddress: + type: string + description: 客户地址 + example: "北京市朝阳区xxx街道xxx号" + customerStatus: + type: string + description: 客户状态（0：正常，1：暂停，2：销户） + enum: ["0", "1", "2"] + example: "1" + serviceStatus: + type: string + description: 服务状态（0：停用，1：正常） + enum: ["0", "1"] + example: "1" + registerDate: + type: string + description: 注册日期 + pattern: '^\d{8}$' + example: "20200101" + lastPayDate: + type: string + description: 最后缴费日期 + pattern: '^\d{8}$' + example: "20231215" + totalPayCount: + type: string + description: 累计缴费笔数 + example: "36" + totalPayAmount: + type: string + description: 累计缴费金额（单位：分） + example: "540000" + filed1: + type: string + description: 备用字段1 + maxLength: 100 + filed2: + type: string + description: 备用字段2 + maxLength: 100 + filed3: + type: string + description: 备用字段3 + maxLength: 100 + + # 对账请求 + PaymentCheckRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - companyId + - payDate + - payCount + - payMoney + - fileName + properties: + companyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + payDate: + type: string + description: 对账日期 + pattern: '^\d{8}$' + example: "20240101" + payCount: + type: string + description: 交易总笔数 + example: "100" + maxLength: 8 + payMoney: + type: string + description: 交易总金额（单位：分） + example: "150000" + maxLength: 10 + fileName: + type: string + description: 对账文件名 + example: "654321_20240101.txt" + maxLength: 100 + + # 对账响应 + PaymentCheckResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + companyId: + type: string + description: 机构编码 + example: "654321" + payDate: + type: string + description: 对账日期 + example: "20240101" + payAmount: + type: string + description: 交易总金额 + example: "150000" + + # 取消代扣交易请求 + WithholdingCancelDiscRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - billKey + - companyId + - originalTranSeq + - originalTranDate + - contractNo + - payAmount + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + companyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + originalTranSeq: + type: string + description: 原交易流水号 + example: "ORIG123456789012" + maxLength: 40 + originalTranDate: + type: string + description: 原交易日期 + pattern: '^\d{8}$' + example: "20240101" + cancelReason: + type: string + description: 取消原因 + example: "用户申请取消" + maxLength: 200 + contractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 30 + payAmount: + type: string + description: 缴费金额（单位：分） + example: "15000" + + # 取消代扣交易响应 + WithholdingCancelDiscResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + companyId: + type: string + description: 机构编码 + example: "654321" + originalTranSeq: + type: string + description: 原交易流水号 + example: "ORIG123456789012" + cancelStatus: + type: string + description: 取消状态（1：成功，0：失败） + enum: ["0", "1"] + example: "1" + cancelTime: + type: string + description: 取消时间 + pattern: '^\d{14}$' + example: "20240101120000" + + # 代扣送盘状态查询请求 + WithholdingSendDiscCheckRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - billKey + - companyId + - originalTranSeq + - originalTranDate + - contractNo + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + companyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + originalTranSeq: + type: string + description: 原交易流水号 + example: "ORIG123456789012" + maxLength: 40 + originalTranDate: + type: string + description: 原交易日期 + pattern: '^\d{8}$' + example: "20240101" + contractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 30 + + # 代扣送盘状态查询响应 + WithholdingSendDiscCheckResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + companyId: + type: string + description: 机构编码 + example: "654321" + originalTranSeq: + type: string + description: 原交易流水号 + example: "ORIG123456789012" + discStatus: + type: string + description: 送盘状态（0：待处理，1：处理中，2：处理成功，3：处理失败，4：已取消） + enum: ["0", "1", "2", "3", "4"] + example: "2" + discStatusDesc: + type: string + description: 送盘状态描述 + example: "处理成功" + discTime: + type: string + description: 处理时间 + pattern: '^\d{14}$' + example: "20240101120000" + payAmount: + type: string + description: 缴费金额（单位：分） + example: "15000" + failReason: + type: string + description: 失败原因 + example: "" + + # 代扣回盘状态查询请求 + WithholdingBackDiscCheckRequest: + allOf: + - $ref: '#/components/schemas/BaseRequest' + - type: object + xml: + name: "in" + required: + - billKey + - companyId + - originalTranSeq + - originalTranDate + - contractNo + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + companyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + originalTranSeq: + type: string + description: 原交易流水号 + example: "ORIG123456789012" + maxLength: 40 + originalTranDate: + type: string + description: 原交易日期 + pattern: '^\d{8}$' + example: "20240101" + contractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 30 + batchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + maxLength: 50 + + # 代扣回盘状态查询响应 + WithholdingBackDiscCheckResponse: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + xml: + name: "out" + properties: + billKey: + type: string + description: 客户编号 + example: "123456" + companyId: + type: string + description: 机构编码 + example: "654321" + originalTranSeq: + type: string + description: 原交易流水号 + example: "ORIG123456789012" + discStatus: + type: string + description: 回盘状态（0：待处理，1：处理中，2：处理成功，3：处理失败，4：已取消） + enum: ["0", "1", "2", "3", "4"] + example: "2" + discStatusDesc: + type: string + description: 回盘状态描述 + example: "处理成功" + discTime: + type: string + description: 处理时间 + pattern: '^\d{14}$' + example: "20240101120000" + payAmount: + type: string + description: 缴费金额（单位：分） + example: "15000" + actualPayAmount: + type: string + description: 实际扣款金额（单位：分） + example: "15000" + batchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + clearingDate: + type: string + description: 清算日期 + pattern: '^\d{8}$' + example: "20240102" + failReason: + type: string + description: 失败原因 + example: "" + + \ No newline at end of file diff --git a/docs/api/openapi/main/components/security.yaml b/docs/api/openapi/main/components/security.yaml new file mode 100644 index 0000000..eef9bd6 --- /dev/null +++ b/docs/api/openapi/main/components/security.yaml @@ -0,0 +1,42 @@ +components: + securitySchemes: + # API密钥认证 + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + description: API密钥认证 + + # 加密数据认证 + EncryptedData: + type: apiKey + in: header + name: X-Encrypted-Data + description: | + 加密数据认证方式，支持以下加密算法： + - 3DES: 使用3DES ECB模式，PKCS7填充 + - SM2: 使用SM2非对称加密，支持C1C3C2和C1C2C3模式 + - SM4: 使用SM4对称加密，支持ECB和CBC模式 + + 加密后的数据需要进行Base64编码传输。 + + # 机构认证 + InstAuth: + type: http + scheme: basic + description: 机构编码认证（基于HTTP Basic Auth） + + # 数字签名认证 + DigitalSign: + type: apiKey + in: header + name: X-Digital-Sign + description: | + 数字签名认证，使用以下方式： + 1. 将请求数据按指定规则排序 + 2. 使用指定密钥进行签名 + 3. 将签名结果Base64编码后放入请求头 + + 支持的签名算法： + - SHA256withRSA + - SM3withSM2 \ No newline at end of file diff --git a/docs/api/openapi/main/openapi.yaml b/docs/api/openapi/main/openapi.yaml new file mode 100644 index 0000000..f4aa571 --- /dev/null +++ b/docs/api/openapi/main/openapi.yaml @@ -0,0 +1,381 @@ +openapi: 3.0.3 +info: + title: 营收系统接口API + description: | + 营收系统与银行/第三方支付机构之间的接口交互API文档 + + ## 特性 + - 支持账单查询、缴费、红冲等核心功能 + - 支持银行代扣签约、解约、送盘、回盘 + - 支持XML和JSON两种数据格式 + - 支持多种加密算法（3DES、SM2、SM4） + - 统一错误码和响应格式 + + ## 安全认证 + 本API使用多种加密方式保证数据安全传输： + - 数据加密后Base64编码传输 + - 支持3DES、SM2、SM4等加密算法 + - 通过请求头指定加密类型和模式 + + version: 1.0.0 + contact: + name: 营收系统API支持 + email: support@billing-system.com + license: + name: 专有许可证 + +servers: + - url: https://api.billing-system.com + description: 生产环境 + - url: https://test-api.billing-system.com + description: 测试环境 + - url: https://dev-api.billing-system.com + description: 开发环境 + +tags: + - name: 账单管理 + description: 账单查询、缴费、红冲相关接口 + - name: 代扣管理 + description: 银行代扣签约、解约、送盘、回盘相关接口 + +paths: + # 账单查询 + /api/app/payCeb/getChargeSearch: + $ref: './paths/bill-query.yaml#/BillQuery' + + # 账单缴费 + /api/app/payCeb/getChargeOffs: + $ref: './paths/bill-pay.yaml#/BillPay' + + # 账单红冲 + /api/app/payInvalid/payInvalid: + $ref: './paths/pay-invalid.yaml#/PayInvalid' + + # 代扣签约 + /api/app/bankWithholding/signing: + $ref: './paths/withholding-signing.yaml#/WithholdingSigning' + + # 代扣解约 + /api/app/bankWithholding/termination: + $ref: './paths/withholding-termination.yaml#/WithholdingTermination' + + # 代扣送盘 + /api/app/bankWithholding/sendDisc: + $ref: './paths/withholding-send-disc.yaml#/WithholdingSendDisc' + + # 代扣回盘 + /api/app/bankWithholding/backDisc: + $ref: './paths/withholding-back-disc.yaml#/WithholdingBackDisc' + + # 对账接口 + /api/app/payCeb/paymentCheck: + $ref: './paths/payment-check.yaml#/PaymentCheck' + + # 取消代扣交易 + /api/app/bankWithholding/cancelDisc: + $ref: './paths/withholding-cancel-disc.yaml#/WithholdingCancelDisc' + + # 代扣送盘状态查询 + /api/app/bankWithholding/sendDiscCheck: + $ref: './paths/withholding-send-disc-check.yaml#/WithholdingSendDiscCheck' + + # 代扣回盘状态查询 + /api/app/bankWithholding/backDiscCheck: + $ref: './paths/withholding-back-disc-check.yaml#/WithholdingBackDiscCheck' + + # 客户基本信息查询 + /api/app/customer/check: + $ref: './paths/customer-check.yaml#/CustomerCheck' + +components: + # 数据模型 + schemas: + # 基础请求模型 + BaseRequest: + type: object + required: + - Version + - InstId + - TranCode + - TranDate + - TranSeq + properties: + Version: + type: string + description: 版本号 + example: "1.0.1" + InstId: + type: string + description: 机构编码 + example: "00001" + maxLength: 30 + TranCode: + type: string + description: 交易码 + example: "Query" + maxLength: 20 + TranDate: + type: string + description: 交易日期 + pattern: '^\d{8}$' + example: "20240101" + TranSeq: + type: string + description: 交易流水号（银行生成的唯一标识） + example: "123456789012" + maxLength: 40 + + # 基础响应模型 + BaseResponse: + type: object + required: + - Version + - InstId + - TranCode + - TranDate + - TranSeq + - RespCode + - RespMessage + properties: + Version: + type: string + description: 版本号 + example: "1.0.1" + InstId: + type: string + description: 机构编码 + example: "00001" + TranCode: + type: string + description: 交易码 + example: "QueryRes" + TranDate: + type: string + description: 交易日期 + pattern: '^\d{8}$' + example: "20240101" + TranSeq: + type: string + description: 交易流水号 + example: "123456789012" + RespCode: + type: string + description: 返回码 + enum: + - "AAAAAAA" # 成功 + - "DEF0001" # 无相应记录 + - "DEF0002" # 缴费金额不匹配 + - "SYS1001" # 系统异常 + - "SEC2001" # 加密错误 + example: "AAAAAAA" + RespMessage: + type: string + description: 返回消息 + example: "成功" + maxLength: 60 + + # 错误详情 + ErrorDetail: + type: object + properties: + ErrorCode: + type: string + description: 错误码 + example: "DEF0001" + ErrorMsg: + type: string + description: 错误消息 + example: "用户编号123456不存在" + ErrorTime: + type: string + format: date-time + description: 错误时间 + example: "2024-01-01T12:00:00.000Z" + + # 其他数据模型引用原有文件 + BillQueryRequest: + $ref: './components/schemas.yaml#/components/schemas/BillQueryRequest' + + BillQueryResponse: + $ref: './components/schemas.yaml#/components/schemas/BillQueryResponse' + + BillPayRequest: + $ref: './components/schemas.yaml#/components/schemas/BillPayRequest' + + BillPayResponse: + $ref: './components/schemas.yaml#/components/schemas/BillPayResponse' + + # 响应组件 + responses: + # 业务错误响应 + BusinessError: + description: 业务处理错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 系统错误响应 + SystemError: + description: 系统异常错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 安全错误响应 + SecurityError: + description: 安全验证错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 网络错误响应 + NetworkError: + description: 网络通信错误 + content: + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + application/json: + schema: + allOf: + - $ref: '#/components/schemas/BaseResponse' + - type: object + properties: + ErrorDetail: + $ref: '#/components/schemas/ErrorDetail' + + # 参数组件 + parameters: + ContentTypeHeader: + name: Content-Type + in: header + required: true + description: 请求内容类型 + schema: + type: string + enum: + - application/xml + - application/json + example: "application/xml" + + EncryptTypeHeader: + name: X-Encrypt-Type + in: header + required: false + description: 加密算法类型 + schema: + type: string + enum: + - "3DES" + - "SM2" + - "SM4" + example: "3DES" + + EncryptModeHeader: + name: X-Encrypt-Mode + in: header + required: false + description: 加密模式 + schema: + type: string + enum: + - "ECB" + - "CBC" + example: "ECB" + + DataTypeHeader: + name: X-Data-Type + in: header + required: false + description: 数据格式类型 + schema: + type: string + enum: + - "XML" + - "JSON" + example: "XML" + + # 响应头组件 + headers: + ContentType: + description: 响应内容类型 + schema: + type: string + example: "application/xml; charset=GBK" + + ResponseTime: + description: 响应时间（毫秒） + schema: + type: integer + example: 150 + + RequestId: + description: 请求唯一标识 + schema: + type: string + example: "req-123456789012" + + # 安全认证组件 + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + description: API密钥认证 + + EncryptedData: + type: http + scheme: bearer + bearerFormat: encrypted + description: 加密数据传输认证 + +security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/bill-pay.yaml b/docs/api/openapi/main/paths/bill-pay.yaml new file mode 100644 index 0000000..c8a1396 --- /dev/null +++ b/docs/api/openapi/main/paths/bill-pay.yaml @@ -0,0 +1,140 @@ +BillPay: + post: + tags: + - 账单管理 + summary: 账单缴费 + description: | + 执行账单缴费操作，支持多种支付渠道。 + + ## 业务说明 + - 支持指定客户编号和缴费金额进行缴费 + - 支持多种二级支付渠道（支付宝、微信等） + - 实时更新账单状态和生成交易记录 + - 支持XML和JSON两种数据格式 + - 缴费金额必须与账单金额完全匹配 + + ## 业务规则 + - 缴费金额必须大于0.01元 + - 账单状态必须为未缴费状态 + - 同一笔账单不能重复缴费 + - 缴费成功后账单状态自动更新为已缴费 + + ## 调用频率限制 + - 单个客户编号每分钟最多缴费5次 + - 单个机构每分钟最多缴费500次 + + operationId: payBill + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 账单缴费请求数据 + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillPayRequest' + example: | + + + 1.0.1 + 00001 + Pay + 20240101 + 123456789012 + 123456 + 654321 + 150.00 + 1 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillPayRequest' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "Pay" + TranDate: "20240101" + TranSeq: "123456789012" + BillKey: "123456" + CompanyId: "654321" + PayAmount: 150.00 + SubChannel: 1 + + responses: + '200': + description: 缴费成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillPayResponse' + example: | + + + 1.0.1 + 00001 + PayRes + 20240101 + 123456789012 + AAAAAAA + 缴费成功 + + + TXN123456789012 + 123456 + 654321 + Pay + 150.00 + 2024-01-01T12:00:00.000Z + 1 + 1 + AAAAAAA + 成功 + + + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillPayResponse' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "PayRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "AAAAAAA" + RespMessage: "缴费成功" + Data: + Transaction: + TranSeq: "TXN123456789012" + BillKey: "123456" + CompanyId: "654321" + TranCode: "Pay" + PayAmount: 150.00 + PayDate: "2024-01-01T12:00:00.000Z" + SubChannel: 1 + TranStatus: 1 + RespCode: "AAAAAAA" + RespMessage: "成功" + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/bill-query.yaml b/docs/api/openapi/main/paths/bill-query.yaml new file mode 100644 index 0000000..b3b6d97 --- /dev/null +++ b/docs/api/openapi/main/paths/bill-query.yaml @@ -0,0 +1,136 @@ +BillQuery: + post: + tags: + - 账单管理 + summary: 账单查询 + description: | + 根据客户编号查询账单信息，包括客户基本信息和账单详情。 + + ## 业务说明 + - 支持根据客户编号（缴费号）查询账单 + - 返回客户基本信息和未缴费账单列表 + - 支持XML和JSON两种数据格式 + - 数据传输支持多种加密方式 + + ## 调用频率限制 + - 单个客户编号每分钟最多查询10次 + - 单个机构每分钟最多查询1000次 + + operationId: queryBill + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 账单查询请求数据 + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillQueryRequest' + example: | + + + 1.0.1 + 00001 + Query + 20240101 + 123456789012 + 123456 + 654321 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillQueryRequest' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "Query" + TranDate: "20240101" + TranSeq: "123456789012" + BillKey: "123456" + CompanyId: "654321" + + responses: + '200': + description: 查询成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillQueryResponse' + example: | + + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + AAAAAAA + 成功 + + + 123456 + 张三 + CONTRACT001 + 654321 + + + + 123456 + 654321 + 150.00 + 0.00 + 2024-01-01 + 2024-01-31 + 0 + + + + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/BillQueryResponse' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "QueryRes" + TranDate: "20240101" + TranSeq: "123456789012" + RespCode: "AAAAAAA" + RespMessage: "成功" + Data: + Customer: + BillKey: "123456" + CustomerName: "张三" + ContractNo: "CONTRACT001" + CompanyId: "654321" + Bills: + - BillKey: "123456" + CompanyId: "654321" + PayAmount: 150.00 + Balance: 0.00 + BeginDate: "2024-01-01" + EndDate: "2024-01-31" + BillStatus: 0 + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/customer-check.yaml b/docs/api/openapi/main/paths/customer-check.yaml new file mode 100644 index 0000000..10e3e85 --- /dev/null +++ b/docs/api/openapi/main/paths/customer-check.yaml @@ -0,0 +1,107 @@ +CustomerCheck: + post: + tags: + - 账单管理 + summary: 客户基本信息查询 + description: | + 银行向公用事业单位发起的客户基本信息查询请求接口。 + 用于查询客户的基本信息，包括客户姓名、联系方式、地址等详细信息。 + + ## 交易码说明 + - 请求交易码：CustomerCheck + - 应答交易码：CustomerCheckRes + + ## 查询信息包括 + - 客户基本信息：姓名、身份证号等 + - 客户联系信息：电话、地址等 + - 客户状态信息：账户状态、服务状态等 + - 历史缴费记录摘要 + + ## 使用场景 + - 客户信息核验 + - 代扣协议签约前的客户信息确认 + - 客户服务和支持 + - 风险评估和反欺诈检查 + + operationId: customerCheck + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/CustomerCheckRequest' + example: | + + + 1.0.1 + 00001 + CustomerCheck + 20240101 + 123456789012 + 123456 + 654321 + 0 + CONTRACT001 + + + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/CustomerCheckRequest' + responses: + '200': + description: 客户基本信息查询成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/CustomerCheckResponse' + example: | + + + 1.0.1 + 00001 + CustomerCheckRes + 20240101 + 123456789012 + AAAAAAA + 查询成功 + 123456 + 654321 + CONTRACT001 + 张三 + 13812345678 + 北京市朝阳区xxx街道xxx号 + 1 + 1 + 20200101 + 20231215 + 36 + 540000 + + + + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/CustomerCheckResponse' + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '403': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/pay-invalid.yaml b/docs/api/openapi/main/paths/pay-invalid.yaml new file mode 100644 index 0000000..80d9436 --- /dev/null +++ b/docs/api/openapi/main/paths/pay-invalid.yaml @@ -0,0 +1,192 @@ +PayInvalid: + post: + tags: + - 账单管理 + summary: 账单红冲 + description: | + 对已缴费的账单进行红冲（撤销）操作。 + + ## 业务说明 + - 支持对已缴费账单进行红冲操作 + - 红冲后账单状态恢复为未缴费 + - 生成红冲交易记录 + - 支持XML和JSON两种数据格式 + + ## 业务规则 + - 只能对已缴费的账单进行红冲 + - 红冲金额必须与原缴费金额一致 + - 同一笔缴费记录只能红冲一次 + - 红冲成功后生成负数交易记录 + + ## 调用频率限制 + - 单个交易流水号每分钟最多红冲1次 + - 单个机构每分钟最多红冲100次 + + operationId: invalidPayment + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 账单红冲请求数据 + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - OriginalTranSeq + - BillKey + - CompanyId + properties: + OriginalTranSeq: + type: string + description: 原交易流水号 + example: "TXN123456789012" + maxLength: 40 + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + example: | + + + 1.0.1 + 00001 + PayInvalid + 20240101 + 123456789013 + TXN123456789012 + 123456 + 654321 + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - OriginalTranSeq + - BillKey + - CompanyId + properties: + OriginalTranSeq: + type: string + description: 原交易流水号 + example: "TXN123456789012" + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "PayInvalid" + TranDate: "20240101" + TranSeq: "123456789013" + OriginalTranSeq: "TXN123456789012" + BillKey: "123456" + CompanyId: "654321" + + responses: + '200': + description: 红冲成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + Transaction: + $ref: '../components/schemas.yaml#/components/schemas/Transaction' + example: | + + + 1.0.1 + 00001 + PayInvalidRes + 20240101 + 123456789013 + AAAAAAA + 红冲成功 + + + REV123456789013 + 123456 + 654321 + PayInvalid + -150.00 + 2024-01-01T12:00:00.000Z + 1 + AAAAAAA + 成功 + + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + Transaction: + $ref: '../components/schemas.yaml#/components/schemas/Transaction' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "PayInvalidRes" + TranDate: "20240101" + TranSeq: "123456789013" + RespCode: "AAAAAAA" + RespMessage: "红冲成功" + Data: + Transaction: + TranSeq: "REV123456789013" + BillKey: "123456" + CompanyId: "654321" + TranCode: "PayInvalid" + PayAmount: -150.00 + PayDate: "2024-01-01T12:00:00.000Z" + TranStatus: 1 + RespCode: "AAAAAAA" + RespMessage: "成功" + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/payment-check.yaml b/docs/api/openapi/main/paths/payment-check.yaml new file mode 100644 index 0000000..3d8b4cb --- /dev/null +++ b/docs/api/openapi/main/paths/payment-check.yaml @@ -0,0 +1,92 @@ +PaymentCheck: + post: + tags: + - 账单管理 + summary: 缴费单对账 + description: | + 代理收费向公用事业单位发起的缴费单对账请求接口。 + 由代理收费公司每天日切后，进行批处理，自动生成和传送对账文件给公用事业单位。 + + ## 交易码说明 + - 请求交易码：PayCheck + - 应答交易码：PayCheckRes + + ## 对账文件格式 + 对账文件为文本文件txt格式，编码格式为UTF-8，包括明细行和汇总行。 + 行内每个分项之间以"|"为分隔符。 + + ### 汇总行格式 + `交易笔数|总金额` + + ### 明细行格式 + `交易日期|交易流水号|客户编号|缴费金额|二级渠道|交易类型` + + operationId: paymentCheck + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/PaymentCheckRequest' + example: | + + + 1.0.1 + 00001 + PayCheck + 20240101 + 123456789012 + 654321 + 20240101 + 10 + 150000 + 654321_20240101.txt + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/PaymentCheckRequest' + responses: + '200': + description: 对账成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/PaymentCheckResponse' + example: | + + + 1.0.1 + 00001 + PayCheckRes + 20240101 + 123456789012 + AAAAAAA + 对账成功 + 654321 + 20240101 + 150000 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/PaymentCheckResponse' + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '403': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-back-disc-check.yaml b/docs/api/openapi/main/paths/withholding-back-disc-check.yaml new file mode 100644 index 0000000..6f07175 --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-back-disc-check.yaml @@ -0,0 +1,104 @@ +WithholdingBackDiscCheck: + post: + tags: + - 代扣管理 + summary: 代扣回盘状态查询 + description: | + 银行向公用事业单位发起的代扣回盘状态查询请求接口。 + 用于查询已发起的代扣回盘交易的当前处理状态。 + + ## 交易码说明 + - 请求交易码：BackDiscCheck + - 应答交易码：BackDiscCheckRes + + ## 查询状态说明 + - 0: 待处理 + - 1: 处理中 + - 2: 处理成功 + - 3: 处理失败 + - 4: 已取消 + + ## 使用场景 + - 银行系统需要确认回盘交易状态 + - 处理异常情况的状态核查 + - 定时批量状态查询 + - 对账和清算流程中的状态确认 + + operationId: withholdingBackDiscCheck + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingBackDiscCheckRequest' + example: | + + + 1.0.1 + 00001 + BackDiscCheck + 20240101 + 123456789012 + 123456 + 654321 + ORIG123456789012 + 20240101 + CONTRACT001 + BATCH20240101001 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingBackDiscCheckRequest' + responses: + '200': + description: 代扣回盘状态查询成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingBackDiscCheckResponse' + example: | + + + 1.0.1 + 00001 + BackDiscCheckRes + 20240101 + 123456789012 + AAAAAAA + 查询成功 + 123456 + 654321 + ORIG123456789012 + 2 + 处理成功 + 20240101120000 + 15000 + 15000 + BATCH20240101001 + 20240102 + + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingBackDiscCheckResponse' + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '403': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-back-disc.yaml b/docs/api/openapi/main/paths/withholding-back-disc.yaml new file mode 100644 index 0000000..3660f33 --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-back-disc.yaml @@ -0,0 +1,334 @@ +WithholdingBackDisc: + post: + tags: + - 代扣管理 + summary: 代扣回盘 + description: | + 银行代扣回盘接口，接收银行返回的代扣结果。 + + ## 业务说明 + - 接收银行处理代扣送盘后的结果反馈 + - 包含每笔代扣的成功或失败信息 + - 根据回盘结果更新账单和交易状态 + - 支持XML和JSON两种数据格式 + - 自动处理代扣成功和失败的业务逻辑 + + ## 业务规则 + - 回盘数据必须与送盘数据对应 + - 成功的代扣自动更新账单状态为已缴费 + - 失败的代扣保持原账单状态 + - 生成相应的交易记录和状态 + + ## 调用频率限制 + - 单个批次只能回盘一次 + - 支持银行异步回盘处理 + + operationId: withholdingBackDisc + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 代扣回盘请求数据 + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BatchNo + - TotalCount + - SuccessCount + - FailCount + - ResultList + properties: + BatchNo: + type: string + description: 原送盘批次号 + example: "BATCH20240101001" + maxLength: 50 + TotalCount: + type: integer + description: 总笔数 + example: 2 + minimum: 1 + SuccessCount: + type: integer + description: 成功笔数 + example: 1 + minimum: 0 + FailCount: + type: integer + description: 失败笔数 + example: 1 + minimum: 0 + ResultList: + type: array + description: 代扣结果列表 + items: + type: object + required: + - BillKey + - CompanyId + - AgreementNo + - PayAmount + - ResultCode + - ResultMessage + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + PayAmount: + type: number + format: decimal + description: 代扣金额 + example: 150.00 + ResultCode: + type: string + description: 代扣结果码 + enum: ["SUCCESS", "FAIL"] + example: "SUCCESS" + ResultMessage: + type: string + description: 代扣结果信息 + example: "代扣成功" + FailReason: + type: string + description: 失败原因（结果为FAIL时必填） + example: "余额不足" + example: | + + + 1.0.1 + 00001 + BackDisc + 20240101 + 123456789017 + BATCH20240101001 + 2 + 1 + 1 + + + 123456 + 654321 + AGR001 + 150.00 + SUCCESS + 代扣成功 + + + 123457 + 654321 + AGR002 + 150.00 + FAIL + 代扣失败 + 余额不足 + + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BatchNo + - TotalCount + - SuccessCount + - FailCount + - ResultList + properties: + BatchNo: + type: string + description: 原送盘批次号 + example: "BATCH20240101001" + TotalCount: + type: integer + description: 总笔数 + example: 2 + SuccessCount: + type: integer + description: 成功笔数 + example: 1 + FailCount: + type: integer + description: 失败笔数 + example: 1 + ResultList: + type: array + description: 代扣结果列表 + items: + type: object + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + PayAmount: + type: number + format: decimal + description: 代扣金额 + example: 150.00 + ResultCode: + type: string + description: 代扣结果码 + example: "SUCCESS" + ResultMessage: + type: string + description: 代扣结果信息 + example: "代扣成功" + FailReason: + type: string + description: 失败原因 + example: "余额不足" + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "BackDisc" + TranDate: "20240101" + TranSeq: "123456789017" + BatchNo: "BATCH20240101001" + TotalCount: 2 + SuccessCount: 1 + FailCount: 1 + ResultList: + - BillKey: "123456" + CompanyId: "654321" + AgreementNo: "AGR001" + PayAmount: 150.00 + ResultCode: "SUCCESS" + ResultMessage: "代扣成功" + - BillKey: "123457" + CompanyId: "654321" + AgreementNo: "AGR002" + PayAmount: 150.00 + ResultCode: "FAIL" + ResultMessage: "代扣失败" + FailReason: "余额不足" + + responses: + '200': + description: 回盘处理成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + ProcessedCount: + type: integer + description: 已处理笔数 + example: 2 + UpdatedBills: + type: integer + description: 更新账单数 + example: 1 + CreatedTransactions: + type: integer + description: 创建交易数 + example: 2 + example: | + + + 1.0.1 + 00001 + BackDiscRes + 20240101 + 123456789017 + AAAAAAA + 回盘处理成功 + + BATCH20240101001 + 2 + 1 + 2 + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + ProcessedCount: + type: integer + description: 已处理笔数 + example: 2 + UpdatedBills: + type: integer + description: 更新账单数 + example: 1 + CreatedTransactions: + type: integer + description: 创建交易数 + example: 2 + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "BackDiscRes" + TranDate: "20240101" + TranSeq: "123456789017" + RespCode: "AAAAAAA" + RespMessage: "回盘处理成功" + Data: + BatchNo: "BATCH20240101001" + ProcessedCount: 2 + UpdatedBills: 1 + CreatedTransactions: 2 + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-cancel-disc.yaml b/docs/api/openapi/main/paths/withholding-cancel-disc.yaml new file mode 100644 index 0000000..67221b6 --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-cancel-disc.yaml @@ -0,0 +1,96 @@ +WithholdingCancelDisc: + post: + tags: + - 代扣管理 + summary: 取消代扣交易 + description: | + 银行向公用事业单位发起的取消代扣交易请求接口。 + 用于取消已经发起但尚未完成的代扣交易。 + + ## 交易码说明 + - 请求交易码：CancelDisc + - 应答交易码：CancelDiscRes + + ## 使用场景 + - 代扣交易发起后，用户要求取消 + - 代扣交易异常需要撤销 + - 银行系统故障需要回滚交易 + + ## 注意事项 + - 只能取消当天发起的代扣交易 + - 已经成功扣款的交易不能取消，需要通过退款流程处理 + - 取消成功后，相关的代扣协议仍然有效 + + operationId: withholdingCancelDisc + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingCancelDiscRequest' + example: | + + + 1.0.1 + 00001 + CancelDisc + 20240101 + 123456789012 + 123456 + 654321 + ORIG123456789012 + 20240101 + 用户申请取消 + CONTRACT001 + 15000 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingCancelDiscRequest' + responses: + '200': + description: 取消代扣交易成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingCancelDiscResponse' + example: | + + + 1.0.1 + 00001 + CancelDiscRes + 20240101 + 123456789012 + AAAAAAA + 取消代扣交易成功 + 123456 + 654321 + ORIG123456789012 + 1 + 20240101120000 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingCancelDiscResponse' + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '403': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-send-disc-check.yaml b/docs/api/openapi/main/paths/withholding-send-disc-check.yaml new file mode 100644 index 0000000..f5c7559 --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-send-disc-check.yaml @@ -0,0 +1,99 @@ +WithholdingSendDiscCheck: + post: + tags: + - 代扣管理 + summary: 代扣送盘状态查询 + description: | + 银行向公用事业单位发起的代扣送盘状态查询请求接口。 + 用于查询已发起的代扣送盘交易的当前处理状态。 + + ## 交易码说明 + - 请求交易码：SendDiscCheck + - 应答交易码：SendDiscCheckRes + + ## 查询状态说明 + - 0: 待处理 + - 1: 处理中 + - 2: 处理成功 + - 3: 处理失败 + - 4: 已取消 + + ## 使用场景 + - 银行系统需要确认送盘交易状态 + - 处理异常情况的状态核查 + - 定时批量状态查询 + + operationId: withholdingSendDiscCheck + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingSendDiscCheckRequest' + example: | + + + 1.0.1 + 00001 + SendDiscCheck + 20240101 + 123456789012 + 123456 + 654321 + ORIG123456789012 + 20240101 + CONTRACT001 + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingSendDiscCheckRequest' + responses: + '200': + description: 代扣送盘状态查询成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingSendDiscCheckResponse' + example: | + + + 1.0.1 + 00001 + SendDiscCheckRes + 20240101 + 123456789012 + AAAAAAA + 查询成功 + 123456 + 654321 + ORIG123456789012 + 2 + 处理成功 + 20240101120000 + 15000 + + + application/json: + schema: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingSendDiscCheckResponse' + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '403': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-send-disc.yaml b/docs/api/openapi/main/paths/withholding-send-disc.yaml new file mode 100644 index 0000000..9e93a04 --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-send-disc.yaml @@ -0,0 +1,287 @@ +WithholdingSendDisc: + post: + tags: + - 代扣管理 + summary: 代扣送盘 + description: | + 银行代扣送盘接口，向银行发送批量代扣请求。 + + ## 业务说明 + - 支持批量向银行发送代扣请求 + - 包含待代扣的账单信息和客户信息 + - 支持本行和他行账户代扣 + - 送盘成功后等待银行回盘确认 + - 支持XML和JSON两种数据格式 + + ## 业务规则 + - 只能对已签约且有效的协议进行代扣 + - 代扣金额必需与账单金额一致 + - 客户账户余额必须充足 + - 送盘成功后生成代扣交易记录 + + ## 调用频率限制 + - 单个批次最多包含1000笔代扣 + - 单个机构每小时最多送盘10次 + + operationId: withholdingSendDisc + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 代扣送盘请求数据 + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BatchNo + - TotalCount + - TotalAmount + - WithholdingList + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + maxLength: 50 + TotalCount: + type: integer + description: 总笔数 + example: 10 + minimum: 1 + maximum: 1000 + TotalAmount: + type: number + format: decimal + description: 总金额 + example: 1500.00 + minimum: 0.01 + WithholdingList: + type: array + description: 代扣明细列表 + items: + type: object + required: + - BillKey + - CompanyId + - AgreementNo + - PayAmount + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + PayAmount: + type: number + format: decimal + description: 代扣金额 + example: 150.00 + example: | + + + 1.0.1 + 00001 + SendDisc + 20240101 + 123456789016 + BATCH20240101001 + 2 + 300.00 + + + 123456 + 654321 + AGR001 + 150.00 + + + 123457 + 654321 + AGR002 + 150.00 + + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BatchNo + - TotalCount + - TotalAmount + - WithholdingList + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + TotalCount: + type: integer + description: 总笔数 + example: 2 + TotalAmount: + type: number + format: decimal + description: 总金额 + example: 300.00 + WithholdingList: + type: array + description: 代扣明细列表 + items: + type: object + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + PayAmount: + type: number + format: decimal + description: 代扣金额 + example: 150.00 + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "SendDisc" + TranDate: "20240101" + TranSeq: "123456789016" + BatchNo: "BATCH20240101001" + TotalCount: 2 + TotalAmount: 300.00 + WithholdingList: + - BillKey: "123456" + CompanyId: "654321" + AgreementNo: "AGR001" + PayAmount: 150.00 + - BillKey: "123457" + CompanyId: "654321" + AgreementNo: "AGR002" + PayAmount: 150.00 + + responses: + '200': + description: 送盘成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + ProcessedCount: + type: integer + description: 已处理笔数 + example: 2 + SuccessCount: + type: integer + description: 成功笔数 + example: 2 + FailCount: + type: integer + description: 失败笔数 + example: 0 + example: | + + + 1.0.1 + 00001 + SendDiscRes + 20240101 + 123456789016 + AAAAAAA + 送盘成功 + + BATCH20240101001 + 2 + 2 + 0 + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + BatchNo: + type: string + description: 批次号 + example: "BATCH20240101001" + ProcessedCount: + type: integer + description: 已处理笔数 + example: 2 + SuccessCount: + type: integer + description: 成功笔数 + example: 2 + FailCount: + type: integer + description: 失败笔数 + example: 0 + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "SendDiscRes" + TranDate: "20240101" + TranSeq: "123456789016" + RespCode: "AAAAAAA" + RespMessage: "送盘成功" + Data: + BatchNo: "BATCH20240101001" + ProcessedCount: 2 + SuccessCount: 2 + FailCount: 0 + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-signing.yaml b/docs/api/openapi/main/paths/withholding-signing.yaml new file mode 100644 index 0000000..b52cb25 --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-signing.yaml @@ -0,0 +1,243 @@ +WithholdingSigning: + post: + tags: + - 代扣管理 + summary: 代扣签约 + description: | + 银行代扣业务签约接口，建立客户与银行的代扣协议。 + + ## 业务说明 + - 支持客户与银行签署代扣协议 + - 包含客户基本信息和银行账户信息 + - 支持本行和他行账户签约 + - 签约成功后可进行自动代扣 + - 支持XML和JSON两种数据格式 + + ## 业务规则 + - 客户编号必须在系统中存在 + - 银行账户信息必须真实有效 + - 同一客户同一银行账户只能签约一次 + - 签约成功后协议状态为已签约 + + ## 调用频率限制 + - 单个客户编号每天最多签约5次 + - 单个机构每分钟最多签约50次 + + operationId: withholdingSigning + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 代扣签约请求数据 + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BillKey + - CompanyId + - AccountName + - AccountNo + - BankName + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + AccountName: + type: string + description: 开户名 + example: "张三" + maxLength: 150 + AccountNo: + type: string + description: 开户账号 + example: "6222001234567890" + maxLength: 30 + BankName: + type: string + description: 银行名称 + example: "中国工商银行" + maxLength: 150 + ContractNo: + type: string + description: 合同号 + example: "CONTRACT001" + maxLength: 150 + BankType: + type: integer + description: 银行类型 + enum: [0, 1] # 0:本行 1:他行 + example: 0 + example: | + + + 1.0.1 + 00001 + Signing + 20240101 + 123456789014 + 123456 + 654321 + 张三 + 6222001234567890 + 中国工商银行 + CONTRACT001 + 0 + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BillKey + - CompanyId + - AccountName + - AccountNo + - BankName + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + AccountName: + type: string + description: 开户名 + example: "张三" + AccountNo: + type: string + description: 开户账号 + example: "6222001234567890" + BankName: + type: string + description: 银行名称 + example: "中国工商银行" + ContractNo: + type: string + description: 合同号 + example: "CONTRACT001" + BankType: + type: integer + description: 银行类型 + example: 0 + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "Signing" + TranDate: "20240101" + TranSeq: "123456789014" + BillKey: "123456" + CompanyId: "654321" + AccountName: "张三" + AccountNo: "6222001234567890" + BankName: "中国工商银行" + ContractNo: "CONTRACT001" + BankType: 0 + + responses: + '200': + description: 签约成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + Agreement: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingAgreement' + example: | + + + 1.0.1 + 00001 + SigningRes + 20240101 + 123456789014 + AAAAAAA + 签约成功 + + + 123456 + 654321 + 张三 + 6222001234567890 + 中国工商银行 + CONTRACT001 + AGR001 + 0 + 1 + 2024-01-01 + + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + Agreement: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingAgreement' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "SigningRes" + TranDate: "20240101" + TranSeq: "123456789014" + RespCode: "AAAAAAA" + RespMessage: "签约成功" + Data: + Agreement: + BillKey: "123456" + CompanyId: "654321" + AccountName: "张三" + AccountNo: "6222001234567890" + BankName: "中国工商银行" + ContractNo: "CONTRACT001" + AgreementNo: "AGR001" + BankType: 0 + AgreementStatus: 1 + SigningDate: "2024-01-01" + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/main/paths/withholding-termination.yaml b/docs/api/openapi/main/paths/withholding-termination.yaml new file mode 100644 index 0000000..18459ac --- /dev/null +++ b/docs/api/openapi/main/paths/withholding-termination.yaml @@ -0,0 +1,184 @@ +WithholdingTermination: + post: + tags: + - 代扣管理 + summary: 代扣解约 + description: | + 银行代扣业务解约接口，终止客户与银行的代扣协议。 + + ## 业务说明 + - 支持客户解除与银行的代扣协议 + - 解约后不能再进行自动代扣 + - 支持XML和JSON两种数据格式 + - 解约后协议状态变更为已解约 + + ## 业务规则 + - 只能解约已签约状态的协议 + - 解约成功后协议状态更新为已解约 + - 同一协议只能解约一次 + - 解约不影响已产生的交易记录 + + ## 调用频率限制 + - 单个协议号每天最多解约1次 + - 单个机构每分钟最多解约20次 + + operationId: withholdingTermination + parameters: + - $ref: '../components/parameters.yaml#/components/parameters/ContentTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptTypeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/EncryptModeHeader' + - $ref: '../components/parameters.yaml#/components/parameters/DataTypeHeader' + requestBody: + required: true + description: 代扣解约请求数据 + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BillKey + - CompanyId + - AgreementNo + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + maxLength: 35 + CompanyId: + type: string + description: 机构编码 + example: "654321" + maxLength: 30 + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + maxLength: 150 + example: | + + + 1.0.1 + 00001 + Termination + 20240101 + 123456789015 + 123456 + 654321 + AGR001 + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseRequest' + - type: object + required: + - BillKey + - CompanyId + - AgreementNo + properties: + BillKey: + type: string + description: 客户编号 + example: "123456" + CompanyId: + type: string + description: 机构编码 + example: "654321" + AgreementNo: + type: string + description: 协议号 + example: "AGR001" + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "Termination" + TranDate: "20240101" + TranSeq: "123456789015" + BillKey: "123456" + CompanyId: "654321" + AgreementNo: "AGR001" + + responses: + '200': + description: 解约成功 + headers: + Content-Type: + $ref: '../components/headers.yaml#/components/headers/ContentType' + X-Response-Time: + $ref: '../components/headers.yaml#/components/headers/ResponseTime' + X-Request-Id: + $ref: '../components/headers.yaml#/components/headers/RequestId' + content: + application/xml: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + Agreement: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingAgreement' + example: | + + + 1.0.1 + 00001 + TerminationRes + 20240101 + 123456789015 + AAAAAAA + 解约成功 + + + 123456 + 654321 + AGR001 + 2 + 2024-01-01 + + + + application/json: + schema: + allOf: + - $ref: '../components/schemas.yaml#/components/schemas/BaseResponse' + - type: object + properties: + Data: + type: object + properties: + Agreement: + $ref: '../components/schemas.yaml#/components/schemas/WithholdingAgreement' + example: + Version: "1.0.1" + InstId: "00001" + TranCode: "TerminationRes" + TranDate: "20240101" + TranSeq: "123456789015" + RespCode: "AAAAAAA" + RespMessage: "解约成功" + Data: + Agreement: + BillKey: "123456" + CompanyId: "654321" + AgreementNo: "AGR001" + AgreementStatus: 2 + TerminationDate: "2024-01-01" + + '400': + $ref: '../components/responses.yaml#/components/responses/BusinessError' + '500': + $ref: '../components/responses.yaml#/components/responses/SystemError' + '401': + $ref: '../components/responses.yaml#/components/responses/SecurityError' + '408': + $ref: '../components/responses.yaml#/components/responses/NetworkError' + + security: + - ApiKeyAuth: [] + - EncryptedData: [] \ No newline at end of file diff --git a/docs/api/openapi/serve.js b/docs/api/openapi/serve.js new file mode 100644 index 0000000..a9e93bf --- /dev/null +++ b/docs/api/openapi/serve.js @@ -0,0 +1,119 @@ +#!/usr/bin/env node + +const express = require('express'); +const path = require('path'); +const fs = require('fs'); + +const app = express(); +const PORT = 3001; + +// 静态文件服务 +app.use('/docs', express.static(path.join(__dirname))); + +// 主页路由 +app.get('/', (req, res) => { + res.send(` + + + + 营收系统接口文档 + + + + +
+

🏦 营收系统接口OpenAPI文档

+

银行/第三方支付机构接口交互API文档 - 基于OpenAPI 3.0.3规范

+
+ +
+

📖 文档访问

+ + 在Swagger Editor中打开 + + + 查看原始YAML + + + 使用说明 + +
+ +
+

🚀 主要功能

+
账单管理: 查询、缴费、红冲
+
代扣管理: 签约、解约、送盘、回盘
+
多格式支持: XML (GBK) 和 JSON (UTF-8)
+
安全认证: 3DES、SM2、SM4多种加密算法
+
错误处理: 统一错误码和详细错误信息
+
+ +
+

📋 API概览

+
    +
  • POST /api/app/billQuery/query - 账单查询
    • +
  • POST /api/app/billPay/pay - 账单缴费
    • +
  • POST /api/app/payInvalid/payInvalid - 账单红冲
    • +
  • POST /api/app/bankWithholding/signing - 代扣签约
    • +
  • POST /api/app/bankWithholding/termination - 代扣解约
    • +
  • POST /api/app/bankWithholding/sendDisc - 代扣送盘
    • +
  • POST /api/app/bankWithholding/backDisc - 代扣回盘
    • +
+
+ +
+

🔧 快速测试

+

账单查询示例（JSON格式）:

+ 
{
+  "Version": "1.0.1",
+  "InstId": "00001",
+  "TranCode": "Query",
+  "TranDate": "20240101",
+  "TranSeq": "123456789012",
+  "BillKey": "123456",
+  "CompanyId": "654321"
+}
+
+ +
+

🛠️ 开发工具

+

推荐使用以下工具进行API开发和测试：

+ +
+ +
+

营收系统接口API v1.0.0 | OpenAPI 3.0.3

+
+ + + `); +}); + +// 启动服务器 +app.listen(PORT, () => { + console.log('🚀 营收系统接口文档服务已启动!'); + console.log(`📖 访问地址: http://localhost:${PORT}`); + console.log(`📋 Swagger Editor: https://editor.swagger.io/?url=http://localhost:${PORT}/docs/main/openapi.yaml`); + console.log(''); + console.log('📁 文档结构:'); + console.log('├── docs/main/openapi.yaml # 主入口文档'); + console.log('├── docs/main/components/ # 通用组件'); + console.log('└── docs/main/paths/ # API路径定义'); + console.log(''); + console.log('按 Ctrl+C 停止服务'); +}); + +module.exports = app; \ No newline at end of file diff --git a/docs/api/openapi/validate.js b/docs/api/openapi/validate.js new file mode 100644 index 0000000..69efe56 --- /dev/null +++ b/docs/api/openapi/validate.js @@ -0,0 +1,119 @@ +#!/usr/bin/env node + +const YAML = require('yaml'); +const fs = require('fs'); +const path = require('path'); + +/** + * 验证OpenAPI文档的基本语法和结构 + */ +function validateOpenAPIDoc() { + try { + console.log('🔍 开始验证营收系统OpenAPI文档...\n'); + + // 读取主文档 + const mainDocPath = path.join(__dirname, 'main', 'openapi.yaml'); + const mainContent = fs.readFileSync(mainDocPath, 'utf8'); + const mainDoc = YAML.parse(mainContent); + + // 验证基本结构 + console.log('✅ 主文档语法正确'); + console.log(`📋 API标题: ${mainDoc.info.title}`); + console.log(`📋 API版本: ${mainDoc.info.version}`); + console.log(`📋 OpenAPI版本: ${mainDoc.openapi}`); + + // 验证服务器配置 + if (mainDoc.servers && mainDoc.servers.length > 0) { + console.log(`🌐 配置了 ${mainDoc.servers.length} 个服务器环境:`); + mainDoc.servers.forEach((server, index) => { + console.log(` ${index + 1}. ${server.description}: ${server.url}`); + }); + } + + // 验证标签 + if (mainDoc.tags && mainDoc.tags.length > 0) { + console.log(`🏷️ 定义了 ${mainDoc.tags.length} 个标签:`); + mainDoc.tags.forEach((tag, index) => { + console.log(` ${index + 1}. ${tag.name}: ${tag.description}`); + }); + } + + // 验证路径 + if (mainDoc.paths) { + const pathCount = Object.keys(mainDoc.paths).length; + console.log(`🛣️ 定义了 ${pathCount} 个API路径:`); + Object.keys(mainDoc.paths).forEach((path, index) => { + console.log(` ${index + 1}. ${path}`); + }); + } + + // 验证组件文件 + console.log('\n🔧 验证组件文件:'); + const componentFiles = [ + 'components/schemas.yaml', + 'components/responses.yaml', + 'components/parameters.yaml', + 'components/headers.yaml', + 'components/security.yaml' + ]; + + componentFiles.forEach(file => { + const filePath = path.join(__dirname, 'main', file); + if (fs.existsSync(filePath)) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + YAML.parse(content); + console.log(` ✅ ${file}`); + } catch (error) { + console.log(` ❌ ${file}: ${error.message}`); + } + } else { + console.log(` ⚠️ ${file}: 文件不存在`); + } + }); + + // 验证路径文件 + console.log('\n🛤️ 验证路径文件:'); + const pathFiles = [ + 'paths/bill-query.yaml', + 'paths/bill-pay.yaml', + 'paths/pay-invalid.yaml', + 'paths/withholding-signing.yaml', + 'paths/withholding-termination.yaml', + 'paths/withholding-send-disc.yaml', + 'paths/withholding-back-disc.yaml' + ]; + + pathFiles.forEach(file => { + const filePath = path.join(__dirname, 'main', file); + if (fs.existsSync(filePath)) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + YAML.parse(content); + console.log(` ✅ ${file}`); + } catch (error) { + console.log(` ❌ ${file}: ${error.message}`); + } + } else { + console.log(` ⚠️ ${file}: 文件不存在`); + } + }); + + console.log('\n🎉 OpenAPI文档验证完成!'); + console.log('\n📖 使用方法:'); + console.log('1. 在Swagger Editor中打开 docs/main/openapi.yaml'); + console.log('2. 或使用命令: npx swagger-ui-serve docs/main/openapi.yaml'); + console.log('3. 或导入到Postman等API测试工具中'); + + } catch (error) { + console.error('❌ 验证失败:', error.message); + process.exit(1); + } +} + +// 如果直接运行此脚本 +if (require.main === module) { + validateOpenAPIDoc(); +} + +module.exports = { validateOpenAPIDoc }; \ No newline at end of file diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index 17e827a..0f2fd38 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -116,6 +116,8 @@ > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。 +| 2026-03-26 | 方案二整体部署方案独立成文 | 1）新增 `docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md`，将已采纳 PostgreSQL 16 方案二后的整体部署方案独立成文；2）结合当前前后端分层部署形态，补齐应用、数据库、中间件、静态存储的一体化部署结构；3）新增软件拓扑图、网络拓扑图、主机角色划分、资源配置建议、网络需求和端口访问建议；4）在 `07_PostgreSQL16_DR_Resource_Application.md` 增加独立文档引用说明，在技术专项目录增加入口。 | 用户明确要求不要仅在 `07` 文档内保留方案二内容，而是需要形成独立文件，并作为已采纳数据库方案后的整体部署方案提交评审。 | 正面影响，数据库资源申请专题与整体部署方案实现职责分离；后续甲方可分别评审“数据库容灾资源申请”和“系统整体部署方案”，减少口径混杂并提升部署审批的可读性。 | + | 2026-03-18 | REV-005 统计模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 为 `T055`、`T060`、`T061`、`T062`、`T063` 新增可直接填写的样本记录模板；2）将 SC-001 ~ SC-004 的建议统计口径细化为表格字段与待补说明，避免后续只剩抽象待办；3）保持“模板已补齐但实际统计结果仍待联调/测试环境补录”的真实状态，不虚构样本结果。 | 用户继续推进 REV-005，希望把剩余统计类待办进一步收敛成可执行模板，便于后续直接补录真实样本而不是重新设计统计格式。 | 正面影响，REV-005 当前已具备统一的统计与日志抽样记录模板；后续补 `T055`、`T060 ~ T063` 时可直接按模板填充真实环境数据，减少再次整理验证文档结构的成本。 | | 2026-03-18 | REV-005 verify 执行入口补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 补齐 `/business/invoice/apply`、`/query`、`/query/compensate`、`/write-back`、`/customer/query`、`/customer/download`、`/customer/push`、`/invalidate`、`/red-ink` 的最小请求模板；2）继续补齐 `T055`、`T060 ~ T063` 的执行命令草稿与样本采集顺序，明确仅作为测试/联调环境占位模板，真实地址、鉴权信息、业务主键与统计结果均待后续替换和回填；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“替换真实环境参数即可执行”的状态。 | 用户继续推进 REV-005，希望不要停留在抽象验证建议，而是把剩余 verify 工作推进到可直接执行、可直接补样本的程度。 | 正面影响，REV-005 当前已具备统一的验证入口、请求模板、命令草稿与采样顺序；后续在测试或联调环境中可直接替换参数发起请求并回填 `T055`、`T060 ~ T063` 的真实结果，减少重复梳理接口和命令的成本。 | | 2026-03-18 | REV-005 联调补录清单补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增 `T055`、`T060 ~ T063` 的联调补录清单，按“申请 → 查询 → 回写 → 补偿查询 → 客户查询/下载/推送 → 作废/红冲 → 日志抽样”顺序拆解步骤；2）为每一步明确主要输入、预期产出与回填位置，确保联调执行时不再重复梳理样本归档方式；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“可按顺序执行并即时补录”的状态。 | 用户继续推进 REV-005，希望把剩余运行态补证工作从“有命令草稿”进一步推进到“有顺序、有产出、有回填位置”的联调操作清单。 | 正面影响，REV-005 当前已具备联调补录步骤清单，后续在测试或联调环境中可按固定顺序执行并即时回填样本、统计与日志证据，降低遗漏申请单号、受理号与日志检索条件的风险。 | @@ -350,3 +352,7 @@ - `sw-business-bank` 已新增 `FILE_TRANSFER_CONFIG` 配置类型、统一文件传输解析器、`SFTP/FTP` 双协议解析能力，以及 `send/back/reconcile` 审计字段承接；已落库批次回盘目录继续沿用批次固化结果。 - 已完成 backend 最小验证：`mvn -f ../water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am -DskipTests compile` 通过；`mvn ... -Dtest=BankTransferPathResolverTest,BankWithholdingTransferConfigTest -Dsurefire.failIfNoSpecifiedTests=false test` 通过，共 9 个定向测试全部通过。 - 当前剩余 deferred 继续限定为真实银行 `SFTP/FTP` 联调、生产凭据与白名单开通、`BankCollection` 托收链路对等改造，以及运行态样本补证，不将其误写为已闭环能力。 +- 新增 `docs/guides/NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md`，形成诺税通 saas 首期对接实施清单，统一接口优先级、请求/响应字段映射、业务流程图、错误码处理策略与沙箱测试清单口径，作为外部发票平台首批实施与联调验收的正式参考。 +- 新增 `docs/guides/NUOSHUITONG_DATABASE_DESIGN.md`，形成诺税通对接数据库设计草案，明确发票、红字单据、设备、库存、企业配置与平台日志等落表建议，作为后续正式 DDL 与专项数据库设计对齐的输入。 +- 新增 `docs/guides/NUOSHUITONG_DDL_DRAFT.md`，形成诺税通对接 DDL 草案，覆盖核心表 `CREATE TABLE`、唯一约束与索引建议，作为后续数据库实现与 PostgreSQL/openGauss 方言适配的基础版本。 +- 新增 `docs/guides/NUOSHUITONG_PG_OPENGAUSS_DDL_GUIDE.md`，形成 PostgreSQL 16 / openGauss 适配建议，明确类型替换、主键策略、索引兼容性和迁移实施注意事项，作为双数据库口径下的实现参考。 diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 2081655..00ef94b 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -147,6 +147,8 @@ - [x] 已补齐网络、存储、切换与恢复要求 ✅ - [x] 已补齐 PostgreSQL 代理架构、`HAProxy` / `PgBouncer` 配置样例与应用接入建议 ✅ - [x] 已补齐计划切换、故障切换、回切、检查表与验证表 ✅ + - [x] 已将原方案二抽出为整体部署方案，补齐前端、后端、中间件、数据库、静态存储和网络需求 ✅ + - [x] 已新增独立文档 `08_Integrated_Deployment_Design_PlanB.md`，沉淀已采纳方案二后的整体部署方案 ✅ ### 📋 010-bank-transfer-config 银行文件传输配置能力 diff --git a/docs/design/01_Overview/03_Summary_Design.md b/docs/design/01_Overview/03_Summary_Design.md index ac3fc0a..369c6c4 100644 --- a/docs/design/01_Overview/03_Summary_Design.md +++ b/docs/design/01_Overview/03_Summary_Design.md @@ -147,7 +147,7 @@ retrieval_priority: P0 - 业务服务层：SYS-001 统一平台、SYS-002 营收业务系统、SYS-003 手机抄表APP、SYS-004 微网厅系统、SYS-005 工单管理系统、SYS-006 表务管理系统、SYS-007 报装业务系统 -- 基础服务层：SYS-008 发票服务子系统（统一开票）、SYS-009 支付与银行结算子系统（统一聚合支付/退款/渠道适配/第三方支付平台/银行代扣/夜间批量代扣/对账/加解密/支付回调）、SYS-010 消息服务子系统（统一短信/邮件/站内信/模板消息/微信通知/数科系统对接）、注册/配置中心、任务调度等基础服务 +- 基础服务层：SYS-008 发票服务子系统（统一开票）、SYS-009 支付与银行结算子系统（统一聚合支付/退款/渠道适配/第三方支付平台/银行实时收费、代扣/托收签解约、批次与对账契约、加解密与支付回调，夜间批量代扣/完整对账结算按后续完善项管理）、SYS-010 消息服务子系统（统一短信/邮件/站内信/模板消息/微信通知/数科系统对接）、注册/配置中心、任务调度等基础服务   通过系统的建设，实现福建省水投数字科技有限公司客户服务管理领域的业务流程梳理再造、组织架构的优化、管理制度的建设、绩效考核标准的建设。构建以客户为中心的一体化服务体系，将客户的所有信息进行有机的关联，方便企业对营收信息进行综合分析和管理，为客户提供更多、更便捷、更主动的个性化服务，提高客户服务的质量和客户满意度。 @@ -161,7 +161,7 @@ retrieval_priority: P0 - **表务管理系统**：设备档案、表务全生命周期管理 - **报装业务系统**：覆盖报装申请、踏勘、施工、验收、通水与档案归档的端到端流程,支持调用泛微进行合同签订，电子签章，支持各租户自定义报装流程和表单定义 - **发票服务子系统**（基础服务）：统一开票网关与供应商适配（现优先对接航天，预留博思），回执与存证 -- **支付与银行对接子系统**（基础服务）：统一支付/退款、银行代扣送盘/回盘、对账处理、加解密签名,第三方支付平台（微信、支付宝），支持夜间进行批量代扣 +- **支付与银行对接子系统**（基础服务）：统一支付/退款、银行实时收费、代扣/托收签解约、送盘/回盘/对账契约、加解密签名与第三方支付平台（微信、支付宝）；夜间批量代扣和完整结算闭环按后续完善项管理 - **消息服务子系统**（基础服务）：统一短信/邮件/站内信/模板消息，下行推送与到达回执，供各业务子系统调用（如营收业务系统催缴），微信信息通知，对接数科已建系统通知（OA、智水擎，水投数科 app） ### 功能范围 @@ -206,6 +206,7 @@ retrieval_priority: P0 #### SYS-009 支付与银行结算子系统（基础服务） - 聚合支付/退款、渠道适配（微信/支付宝/银联聚合等）、第三方支付平台（微信、支付宝）、支付结果通知、银行代扣（送盘/回盘）、支持夜间进行批量代扣、对账文件处理、加解密/签名 +- 当前实现侧已确认聚合支付基础能力、银行欠费查询/缴费、`BankWithholding` 六条银行入口（客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询）、代扣/托收签约解约和后台资源管理具备证据；其中 `BankCollection` 平行链路、夜间批量代扣、完整对账与结算仍按部分实现或后续完善项管理 #### SYS-010 消息服务子系统（基础服务） @@ -747,7 +748,7 @@ graph TB | SYS-006 | 表务管理系统 | 设备档案、表务全生命周期管理 | 自行开发 | | SYS-007 | 报装业务系统 | 报装流程管理、合同签订与电子签章、工程管理、档案管理 | 自行开发 | | SYS-008 | 发票服务子系统 | 统一开票网关、供应商适配器（优先对接航天）、回执处理与存证 | 自行开发 | -| SYS-009 | 支付与银行结算子系统 | 聚合支付/退款、渠道适配（微信/支付宝/银联）、支付通知、银行代扣送盘/回盘、夜间批量代扣、对账处理、加解密签名 | 自行开发 | +| SYS-009 | 支付与银行结算子系统 | 聚合支付/退款、渠道适配（微信/支付宝/银联）、支付通知、银行实时收费、代扣/托收签解约、送盘/回盘/对账契约、加解密签名；夜间批量代扣与完整结算闭环按后续完善项管理 | 自行开发 | | SYS-010 | 消息服务子系统 | 短信/邮件/站内信模板与发送、回执查询、批量推送 | 自行开发 | ### 子系统间关系 @@ -3675,14 +3676,14 @@ graph TD ## 任务概述 -  支付与银行结算子系统（SYS-009）统一承载聚合支付/退款、渠道适配（微信/支付宝/银联聚合）、支付回调验签入账，以及银行代扣（送盘/回盘）、支持夜间进行批量代扣、对账文件处理与安全加解密/签名，向上对营收/微网厅等系统提供标准化支付与结算能力。 +  支付与银行结算子系统（SYS-009）统一承载聚合支付/退款、渠道适配（微信/支付宝/银联聚合）、支付回调验签入账，以及银行实时收费、代扣/托收签约解约、送盘/回盘/对账契约与安全加解密/签名，向上对营收/微网厅等系统提供标准化支付与结算能力。夜间批量代扣、完整回盘状态补偿、对账差异处理与结算确认当前仍按后续完善项管理。 ## 设计概述 ### 总体约束 - 多渠道聚合：统一接入微信/支付宝/银联聚合 -- 统一结算：批量代扣送回盘、批量对账文件处理、差异对齐 +- 统一结算：统一维护批次、回盘、对账和差异语义，完整结算闭环按后续完善项推进 - 安全合规：签名/验签、加解密、回调防重放、幂等 - 高可用：基础重试补偿机制 @@ -3692,7 +3693,7 @@ graph TD ### 子系统外部接口（SYS-009） -  支付与银行结算子系统作为统一的支付能力中心，为上游业务系统提供聚合支付、银行代扣、退款处理、对账管理等全方位的支付结算服务。系统与微信支付、支付宝、银联聚合及各大银行系统对接，提供安全可靠的支付解决方案。 +  支付与银行结算子系统作为统一的支付能力中心，为上游业务系统提供聚合支付、银行实时收费、代扣/托收签解约、退款处理、对账管理等支付结算服务。以下接口表表达的是正式设计目标边界，其中聚合支付、实时收费查询/缴费、代扣/托收签解约已具备较明确实现证据；`BankWithholding` 六条银行入口已形成最小实现态闭环，托收平行链路、对账和完整结算闭环仍按部分实现或后续完善项管理。 | 接口编号 | 接口名称 | 功能描述 | 调用方 | 接口协议 | 输入参数 | 输出结果 | |---|---|---|---|---|---|---| @@ -3700,9 +3701,9 @@ graph TD | IF-PAY-002 | 统一关单接口 | 订单关闭和撤销处理 | 营收系统/微网厅 | HTTP/REST | 订单号、关闭原因、操作类型 | 关单状态、退款信息、处理结果 | | IF-PAY-003 | 统一退款接口 | 原路退款和部分退款处理 | 营收系统/微网厅 | HTTP/REST | 原订单号、退款金额、退款原因 | 退款单号、退款状态、预计到账时间 | | IF-PAY-004 | 支付回调接口 | 接收渠道支付结果回调 | 微信/支付宝/银联 | HTTP/REST | 回调数据、签名、时间戳 | 处理确认、业务更新状态 | -| IF-PAY-005 | 批量代扣送盘接口 | 银行批量代扣文件发送 | 营收业务系统 | HTTP/REST/SFTP | 代扣清单、客户签约信息、扣款金额 | 送盘状态、批次号、预计处理时间 | -| IF-PAY-006 | 批量代扣回盘接口 | 银行代扣结果回盘处理 | 银行系统 | HTTP/REST/SFTP | 回盘文件、处理结果、失败原因 | 解析结果、状态更新、异常处理 | -| IF-PAY-007 | 批量对账文件接口 | 银行对账文件处理分析 | 银行系统/营收系统 | HTTP/REST/SFTP | 对账文件、对账日期、差异规则 | 对账结果、差异明细、调整建议 | +| IF-PAY-005 | 批量代扣送盘接口 | 银行批量代扣文件发送 | 营收业务系统 | HTTP/REST/SFTP | 代扣清单、客户签约信息、扣款金额 | 送盘状态、批次号、预计处理时间（`BankWithholding` 已具备最小实现态闭环；真实文件通道联调仍待补证） | +| IF-PAY-006 | 批量代扣回盘接口 | 银行代扣结果回盘处理 | 银行系统 | HTTP/REST/SFTP | 回盘文件、处理结果、失败原因 | 解析结果、状态更新、异常处理（`BankWithholding` 已具备最小实现态闭环；真实文件解析与异常补偿仍待补证） | +| IF-PAY-007 | 批量对账文件接口 | 银行对账文件处理分析 | 银行系统/营收系统 | HTTP/REST/SFTP | 对账文件、对账日期、差异规则 | 对账结果、差异明细、调整建议（当前仍按部分实现或后续完善项管理） | | IF-PAY-008 | 加解密签名接口 | 支付数据安全处理 | 内部模块调用 | HTTP/REST | 待处理数据、加密类型、签名算法 | 处理结果、安全凭证、验证状态 | ## 子系统架构设计 @@ -3831,6 +3832,7 @@ graph TD - 差异识别与异常记录 - 冲正/补记建议生成 - 对账报告与追踪链路告警 +- 当前阶段按目标能力保留正式设计口径，不直接表述为已形成完整闭环 #### PAY-006: 加解密/签名 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index 771c05b..84ff12a 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -1223,6 +1223,8 @@ retrieval_priority: P0 | `bk_reconcile_diff` | `batch_id`, `trade_no`, `diff_type`, `diff_amount` | 对账差异 | | `bk_settlement_batch` | `batch_no`, `channel_code`, `settlement_date`, `settlement_status` | 结算批次 | +> 当前实现边界说明：`bk_*` 表族已形成较完整的对象承接口径，且签约、解约、交易流水与后台资源管理具备明确实现证据；但送盘、回盘、对账、结算等业务编排仍缺少完整闭环与统一迁移证据，数据库专项不得据此倒推出“银行协同已全部落地”。 + diff --git a/docs/design/03_Technical_Design/07_PostgreSQL16_DR_Resource_Application.md b/docs/design/03_Technical_Design/07_PostgreSQL16_DR_Resource_Application.md index 5360a27..f3370eb 100644 --- a/docs/design/03_Technical_Design/07_PostgreSQL16_DR_Resource_Application.md +++ b/docs/design/03_Technical_Design/07_PostgreSQL16_DR_Resource_Application.md @@ -28,14 +28,15 @@ retrieval_priority: P1 4. 容灾形态说明 5. 资源配比原则 6. 推荐部署方案 -7. 甲方审批汇总表 -8. 详细资源申请清单 -9. 网络与存储要求 -10. 数据库代理与连接接入方案 -11. 部署实施说明 -12. 切换与恢复说明 -13. 切换实施细则 -14. 申请结论 +7. 方案二独立整体部署方案 +8. 甲方审批汇总表 +9. 详细资源申请清单 +10. 网络与存储要求 +11. 数据库代理与连接接入方案 +12. 部署实施说明 +13. 切换与恢复说明 +14. 切换实施细则 +15. 申请结论 ## 编制目的 @@ -212,6 +213,185 @@ flowchart TD 本项目建议优先向甲方申请方案 B；如甲方同时要求区域级灾难恢复能力，建议直接申请方案 C。 +## 方案二独立整体部署方案 + +> 本节内容已独立沉淀为 `docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md`。如需评审“已采纳方案二后的整体部署方案”，以独立文档为准。 + +### 方案定位 + +本方案基于原“方案 B：正式生产推荐方案”进一步展开，作为适配当前福建水务营收系统前后端分层部署形态的独立整体部署方案。 + +本方案的核心约束如下： + +1. 前端服务与后端服务保持分层部署。 +2. 中间件集中部署在 1 台主机上。 +3. 数据库控制组件与中间件部署在同一台主机上。 +4. 数据库采用同城双可用区主备架构。 +5. 静态存储采用 MinIO，并与中间件一并集中部署。 + +### 适用场景 + +本方案适用于以下场景： + +1. 当前项目已具备前端 Nginx + Vue3、后端 Spring Boot 的分层部署模式。 +2. 甲方希望在控制主机数量的前提下，完成应用层、数据库层、中间件层与静态存储层的整体建设。 +3. 甲方接受“中间件集中部署、数据库双节点容灾、前后端分层部署”的资源结构。 + +### 整体部署拓扑 + +```mermaid +flowchart LR + subgraph CLIENT[访问入口] + U1[PC端用户] + U2[移动端用户] + U3[第三方系统] + end + + subgraph LB[负载均衡层] + LB1[负载均衡/VIP] + end + + subgraph FE[前端服务层] + FE1[前端服务器 1
Nginx + Vue3] + FE2[前端服务器 2
Nginx + Vue3] + end + + subgraph BE[后端服务层] + BE1[后端服务器 1
Spring Boot] + BE2[后端服务器 2
Spring Boot] + BE3[后端服务器 3
Spring Boot] + BE4[后端服务器 4
Spring Boot] + end + + subgraph MW[中间件与数据库控制层] + MW1[中间件服务器
Redis + Nacos + MinIO
HAProxy + PgBouncer + Patroni] + end + + subgraph DBA[数据库可用区 A] + PG1[(PostgreSQL 16 主库)] + end + + subgraph DBB[数据库可用区 B] + PG2[(PostgreSQL 16 同城热备库)] + end + + CLIENT --> LB + LB --> FE + FE --> BE + BE --> MW1 + MW1 --> PG1 + MW1 --> PG2 + PG1 -->|同步复制| PG2 + PG1 --> BK[备份归档存储] + PG2 --> BK +``` + +### 主机角色划分 + +| 层级 | 主机角色 | 数量 | 主要部署内容 | 说明 | +|---|---|---:|---|---| +| 负载均衡层 | 负载均衡/VIP | 1 组 | 统一访问入口、SSL 卸载、转发控制 | 对外统一入口 | +| 前端服务层 | 前端服务器 | 2 台 | Nginx、Vue3 静态页面 | 承担 PC/H5 前端访问 | +| 后端服务层 | 后端服务器 | 4 台 | Spring Boot 业务服务 | 承担营收、账务、表务、发票、银行等业务 | +| 中间件层 | 中间件服务器 | 1 台 | Redis、Nacos、MinIO | 中间件集中部署 | +| 数据库控制层 | 数据库控制服务器 | 与中间件同机 | HAProxy、PgBouncer、Patroni | 不单独新增主机，部署在中间件服务器上 | +| 数据库层 | 主库服务器 | 1 台 | PostgreSQL 16 Primary | 部署在可用区 A | +| 数据库层 | 热备服务器 | 1 台 | PostgreSQL 16 Standby | 部署在可用区 B | +| 备份层 | 备份归档存储 | 1 套 | 基础备份、WAL 归档、恢复副本 | 独立存储空间 | + +### 部署说明 + +#### 1. 前端部署 + +1. 前端采用 2 台服务器部署 `Nginx + Vue3` 静态资源。 +2. 前端服务器不直接访问数据库，仅通过 HTTP/HTTPS 调用后端服务。 +3. 负载均衡层对前端节点做健康检查和请求分发。 + +#### 2. 后端部署 + +1. 后端采用 4 台 Spring Boot 应用服务器集群部署。 +2. 所有后端节点统一连接中间件与数据库控制主机暴露的数据库代理地址。 +3. 后端节点统一访问 Redis、Nacos 和 MinIO，不直接连接数据库主机 IP。 + +#### 3. 中间件与静态存储部署 + +1. 中间件统一部署在 1 台主机上。 +2. 中间件主机承载以下组件： + - Redis：缓存、会话、轻量级消息能力 + - Nacos：配置中心、注册治理能力 + - MinIO：静态文件与附件存储 +3. MinIO 作为本项目静态存储与对象存储统一入口，承接附件、票据文件、导出文件及其他静态资源。 + +#### 4. 数据库控制组件部署 + +1. 数据库控制组件不单独新增主机。 +2. `HAProxy`、`PgBouncer`、`Patroni` 与中间件部署在同一台主机。 +3. 后端应用通过该主机上的统一数据库代理地址访问 PostgreSQL 主备集群。 +4. 数据库切换时，由 Patroni 负责主备角色管理，由 HAProxy 完成入口切换，由 PgBouncer 完成连接池接管。 + +#### 5. 数据库部署 + +1. PostgreSQL 16 采用 1 主 1 热备模式。 +2. 主库与热备库分别部署在同城不同可用区或不同故障域。 +3. 主备之间采用同步复制，保障核心收费、账务、对账数据的一致性要求。 +4. 主库和热备库同时将基础备份与 WAL 归档写入备份归档存储。 + +### 资源建议 + +| 主机角色 | 数量 | 建议配置 | 备注 | +|---|---:|---|---| +| 前端服务器 | 2 台 | 8 核 CPU / 16 GB 内存 / 200 GB SSD | 支撑 Nginx 与静态页面发布 | +| 后端服务器 | 4 台 | 16 核 CPU / 32 GB 内存 / 300 GB SSD | 对齐当前主文档后端服务集群口径 | +| 中间件与数据库控制服务器 | 1 台 | 16 核 CPU / 64 GB 内存 / 2 TB SSD | 同机承载 Redis、Nacos、MinIO、HAProxy、PgBouncer、Patroni | +| PostgreSQL 主库服务器 | 1 台 | 16 核 CPU / 64 GB 内存 / 2 TB NVMe SSD | 生产写入节点 | +| PostgreSQL 热备服务器 | 1 台 | 16 核 CPU / 64 GB 内存 / 2 TB NVMe SSD | 正式切换接管节点 | +| 备份归档存储 | 1 套 | 可用空间 4 TB 至 6 TB | 存放全量备份与 WAL 归档 | + +### 网络需求 + +#### 1. 网络分区建议 + +| 网络分区 | 部署对象 | 访问要求 | +|---|---|---| +| 接入区 | 负载均衡、前端服务器 | 对外提供 HTTPS 访问 | +| 应用区 | 后端服务器 | 仅允许接入区与运维区访问 | +| 中间件区 | Redis、Nacos、MinIO、数据库控制组件 | 仅允许后端服务器与运维区访问 | +| 数据区 | PostgreSQL 主库、热备库、备份存储 | 严格限制，仅允许中间件控制主机和运维区访问 | + +#### 2. 带宽与时延要求 + +| 网络链路 | 建议要求 | 说明 | +|---|---|---| +| 前端到后端 | 千兆网络 | 满足业务访问与接口调用 | +| 后端到中间件 | 千兆网络 | 满足缓存、配置、文件访问 | +| 中间件控制主机到数据库 | 千兆网络以上 | 满足数据库代理与健康检查 | +| 主备复制链路 | 不低于 10 Gbps | 支撑同步复制 | +| 同城主备时延 | 建议低于 2 ms | 支撑稳定同步复制 | +| 数据库到备份存储 | 千兆网络以上 | 满足基础备份与 WAL 归档传输 | + +#### 3. 端口与访问控制建议 + +| 服务 | 典型端口 | 访问范围 | +|---|---|---| +| Nginx/HTTPS | 443 | 对外开放 | +| 后端 HTTP/HTTPS | 项目自定义端口 | 仅前端与内网调用 | +| Redis | 6379 | 仅后端与运维可访问 | +| Nacos | 8848 | 仅后端与运维可访问 | +| MinIO | 9000/9001 | 仅后端与运维可访问 | +| PgBouncer | 6432 | 仅后端可访问 | +| HAProxy | 5000 或项目定义端口 | 仅 PgBouncer 与运维可访问 | +| PostgreSQL | 5432 | 仅数据库控制主机与运维可访问 | + +### 正式方案结论 + +结合当前项目前后端部署形态，建议以本方案作为 PostgreSQL 16 正式生产推荐部署方案。其总体特点为： + +1. 前端与后端保持现有分层集群部署模式。 +2. 中间件与数据库控制组件集中部署在 1 台主机，控制主机数量。 +3. PostgreSQL 16 采用同城双可用区 1 主 1 热备部署，满足高可用要求。 +4. MinIO 作为静态存储统一入口，与中间件同机部署，便于统一运维。 +5. 网络上采用应用区、中间件区、数据区分层隔离，保障安全性与可维护性。 + ## 甲方审批汇总表 以下汇总表用于甲方进行资源审批、预算评估和实施范围确认。建议优先按“方案 B：正式生产推荐方案”审批；如甲方同时要求区域级灾难恢复能力，可按“方案 C：正式生产增强方案”审批。 diff --git a/docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md b/docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md new file mode 100644 index 0000000..f4addb5 --- /dev/null +++ b/docs/design/03_Technical_Design/08_Integrated_Deployment_Design_PlanB.md @@ -0,0 +1,730 @@ +--- +doc_id: TC-08-INTEGRATED-DEPLOYMENT +doc_role: supplemental_document +authority: secondary +scope: 方案二整体部署 +source_of_truth: false +last_reviewed: 2026-03-26 +retrieval_priority: P1 +--- + +# 福建水务营收系统整体部署方案说明书 + +## 文档信息 +| 项目信息 | 详情 | +|---------|------| +| **项目名称** | 福建水务营收系统 | +| **文档类型** | 技术专题说明 | +| **方案定位** | 已采纳 PostgreSQL 16 方案二作为数据库部署方案后的整体部署方案 | +| **文档版本** | v1.0 | +| **编写日期** | 2026-03-26 | +| **文档状态** | ✅ 正式建议稿 | + +## 目录 + +1. 编制目的 +2. 方案前提 +3. 整体部署原则 +4. 软件拓扑图 +5. 主机部署图 +6. 数据库访问链路图 +7. 备份恢复链路图 +8. 网络拓扑图 +9. 主机角色与部署内容 +10. 资源配置建议 +11. 资源审批汇总表 +12. 基础软件与版本清单 +13. 部署方式说明 +14. 网络需求 +15. 网络开通清单 +16. 访问控制与端口建议 +17. 实施步骤 +18. 验收标准 +19. 部署结论 + +## 编制目的 + +本文档用于在已采纳 PostgreSQL 16 方案二作为数据库部署方案的前提下，形成覆盖前端、后端、中间件、静态存储及数据库的一体化整体部署方案，作为甲方进行主机、网络、存储与基础软件资源审批的依据。 + +## 方案前提 + +本方案以以下前提为基础： + +1. 数据库部署方案已采纳 `docs/design/03_Technical_Design/07_PostgreSQL16_DR_Resource_Application.md` 中的方案二，即“同城双可用区主备容灾方案”。 +2. 前端继续采用 `Nginx + Vue3` 的静态部署模式。 +3. 对外访问经甲方或第三方管理的公网入口进行薄转发，不纳入本方案主机资源范围。 +4. 内网 `Nginx` 单独部署，负责将开放 API 端点负载到两台业务应用节点。 +5. 两台业务应用节点内均部署 `Spring Boot Gateway`，作为微服务集群统一接入入口，并同时承载业务服务。 +6. 中间件集中部署在 1 台主机上。 +7. 数据库控制组件与中间件部署在同一台主机上。 +8. `RustFS` 作为静态存储与对象存储统一入口，与中间件同机部署。 +9. 一期口径下，原“数据与中间件节点”和“文件存储节点”合并为 1 台综合节点。 +10. 银行文件交换采用独立 `SFTP/FTP` 文件交换服务器，作为银行送盘、回盘、对账文件交换专用前置机。 +11. 当前已知可用于本方案的业务与基础设施主机资源如下： + - 内网 Nginx 入口节点：8 核 CPU / 16 GB 内存 / 300 GB 存储，共 1 台 + - 业务应用节点（主）：32 核 CPU / 64 GB 内存 / 300 GB 存储，共 2 台 + - 数据、中间件与文件存储综合节点：16 核 CPU / 32 GB 内存 / 2300 GB 存储，共 1 台 + - 银行文件交换服务器：2 核 CPU / 8 GB 内存 / 200 GB 存储，共 1 台 + - 另行配置 PostgreSQL 主库与热备库各 1 台 + +## 整体部署原则 + +整体部署遵循以下原则： + +1. 前后端逻辑分层部署，避免数据库节点与业务节点混部。 +2. 中间件集中部署，降低主机数量和运维复杂度。 +3. 数据库主备分离部署，避免与中间件、应用节点混部。 +4. 数据库控制组件集中部署，通过统一代理地址屏蔽主备切换细节。 +5. 网络按公网接入区、内网接入区、应用区、中间件与文件存储区、银行文件交换区、数据区分层隔离。 +6. 在现有主机数量约束下，优先复用现有业务应用节点、内网入口节点及综合节点资源。 + +## 软件拓扑图 + +**图 4-1 访问与应用软件拓扑图** + +```mermaid +flowchart LR + classDef source fill:#ecfeff,stroke:#0891b2,stroke-width:1.2px,color:#083344; + classDef access fill:#fff7ed,stroke:#ea580c,stroke-width:1.4px,color:#7c2d12; + classDef app fill:#eff6ff,stroke:#2563eb,stroke-width:1.4px,color:#1e3a8a; + + subgraph OUTER[公网域] + direction TB + U2[移动端用户]:::source + U3[第三方系统]:::source + G1[公网接入代理]:::access + end + + subgraph INNER[内部网络域] + direction TB + U1[PC 端用户]:::source + G2[内网 Nginx]:::access + end + + subgraph APP1[业务应用节点 1] + direction TB + A1G[Spring Boot Gateway]:::app + A1B[业务服务]:::app + end + + subgraph APP2[业务应用节点 2] + direction TB + A2G[Spring Boot Gateway]:::app + A2B[业务服务]:::app + end + + U1 -->|内网访问| G2 + U2 -->|HTTPS 443| G1 + U3 -->|接口访问| G1 + G1 -->|跨公网/内网边界转发| G2 + G2 -->|负载到节点 1| A1G + G2 -->|负载到节点 2| A2G + A1G --> A1B + A2G --> A2B +``` + +图说明： + +1. 图中已明确区分公网域与内部网络域。 +2. PC 端用户通过内网直接访问内部网络域中的内网 Nginx。 +3. 移动端用户和第三方系统位于公网域，先经公网接入代理，再跨边界转发到内部网络域中的内网 Nginx。 +4. 内网 Nginx 将开放 API 端点负载到两台业务应用节点。 +5. 两台业务应用节点内均部署 Spring Boot Gateway，作为微服务集群统一接入入口。 +6. 每台业务应用节点内的 Gateway 再向本节点业务服务转发请求。 + +**图 4-2 综合服务软件拓扑图** + +```mermaid +flowchart TB + classDef app fill:#eff6ff,stroke:#2563eb,stroke-width:1.4px,color:#1e3a8a; + classDef service fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.4px,color:#4c1d95; + + A1[业务应用节点 1
Gateway + Biz]:::app + A2[业务应用节点 2
Gateway + Biz]:::app + + subgraph M[综合节点] + direction TB + M2[Redis / Nacos / RustFS]:::service + M3[HAProxy / PgBouncer / Patroni]:::service + end + + A1 -->|缓存 配置 文件访问| M2 + A2 -->|缓存 配置 文件访问| M2 + A1 -->|数据库代理访问| M3 + A2 -->|数据库代理访问| M3 +``` + +图说明： + +1. 综合节点承接缓存、配置、对象存储及数据库控制组件。 +2. 两台业务应用节点统一访问综合节点，不直接连接数据库。 + +**图 4-3 数据与备份软件拓扑图** + +```mermaid +flowchart LR + classDef service fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.4px,color:#4c1d95; + classDef data fill:#ecfdf5,stroke:#059669,stroke-width:1.4px,color:#064e3b; + classDef backup fill:#fffbeb,stroke:#d97706,stroke-width:1.4px,color:#78350f; + classDef bank fill:#fef2f2,stroke:#dc2626,stroke-width:1.4px,color:#7f1d1d; + + M2[RustFS / 文件归档]:::service + M3[HAProxy / PgBouncer / Patroni]:::service + F1[SFTP / FTP 文件交换服务器]:::bank + D1[(PostgreSQL 主库)]:::data + D2[(PostgreSQL 热备)]:::data + B1[备份归档存储]:::backup + + M3 -->|数据库访问| D1 + M3 -->|状态感知| D2 + D1 -->|同步复制| D2 + D1 -->|基础备份 WAL 归档| B1 + D2 -->|备份副本| B1 + M2 -->|对象存储归档| B1 + F1 -->|银行文件归档| B1 +``` + +图说明： + +1. 数据库控制组件经由主库提供数据库访问能力。 +2. 主库与热备之间通过同步复制保持一致性。 +3. 银行文件交换服务器承接送盘、回盘、对账文件交换能力。 +4. RustFS 与银行文件交换服务器分别将各自数据归档到备份归档存储。 + +## 主机部署图 + +**图 4-4 主机部署总览图** + +```mermaid +flowchart LR + classDef gateway fill:#fff7ed,stroke:#ea580c,stroke-width:1.2px,color:#7c2d12; + classDef app fill:#eff6ff,stroke:#2563eb,stroke-width:1.2px,color:#1e3a8a; + classDef middle fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.2px,color:#4c1d95; + classDef data fill:#ecfdf5,stroke:#059669,stroke-width:1.2px,color:#064e3b; + + GW[内网 Nginx 入口节点]:::gateway + APP1[业务应用节点 1
内含 Gateway]:::app + APP2[业务应用节点 2
内含 Gateway]:::app + MID[综合节点]:::middle + FTP[SFTP / FTP 文件交换服务器]:::middle + DB1[(数据库主库服务器)]:::data + DB2[(数据库热备服务器)]:::data + + GW --> APP1 + GW --> APP2 + APP1 --> MID + APP2 --> MID + APP1 --> FTP + APP2 --> FTP + MID --> DB1 + MID --> DB2 + DB1 --> DB2 +``` + +图说明： + +1. 内网 Nginx 入口节点作为我方统一接入入口，承接 API 转发与内部负载均衡能力。 +2. 业务应用节点 1 和业务应用节点 2 组成应用主机集群，节点内同时部署 Spring Boot Gateway 与核心业务服务。 +3. 综合节点集中承载 Redis、Nacos、RustFS、HAProxy、PgBouncer、Patroni，并同时访问数据库主库与热备服务器。 +4. 独立的 SFTP/FTP 文件交换服务器承接银行送盘、回盘、对账文件交换，并由业务应用节点直接访问。 +5. 数据库主库服务器与数据库热备服务器独立部署，满足数据库高可用要求。 + +主机部署细化说明： + +1. 内网 Nginx 入口节点部署 `Nginx`，负责开放 API 转发和内部负载均衡。 +2. 两台业务应用节点分别部署 `Spring Boot Gateway` 与业务服务实例。 +3. 综合节点部署 `Redis`、`Nacos`、`RustFS`、`HAProxy`、`PgBouncer`、`Patroni`，并负责访问数据库主库与热备服务器。 +4. SFTP/FTP 文件交换服务器部署银行文件交换服务及送盘、回盘、对账目录，由业务应用节点直接访问。 +5. 数据库主库服务器部署 PostgreSQL 主库实例，数据库热备服务器部署 PostgreSQL 热备实例。 + +## 数据库访问链路图 + +**图 4-5 数据库访问链路图** + +```mermaid +flowchart LR + A1[业务应用节点 1] + A2[业务应用节点 2] + P[PgBouncer] + H[HAProxy] + M[(主库)] + S[(热备)] + T[Patroni] + + A1 -->|统一代理地址| P + A2 -->|统一代理地址| P + P -->|连接池复用| H + H -->|写流量| M + H -.热备探测 / 状态访问.-> S + M -->|同步复制| S + T -.主备状态管理.-> H +``` + +图说明： + +1. 业务应用不直接连接数据库主机。 +2. PgBouncer 负责连接池。 +3. HAProxy 负责数据库入口代理。 +4. Patroni 负责主备状态管理与切换控制。 +5. 综合节点侧的数据库控制组件会同时访问主库和热备，用于探测、控制和切换。 + +## 备份恢复链路图 + +**图 4-6 备份恢复链路图** + +```mermaid +flowchart LR + DB1[(PostgreSQL 主库)] --> BK[备份归档存储] + DB2[(PostgreSQL 热备)] --> BK + MID[综合节点 / RustFS] --> BK + BK --> REC[恢复与演练入口] +``` + +图说明： + +1. 主库和热备均向备份归档存储输出备份数据。 +2. 综合节点中的 RustFS 文件数据也纳入备份范围。 +3. 备份归档存储作为数据库恢复与文件恢复的统一入口。 + +## 网络拓扑图 + +> 说明：如需生成正式网络分区图与网络连接图，统一以 `scripts/generate_planb_diagrams.py` 生成的产物为准；其他脚本仅用于布局试验，不作为正式交付依据。 + +**图 4-7 网络分区图** + +```mermaid +flowchart LR + classDef user fill:#ecfeff,stroke:#0891b2,stroke-width:1.2px,color:#083344; + classDef edge fill:#fff7ed,stroke:#ea580c,stroke-width:1.2px,color:#7c2d12; + classDef zone fill:#f8fafc,stroke:#94a3b8,stroke-width:1.2px,color:#0f172a; + classDef svc fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.2px,color:#4c1d95; + classDef data fill:#ecfdf5,stroke:#059669,stroke-width:1.2px,color:#064e3b; + classDef bank fill:#fef2f2,stroke:#dc2626,stroke-width:1.2px,color:#7f1d1d; + classDef backup fill:#fffbeb,stroke:#d97706,stroke-width:1.2px,color:#78350f; + + U[用户与外部系统]:::user + PGW[公网接入代理]:::edge + + subgraph Z1[内网接入区] + IGW[内网 Nginx] + end + + subgraph Z2[应用区] + APP[业务应用集群] + end + + subgraph Z3[综合服务区] + MID[综合节点] + end + + subgraph Z4[数据区] + DBM[(PostgreSQL 主库)] + DBS[(PostgreSQL 热备)] + end + + subgraph Z6[互联网银行交换区] + FX[SFTP / FTP 文件交换服务器] + end + + subgraph Z5[机房接入区] + BK[备份归档存储] + end + + class Z1,Z2,Z3,Z4,Z5,Z6 zone; + class IGW edge; + class APP svc; + class MID svc; + class DBM,DBS data; + class FX bank; + class BK backup; + + U --> PGW + U --> IGW + PGW --> IGW + IGW --> APP + APP --> FX + APP --> MID + MID --> DBM + MID --> DBS + DBM --> BK + DBS --> BK + MID --> BK +``` + +图说明： + +1. 公网接入代理不纳入我方主机资源，但作为公网访问进入内网的前置接入层予以保留。 +2. 网络分区图按服务器和服务器集群粒度表达，不展开单机内部软件组件。 +3. PC 端用户可直接通过内网访问内网 Nginx；移动端和第三方系统经公网接入代理后进入内网 Nginx。 +4. 业务应用集群、综合服务区、数据区、机房接入区、互联网银行交换区相互隔离，通过授权链路互通。 + +**图 4-8 网络连接图** + +```mermaid +flowchart TB + classDef user fill:#ecfeff,stroke:#0891b2,stroke-width:1.2px,color:#083344; + classDef access fill:#fff7ed,stroke:#ea580c,stroke-width:1.2px,color:#7c2d12; + classDef app fill:#eff6ff,stroke:#2563eb,stroke-width:1.2px,color:#1e3a8a; + classDef middle fill:#f5f3ff,stroke:#7c3aed,stroke-width:1.2px,color:#4c1d95; + classDef data fill:#ecfdf5,stroke:#059669,stroke-width:1.2px,color:#064e3b; + classDef backup fill:#fffbeb,stroke:#d97706,stroke-width:1.2px,color:#78350f; + classDef bank fill:#fef2f2,stroke:#dc2626,stroke-width:1.2px,color:#7f1d1d; + + subgraph OUTER[公网域] + direction LR + M[移动端用户]:::user + T[第三方系统]:::user + FX[SFTP/FTP文件交换服务器]:::bank + end + + subgraph INNER[内部网络域] + direction TB + subgraph CLIENT[客户端] + PC[PC 端用户]:::user + end + + subgraph ACCESS[接入层] + PGW[公网接入代理]:::access + IGW[内网 Nginx]:::access + end + + subgraph SVC[应用与中间件层] + APP[业务应用集群
Spring Boot Gateway + Biz]:::app + CACHE[Redis / Nacos / RustFS]:::middle + CTRL[HAProxy / PgBouncer / Patroni]:::middle + end + + subgraph DATA[数据层] + DBM[(PostgreSQL 主库)]:::data + DBS[(PostgreSQL 热备)]:::data + end + + subgraph STORAGE[存储层] + STORE[备份归档存储]:::backup + end + end + + %% 公网访问链路 + M -->|HTTPS 443| PGW + T -->|HTTPS 443 / 接口| PGW + PGW -->|请求转发| IGW + + %% 内网访问链路 + PC -->|内网访问| IGW + IGW -->|网关/应用端口| APP + + %% 应用层依赖 + APP -->|6379 / 8848 / 9000| CACHE + APP -->|文件传输| FX + APP -->|6432 / 5000| CTRL + CTRL -->|5432| DBM + CTRL -.->|5432 状态探测| DBS + DBM -->|主备同步| DBS + + %% 数据备份与归档 + CACHE -->|归档文件| STORE + DBM -->|备份 / WAL 归档| STORE + DBS -.->|备份副本| STORE + +``` + +图说明： + +1. 图中已明确区分公网域与内部网络域，公网访问通过公网接入代理跨边界进入内部网络。 +2. PC 端用户位于内部网络域，直接访问内网 Nginx；移动端和第三方系统位于公网域。 +3. 内网 Nginx 统一将 API / Gateway 请求负载到业务应用集群。 +4. 业务应用集群分别访问综合服务、银行文件交换服务器和数据库控制组件。 +5. 综合服务中的数据库控制组件同时访问 PostgreSQL 主库与热备；数据库与综合服务均向备份归档存储输出归档数据。 + +## 主机角色与部署内容 + +| 层级 | 主机角色 | 数量 | 主要部署内容 | 说明 | +|---|---|---:|---|---| +| 接入层 | 内网 Nginx 入口节点 | 1 台 | Nginx、API 转发、内部负载均衡 | 作为我方统一内网接入入口，承接开放 API 转发 | +| 应用层 | 业务应用节点（主） | 2 台 | Spring Boot Gateway、Spring Boot 业务服务 | 承载微服务集群接入与表务、抄表、收费、账务、发票、报表等核心应用服务 | +| 综合支撑层 | 数据、中间件与文件存储综合节点 | 1 台 | Redis、Nacos、RustFS、HAProxy、PgBouncer、Patroni | 中间件、数据库控制与文件存储同机部署 | +| 银行交换层 | SFTP/FTP 文件交换服务器 | 1 台 | SFTP/FTP 服务、送盘目录、回盘目录、对账目录、归档目录 | 作为银行文件交换专用前置机 | +| 数据库层 | PostgreSQL 主库服务器 | 1 台 | PostgreSQL 16 Primary | 部署在可用区 A | +| 数据库层 | PostgreSQL 热备服务器 | 1 台 | PostgreSQL 16 Standby | 部署在可用区 B | +| 备份层 | 备份归档存储 | 1 套 | 基础备份、WAL 归档、恢复副本 | 独立备份空间 | + +## 资源配置建议 + +| 主机角色 | 数量 | 建议配置 | 备注 | +|---|---:|---|---| +| 内网 Nginx 入口节点 | 1 台 | 8 核 CPU / 16 GB 内存 / 300 GB 存储 | 承载内网 Nginx、API 转发和内部负载均衡 | +| 业务应用节点（主） | 2 台 | 32 核 CPU / 64 GB 内存 / 300 GB 存储 | 承载 Spring Boot Gateway 及表务、抄表、收费、账务、发票、报表等核心应用服务 | +| 数据、中间件与文件存储综合节点 | 1 台 | 16 核 CPU / 32 GB 内存 / 2300 GB 存储 | 承载缓存、配置治理、数据库控制、图片、附件等非结构化数据 | +| SFTP/FTP 文件交换服务器 | 1 台 | 2 核 CPU / 8 GB 内存 / 200 GB 存储 | 承载银行送盘、回盘、对账、归档文件交换，建议独立部署 | +| PostgreSQL 主库服务器 | 1 台 | 24 核 CPU / 48 GB 内存 / 1 TB NVMe SSD | 生产写入节点，不计入上述已知 4 类业务主机 | +| PostgreSQL 热备服务器 | 1 台 | 24 核 CPU / 48 GB 内存 / 1 TB NVMe SSD | 正式切换接管节点，不计入上述已知 4 类业务主机 | +| 备份归档存储 | 1 套 | 可用空间 4 TB 至 6 TB | 存放全量备份与 WAL 归档 | + +### 银行文件交换服务器容量估算 + +按 20 万用户、5 年保留期估算，银行文件交换服务器主要承载代扣、托收、对账等批次文件，不承载全量业务明细数据库。 + +估算依据如下： + +1. 银行代扣、托收、对账文件以批次文件为主，不是每位用户每天形成独立文件。 +2. 按“仅覆盖银行代扣/托收用户，且按月批次送盘/回盘一次”的业务节奏估算，单个批次文件大小通常在 `10 MB ~ 40 MB` 量级。 +3. 按每月送盘、回盘、对账共 `3` 类核心文件估算，月文件量约为： + - `30 MB ~ 120 MB / 月` +4. 按 1 年估算，原始批次文件总量约为： + - `0.36 GB ~ 1.44 GB / 年` +5. 考虑归档副本、异常重传、中间文件和运行日志，按 `10 ~ 15` 倍放大后，5 年总量通常约为： + - `20 GB ~ 110 GB` + +因此，按最节约的一期规划，银行文件交换服务器可按 `2 核 CPU / 8 GB 内存 / 200 GB 存储` 配置满足送盘、回盘、对账文件交换与 5 年留存需要；如后续银行通道数量增加、并发文件交换增加或保留策略扩大，再扩容至 `4 核 / 8 GB / 500 GB` 即可。建议设置 `70%` 容量预警，并预留扩容机制。 + +## 资源审批汇总表 + +以下汇总表用于甲方进行主机、存储、网络及基础软件部署范围审批。 + +| 序号 | 资源名称 | 数量 | 规格 | 部署内容 | 用途说明 | 建议口径 | +|---|---:|---:|---|---|---|---| +| 1 | 内网 Nginx 入口节点 | 1 台 | 8 核 CPU / 16 GB 内存 / 300 GB 存储 | Nginx、API 转发、内部负载均衡 | 我方统一内网接入入口 | 可利旧优先 | +| 2 | 业务应用节点（主） | 2 台 | 32 核 CPU / 64 GB 内存 / 300 GB 存储 | Spring Boot Gateway、Spring Boot 核心业务服务 | 承载微服务接入与核心业务服务 | 现有资源纳入正式方案 | +| 3 | 数据、中间件与文件存储综合节点 | 1 台 | 16 核 CPU / 32 GB 内存 / 2300 GB 存储 | Redis、Nacos、RustFS、HAProxy、PgBouncer、Patroni | 承载缓存、配置治理、数据库控制、图片、附件、导出文件等能力 | 现有资源纳入正式方案 | +| 4 | SFTP/FTP 文件交换服务器 | 1 台 | 2 核 CPU / 8 GB 内存 / 200 GB 存储 | SFTP/FTP 服务、送盘/回盘/对账目录、归档目录 | 承载银行文件交换与目录隔离 | 按最节约一期规划建议新增或单独利旧 | +| 5 | PostgreSQL 主库服务器 | 1 台 | 24 核 CPU / 48 GB 内存 / 1 TB NVMe SSD | PostgreSQL 16 Primary | 承载生产写入 | 建议单独配置 | +| 6 | PostgreSQL 热备服务器 | 1 台 | 24 核 CPU / 48 GB 内存 / 1 TB NVMe SSD | PostgreSQL 16 Standby | 承载正式切换接管 | 建议单独配置 | +| 7 | 备份归档存储 | 1 套 | 可用空间 4 TB 至 6 TB | 基础备份、WAL 归档、恢复副本 | 保障恢复与审计追溯 | 可利旧或新增存储空间 | + +### 审批建议 + +1. 业务应用节点、综合节点、内网 Nginx 入口节点可优先按现有资源纳入实施范围。 +2. SFTP/FTP 文件交换服务器建议单独审批，以满足银行文件交换隔离和安全要求。 +3. PostgreSQL 主库与热备库建议作为单独审批项，避免与现有业务节点混部。 +4. 备份归档存储建议作为单独资源项审批，避免后期因备份空间不足影响正式上线。 + +## 基础软件与版本清单 + +| 类别 | 软件名称 | 建议版本 | 部署位置 | 说明 | +|---|---|---|---|---| +| 操作系统 | Linux 发行版 | 银河麒麟（Kylin V10）X86 | 全部服务器 | 按甲方当前基础环境标准选定 | +| 运行环境 | JDK | 17 | 业务应用节点 | Spring Boot 运行环境 | +| 接入层 | Nginx | 1.20+ | 内网 Nginx 入口节点 | 内网 API 转发、内部负载均衡 | +| 网关服务 | Spring Boot Gateway | 3.x | 业务应用节点 | 微服务集群统一接入 | +| 业务服务 | Spring Boot | 3.x | 业务应用节点 | 核心业务服务框架 | +| 银行文件交换 | SFTP/FTP 服务 | 稳定版 | SFTP/FTP 文件交换服务器 | 银行送盘、回盘、对账文件交换 | +| 数据库 | PostgreSQL | 16 | 主库、热备库 | 主备数据库部署 | +| 缓存 | Redis | 6.2+ | 综合节点 | 缓存、会话、轻量级消息能力 | +| 配置中心 | Nacos | 2.x | 综合节点 | 配置治理与注册管理 | +| 对象存储 | RustFS | 以项目实际版本为准 | 综合节点 | 图片、附件、导出文件存储 | +| 数据库代理 | HAProxy | 2.x | 综合节点 | 数据库读写入口代理 | +| 连接池 | PgBouncer | 1.2x+ | 综合节点 | 统一数据库连接池 | +| 高可用控制 | Patroni | 稳定版 | 综合节点 | 主备状态管理与切换 | + +## 部署方式说明 + +### 总体部署原则 + +本方案的部署方式遵循以下原则： + +1. 入口代理类组件优先采用 `Docker` 部署，并可优先评估 `host` 网络模式。 +2. 业务应用优先采用 `Docker` 部署，但不建议使用 `host` 网络模式。 +3. 数据库主备优先采用物理机或虚拟机直接部署，不建议容器化承载 PostgreSQL 主备本体。 +4. 数据库控制组件如需容器化，应优先选择轻量代理组件容器化，高可用控制组件仍以直接部署为优先。 + +### 组件部署方式建议 + +| 组件 | 部署节点 | 建议部署方式 | 是否建议 `host` 模式 | 说明 | +|---|---|---|---|---| +| 内网 Nginx | 内网 Nginx 入口节点 | Docker 部署 | 是，优先建议 | 作为我方统一接入入口，便于端口管理与转发 | +| Spring Boot Gateway | 业务应用节点（主） | Docker 部署 | 否 | 作为微服务统一接入入口，建议与业务服务同节点部署 | +| Spring Boot 应用 | 业务应用节点（主） | Docker 部署 | 否 | 便于发布、回滚、扩容，保留容器网络隔离 | +| SFTP/FTP 服务 | SFTP/FTP 文件交换服务器 | 物理机/虚拟机直接部署 | 否 | 作为银行文件交换专用服务，建议独立部署并做目录隔离 | +| Redis | 综合节点 | Docker 部署 | 可选 | 可采用普通容器网络，必要时可评估 `host` | +| Nacos | 综合节点 | Docker 部署 | 可选 | 默认容器网络即可，便于配置治理 | +| HAProxy | 综合节点 | Docker 部署 | 是，优先建议 | 作为数据库代理入口，适合 `host` 模式 | +| PgBouncer | 综合节点 | Docker 部署 | 是，优先建议 | 作为数据库连接池入口，适合 `host` 模式 | +| Patroni | 综合节点 | 物理机/虚拟机直接部署 | 否 | 建议与系统服务集成，便于运维与切换控制 | +| RustFS | 综合节点 | Docker 部署 | 否 | 更关注数据盘挂载与对象存储目录管理 | +| PostgreSQL 主库 | 主库服务器 | 物理机/虚拟机直接部署 | 否 | 核心数据库本体不建议容器化 | +| PostgreSQL 热备 | 热备服务器 | 物理机/虚拟机直接部署 | 否 | 高可用数据库本体不建议容器化 | + +### 优先采用 Docker 且可使用 `host` 模式的组件 + +结合当前资源结构，建议优先采用 `Docker + host` 模式的组件如下： + +1. `内网 Nginx` +2. `HAProxy` +3. `PgBouncer` + +采用 `host` 模式的主要原因如下： + +1. 直接监听固定服务端口，减少端口映射复杂度。 +2. 更便于与主机防火墙、域名、VIP、健康检查配合。 +3. 对于入口类与代理类组件，运维体验更接近直接部署。 + +### 不建议采用 `host` 模式的组件 + +以下组件不建议采用 `Docker + host` 模式： + +1. `Spring Boot` 业务应用：应保留容器网络隔离，便于扩容和端口治理。 +2. `RustFS`：应以存储挂载与数据目录管理为重点，不依赖 `host` 模式。 +3. `PostgreSQL 主库 / 热备`：数据库本体优先直接部署，不建议容器化。 +4. `Patroni`：建议直接部署，便于与数据库高可用控制链路协同。 + +## 网络需求 + +### 1. 网络分区要求 + +| 网络分区 | 部署对象 | 访问要求 | +|---|---|---| +| 公网接入区 | 公网入口薄转发 | 对外提供 HTTPS 访问，不纳入我方主机资源 | +| 应用区 | 业务应用节点 | 仅允许内网接入区与运维区访问 | +| 中间件与文件存储区 | Redis、Nacos、RustFS、数据库控制组件 | 仅允许业务应用节点与运维区访问 | +| 银行文件交换区 | SFTP/FTP 文件交换服务器 | 仅允许业务应用节点、银行专线或授权外联链路访问 | +| 数据区 | PostgreSQL 主库、热备库、备份存储 | 严格限制，仅允许中间件控制主机和运维区访问 | + +### 2. 带宽与时延要求 + +| 网络链路 | 建议要求 | 说明 | +|---|---|---| +| 公网入口薄转发到内网 Nginx | 千兆网络 | 满足公网入口转发 | +| 内网 Nginx 到业务应用 | 千兆网络 | 满足开放 API 转发与网关接入 | +| 业务应用到综合节点 | 千兆网络 | 满足缓存、配置治理、文件访问与数据库代理访问 | +| 业务应用到 SFTP/FTP 服务器 | 千兆网络 | 满足送盘、回盘、对账文件交换 | +| 银行链路到 SFTP/FTP 服务器 | 千兆网络或专线 | 满足银行文件交换与目录投递 | +| 综合节点到数据库 | 千兆网络以上 | 满足数据库代理与健康检查 | +| 主备复制链路 | 不低于 10 Gbps | 支撑同步复制 | +| 同城主备时延 | 建议低于 2 ms | 支撑稳定同步复制 | +| 数据库到备份存储 | 千兆网络以上 | 满足基础备份与 WAL 归档传输 | +| 综合节点到备份存储 | 千兆网络以上 | 满足文件数据备份与归档传输 | + +### 3. 网络开通要求 + +| 类别 | 开通要求 | 说明 | +|---|---|---| +| 对外访问 | 开通 443 端口 | 提供统一 HTTPS 入口 | +| 公网入口薄转发访问内网 Nginx | 开通公网入口到内网 Nginx 的转发端口 | 仅授权链路访问 | +| 内网 Nginx 访问应用 | 开通内网 Nginx 到业务应用的 API / 网关端口 | 仅内网访问 | +| 应用访问综合节点 | 开通 Redis、Nacos、RustFS、PgBouncer 相关端口 | 仅应用区访问 | +| 业务应用访问 SFTP/FTP 服务器 | 开通 SFTP/FTP 相关端口 | 用于银行文件送盘、回盘、对账交换 | +| 银行链路访问 SFTP/FTP 服务器 | 开通 FTP/SFTP 服务端口 | 仅银行授权链路访问 | +| 综合节点访问数据库 | 开通 PostgreSQL 5432 及健康检查相关端口 | 仅综合节点访问 | +| 运维访问 | 开通运维区到各层必要管理端口 | 用于巡检、发布、恢复、切换 | + +## 网络开通清单 + +| 源区域/源主机 | 目标区域/目标主机 | 协议/端口 | 用途 | 开通要求 | +|---|---|---|---|---| +| 外部用户 | 公网入口薄转发 | HTTPS/443 | 页面访问、接口入口 | 对外开放 | +| 公网入口薄转发 | 内网 Nginx 入口节点 | HTTP/HTTPS/转发端口 | 公网访问转入内网入口 | 授权链路放通 | +| 内网 Nginx 入口节点 | 业务应用节点（主） | HTTP/HTTPS/网关端口 | 内网 API 转发与微服务接入 | 内网放通 | +| 业务应用节点（主） | 综合节点 | TCP/6379 | Redis 访问 | 内网放通 | +| 业务应用节点（主） | 综合节点 | TCP/8848 | Nacos 访问 | 内网放通 | +| 业务应用节点（主） | 综合节点 | TCP/6432 | PgBouncer 访问 | 内网放通 | +| 业务应用节点（主） | 综合节点 | RustFS 对象存储端口 | RustFS 文件访问 | 内网放通 | +| 业务应用节点（主） | SFTP/FTP 文件交换服务器 | TCP/21 或 22 | 银行送盘、回盘、对账文件交换 | 内网放通 | +| 银行专线或授权外联链路 | SFTP/FTP 文件交换服务器 | TCP/21 或 22 | 银行文件目录投递与回收 | 仅授权链路放通 | +| 综合节点 | PostgreSQL 主库服务器 | TCP/5432 | 数据库代理与控制访问 | 内网放通 | +| 综合节点 | PostgreSQL 热备服务器 | TCP/5432 | 数据库代理、状态探测与控制访问 | 内网放通 | +| PostgreSQL 主库服务器 | PostgreSQL 热备服务器 | TCP/5432 | 主备同步复制 | 高带宽、低时延专用链路 | +| PostgreSQL 主库/热备库 | 备份归档存储 | TCP/存储协议端口 | 基础备份与 WAL 归档 | 内网放通 | +| 综合节点 | 备份归档存储 | TCP/存储协议端口 | 文件归档与备份 | 内网放通 | +| 运维管理终端 | 各节点 | SSH/22 及必要管理端口 | 运维、巡检、发布、恢复 | 仅运维区放通 | + +## 访问控制与端口建议 + +| 服务 | 典型端口 | 访问范围 | +|---|---|---| +| Nginx/HTTPS | 443 | 对外开放 | +| Spring Boot Gateway / 业务应用端口 | 项目自定义端口 | 仅内网 Nginx 与内网调用 | +| Redis | 6379 | 仅业务应用与运维可访问 | +| Nacos | 8848 | 仅业务应用与运维可访问 | +| RustFS | 按 RustFS 实际部署端口 | 仅业务应用与运维可访问 | +| SFTP/FTP 服务 | 21 或 22 | 仅业务应用节点、运维和银行授权链路可访问 | +| PgBouncer | 6432 | 仅业务应用可访问 | +| HAProxy | 5000 或项目定义端口 | 仅 PgBouncer 与运维可访问 | +| PostgreSQL | 5432 | 仅数据库控制主机与运维可访问 | + +## 实施步骤 + +### 1. 基础资源准备 + +1. 确认内网 Nginx 入口节点、业务应用节点、综合节点是否为利旧资源。 +2. 完成 SFTP/FTP 文件交换服务器、PostgreSQL 主库服务器、热备服务器及备份归档存储审批。 +3. 完成各网络分区、IP、域名、SSL 证书、路由及防火墙策略准备。 + +### 2. 基础软件安装 + +1. 安装操作系统并完成安全基线加固。 +2. 在业务应用节点安装 JDK、部署业务运行环境。 +3. 在内网 Nginx 入口节点安装 Nginx。 +4. 在综合节点安装 Redis、Nacos、RustFS、HAProxy、PgBouncer、Patroni。 +5. 在 SFTP/FTP 文件交换服务器安装 SFTP/FTP 服务并配置目录结构。 +6. 在数据库主备节点安装 PostgreSQL 16。 + +### 3. 数据库主备部署 + +1. 初始化 PostgreSQL 主库。 +2. 初始化 PostgreSQL 热备库并建立同步复制。 +3. 配置 Patroni、HAProxy、PgBouncer 联动。 +4. 配置基础备份与 WAL 归档。 +5. 配置业务应用节点到 SFTP/FTP 文件交换服务器的文件交换目录映射。 + +### 4. 应用与存储部署 + +1. 在业务应用节点部署 Spring Boot Gateway 和业务应用服务。 +2. 在内网 Nginx 入口节点配置 API 转发和内部负载均衡规则。 +3. 在综合节点初始化 RustFS 存储桶和访问策略。 +4. 在 SFTP/FTP 文件交换服务器配置送盘、回盘、对账、归档目录。 +5. 配置业务应用到 Redis、Nacos、RustFS、PgBouncer 的连接参数。 + +### 5. 联调与演练 + +1. 完成前后端联调。 +2. 完成中间件访问验证。 +3. 完成数据库主备同步验证。 +4. 完成文件上传、下载、归档验证。 +5. 完成主备切换演练与回切演练。 + +### 6. 上线准备与正式投产 + +1. 完成上线前巡检与问题清零。 +2. 确认监控、日志、备份、告警正常。 +3. 完成上线窗口审批。 +4. 按上线顺序切换生产流量。 + +## 验收标准 + +| 验收项 | 验收标准 | 说明 | +|---|---|---| +| 对外访问 | 用户可通过统一域名正常访问系统 | 公网入口薄转发与内网 Nginx 链路正常 | +| 业务应用可用性 | 表务、抄表、收费、账务、发票、报表等核心服务正常 | 业务主流程可执行 | +| Redis 可用性 | 缓存读写正常 | 中间件能力正常 | +| Nacos 可用性 | 配置下发正常 | 配置治理能力正常 | +| RustFS 可用性 | 图片、附件上传下载正常 | 文件存储能力正常 | +| SFTP/FTP 文件交换 | 送盘、回盘、对账目录读写正常 | 银行文件交换能力正常 | +| 数据库连接能力 | 业务应用可通过 PgBouncer 正常连接数据库 | 代理接入正常 | +| PostgreSQL 主备同步 | 主备复制正常，无严重延迟 | 高可用基础正常 | +| 数据库切换演练 | 主备切换成功，业务恢复正常 | 高可用能力可验证 | +| 备份归档 | 基础备份与 WAL 归档正常 | 恢复能力可验证 | +| 运维监控 | 关键节点监控、日志、告警正常 | 运维可观测性正常 | + +## 部署结论 + +在已采纳 PostgreSQL 16 方案二作为数据库部署方案的前提下，建议福建水务营收系统采用“前后端分层部署 + 中间件集中部署 + 数据库主备分离部署”的整体部署模式。 + +本方案的最终结论如下： + +1. 公网入口薄转发不纳入我方主机资源；我方实际部署的统一接入入口为内网 Nginx 入口节点。 +2. 2 台业务应用节点作为核心业务集群，节点内同时部署 Spring Boot Gateway 和业务服务，承接微服务统一接入与核心业务处理。 +3. 综合节点集中承载 Redis、Nacos、RustFS 及数据库控制组件，进一步压缩一期主机数量并降低部署复杂度。 + +## RustFS 产品介绍与选型说明 + +RustFS 是一款支持私有化部署的 S3 兼容对象存储方案，可用于承接图片、附件、导出文件和归档文件等非结构化数据场景。结合本项目当前整体部署方案，RustFS 作为综合节点上的对象存储组件，可替代 MinIO 承接对象存储能力。 + +本项目采用 RustFS 的原因如下： + +1. RustFS 具备对象存储能力，适合图片、附件、导出文件和归档文件统一存储。 +2. RustFS 支持私有化部署，适合甲方对自主可控和本地化部署的要求。 +3. RustFS 可作为独立对象存储组件部署在综合节点中，与缓存、配置治理和数据库控制能力协同运行。 +4. 当前方案中，银行文件交换仍由独立的 SFTP/FTP 文件交换服务器承接，RustFS 不承担银行送盘、回盘和对账文件交换职责。 +4. 新增 1 台 SFTP/FTP 文件交换服务器，作为银行送盘、回盘、对账文件交换专用前置机。 +5. PostgreSQL 16 采用同城双可用区 1 主 1 热备部署，满足高可用要求。 +6. 网络采用公网接入区、内网接入区、应用区、中间件与文件存储区、银行文件交换区、数据区分层隔离模式，以满足安全性、可维护性和资源审批要求。 diff --git a/docs/design/03_Technical_Design/README.md b/docs/design/03_Technical_Design/README.md index ca0847b..7c877fa 100644 --- a/docs/design/03_Technical_Design/README.md +++ b/docs/design/03_Technical_Design/README.md @@ -16,6 +16,7 @@ - `02_Table_Specs.md`：单表规格补充（历史映射，非主口径） - `06_Sensitive_Data_Encryption.md`：敏感数据加密方案 - `07_PostgreSQL16_DR_Resource_Application.md`：PostgreSQL 16 容灾与资源申请专题说明 +- `08_Integrated_Deployment_Design_PlanB.md`：采纳 PostgreSQL 16 方案二后的整体部署方案 ## 维护原则 diff --git a/docs/design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx b/docs/design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx new file mode 100644 index 0000000..f9a8a5a Binary files /dev/null and b/docs/design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx differ diff --git a/docs/design/04_Appendix/Archive/银行缴费接口规范设计文档.md b/docs/design/04_Appendix/Archive/银行缴费接口规范设计文档.md new file mode 100644 index 0000000..c76a243 --- /dev/null +++ b/docs/design/04_Appendix/Archive/银行缴费接口规范设计文档.md @@ -0,0 +1,573 @@ +# 营收系统接口规范设计文档 + +## 1. 文档概述 + +### 1.1 文档信息 +- **文档名称**：营收系统接口规范设计文档 +- **版本**：1.0 +- **编写日期**：2024年12月 +- **基于原始文档**：营收系统缴费接口 v1.5 + +### 1.2 设计目标 +本文档旨在为营收系统与银行/第三方支付机构之间的接口交互提供标准化、规范化的设计指导，确保系统的高可用性、安全性和可扩展性。 + +### 1.3 适用范围 +- 公用事业单位（水司、电力等） +- 银行机构 +- 第三方支付平台 +- 系统集成商 + +## 2. 系统架构设计 + +### 2.1 整体架构 + +``` +┌─────────────────┐ HTTP/HTTPS ┌─────────────────┐ +│ │<──────────────────>│ │ +│ 银行/支付平台 │ │ 营收系统 │ +│ │ │ │ +└─────────────────┘ └─────────────────┘ + │ │ + │ │ + v v +┌─────────────────┐ ┌─────────────────┐ +│ 对账文件处理 │ │ 业务数据库 │ +└─────────────────┘ └─────────────────┘ +``` + +### 2.2 接口分层设计 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 表示层 (Presentation Layer) │ +│ HTTP/HTTPS + XML/JSON │ +├─────────────────────────────────────────────────────────┤ +│ 业务层 (Business Layer) │ +│ 查询服务 | 缴费服务 | 代扣服务 | 对账服务 │ +├─────────────────────────────────────────────────────────┤ +│ 数据层 (Data Layer) │ +│ 用户数据 | 账单数据 | 交易数据 │ +└─────────────────────────────────────────────────────────┘ +``` + +## 3. 接口设计规范 + +### 3.1 RESTful设计原则 + +虽然原系统使用XML格式，但建议遵循RESTful设计原则： + +| 功能模块 | HTTP方法 | 资源路径 | 描述 | +|----------|----------|----------|------| +| 账单查询 | POST | `/api/app/billQuery/query` | 查询用户账单 | +| 账单缴费 | POST | `/api/app/billPay/pay` | 执行缴费操作 | +| 账单红冲 | POST | `/api/app/payInvalid/payInvalid` | 红冲已缴费账单 | +| 代扣签约 | POST | `/api/app/bankWithholding/signing` | 代扣签约 | +| 代扣解约 | POST | `/api/app/bankWithholding/termination` | 代扣解约 | +| 代扣送盘 | POST | `/api/app/bankWithholding/sendDisc` | 代扣送盘 | +| 代扣回盘 | POST | `/api/app/bankWithholding/backDisc` | 代扣回盘 | + +### 3.2 数据格式规范 + +#### 3.2.1 请求格式 +- **内容类型**：`application/xml` 或 `application/json` +- **字符编码**：GBK（XML）或 UTF-8（JSON） +- **请求方法**：POST + +#### 3.2.2 响应格式 +- **状态码**：200 OK（业务成功/失败通过返回码区分） +- **内容类型**：与请求格式保持一致 +- **响应结构**：统一的响应格式 + +### 3.3 安全设计规范 + +#### 3.3.1 加密策略 + +``` +┌─────────────────┐ 加密传输 ┌─────────────────┐ +│ 客户端 │ ──────────────> │ 服务端 │ +│ │ │ │ +│ 1. 数据加密 │ │ 1. 数据解密 │ +│ 2. Base64编码 │ │ 2. Base64解码 │ +│ 3. HTTP传输 │ │ 3. 业务处理 │ +└─────────────────┘ └─────────────────┘ +``` + +#### 3.3.2 支持的加密算法 + +| 加密类型 | 加密模式 | 填充方式 | 安全等级 | +|----------|----------|----------|----------| +| 3DES | ECB | PKCS7 | 中等 | +| SM2 | C1C3C2/C1C2C3 | - | 高 | +| SM4 | ECB/CBC | PKCS7 | 高 | + +#### 3.3.3 请求头设计 + +```http +Content-Type: application/xml; charset=GBK +EncryptType: 3DES +EncryptMode: ECB +DataType: XML +``` + +### 3.4 错误处理规范 + +#### 3.4.1 统一错误码设计 + +``` +AAAAAAA: 成功 +DEF0xxx: 业务错误 (0001-0999) +SYS1xxx: 系统错误 (1000-1999) +SEC2xxx: 安全错误 (2000-2999) +NET3xxx: 网络错误 (3000-3999) +``` + +#### 3.4.2 错误响应格式 + +```xml + + 1.0.1 + 00001 + QueryRes + 20240101 + 123456789012 + DEF0001 + 无相应记录 + + DEF0001 + 用户编号123456不存在 + 2024-01-01 12:00:00 + + +``` + +## 4. 数据模型设计 + +### 4.1 核心实体模型 + +#### 4.1.1 用户实体 (Customer) + +```sql +CREATE TABLE customer ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + bill_key VARCHAR(35) NOT NULL UNIQUE COMMENT '客户编号', + customer_name VARCHAR(150) NOT NULL COMMENT '客户姓名', + contract_no VARCHAR(30) COMMENT '合同号', + company_id VARCHAR(30) NOT NULL COMMENT '机构编码', + created_time DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_bill_key (bill_key), + INDEX idx_company_id (company_id) +); +``` + +#### 4.1.2 账单实体 (Bill) + +```sql +CREATE TABLE bill ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + bill_key VARCHAR(35) NOT NULL COMMENT '客户编号', + company_id VARCHAR(30) NOT NULL COMMENT '机构编码', + pay_amount DECIMAL(16,2) NOT NULL COMMENT '缴费金额', + balance DECIMAL(16,2) DEFAULT 0.00 COMMENT '余额', + begin_date DATE COMMENT '账单开始日期', + end_date DATE COMMENT '账单结束日期', + bill_status TINYINT DEFAULT 0 COMMENT '账单状态 0:未缴费 1:已缴费', + created_time DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_bill_key (bill_key), + INDEX idx_company_id (company_id), + INDEX idx_status (bill_status) +); +``` + +#### 4.1.3 交易记录 (Transaction) + +```sql +CREATE TABLE transaction ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + tran_seq VARCHAR(40) NOT NULL UNIQUE COMMENT '交易流水号', + bill_key VARCHAR(35) NOT NULL COMMENT '客户编号', + company_id VARCHAR(30) NOT NULL COMMENT '机构编码', + tran_code VARCHAR(20) NOT NULL COMMENT '交易码', + pay_amount DECIMAL(16,2) NOT NULL COMMENT '交易金额', + pay_date DATETIME NOT NULL COMMENT '交易时间', + sub_channel TINYINT COMMENT '二级渠道 1:支付宝 2:微信 6:其它', + tran_status TINYINT DEFAULT 0 COMMENT '交易状态 0:处理中 1:成功 2:失败', + resp_code VARCHAR(7) COMMENT '返回码', + resp_message VARCHAR(60) COMMENT '返回消息', + created_time DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_tran_seq (tran_seq), + INDEX idx_bill_key (bill_key), + INDEX idx_pay_date (pay_date), + INDEX idx_status (tran_status) +); +``` + +### 4.2 代扣相关实体 + +#### 4.2.1 代扣协议 (WithholdingAgreement) + +```sql +CREATE TABLE withholding_agreement ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + bill_key VARCHAR(35) NOT NULL COMMENT '客户编号', + company_id VARCHAR(30) NOT NULL COMMENT '机构编码', + account_name VARCHAR(150) NOT NULL COMMENT '开户名', + account_no VARCHAR(30) NOT NULL COMMENT '开户账号', + bank_name VARCHAR(150) COMMENT '银行名称', + contract_no VARCHAR(150) COMMENT '合同号', + agreement_no VARCHAR(150) COMMENT '协议号', + bank_type TINYINT COMMENT '银行类型 0:本行 1:他行', + agreement_status TINYINT DEFAULT 0 COMMENT '协议状态 0:未签约 1:已签约 2:已解约', + signing_date DATE COMMENT '签约日期', + termination_date DATE COMMENT '解约日期', + created_time DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_bill_key (bill_key), + INDEX idx_account_no (account_no), + INDEX idx_status (agreement_status) +); +``` + +## 5. 接口实现规范 + +### 5.1 查询接口实现 + +#### 5.1.1 业务流程 + +``` +Client Request → Parameter Validation → Business Logic → Data Query → Response Format → Client Response +``` + +#### 5.1.2 核心逻辑 + +```java +@Service +public class BillQueryService { + + public QueryResponse queryBill(QueryRequest request) { + // 1. 参数校验 + validateRequest(request); + + // 2. 业务逻辑处理 + List bills = billRepository.findByBillKeyAndCompanyId( + request.getBillKey(), + request.getCompanyId() + ); + + // 3. 构造响应 + return buildQueryResponse(bills); + } + + private void validateRequest(QueryRequest request) { + if (StringUtils.isEmpty(request.getBillKey())) { + throw new BusinessException("DEF0001", "客户编号不能为空"); + } + // 其他校验逻辑... + } +} +``` + +### 5.2 缴费接口实现 + +#### 5.2.1 业务流程 + +``` +Client Request → Parameter Validation → Balance Check → Payment Processing → Transaction Record → Response +``` + +#### 5.2.2 事务处理 + +```java +@Service +@Transactional +public class BillPayService { + + public PayResponse payBill(PayRequest request) { + // 1. 参数校验 + validatePayRequest(request); + + // 2. 账单查询 + Bill bill = billRepository.findByBillKeyAndCompanyId( + request.getBillKey(), + request.getCompanyId() + ); + + // 3. 金额校验 + if (bill.getPayAmount().compareTo(request.getPayAmount()) != 0) { + throw new BusinessException("DEF0002", "缴费金额不匹配"); + } + + // 4. 更新账单状态 + bill.setBillStatus(1); + billRepository.save(bill); + + // 5. 记录交易 + Transaction transaction = createTransaction(request); + transactionRepository.save(transaction); + + // 6. 构造响应 + return buildPayResponse(request); + } +} +``` + +## 6. 性能设计规范 + +### 6.1 性能指标 + +| 指标类型 | 要求 | 说明 | +|----------|------|------| +| 响应时间 | < 3秒 | 95%的请求在3秒内响应 | +| 并发量 | 1000 TPS | 支持1000笔/秒的交易处理 | +| 可用性 | 99.9% | 年度可用性不低于99.9% | +| 错误率 | < 0.1% | 系统错误率控制在0.1%以内 | + +### 6.2 缓存策略 + +```java +@Service +public class BillQueryService { + + @Cacheable(value = "billCache", key = "#billKey + '_' + #companyId") + public List queryBillWithCache(String billKey, String companyId) { + return billRepository.findByBillKeyAndCompanyId(billKey, companyId); + } +} +``` + +### 6.3 数据库优化 + +#### 6.3.1 索引设计 +- 主要查询字段建立索引 +- 复合索引优化多条件查询 +- 定期分析索引使用情况 + +#### 6.3.2 分表策略 +- 按时间分表：每月一张交易表 +- 按机构分库：不同机构使用不同数据库 + +## 7. 监控与日志规范 + +### 7.1 日志规范 + +#### 7.1.1 日志级别 +- ERROR: 系统错误，需要立即处理 +- WARN: 业务警告，需要关注 +- INFO: 关键业务流程记录 +- DEBUG: 调试信息 + +#### 7.1.2 日志格式 + +``` +[时间戳] [日志级别] [线程名] [类名] [方法名] - [交易流水号] [业务描述] [详细信息] +``` + +示例： +``` +2024-01-01 12:00:00.123 [INFO] [http-thread-1] [BillQueryService] [queryBill] - [TXN123456789012] 查询账单开始 {"billKey":"123456","companyId":"654321"} +``` + +### 7.2 监控指标 + +#### 7.2.1 业务监控 +- 交易成功率 +- 平均响应时间 +- 接口调用量 +- 错误码分布 + +#### 7.2.2 系统监控 +- CPU使用率 +- 内存使用率 +- 数据库连接数 +- 网络IO + +## 8. 部署架构规范 + +### 8.1 生产环境架构 + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ 负载均衡器 │────>│ Web服务器1 │ │ 数据库主库 │ +│ (Nginx/F5) │ │ (Tomcat) │────>│ (MySQL) │ +│ │ └─────────────────┘ │ │ +│ │ ┌─────────────────┐ └─────────────────┘ +│ │────>│ Web服务器2 │ ┌─────────────────┐ +└─────────────────┘ │ (Tomcat) │────>│ 数据库从库 │ + └─────────────────┘ │ (MySQL) │ + └─────────────────┘ +``` + +### 8.2 容器化部署 + +#### 8.2.1 Docker配置 + +```dockerfile +FROM openjdk:8-jre-alpine +VOLUME /tmp +ADD app.jar app.jar +EXPOSE 8080 +ENTRYPOINT ["java","-Djava.security.egd=file:/dev/./urandom","-jar","/app.jar"] +``` + +#### 8.2.2 Kubernetes配置 + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: billing-api +spec: + replicas: 3 + selector: + matchLabels: + app: billing-api + template: + metadata: + labels: + app: billing-api + spec: + containers: + - name: billing-api + image: billing-api:latest + ports: + - containerPort: 8080 + resources: + requests: + memory: "512Mi" + cpu: "500m" + limits: + memory: "1Gi" + cpu: "1" +``` + +## 9. 测试规范 + +### 9.1 测试策略 + +#### 9.1.1 单元测试 +- 覆盖率 >= 80% +- 核心业务逻辑 100% 覆盖 +- Mock 外部依赖 + +#### 9.1.2 集成测试 +- 接口层面的集成测试 +- 数据库集成测试 +- 第三方服务集成测试 + +#### 9.1.3 性能测试 +- 压力测试：测试系统极限 +- 负载测试：测试正常负载下的性能 +- 稳定性测试：长时间运行测试 + +### 9.2 测试用例设计 + +#### 9.2.1 查询接口测试用例 + +```java +@Test +public void testQueryBill_Success() { + // Given + QueryRequest request = new QueryRequest(); + request.setBillKey("123456"); + request.setCompanyId("654321"); + + // When + QueryResponse response = billQueryService.queryBill(request); + + // Then + assertEquals("AAAAAAA", response.getRespCode()); + assertNotNull(response.getData()); +} + +@Test +public void testQueryBill_NotFound() { + // Given + QueryRequest request = new QueryRequest(); + request.setBillKey("999999"); + request.setCompanyId("654321"); + + // When & Then + BusinessException exception = assertThrows( + BusinessException.class, + () -> billQueryService.queryBill(request) + ); + assertEquals("DEF0001", exception.getCode()); +} +``` + +## 10. 安全审计规范 + +### 10.1 安全审计要求 + +#### 10.1.1 审计内容 +- 所有接口调用记录 +- 敏感操作日志 +- 异常访问记录 +- 系统配置变更 + +#### 10.1.2 审计日志格式 + +```json +{ + "timestamp": "2024-01-01T12:00:00.123Z", + "event_type": "API_CALL", + "user_id": "bank_001", + "ip_address": "192.168.1.100", + "endpoint": "/api/app/billQuery/query", + "request_id": "TXN123456789012", + "response_code": "AAAAAAA", + "execution_time": 1500, + "data_accessed": { + "bill_key": "123456", + "company_id": "654321" + } +} +``` + +### 10.2 安全控制措施 + +#### 10.2.1 访问控制 +- IP白名单机制 +- API密钥认证 +- 请求频率限制 + +#### 10.2.2 数据保护 +- 敏感数据加密存储 +- 传输过程加密 +- 数据脱敏处理 + +## 11. 运维规范 + +### 11.1 发布流程 + +``` +开发环境 → 测试环境 → 预生产环境 → 生产环境 + ↓ ↓ ↓ ↓ + 单元测试 集成测试 性能测试 灰度发布 +``` + +### 11.2 回滚策略 + +#### 11.2.1 快速回滚 +- 保留前一版本的部署包 +- 数据库版本管理 +- 配置文件版本控制 + +#### 11.2.2 回滚触发条件 +- 系统错误率超过阈值 +- 响应时间超过预期 +- 业务功能异常 + +## 12. 总结 + +本规范设计文档为营收系统接口的设计、开发、测试、部署和运维提供了全面的指导。通过遵循这些规范，可以确保系统的： + +1. **可靠性**：通过完善的错误处理和事务管理 +2. **安全性**：通过多层次的安全控制措施 +3. **性能**：通过合理的架构设计和优化策略 +4. **可维护性**：通过标准化的代码和文档规范 +5. **可扩展性**：通过模块化和微服务架构设计 + +建议在实际项目中根据具体需求对本规范进行适当调整和完善。 \ No newline at end of file diff --git a/docs/design/04_Appendix/Archive/银行缴费接口说明-v2.md b/docs/design/04_Appendix/Archive/银行缴费接口说明-v2.md new file mode 100644 index 0000000..a645b18 --- /dev/null +++ b/docs/design/04_Appendix/Archive/银行缴费接口说明-v2.md @@ -0,0 +1,385 @@ +# 营收系统缴费接口文档 + +**版本：** 1.5 +**作者：** 曹红强 +**最后更新：** 2023/03/10 + +## 修订记录 + +| 版本号 | 修改日期 | 修改人 | 修改内容 | +|--------|----------|--------|----------| +| v1.0 | 2021/03/24 | 曹红强 | 初始版本 | +| v1.1 | 2021/04/04 | 曹红强 | 新增代扣相关接口 | +| v1.2 | 2021/12/21 | 曹红强 | 完善文档结构及说明 | +| v1.3 | 2022/01/25 | 晋腾飞 | 完善文档结构及说明 | +| v1.4 | 2022/05/02 | 晋腾飞 | 添加托收相关接口 | +| v1.5 | 2023/03/10 | 晋腾飞 | 添加加密方式说明 | + +## 概述 + +本文档主要是针对营收系统和银行（或代收机构）间的实时收费、银行代扣、银行托收（小额支付）协议。 + +## 术语 + +1. **商户/第三方支付平台/支付平台/第三方/支付公司**：指第三方支付公司（比如支付宝、微信等）或者银行（比如招商银行、平安银行等）。 +2. **公用事业单位**：指接入的缴费事业单位，例如自来水公司、电力公司等。第三方支付发起的实时交易经总行和分行转发最终到公用事业单位进行处理。 + +## 通讯模式 + +- **通讯协议**：HTTP +- **提交方式**：POST +- **加密方式**：在请求头Header中填写 +- **参数格式**：HTTP包体中采用XML或JSON格式，默认XML格式 +- **服务端口和地址**：由公用事业单位提供 +- **超时时间**：银行方接收接口返回超时时间建议设置为30秒 + +## 报文说明 + +### 报文格式 + +#### XML格式示例 + +```xml + + + 1.0.1 + 缴费渠道 + 交易码 + 交易日期 + 交易流水号 + VALUE1 + VALUE2 + +``` + +#### 报文说明 + +1. **编码方式**：报文中固定写"GBK"，实际编码采用GBK +2. **in**：根节点 +3. **Version**：固定写"1.0.1" +4. **InstId**：缴费渠道，最大长度5个字节，区别不同缴费渠道 +5. **TranCode**：交易码 + - 账单查询：Query/QueryRes + - 账单缴费：Pay/PayRes +6. **TranDate**：交易日期，格式YYYYMMDD +7. **TranSeq**：交易流水号，由银行系统产生，最大长度40个字节，同一天内不可重复 + +### 报文加密 + +#### 加密方式说明 + +加密方式填写在HTTP请求头Header里面，支持的加密方式：3DES、SM2、SM4 + +| 字段 | Header字段名 | 长度 | 约束条件 | 说明 | +|------|-------------|------|----------|------| +| 加密类型 | EncryptType | char(20) | 必填 | 3DES,SM2,SM4 (默认3DES) | +| 加密模式 | EncryptMode | char(20) | 必填 | 3DES(ECB), SM2(C1C2C3,C1C3C2), SM4(ECB,CBC) | +| 数据格式 | DataType | char(20) | 必填 | XML或JSON，默认XML | + +#### 默认加密方式 + +如果HTTP请求头Header（EncryptType）不填写加密方式，默认为XML报文整体采用3DES函数加密，ECB模式PKCS7填充。加密后的报文用base64编码。 + +#### SM2加密方式 + +HTTP请求头Header字段EncryptType填写SM2，默认加密模式为C1C3C2，默认报文body数据格式为XML。 + +#### SM4加密方式 + +HTTP请求头Header字段EncryptType填写SM4，默认加密模式为ECB，默认报文body数据格式为XML。 + +## 报文头 + +所有接口报文开始都有以下5个固定域： + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|----------|--------|------|----------|------| +| 版本号 | Version | char(20) | 必填 | 固定为1.0.1 | +| 缴费渠道 | InstId | char(5) | 必填 | 由水司软件方提供 | +| 交易码 | TranCode | char(20) | 必填 | 见交易码说明 | +| 交易日期 | TranDate | char(8) | 必填 | YYYYMMDD | +| 流水号 | TranSeq | char(40) | 必填 | 银行系统产生的唯一流水号 | + +### 交易码说明 + +- 账单查询：Query/QueryRes +- 账单缴费：Pay/PayRes +- 代扣签约：Signing/SigningRes +- 代扣解约：Termination/TerminationRes +- 代扣送盘：SendDisc/SendDiscRes +- 代扣回盘：BackDisc/BackDiscRes +- 取消代扣：CancelDisc/CancelDiscRes + +## 接口规范 + +### 1. 账单查询接口 + +#### 请求接口 +- **接口地址**：`/api/app/billQuery/query` +- **请求方法**：POST +- **交易码**：Query + +#### 请求参数 + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|----------|--------|------|----------|------| +| 客户编号 | billKey | char(35) | 必填 | 用水户的唯一标识 | +| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 | +| 开始条数 | beginNum | Num(5) | 可选 | 默认1 | +| 查询条数 | queryNum | Num(5) | 可选 | 默认1，最大100 | +| 扩展字段1 | filed1 | char(100) | 可选 | 扩展字段 | +| 扩展字段2 | filed2 | char(100) | 可选 | 扩展字段 | +| 扩展字段3 | filed3 | char(100) | 可选 | 扩展字段 | +| 扩展字段4 | filed4 | char(100) | 可选 | 扩展字段 | + +#### 请求示例 + +```xml + + + 1.0.1 + 00001 + Query + 20180101 + 123456789012 + 123456 + 654321 + 1 + 1 + + + + + +``` + +#### 应答参数 + +| 中文域名 | 标签名 | 长度 | 说明 | +|----------|--------|------|------| +| 返回代码 | RespCode | char(7) | 查询返回代码 | +| 返回说明 | RespMessage | char(60) | 查询返回说明 | +| 客户编号 | billKey | char(35) | 原样返回 | +| 机构编码 | companyId | char(30) | 原样返回 | +| 总条数 | totalNum | Num(5) | 查询结果总条数 | + +#### Data数据结构 + +| 中文域名 | 标签名 | 长度 | 说明 | +|----------|--------|------|------| +| 合同号 | contractNo | char(30) | 合同号码 | +| 客户姓名 | customerName | char(150) | 客户姓名 | +| 余额 | balance | Number(16,2) | 账户余额 | +| 缴费金额 | payAmount | Number(16,2) | 应缴费金额 | +| 开始日期 | beginDate | char(8) | 账单开始日期 | +| 结束日期 | endDate | char(8) | 账单结束日期 | + +#### 应答示例 + +```xml + + + 1.0.1 + 00001 + QueryRes + 20180101 + 123456789012 + AAAAAAA + 查询成功 + 123456 + 654321 + 1 + + 123456 + 张三 + + 2314 + + + + +``` + +### 2. 缴费接口 + +#### 请求接口 +- **接口地址**：`/api/app/billPay/pay` +- **请求方法**：POST +- **交易码**：Pay + +#### 请求参数 + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|----------|--------|------|----------|------| +| 客户编号 | billKey | char(35) | 必填 | 用水户的唯一标识 | +| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 | +| 缴费日期 | payDate | char(14) | 必填 | YYYYMMDDHHMMSS | +| 客户姓名 | customerName | char(150) | 必填 | 客户姓名 | +| 缴费金额 | payAmount | Number(16,2) | 必填 | 缴费金额 | +| 合同号 | contractNo | char(30) | 必填 | 合同号码 | +| 查询类型 | queryType | char(1) | 可选 | 默认0，客户编号查询；1：条形码查询 | +| 二级渠道 | subChannel | char(1) | 可选 | 1:支付宝 2:微信 6:其它 | + +#### 请求示例 + +```xml + + + 1.0.1 + 00001 + Pay + 20180101 + 123456789012 + 123456 + 654321 + 20110513081540 + 张三 + 5555 + 123456 + +``` + +#### 应答参数 + +| 中文域名 | 标签名 | 长度 | 说明 | +|----------|--------|------|------| +| 返回代码 | RespCode | char(7) | 缴费返回代码 | +| 返回说明 | RespMessage | char(60) | 缴费返回说明 | +| 客户编号 | billKey | char(35) | 原样返回 | +| 机构编码 | companyId | char(30) | 原样返回 | +| 交易日期 | payDate | char(14) | 原样返回 | +| 缴费金额 | payAmount | Number(16,2) | 原样返回 | + +#### 应答示例 + +```xml + + + 1.0.1 + 00001 + PayRes + 20180101 + 123456789012 + AAAAAAA + 缴费成功 + 123456 + 654321 + 20110513081540 + 5555 + +``` + +### 3. 账单红冲接口 + +#### 请求接口 +- **接口地址**：`/api/app/payInvalid/payInvalid` +- **请求方法**：POST +- **交易码**：PayInvalid + +#### 请求参数 + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|----------|--------|------|----------|------| +| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 | +| 交易日期 | payDate | char(14) | 必填 | YYYYMMDDHHMMSS | +| 红冲流水号 | agencyBillNo | char(30) | 必填 | 缴费时的账单流水号 | +| 缴费金额 | payMoney | char(30) | 必填 | 缴费金额 | + +**说明**：只可红冲当天收费且未对账交易，红冲成功后银行需发起自动退款。 + +### 4. 代扣签约接口 + +#### 请求接口 +- **接口地址**：`/api/app/bankWithholding/signing` +- **请求方法**：POST +- **交易码**：Signing + +#### 请求参数 + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|----------|--------|------|----------|------| +| 客户编号 | billKey | char(35) | 必填 | 用水户的唯一标识 | +| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 | +| 签约日期 | signingDate | char(8) | 必填 | YYYYMMDD | +| 开户名 | accountName | char(150) | 必填 | 开户名 | +| 开户账号 | accountNo | char(30) | 必填 | 用户的账号 | +| 银行名称 | bankName | char(150) | 可选 | 总行名称 | +| 合同号 | contractNo | char(150) | 可选 | 合同号 | +| 协议号 | agreementNo | char(150) | 可选 | 协议号 | +| 银行类型 | bankType | char(1) | 可选 | 0：本行 1：他行 | + +### 5. 代扣解约接口 + +#### 请求接口 +- **接口地址**：`/api/app/bankWithholding/termination` +- **请求方法**：POST +- **交易码**：Termination + +### 6. 代扣送盘接口 + +#### 请求接口 +- **接口地址**：`/api/app/bankWithholding/sendDisc` +- **请求方法**：POST +- **交易码**：SendDisc + +### 7. 代扣回盘接口 + +#### 请求接口 +- **接口地址**：`/api/app/bankWithholding/backDisc` +- **请求方法**：POST +- **交易码**：BackDisc + +## 对账文件 + +### 对账文件格式 + +对账文件为文本文件txt格式，编码格式为UTF-8，包括明细行和汇总行。行内每个分项之间以"|"为分隔符。 + +#### 汇总行格式 +``` +交易笔数|总金额 +``` + +#### 明细行格式 +``` +交易日期|交易流水号|客户编号|缴费金额|二级渠道|交易类型 +``` + +#### 文件命名规则 +``` +机构编码(companyId)_对账日期.txt +``` + +其中对账日期为交易当天日期非当前时间。 + +## 返回代码说明 + +| 序号 | 错误码 | 错误说明 | +|------|--------|----------| +| 0 | AAAAAAA | 成功 | +| 1 | DEF0001 | 无相应记录 | +| 2 | DEF0002 | 用户未欠费 | +| 3 | DEF0003 | 与第三方通讯失败 | +| 4 | DEF0004 | 超过受理期,银行不予受理,请至缴费单位缴费 | + +## 附录 + +### 扣款结果标志说明 + +- **0**：扣款成功，其余状态按失败处理 +- **1**：扣款失败，余额不足 +- **2**：账号、户名错误 +- **3**：账号不存在 +- **4**：重复扣款 +- **99**：其他原因 + +### 二级渠道说明 + +- **1**：支付宝 +- **2**：微信 +- **6**：其它 + +### 银行类型说明 + +- **0**：本行 +- **1**：他行 \ No newline at end of file diff --git a/docs/design/04_Appendix/Archive/银行缴费接口说明.md b/docs/design/04_Appendix/Archive/银行缴费接口说明.md new file mode 100644 index 0000000..c0da121 --- /dev/null +++ b/docs/design/04_Appendix/Archive/银行缴费接口说明.md @@ -0,0 +1,606 @@ +# 营收系统缴费接口 + +**版本：** 1.5 + +**作者：** 曹红强 + +## 修订记录 + +| 版本号 | 修改日期 | 修改人 | 修改内容 | +|---|---|---|---| +| v1.0 | 2021/03/24 | 曹红强 | 初始版本 | +| v1.1 | 2021/04/04 | 曹红强 | 新增代扣相关接口 | +| v1.2 | 2021/12/21 | 曹红强 | 完善文档结构及说明 | +| v1.3 | 2022/01/25 | 晋腾飞 | 完善文档结构及说明 | +| v1.4 | 2022/05/02 | 晋腾飞 | 添加托收相关接口 | +| v1.5 | 2023/03/10 | 晋腾飞 | 添加加密方式说明 | + + + + +## 概述 + +本文档主要是针对营收系统和银行（或代收机构）间的实时收费、银行代扣、银行托收（小额支付）协议。 + + + + +## 术语 + +1. 文档中提到的商户、第三方支付平台、支付平台、第三方、支付公司指的就是第三方支付公司（比如支付宝，微信等）或者银行（比如招商银行，平安银行等）。 + +2. 公用事业单位：是指从接入的缴费事业单位，例如：自来水公司，电力公司等，第三方支付发的实时交易经总行和分行转发最终到公用事业单位进行处理。 + + + + +## 通讯模式 + +公用事业单位和银行系统之间采用 Http 进行通讯，提交方式为 POST，加密方式在请求头 Header 填写，接口参数在 Http 包体中采用 XML 或 JSON 格式，默认 XML 格式。服务端口和服务地址，由公用事业单位提供。银行方接收接口返回超时时间建议设置为 30 秒。 + + + + +## 报文说明 + +### 报文格式 + +#### XML + +```xml + + + 1.0.1 + 缴费渠道 + 交易码 + 交易日期 + 交易流水号 + VALUE1 + VALUE2 + +``` + +如上所示为 XML 报文示例： + +1. 编码方式在报文中固定写“GBK”，但是实际的编码采用 GBK； +2. `in`：根节点； +3. `Version`：固定写“1.0.1”。 +4. `InstId`：缴费渠道，长度最大长度 5 个字节，区别不同缴费渠道 +5. `TranCode`：交易码，账单查询时交易码为 Query,查询应答给银行为 QueryRes；账单缴费时交易码为 Pay，缴费应答给银行时为 PayRes。 +6. `TranDate`：交易日期，YYYYMMDD，如 20210101，当前交易时间。 +7. `TranSeq`：交易流水号，由银行系统产生，用作标识每笔交易的请求，最大长度 40 个字节，并且同一天内该值不可重复。 +8. `TAG1`：节点标签名； +9. `VALUE1`：节点值。 + + + + +### 报文模版 + +#### 请求 + +```xml + + + 1.0.1 + 00001 + Query + 20180101 + 123456789012 + 客户编号 + …… + + +``` + +#### 应答 + +```xml + + + 1.0.1 + 00001 + QueryRes + 请求的日期原样返回 + 请求的日期原样返回 + AAAAAAA + 成功 + 客户编号 + …… + + 1 + + 合同号 + + +``` + + + + +### 报文样例 + +#### 查询请求 + +```xml + + + 1.0.1 + 00001 + Query + 20180101 + 123456789012 + 123456 + 654321 + 1 + 1 + + + + + +``` + +#### 查询应答 + +```xml + + + 1.0.1 + 00001 + QueryRes + 20180101 + 123456789012 + AAAAAAA + 查询成功 + + 123456 + 654321 + + + + + + + + 1 + + 123456 + 张三 + + 2314 + + + + + + + + + +``` + + + + +### 销账请求 + +```xml + + + 1.0.1 + 00001 + Pay + 20180101 + 123456789012 + 123456 + 654321 + 20110513081540 + + + + + 张三 + 5555 + 123456 + +``` + +### 销账应答 + +```xml + + + 1.0.1 + 00001 + PayRes + 20180101 + 123456789012 + AAAAAA + 缴费成功 + 123456 + 654321 + 20110513081540 + 5555 + +``` + + + + +## 报文编码 + +报文中可能有汉字，需要对报文进行 GBK 编码才能正常显示。 + +1. 编码方式在报文中固定写“GBK” + + + + +## 报文加密 + +### 加密方式说明 + +加密方式填写在 http 请求头 Header 里面，加密方式有：3DES,SM2,SM4，加密方式对 body 数据整体进行加密 + +| 中文域名 | 字段 | 长度 | 约束条件 | 说明 | +|---|---|---|---|---| +| 加密类型 | EncryptType | char(20) | 必填 | 3DES,SM2,SM4 (默认 3DES) | +| 加密模式 | EncryptMode | char(20) | 必填 | 3DES(ECB), SM2(C1C2C3,C1C3C2), SM4(ECB,CBC) | +| 数据格式 | DataType | char(20) | 必填 | XML 或 JOSN (默认 XML) | + +### 默认加密方式 + +如果 http 请求头 Header（EncryptType）不填写加密方式，默认为 XML 报文整体采用 3DES 函数加密，ECB 模式 PKCS7P 填充。 + +加密之后的报文，用 base64 编码。 + +### SM2 加密方式 + +http 请求头 Header 字段 EncryptType 填写 SM2，默认加密模式为 C1C3C2,默认报文 body 数据格式为 XML + +### SM4 加密方式 + +http 请求头 Header 字段 EncryptType 填写 SM4，默认加密模式为 ECB,默认报文 body 数据格式为 XML + +### 加密请求示例 + +加密方式请求头填写示例： + +``` +[Image Placeholder for Encrypt Header Example] +``` + +加密 body 请求示例： + +``` +[Image Placeholder for Encrypt Body Example] +``` + + + + +## 报文头 + +### 报文头固定域 + +所有接口报文开始，都有这 5 个域，这里统一说明。查询和缴费的章节，不再说明报文头这 5 个域。 + +| 中文域名 | 标签名 | 长度 | 对应字段 | 约束条件 | 说明 | +|---|---|---|---|---|---| +| 版本号 | Version | char(20) | | 必填 | 固定为 1.0.1 | +| 缴费渠道 | InstId | char(5) | | 必填 | 由水司软件方提供 | +| 交易码 | TranCode | char(20) | | 必填 | 见说明 | +| 交易日期 | TranDate | char(8) | | 必填 | YYYYMMDD | +| 流水号 | TranSeq | char(40) | Input2 | 必填 | 见说明 | + +说明： + +* **交易码：** + * 账单查询时交易码为 Query,查询应答给予银行为 QueryRes； + * 账单缴费时交易码为 Pay,缴费应答时为 PayRes； + * 代扣签约请求时交易码为 Signing,签约应答时为 SigningRes； + * 代扣解约请求时交易码为 Termination,解约应答时为 TerminationRes； + * 代扣送盘请求时交易码为 SendDisc,送盘应答时交易码为 SendDiscRes； + * 代扣回盘请求时交易码为 BackDisc,回盘应答时交易码为 BackDiscRes； + * 取消代扣交易请求时交易码为 CancelDisc,应答码为 CancelDiscRes； + * 代扣送盘状态查询交易码为 SendDiscCheck,应答交易码为 SendDiscCheckRes； + * 代扣回盘状态查询交易码为 BackDiscCheck,应答交易码为 BackDiscCheckRes； + * 客户基本信息查询交易码为 CustomerCheck, 应答交易码为 CustomerCheckRes; + * 实时收费红冲查询交易码为 PayInvalid,应答交易码为 PayInvalidRes; + * 代理收费向公用事业单位发起缴费单对账请求交易码为 PayCheck，应答交易码为 PayCheckRes。 + +* **交易流水号：** 由银行系统产生，用作标识每笔交易的请求，最大长度 40 个字节，并且值不可重复。 + + + + +## 请求图例 + +### PostMan + +``` +[Image Placeholder for PostMan Example] +``` + +### Swagger + +``` +[Image Placeholder for Swagger Example] +``` + +说明： + +* 请求返回 415 或 400 Body 加密内容请前后添加双引号 +* 请求返回 500 请联系运维人员参与对接 + + + + +## 1.1 实时收费 + +### 欠费查询 + +Query 是从银行向公用事业单位发起的查询缴费单信息的请求报文。 + +**请求地址：** `/api/app/payCeb/getChargeSearch` + +| 中文域名 | 标签名 | 长度 | 对应字段 | 约束条件 | 说明 | +|---|---|---|---|---|---| +| 客户编号 | billKey | char(35) | Input1 | 必填 | 客户编号 | +| 机构编码 | companyId | char(30) | | 必填 | 由水司软件方提供 | +| 查询类型 | billType | char(10) | | 必填 | 见说明 | +| 起始笔数 | beginNum | Num(3) | | | 查询起始笔数，从 1 开始 | +| 查询笔数 | queryNum | Num(3) | | | 查询笔数 | +| 备用字段 | filed1 | char(100) | Input2 | | 二级渠道，默认 6，见说明 | +| 备用字段 | filed2 | char(100) | Input3 | | 预留字段 | +| 备用字段 | filed3 | char(100) | Input4 | | 预留字段 | +| 备用字段 | filed4 | char(100) | Input5 | | 预留字段 | + +说明： + +* **查询类型：** 默认 0，客户编号查询，1 条形码查询，客户编号为条形码； +* **二级渠道：** + * 1:支付宝； + * 2：微信； + * 6：实时收费 + +### 应答报文 + +QueryRes 是公用事业单位返回给银行的查询应答报文。 + +| 中文域名 | 标签名 | 长度 | 对应字段 | 说明 | +|---|---|---|---|---| +| 返回代码 | RespCode | 7 | | 查询返回代码 | +| 返回说明 | RespMessage | 60 | | 查询返回说明 | +| 客户编号 | billKey | char(35) | Output1 | 原样返回 | +| 机构编码 | companyId | Num(30) | | 原样返回 | +| 备用字段 | item1 | Num(100) | Output2 | 预留数据域 | +| 备用字段 | item2 | char(100) | Output3 | 预留数据域 | +| 备用字段 | item3 | char(100) | Item1 | 预留数据域 | +| 备用字段 | item4 | char(100) | Item2 | 预留数据域 | +| 备用字段 | item5 | char(100) | Item3 | 预留数据域 | +| 备用字段 | item6 | char(100) | Item4 | 预留数据域 | +| 备用字段 | item7 | char(100) | Item5 | 预留数据域 | +| 总笔数 | totalNum | char(3) | TotalNum | 返回总查询笔数 | +| 合同号 | contractNo | char(30) | ContractNo | 账单唯一标识 | +| 客户姓名 | customerName | char(100) | CustomerName | 循环域 | +| 余额 | balance | Number | Balance | 循环域(单位：分) | +| 应缴金额 | payAmount | Number | Amount | 循环域(单位：分) | +| 起始日期 | beginDate | char(10) | BeginDate | 循环域，停用字段 | +| 截至日期 | endDate | char(10) | EndDate | 循环域，停用字段 | +| 备用字段 | filed1 | char(100) | FormItem1 | 循环域 账期 | +| 备用字段 | filed2 | char(100) | FormItem2 | 循环域 滞纳金 | +| 备用字段 | filed3 | char(100) | FormItem3 | 循环域 | +| 备用字段 | filed4 | char(100) | FormItem4 | 循环域 | +| 备用字段 | filed5 | char(100) | FormItem5 | 循环域 客户地址 | + + + + +### 欠费缴纳 + +Pay 是银行向公用事业单位发起的欠费缴纳的请求报文。 + +**请求地址：** `/api/app/payCeb/getChargeOffs` + +| 中文域名 | 标签名 | 长度 | 对应字段 | 约束条件 | 说明 | +|---|---|---|---|---|---| +| 客户编号 | billKey | char(35) | Input1 | 必填 | 客户编号 | +| 机构编码 | companyId | char(30) | | 必填 | 由水司软件方提供 | +| 查询类型 | billType | char(10) | | 必填 | 见说明 | +| 交易日期 | payDate | Num(3) | | 必填 | 见说明 | +| 备用字段 | filed1 | char(100) | Input2 | | 帐期 | +| 备用字段 | filed2 | char(100) | Input3 | | 滞纳金(单位：分) | +| 备用字段 | filed3 | char(100) | Item1 | 必填 | 二级渠道，见说明 | +| 备用字段 | filed4 | char(100) | Item2 | | 预留数据域 | +| 客户姓名 | customerName | char(100) | CustomerName | | 查询应答报文取 | +| 缴费金额 | payAmount | Number | Amount | 必填 | (单位：分) | +| 合同号 | contractNo | char(30) | ContractNo | 必填 | 查询接口应答报文取 | + +说明： + +* **查询类型：** 默认 0，客户编号查询，1 条形码查询，客户编号为条形码； +* **交易日期：** YYYYMMDDHHMMSS，(支付缴费单时系统当前时间) +* **二级渠道：** + * 1：支付宝 + * 2：微信 + * 6：其它 + +### 应答报文 + +PayRes 公用事业单位返回银行的缴费应答报文。 + +| 中文域名 | 标签名 | 长度 | 对应字段 | 说明 | +|---|---|---|---|---| +| 返回代码 | RespCode | 7 | | 缴费返回代码 | +| 返回说明 | RespMessage | 60 | | 缴费返回说明 | +| 客户编号 | billKey | char(35) | | 原样返回 | +| 机构编码 | companyId | Num(30) | | 原样返回 | +| 交易日期 | payDate | Num(14) | | 原样返回 | +| 缴费金额 | payAmount | Number(16,2) | | 原样返回 | + + + + +## 账单红冲 + +### 请求报文 + +PayInvalid 是从银行向公用事业单位发起的红冲缴费单信息的请求报文，只可红冲当天收费且未对账交易，红冲成功后银行需发起自动退款。 + +**请求接口：** `/api/app/payInvalid/payInvalid` + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|---|---|---|---|---| +| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 | +| 交易日期 | payDate | char(30) | | 交易日期 | +| 红冲流水号 | agencyBillNo | char(30) | | 缴费时的账单流水号 | +| 缴费金额 | payMoney | char(30) | | 缴费金额 | + +说明： + +* **交易日期：** YYYYMMDDHHMMSS，(支付缴费单时系统时间) + +### 应答报文 + +PayInvalidRes 是公用事业单位返回给银行的红冲缴费单信息的应答报文。 + +| 中文域名 | 标签名 | 长度 | 对应字段 | 约束条件 | 说明 | +|---|---|---|---|---|---| +| 返回代码 | RespCode | char(30) | | 必填 | 返回代码 | +| 返回说明 | RespMessage | char(30) | | 必填 | 返回说明 | +| 机构编码 | companyId | char(30) | | 必填 | 由水司软件方提供 | +| 交易日期 | payDate | char(30) | | | 交易日期 | +| 红冲流水号 | agencyBillNo | char(30) | | | 缴费时的账单流水号 | +| 缴费金额 | payMoney | char(30) | | | 缴费金额 | + + + + +## 对账文件上传 + +### 账单说明 + +银行每天日结后，进行批处理，自动生成和传送（通过 FTP 或 SFTP）对账文件给公用事业单位。 + +### 对账文件格式 + +对账文件为文本文件 txt 格式，编码格式为 UTF-8，包括明细行和汇总行。行内每个分项之间以“|”为分隔符。无交易数据时，对账文件有且只有一条汇总行。汇总行放在文件前面，定义如下: + +`交易笔数|总金额` + +明细行的定义如下： + +`交易日期|交易流水号|客户编号|缴费金额|二级渠道|交易类型` + +注释：对账文件内的交易流水号要与缴费时的流水号保持一致。 + +说明： + +1. **关于文件命名：** + T 日所有交易按收费单位生成 n 个对账文件，文件名：机构编码(companyId)_对账日期.txt，其中对账日期为交易当天日期非当前时间。 + 例如：某水司机构编码（companyId）为 yhcs_yh，则 2021 年 1 月 1 日对账文件：yhcs_yh_20210101.txt； +2. 文件中只含缴费成功的交易； +3. 缴费金额单位是分； +4. 交易类型：默认 0，客户编号查询，1 条形码查询; +5. 文件编码格式采用 UTF-8。 + + + + +### 对账接口 + +#### 对账说明 + +由代理收费公司每天日切后，进行批处理，自动生成和传送对账文件给公用事业单位。 + +#### 请求报文 + +PayCheck 代理收费向公用事业单位发起的缴费单对账的请求报文。 + +**请求接口：** `/api/app/payCeb/paymentCheck` + +| 中文域名 | 标签名 | 长度 | 约束条件 | 说明 | +|---|---|---|---|---| +| 机构编码 | companyId | char(30) | 必填 | 由水司软件方提供 | +| 对账日期 | payDate | char(8) | 必填 | 需要对账的日期，非实时日期 | +| 交易笔数 | payCount | char(8) | 必填 | 交易总笔数 | +| 交易总金额 | payMoney | char(10) | 必填 | 交易总金额到分 | +| 对账文件名 | fileName | Char(100) | 必填 | 见说明 | + +说明： + +* **对账文件名：** 机构编码(companyId)_对账日期.txt，其中对账日期为交易当天日期非当前时间。 +* **交易日期：** YYYYMMDDHHMMSS，(支付缴费单时系统时间) + +#### 应答报文 + +PayCheckRes 公用事业单位返回的缴费对账应答报文。 + +| 中文域名 | 标签名 | 长度 | 约束条件 | +|---|---|---|---| +| 返回代码 | RespCode | 7 | 缴费返回代码 | +| 返回说明 | RespMessage | 60 | 缴费返回说明 | +| 机构编码 | companyId | char(30) | 原样返回 | +| 交易日期 | payDate | char(14) | 原样返回 | +| 缴费金额 | payAmount | Number(16,2) | 原样返回 | + + + + +## 1.2 银行代扣 + +### 代扣签约 + +Signing 是从银行向公用事业单位发起的代扣签约信息的请求报文。 + +**请求接口：** `/api/app/bankWithholding/signing` + +| 中文域名 | 标签名 | 长度 | 对应字段 | 约束条件 | 说明 | +|---|---|---|---|---|---| +| 客户编号 | billKey | char(35) | Input1 | 必填 | 客户编号 | +| 机构编码 | companyId | char(30) | | 必填 | 由水司软件方提供 | +| 开户名称 | accountName | char(100) | | 必输 | 开户名称 | +| 开户账号 | accountNo | char(30) | | 必填 | 开户账号 | +| 开户行 | branchName | char(150) | | 必填 | 开户行 | +| 合同号 | contractNo | char(50) | | | 合同号 | +| 备用字段 | filed1 | char(100) | | | 预留字段 | +| 备用字段 | filed2 | char(100) | | | 预留字段 | +| 备用字段 | filed3 | char(100) | | | 预留字段 | + +### 应答报文 + +SigningRes 是公用事业单位返回给银行的查询应答报文。 + +| 中文域名 | 标签名 | 长度 | 对应字段 | 说明 | +|---|---|---|---|---| +| 返回代码 | RespCode | 7 | | 查询返回代码 | +| 返回说明 | RespMessage | 60 | | 查询返回说明 | +| 客户编号 | billKey | char(35) | | 原样返回 | +| 备用字段 | filed1 | char(100) | | 循环域 | +| 备用字段 | filed2 | char(100) | | 循环域 | +| 备用字段 | filed3 | char(100) | | 循环域 | + + + + +### 代扣解约 + +Termination 是从银行向公用事业单位发起的代扣解约信息的请求报文。 + +**请求地址：** `/api/app/bankWithholding/termination` + +| 中文域名 | 标签名 | 长度 | 对应字段 | 约束条件 | 说明 | +|---|---|---|---|---|---| +| 客户编号 | billKey | char(35) | Input1 | 必填 | 客户编号 | +| 机构编码 | companyId | char(30) | | 必填 | 由水司软件方提供 | +| 开户名称 | accountName | char(100) | | 必输 | 开户名称 | +| 开户账号 | accountNo | char(30) | | 必填 | 开户账号 | +| 开户行 | branchName | char(150) | | 必填 | 开户行 | +| 合同号 | contractNo | char(50) | | | | +| 备用字段 | filed1 | char(100) | | | 预留字段 | +| 备用字段 | filed2 | char(100) | | | 预留字段 | + + + diff --git a/docs/guides/NUOSHUITONG_DATABASE_DESIGN.md b/docs/guides/NUOSHUITONG_DATABASE_DESIGN.md new file mode 100644 index 0000000..87c6707 --- /dev/null +++ b/docs/guides/NUOSHUITONG_DATABASE_DESIGN.md @@ -0,0 +1,543 @@ +# 诺税通对接数据库设计草案 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 项目名称 | 福建水务营收系统 | +| 文档类型 | 外部平台对接数据库设计草案 | +| 对接平台 | 诺税通 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` 对齐，纳入正式专项设计口径 diff --git a/docs/guides/NUOSHUITONG_DDL_DRAFT.md b/docs/guides/NUOSHUITONG_DDL_DRAFT.md new file mode 100644 index 0000000..0675caa --- /dev/null +++ b/docs/guides/NUOSHUITONG_DDL_DRAFT.md @@ -0,0 +1,529 @@ +# 诺税通对接 DDL 草案 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 项目名称 | 福建水务营收系统 | +| 文档类型 | 外部平台对接 DDL 草案 | +| 对接平台 | 诺税通 saas | +| 适用范围 | 发票、红字单据、设备、库存、企业配置、平台日志 | +| 版本 | v1.0 | +| 日期 | 2026-03-24 | +| 状态 | 草案 | + +## 适用说明 + +本文档在 `docs/guides/NUOSHUITONG_DATABASE_DESIGN.md` 的基础上，进一步给出面向实现的 DDL 草案。当前以 PostgreSQL/MySQL 均可平滑迁移的通用 SQL 风格表达为主，重点用于： +- 明确核心表字段结构 +- 明确主键、唯一约束与索引建议 +- 为后续纳入正式数据库设计主文档提供输入 + +## 使用约定 + +- 主键统一使用 `bigint` +- 金额统一使用 `decimal(18,2)` +- 数量/单价类字段视场景使用 `decimal(18,6)` +- 状态类字段统一使用 `varchar(32)` +- URL 字段统一预留 `varchar(1024)` +- 长报文、原始回调、请求响应体统一使用 `text` / `longtext` + +## DDL 草案 + +## `ns_invoice` 发票主表 + +```sql +CREATE TABLE ns_invoice ( + id BIGINT PRIMARY KEY, + sys_request_no VARCHAR(64) NOT NULL, + order_no VARCHAR(64), + source_business_type VARCHAR(32), + source_business_id VARCHAR(64), + platform_invoice_serial_num VARCHAR(64), + invoice_id VARCHAR(64), + invoice_code VARCHAR(32), + invoice_no VARCHAR(32), + all_electronic_invoice_no VARCHAR(64), + seller_tax_no VARCHAR(32) NOT NULL, + 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) NOT NULL, + 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), + ofd_url VARCHAR(1024), + image_url VARCHAR(1024), + paper_pdf_url VARCHAR(1024), + 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, + latest_result VARCHAR(1000), + latest_error VARCHAR(1000), + try_count INT, + last_try_time DATETIME, + next_try_time DATETIME, + created_at DATETIME NOT NULL, + updated_at DATETIME NOT NULL, + created_by VARCHAR(64), + updated_by VARCHAR(64) +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_invoice + ADD CONSTRAINT uk_ns_invoice_sys_request_no UNIQUE (sys_request_no); + +CREATE UNIQUE INDEX uk_ns_invoice_platform_serial_num + ON ns_invoice (platform_invoice_serial_num); + +CREATE INDEX idx_ns_invoice_order_no + ON ns_invoice (order_no); + +CREATE INDEX idx_ns_invoice_status + ON ns_invoice (request_status, invoice_status, delivery_status); + +CREATE INDEX idx_ns_invoice_seller_tax_no + ON ns_invoice (seller_tax_no); + +CREATE INDEX idx_ns_invoice_invoice_time + ON ns_invoice (invoice_time); + +CREATE INDEX idx_ns_invoice_next_try_time + ON ns_invoice (next_try_time); +``` + +## `ns_invoice_item` 发票明细表 + +```sql +CREATE TABLE ns_invoice_item ( + id BIGINT PRIMARY KEY, + invoice_id BIGINT NOT NULL, + line_no INT NOT NULL, + goods_name VARCHAR(255) NOT NULL, + 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 NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_invoice_item + ADD CONSTRAINT fk_ns_invoice_item_invoice + FOREIGN KEY (invoice_id) REFERENCES ns_invoice(id); + +CREATE UNIQUE INDEX uk_ns_invoice_item_invoice_line + ON ns_invoice_item (invoice_id, line_no); + +CREATE INDEX idx_ns_invoice_item_invoice_id + ON ns_invoice_item (invoice_id); +``` + +## `ns_invoice_delivery` 发票交付记录表 + +```sql +CREATE TABLE ns_invoice_delivery ( + id BIGINT PRIMARY KEY, + invoice_id BIGINT NOT NULL, + delivery_type VARCHAR(16) NOT NULL, + delivery_target VARCHAR(256) NOT NULL, + cc_target VARCHAR(512), + delivery_status VARCHAR(32) NOT NULL, + delivery_message VARCHAR(1000), + delivery_attempt_no INT NOT NULL, + is_retry SMALLINT NOT NULL, + response_code VARCHAR(32), + response_body TEXT, + delivery_time DATETIME, + created_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_invoice_delivery + ADD CONSTRAINT fk_ns_invoice_delivery_invoice + FOREIGN KEY (invoice_id) REFERENCES ns_invoice(id); + +CREATE INDEX idx_ns_invoice_delivery_invoice_id + ON ns_invoice_delivery (invoice_id); + +CREATE INDEX idx_ns_invoice_delivery_status + ON ns_invoice_delivery (delivery_status, delivery_time); +``` + +## `ns_invoice_reversal` 发票逆向处理表 + +```sql +CREATE TABLE ns_invoice_reversal ( + id BIGINT PRIMARY KEY, + invoice_id BIGINT NOT NULL, + reversal_type VARCHAR(32) NOT NULL, + source_invoice_code VARCHAR(32), + source_invoice_no VARCHAR(32), + invalid_reason VARCHAR(32), + specific_reason VARCHAR(500), + request_status VARCHAR(32) NOT NULL, + reversal_status VARCHAR(32), + platform_result_code VARCHAR(32), + platform_result_msg VARCHAR(1000), + target_invoice_id BIGINT, + created_at DATETIME NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_invoice_reversal + ADD CONSTRAINT fk_ns_invoice_reversal_invoice + FOREIGN KEY (invoice_id) REFERENCES ns_invoice(id); + +CREATE INDEX idx_ns_invoice_reversal_invoice_id + ON ns_invoice_reversal (invoice_id); + +CREATE INDEX idx_ns_invoice_reversal_status + ON ns_invoice_reversal (request_status, reversal_status); +``` + +## `ns_red_document` 红字单据主表 + +```sql +CREATE TABLE ns_red_document ( + id BIGINT PRIMARY KEY, + invoice_id BIGINT, + document_type VARCHAR(16) NOT NULL, + bill_no VARCHAR(64), + bill_id VARCHAR(64), + bill_info_no VARCHAR(64), + bill_confirm_no VARCHAR(64), + bill_uuid VARCHAR(64), + 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), + callback_status VARCHAR(32), + last_sync_time DATETIME, + created_at DATETIME NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_red_document + ADD CONSTRAINT fk_ns_red_document_invoice + FOREIGN KEY (invoice_id) REFERENCES ns_invoice(id); + +CREATE UNIQUE INDEX uk_ns_red_document_bill_no + ON ns_red_document (bill_no); + +CREATE UNIQUE INDEX uk_ns_red_document_bill_id + ON ns_red_document (bill_id); + +CREATE INDEX idx_ns_red_document_invoice_id + ON ns_red_document (invoice_id); + +CREATE INDEX idx_ns_red_document_status + ON ns_red_document (document_type, bill_status, open_status); +``` + +## `ns_red_document_item` 红字单据明细表 + +```sql +CREATE TABLE ns_red_document_item ( + id BIGINT PRIMARY KEY, + red_document_id BIGINT NOT NULL, + line_no INT NOT NULL, + 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 NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_red_document_item + ADD CONSTRAINT fk_ns_red_document_item_main + FOREIGN KEY (red_document_id) REFERENCES ns_red_document(id); + +CREATE UNIQUE INDEX uk_ns_red_document_item_line + ON ns_red_document_item (red_document_id, line_no); +``` + +## `ns_billing_device` 开票设备表 + +```sql +CREATE TABLE ns_billing_device ( + id BIGINT PRIMARY KEY, + tax_num VARCHAR(32) NOT NULL, + company_id VARCHAR(64), + 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), + device_status VARCHAR(32) NOT NULL, + 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 NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +CREATE UNIQUE INDEX uk_ns_billing_device_tax_ext_machine + ON ns_billing_device (tax_num, extension_num, machine_num); + +CREATE INDEX idx_ns_billing_device_tax_num + ON ns_billing_device (tax_num); + +CREATE INDEX idx_ns_billing_device_status + ON ns_billing_device (device_status, report_tax_status, clear_card_status); +``` + +## `ns_invoice_stock_snapshot` 发票库存快照表 + +```sql +CREATE TABLE ns_invoice_stock_snapshot ( + id BIGINT PRIMARY KEY, + device_id BIGINT, + seller_tax_no VARCHAR(32) NOT NULL, + 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) NOT NULL, + snapshot_time DATETIME NOT NULL, + created_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +ALTER TABLE ns_invoice_stock_snapshot + ADD CONSTRAINT fk_ns_invoice_stock_device + FOREIGN KEY (device_id) REFERENCES ns_billing_device(id); + +CREATE INDEX idx_ns_stock_device_time + ON ns_invoice_stock_snapshot (device_id, snapshot_time); + +CREATE INDEX idx_ns_stock_tax_line_time + ON ns_invoice_stock_snapshot (seller_tax_no, invoice_line, snapshot_time); +``` + +## `ns_enterprise_billing_config` 企业开票配置表 + +```sql +CREATE TABLE ns_enterprise_billing_config ( + id BIGINT PRIMARY KEY, + tax_num VARCHAR(32) NOT NULL, + company_id VARCHAR(64), + 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 NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +CREATE UNIQUE INDEX uk_ns_enterprise_billing_config_tax_num + ON ns_enterprise_billing_config (tax_num); +``` + +## `ns_platform_event_log` 平台回调事件表 + +```sql +CREATE TABLE ns_platform_event_log ( + id BIGINT PRIMARY KEY, + event_type VARCHAR(32) NOT NULL, + event_key VARCHAR(128) NOT NULL, + seller_tax_no VARCHAR(32), + business_key VARCHAR(128), + payload_json TEXT NOT NULL, + process_status VARCHAR(32) NOT NULL, + process_message VARCHAR(1000), + processed_at DATETIME, + created_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +CREATE UNIQUE INDEX uk_ns_platform_event_log_event_key + ON ns_platform_event_log (event_key); + +CREATE INDEX idx_ns_platform_event_log_type_status + ON ns_platform_event_log (event_type, process_status); +``` + +## `ns_platform_request_log` 平台请求响应日志表 + +```sql +CREATE TABLE ns_platform_request_log ( + id BIGINT PRIMARY KEY, + request_id VARCHAR(64) NOT NULL, + business_type VARCHAR(32), + business_id VARCHAR(64), + method_name VARCHAR(128), + request_headers_masked TEXT, + request_body TEXT, + response_body TEXT, + response_code VARCHAR(32), + success_flag SMALLINT, + error_message VARCHAR(1000), + created_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +CREATE UNIQUE INDEX uk_ns_platform_request_log_request_id + ON ns_platform_request_log (request_id); + +CREATE INDEX idx_ns_platform_request_log_business + ON ns_platform_request_log (business_type, business_id); + +CREATE INDEX idx_ns_platform_request_log_method_name + ON ns_platform_request_log (method_name); +``` + +## `ns_config_dictionary_cache` 配置字典缓存表（可选） + +```sql +CREATE TABLE ns_config_dictionary_cache ( + id BIGINT PRIMARY KEY, + dict_type VARCHAR(64) NOT NULL, + dict_key VARCHAR(128) NOT NULL, + dict_name VARCHAR(255), + company_id VARCHAR(64), + company_name VARCHAR(255), + extra_json TEXT, + last_sync_time DATETIME, + created_at DATETIME NOT NULL, + updated_at DATETIME NOT NULL +); +``` + +### 约束与索引建议 + +```sql +CREATE UNIQUE INDEX uk_ns_config_dictionary_cache_type_key + ON ns_config_dictionary_cache (dict_type, dict_key); + +CREATE INDEX idx_ns_config_dictionary_cache_type + ON ns_config_dictionary_cache (dict_type); +``` + +## 首期最小实施 DDL 建议 + +若以“最小可用”为目标，建议优先建以下 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` + +## 后续建议 + +建议在此基础上继续完成： +- 字段注释 SQL 草案 +- 状态码 / 枚举字典与字段注释联动 +- PostgreSQL 16 / openGauss 方言适配版本 +- 与 `docs/design/03_Technical_Design/01_Database_Design.md` 的正式章节对齐 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/01_概述与接入约定.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/01_概述与接入约定.md new file mode 100644 index 0000000..dca12a8 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/01_概述与接入约定.md @@ -0,0 +1,53 @@ +--- +title: 概述与接入约定 +aliases: + - 概述与接入约定 + - 诺税通概述与接入约定 + - 概述与接入约定索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 概述与接入约定 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [源文档封面与概述](01_概述与接入约定.md#源文档封面与概述) +- [交互说明](01_概述与接入约定.md#交互说明) + +## 使用说明 + +- 本分组保留为概览页，适合作为首次阅读入口。 +- 详细接口请从其他分组或总索引进入。 + +--- + +## 源文档封面与概述 + +# 概述 + +本文档定义了诺税通-销项服务面向第三方系统的数据协议接口，主要包括：开票请求接口、开票结果查询接口、开票结果回传等接口。 + +# 技术规范 + +## 交互说明 + + +本文档提供的接口均为post请求方式的HTTP接口，参数均以在消息主体body中以application/json方式提交，即请求头中Content-Type需配置为“application/json;charset=utf-8”。 + +说明：限定的最大长度为字符个数（一个汉字或全角符号算两个字符），最大长度中的带小数点（.）的，表示该字段只支持数值以不带千位分隔符的十进制浮点数表示，限定总长度和最大小数位，如16.2表示为-9999999999999.99到9999999999999.99的数。 + +# 接口列表 + diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/02_开票主链路.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/02_开票主链路.md new file mode 100644 index 0000000..df179d8 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/02_开票主链路.md @@ -0,0 +1,37 @@ +--- +title: 开票主链路 +aliases: + - 开票主链路 + - 诺税通开票主链路 + - 开票主链路索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 开票主链路 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/开票请求接口|开票请求接口]] +- [[interfaces/开票结果查询接口|开票结果查询接口]] +- [[interfaces/开票结果回传|开票结果回传]] +- [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]] +- [[interfaces/发票列表查询接口|发票列表查询接口]] +- [[interfaces/发票交付|发票交付]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/03_作废重开与冲红.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/03_作废重开与冲红.md new file mode 100644 index 0000000..1d4e487 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/03_作废重开与冲红.md @@ -0,0 +1,37 @@ +--- +title: 作废重开与冲红 +aliases: + - 作废重开与冲红 + - 诺税通作废重开与冲红 + - 作废重开与冲红索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 作废重开与冲红 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/发票作废申请接口|发票作废申请接口]] +- [[interfaces/发票重开接口|发票重开接口]] +- [[interfaces/快捷冲红接口|快捷冲红接口]] +- [[interfaces/空白发票作废申请|空白发票作废申请]] +- [[interfaces/蓝字发票剩余可冲红的金额_税额查询接口|蓝字发票剩余可冲红的金额、税额查询接口]] +- [[interfaces/获取关联发票接口|获取关联发票接口]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/04_红字信息表.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/04_红字信息表.md new file mode 100644 index 0000000..d49daba --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/04_红字信息表.md @@ -0,0 +1,37 @@ +--- +title: 红字信息表 +aliases: + - 红字信息表 + - 诺税通红字信息表 + - 红字信息表索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/红字信息表申请接口_不支持拆分_不推荐使用|红字信息表申请接口（不支持拆分，不推荐使用）]] +- [[interfaces/红字信息表申请接口_支持拆分|红字信息表申请接口（支持拆分）]] +- [[interfaces/红字信息表下载接口|红字信息表下载接口]] +- [[interfaces/红字信息表查询接口|红字信息表查询接口]] +- [[interfaces/红字信息表撤销接口|红字信息表撤销接口]] +- [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/05_红字确认单.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/05_红字确认单.md new file mode 100644 index 0000000..a03e6ae --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/05_红字确认单.md @@ -0,0 +1,36 @@ +--- +title: 红字确认单 +aliases: + - 红字确认单 + - 诺税通红字确认单 + - 红字确认单索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字确认单 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/红字确认单申请接口|红字确认单申请接口]] +- [[interfaces/红字确认单下载接口|红字确认单下载接口]] +- [[interfaces/红字确认单查询接口|红字确认单查询接口]] +- [[interfaces/红字确认单确认接口|红字确认单确认接口]] +- [[interfaces/红字确认单撤销接口|红字确认单撤销接口]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/06_库存票源与打印.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/06_库存票源与打印.md new file mode 100644 index 0000000..eac0251 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/06_库存票源与打印.md @@ -0,0 +1,42 @@ +--- +title: 库存票源与打印 +aliases: + - 库存票源与打印 + - 诺税通库存票源与打印 + - 库存票源与打印索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 库存票源与打印 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/获取纸票打印编号接口|获取纸票打印编号接口]] +- [[interfaces/获取指定票种当前代码号码|获取指定票种当前代码号码]] +- [[interfaces/获取下一张发票号码代码接口_A9机柜|获取下一张发票号码代码接口（A9+机柜）]] +- [[interfaces/发票库存余量查询接口|发票库存余量查询接口]] +- [[interfaces/刷新获取开票设备实时发票库存接口|刷新获取开票设备实时发票库存接口]] +- [[interfaces/票源下载接口|票源下载接口]] +- [[interfaces/查询可下载发票库存列表接口|查询可下载发票库存列表接口]] +- [[interfaces/自定义票源下载接口|自定义票源下载接口]] +- [[interfaces/刷新可下载发票库存接口|刷新可下载发票库存接口]] +- [[interfaces/乐企查询数电库存接口|乐企查询数电库存接口]] +- [[interfaces/乐企数电发票库存申领接口|乐企数电发票库存申领接口]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/07_设备企业与配置.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/07_设备企业与配置.md new file mode 100644 index 0000000..f60f38e --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/07_设备企业与配置.md @@ -0,0 +1,41 @@ +--- +title: 设备企业与配置 +aliases: + - 设备企业与配置 + - 诺税通设备企业与配置 + - 设备企业与配置索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 设备企业与配置 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[08_车辆辅助与回传]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/企业设备状态查询接口|企业设备状态查询接口]] +- [[interfaces/企业设备查询接口|企业设备查询接口]] +- [[interfaces/创建开票设备接口|创建开票设备接口]] +- [[interfaces/新增_修改企业开票信息|新增/修改企业开票信息]] +- [[interfaces/录入自定义字段|录入自定义字段]] +- [[interfaces/批量获取信息转换配置接口|批量获取信息转换配置接口]] +- [[interfaces/批量获取备注配置信息接口|批量获取备注配置信息接口]] +- [[interfaces/根据业务标识查询对应值列表接口|根据业务标识查询对应值列表接口]] +- [[interfaces/获取查询数电登录认证_开票实名认证二维码|获取查询数电登录认证、开票实名认证二维码]] +- [[interfaces/登录扫码认证确认接口|登录扫码认证确认接口]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/08_车辆辅助与回传.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/08_车辆辅助与回传.md new file mode 100644 index 0000000..8d9e671 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/08_车辆辅助与回传.md @@ -0,0 +1,40 @@ +--- +title: 车辆辅助与回传 +aliases: + - 车辆辅助与回传 + - 诺税通车辆辅助与回传 + - 车辆辅助与回传索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 车辆辅助与回传 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[09_专项能力]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/收票入库接口_本地提取发票|收票入库接口（本地提取发票）]] +- [[interfaces/创建_查询企业车架号_合格证状态接口|创建/查询企业车架号、合格证状态接口]] +- [[interfaces/企业车架号等信息查询结果回传接口|企业车架号等信息查询结果回传接口]] +- [[interfaces/查询获取车架号是否可开票结果接口|查询获取车架号是否可开票结果接口]] +- [[interfaces/获取DAT加密包文件流接口|获取DAT加密包文件流接口]] +- [[interfaces/更新发票票据关联状态接口|更新发票票据关联状态接口]] +- [[interfaces/删除发票信息接口|删除发票信息接口]] +- [[interfaces/审核开票删除回传接口|审核开票删除回传接口]] +- [[interfaces/批量查询发票xmlUrl接口|批量查询发票xmlUrl接口]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/09_专项能力.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/09_专项能力.md new file mode 100644 index 0000000..4289c9b --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/09_专项能力.md @@ -0,0 +1,40 @@ +--- +title: 专项能力 +aliases: + - 专项能力 + - 诺税通专项能力 + - 专项能力索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 专项能力 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[10_附录_通用状态码]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [[interfaces/查询成品油库存列表接口|查询成品油库存列表接口]] +- [[interfaces/成品油库存下载接口|成品油库存下载接口]] +- [[interfaces/刷新获取税盘实时成品油库存接口|刷新获取税盘实时成品油库存接口]] +- [[interfaces/抄报清卡|抄报清卡]] +- [[interfaces/授信额度刷新接口|授信额度刷新接口]] +- [[interfaces/查询授信额度数据|查询授信额度数据]] +- [[interfaces/乐企授信额度下载_退回接口|乐企授信额度下载/退回接口]] +- [[interfaces/乐企授信额度更新有效期接口|乐企授信额度更新有效期接口]] +- [[interfaces/获取发票勾选入账状态接口|获取发票勾选入账状态接口]] + +## 使用说明 + +- 点击上方单接口页进入正文。 +- 适合在 Obsidian 中作为专题 MOC 使用。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/10_附录_通用状态码.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/10_附录_通用状态码.md new file mode 100644 index 0000000..4f10918 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/10_附录_通用状态码.md @@ -0,0 +1,41 @@ +--- +title: 附录：通用状态码 +aliases: + - 附录：通用状态码 + - 诺税通附录：通用状态码 + - 附录：通用状态码索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 附录：通用状态码 + +> [!info] 导航 +> 总索引：[[README]] +> 同级分组：[[01_概述与接入约定]] · [[02_开票主链路]] · [[03_作废重开与冲红]] · [[04_红字信息表]] · [[05_红字确认单]] · [[06_库存票源与打印]] · [[07_设备企业与配置]] · [[08_车辆辅助与回传]] · [[09_专项能力]] + +> [!abstract] 说明 +> 本页作为 Obsidian MOC，仅保留分组导航与接口入口；接口正文已下沉为单接口一页。 + +## 接口入口 + +- [通用状态码说明](10_附录_通用状态码.md#通用状态码说明) + +## 使用说明 + +- 本分组保留附录全文，便于各接口页统一回查状态码。 + +## 通用状态码说明 + +| | | +|:----------:|:--------------------:| +| **状态码** | **描述** | +| 200 | 成功 | +| 501 | 请求异常或服务器异常 | + +更多错误码描述可见message字段。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/11_枚举清单.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/11_枚举清单.md new file mode 100644 index 0000000..fba9fa9 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/11_枚举清单.md @@ -0,0 +1,147 @@ +--- +title: 诺税通接口枚举清单 +aliases: + - 诺税通枚举清单 + - 诺税通参数枚举索引 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - enum-index +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: extracted-summary +--- + +# 诺税通接口枚举清单 + +> [!abstract] 说明 +> 本文从诺税通销项服务接口规范中提取各接口内出现的参数枚举、状态枚举与布尔/标志位语义，便于实施时统一核对。 +> 原始接口正文请进入 `interfaces/` 下的单接口页查看。 + +## 开票主链路 + +### [[interfaces/开票请求接口|开票请求接口]] + +- `invoiceType`：1:蓝票；2:红票 | 2 +- `invoiceLine`：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | 2 +- `remark`：j：机动车发票时，备注需注明：“一车一票”否则接口会自动添加该文案 | 备注，（注意：不同开票服务器类型支持的备注长度不同，请在提交前做好确认） | 数电电票：200(中文计算一位) 其他发票：230(中文计算两位) +- `notifyType`：-1:不推送；0:邮箱；1:手机(默认)；2:邮箱、手机 | 2 +- `listFlag`：0:非清单；1:清单，纸票超过8行自动转成清单，电票无清单概念，默认都传0 | 2 +- `substituteFlag`：0:非代开；1:代开 +- `withTaxFlag`：0:不含税,1:含税 | 2 +- `favouredPolicyFlag`：0:不使用；1:使用 数电发票时为空，仅传入优惠政策编码即可 | 2 +- `zeroRateFlag`：1:免税；2:不征税；3:普通零税率；favouredPolicyFlag:0 zeroRateFlag:3 favouredPolicyName: 免税时，对应传值： favouredPolicyFlag:1 zeroRateFlag:1 favouredPolicyName:“免税” 不征税，对应传值： favouredPolicyFlag:1 zeroRateFlag:2 favouredPolicyName:“不征税” | 2 + +### [[interfaces/开票结果查询接口|开票结果查询接口]] + +- `status`：0:开票中1:开票完成2:开票失败3:发票生成 | 2 +- `invoiceLine`：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | 2 +- `productOilFlag`：0:非成品油；1:成品油 | 2 +- `vehicleFlag`：0：非机动车；1：机动车 | 2 +- `listFlag`：0:非清单，1:清单 | 2 +- `invalidReason`：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） | 1 +- `withTaxFlag`：0:不含税；1:含税 | 2 +- `detailType`：0:正常行；1:折扣行；2:被折扣行 | 2 +- `favouredPolicyFlag`：0:不使用；1:使用 | 2 +- `zeroRateFlag`：1:免税；2:不征税；3:普通零税率 | 2 + +### [[interfaces/开票结果回传|开票结果回传]] + +- `successFlag`：True:开票成功；false：开票失败 | 1 +- `vehicleFlag`：0：非机动车；1：机动车 | 2 +- `invoiceStatus`：1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功 +- `invoiceLine`：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j:机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) 仅开票成功会返回 | 2 +- `relatedState`：0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败) | +- `invalidReason`：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） | 1 + +### [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]] + +- `invoiceLine`：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | 1 +- `productOilFlag`：0:非成品油；1:成品油 +- `vehicleFlag`：0：非机动车；1：机动车 | 2 +- `listFlag`：0：非清单；1：清单 +- `invoiceStatus`：1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功 +- `relatedState`：0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败) | +- `invalidReason`：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） | 1 +- `withTaxFlag`：1:含税；0:不含税 +- `detailType`：0:正常行；1:折扣行；2:被扣行 +- `zeroRateFlag`：1:免税；2:不征税；3:普通零税率 +- `favouredPolicyFlag`：0:不使用；1:使用 + +### [[interfaces/发票列表查询接口|发票列表查询接口]] + +- `status`：0:开票中1:开票完成2:开票失败3:发票生成 | 2 +- `invoiceLine`：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | 2 +- `productOilFlag`：0:非成品油；1:成品油 | 2 +- `vehicleFlag`：0：非机动车；1：机动车 | 2 +- `listFlag`：0:非清单，1:清单 | 2 +- `invalidReason`：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） | 1 +- `withTaxFlag`：0:不含税；1:含税 | 2 +- `detailType`：0:正常行；1:折扣行；2:被折扣行 | 2 +- `favouredPolicyFlag`：0:不使用；1:使用 | 2 +- `zeroRateFlag`：1:免税；2:不征税；3:普通零税率 | 2 + +## 作废重开与冲红 + +### [[interfaces/快捷冲红接口|快捷冲红接口]] + +- `fastRedType`：1:数电发票快捷冲红(数电发票必传1) | 1 +- `fastRedType`：1:数电快捷冲红(数电发票必传1) | 1 + +## 红字信息表 + +### [[interfaces/红字信息表申请接口_不支持拆分_不推荐使用|红字信息表申请接口（不支持拆分，不推荐使用）]] + +- `billType`：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） 默认为：0正常 注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单） 若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填 + +### [[interfaces/红字信息表申请接口_支持拆分|红字信息表申请接口（支持拆分）]] + +- `billType`：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） 默认为：0正常 注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单） 若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填 + +### [[interfaces/红字信息表查询接口|红字信息表查询接口]] + +- `billType`：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回 4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） | 1 +- `taxRate`：0:一票一税率 1:一票多税率) | 1 +- `billStatus`：-1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销) | 2 + +### [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]] + +- `backType`：1: 红字信息表 2：红字确认单 | 2 +- `billType`：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回 4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） | 1 +- `billStatus`：-1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销 -2:删除成功) | 2 +- `backType`：1: 红字信息表 2：红字确认单 | 2 +- `openStatus`：0：未开具 1：已开具 | 2 +- `blueInvoiceLine`：bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 | 5 + +## 红字确认单 + +### [[interfaces/红字确认单申请接口|红字确认单申请接口]] + +- `blueInvoiceLine`：bs:数电专票(电子), pc:数电普票(电子)， es:数电专票(纸质)；ec:数电普票(纸质)， p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 | 5 +- `withTaxFlag`：0:不含税,1:含税 | 1 +- `zeroRateFlag`：1:免税；2:不征税；3:普通零税率 | 2 + +### [[interfaces/红字确认单下载接口|红字确认单下载接口]] + +- `billStatus`：1：我是购买方时，必填 确认单状态，0.待确认 1.已确认 2.已过期 3.销方否认 4.已撤销 | 4 + +### [[interfaces/红字确认单查询接口|红字确认单查询接口]] + +- `openStatus`：0：未开具 1：已开具 | 2 +- `blueInvoiceLine`：bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 | 5 + +## 设备企业与配置 + +### [[interfaces/创建开票设备接口|创建开票设备接口]] + +- `serverType`：1:C48, 11:诺诺开票, 14：A9, 15:四川税局代开, 17:诺诺机柜, 18:税控服务器, 20:单机版, 22:数电发票开票模式（通用版）, 24:数电发票开票模式（单机版）, 25:数电发票开票模式（机柜版） 数电单机版和机柜版暂只支持半本地环境 | 4 +- `invoiceTypelist`：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | - + +## 车辆辅助与回传 + +### [[interfaces/收票入库接口_本地提取发票|收票入库接口（本地提取发票）]] + +- `invoiceType`：1：蓝票；2：红票 +- `withTaxFlag`：0:不含税,1:含税 + diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/12_标准枚举字典.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/12_标准枚举字典.md new file mode 100644 index 0000000..8e0faeb --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/12_标准枚举字典.md @@ -0,0 +1,341 @@ +--- +title: 诺税通标准枚举字典 +aliases: + - 诺税通枚举字典 + - 诺税通字段级枚举表 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - enum-dictionary +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: normalized-from-enum-index +--- + +# 诺税通标准枚举字典 + +> [!abstract] 说明 +> 本文对 `11_枚举清单.md` 中跨接口重复出现的枚举字段进行字段级归并，便于实施时统一理解与复用。 +> 若同一字段在不同接口中存在补充说明或口径差异，均在“来源接口”中保留。 + +## 快速导航 + +- [[#`invoiceLine`|`invoiceLine`]] +- [[#`invoiceType`|`invoiceType`]] +- [[#`status`|`status`]] +- [[#`invoiceStatus`|`invoiceStatus`]] +- [[#`billStatus`|`billStatus`]] +- [[#`billType`|`billType`]] +- [[#`withTaxFlag`|`withTaxFlag`]] +- [[#`listFlag`|`listFlag`]] +- [[#`detailType`|`detailType`]] +- [[#`invalidReason`|`invalidReason`]] +- [[#`notifyType`|`notifyType`]] +- [[#`vehicleFlag`|`vehicleFlag`]] +- [[#`productOilFlag`|`productOilFlag`]] +- [[#`zeroRateFlag`|`zeroRateFlag`]] +- [[#`favouredPolicyFlag`|`favouredPolicyFlag`]] +- [[#`backType`|`backType`]] +- [[#`openStatus`|`openStatus`]] +- [[#`serverType`|`serverType`]] +- [[#`fastRedType`|`fastRedType`]] +- [[#`taxRate`|`taxRate`]] +- [[#`relatedState`|`relatedState`]] +- [[#`successFlag`|`successFlag`]] +- [[#`substituteFlag`|`substituteFlag`]] +- [[#`blueInvoiceLine`|`blueInvoiceLine`]] +- [[#`invoiceTypelist`|`invoiceTypelist`]] +- [[#`remark`|`remark`]] + +## `invoiceLine` + +> [!summary] 标准口径 +> - p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) +> - p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) +> - p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j:机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) 仅开票成功会返回 +> - p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) +- **开票主链路 / [[interfaces/开票结果回传|开票结果回传]]**：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j:机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) 仅开票成功会返回 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) + +## `invoiceType` + +> [!summary] 标准口径 +> - 1:蓝票；2:红票 +> - 1：蓝票；2：红票 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：1:蓝票；2:红票 +- **车辆辅助与回传 / [[interfaces/收票入库接口_本地提取发票|收票入库接口（本地提取发票）]]**：1：蓝票；2：红票 + +## `status` + +> [!summary] 标准口径 +> - 0:开票中1:开票完成2:开票失败3:发票生成 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0:开票中1:开票完成2:开票失败3:发票生成 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0:开票中1:开票完成2:开票失败3:发票生成 + +## `invoiceStatus` + +> [!summary] 标准口径 +> - 1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果回传|开票结果回传]]**：1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功 + +## `billStatus` + +> [!summary] 标准口径 +> - -1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销) +> - -1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销 -2:删除成功) +> - 1：我是购买方时，必填 确认单状态，0.待确认 1.已确认 2.已过期 3.销方否认 4.已撤销 + +### 来源接口 + +- **红字信息表 / [[interfaces/红字信息表查询接口|红字信息表查询接口]]**：-1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销) +- **红字信息表 / [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]]**：-1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销 -2:删除成功) +- **红字确认单 / [[interfaces/红字确认单下载接口|红字确认单下载接口]]**：1：我是购买方时，必填 确认单状态，0.待确认 1.已确认 2.已过期 3.销方否认 4.已撤销 + +## `billType` + +> [!summary] 标准口径 +> - 0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） 默认为：0正常 注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单） 若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填 +> - 0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回 4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） + +### 来源接口 + +- **红字信息表 / [[interfaces/红字信息表申请接口_不支持拆分_不推荐使用|红字信息表申请接口（不支持拆分，不推荐使用）]]**：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） 默认为：0正常 注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单） 若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填 +- **红字信息表 / [[interfaces/红字信息表申请接口_支持拆分|红字信息表申请接口（支持拆分）]]**：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） 默认为：0正常 注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单） 若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填 +- **红字信息表 / [[interfaces/红字信息表查询接口|红字信息表查询接口]]**：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回 4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） +- **红字信息表 / [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]]**：0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回 4、矿产品类专用信息表（涉及销售数量和金额变更） 5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动） + +## `withTaxFlag` + +> [!summary] 标准口径 +> - 0:不含税,1:含税 +> - 0:不含税；1:含税 +> - 1:含税；0:不含税 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：0:不含税,1:含税 +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0:不含税；1:含税 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：1:含税；0:不含税 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0:不含税；1:含税 +- **红字确认单 / [[interfaces/红字确认单申请接口|红字确认单申请接口]]**：0:不含税,1:含税 +- **车辆辅助与回传 / [[interfaces/收票入库接口_本地提取发票|收票入库接口（本地提取发票）]]**：0:不含税,1:含税 + +## `listFlag` + +> [!summary] 标准口径 +> - 0:非清单；1:清单，纸票超过8行自动转成清单，电票无清单概念，默认都传0 +> - 0:非清单，1:清单 +> - 0：非清单；1：清单 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：0:非清单；1:清单，纸票超过8行自动转成清单，电票无清单概念，默认都传0 +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0:非清单，1:清单 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：0：非清单；1：清单 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0:非清单，1:清单 + +## `detailType` + +> [!summary] 标准口径 +> - 0:正常行；1:折扣行；2:被折扣行 +> - 0:正常行；1:折扣行；2:被扣行 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0:正常行；1:折扣行；2:被折扣行 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：0:正常行；1:折扣行；2:被扣行 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0:正常行；1:折扣行；2:被折扣行 + +## `invalidReason` + +> [!summary] 标准口径 +> - 1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） +- **开票主链路 / [[interfaces/开票结果回传|开票结果回传]]**：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：1:销货退回；2:开票有误；3:服务中止；4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回） + +## `notifyType` + +> [!summary] 标准口径 +> - -1:不推送；0:邮箱；1:手机(默认)；2:邮箱、手机 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：-1:不推送；0:邮箱；1:手机(默认)；2:邮箱、手机 + +## `vehicleFlag` + +> [!summary] 标准口径 +> - 0：非机动车；1：机动车 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0：非机动车；1：机动车 +- **开票主链路 / [[interfaces/开票结果回传|开票结果回传]]**：0：非机动车；1：机动车 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：0：非机动车；1：机动车 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0：非机动车；1：机动车 + +## `productOilFlag` + +> [!summary] 标准口径 +> - 0:非成品油；1:成品油 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0:非成品油；1:成品油 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：0:非成品油；1:成品油 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0:非成品油；1:成品油 + +## `zeroRateFlag` + +> [!summary] 标准口径 +> - 1:免税；2:不征税；3:普通零税率；favouredPolicyFlag:0 zeroRateFlag:3 favouredPolicyName: 免税时，对应传值： favouredPolicyFlag:1 zeroRateFlag:1 favouredPolicyName:“免税” 不征税，对应传值： favouredPolicyFlag:1 zeroRateFlag:2 favouredPolicyName:“不征税” +> - 1:免税；2:不征税；3:普通零税率 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：1:免税；2:不征税；3:普通零税率；favouredPolicyFlag:0 zeroRateFlag:3 favouredPolicyName: 免税时，对应传值： favouredPolicyFlag:1 zeroRateFlag:1 favouredPolicyName:“免税” 不征税，对应传值： favouredPolicyFlag:1 zeroRateFlag:2 favouredPolicyName:“不征税” +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：1:免税；2:不征税；3:普通零税率 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：1:免税；2:不征税；3:普通零税率 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：1:免税；2:不征税；3:普通零税率 +- **红字确认单 / [[interfaces/红字确认单申请接口|红字确认单申请接口]]**：1:免税；2:不征税；3:普通零税率 + +## `favouredPolicyFlag` + +> [!summary] 标准口径 +> - 0:不使用；1:使用 数电发票时为空，仅传入优惠政策编码即可 +> - 0:不使用；1:使用 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：0:不使用；1:使用 数电发票时为空，仅传入优惠政策编码即可 +- **开票主链路 / [[interfaces/开票结果查询接口|开票结果查询接口]]**：0:不使用；1:使用 +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：0:不使用；1:使用 +- **开票主链路 / [[interfaces/发票列表查询接口|发票列表查询接口]]**：0:不使用；1:使用 + +## `backType` + +> [!summary] 标准口径 +> - 1: 红字信息表 2：红字确认单 + +### 来源接口 + +- **红字信息表 / [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]]**：1: 红字信息表 2：红字确认单 + +## `openStatus` + +> [!summary] 标准口径 +> - 0：未开具 1：已开具 + +### 来源接口 + +- **红字信息表 / [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]]**：0：未开具 1：已开具 +- **红字确认单 / [[interfaces/红字确认单查询接口|红字确认单查询接口]]**：0：未开具 1：已开具 + +## `serverType` + +> [!summary] 标准口径 +> - 1:C48, 11:诺诺开票, 14：A9, 15:四川税局代开, 17:诺诺机柜, 18:税控服务器, 20:单机版, 22:数电发票开票模式（通用版）, 24:数电发票开票模式（单机版）, 25:数电发票开票模式（机柜版） 数电单机版和机柜版暂只支持半本地环境 + +### 来源接口 + +- **设备企业与配置 / [[interfaces/创建开票设备接口|创建开票设备接口]]**：1:C48, 11:诺诺开票, 14：A9, 15:四川税局代开, 17:诺诺机柜, 18:税控服务器, 20:单机版, 22:数电发票开票模式（通用版）, 24:数电发票开票模式（单机版）, 25:数电发票开票模式（机柜版） 数电单机版和机柜版暂只支持半本地环境 + +## `fastRedType` + +> [!summary] 标准口径 +> - 1:数电发票快捷冲红(数电发票必传1) +> - 1:数电快捷冲红(数电发票必传1) + +### 来源接口 + +- **作废重开与冲红 / [[interfaces/快捷冲红接口|快捷冲红接口]]**：1:数电快捷冲红(数电发票必传1) + +## `taxRate` + +> [!summary] 标准口径 +> - 0:一票一税率 1:一票多税率) + +### 来源接口 + +- **红字信息表 / [[interfaces/红字信息表查询接口|红字信息表查询接口]]**：0:一票一税率 1:一票多税率) + +## `relatedState` + +> [!summary] 标准口径 +> - 0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败) | + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果回传|开票结果回传]]**：0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败) | +- **开票主链路 / [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]]**：0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败) | + +## `successFlag` + +> [!summary] 标准口径 +> - True:开票成功；false：开票失败 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票结果回传|开票结果回传]]**：True:开票成功；false：开票失败 + +## `substituteFlag` + +> [!summary] 标准口径 +> - 0:非代开；1:代开 + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：0:非代开；1:代开 + +## `blueInvoiceLine` + +> [!summary] 标准口径 +> - bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 +> - bs:数电专票(电子), pc:数电普票(电子)， es:数电专票(纸质)；ec:数电普票(纸质)， p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 + +### 来源接口 + +- **红字信息表 / [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]]**：bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 +- **红字确认单 / [[interfaces/红字确认单申请接口|红字确认单申请接口]]**：bs:数电专票(电子), pc:数电普票(电子)， es:数电专票(纸质)；ec:数电普票(纸质)， p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 +- **红字确认单 / [[interfaces/红字确认单查询接口|红字确认单查询接口]]**：bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) p:电子增值税普通发票， c:增值税普通发票(纸票)， s:增值税专用发票， b:增值税电子专用发票 + +## `invoiceTypelist` + +> [!summary] 标准口径 +> - p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) + +### 来源接口 + +- **设备企业与配置 / [[interfaces/创建开票设备接口|创建开票设备接口]]**：p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) + +## `remark` + +> [!summary] 标准口径 +> - j：机动车发票时，备注需注明：“一车一票”否则接口会自动添加该文案 | 备注，（注意：不同开票服务器类型支持的备注长度不同，请在提交前做好确认） | 数电电票：200(中文计算一位) 其他发票：230(中文计算两位) + +### 来源接口 + +- **开票主链路 / [[interfaces/开票请求接口|开票请求接口]]**：j：机动车发票时，备注需注明：“一车一票”否则接口会自动添加该文案 | 备注，（注意：不同开票服务器类型支持的备注长度不同，请在提交前做好确认） | 数电电票：200(中文计算一位) 其他发票：230(中文计算两位) + diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/README.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/README.md new file mode 100644 index 0000000..f069341 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/README.md @@ -0,0 +1,130 @@ +--- +title: 诺税通销项服务接口规范索引 +aliases: + - 诺税通销项接口规范 + - 诺税通销项服务接口目录 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - moc +source_docx: ../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 诺税通销项服务接口规范索引 + +> [!abstract] 文档说明 +> 本目录为 `诺诺网-诺税通销项服务对外接口规范v1.3.18.docx` 的 Markdown 转换结果，已进一步拆分为“单接口一页”。 +> 适用于 Obsidian 检索、双链浏览与专题整理。 +> 原始来源：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 配套实施清单：[NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md](../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +## 分组导航 + +- [[01_概述与接入约定]] +- [[02_开票主链路]] +- [[03_作废重开与冲红]] +- [[04_红字信息表]] +- [[05_红字确认单]] +- [[06_库存票源与打印]] +- [[07_设备企业与配置]] +- [[08_车辆辅助与回传]] +- [[09_专项能力]] +- [[10_附录_通用状态码]] +- [[11_枚举清单]] +- [[12_标准枚举字典]] + +## 单接口索引 + +### 开票主链路 + +- [[interfaces/开票请求接口|开票请求接口]] +- [[interfaces/开票结果查询接口|开票结果查询接口]] +- [[interfaces/开票结果回传|开票结果回传]] +- [[interfaces/开票结果回传_含明细|开票结果回传（含明细）]] +- [[interfaces/发票列表查询接口|发票列表查询接口]] +- [[interfaces/发票交付|发票交付]] + +### 作废重开与冲红 + +- [[interfaces/发票作废申请接口|发票作废申请接口]] +- [[interfaces/发票重开接口|发票重开接口]] +- [[interfaces/获取关联发票接口|获取关联发票接口]] +- [[interfaces/快捷冲红接口|快捷冲红接口]] +- [[interfaces/空白发票作废申请|空白发票作废申请]] +- [[interfaces/蓝字发票剩余可冲红的金额_税额查询接口|蓝字发票剩余可冲红的金额、税额查询接口]] + +### 红字信息表 + +- [[interfaces/红字信息表申请接口_不支持拆分_不推荐使用|红字信息表申请接口（不支持拆分，不推荐使用）]] +- [[interfaces/红字信息表申请接口_支持拆分|红字信息表申请接口（支持拆分）]] +- [[interfaces/红字信息表下载接口|红字信息表下载接口]] +- [[interfaces/红字信息表查询接口|红字信息表查询接口]] +- [[interfaces/红字信息表撤销接口|红字信息表撤销接口]] +- [[interfaces/红字信息表_红字确认单回传|红字信息表/红字确认单回传]] + +### 红字确认单 + +- [[interfaces/红字确认单申请接口|红字确认单申请接口]] +- [[interfaces/红字确认单下载接口|红字确认单下载接口]] +- [[interfaces/红字确认单查询接口|红字确认单查询接口]] +- [[interfaces/红字确认单确认接口|红字确认单确认接口]] +- [[interfaces/红字确认单撤销接口|红字确认单撤销接口]] + +### 库存票源与打印 + +- [[interfaces/获取纸票打印编号接口|获取纸票打印编号接口]] +- [[interfaces/获取指定票种当前代码号码|获取指定票种当前代码号码]] +- [[interfaces/发票库存余量查询接口|发票库存余量查询接口]] +- [[interfaces/刷新获取开票设备实时发票库存接口|刷新获取开票设备实时发票库存接口]] +- [[interfaces/获取下一张发票号码代码接口_A9机柜|获取下一张发票号码代码接口（A9+机柜）]] +- [[interfaces/票源下载接口|票源下载接口]] +- [[interfaces/查询可下载发票库存列表接口|查询可下载发票库存列表接口]] +- [[interfaces/自定义票源下载接口|自定义票源下载接口]] +- [[interfaces/刷新可下载发票库存接口|刷新可下载发票库存接口]] +- [[interfaces/乐企查询数电库存接口|乐企查询数电库存接口]] +- [[interfaces/乐企数电发票库存申领接口|乐企数电发票库存申领接口]] + +### 设备企业与配置 + +- [[interfaces/企业设备状态查询接口|企业设备状态查询接口]] +- [[interfaces/新增_修改企业开票信息|新增/修改企业开票信息]] +- [[interfaces/批量获取信息转换配置接口|批量获取信息转换配置接口]] +- [[interfaces/批量获取备注配置信息接口|批量获取备注配置信息接口]] +- [[interfaces/根据业务标识查询对应值列表接口|根据业务标识查询对应值列表接口]] +- [[interfaces/企业设备查询接口|企业设备查询接口]] +- [[interfaces/创建开票设备接口|创建开票设备接口]] +- [[interfaces/录入自定义字段|录入自定义字段]] +- [[interfaces/获取查询数电登录认证_开票实名认证二维码|获取查询数电登录认证、开票实名认证二维码]] +- [[interfaces/登录扫码认证确认接口|登录扫码认证确认接口]] + +### 车辆辅助与回传 + +- [[interfaces/收票入库接口_本地提取发票|收票入库接口（本地提取发票）]] +- [[interfaces/创建_查询企业车架号_合格证状态接口|创建/查询企业车架号、合格证状态接口]] +- [[interfaces/企业车架号等信息查询结果回传接口|企业车架号等信息查询结果回传接口]] +- [[interfaces/获取DAT加密包文件流接口|获取DAT加密包文件流接口]] +- [[interfaces/更新发票票据关联状态接口|更新发票票据关联状态接口]] +- [[interfaces/查询获取车架号是否可开票结果接口|查询获取车架号是否可开票结果接口]] +- [[interfaces/删除发票信息接口|删除发票信息接口]] +- [[interfaces/审核开票删除回传接口|审核开票删除回传接口]] +- [[interfaces/批量查询发票xmlUrl接口|批量查询发票xmlUrl接口]] + +### 专项能力 + +- [[interfaces/查询成品油库存列表接口|查询成品油库存列表接口]] +- [[interfaces/成品油库存下载接口|成品油库存下载接口]] +- [[interfaces/刷新获取税盘实时成品油库存接口|刷新获取税盘实时成品油库存接口]] +- [[interfaces/抄报清卡|抄报清卡]] +- [[interfaces/授信额度刷新接口|授信额度刷新接口]] +- [[interfaces/查询授信额度数据|查询授信额度数据]] +- [[interfaces/乐企授信额度下载_退回接口|乐企授信额度下载/退回接口]] +- [[interfaces/乐企授信额度更新有效期接口|乐企授信额度更新有效期接口]] +- [[interfaces/获取发票勾选入账状态接口|获取发票勾选入账状态接口]] + +## 使用建议 + +- 先阅读 [[01_概述与接入约定]] 了解整体交互方式。 +- 再按业务主题进入分组 MOC，最终跳转到 `interfaces/` 下的单接口笔记。 +- 若需实施口径，请同步参照 `NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md`。 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企授信额度下载_退回接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企授信额度下载_退回接口.md new file mode 100644 index 0000000..9e6701a --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企授信额度下载_退回接口.md @@ -0,0 +1,106 @@ +--- +title: 乐企授信额度下载/退回接口 +aliases: + - 乐企授信额度下载/退回接口 + - 诺税通乐企授信额度下载/退回接口 + - 专项能力-乐企授信额度下载/退回接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 乐企授信额度下载/退回接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/creditQuota/downloadOrReturn.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 乐企授信额度下载/退回接口 + +### 接口说明 + +乐企模式授信额度下载\退回接口，调用该接口时，需保证对应企业税号查询过授信额度。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/creditQuota/downloadOrReturn.do | + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| taxNum | String | 是 | 需要查询的企业税号 | 企业税号 | 20 | +| amount | BigDecimal | 是 | 需要下载\退回的金额，只能为正数数字 | 处理额度 | (12,2) | +| type | Integer | 是 | 0:下载 1:退回 | 请求类型 | 1 | + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"amount": 100,

+

"type": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| vestPeriodBegin | Date | 是 | 2023-03-01 00:00:00 | 授信额度使用区间起 | \- | +| vestPeriodEnd | Date | 是 | 2023-03-31 00:00:00 | 授信额度使用区间止 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"vestPeriodBegin": "2023-03-01 00:00:00",

+

"vestPeriodEnd": "2023-03-31 00:00:00"

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企授信额度更新有效期接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企授信额度更新有效期接口.md new file mode 100644 index 0000000..d509d2d --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企授信额度更新有效期接口.md @@ -0,0 +1,104 @@ +--- +title: 乐企授信额度更新有效期接口 +aliases: + - 乐企授信额度更新有效期接口 + - 诺税通乐企授信额度更新有效期接口 + - 专项能力-乐企授信额度更新有效期接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 乐企授信额度更新有效期接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/creditQuota/updateVestPeriod.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 乐企授信额度更新有效期接口 + +### 接口说明 + +乐企模式授信额度更新有效期接口，调用该接口时，需保证对应企业税号查询过授信额度。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/creditQuota/updateVestPeriod.do | + +### 请求参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:------------------:|:--------:|:--------:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| taxNum | String | 是 | 需要查询的企业税号 | 企业税号 | 20 | + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| vestPeriodBegin | Date | 是 | 2023-03-01 00:00:00 | 授信额度使用区间起 | \- | +| vestPeriodEnd | Date | 是 | 2023-03-31 00:00:00 | 授信额度使用区间止 | \- | +| vestPeriod | String | 是 | 202303 | 授信额度属期 格式：yyyyMM | 6 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"vestPeriodBegin": "2023-03-01 00:00:00",

+

"vestPeriodEnd": "2023-03-31 00:00:00",

+

"vestPeriod": "202303"

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企数电发票库存申领接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企数电发票库存申领接口.md new file mode 100644 index 0000000..d59d639 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企数电发票库存申领接口.md @@ -0,0 +1,170 @@ +--- +title: 乐企数电发票库存申领接口 +aliases: + - 乐企数电发票库存申领接口 + - 诺税通乐企数电发票库存申领接口 + - 库存票源与打印-乐企数电发票库存申领接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 乐企数电发票库存申领接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/fullStock/applyStock.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 乐企数电发票库存申领接口 + +### 接口说明 + +向纳税人提供批量预赋码功能，用于企业给数字化电子发票自动赋发票号码。每次最多申请5000份数字化电子发票。 + +### 接口地址 + +| | +|:------------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/fullStock/applyStock.do | + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| taxNum | String | 是 | 企业税号 | 申领发票的纳税人识别号或统一社会信用代码 | 20 | +| applyNum | Integer | 是 | 申领数量 | 申领数量最大值：5000 | 10 | + +### 请求示例 + + +++ + + + + + +

{

+

"applyNum": 2,

+

"taxNum": "339901999999199"

+

}

+ +### 返回参数 + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值描述长度
codeInteger是200状态,200-成功，非200-失败6
messageString是成功详细信息1024
dataObject是查询对象
数据信息
applyNumInteger是2领用数量10
invoiceNumStartString是23446000000000000042
+

发票起始号码

+
20
invoiceNumEndString是23446000000000000043发票终止号码20
+ +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"applyNum": 2,

+

"invoiceNumStart": "23446000000000000042",

+

"invoiceNumEnd": "23446000000000000043"

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企查询数电库存接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企查询数电库存接口.md new file mode 100644 index 0000000..3fa817b --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/乐企查询数电库存接口.md @@ -0,0 +1,105 @@ +--- +title: 乐企查询数电库存接口 +aliases: + - 乐企查询数电库存接口 + - 诺税通乐企查询数电库存接口 + - 库存票源与打印-乐企查询数电库存接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 乐企查询数电库存接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/fullStock/queryFullStock.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 乐企查询数电库存接口 + +### 接口说明 + +用于查询数电发票库存 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/fullStock/queryFullStock.do | + +### 请求参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:------------------:|:--------:|:--------:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| taxNum | String | 是 | 需要查询的企业税号 | 企业税号 | 20 | + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| **数据信息** | | | | | | +| availableNum | Integer | 是 | 1 | 可用库存数量 | \- | +| lockNum | Integer | 是 | 1 | 锁定库存数量 | \- | +| applyTime | String | 是 | 2023-03-01 10:00:00 | 最后领用时间 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"availableNum": 1,

+

"lockNum": 1,

+

"applyTime": "2023-03-01 10:00:00"

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业设备查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业设备查询接口.md new file mode 100644 index 0000000..efe8a95 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业设备查询接口.md @@ -0,0 +1,137 @@ +--- +title: 企业设备查询接口 +aliases: + - 企业设备查询接口 + - 诺税通企业设备查询接口 + - 设备企业与配置-企业设备查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 企业设备查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`|` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 企业设备查询接口 + +### 接口说明 + +与3.19相比返回增加了包括开票员id在内的全量设备信息，以票种+设备唯一返回 + +### 接口地址 + +| | | +|:---|----| +| http\[s\]://\\[:\\]/salescore/extensioninfo/queryExtensionList.do | | + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **描述** | **最大长度** | +| companyId | Long | 否 | 10162 | 公司id | | +| taxnum | String | 是 | 150301199811285326 | 税号 | 20 | +| extensionNum | String | 否 | 0 | 分机号 | 12 | +| machineNum | String | 否 | 661565671900 | 机器号 | 12 | +| invoiceLine | String | 否 | c | 发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | | +| clerkId | String | 否 | 1 | 开票员id | | + +### 请求示例 + + +++ + + + + + +

{

+

    "companyId" :"10162",

+

    "taxnum" : "150301199811285326",

+

    "clerkId" : "1",

+

    "invoiceLine" : "c",

+

    "machineNum" : "661565671900",

+

    "extensionNum" : "0"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | Integer | 是 | 200 | | 状态,200-成功，非200-失败 | 6 | +| message | String | | 成功 | | 详细信息 | 1024 | +| data | Object | | | | 数据对象 | | +| 数据信息 | | | | | | | +| extensionId | Long | | 1373 | | extension设备表的主键 | | +| InvoiceType | String | | c | | 发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) | | +| extensionNum | Integer | | 0 | | 分机号 | 12 | +| machineNum | String | | 661565671900 | | 机器编码 | 12 | +| terminalNum | Integer | | 1 | | 终端号 | 10 | +| serverType | Integer | | 14 | | 开票服务器类型 | | +| reportTaxStatus | Integer | | 1 | | 报税状态 -1:未知 0:未抄报 1:已抄报 | | +| clearCardStatus | Integer | | 1 | | 清卡状态 -1:未知 0:未清卡 1:已清卡 | | +| lockDate | String | | 2022-06-15 | | 锁死日期 | | +| singleBillingLimit | BigDecimal | | 999999.99 | | 单张开票限额 | | +| offlineAmount | BigDecimal | | 9999999991.00 | | 离线剩余金额 | | +| offlineTime | BigDecimal | | 720.00 | | 离线时限(h) | | +| updateTime | String | | 2022-05-25 07:37:02 | | 更新时间 | | +| clerkIds | String | | 1 | | 开票员id,多个用逗号隔开 | | +| loginAccount | String | | | | 数电账号 | | + +### 返回示例 + + +++ + + + + + +

{

+

    "code": 200,

+

    "message": "成功",

+

    "data": [

+

        {

+

            "invoiceType": "c",

+

            "extensionNum": 0,

+

            "machineNum": "661565671900",

+

            "terminalNum": 1,

+

            "serverType": 14,

+

            "reportTaxStatus": 1,

+

            "clearCardStatus": 1,

+

            "lockDate": "2022-06-15",

+

            "singleBillingLimit": "999999.99",

+

            "offlineAmount": "9999999991.00",

+

            "offlineTime": "720.00",

+

            "updateTime": "2022-05-25 07:37:02",

+

            "clerkIds": "1"

+

        }

+

    ]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业设备状态查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业设备状态查询接口.md new file mode 100644 index 0000000..a854dd2 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业设备状态查询接口.md @@ -0,0 +1,178 @@ +--- +title: 企业设备状态查询接口 +aliases: + - 企业设备状态查询接口 + - 诺税通企业设备状态查询接口 + - 设备企业与配置-企业设备状态查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 企业设备状态查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/extensioninfo/queryEquipmentStatusList.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P1（开票前保障） + + + +## 企业设备状态查询接口 + +### 接口说明 + +企业设备状态查询接口。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/extensioninfo/queryEquipmentStatusList.do | + +### 请求参数(用json格式接收) + +| | | | | | +|:-------------:|:--------:|:--------:|:--------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| extensionNum | String | 选填 | 分机号 | 5 | +| machineNumber | String | 选填 | 机器编号 | 12 | +| sellerTaxnum | String | 是 | 销方税号 | 20 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": "0",

+

"machineNumber": "123",

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | | 查询成功则返回企业设备状态信息 | | +| 企业设备状态 | | | | | +| invoiceLine | String | 是 | 发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票 | | +| reportTaxStatus | Integer | | 报税状态 -1:未知 0:未抄报 1:已抄报 | | +| clearCardStatus | Integer | | 清卡状态 -1:未知 0:未清卡 1:已清卡 | | +| lockDate | Date | | 锁死日期 | | +| singleBillingLimit | BigDecimal | | 单张开票限额 | | +| offlineAmount | BigDecimal | | 离线剩余金额 | | +| offlineTime | BigDecimal | | 离线时限(h) | | +| updateTime | Date | | 更新时间 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

    "code":200,

+

    "message":"成功",

+

    "data":[

+

        {

+

            "invoiceLine":"s",

+

            "lockDate":"2020-07-01",

+

            "reportTaxStatus":1,

+

            "clearCardStatus":-1,

+

            "offlineAmount":"111111111080.99",

+

            "offlineTime":"999.00",

+

            "singleBillingLimit":"100000000.00",

+

            "updateTime":"2020-11-25 01:00:01"

+

        },

+

        {

+

            "invoiceLine":"c",

+

            "lockDate":"2020-07-01",

+

            "reportTaxStatus":1,

+

            "clearCardStatus":-1,

+

            "offlineAmount":"111111111019.60",

+

            "offlineTime":"999.00",

+

            "singleBillingLimit":"100000000.00",

+

            "updateTime":"2020-11-25 01:00:01"

+

        },

+

        {

+

            "invoiceLine":"p",

+

            "lockDate":"2020-06-15",

+

            "reportTaxStatus":1,

+

            "clearCardStatus":-1,

+

            "offlineAmount":"320122.95",

+

            "offlineTime":"999.00",

+

            "singleBillingLimit":"9999.99",

+

            "updateTime":"2021-02-02 11:32:01"

+

        },

+

        {

+

            "invoiceLine":"j",

+

            "lockDate":"2020-06-15",

+

            "reportTaxStatus":1,

+

            "clearCardStatus":-1,

+

            "offlineAmount":"999999999.00",

+

            "offlineTime":"999.00",

+

            "singleBillingLimit":"10000000.00",

+

            "updateTime":"2020-11-25 01:00:02"

+

        },

+

        {

+

            "invoiceLine":"r",

+

            "lockDate":"2020-06-15",

+

            "reportTaxStatus":1,

+

            "clearCardStatus":-1,

+

            "offlineAmount":"1111111.11",

+

            "offlineTime":"999.00",

+

            "singleBillingLimit":"10000000.00",

+

            "updateTime":"2020-11-25 01:00:02"

+

        }

+

    ]

+

}

+ +失败示例： + + +++ + + + + + +

{

+

    "code":900,

+

    "message":"不存在该设备抄报税信息",

+

    "data":null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业车架号等信息查询结果回传接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业车架号等信息查询结果回传接口.md new file mode 100644 index 0000000..7332c40 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/企业车架号等信息查询结果回传接口.md @@ -0,0 +1,192 @@ +--- +title: 企业车架号等信息查询结果回传接口 +aliases: + - 企业车架号等信息查询结果回传接口 + - 诺税通企业车架号等信息查询结果回传接口 + - 车辆辅助与回传-企业车架号等信息查询结果回传接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 企业车架号等信息查询结果回传接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`用户通过查询企业车架号、合格证状态接口中的callbackUrl字段提供回调地址。` +> - 请求方式：`POST` +> - 是否回调：是 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 企业车架号等信息查询结果回传接口 + +### 接口说明 + +企业车架号等信息查询结果回传接口。 + +### 接口地址 + +用户通过查询企业车架号、合格证状态接口中的callbackUrl字段提供回调地址。 + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | +| vehicleCode | String | 是 | 5656565 | 支持数字、字母、星号 | 车架号 | +| sellerTaxnum | String | 是 | 338801999999001 | 必填 | 车架号所属企业税号，进项归集则需传购方企业税号 | +| status | String | 是 | 1 | 必填 | 查询状态 1:查询成功，2：查询失败 | +| certificate | String | 否 | 125999915630 | 非必填 | 合格证号 | +| extensionNumber | integer | 否 | 123 | 非必填 | 分机号 | +| machineCode | String | 否 | 123456789012 | 非必填 | 机器编号 | +| terminalNum | String | 否 | 0 | 非必填 | 终端号 | +| importCertifyNum | String | 否 | 343455555 | 非必填 | 进口证明书号（进口车才有） | +| describe | String | 否 | | 非必填 | 描述信息 | +| brandModel | String | 否 | | 非必填 | 厂牌型号 | +| engineNum | String | 否 | | 非必填 | 发动机号码 | +| vehicleType | String | 否 | | 非必填 | 车辆类型 | +| inspectionOddNum | String | 否 | \- | 非必填 | 商检单号 | +| productOrigin | String | 否 | 上海 | 非必填 | 产地 | +| requestSrc | String | 是 | 3 | 必填 | 请求来源(0:未知;1-页面添加;2-页面导入;3-api进项调用;4-api用户调用;) | +| vehicleStatus | String | 是 | 1 | 必填 | 车架号状态：1-可开票;3-未知;4-不可开票 | + +### 请求示例 + +查询成功回调（表示该车架号可开票）： + + +++ + + + + + +

{

+

"vehicleCode": "5656565",

+

"sellerTaxnum": "338801999999001",

+

"certificate": "125999915630",

+

"status": "1",

+

"extensionNumber": "123",

+

"machineCode": "123456789012",

+

"importCertifyNum": "343455555",

+

"describe": "机动车合格证号可用",

+

"brandModel": "",

+

"engineNum": "",

+

"vehicleType": "",

+

"inspectionOddNum": "",

+

"productOrigin": "",

+

"requestSrc": "4",

+

"vehicleStatus": "1"

+

}

+ +查询失败回调（表示该车架号不可开票）： + + +++ + + + + + +

{

+

"vehicleCode": "5656565",

+

"sellerTaxnum": "338801999999001",

+

"certificate": "125999915630",

+

"status": "2",

+

"describe": "合格证存在，不属于本企业",

+

"requestSrc": "4",

+

"vehicleStatus": "4"

+

}

+ +【describe】字段文案包含： + +1、合格证已被使用 + +2、查询到合格证信息已使用，不允许开具发票 + +3、未查询到合格证信息，不允许开具发票 + + +4、合格证存在，不属于本企业！ + +### 返回参数 + + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必须示例值更多限制描述最大长度
codeInteger是0000

状态,0000-成功，

+

非0000-失败

6
messageString是成功详细信息1024
+ +### 返回示例 + +示例： + + +++ + + + + + +

{

+

"code": 0000,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/创建_查询企业车架号_合格证状态接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/创建_查询企业车架号_合格证状态接口.md new file mode 100644 index 0000000..0866696 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/创建_查询企业车架号_合格证状态接口.md @@ -0,0 +1,132 @@ +--- +title: 创建/查询企业车架号、合格证状态接口 +aliases: + - 创建/查询企业车架号、合格证状态接口 + - 诺税通创建/查询企业车架号、合格证状态接口 + - 车辆辅助与回传-创建/查询企业车架号、合格证状态接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 创建/查询企业车架号、合格证状态接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/query/vehicleCodeIsInvoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 创建/查询企业车架号、合格证状态接口 + +### 接口说明 + +仅用于请求车架号在税局的是否可开票状态，改接口返回成功仅说明提交查询请求成功，因需和税局交互，故需异步通过查询或回调获取查询结果。请求成功的数据可至诺税通-库存管理-车辆库存中查看。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/query/vehicleCodeIsInvoice.do | + +### 请求参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| vehicleCode | String | 是 | 5656565 | 支持数字、字母、星号 | 车架号 | 23 | +| sellerTaxnum | String | 是 | 338801999999001 | 必填 | 车架号所属企业税号，进项归集则需传购方企业税号 | 20 | +| certificate | String | 否 | 125999915630 | 非必填 | 合格证号 | 50 | +| vehicle Type | String | 否 | 辉腾 | 非必填 | 车辆类型 | 40 | +| brandModel | String | 否 | 大众 | 非必填 | 厂牌型号 | 60 | +| warehouse | String | 否 | 上海 | 非必填 | 所在仓库 | 50 | +| extensionNum | String | 否 | 0 | 非必填 | 分机号 | 5 | +| machineNumber | String | 否 | 1234565654 | 非必填 | 机器编号 | 12 | +| terminalNum | String | 否 | 0 | 非必填 | 终端号 | 12 | +| engineNum | String | 否 | 21166621 | 非必填 | 发动机号码 | 50 | +| importCertifyNum | String | 否 | 343455555 | 非必填 | 进口证明书号 | 36 | +| inspectionOddNum | String | 否 | \- | 非必填 | 商检单号 | 32 | +| productOrigin | String | 否 | \- | 非必填 | 产地 | 32 | +| displacement | String | 否 | | 非必填 | 排量 | 50 | +| callbackUrl | String | 否 | http://127.0.0.1:8080/ | 当请求来源不是3时，必填 | 回调地址 | 255 | +| requestSrc | String | 否 | 4 | 非必填 | 请求来源(0:未知;1-页面添加;2-页面导入;3-api进项调用;4-api用户调用;)默认为4 | 1 | +| refreshFlag | String | 否 | 1 | 非必填 | 刷新标记。(0:不需要调用电票进行刷新;1-需要调用)默认为1 | 1 | + +### 请求示例 + + +++ + + + + + +

{

+

"vehicleCode": "5656565",

+

"sellerTaxnum": "338801999999001",

+

"certificate": "125999915630",

+

"callbackUrl": "http://127.0.0.1:8080/"，

+

"brandModel": "品牌型号"，

+

"warehouse": "上海"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | Integer | 是 | 200 | | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 提交成功 | | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "提交成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 3001,

+

"message": "结果查询中，请稍候重试"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/创建开票设备接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/创建开票设备接口.md new file mode 100644 index 0000000..447d6de --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/创建开票设备接口.md @@ -0,0 +1,230 @@ +--- +title: 创建开票设备接口 +aliases: + - 创建开票设备接口 + - 诺税通创建开票设备接口 + - 设备企业与配置-创建开票设备接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 创建开票设备接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/extensioninfo/insertExtension.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 创建开票设备接口 + +### 接口说明 + +新增开票设备接口,开票设备唯一性规则：当开票员存在时 同一个开票员+开票设备+票种唯一，当不存在开票员时，针对数电设备分机号或登录账号不可重复，针对其他设备，机器编号不可重复。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/extensioninfo/insertExtension.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
taxNumString是企业税号20
extensionNumInteger是分机号 0--65535数字-
terminalNumInteger否终端号2
machineNumString否机器编号 非数电设备必填32
serverTypeInteger是

开票服务器类型 传对应的数字枚举

+

1:C48,

+

11:诺诺开票,

+

14：A9,

+

15:四川税局代开,

+

17:诺诺机柜,

+

18:税控服务器,

+

20:单机版,

+

22:数电发票开票模式（通用版）,

+

24:数电发票开票模式（单机版）,

+

25:数电发票开票模式（机柜版）

+

数电单机版和机柜版暂只支持半本地环境

4
loginAccountString否数电开票账号 开票服务器类型为数电时必传20
elePasswordString否数电开票密码，使用aes加密 开票服务器类型为数电时必传加密前1-20位
equipmentCabinetIdString否机柜序列号 当服务器类型为诺诺机柜时必传30
taxMachinePwdString否设备证书口令 当服务器类型为诺诺机柜时必传35
taxPlatPwdString否设备口令 当服务器类型为诺诺机柜时必传100
serverAddressString否服务器地址 当开票服务为A9或C48时必传100
invoiceTypelistString是

当前设备可开发票种类，使用,隔开

+

p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)

-
clerkListList<Long>否开票员userId集合 当设备需要绑定开票员时必传-
projectListList<String>否项目编码集合 当设备需要绑定设备信息时必传-
+ +### 请求示例 + + +++ + + + + + +

{

+

"taxnum": "150301199811285326",

+

"projectList": ["BJ01-002","20221008"],

+

"serverType": 14,

+

"extensionNum": "5",

+

"machineNum": "123456987456",

+

"terminalNum": "5",

+

"serverAddress": "123456",

+

"clerkList": [8,7],

+

"companName": "移动测试盘326",

+

"invoiceTypelist": "b,s,p,c"

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | String | 是 | 123456789 | 当前新增设备的唯一标识 | 20 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功",

+

"data": "123456789"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/删除发票信息接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/删除发票信息接口.md new file mode 100644 index 0000000..f1b8948 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/删除发票信息接口.md @@ -0,0 +1,117 @@ +--- +title: 删除发票信息接口 +aliases: + - 删除发票信息接口 + - 诺税通删除发票信息接口 + - 车辆辅助与回传-删除发票信息接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 删除发票信息接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/invoiceList/delete.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 删除发票信息接口 + +### 接口说明 + +支持开票失败状态发票删除以及开票中状态发票撤回,传入订单编号删除时支持删除审核开票记录。 + +### 接口地址 + +| | +|-----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/invoiceList/delete.do | + +### 请求参数(用json格式接收) + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| valueType | Integer | 是 | 值类型：0：发票流水号，1：订单编号 | \- | +| value | String | 是 | 若值类型为0，value为发票流水号的值；若值类型为1，value为订单编号的值 | \- | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"value": "21051310255001000228",

+

"valueType": 0

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

    "code":200,

+

    "message":"成功",

+

    "data":  null

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 900,

+

"message": "非开票失败、开票中状态的发票信息不允许删除",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新可下载发票库存接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新可下载发票库存接口.md new file mode 100644 index 0000000..335bfa9 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新可下载发票库存接口.md @@ -0,0 +1,118 @@ +--- +title: 刷新可下载发票库存接口 +aliases: + - 刷新可下载发票库存接口 + - 诺税通刷新可下载发票库存接口 + - 库存票源与打印-刷新可下载发票库存接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 刷新可下载发票库存接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/stock/flushDownloadableStock.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 刷新可下载发票库存接口 + +### 接口说明 + +从税局获取局端可下载发票的信息，仅支持开票服务器类型为诺诺机柜和诺诺开票。控制一分钟之内只能操作一次,请勿频繁操作。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/stock/flushDownloadableStock.do | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 是 | 分机号，纯数字 | \- | +| machineNumber | String | 是 | 机器编号，12位数字 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": 0,

+

"machineNumber": "661565671900",

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 900,

+

"message": "一分钟之内只能操作一次,请勿频繁操作",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新获取开票设备实时发票库存接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新获取开票设备实时发票库存接口.md new file mode 100644 index 0000000..c704360 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新获取开票设备实时发票库存接口.md @@ -0,0 +1,118 @@ +--- +title: 刷新获取开票设备实时发票库存接口 +aliases: + - 刷新获取开票设备实时发票库存接口 + - 诺税通刷新获取开票设备实时发票库存接口 + - 库存票源与打印-刷新获取开票设备实时发票库存接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 刷新获取开票设备实时发票库存接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/stock/refreshLocalStock.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 刷新获取开票设备实时发票库存接口 + +### 接口说明 + +触发刷新获取税盘实时库存接口，仅下发查询指令，需配合库存余量查询接口获取刷新后的实时库存。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/stock/refreshLocalStock.do | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 否 | 分机号，纯数字 | \- | +| machineNumber | String | 否 | 机器编号，12位数字 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": 0,

+

"machineNumber": "661565671900",

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 900,

+

"message": "未找到设备！",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新获取税盘实时成品油库存接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新获取税盘实时成品油库存接口.md new file mode 100644 index 0000000..71a1749 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/刷新获取税盘实时成品油库存接口.md @@ -0,0 +1,118 @@ +--- +title: 刷新获取税盘实时成品油库存接口 +aliases: + - 刷新获取税盘实时成品油库存接口 + - 诺税通刷新获取税盘实时成品油库存接口 + - 专项能力-刷新获取税盘实时成品油库存接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 刷新获取税盘实时成品油库存接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/oilStock/refreshProductOil.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 刷新获取税盘实时成品油库存接口 + +### 接口说明 + +刷新成品油库存接口 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/oilStock/refreshProductOil.do | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 是 | 分机号，纯数字 | \- | +| machineNumber | String | 否 | 机器编号，12位数字 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": 0,

+

"machineNumber": "661565671900",

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 913,

+

"message": "不支持的开票服务器类型！",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票交付.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票交付.md new file mode 100644 index 0000000..9321e1f --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票交付.md @@ -0,0 +1,181 @@ +--- +title: 发票交付 +aliases: + - 发票交付 + - 诺税通发票交付 + - 开票主链路-发票交付 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 发票交付 + +> [!info] 导航 +> 上级索引：[[README]] · [[02_开票主链路]] +> 文档链接：[总索引](../README.md) · [分组页](../02_开票主链路.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[02_开票主链路]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/invoice/delivery.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P1 + + + +## 发票交付 + +### 接口说明 + +发票交付接口，用于提供给企业对诺税通中开具的发票进行交付，具体的短信、邮件发送通道根据不同企业配置决定。 + +### 接口地址 + +| | +|:--------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/invoice/delivery.do | + +### 请求参数 + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必须示例值描述最大长度
sellerTaxnumString否150301199811285326销方税号；销方税号和销方组织编码其一必填
sellerCompanyCodeString否10162销方组织编码；销方税号和销方组织编码其一必填
invoiceCodeString否050001901011发票代码12或10位12
invoiceNumberString是93693692

发票号码

+

8或20位

20
notifyPhoneString否交付手机号码；交付电话号码和交付邮箱至少有一个不为空，仅支持一个
notifyEmailString否交付邮箱地址；交付电话号码和交付邮箱至少有一个不为空，仅支持一个
ccPhoneString否抄送手机号，当推送手机notifyPhone有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个100
ccEmailString否抄送邮箱，当推送邮箱notifyEmail有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个250
+ +### 请求实例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"sellerCompanyCode": "",

+

"invoiceCode": "",

+

"invoiceNumber": "93693692",

+

"notifyPhone": "15669968255",

+

"notifyEmail": "zhuyihui@nnuo.com"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票作废申请接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票作废申请接口.md new file mode 100644 index 0000000..e634888 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票作废申请接口.md @@ -0,0 +1,146 @@ +--- +title: 发票作废申请接口 +aliases: + - 发票作废申请接口 + - 诺税通发票作废申请接口 + - 作废重开与冲红-发票作废申请接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 发票作废申请接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[03_作废重开与冲红]] +> 文档链接：[总索引](../README.md) · [分组页](../03_作废重开与冲红.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[03_作废重开与冲红]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/invalid-oneInvoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P1 + + + +## 发票作废申请接口 + +### 接口说明 + +申请发票作废。 + +### 接口地址 + +| | +|:----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/invalid-oneInvoice.do | + +### 请求参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| invoiceId | String | 是 | 18081620564001000232 | 必填 | 发票请求流水号 | 20 | +| sellerTaxnum | String | 否 | 339901999999610 | 企业税号和组织编码必填其一 | 发票对应的销方企业税号 | 20 | +| companyCode | String | 否 | | 企业税号和组织编码必填其一 | 组织编码 | 20 | +| invoiceCode | String | 是 | 125999915630 | 必填 | 对应发票代码 | 12 | +| invoiceNumber | String | 是 | 00130865 | 必填 | 对应发票号码 | 8 | +| invalidReason | Integer | 否 | | 数电纸票时需要传（1:销货退回;2:开票有误;3:服务中止;4:其他），默认 2 | 作废原因 | 1 | +| specificReason | String | 否 | | 数电纸票且作废原因选择4-其他时需要传 | 其他作废原因详情 | 255 | +| columnFirst | String | 否 | 退货单号123 | 否 | 自定义列1 | | +| columnSecond | String | 否 | 退货单号123 | 否 | 自定义列2 | | +| columnThree | String | 否 | 退货单号123 | 否 | 自定义列3 | | +| invalidUserCode | String | 否 | 123 | 否 | 作废操作人用户编码，优先使用操作人id | 20 | +| invalidUserId | Long | 否 | 1 | 否 | 作废操作人ID | 11 | + +### 请求示例 + + +++ + + + + + +

{

+

"invoiceId": "18081620564001000232",

+

"sellerTaxnum": "339901999999610",

+

"invoiceCode": "125999915630",

+

"invoiceNumber": "00130865"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | Integer | 是 | 200 | | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 作废成功 | | 详细信息 | 1024 | +| data | String | 是 | 18081620564001000232 | | 提交成功则返回发票请求流水号 | 32 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "作废成功",

+

"data": "18081620564001000232"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 9151,

+

"message": "非当月纸票不能作废"

+

}

+ +### 状态码说明 + +| | | +|:----------:|:---------------------------------------------------------:| +| **状态码** | **描述** | +| 2733 | 发票不存在 | +| 2739 | 开票未完成，不可进行作废 | +| 2740 | 电票暂不支持作废 | +| 2741 | 发票被冲红不支持作废 | +| 2743 | 非当月发票不支持作废 | +| 2744 | 不支持重复作废 | +| 2749 | 发票已经作废 | +| 2751 | 企业税号不能为空 | +| 2755 | 入参invoiceId不能为空 | +| 2756 | 入参invoiceCode不能为空 | +| 2757 | 入参invoiceNumber不能为空 | +| 2758 | 入参invoiceId查询的发票记录中发票代码和入参发票代码不匹配 | +| 2759 | 入参invoiceId查询的发票记录中发票号码和入参发票号码不匹配 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票列表查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票列表查询接口.md new file mode 100644 index 0000000..82bc6b2 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票列表查询接口.md @@ -0,0 +1,2057 @@ +--- +title: 发票列表查询接口 +aliases: + - 发票列表查询接口 + - 诺税通发票列表查询接口 + - 开票主链路-发票列表查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 发票列表查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[02_开票主链路]] +> 文档链接：[总索引](../README.md) · [分组页](../02_开票主链路.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[02_开票主链路]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/queryInvoiceList.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P0 + + + +## 发票列表查询接口 + +### 接口说明 + +通过时间、自定义字段分页查询企业发票列表。 + +### 接口地址 + +| | +|:--------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/queryInvoiceList.do | + +### 请求参数 + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值更多限制描述
sellerTaxnumString否150301199811285326销方税号和销方组织编码二选一必填销方税号
companyCodeString否销方税号和销方组织编码二选一必填销方组织编码
requestTypeInteger否0默认为0请求类型，默认是0；0为按照订单添加时间查询，1为按照开票时间查询
startDateString是2021-07-01格式：yyyy-MM-dd,开始时间和结束时间跨度不能超过365天开始时间
endDateString是2021-07-21格式：yyyy-MM-dd,开始时间和结束时间跨度不能超过365天结束时间
columnFirstString否1
columnSecondString否2
columnThreeString否3
isDetailInt否0默认为0

是否包含明细

+

0不包含 1包含

pageNumint否1默认为1当前页
pageSizeint否15默认为15，分页条数最大支持50条分页条数
+ +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"requestType":1,

+

"startDate":"2021-07-01",

+

"endDate":"2021-07-21",

+

"columnFirst":"1",

+

"columnSecond":"2",

+

"columnThree":"3",

+

"isDetail":1,

+

"pageNum":1,

+

"pageSize":15

+

}

+ +### 返回参数 + + ++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值更多限制描述最大长度
codeInteger是200状态,200-成功，非200-失败6
messageString查询成功详细信息1024
dataObject18081620564001000232查询成功则返回数据信息
数据信息
pageNumint是1当前页数
pageSizeint是15每页条数
pagesint是1总页数
totalint是2数据总数
listList查询成功则返回发票信息
发票信息
orderNoString否20170104120207971529订单号64
invoiceIdString否20092114394901000002流水号20
statusInteger否2开票状态(0:开票中1:开票完成2:开票失败3:发票生成2
invalidStateInteger否0发票作废状态: 0 未提交 , 1 作废成功 , 2 作废失败 , 3 已提交(作废中)。默认值02
invalidTimeString否1604576878000发票作废时间
requestSrcInteger否开票方式,0:api接口 1:手工开票 2:批量导入 5:本地提取1
errorMessageString否[9999]HX1000 4003-发票数据写盘失败[TCD_769_25,离线发票累计金额超限！],发票代码或号码为空开票异常信息128
pdfUrlString否https://inv.jss.com.cn/group1/M00/A6/4C/wKgHPll_IU-AVELfAACNq5bmzFM769.pdf发票pdf地址255
paperPdfUrlString否PDF含底图255
imageUrlString否发票jpg地址，清单票发票主信息与清单信息以”,”隔开255
ofdUrlString否发票ofd地址255
invoiceTimeString否1604576878000开票日期19
invoiceCodeString否125999915630发票代码12
invoiceNumberString否00130865发票号码8
allElectronicInvoiceNumberString否数电发票号码20
taxFreeAmountTotalBigDecimal否不含税金额15.2
taxTotalBigDecimal否税额15.2
taxAmountTotalBigDecimal否含税金额15.2
buyerNameString否浙江爱信诺购方名称100
buyerTaxnumString否339901999999103购方税号20
buyerAddressString否浙江省杭州市万塘路购方地址100
buyerPhoneString否15858585858购方电话50
buyerBankString否购方开户行购方开户行100
buyerAccountString否购方银行账号购方银行账号30
invoiceLineString否1发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)2
checkCodeString否校验码20
qrCodeString否二维码3000
machineNumberString否机器编号12
invoiceCipherString否发票密文300
clerkerString否张三开票人20
payeeString否李四收款人20
checkerString否王五复核人20
sellerNameString否浙江爱信诺销方名称100
sellerTaxnumString否330100555190356销方税号20
sellerAddressString否杭州市西湖区万塘路销方地址100
sellerPhoneString否0571-81029365销方电话20
sellerBankString否开户行销方开户行100
sellerAccountString否开户行账号销方开户行账号30
remarkString否备注信息备注

数电电票：200(中文计算一位)

+

其他发票：230(中文计算两位)

productOilFlagInteger否0

成品油标志，

+

0:非成品油;

+

1:成品油

2
vehicleFlagInteger否0默认00：非机动车。1：机动车2
extensionNumInteger否开票请求分机号,范围为0-655355
terminalNumInteger否开票请求终端号5
notifyPhoneString否推送手机20
notifyEmailString否test@xx.com推送邮箱50
deptIdString否9F7E9439CA8B4C60A2FFF3EA3290B088部门门店id（诺诺系统中的id）32
clerkIdString否3F7EA439CA8B4C60A2FFF3EA3290B084开票员id（诺诺系统中的id）32
oriInvoiceCodeString否125999915630原发票代码12
oriInvoiceNumberString否00130865原发票号码8
oldEleInvoiceNumberString否原数电发票号码20
listFlagInteger否0

清单标志，

+

0:非清单，1:清单

2
listGoodsNameString否详见销货清单注意：税局要求清单项目名称为（详见销货清单）90
orderDateString否2022-05-12年-月-日订单日期10
deliverDateString否2022-05-12年-月-日发货日期
columnFirstString否业务调用方自定义字段一业务调用方自定义字段一255
columnSecondString否业务调用方自定义字段二业务调用方自定义字段二255
columnThreeString否业务调用方自定义字段三业务调用方自定义字段三255
projectCodeString否项目编码64
projectNameString否项目名称300
mailNoString否快递单号
businessTypeString否枚举值来源为基础字典配置业务类型
ccPhoneString否抄送手机，多个以英文逗号分隔100
ccEmailString否抄送邮箱，多个以英文逗号分隔250
invalidReasonInteger否数电纸票作废原因 1:销货退回;2:开票有误;3:服务中止;4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回）1
specificReasonString否其他作废原因详情（作废原因为4 且回传其他信息时返回）255
specificFactorString否特定要素：0普通发票 01成品油 03建筑服务 04货物运输发票 05不动产销售发票 06不动产租赁发票 09旅客运输发票 14机动车 16农产品收购 33二手车反向开具 35矿产品发票50
subjectAccountCodeString否T123核算主体编码维护在诺税通的“核算主体编码”200
subjectAccountString否核算主体名称核算主体名称核算主体名称200
redReasonInteger否11：销售退回2：开票有误3：服务终止4：销售折让冲红原因1
naturalPersonFlagInteger否0购买方自然人标志：0-否（默认）、1-是2
invoiceGoodsTransportsList否货物运输发票时必填货物运输明细最大长度2000
realPropertyRentObject否开具不动产租赁发票时必填不动产租赁发票信息
invoiceBuildingInfoObject否建筑服务发票时必填建筑服务信息
货物运输明细
goodsNameString否煤炭运输货物名称80
originString否北京市市辖区东城区起运地80
destinationString否北京市市辖区丰台区到达地80
transportTool否1运输工具种类：1铁路运输、2公路运输、3.水路运输、4.航空运输、5.管道运输1
transportToolNumString否车牌号DD运输工具牌号80
detailList否发票明细信息
发票明细
detailIndexInteger否0明细行序号5
goodsNameString否商品名称90
taxrateString否0.16税率10
withTaxFlagInteger否

单价含税标志:

+

0:不含税;

+

1:含税

2
taxFreePriceBigDecimal否不含税单价32.16
goodsPriceBigDecimal否含税单价32.16
goodsNumBigDecimal否数量32.16
taxAmountBigDecimal否含税金额15.2
taxFreeAmountBigDecimal否不含税金额15.2
taxBigDecimal否税额15.2
goodsUnitString否单位22
specTypeString否规格型号40
commodityCodeString否商品编码64
goodsCodeString否税收分类编码19
goodsCodeAbbString否税收分类编码简称200
detailTypeInteger否

明细行性质:

+

0:正常行;

+

1:折扣行;

+

2:被折扣行

2
favouredPolicyFlagInteger否

优惠政策标识:

+

0:不使用;

+

1:使用

2
favouredPolicyNameString否优惠政策内容，如：即征即退、免税、简易征收 等50
zeroRateFlagInteger否

零税率标识:

+

空:非零税率;

+

1:免税;

+

2:不征税;

+

3:普通零税率

2
selfCodeString否自行编码20
deductionBigDecimal否扣除额15.2
columnFirstString否自定义字段1255
columnSecondString否自定义字段2255
columnThreeString否自定义字段3255
columnFourString否自定义字段4255
columnFiveString否自定义字段5255
favouredPolicyCodeString否01：简易征收 02：稀土产品 03：免税 04：不征税 05：先征后退 06：100%先征后退 07：50%先征后退 08：按3%简易征收 09：按5%简易征收 10：按5%简易征收减按1.5%计征 11：即征即退30% 12：即征即退50% 13：即征即退70% 14：即征即退100% 15：超税负3%即征即退 16：超税负8%即征即退 17：超税负12%即征即退 18：超税负6%即征即退

优惠政策编码

+

数电发票特有字段

机动车(j)/二手车(u)发票明细
vehicleTypeString否车辆类型40
brandModelString否厂牌型号60
productOriginString否产地32
certificateString否合格证号50
importCertifyNumString否进口证明书号50
inspectionOddNumString否商检单号50
engineNumString否发动机号码50
vehicleCodeString否车辆识别代号/车架号码50
taxOfficeCodeString否主营税务机关及代码100
intactCertificateNumString否完税凭证号码50
measureUnitsString否吨位20
maxCapacityString否限乘人数10
produceCompanyNameString否生产企业名称50
organizationCodeString否339901999999103其他证件号码30
organizeTypeString是发票种类为二手车发票返回开票方类型：1.经营单位2.拍卖单位3.二手车市场（二手车专用）2
licenseNumberString是发票种类为二手车发票返回车牌号码（二手车专用）20
registerCertNoString是发票种类为二手车发票返回登记证号（二手车专用）20
vehicleManagementNameString是发票种类为二手车发票返回转入地车辆管理所名称（二手车专用）80
salerNameString是发票种类为二手车发票返回卖方单位/个人名称（二手车专用）80
salerNumString是发票种类为二手车发票返回卖方单位代码/身份证号码（二手车专用）20
salerAddressString否卖方单位/个人地址（二手车专用）80
salerPhoneString否卖方电话（二手车专用）20
不动产租赁发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
rentStartDateString是2023-02-17yyyy-MM-dd格式租赁期起期10
rentEndDateString是2023-02-18yyyy-MM-dd格式租赁期止期10
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位1
建筑服务发票信息
buildingAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入建筑服务发生地-
detailedAddressString否XXXX街道XXX号建筑服务发生地+详细地址最大长度120详细地址120
landVatItemNoString否1234556土地增值税项目编号16
itemNameString是1234556项目名称80
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertySellObject否不动产销售发票时必填不动产销售发票信息
不动产销售发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位10
realPropertyContractNumberString否不动产单元代码/网签合同备案编号28
incrementTaxNumberString否土地增值税项目编号18
priceString否核定计税价格20
taxAmountString否核定计税价格有值时,实际成交含税金额必填实际成交含税金额20
invoiceTravellerTransportInfoListList否开旅客运输发票时传入出行人信息出行人信息
出行人信息
travellerString是出行人20
travelDateString是年-月-日格式出行日期 年-月-日10
travellerCardTypeString是

101-组织机构代码证

+

102-营业执照

+

103-税务登记证

+

199-其他单位证件

+

201-居民身份证

+

202-军官证

+

203-武警警官证

+

204-士兵证

+

205-军队离退休干部证

+

206-残疾人证

+

207-残疾军人证（1-8级）

+

208-外国护照

+

210-港澳居民来往内地通行证

+

212-中华人民共和国往来港澳通行证

+

213-台湾居民来往大陆通行证

+

214-大陆居民往来台湾通行证

+

215-外国人居留证

+

216-外交官证

+

217-使（领事）馆证

+

218-海员证

+

219-香港永久性居民身份证

+

220-台湾身份证

+

221-澳门特别行政区永久性居民身份证

+

222-外国人身份证件

+

224-就业失业登记证

+

225-退休证

+

226-离休证

+

227-中国护照

+

228-城镇退役士兵自谋职业证

+

229-随军家属身份证明

+

230-中国人民解放军军官转业证书

+

231-中国人民解放军义务兵退出现役证

+

232-中国人民解放军士官退出现役证

+

233-外国人永久居留身份证（外国人永久居留证）

+

234-就业创业证

+

235-香港特别行政区护照

+

236-澳门特别行政区护照

+

237-中华人民共和国港澳居民居住证

+

238-中华人民共和国台湾居民居住证

+

239-《中华人民共和国外国人工作许可证》（A类）

+

240-《中华人民共和国外国人工作许可证》（B类）

+

241-《中华人民共和国外国人工作许可证》（C类）

+

291-出生医学证明

+

299-其他个人证件

出行人证件类型5
travellerCardNoString是出行人证件号码20
travelPlaceString是出行地80
arrivePlaceString是到达地80
vehicleTypeInteger是
    +

  1. 飞机

    2. +

  2. 火车

    3. +

  3. 长途汽车

    4. +

  4. 公共交通

    5. +

  5. 出租车

    6. +

  6. 汽车

    7. +

  7. 船舶

    +

    9-其他

    8. +
交通工具类型2
vehicleLevelString否

当交通工具类型是火车、飞机、船舶时必填选择，其他交通工具时可选填

+

当交通工具类型是火车时，必填，下拉框选择，可选项是 一等座、二等座、软席（软座、软卧）、硬卧（硬座、硬卧）

+

当交通工具类型是飞机时，必填，下拉框选择，可选项是 公务舱、头等舱、经济舱

+

当交通工具类型是船舶事，必填，下拉框选择，可选项是 一等舱、二等舱、三等舱

+

当交通工具类型是其他时，选填

交通工具等级20
+ +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"data": {

+

"pageNum": 1,

+

"pageSize": 15,

+

"pages": 1,

+

"total": 2,

+

"list": [

+

{

+

"buyerAccount": "123456789012345678901234567890",

+

"buyerAddress": "浙江金华婺城区",

+

"buyerBank": "工商银行",

+

"buyerName": "浙江师范大学",

+

"buyerPhone": "0579-88888887",

+

"buyerTaxnum": "339901999999142",

+

"checkCode": "44247972354050973155",

+

"checker": "ying",

+

"clerkId": "",

+

"clerker": "自动开票",

+

"columnFirst": "1",

+

"columnSecond": "2",

+

"columnThree": "3",

+

"deptId": "",

+

"extensionNum": 0,

+

"imageUrl": "https://invtest.nntest.cn/fp/aUl7efywBqGm-WqwuBHyR-TuSTdyr1vDp6vV4xUQ-Ms51qY2OEO1t8aughx4NPG82l_jECyLMEzBoXrlwxJuig.jpg",

+

"invalidState": 0,

+

"invoiceCipher": "-&lt;3359597+2969&gt;-08&lt;7+8*03&lt;3/-4845-+4&gt;450658*517/659574+&gt;530&lt;/14444313-4/&gt;21+&lt;3++9232-&gt;9-*4*-80-/*2418/7014&lt;1",

+

"invoiceCode": "150010020011",

+

"invoiceId": "21062515355501000053",

+

"invoiceLine": "p",

+

"invoiceNumber": "13458270",

+

"invoiceTime": 1624606697000,

+

"invalidTime":"1604576878000",

+

"requestSrc":"1",

+

"listFlag": 0,

+

"listGoodsName": "",

+

"machineNumber": "661565671900",

+

"notifyEmail": "",

+

"notifyPhone": "",

+

"ofdUrl": "",

+

"orderNo": "d66d077f01484315b6d44dca86295d16",

+

"oriInvoiceCode": "150010020011",

+

"oriInvoiceNumber": "13458270",

+

"payee": "zhangsan",

+

"pdfUrl": "https://invtest.nntest.cn/fp/aUl7efywBqGm-WqwuBHyR7VgIQHxTpPvSxy-wAnGgAitSwrfyaeVMyJhHWPtA3NNDC3H8IVGaK4gfceqZubnfg.pdf",

+

"productOilFlag": 0,

+

"qrCode": "01,10,150010020011,13458270,1.00,20210625,44247972354050973155,F829,",

+

"remark": "222",

+

"sellerAccount": "66998877665544332211",

+

"sellerAddress": "金色西溪",

+

"sellerBank": "中国银行",

+

"sellerName": "移动测试盘",

+

"sellerPhone": "41312",

+

"sellerTaxnum": "150301199811285326",

+

"status": 1,

+

"taxAmountTotal": 1.03,

+

"taxFreeAmountTotal": 1,

+

"taxTotal": 0.03,

+

"terminalNum": 1,

+

"vehicleFlag": 0,

+

"projectCode": "项目名称",

+

"projectName": "项目编码",

+

"detail":[

+

{

+

"detailIndex":0,

+

"detailType":0,

+

"goodsName":"苹果",

+

"withTaxFlag":0,

+

"goodsPrice":"1.09",

+

"taxFreePrice":"1",

+

"goodsNum":"1",

+

"taxrate":"0.09",

+

"specType":"20个",

+

"goodsUnit":"箱",

+

"goodsCode":"1010115010100000000",

+

"goodsCodeAbb":"水果",

+

"favouredPolicyFlag":0,

+

"zeroRateFlag":"",

+

"favouredPolicyName":"",

+

"selfCode":null,

+

"deduction":null,

+

"taxAmount":"1.09",

+

"taxFreeAmount":"1.00",

+

"tax":"0.09",

+

"vehicleType":"三轮运输车",

+

"brandModel":"厂牌型号",

+

"productOrigin":"产地",

+

"certificate":"合格证号",

+

"importCertifyNum":"进出口证明书号",

+

"inspectionOddNum":"商检单号",

+

"engineNum":"发动机号",

+

"vehicleCode":"车辆识别代号",

+

"measureUnits":"吨",

+

"maxCapacity":"10",

+

"organizationCode":"组织机构代码",

+

"produceCompanyName":"生产企业名称",

+

"columnFirst":"自定义字段1",

+

"columnSecond":"自定义字段2",

+

"columnThree":"自定义字段3",

+

"columnFour":"自定义字段4",

+

"columnFive":"自定义字段5"

+

}

+

]

+

},

+

{

+

"buyerAccount": "123456789012345678901234567890",

+

"buyerAddress": "浙江金华婺城区",

+

"buyerBank": "工商银行",

+

"buyerName": "浙江师范大学",

+

"buyerPhone": "0579-88888887",

+

"buyerTaxnum": "339901999999142",

+

"checkCode": "51425603410203243765",

+

"checker": "ying",

+

"clerkId": "",

+

"clerker": "自动开票",

+

"columnFirst": "1",

+

"columnSecond": "2",

+

"columnThree": "3",

+

"deptId": "",

+

"extensionNum": 0,

+

"imageUrl": "https://invtest.nntest.cn/fp/yGRZLqKEdmrazWrzrjyAPXvOrBm2E5eX9CDq6WYWwEn21ct8SLwlfbXKcy6UdWC_E-Tl9W-xZzVPzVC3q7bviA.jpg",

+

"invalidState": 0,

+

"invoiceCipher": "2/32-21/5979-&lt;1/*380-&gt;-1864&lt;8&lt;4&lt;015&lt;5*--+17/+/8945/6+248--9//0+&gt;00126-9+14/184-/&lt;38+**+10&lt;917+1529857*8*&lt;001",

+

"invoiceCode": "150010020012",

+

"invoiceId": "21062811273101175660",

+

"invoiceLine": "p",

+

"invoiceNumber": "35424243",

+

"invoiceTime": 1624850993000,

+

"listFlag": 0,

+

"listGoodsName": "",

+

"machineNumber": "661565671900",

+

"notifyEmail": "",

+

"notifyPhone": "",

+

"ofdUrl": "",

+

"orderNo": "f74cfabe58204444b441e41b9ec2ec06",

+

"oriInvoiceCode": "150010020012",

+

"oriInvoiceNumber": "35424243",

+

"payee": "zhangsan",

+

"pdfUrl": "https://invtest.nntest.cn/fp/yGRZLqKEdmrazWrzrjyAPXMQKkuNfD09X5SFPQgz6v6H9YJPp9QXzJa9qgiWf2hfW5gEdDPUwwzLmuYXHLvBHQ.pdf",

+

"productOilFlag": 0,

+

"qrCode": "01,10,150010020012,35424243,1.00,20210628,51425603410203243765,4319,",

+

"remark": "222",

+

"sellerAccount": "66998877665544332211",

+

"sellerAddress": "金色西溪",

+

"sellerBank": "中国银行",

+

"sellerName": "移动测试盘",

+

"sellerPhone": "41312",

+

"sellerTaxnum": "150301199811285326",

+

"status": 1,

+

"taxAmountTotal": 1.03,

+

"taxFreeAmountTotal": 1,

+

"taxTotal": 0.03,

+

"terminalNum": 1,

+

"vehicleFlag": 0,

+

"projectCode": "项目名称",

+

"projectName": "项目编码",

+

"detail":[

+

{

+

"detailIndex":0,

+

"detailType":0,

+

"goodsName":"苹果",

+

"withTaxFlag":0,

+

"goodsPrice":"1.09",

+

"taxFreePrice":"1",

+

"goodsNum":"1",

+

"taxrate":"0.09",

+

"specType":"20个",

+

"goodsUnit":"箱",

+

"goodsCode":"1010115010100000000",

+

"goodsCodeAbb":"水果",

+

"favouredPolicyFlag":0,

+

"zeroRateFlag":"",

+

"favouredPolicyName":"",

+

"selfCode":null,

+

"deduction":null,

+

"taxAmount":"1.09",

+

"taxFreeAmount":"1.00",

+

"tax":"0.09",

+

"vehicleType":"三轮运输车",

+

"brandModel":"厂牌型号",

+

"productOrigin":"产地",

+

"certificate":"合格证号",

+

"importCertifyNum":"进出口证明书号",

+

"inspectionOddNum":"商检单号",

+

"engineNum":"发动机号",

+

"vehicleCode":"车辆识别代号",

+

"measureUnits":"吨",

+

"maxCapacity":"10",

+

"organizationCode":"组织机构代码",

+

"produceCompanyName":"生产企业名称",

+

"columnFirst":"自定义字段1",

+

"columnSecond":"自定义字段2",

+

"columnThree":"自定义字段3",

+

"columnFour":"自定义字段4",

+

"columnFive":"自定义字段5"

+

}

+

]

+

}

+

]

+

},

+

"message": "成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code":2649,

+

"message":"销方税号不能为空"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票库存余量查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票库存余量查询接口.md new file mode 100644 index 0000000..de0ec67 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票库存余量查询接口.md @@ -0,0 +1,146 @@ +--- +title: 发票库存余量查询接口 +aliases: + - 发票库存余量查询接口 + - 诺税通发票库存余量查询接口 + - 库存票源与打印-发票库存余量查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 发票库存余量查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/queryStockInfoList.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P1（开票前保障） + + + +## 发票库存余量查询接口 + +### 接口说明 + +查询开票设备的发票库存余量。 + +### 接口地址 + +| | +|:----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/queryStockInfoList.do | + +### 请求参数(用json格式接收) + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **其他说明** | **描述** | **长度** | +| extensionNum | String | 否 | | 分机号 | 5 | +| machineNumber | String | 否 | | 机器编号 | 12 | +| sellerTaxnum | String | 否 | 销方税号、销方公司编码、销方公司名字三个必填其一 | 销方税号 | 20 | +| sellerCompanyCode | String | 否 | 销方税号、销方公司编码、销方公司名字三个必填其一 | 销方公司编码 | 20 | +| sellerCompanyName | String | 否 | 销方税号、销方公司编码、销方公司名字三个必填其一 | 销方公司名字 | 100 | +| searchRange | Integer | 否 | | 查询范围,0:全部,1:仅在诺税通开票设备中维护的设备余量信息;默认0 | 1 | + +### 请求示例 + + +++ + + + + + +

{

+

  "extensionNum": "0",

+

  "machineNumber": "661565671900",

+

  "sellerTaxnum": "150301199811285326",

+

  "sellerCompanyName":"移动测试盘326",

+

  "sellerCompanyCode" : "1100"

+

}

+ +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | | 查询成功则返回红字申请信息 | | +| 库存信息 | | | | | +| sellerTaxnum | String | | 销方税号 | | +| extensionNum | Integer | | 分机号 | | +| machineNumber | String | | 机器编号 | | +| stocks | List | | 库存信息列表 | | +| 库存明细 | | | | | +| terminalNum | Integer | | 终端号 | | +| invoiceLine | String | | 发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票 | | +| invoiceCode | String | | 发票代码 | | +| invoiceNumStart | String | | 起始号码 | | +| inoviceNumEnd | String | | 终止号码 | | +| remainNum | Integer | | 剩余分数 | | +| isDefault | Integer | | 是否默认卷：1-是 0-否(默认) | | +| createTime | Date | | 更新时间 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"sellerTaxnum": "150301199811285326",

+

"extensionNum": 0,

+

"machineNumber": null,

+

"stocks": [

+

{

+

"terminalNum": 0,

+

"invoiceLine": "s",

+

"invoiceCode": "5000201530",

+

"invoiceNumStart": "71895758",

+

"invoiceNumEnd": "0",

+

"remainNum": 0,

+

"createTime": "2021-06-04 17:20:24"

+

},

+

{

+

"terminalNum": 0,

+

"invoiceLine": "s",

+

"invoiceCode": "5000201530",

+

"invoiceNumStart": "85199644",

+

"invoiceNumEnd": "0",

+

"remainNum": 0,

+

"createTime": "2021-06-04 17:20:24"

+

}

+

]

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票重开接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票重开接口.md new file mode 100644 index 0000000..92543b9 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/发票重开接口.md @@ -0,0 +1,186 @@ +--- +title: 发票重开接口 +aliases: + - 发票重开接口 + - 诺税通发票重开接口 + - 作废重开与冲红-发票重开接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 发票重开接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[03_作废重开与冲红]] +> 文档链接：[总索引](../README.md) · [分组页](../03_作废重开与冲红.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[03_作废重开与冲红]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/reInvoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 发票重开接口 + +### 接口说明 + +当请求诺税通开具的发票返回开票失败时，可通过调用该接口触发开票失败的发票数据重新发起开票。 + +### 接口地址 + +| | +|--------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/reInvoice.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
sellerTaxNumString否

销方税号

+

企业税号和组织编码必填其一

20
companyCodeString否

组织编码

+

企业税号和组织编码必填其一

20
invoiceIdString否发票流水号(invoiceId和orderNo任一必填)32
orderNoString否订单号(invoiceId和orderNo任一必填)32
nextInvoiceCodeString否

下一张发票代码

+

支持票种：c普通发票（纸质）f收购发票（纸质）

+

指定发票卷重开时必传

12
nextInvoiceNumString否

下一张发票号码

+

支持票种：c普通发票（纸质）f收购发票（纸质）

+

当【下一张发票代码】有值时，【下一张发票号码】和【发票终止号码】二选一必填

invoiceNumEndString否

发票终止号码

+

支持票种：c普通发票（纸质）f收购发票（纸质）

+

当【下一张发票代码】有值时，【下一张发票号码】和【发票终止号码】二选一必填

+ +### 请求示例 + + +++ + + + + + +

{

+

"invoiceId": "21031114572601000143",

+

"orderNo": "21031114572601000143",

+

"sellerTaxnum": "150301199811285326",

+

"nextInvoiceNum": "1234456",

+

"nextInvoiceCode": "123456"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 2733,

+

"message": "该发票不存在"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/审核开票删除回传接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/审核开票删除回传接口.md new file mode 100644 index 0000000..6009344 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/审核开票删除回传接口.md @@ -0,0 +1,140 @@ +--- +title: 审核开票删除回传接口 +aliases: + - 审核开票删除回传接口 + - 诺税通审核开票删除回传接口 + - 车辆辅助与回传-审核开票删除回传接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 审核开票删除回传接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`用户通过开票请求中的bizCallbackUrl字段提供回调地址。` +> - 请求方式：`POST` +> - 是否回调：是 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 审核开票删除回传接口 + +### 接口说明 + +返回审核开票删除信息的订单编号和税号等信息 + +注意：请按照文档要求提供接口。 + +### 接口地址 + +用户通过开票请求中的bizCallbackUrl字段提供回调地址。 + +### 请求参数(用json格式接收) + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **描述** | **最大长度** | +| orderNo | String | 是 | 20220426094552511469 | 订单编号 | 64 | +| sellerTaxnum | String | 是 | 150301199811285326 | 销方税号 | 20 | +| invoiceStatus | Integer | 是 | 6 | 发票处理结果: 6：审核开票删除 | 1 | +| formId | String | 否 | CB00696BD1094735849897E66029AB45 | 流程审批单id,回传给oa时必须 | 50 | +| formType | int | 否 | 2 | 流程类型（1：用印申请,2:蓝票开具申请,3:红票开具申请,4:发票作废申请）,回传给oa时必须 | | +| deleteDate | String | 是 | 2022-04-26 14:45:30 | 删除时间yyyy-MM-dd HH:mm:ss格式 | | +| deleteUserId | long | 是 | 1 | 删除操作人id | | +| deleteUserName | String | 是 | 张三 | 删除操作人名称 | | + +### 请求示例 + + +++ + + + + + +

{

+

"deleteDate":"2022-04-29 15:51:39",

+

"deleteUserId":1,

+

"deleteUserName":"张三",

+

"formId":"7BCB5E90EAF64B9C903D920BF82591E4",

+

"formType":2,

+

"orderNo":"20220425091325328406",

+

"sellerTaxnum":"150301199811285326"

+

}

+ +### 返回参数 + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必须示例值描述最大长度
codeInteger是200

状态,0000或200-成功，

+

非0000，非200-失败

6
messageString是成功详细信息1024
+ +### 返回示例 + +示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果回传.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果回传.md new file mode 100644 index 0000000..2cbb6df --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果回传.md @@ -0,0 +1,620 @@ +--- +title: 开票结果回传 +aliases: + - 开票结果回传 + - 诺税通开票结果回传 + - 开票主链路-开票结果回传 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 开票结果回传 + +> [!info] 导航 +> 上级索引：[[README]] · [[02_开票主链路]] +> 文档链接：[总索引](../README.md) · [分组页](../02_开票主链路.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[02_开票主链路]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`用户通过开票请求中的bizCallbackUrl字段提供回调地址。` +> - 请求方式：`POST` +> - 是否回调：是 +> - 是否主链路：是 +> - 推荐优先级：P0（如采用回调模式） + + + +## 开票结果回传 + +### 接口说明 + +返回开票申请结果。 + +注意：请按照文档要求提供接口。 + +### 接口地址 + +用户通过开票请求中的bizCallbackUrl字段提供回调地址。 + +### 请求参数(用json格式接收) + + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必须示例值更多限制描述最大长度
orderNoString是订单编号64
sellerTaxnumString是339901999999610销方税号20
invoiceIdString是20011617430401068182发票流水号32
successFlagboolean是trueTrue:开票成功；false：开票失败1
vehicleFlagInteger否0可不填，默认00：非机动车。1：机动车2
productOilFlagInteger否0可不填，默认0成品油标志：0非成品油，1成品油，默认为02
invoiceStatusInteger是

发票处理结果: 1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功。

+

结果处于开票成功、 开票失败、作废成功、作废失败，开票失败删除成功触发回传

1
errorMessageString否[9999]HX1000 4003-发票数据写盘失败[TCD_769_25,离线发票累计金额超限！],发票代码或号码为空开票异常信息128
pdfUrlString否https://inv.jss.com.cn/group1/M00/A6/4C/wKgHPll_IU-AVELfAACNq5bmzFM769.pdf发票pdf地址，仅开票成功且版式文件为pdf时返回255
paperPdfUrlString否纸票pdf地址（含底图）256
imageUrlString否发票jpg地址，清单票发票主信息与清单信息以”,”隔开，仅开票成功会返回255
ofdUrlString否发票ofd地址，仅开票成功且版式文件为ofd时返回255
orderDateString否2022-05-12年-月-日订单日期10
deliverDateString否2022-05-12年-月-日发货日期10
invoiceTimeDate否1604576878000开票日期，仅开票成功会返回13
invalidTimeDate否1615985882000作废日期，仅作废成功后返回13
invoiceCodeString否125999915630发票代码，仅开票成功会返回12
invoiceNumberString否00130865发票号码，仅开票成功会返回20
allElectronicInvoiceNumberString否数电发票号码，仅数电发票（电票+纸票）开票成功会返回20
oriInvoiceCodeString否红票对应的蓝票发票代码12
oriInvoiceNumberString否红票对应的蓝票发票号码20
oldEleInvoiceNumberString否红票对应的蓝票数电发票号码20
billNoString否红字申请流水号，仅红字专票返回24
billInfoNoString否红字申请表编号，仅红字专票返回24
taxFreeAmountTotalBigDecimal否不含税金额，仅开票成功会返回15.2
taxTotalBigDecimal否税额，仅开票成功会返回15.2
taxAmountTotalBigDecimal否含税金额，仅开票成功会返回15.2
buyerNameString否浙江爱信诺购方名称，仅开票成功会返回100
buyerTaxnumString否339901999999103购方税号，仅开票成功会返回20
sellerNameString否浙江爱信诺销方名称，仅开票成功会返回100
invoiceLineString否1发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j:机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质) 仅开票成功会返回2
columnFirstString否有值就回传企业开票时传入自定义字段1
columnSecondString否有值就回传企业开票时传入自定义字段2
columnThreeString否有值就回传企业开票时传入自定义字段3
requestSrcInteger否开票方式,0:api接口 1:手工开票 2:批量导入 5:本地提取1
mailNoString否快递单号
businessTypeString否枚举值来源为基础字典配置业务类型
relatedStateInteger否有值就回传关联状态(0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败)
buyerManagerNameString否购买方经办人姓名，数电特有字段16
managerCardTypeString否101-组织机构代码证,102-营业执照,103-税务登记证, 199-其他单位证件, 201-居民身份证, 202-军官证, 203-武警警官证, 204-士兵证, 205-军队离退休干部证, 206-残疾人证, 207-残疾军人证（1-8级）, 208-外国护照, 210-港澳居民来往内地通行证, 212-中华人民共和国往来港澳通行证, 213-台湾居民来往大陆通行证, 214-大陆居民往来台湾通行证, 215-外国人居留证, 216-外交官证 299-其他个人证件经办人证件类型数电特有字段40
managerCardNoString否经办人证件号码数电特有字段，证件类型有值时必填20
billIdString否仅数电红票回传红字确认单流水号32
billConfirmNoString否仅数电红票回传红字确认单编号32
billUuidString否仅数电红票回传红字确认单UUID32
specificFactorString否

特定要素：0普通发票 01成品油 03建筑服务 04货物运输发票 05不动产销售发票 06不动产租赁发票 09旅客运输发票 14机动车 16农产品收购 33二手车反向开具

+

35 矿产品发票

2
invalidReasonInteger否数电纸票作废原因 1:销货退回;2:开票有误;3:服务中止;4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回）1
specificReasonString否其他作废原因详情（作废原因为4 且回传其他信息时返回）255
subjectAccountCodeString否T123核算主体编码维护在诺税通的“核算主体编码”200
subjectAccountString否核算主体名称核算主体名称核算主体名称200
redReasonInteger否11：销售退回2：开票有误3：服务终止4：销售折让冲红原因1
naturalPersonFlagInteger否0购买方自然人标志：0-否（默认）、1-是2
customerCodeString否客户编码64
+ +### 请求示例 + + +++ + + + + + +

{

+

"buyerName":"个人",

+

"buyerTaxnum":"339901999999142",

+

"imageUrl":"",

+

"invoiceCode":"131880930610",

+

"invoiceId":"20111014474101989690",

+

"invoiceLine":"p",

+

"invoiceNumber":"61001098",

+

"invoiceTime":1604994991000,

+

"orderNo":"20170104120207971529",

+

"pdfUrl":"https://invtest.nntest.cn/fp/tKhNlLpWjoP84chMYndBjLxrATHP7jJAEK71fHqOJVpzR7q39iU4mBTNBtjfHAANtFoj04OLAjWzfbYJIJhzhA.pdf",

+

"sellerName":"演示公司",

+

"successFlag":true,

+

"taxAmountTotal":1.09,

+

"taxFreeAmountTotal":0.09,

+

"sellerTaxnum":"339901999999610",

+

"taxTotal":0.01,

+

"taxOfficeCode":"税务机关代码",

+

"intactCertificateNum":"税务机关名称",

+

"organizationCode":"完整凭证号码",

+

"mailNo":"SF67263555514",

+

"relatedState":2,

+

"customerCode":"263555514"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | String | 是 | 0000 | | 状态码，字符串”0000”表示成功，非”0000”的字符串表示失败 | 6 | +| message | String | 是 | 同步成功 | | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": "0000",

+

"message": "业务方接收同步成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": "9999",

+

"message": "同步失败的异常信息"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果回传_含明细.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果回传_含明细.md new file mode 100644 index 0000000..c48b62f --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果回传_含明细.md @@ -0,0 +1,1825 @@ +--- +title: 开票结果回传（含明细） +aliases: + - 开票结果回传（含明细） + - 诺税通开票结果回传（含明细） + - 开票主链路-开票结果回传（含明细） +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 开票结果回传（含明细） + +> [!info] 导航 +> 上级索引：[[README]] · [[02_开票主链路]] +> 文档链接：[总索引](../README.md) · [分组页](../02_开票主链路.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[02_开票主链路]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`用户通过开票请求中的bizCallbackUrl字段提供回调地址，或读取诺税通手工配置的回调地址进行回调。` +> - 请求方式：`POST` +> - 是否回调：是 +> - 是否主链路：是 +> - 推荐优先级：P0（如采用回调模式） + + + +## 开票结果回传（含明细） + +### 接口说明 + +返回开票申请结果。 + +注意：请按照文档要求提供接口。 + +### 接口地址 + +用户通过开票请求中的bizCallbackUrl字段提供回调地址，或读取诺税通手工配置的回调地址进行回调。 + +### 请求参数(用json格式接收) + + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必须示例值更多限制描述最大长度
orderNoString是订单编号64
invoiceIdString是发票流水号20
createTimeDate是1615985882000创建日期13
invoiceTimeDate是1615985882000开票日期13
updateTimeDate是1615985882000更新时间13
orderDateString否2022-05-12年-月-日订单日期10
deliverDateString否2022-05-12年-月-日发货日期10
invalidTimeDate否1615985882000仅作废成功后返回作废日期13
requestSrcInteger否开票方式,0:api接口 1:手工开票 2:批量导入 5:本地提取1
invoiceCodeString否仅开票成功后返回发票代码12
invoiceNumberString否仅开票成功后返回发票号码20
allElectronicInvoiceNumberString否数电发票号码，仅数电发票（电票+纸票）开票成功会返回20
invoiceTypeInteger是发票类型：红字发票、蓝字发票2
oriInvoiceCodeString否红票对应的蓝票发票代码12
oriInvoiceNumberString否红票对应的蓝票发票号码20
oldEleInvoiceNumberString否红票对应的蓝票数电发票号码20
billNoString否红字申请流水号，仅红字专票返回24
billInfoNoString否红字申请表编号，仅红字专票返回24
taxTotalBigDecimal否价税税额（保留小数点后2位）30
taxFreeAmountTotalBigDecimal否不含税金额（保留小数点后2位）30
taxAmountTotalBigDecimal否价税合计 （保留小数点后2位）30
pdfUrlString否发票pdf地址256
ofdUrlString否发票ofd地址256
notifyEmailString否交付邮箱50
notifyPhoneString否交付手机20
buyerTaxnumString否购方税号20
buyerNameString否购方名称100
customerCodeString否123456蓝票 购方名称和客户编码二选一必填客户编码，如果未传入客户名称，则使用客户编码查询补充购方信息64
buyerPhoneString否购方电话50
buyerAddressString否购方地址100
buyerBankString否购方银行开户行100
buyerAccountString否购方银行账号30
checkCodeString否校验码35
qrCodeString否二维码30
invoiceCipherString否发票密文300
invoiceLineString否发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)1
sellerTaxnumString是销方税号20
sellerNameString否销方名称200
sellerPhoneString否销方电话20
sellerAddressString否销方地址80
sellerBankString否销方开户银行100
sellerAccountString否销方银行账号30
clerkerString否开票员20
payeeString否收款人20
checkerString否复核人20
remarkString否备注

数电电票：200(中文计算一位)

+

其他发票：230(中文计算两位)

productOilFlagInteger否

成品油标志:

+

0:非成品油;

+

1:成品油;

1
vehicleFlagInteger否0默认00：非机动车。1：机动车2
listFlagInteger否

清单标志：

+

0：非清单；

+

1：清单；

1
listGoodsNameString否清单项目名称90
extensionNumInteger否分机号5
machineNumberString否税控设备号（机器编码）12
terminalNumInteger否终端号10
imageUrlString否发票jpg图片地址（清单票发票主信息与清单信息以”,”隔开）256
paperPdfUrlString否纸票pdf地址（含底图）256
departmentIdLong否部门id50
userIdLong否开票员id50
invoiceStatusInteger是

发票处理结果: 1:开票成功、 2:开票失败、3:作废成功、4:作废失败；5:开票失败删除成功。

+

结果处于开票成功、 开票失败、作废成功、作废失败，开票失败删除成功触发回传

1
errorMessageString否开票异常信息：包括开票失败原因300
columnFirstString否有值就回传企业开票时传入自定义字段1
columnSecondString否有值就回传企业开票时传入自定义字段2
columnThreeString否有值就回传企业开票时传入自定义字段3
mailNoString否快递单号
businessTypeString否枚举值来源为基础字典配置业务类型
relatedStateInteger否有值就回传关联状态(0:未关联 1:关联中 2:关联成功 3:部分关联 4:关联失败)
specificFactorString否

特定要素：0普通发票 01成品油 03建筑服务 04货物运输发票 05不动产销售发票 06不动产租赁发票 09旅客运输发票 14机动车 16农产品收购 33二手车反向开具

+

35 矿产品发票

2
detailList否发票明细信息（非必须，根据企业资质配置）
buyerManagerNameString否购买方经办人姓名，数电特有字段16
managerCardNoString否经办人证件号码数电特有字段，证件类型有值时必填20
managerCardTypeString否101-组织机构代码证,102-营业执照,103-税务登记证, 199-其他单位证件, 201-居民身份证, 202-军官证, 203-武警警官证, 204-士兵证, 205-军队离退休干部证, 206-残疾人证, 207-残疾军人证（1-8级）, 208-外国护照, 210-港澳居民来往内地通行证, 212-中华人民共和国往来港澳通行证, 213-台湾居民来往大陆通行证, 214-大陆居民往来台湾通行证, 215-外国人居留证, 216-外交官证 299-其他个人证件经办人证件类型数电特有字段40
billIdString否仅数电红票回传红字确认单流水号32
billConfirmNoString否仅数电红票回传红字确认单编号32
billUuidString否仅数电红票回传红字确认单UUID32
invalidReasonInteger否数电纸票作废原因 1:销货退回;2:开票有误;3:服务中止;4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回）1
specificReasonString否其他作废原因详情（作废原因为4 且回传其他信息时返回）255
subjectAccountCodeString否T123核算主体编码维护在诺税通的“核算主体编码”200
subjectAccountString否核算主体名称核算主体名称核算主体名称200
redReasonInteger否11：销售退回2：开票有误3：服务终止4：销售折让冲红原因1
naturalPersonFlagInteger否0购买方自然人标志：0-否（默认）、1-是2
invoiceGoodsTransportsList否货物运输发票时必填货物运输明细最大长度2000
realPropertyRentObject否开具不动产租赁发票时必填不动产租赁发票信息
invoiceBuildingInfoObject否建筑服务发票时必填建筑服务信息
商品明细
detailIndexInteger否明细序号5
commodityCodeString否商品编码64
goodsNameString否商品名称90
goodsCodeAbbString否商品简称200
goodsUnitString否单位22
goodsPriceBigDecimal否根据含税标志决定是含税单价还是不含税单价含税单价32,16
taxFreePriceBigDecimal否根据含税标志决定是含税单价还是不含税单价不含税单价32,16
taxrateString否税率10
goodsNumBigDecimal否数量32,16
taxAmountBigDecimal否含税金额16.2
taxFreeAmountBigDecimal否不含税金额16.2
taxBigDecimal否税额16.2
specTypeString否规格型号40
goodsCodeString否税收分类编码19
selfCodeString否自行编码20
withTaxFlagInteger否

含税标识:

+

1:含税;

+

0:不含税;

detailTypeInteger否

发票行性质:

+

0:正常行;

+

1:折扣行;

+

2:被扣行;

1
zeroRateFlagString否

零税率标识:

+

空:非零税率;

+

1:免税;

+

2:不征税;

+

3:普通零税率;

1
favouredPolicyNameString否优惠政策名称（增值税特殊管理）50
favouredPolicyFlagInteger否

优惠政策标识:

+

0:不使用;

+

1:使用;

1
deductionBigDecimal否扣除额（保留两位小数）
columnFirstString否有值就回传自定义字段1
columnSecondString否有值就回传自定义字段2
columnThreeString否有值就回传自定义字段3
columnFourString否有值就回传自定义字段4
columnFiveString否有值就回传自定义字段5
favouredPolicyCodeString否01：简易征收 02：稀土产品 03：免税 04：不征税 05：先征后退 06：100%先征后退 07：50%先征后退 08：按3%简易征收 09：按5%简易征收 10：按5%简易征收减按1.5%计征 11：即征即退30% 12：即征即退50% 13：即征即退70% 14：即征即退100% 15：超税负3%即征即退 16：超税负8%即征即退 17：超税负12%即征即退 18：超税负6%即征即退

优惠政策编码

+

数电发票特有字段，如使用优惠政策时，该字段必填。

机动车(j)/二手车(u)明细
vehicleTypeString是发票种类为u，j时必填车辆类型40
brandModelString是发票种类为u，j时必填厂牌型号60
productOriginString是发票种类为j时必填产地32
importCertifyNumString否进口证明书号50
certificateString否合格证号36
inspectionOddNumString否商检单号32
engineNumString否发动机号码50
vehicleCodeString是发票种类为u，j时必填车辆识别单号23
intactCertificateNumString否完税凭证号码
measureUnitsString否吨位8
maxCapacityString否限乘人数12
produceCompanyNameString否厂家信息200
organizationCodeString否其他证件号30
taxOfficeCodeString否税务机关代码100
+ + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
organizeTypeString是发票种类为u时必填开票方类型：1.经营单位2.拍卖单位3.二手车市场（二手车专用）2
licenseNumberString是发票种类为u时必填车牌号码（二手车专用）20
registerCertNoString是发票种类为u时必填登记证号（二手车专用）20
vehicleManagementNameString是发票种类为u时必填转入地车辆管理所名称（二手车专用）80
salerNameString是发票种类为u时必填卖方单位/个人名称（二手车专用）80
salerNumString是发票种类为u时必填卖方单位代码/身份证号码（二手车专用）20
salerAddressString否卖方单位/个人地址（二手车专用）80
salerPhoneString否卖方电话（二手车专用）20
货物运输明细
goodsNameString否煤炭运输货物名称80
originString否北京市市辖区东城区起运地80
destinationString否北京市市辖区丰台区到达地80
transportTool否1运输工具种类：1铁路运输、2公路运输、3.水路运输、4.航空运输、5.管道运输1
transportToolNumString否车牌号DD运输工具牌号80
不动产租赁发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
rentStartDateString是2023-02-17yyyy-MM-dd格式租赁期起期10
rentEndDateString是2023-02-18yyyy-MM-dd格式租赁期止期10
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位1
建筑服务发票信息
buildingAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入建筑服务发生地-
detailedAddressString否XXXX街道XXX号建筑服务发生地+详细地址最大长度120详细地址120
landVatItemNoString否1234556土地增值税项目编号16
itemNameString是1234556项目名称80
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertySellObject否不动产销售发票时必填不动产销售发票信息
不动产销售发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位10
realPropertyContractNumberString否不动产单元代码/网签合同备案编号28
incrementTaxNumberString否土地增值税项目编号18
priceString否核定计税价格20
taxAmountString否核定计税价格有值时,实际成交含税金额必填实际成交含税金额20
invoiceTravellerTransportInfoListList否开旅客运输发票时传入出行人信息出行人信息
出行人信息
travellerString是出行人20
travelDateString是年-月-日格式出行日期 年-月-日10
travellerCardTypeString是

101-组织机构代码证

+

102-营业执照

+

103-税务登记证

+

199-其他单位证件

+

201-居民身份证

+

202-军官证

+

203-武警警官证

+

204-士兵证

+

205-军队离退休干部证

+

206-残疾人证

+

207-残疾军人证（1-8级）

+

208-外国护照

+

210-港澳居民来往内地通行证

+

212-中华人民共和国往来港澳通行证

+

213-台湾居民来往大陆通行证

+

214-大陆居民往来台湾通行证

+

215-外国人居留证

+

216-外交官证

+

217-使（领事）馆证

+

218-海员证

+

219-香港永久性居民身份证

+

220-台湾身份证

+

221-澳门特别行政区永久性居民身份证

+

222-外国人身份证件

+

224-就业失业登记证

+

225-退休证

+

226-离休证

+

227-中国护照

+

228-城镇退役士兵自谋职业证

+

229-随军家属身份证明

+

230-中国人民解放军军官转业证书

+

231-中国人民解放军义务兵退出现役证

+

232-中国人民解放军士官退出现役证

+

233-外国人永久居留身份证（外国人永久居留证）

+

234-就业创业证

+

235-香港特别行政区护照

+

236-澳门特别行政区护照

+

237-中华人民共和国港澳居民居住证

+

238-中华人民共和国台湾居民居住证

+

239-《中华人民共和国外国人工作许可证》（A类）

+

240-《中华人民共和国外国人工作许可证》（B类）

+

241-《中华人民共和国外国人工作许可证》（C类）

+

291-出生医学证明

+

299-其他个人证件

出行人证件类型5
travellerCardNoString是出行人证件号码20
travelPlaceString是出行地80
arrivePlaceString是到达地80
vehicleTypeInteger是
    +

  1. 飞机

    2. +

  2. 火车

    3. +

  3. 长途汽车

    4. +

  4. 公共交通

    5. +

  5. 出租车

    6. +

  6. 汽车

    7. +

  7. 船舶

    +

    9-其他

    8. +
交通工具类型2
vehicleLevelString否

当交通工具类型是火车、飞机、船舶时必填选择，其他交通工具时可选填

+

当交通工具类型是火车时，必填，下拉框选择，可选项是 一等座、二等座、软席（软座、软卧）、硬卧（硬座、硬卧）

+

当交通工具类型是飞机时，必填，下拉框选择，可选项是 公务舱、头等舱、经济舱

+

当交通工具类型是船舶事，必填，下拉框选择，可选项是 一等舱、二等舱、三等舱

+

当交通工具类型是其他时，选填

交通工具等级20
+ +### 请求示例 + + +++ + + + + + +

{

+

    "businessType": "0",

+

    "buyerAccount": "111111",

+

    "buyerAddress": "杭州市",

+

    "buyerBank": "中国工商银行  ",

+

    "buyerName": "冲红原因测试用蓝票",

+

    "buyerPhone": "",

+

    "buyerTaxnum": "91610132MA6W2MHJ1E",

+

    "checker": "",

+

    "clerker": "张三",

+

    "columnFirst": "主表自定义标识1",

+

    "columnSecond": "主表自定义标识2",

+

    "columnThree": "主表自定义标识3",

+

    "companyCode": "1100",

+

    "companyId": 10162,

+

    "createTime": 1643340360000,

+

    "deliverDate": "Tue Apr 19 15:48:57 CST 2022",

+

    "detail": [

+

        {

+

            "columnFirst": "详情表自定义1",

+

            "columnFive": "详情表自定义5",

+

            "columnFour": "详情表自定义4",

+

            "columnSecond": "详情表自定义2",

+

            "columnThree": "详情表自定义3",

+

            "detailIndex": 0,

+

            "detailType": 0,

+

            "favouredPolicyFlag": 0,

+

            "favouredPolicyName": "",

+

            "goodsCode": "1070101010100000000",

+

            "goodsCodeAbb": "汽油",

+

            "goodsName": "电脑",

+

            "goodsNum": -1.0000000000000000,

+

            "goodsPrice": 11.3000000000000000,

+

            "goodsUnit": "升",

+

            "selfCode": "10701010101",

+

            "specType": "Y460",

+

            "tax": -1.30,

+

            "taxAmount": -11.30,

+

            "taxFreeAmount": -10.00,

+

            "taxFreePrice": 10.0000000000000000,

+

            "taxrate": "0.13",

+

            "withTaxFlag": 0,

+

            "zeroRateFlag": ""

+

        }

+

    ],

+

    "invoiceCode": "033002000911",

+

    "invoiceLine": "p",

+

    "invoiceNumber": "36831764",

+

    "invoiceType": 2,

+

    "listFlag": 0,

+

    "listGoodsName": "详见销货清单",

+

    "orderNo": "20220223134754150666",

+

    "payee": "",

+

    "productOilFlag": 1,

+

    "remark": "对应正数发票代码:033002000911号码:36831764",

+

    "requestSrc": 6,

+

    "sellerAccount": "123",

+

    "sellerAddress": "123",

+

    "sellerBank": "213",

+

    "sellerName": "移动测试盘326",

+

    "sellerPhone": "123",

+

    "sellerTaxnum": "150301199811285326",

+

    "substituteFlag": 0,

+

    "userId": 1,

+

    "invoiceTime": "2021-03-12T14:59:25.715",

+

    "taxAmountTotal": "12.01",

+

"taxFreeAmountTotal": "12.01",

+

"taxTotal": "12.01",

+

    "mailNo": "SF67263555514",

+

"relatedState":2,

+

"customerCode":"263555514"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | String | 是 | 0000 | | 状态码，字符串”0000”表示成功，非”0000”的字符串表示失败 | 6 | +| message | String | 是 | 同步成功 | | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": "0000",

+

"message": "业务方接收同步成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": "9999",

+

"message": "同步失败的异常信息"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果查询接口.md new file mode 100644 index 0000000..b521b8f --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票结果查询接口.md @@ -0,0 +1,1995 @@ +--- +title: 开票结果查询接口 +aliases: + - 开票结果查询接口 + - 诺税通开票结果查询接口 + - 开票主链路-开票结果查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 开票结果查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[02_开票主链路]] +> 文档链接：[总索引](../README.md) · [分组页](../02_开票主链路.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[02_开票主链路]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/query-invoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P0 + + + +## 开票结果查询接口 + +### 接口说明 + +通过该接口提交流水号或订单号信息，查询开票结果。 + +### 接口地址 + +| | +|:-----------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/query-invoice.do | + +### 请求参数 + + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值更多限制描述最大长度
invoiceIdString[]否20092114394901000002流水号列表与订单号列表、发票号码列表、数电号码四选一，单次最多支持查询50个流水号。流水号列表单个参数最大长度20
orderNoString[]否20170104120207971529

流水号列表与订单号列表、发票号码列表、数电号码四选一，单次最多支持

+

查询50个订单号。

订单号列表单个参数最大长度64
invoiceNumberString[]否["93667697", "93667694"]

流水号列表与订单号列表、发票号码列表、数电号码四选一，单次最多支持

+

查询50个发票号码

发票号码列表
invoiceCodeString否5000201530使用发票号码列表查询时必传，数电电票该字段为空，传入发票号码，未传入发票代码默认为查询数电电票发票代码
fuzzyFlagBoolean否false默认为false订单号是否模糊查询，当orderNo列表元素个数为1且本字段为true时，可以模糊查询订单号对应的发票记录1
sellerTaxnumString否7010412020797152企业税号和组织编码必填其一企业税号20
companyCodeString否企业税号和组织编码必填其一组织编码20
returnInvoiceDetailFlagBoolean否true默认为true返回发票明细标识1
allElectronicInvoiceNumberString[]否

支持

+

查询50个数电发票发票号码，流水号列表与订单号列表、发票号码列表、数电号码四选一

数电发票号码（数电电票、数电纸票都支持）单个参数最大20
+ +### 请求示例 + + +++ + + + + + +

{

+

"invoiceId": ["20111014474101989690", "20111014550501989882"],

+

"sellerTaxnum": "339901999999610",

+

"returnInvoiceDetailFlag": true

+

}

+ +### 返回参数： + + +++++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值更多限制描述最大长度
codeInteger是200状态,200-成功，非200-失败6
messageString查询成功详细信息1024
dataList18081620564001000232查询成功则返回发票信息
发票信息
orderNoString否20170104120207971529订单号64
invoiceIdString否20092114394901000002流水号20
statusInteger否2开票状态(0:开票中1:开票完成2:开票失败3:发票生成2
invalidStateInteger否0发票作废状态: 0 未提交 , 1 作废成功 , 2 作废失败 , 3 已提交(作废中)。默认值02
invalidTimeString否1604576878000发票作废时间
orderDateString否2022-05-12年-月-日订单日期10
deliverDateString否2022-05-12年-月-日发货日期10
errorMessageString否[9999]HX1000 4003-发票数据写盘失败[TCD_769_25,离线发票累计金额超限！],发票代码或号码为空开票异常信息128
pdfUrlString否https://inv.jss.com.cn/group1/M00/A6/4C/wKgHPll_IU-AVELfAACNq5bmzFM769.pdf发票pdf地址255
paperPdfUrlString否PDF含底图255
imageUrlString否发票jpg地址，清单票发票主信息与清单信息以”,”隔开255
ofdUrlString否发票ofd地址255
invoiceTimeString否1604576878000开票日期19
invoiceCodeString否125999915630发票代码12
invoiceNumberString否00130865发票号码20
allElectronicInvoiceNumberString否数电发票号码20
taxFreeAmountTotalBigDecimal否不含税金额15.2
taxTotalBigDecimal否税额15.2
taxAmountTotalBigDecimal否含税金额15.2
buyerNameString否浙江爱信诺购方名称100
buyerTaxnumString否339901999999103购方税号20
buyerAddressString否浙江省杭州市万塘路购方地址100
buyerPhoneString否15858585858购方电话50
buyerBankString否购方开户行购方开户行100
buyerAccountString否购方银行账号购方银行账号30
invoiceLineString否1发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票，bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)2
checkCodeString否校验码20
qrCodeString否二维码3000
machineNumberString否机器编号12
invoiceCipherString否发票密文300
clerkerString否张三开票人20
payeeString否李四收款人20
checkerString否王五复核人20
sellerNameString否浙江爱信诺销方名称100
sellerTaxnumString否330100555190356销方税号20
sellerAddressString否杭州市西湖区万塘路销方地址100
sellerPhoneString否0571-81029365销方电话20
sellerBankString否开户行销方开户行100
sellerAccountString否开户行账号销方开户行账号30
remarkString否备注信息备注

数电电票：200(中文计算一位)

+

其他发票：230(中文计算两位)

productOilFlagInteger否0

成品油标志，

+

0:非成品油;

+

1:成品油

2
vehicleFlagInteger否0默认00：非机动车。1：机动车2
extensionNumInteger否开票请求分机号,范围为0-655355
terminalNumInteger否开票请求终端号5
notifyPhoneString否推送手机20
notifyEmailString否test@xx.com推送邮箱50
deptIdString否9F7E9439CA8B4C60A2FFF3EA3290B088部门门店id（诺诺系统中的id）32
clerkIdString否3F7EA439CA8B4C60A2FFF3EA3290B084开票员id（诺诺系统中的id）32
oriInvoiceCodeString否125999915630原发票代码12
oriInvoiceNumberString否00130865原发票号码8
oldEleInvoiceNumberString否红票对应的蓝票数电发票号码20
listFlagInteger否0

清单标志，

+

0:非清单，1:清单

2
listGoodsNameString否详见销货清单注意：税局要求清单项目名称为（详见销货清单）90
columnFirstString否业务调用方自定义字段一业务调用方自定义字段一255
columnSecondString否业务调用方自定义字段二业务调用方自定义字段二255
columnThreeString否业务调用方自定义字段三业务调用方自定义字段三255
projectCodeString否项目编码64
projectNameString否项目名称300
mailNoString否快递单号
businessTypeString否1枚举值来源为基础字典配置业务类型
buyerManagerNameString否购买方经办人姓名，数电特有字段16
managerCardTypeString否101-组织机构代码证,102-营业执照,103-税务登记证, 199-其他单位证件, 201-居民身份证, 202-军官证, 203-武警警官证, 204-士兵证, 205-军队离退休干部证, 206-残疾人证, 207-残疾军人证（1-8级）, 208-外国护照, 210-港澳居民来往内地通行证, 212-中华人民共和国往来港澳通行证, 213-台湾居民来往大陆通行证, 214-大陆居民往来台湾通行证, 215-外国人居留证, 216-外交官证 299-其他个人证件经办人证件类型数电特有字段40
managerCardNoString否经办人证件号码数电特有字段，证件类型有值时必填20
ccPhoneString否抄送手机，多个以英文逗号分隔100
ccEmailString否抄送邮箱，多个以英文逗号分隔250
specificFactorString否

特定要素：0普通发票 01成品油 03建筑服务 04货物运输发票 05不动产销售发票 06不动产租赁发票 09旅客运输发票 14机动车 16农产品收购 33二手车反向开具

+

35 矿产品发票

2
invalidReasonInteger否数电纸票作废原因 1:销货退回;2:开票有误;3:服务中止;4:其他（已作废状态下的发票，且票为数电纸票且回传其他信息时返回）1
specificReasonString否其他作废原因详情（作废原因为4 且回传其他信息时返回）255
naturalPersonFlagInteger否0购买方自然人标志：0-否（默认）、1-是2
redReasonInteger否11：销售退回2：开票有误3：服务终止4：销售折让冲红原因1
subjectAccountCodeString否T123核算主体编码维护在诺税通的“核算主体编码”200
subjectAccountString否核算主体名称核算主体名称核算主体名称200
customerCodeString否客户编码64
invoiceGoodsTransportsList否货物运输发票时必填货物运输明细最大长度2000
发票明细
detailIndexInteger否0明细行序号5
goodsNameString否商品名称90
taxrateString否0.16税率10
withTaxFlagInteger否

单价含税标志:

+

0:不含税;

+

1:含税

2
taxFreePriceBigDecimal否不含税单价32.16
goodsPriceBigDecimal否含税单价32.16
goodsNumBigDecimal否数量32.16
taxAmountBigDecimal否含税金额15.2
taxFreeAmountBigDecimal否不含税金额15.2
taxBigDecimal否税额15.2
goodsUnitString否单位22
specTypeString否规格型号40
commodityCodeString否商品编码64
goodsCodeString否税收分类编码19
goodsCodeAbbString否税收分类编码简称200
detailTypeInteger否

明细行性质:

+

0:正常行;

+

1:折扣行;

+

2:被折扣行

2
favouredPolicyFlagInteger否

优惠政策标识:

+

0:不使用;

+

1:使用

2
favouredPolicyNameString否优惠政策内容，如：即征即退、免税、简易征收 等50
zeroRateFlagInteger否

零税率标识:

+

空:非零税率;

+

1:免税;

+

2:不征税;

+

3:普通零税率

2
selfCodeString否自行编码20
deductionBigDecimal否扣除额15.2
columnFirstString否自定义字段1255
columnSecondString否自定义字段2255
columnThreeString否自定义字段3255
columnFourString否自定义字段4255
columnFiveString否自定义字段5255
favouredPolicyCodeString否01：简易征收 02：稀土产品 03：免税 04：不征税 05：先征后退 06：100%先征后退 07：50%先征后退 08：按3%简易征收 09：按5%简易征收 10：按5%简易征收减按1.5%计征 11：即征即退30% 12：即征即退50% 13：即征即退70% 14：即征即退100% 15：超税负3%即征即退 16：超税负8%即征即退 17：超税负12%即征即退 18：超税负6%即征即退

优惠政策编码

+

数电发票特有字段

机动车(j)/二手车(u)发票明细
vehicleTypeString否车辆类型40
brandModelString否厂牌型号60
productOriginString否产地32
certificateString否合格证号50
importCertifyNumString否进口证明书号50
inspectionOddNumString否商检单号50
engineNumString否发动机号码50
vehicleCodeString否车辆识别代号/车架号码50
taxOfficeCodeString否主营税务机关及代码100
intactCertificateNumString否完税凭证号码50
measureUnitsString否吨位20
maxCapacityString否限乘人数10
produceCompanyNameString否生产企业名称50
organizationCodeString否339901999999103其他证件号码30
organizeTypeString是发票种类为二手车发票返回开票方类型：1.经营单位2.拍卖单位3.二手车市场（二手车专用）2
licenseNumberString是发票种类为二手车发票返回车牌号码（二手车专用）20
registerCertNoString是发票种类为二手车发票返回登记证号（二手车专用）20
vehicleManagementNameString是发票种类为二手车发票返回转入地车辆管理所名称（二手车专用）80
salerNameString是发票种类为二手车发票返回卖方单位/个人名称（二手车专用）80
salerNumString是发票种类为二手车发票返回卖方单位代码/身份证号码（二手车专用）20
salerAddressString否卖方单位/个人地址（二手车专用）80
salerPhoneString否卖方电话（二手车专用）20
货物运输明细
goodsNameString否煤炭运输货物名称80
originString否北京市市辖区东城区起运地80
destinationString否北京市市辖区丰台区到达地80
transportTool否1运输工具种类：1铁路运输、2公路运输、3.水路运输、4.航空运输、5.管道运输1
transportToolNumString否车牌号DD运输工具牌号80
不动产租赁发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
rentStartDateString是2023-02-17yyyy-MM-dd格式租赁期起期10
rentEndDateString是2023-02-18yyyy-MM-dd格式租赁期止期10
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位1
建筑服务发票信息
buildingAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入建筑服务发生地-
detailedAddressString否XXXX街道XXX号建筑服务发生地+详细地址最大长度120详细地址120
landVatItemNoString否1234556土地增值税项目编号16
itemNameString是1234556项目名称80
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertySellObject否不动产销售发票时必填不动产销售发票信息
不动产销售发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位10
realPropertyContractNumberString否不动产单元代码/网签合同备案编号28
incrementTaxNumberString否土地增值税项目编号18
priceString否核定计税价格20
taxAmountString否核定计税价格有值时,实际成交含税金额必填实际成交含税金额20
invoiceTravellerTransportInfoListList否开旅客运输发票时传入出行人信息出行人信息
出行人信息
travellerString是出行人20
travelDateString是年-月-日格式出行日期 年-月-日10
travellerCardTypeString是

101-组织机构代码证

+

102-营业执照

+

103-税务登记证

+

199-其他单位证件

+

201-居民身份证

+

202-军官证

+

203-武警警官证

+

204-士兵证

+

205-军队离退休干部证

+

206-残疾人证

+

207-残疾军人证（1-8级）

+

208-外国护照

+

210-港澳居民来往内地通行证

+

212-中华人民共和国往来港澳通行证

+

213-台湾居民来往大陆通行证

+

214-大陆居民往来台湾通行证

+

215-外国人居留证

+

216-外交官证

+

217-使（领事）馆证

+

218-海员证

+

219-香港永久性居民身份证

+

220-台湾身份证

+

221-澳门特别行政区永久性居民身份证

+

222-外国人身份证件

+

224-就业失业登记证

+

225-退休证

+

226-离休证

+

227-中国护照

+

228-城镇退役士兵自谋职业证

+

229-随军家属身份证明

+

230-中国人民解放军军官转业证书

+

231-中国人民解放军义务兵退出现役证

+

232-中国人民解放军士官退出现役证

+

233-外国人永久居留身份证（外国人永久居留证）

+

234-就业创业证

+

235-香港特别行政区护照

+

236-澳门特别行政区护照

+

237-中华人民共和国港澳居民居住证

+

238-中华人民共和国台湾居民居住证

+

239-《中华人民共和国外国人工作许可证》（A类）

+

240-《中华人民共和国外国人工作许可证》（B类）

+

241-《中华人民共和国外国人工作许可证》（C类）

+

291-出生医学证明

+

299-其他个人证件

出行人证件类型5
travellerCardNoString是出行人证件号码20
travelPlaceString是出行地80
arrivePlaceString是到达地80
vehicleTypeInteger是
    +

  1. 飞机

    2. +

  2. 火车

    3. +

  3. 长途汽车

    4. +

  4. 公共交通

    5. +

  5. 出租车

    6. +

  6. 汽车

    7. +

  7. 船舶

    +

    9-其他

    8. +
交通工具类型2
vehicleLevelString否

当交通工具类型是火车、飞机、船舶时必填选择，其他交通工具时可选填

+

当交通工具类型是火车时，必填，下拉框选择，可选项是 一等座、二等座、软席（软座、软卧）、硬卧（硬座、硬卧）

+

当交通工具类型是飞机时，必填，下拉框选择，可选项是 公务舱、头等舱、经济舱

+

当交通工具类型是船舶事，必填，下拉框选择，可选项是 一等舱、二等舱、三等舱

+

当交通工具类型是其他时，选填

交通工具等级20
+ +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message":"成功",

+

"data":[

+

{

+

"orderNo":"20170104120207971529",

+

"invoiceId":"20111014474101989690",

+

"status":1,

+

"errorMessage":null,

+

"pdfUrl":"https://invtest.nntest.cn/fp/tKhNlLpWjoP84chMYndBjLxrATHP7jJAEK71fHqOJVpzR7q39iU4mBTNBtjfHAANtFoj04OLAjWzfbYJIJhzhA.pdf",

+

"imageUrl":"",

+

"ofdUrl":null,

+

"invoiceTime":"1604994991000",

+

"invalidTime":"1604576878000",

+

"invoiceCode":"131880930610",

+

"invoiceNumber":"61001098",

+

"taxAmountTotal":"1.09",

+

"taxFreeAmountTotal":"1.00",

+

"taxTotal":"0.09",

+

"buyerName":"个人",

+

"buyerTaxnum":"339901999999142",

+

"buyerAddress":"浙江省杭州市",

+

"buyerPhone":"0571-00000000",

+

"buyerBank":"开户行",

+

"buyerAccount":"银行账号",

+

"invoiceLine":"p",

+

"checkCode":"",

+

"qrCode":"",

+

"machineNumber":"",

+

"invoiceCipher":"",

+

"clerker":"开票员",

+

"payee":"收款人",

+

"checker":"复核人",

+

"sellerName":"演示公司",

+

"sellerTaxnum":"339901999999610",

+

"sellerPhone":"0571-00000000",

+

"sellerAddress":"杭州市西湖区",

+

"sellerBank":"开户行",

+

"sellerAccount":"0000000000000000",

+

"remark":"备注信息",

+

"productOilFlag":0,

+

"extensionNum":null,

+

"terminalNum":null,

+

"notifyPhone":"",

+

"notifyEmail":"",

+

"deptId":"",

+

"clerkId":"",

+

"oriInvoiceCode":null,

+

"oriInvoiceNumber":null,

+

"listFlag":0,

+

"listGoodsName":"",

+

"mailNo": "SF67263555514",

+

"customerCode": "555514",

+

"detail":[

+

{

+

"detailIndex":0,

+

"detailType":0,

+

"goodsName":"苹果",

+

"withTaxFlag":0,

+

"goodsPrice":"1.09",

+

"taxFreePrice":"1",

+

"goodsNum":"1",

+

"taxrate":"0.09",

+

"specType":"20个",

+

"goodsUnit":"箱",

+

"goodsCode":"1010115010100000000",

+

"goodsCodeAbb":"水果",

+

"favouredPolicyFlag":0,

+

"zeroRateFlag":"",

+

"favouredPolicyName":"",

+

"selfCode":null,

+

"deduction":null,

+

"taxAmount":"1.09",

+

"taxFreeAmount":"1.00",

+

"tax":"0.09",

+

"vehicleType":"三轮运输车",

+

"brandModel":"厂牌型号",

+

"productOrigin":"产地",

+

"certificate":"合格证号",

+

"importCertifyNum":"进出口证明书号",

+

"inspectionOddNum":"商检单号",

+

"engineNum":"发动机号",

+

"vehicleCode":"车辆识别代号",

+

"measureUnits":"吨",

+

"maxCapacity":"10",

+

"organizationCode":"组织机构代码",

+

"produceCompanyName":"生产企业名称",

+

"columnFirst":"自定义字段1",

+

"columnSecond":"自定义字段2",

+

"columnThree":"自定义字段3",

+

"columnFour":"自定义字段4",

+

"columnFive":"自定义字段5"

+

}

+

]

+

},

+

{

+

"orderNo":"20201110001",

+

"invoiceId":"20111014550501989882",

+

"status":1,

+

"errorMessage":null,

+

"pdfUrl":"https://invtest.nntest.cn/fp/eu9ulvNPRnZ_0KVsgVBWhKv6Yx8mV4j5hg5-lByUWwB7yu5Jt1gj8nFXU6waJw2kZHAidBnetXYuB1SSseZCuw.pdf",

+

"imageUrl":"",

+

"ofdUrl":null,

+

"invoiceTime":"1604995415000",

+

"invoiceCode":"131880930610",

+

"invoiceNumber":"61001099",

+

"taxAmountTotal":"1.09",

+

"taxFreeAmountTotal":"1.00",

+

"taxTotal":"0.09",

+

"buyerName":"个人",

+

"buyerTaxnum":"339901999999142",

+

"buyerAddress":"浙江省杭州市",

+

"buyerPhone":"0571-00000000",

+

"buyerBank":"开户行",

+

"buyerAccount":"银行账号",

+

"invoiceLine":"p",

+

"checkCode":"",

+

"qrCode":"",

+

"machineNumber":"",

+

"invoiceCipher":"",

+

"clerker":"开票员",

+

"payee":"收款人",

+

"checker":"复核人",

+

"sellerName":"演示公司",

+

"sellerTaxnum":"339901999999610",

+

"sellerPhone":"0571-00000000",

+

"sellerAddress":"杭州市西湖区",

+

"sellerBank":"开户行",

+

"sellerAccount":"0000000000000000",

+

"remark":"备注信息",

+

"productOilFlag":0,

+

"extensionNum":null,

+

"terminalNum":null,

+

"notifyPhone":"",

+

"notifyEmail":"",

+

"deptId":"",

+

"clerkId":"",

+

"oriInvoiceCode":null,

+

"oriInvoiceNumber":null,

+

"listFlag":0,

+

"listGoodsName":"",

+

"customerCode":"263555514",

+

"detail":[

+

{

+

"detailIndex":0,

+

"detailType":0,

+

"goodsName":"苹果",

+

"withTaxFlag":0,

+

"goodsPrice":null,

+

"taxFreePrice":null,

+

"goodsNum":null,

+

"taxrate":"0.09",

+

"specType":"20个",

+

"goodsUnit":"箱",

+

"goodsCode":"1010115010100000000",

+

"goodsCodeAbb":"水果",

+

"favouredPolicyFlag":0,

+

"zeroRateFlag":"",

+

"favouredPolicyName":"",

+

"selfCode":null,

+

"deduction":null,

+

"taxAmount":"1.09",

+

"taxFreeAmount":"1.00",

+

"tax":"0.09",

+

"vehicleType":"三轮运输车",

+

"brandModel":"厂牌型号",

+

"productOrigin":"产地",

+

"certificate":"合格证号",

+

"importCertifyNum":"进出口证明书号",

+

"inspectionOddNum":"商检单号",

+

"engineNum":"发动机号",

+

"vehicleCode":"车辆识别代号",

+

"measureUnits":"吨",

+

"maxCapacity":"10",

+

"organizationCode":"组织机构代码",

+

"produceCompanyName":"生产企业名称",

+

"columnFirst":"自定义字段1",

+

"columnSecond":"自定义字段2",

+

"columnThree":"自定义字段3",

+

"columnFour":"自定义字段4",

+

"columnFive":"自定义字段5"

+

}

+

]

+

}

+

]

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code":2751,

+

"message":"企业税号不能为空"

+

}

+ +### 状态码说明 + +| | | +|:----------:|:--------------------------------------------:| +| **状态码** | **描述** | +| 2751 | 企业税号不能为空 | +| 2752 | 入参发票流水号数组和订单编号数组只能选择一个 | +| 2753 | 入参长度超过50 | +| 2754 | 模糊搜索的订单数组长度不等于1 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票请求接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票请求接口.md new file mode 100644 index 0000000..96bd62d --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/开票请求接口.md @@ -0,0 +1,2056 @@ +--- +title: 开票请求接口 +aliases: + - 开票请求接口 + - 诺税通开票请求接口 + - 开票主链路-开票请求接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 开票请求接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[02_开票主链路]] +> 文档链接：[总索引](../README.md) · [分组页](../02_开票主链路.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[02_开票主链路]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/invoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：是 +> - 推荐优先级：P0 + + + +## 开票请求接口 + +### 接口说明 + +通过该接口提交订单信息，如销方、购方、开票明细等信息，发起开票请求。 + +注意：该接口仅返回是否提交开票申请成功，提交成功后，如税盘等开票成功，则开票状态会更新为开票完成；如果开票失败，则会变更为开票失败，且返回失败原因。 + +数电发票开具红票请使用快捷冲红接口，该接口暂不支持开具数电发票红票。请求开具数电发票蓝票时，需保证在开具时明细序号为从1开始的连续数字，否则不支持部分红冲业务！ + +针对特殊发票开具的要求： + +1. 货物运输发票：商品明细detail中商品名称必填、金额必填、税率必填、税额必填、单位非必填、数量非必填、单价非必填 + +2. 不动产经营租赁服务发票:商品明细detail只能有一行，且规格型号、单位不能有值，数量、单价必填 + +3. 建筑服务发票:商品明细detail只能有一行，且规格型号、单位、数量、单价都不能有值 + +4. 针对矿产品发票：只支持纸专、电普、纸普、电专开具，商品明细detail单位、数量、单价都必填，税收分类编码编码必须102开头 + +### 接口地址 + +| | +|:-----------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/invoice.do | + +### 请求参数 + + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值更多限制描述最大长度
buyerNameString否个人蓝票 购方名称和客户编码二选一必填购方名称100
customerCodeString否123456蓝票 购方名称和客户编码二选一必填客户编码，如果未传入客户名称，则使用客户编码查询补充购方信息64
buyerTaxnumString否339901999999142企业要填，个人可为空购方税号开具机动车销售统一发票时，该字段仅用于填写企业税号或中国居民身份证号
buyerAddressString否浙江省杭州市企业要填，个人可为空购方地址100
buyerPhoneString否0571-00000000企业要填，个人可为空，购方地址+购方电话不得超过100个字符购方电话50
buyerBankString否开户行企业要填，个人可为空购方开户行100
buyerAccountString否银行账号企业要填，个人可为空，开户行+银行账户不得超过100个字符购方银行账号30
orderNoString是20170104120207971529每个企业唯一订单编号64
sellerNameString否演示公司不填写时，以维护在诺税通组织管理中的销方名称为准，如未维护则会报错销方名称100
sellerTaxnumString否339901999999610销方税号20
companyCodeString否如果销方税号有值，优先以销方税号为准

维护在诺税通组织管理中的“公司编码”。sellerTaxnum、companyCode至少填一个。

+

用来关联出诺税通系统内的“companyId”字段。

sellerAddressString否杭州市西湖区不填写时，以维护在诺税通开票信息中的销方地址为准，发票种类为j：机动车发票时，非必填销方地址100
sellerPhoneString否0571-00000000

不填写时，以维护在诺税通开票信息中的销方电话为准，1.发票种类为j：机动车发票时，非必填

+

2，销方地址+销方电话不得超过100个字符

销方电话20
sellerBankString否中国工商银行不填写时，以维护在诺税通开票信息中的销方开户银行为准，发票种类为j：机动车发票时，非必填销方开户银行100
sellerAccountString否0000000000000000

不填写时，以维护在诺税通开票信息中的销方银行账号为准，发票种类为j：机动车发票时，非必填；

+

开户银行+银行账户不得超过100个字符

销方银行账号30
invoiceTypeInteger是1开票类型，1:蓝票；2:红票2
checkBlueInteger是0invoiceType =2时需要传，默认0开具红票时是否校验蓝票 0.校验蓝票是否存在诺税通 1.不校验蓝票是否存在诺税通但校验可冲红金额 2.不校验蓝票是否存在诺税通且不校验可冲红金额2
invoiceLineString否p默认为电票p。发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，b:增值税电子专用发票，j：机动车发票，u：二手车发票,bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)2
requestSrcInteger是0默认为0请求来源，0 :api接口，可自定义，但必须是诺税通已维护好的枚举值1
remarkString否备注信息冲红时，必须在备注中注明“对应正数发票代码:XXXXXXXXX号码:YYYYYYYY”文案，其中“X”为发票代码，“Y”为发票号码，否则接口会自动添加该文案；发票种类为j：机动车发票时，备注需注明：“一车一票”否则接口会自动添加该文案备注，（注意：不同开票服务器类型支持的备注长度不同，请在提交前做好确认）

数电电票：200(中文计算一位)

+

其他发票：230(中文计算两位)

clerkerString否开票员不填写时，以维护在诺税通开票信息的企业维度开票人为准，如未维护则会报错开票人20
payeeString否收款人不填写时，以维护在诺税通开票信息的企业维度收款人为准收款人20
checkerString否复核人不填写时，以维护在诺税通开票信息的企业维复核人为准复核人20
invoiceCodeString否125999915630红票必填，10位或12位，11位的发票代码请左补0至12位对应蓝票发票代码12
invoiceNumberString否00130865红票必填，增值税发票不满8位请左补0，数电发票20位对应蓝票发票号码20
notifyTypeInteger是1推送方式，-1:不推送;0:邮箱;1:手机(默认);2:邮箱、手机2
notifyPhoneString否10000000000推送手机(开票成功会短信提醒购方，推送方式为1或2时，此项必填)20
notifyEmailString否test@xx.com推送邮箱（推送方式为0或2时，此项必填）50
listFlagInteger是0默认为0。清单标志，0:非清单；1:清单，纸票超过8行自动转成清单，电票无清单概念，默认都传02
listGoodsNameString否详见销货清单listFlag为1时，此项为必填注意：税局要求清单项目名称固定为：（详见销货清单）90
extensionNumInteger否

开票设备分机号,范围为0-65535，

+

如需指定设备开票则需传入

5
terminalNumInteger否开票设备终端号，如需指定设备开票则需传入5
machineNumString否机器编号，如需指定设备开票则需传入
substituteFlagInteger是0默认为0代开标志，0:非代开;1:代开。代开蓝票备注文案要求包含：“代开企业税号:***代开企业名称:***.”；代开红票备注文案要求：“对应正数发票代码:***号码:***代开企业税号:***代开企业名称:***.”。（代开企业税号与代开企业名称之间仅支持一个空格或无符号）1
departmentIdLong否开票员所属部门id（诺税通本地系统中的id），如需在诺税通中根据部门筛选查看发票，则可传入32
departmentCodeString否如果departmentId有值，优先以departmentId为准

维护在诺税通部门管理中的“部门编码”。

+

用来关联出诺税通系统内的“departmentId”字段。

userIdLong否开票员用户id（诺税通系统中的id），如需在诺税通中根据开票员筛选查看发票，则可传入32
userCodeString否如果userId有值，优先以userId为准

维护在诺税通用户管理中的“用户编码”。

+

用来关联出诺税通系统内的“userId”字段。

specificFactorString否0开具货物运输发票时，必填04

特定要素：0普通发票 01成品油 03建筑服务 04货物运输发票 05不动产销售发票 06不动产租赁发票09旅客运输发票 14机动车 16农产品收购 33二手车反向开具

+

35 矿产品发票

2
naturalPersonFlagInteger否0非数电普票(电子)发票不支持自然人，传1将报错购买方自然人标志：0-否（默认）、1-是；开具数电普票(电子)时，如受票方（发票抬头）为自然人，并要求能将发票归集在个人票夹中展示，需提供姓名及身份证号（自然人纳税人识别号）；此参数传1；如受票方（发票抬头）为个体工商户，需提供社会统一信用代码或纳税人识别号，此参数传02
naturalPersonVerifyFlagInteger否0若不传，则默认取开票规则配置，若传了则以传入的为准购方名称校验：0-不强制开具，1-校验；传入0且【购方自然人标志】传入0时，若购方名称小于等于4，则会按非自然人继续开票；传入1且【购买方自然人标志】传入0时，若购方名称小于等于4，会拦截开票。1
taxNumVerifyFlagInteger否0若不传，则默认取开票规则配置，若传了则以传入的为准对购方税号校验：0-不校验（若税号在电子税局中不存在，也能继续开票），1校验（若税号在电子税局中不存在则不能开票）1
billInfoNoString否1403011904008472增值税专票冲红时，此项必填。且必须在备注中注明“开具红字增值税专用发票信息表编号ZZZZZZZZZZZZZZZZ”字样，其中“Z”为开具红字增值税专用发票所需要的长度为16位信息表编号。红字信息表编号16
columnFirstString否业务方个性化字段,本应用只作保存。255
columnSecondString否业务方个性化字段,本应用只作保存。255
columnThreeString否业务方个性化字段,本应用只作保存255
bizCallbackUrlString否业务方所请求开票的系统接收发票开票结果的回传地址业务方发票开票开票成功/失败、作废结果回调地址255
exchangeRateString否汇率
exchangeRateTimeDate否汇率日期yyyy-MM-dd格式
contractNoString否合同号
waybillNoString否提运单号
businessTypeString否默认0业务标识(基础模块设置的业务类型枚举值)
shippingFeeBigDecimal否海运费
insuranceFeeBigDecimal否保险费
shippingInsuranceFeeBigDecimal否运保费
loadingHarborString否装船口岸
destinationHarborString否目的港
foreignCurrencyAmountBigDecimal否外币港口
exportDateString否出口日期
currencyTypeenum否

AUD：澳元

+

CAD：加拿大元

+

CFP：法郎

+

CNY：人民币

+

COP：比索

+

EUR：欧元

+

GBP：英镑

+

HKD：港币

+

INR：卢比

+

JPY：日元

+

RUB：卢布

+

THB：泰铢

+

TWD：新台币

+

DEM：马克

+

USD：美元

币种
fobAmountBigDecimal否FOB金额
customsNoString否报关单号
orderDateString否年-月-日，例如2022-05-12订单日期10
deliverDateString否年-月-日，例如2022-05-12发货日期10
redReasonInteger否

1：销售退回

+

2：开票有误

+

3：服务终止

+

4：销售折让

+

当发票种类为：c/p/f/r/e的红字发票时填写

冲红原因
projectCodeString否项目编码64
projectNameString否项目名称300
emergencyFlagInteger否

0：非紧急

+

1：紧急

+

默认为：0

紧急订单标识
nextInvoiceCodeString否

下一张发票代码

+

支持票种：c普通发票（纸质）f收购发票（纸质）

指定发票卷开票时必传12
nextInvoiceNumString否

下一张发票号码

+

支持票种：c普通发票（纸质）f收购发票（纸质）

+

当【下一张发票代码】有值时，【下一张发票号码】和【发票终止号码】二选一

+

必填

指定发票卷开票时下一张发票号码和发票终止号码二选一必传，均不传则认为不指定票卷8
invoiceNumEndString否

发票终止号码

+

支持票种：c普通发票（纸质）f收购发票（纸质）

+

当【下一张发票代码】有值时，【下一张发票号码】和【发票终止号码】二选一

+

必填

指定发票卷开票时下一张发票号码和发票终止号码二选一必传，均不传则认为不指定票卷
buyerManagerNameString否购买方经办人姓名，数电特有字段16
managerCardTypeString否101-组织机构代码证,102-营业执照,103-税务登记证, 199-其他单位证件, 201-居民身份证, 202-军官证, 203-武警警官证, 204-士兵证, 205-军队离退休干部证, 206-残疾人证, 207-残疾军人证（1-8级）, 208-外国护照, 210-港澳居民来往内地通行证, 212-中华人民共和国往来港澳通行证, 213-台湾居民来往大陆通行证, 214-大陆居民往来台湾通行证, 215-外国人居留证, 216-外交官证 299-其他个人证件经办人证件类型数电特有字段40
managerCardNoString否经办人证件号码数电特有字段，证件类型有值时必填20
ccPhoneString否抄送手机号，当推送手机notifyPhone有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个100
ccEmailString否抄送邮箱，当推送邮箱notifyEmail有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个250
paperInvoiceTypeString否数电纸票时才需要传入，枚举值后续会持续更新;（票种为ec时，默认04；票种为es时，默认为1130）票种为ec时，只能为04或05；票种为es时只能为1130或1140或1160或1170

数电纸票类型： 04 2016版增值税普通发票（二联折叠票）

+

05 2016版增值税普通发票（五联折叠票

+

1130 增值税专用发票（中文三联无金额限制版）

+

1140 增值税专用发票（中文四联无金额限制版）

+

1160 增值税专用发票（中文六联无金额限制版）

+

1170 增值税专用发票（中文七联无金额限制版）

12
subjectAccountCodeString否T123核算主体编码维护在诺税通的“核算主体编码”200
subjectAccountString否核算主体名称核算主体名称核算主体名称200
detailList是电子发票明细
invoiceGoodsTransportsList否货物运输发票时必填货物运输明细最大长度2000
realPropertyRentObject否开具不动产租赁发票时必填不动产租赁发票信息
invoiceBuildingInfoObject否建筑服务发票时必填建筑服务信息
发票明细
detailIndexInteger是0明细序号5
detailTypeInteger是0明细行性质:0,正常行;1,折扣行;2,被折扣行2
commodityCodeString否商品编码64
goodsNameString是餐饮费如detailType=1，则此商品行为折扣行，此版本折扣行不允许多行折扣，折扣行必须紧邻被折扣行，项目名称必须与被折扣行一致。商品名称90
withTaxFlagInteger是1必填含税标志，0:不含税,1:含税2
goodsPriceBigDecimal否冲红时项目单价为正数

含税单价，当含税标志为：含税且不含税金额、税额、含税金额未全部传入时，必填，数量和单价必须都不填或者都必填，不可只填一个。

+

建议保留小数点后8位以上，减少计算误差。

+

开具成品油发票时必填且建议为5位小数。

16
taxFreePriceBigDecimal否冲红时项目单价为正数

不含税单价，当含税标志为：不含税且不含税金额、税额、含税金额未全部传入时，必填，数量和单价必须都不填或者都必填，不可只填一个。建议保留小数点后8位。

+

开具成品油发票时必填且建议为5位小数。

16
goodsNumBigDecimal否开具红字发票时，数量为负数

数量，数量、单价必须都不填，或都必填，不可只填一个；当数量、单价都不填时，不含税金额、税额、含税金额都必填；当数量、单价都填时，不含税金额、税额、含税金额可为空。建议保留小数点后8位以上。

+

开具成品油发票时必填且建议为5位小数。

16
taxrateString是0.13税率10
specTypeString否规格型号40
goodsUnitString否单位，开具成品油发票时必填，必须为”升”或“吨”。22
goodsCodeString否可不传入，由接口进行智能匹配，如对接口自动匹配准确率要求高的企业，建议传入税收分类编码19
selfCodeString否自行编码20
favouredPolicyFlagInteger是0默认为:0,不使用

优惠政策标识，0:不使用;1:使用

+

数电发票时为空，仅传入优惠政策编码即可

2
favouredPolicyNameString否favouredPolicyFlag为1时，此项必填

优惠政策内容，如：即征即退、免税、不征税、简易征收等

+

数电发票时为空，仅传入优惠政策编码即可

50
zeroRateFlagInteger否

零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率。

+

数电发票时为空，仅传入优惠政策编码即可

+

普通零税率，对应传值：

+

favouredPolicyFlag:0

+

zeroRateFlag:3

+

favouredPolicyName:

+

免税时，对应传值：

+

favouredPolicyFlag:1

+

zeroRateFlag:1

+

favouredPolicyName:“免税”

+

不征税，对应传值：

+

favouredPolicyFlag:1

+

zeroRateFlag:2

+

favouredPolicyName:“不征税”

2
deductionBigDecimal否

扣除额，小数点后两位。差额征收的发票目前只支持一行明细。不含税差额 = 不含税金额 - 扣除额； 税额 = 不含税差额*税率

+

注意：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00

15.2
taxFreeAmountBigDecimal否精确到小数点后面两位，红字发票为负数。不含税金额、税额、含税金额任何一个不传时，会根据传入的单价，数量进行z计算，可能和实际数值存在误差，建议都传入不含税金额15.2
taxBigDecimal否精确到小数点后面两位，红字发票为负数。不含税金额、税额、含税金额任何一个不传时，会根据传入的单价，数量进行计算，可能和实际数值存在误差，建议都传入税额15.2
taxAmountBigDecimal否精确到小数点后面两位，红字发票为负数。不含税金额、税额、含税金额任何一个不传时，会根据传入的单价，数量进行计算，可能和实际数值存在误差，建议都传入含税金额15.2
tonBigDecimal否盈亏吨数
columnFirstString否自定义字段1255
columnSecondString否自定义字段2255
columnThreeString否自定义字段3255
columnFourString否自定义字段4255
columnFiveString否自定义字段5255
favouredPolicyCodeString否01：简易征收 02：稀土产品 03：免税 04：不征税 05：先征后退 06：100%先征后退 07：50%先征后退 08：按3%简易征收 09：按5%简易征收 10：按5%简易征收减按1.5%计征 11：即征即退30% 12：即征即退50% 13：即征即退70% 14：即征即退100% 15：超税负3%即征即退 16：超税负8%即征即退 17：超税负12%即征即退 18：超税负6%即征即退

优惠政策编码

+

数电发票特有字段，如使用优惠政策时，该字段必填。

机动车(j)/二手车发票(u)明细（发票种类为j或u时需传入）
vehicleTypeString是发票种类为j或u时必填车辆类型40
brandModelString是发票种类为j或u时必填厂牌型号60
productOriginString是发票种类为j时必填产地32
certificateString否合格证号，国产车填写50
importCertifyNumString否进口证明书号，进口车填写36
inspectionOddNumString否商检单号32
engineNumString否发动机号50
vehicleCodeString是发票种类为j或u时必填车架号码/车辆识别代号23
measureUnitsString否吨位8
maxCapacityString限乘人数
organizationCodeString否其他证件号码，仅用于填写非中国居民证件号30
produceCompanyNameString是发票种类为j必填生产企业名称，不同税控设备要求不一致，具体以开票设备为准，金税盘选填，ukey、百旺盘必填100
intactCertificateNumString否完税凭证号码
organizeTypeString是发票种类为u时必填开票方类型：1.经营单位2.拍卖单位3.二手车市场（二手车专用）2
licenseNumberString是发票种类为u时必填车牌号码（二手车专用）20
registerCertNoString是发票种类为u时必填登记证号（二手车专用）20
vehicleManagementNameString是发票种类为u时必填转入地车辆管理所名称（二手车专用）80
salerNameString是发票种类为u时必填卖方单位/个人名称（二手车专用）80
salerNumString是发票种类为u时必填卖方单位代码/身份证号码（二手车专用）20
salerAddressString否卖方单位/个人地址（二手车专用）80
salerPhoneString否卖方电话（二手车专用）20
forceFlagInteger否发票种类为u时填写，默认0是否强制开具标记 0否 1是2
货物运输明细
goodsNameString否煤炭运输货物名称80
originString否北京市市辖区东城区起运地80
destinationString否北京市市辖区丰台区到达地80
transportTool否1运输工具种类：1铁路运输、2公路运输、3.水路运输、4.航空运输、5.管道运输1
transportToolNumString否车牌号DD运输工具牌号80
不动产租赁发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
rentStartDateString是2023-02-17yyyy-MM-dd格式租赁期起期10
rentEndDateString是2023-02-18yyyy-MM-dd格式租赁期止期10
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位1
建筑服务发票信息
buildingAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入建筑服务发生地-
detailedAddressString否XXXX街道XXX号建筑服务发生地+详细地址最大长度120详细地址120
landVatItemNoString否1234556土地增值税项目编号16
itemNameString是1234556项目名称80
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertySellObject否不动产销售发票时必填不动产销售发票信息
不动产销售发票信息
realPropertyAddressString是浙江省杭州市西湖区严格按照省市区/县层级传入不动产地址不动产地址 +不动产详细地址 最大长度120
detailAddressString是xxxxxx街xxx号

需含有"街","路","村","乡","镇","道","巷","号"中一个或多个关键字

+

不动产地址 +不动产详细地址最大长度120

不动产详细地址不动产地址 +不动产详细地址 最大长度120
crossCityFlagInteger是00-否 1-是跨地市标志1
realPropertyCertificateString否123456789产权证书/不动产权证号40
unitString是2

1-平方千米

+

2-平方米

+

3-公顷

+

4-亩

+

5-hm²

+

6-km²

+

7-㎡

面积单位10
realPropertyContractNumberString否不动产单元代码/网签合同备案编号28
incrementTaxNumberString否土地增值税项目编号18
priceString否核定计税价格20
taxAmountString否核定计税价格有值时,实际成交含税金额必填实际成交含税金额20
invoiceTravellerTransportInfoListList否开旅客运输发票时传入出行人信息出行人信息
出行人信息
travellerString是出行人20
travelDateString是年-月-日格式出行日期 年-月-日10
travellerCardTypeString是

101-组织机构代码证

+

102-营业执照

+

103-税务登记证

+

199-其他单位证件

+

201-居民身份证

+

202-军官证

+

203-武警警官证

+

204-士兵证

+

205-军队离退休干部证

+

206-残疾人证

+

207-残疾军人证（1-8级）

+

208-外国护照

+

210-港澳居民来往内地通行证

+

212-中华人民共和国往来港澳通行证

+

213-台湾居民来往大陆通行证

+

214-大陆居民往来台湾通行证

+

215-外国人居留证

+

216-外交官证

+

217-使（领事）馆证

+

218-海员证

+

219-香港永久性居民身份证

+

220-台湾身份证

+

221-澳门特别行政区永久性居民身份证

+

222-外国人身份证件

+

224-就业失业登记证

+

225-退休证

+

226-离休证

+

227-中国护照

+

228-城镇退役士兵自谋职业证

+

229-随军家属身份证明

+

230-中国人民解放军军官转业证书

+

231-中国人民解放军义务兵退出现役证

+

232-中国人民解放军士官退出现役证

+

233-外国人永久居留身份证（外国人永久居留证）

+

234-就业创业证

+

235-香港特别行政区护照

+

236-澳门特别行政区护照

+

237-中华人民共和国港澳居民居住证

+

238-中华人民共和国台湾居民居住证

+

239-《中华人民共和国外国人工作许可证》（A类）

+

240-《中华人民共和国外国人工作许可证》（B类）

+

241-《中华人民共和国外国人工作许可证》（C类）

+

291-出生医学证明

+

299-其他个人证件

出行人证件类型5
travellerCardNoString是出行人证件号码20
travelPlaceString是出行地80
arrivePlaceString是到达地80
vehicleTypeInteger是
    +

  1. 飞机

    2. +

  2. 火车

    3. +

  3. 长途汽车

    4. +

  4. 公共交通

    5. +

  5. 出租车

    6. +

  6. 汽车

    7. +

  7. 船舶

    +

    9-其他

    8. +
交通工具类型2
vehicleLevelString否

当交通工具类型是火车、飞机、船舶时必填选择，其他交通工具时可选填

+

当交通工具类型是火车时，必填，下拉框选择，可选项是 一等座、二等座、软席（软座、软卧）、硬卧（硬座、硬卧）

+

当交通工具类型是飞机时，必填，下拉框选择，可选项是 公务舱、头等舱、经济舱

+

当交通工具类型是船舶事，必填，下拉框选择，可选项是 一等舱、二等舱、三等舱

+

当交通工具类型是其他时，选填

交通工具等级20
+ +**机动车销售统一发票传参规则** + +企业购方税号、中国居民身份证号使用【购方税号：buyerTaxnum】字段传入，其他证件号码（港澳台人员证件号等）使用【其他证件号码：organizationCode】传入。 + +### 请求示例 + + +++ + + + + + +

{

+

"billInfoNo":null,

+

"bizCallbackUrl":null,

+

"buyerAccount":"银行账号",

+

"buyerAddress":"浙江省杭州市",

+

"buyerBank":"开户行",

+

"buyerName":"个人",

+

"buyerPhone":"0571-00000000",

+

"buyerTaxnum":"339901999999142",

+

"checker":"复核人",

+

"clerkId":null,

+

"clerker":"开票员",

+

"columnFirst":null,

+

"columnSecond":null,

+

"columnThree":null,

+

"departmentId":null,

+

"deptId":null,

+

"detail":[

+

{

+

"deduction":null,

+

"detailIndex":0,

+

"detailType":0,

+

"favouredPolicyFlag":0,

+

"favouredPolicyName":null,

+

"goodsCode":"1010115010100000000",

+

"goodsCodeAbb":"水果",

+

"goodsName":"苹果",

+

"goodsNum":1,

+

"goodsPrice":1.09,

+

"goodsUnit":"箱",

+

"selfCode":null,

+

"specType":"20个",

+

"tax":0.09,

+

"taxAmount":1.09,

+

"taxFreeAmount":1,

+

"taxFreePrice":1,

+

"taxrate":"0.09",

+

"withTaxFlag":0,

+

"zeroRateFlag":null,

+

"vehicleType":"三轮运输车",

+

"brandModel":"厂牌型号",

+

"productOrigin":"产地",

+

"certificate":"合格证号",

+

"importCertifyNum":"进出口证明书号",

+

"inspectionOddNum":"商检单号",

+

"engineNum":"发动机号",

+

"vehicleCode":"车辆识别代号",

+

"measureUnits":"吨",

+

"maxCapacity":"10",

+

"organizationCode":"组织机构代码",

+

"produceCompanyName":"生产企业名称",

+

"columnFirst":"自定义字段1",

+

"columnSecond":"自定义字段2",

+

"columnThree":"自定义字段3",

+

"columnFour":"自定义字段4",

+

"columnFive":"自定义字段5"，

+

"forceFlag":1,

+

}

+

],

+

"extensionNum":null,

+

"invoiceCode":null,

+

"invoiceLine":"p",

+

"invoiceNumber":null,

+

"invoiceType":1,

+

"listFlag":0,

+

"listGoodsName":null,

+

"notifyEmail":null,

+

"notifyPhone":null,

+

"notifyType":-1,

+

"orderNo":"20170104120207971529",

+

"payee":"收款人",

+

"productOilFlag":0,

+

"remark":"备注信息",

+

"requestSrc":0,

+

"sellerAccount":"0000000000000000",

+

"sellerAddress":"杭州市西湖区",

+

"sellerBank":"开户行",

+

"sellerName":"演示公司",

+

"sellerPhone":"0571-00000000",

+

"sellerTaxnum":"339901999999610",

+

"substituteFlag":0,

+

"terminalNum":null,

+

"userId":null,

+

"nextInvoiceNum": "1234456",

+

"nextInvoiceCode": "123456"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | Integer | 是 | 200 | | 状态,200-成功，非200-失败 | 6 | +| message | String | | 同步成功 | | 详细信息 | 1024 | +| data | String | | 18081620564001000232 | | 提交成功则返回发票请求流水号，支持多个。如该订单号被拆分成多张发票，则会返回多个流水号。 | 单张发票流水号最大长度：20 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message":"成功",

+

"data":"20111014474101989690"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code":"2050",

+

"message":"公司不存在"

+

}

+ +### 状态码说明 + +| | | +|:--:|:--:| +| **状态码** | **描述** | +| 2505 | 公司不存在 | +| 2600 | 发票类型不能为空 | +| 2601 | 发票类型错误(1:正票 2:红票) | +| 2602 | 红票发票代码不能为空 | +| 2603 | 红票发票号码不能为空 | +| 2604 | 红票发票代码不能超过12位 | +| 2605 | 红票发票号码不能超过8位 | +| 2606 | 红票对应蓝票不存在 | +| 2607 | 发票种类不存在 | +| 2608 | 代开标志不能为空 | +| 2609 | 代开标志只能为0和1 | +| 2610 | 清单标志不能为空 | +| 2611 | 清单标志只能为0和1 | +| 2612 | 清单标志为1时,清单项目名称不能为空 | +| 2613 | 清单项目名称不能超过90位 | +| 2614 | 成品油标志不能为空 | +| 2615 | 成品油标志只能为0和1 | +| 2616 | 成品油发票不支持清单票 | +| 2617 | 成品油发票不支持收购票 | +| 2618 | 成品油发票不支持代开票 | +| 2619 | 红票和蓝票的成品油标识必需一致 | +| 2620 | 暂不支持卷票 | +| 2621 | 该服务器类型暂不支持专票冲红 | +| 2622 | 该服务器类型暂不支持纸票冲红 | +| 2623 | 暂不支持开具收购发票 | +| 2624 | 购方名称不能为空 | +| 2625 | 购方名称不能超过100位 | +| 2626 | 购方税号只支持6-20位 | +| 2627 | 税号只能包含数字和字母 | +| 2628 | 专票购方税号不能为空 | +| 2629 | 购方电话不能超过50位 | +| 2630 | 专票购方电话不能为空 | +| 2631 | 购方地址不能超过100位 | +| 2632 | 专票购方地址不能为空 | +| 2633 | 购方地址和电话不能超过100位 | +| 2634 | 购方开户行不能超过100位 | +| 2635 | 购方开户行不能为空 | +| 2636 | 购方开户账号不能超过20位 | +| 2637 | 购方开户账号不能为空 | +| 2638 | 购方开户行及账号不能超过100位 | +| 2639 | 推送方式不能为空 | +| 2640 | 目前推送方式仅支持:\[-1,0,1,2\] | +| 2641 | 通知手机号不能超过20位 | +| 2642 | 通知手机号格式错误 | +| 2643 | 手机通知时手机号不能为空 | +| 2644 | 邮箱通知时邮箱不能为空 | +| 2645 | 通知邮箱格式错误 | +| 2646 | 通知邮箱不能超过50位 | +| 2647 | 销方名称不能为空 | +| 2648 | 销方名称不能超过100位 | +| 2649 | 销方税号不能为空 | +| 2650 | 销方税号只支持15-20位 | +| 2651 | 不允许对其他企业开具的发票进行冲红 | +| 2652 | 销方地址不能为空 | +| 2653 | 销方地址电话不能超过100位 | +| 2654 | 销方电话不能为空 | +| 2655 | 销方电话不能超过20位 | +| 2656 | 销方开户行不能为空 | +| 2657 | 销方账号不能为空 | +| 2658 | 销方开户行及账号不能超过100位 | +| 2659 | 开票员不能为空 | +| 2660 | 开票员长度不能超过20位 | +| 2661 | 收款员长度不能超过20位 | +| 2662 | 复核人长度不能超过20位 | +| 2663 | 商品详情为空 | +| 2664 | 订单明细行最大支持2000行 | +| 2665 | 数据格式不正确 | +| 2666 | 卷票明细行数不能超过13行 | +| 2667 | 红票备注不能为空 | +| 2668 | 红字信息表编号不能为空 | +| 2669 | 红字申请单号不能超过24位 | +| 2670 | 专用发票红票备注需注明：开具红字增值税专用发票信息表编号\*\*\* | +| 2671 | 代开发票备注需注明：代开企业税号:\*\*\* 代开企业名称:\*\*\* | +| 2672 | 备注长度不能超过230位 | +| 2673 | 订单编号不能为空 | +| 2674 | 订单编号长度不能大于64个字符 | +| 2675 | 请求来源错误 | +| 2676 | 发票已作废，无需冲红 | +| 2677 | 第%s行明细中商品名称不能为空 | +| 2678 | 第%s行明细中商品名称不能超过90位 | +| 2679 | 第%s行明细中商品编码不能超过19位 | +| 2680 | 第%s行明细中发票行性质只能为:\[0,1,2\] | +| 2681 | 第%s行明细中优惠政策标识只能为:\[0,1\] | +| 2682 | 第%s行明细中当优惠政策标识为1时,优惠政策名称不能为空 | +| 2683 | 第%s行明细中优惠政策名称不能超过50位 | +| 2684 | 第%s行明细中零税率标识只能为:\[0,1,2,3\] | +| 2685 | 第%s行明细中自行编码不能超过20位 | +| 2686 | 第%s行明细中单价含税标志只能为:\[0,1\] | +| 2687 | 第%s行明细中含税金额不能超过16位 | +| 2688 | 第%s行明细中不含税金额不能超过16位 | +| 2689 | 第%s行明细中税额不能超过16位 | +| 2690 | 第%s行明细中(不含税金额+税额)不等于含税金额 | +| 2691 | 第%s行明细中成品油单价不能为空 | +| 2692 | 第%s行明细中项目单价为空时，含税金额、不含税金额、税额都不能为空 | +| 2693 | 第%s行明细中商品单价为空时，商品数量也必须为空 | +| 2694 | 第%s行明细中商品单价长度不能超过29位 | +| 2695 | 第%s行明细中商品单价不能为0或负数 | +| 2696 | 第%s行明细中商品数量不能为空，且长度不能超过29位 | +| 2697 | 第%s行明细中蓝票商品数量不能为0或负数 | +| 2698 | 第%s行明细中红票商品数量不能为0或正数 | +| 2699 | 第%s行明细中商品税率不能为空 | +| 2700 | 第%s行明细中支持的税率列表:\[0,0.01,0.015,0.03,0.04,0.05,0.06,0.09,0.10,0.11,0.13,0.16,0.17\] | +| 2701 | 第%s行明细中规格型号不能超过40位 | +| 2702 | 第%s行明细中成品油发票单位不能为空 | +| 2703 | 第%s行明细中成品油发票单位只能为吨或升 | +| 2704 | 第%s行明细中单位不能超过22位 | +| 2705 | 第%s行明细中折扣行必须紧挨被折扣行之后 | +| 2706 | 第%s行明细中红票不支持折扣行发票开具 | +| 2707 | 第%s行明细中蓝票折扣行金额应为负 | +| 2708 | 第%s行明细中蓝票折扣行商品数量应为负 | +| 2709 | 第%s行明细中蓝票被折扣行金额应为正 | +| 2710 | 第%s行明细中蓝票被折扣行商品数量应为正 | +| 2711 | 第%s行明细中蓝票折扣行金额不能大于被折扣行的金额 | +| 2712 | 第%s行明细中折扣行商品税率必须和被折扣行商品税率相同 | +| 2713 | 第%s行明细中折扣行的商品名称必须和被折扣行相同 | +| 2714 | 第%s行明细中红票金额必须小于0 | +| 2715 | 第%s行明细中正票金额必须大于0 | +| 2716 | 扣除额只支持两位小数 | +| 2717 | 收购发票暂不支持开具差额征税发票 | +| 2718 | 扣除额只能开具一条商品明细 | +| 2719 | 扣除额不得小于0 | +| 2720 | 扣除额最大不得超过100亿 | +| 2721 | 扣除额大于等于开票金额时，税额应为0 | +| 2722 | 备注需注明差额征税： | +| 2723 | 扣除额不得大于0 | +| 2724 | 扣除额不得小于负100亿 | +| 2725 | 差额征税红字发票备注需注明 | +| 2726 | 差额征税发票，扣除额不能为空 | +| 2727 | 第%s行明细中金额\*税率-税额大于0.06,明细行名称:%s | +| 2728 | 第%s行明细中不含税单价和数量与不含税金额误差大于0.01,明细行名称:%s | +| 2729 | 正票金额必须大于0 | +| 2730 | 红票金额必须小于0 | +| 2731 | 金额超过对应蓝票剩余含税金额: ￥ | +| 2732 | 金额超过对应蓝票剩余不含税金额：￥ | +| 2734 | 已超过最大交付次数10次 | +| 2735 | 重新交付手机和邮箱不能都为空 | +| 2736 | 纸票不能交付 | +| 2737 | 开票未完成，不可重发通知。 | +| 2738 | 订单编号不能重复 | +| 2745 | 分机号范围为0-65535 | +| 2746 | 终端号不能超过10位 | +| 2747 | 第%s行明细中商品不存在，请重新选择商品或增加新商品 | +| 2761 | 单行明细不含税金额超过单张开票限额不支持拆分开票 | +| 2762 | 折扣后不含税金额超过单张开票限额不允许拆分开票 | +| 2763 | 该订单拆分后发票金额为0，不得拆分开票 | +| 2764 | 第%s行明细中商品税率、增值税特殊管理、零税率标识逻辑关系不正确 | +| 2765 | 第%s行明细中商品零税率标识为1、2、3时，税率应为0% | +| 2766 | 发票拆分异常 | +| 2767 | 发票被拆分后明细大于%d行 | +| 2768 | 需要拆分的发票订单编号长度不能超过60位 | +| 2769 | 发票被拆分后张数大于%d张 | +| 2770 | 单张开票限额为空 | +| 2771 | 单张开票限额不能小于0.01 | +| 2772 | 需拆分发票的不含税金额不能小于0.01 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/录入自定义字段.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/录入自定义字段.md new file mode 100644 index 0000000..3faccca --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/录入自定义字段.md @@ -0,0 +1,106 @@ +--- +title: 录入自定义字段 +aliases: + - 录入自定义字段 + - 诺税通录入自定义字段 + - 设备企业与配置-录入自定义字段 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 录入自定义字段 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/operation/definedColumn/batchSave.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 录入自定义字段 + +### 接口说明 + +根据订单号或流水号录入自定义字段信息。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/operation/definedColumn/batchSave.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | 20 | +| orderNos | List | 否 | 订单号 订单号和发票流水号二选一必填，都传入则优先使用流水号 | 500 | +| invoiceIds | List | 否 | 发票流水号 订单号和发票流水号二选一必填，都传入则优先使用流水号 | 500 | +| columnFirst | String | 否 | 自定义字段一，三个自定义字段不可全为空 | \- | +| columnSecond | String | 否 | 自定义字段二，三个自定义字段不可全为空 | \- | +| columnThree | String | 否 | 自定义字段三，三个自定义字段不可全为空 | \- | + +### 请求示例 + + +++ + + + + + +

{

+

"orderNos": [

+

"123456789"

+

],

+

"sellerTaxnum": "150301199811285326"，

+

"columnFirst": "自定义字段1"，

+

"columnSecond": "自定义字段2"，

+

"columnThree": "自定义字段3"

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/快捷冲红接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/快捷冲红接口.md new file mode 100644 index 0000000..ba4de45 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/快捷冲红接口.md @@ -0,0 +1,402 @@ +--- +title: 快捷冲红接口 +aliases: + - 快捷冲红接口 + - 诺税通快捷冲红接口 + - 作废重开与冲红-快捷冲红接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 快捷冲红接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[03_作废重开与冲红]] +> 文档链接：[总索引](../README.md) · [分组页](../03_作废重开与冲红.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[03_作废重开与冲红]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/ fastRepeatedRedSingle.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 快捷冲红接口 + +### 接口说明 + +支持直接请求蓝字发票直接触发开具对应的红字发票或红字信息表。 + +注：数电发票使用此接口开取红票 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/ fastRepeatedRedSingle.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
sellerTaxnumString否

销方税号，15-20位

+

销方税号和组织编码必填其一

20
companyCodeString否

组织编码

+

企业税号和组织编码必填其一

20
invoiceIdString否蓝票流水号 非数电发票时必填20
invoiceCodeString否蓝票发票代码 非数电发票时必填12
invoiceNumberString否蓝票发票号码 非数电发票时必填8
billIdString否

红字确认单申请单号

+

与billNo、billUuid三选一必填

32
billNoString否

红字确认单编号 数电发票时填写

+

与billId、billUuid三选一必填

32
billUuidString否

红字确认单uuid 数电发票时填写

+

与billId、billNo三选一必填

32
fastRedTypeInteger否快捷冲红类型 不填或者0为普通快捷冲红 1:数电发票快捷冲红(数电发票必传1)1
invoiceLineString否

数电发票跨票种冲红时传入，发票票种：（非数电发票时不需要传）

+

bs:数电专票(电子),

+

pc:数电普票(电子)，

+

es:数电专票(纸质)，

+

ec:数电普票(纸质)

+

1、默认为对应蓝票数电票种；

+

2、蓝票为es 时可选择 bs、es进行冲红

+

3、蓝票为ec时可选择pc、ec进行冲红

+

4、蓝票为数电电票时只能拿原票种冲红

2
orderNoString否红字发票对应订单编号64
columnFirstString否自定义列1
columnSecondString否自定义列2
columnThreeString否自定义列3
+ +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"invoiceId": "14111111111",

+

"invoiceCode": "11111111",

+

"invoiceNumber": "22222222",

+

"billId": "22222222",

+

"billNo": "22222222",

+

"billUuid": "123456",

+

"fastRedType": 1,

+

"invoiceLine": "es",

+

"orderNo": "123456908888",

+

"columnFirst": "c1",

+

"columnSecond": "c2",

+

"columnThree": "c3"

+

}

+ +### 返回参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
codeInteger是

状态,200-成功，非200-失败

+

不代表冲红成功/失败

6
messageString是详细信息1024
dataObject
data内字段说明
sellerTaxnumString是销方税号20
blueInvoiceIdString否蓝票流水号 非数电发票时必填20
blueInvoiceCodeString否蓝票代码 非数电发票时必填12
blueInvoiceNumberString否蓝票号码 非数电发票时必填8
redInvoiceIdString否(蓝票非专票时的字段)红票流水号，非专票时必有值20
redOrderNoString否(蓝票非专票时的字段)红票orderNo，非专票时必有值64
redBillNoString否(蓝票专票时的字段)红字信息表流水号(billNo),不是billInfoNo。专票时必有值24
reasonString否失败原因，冲红失败时才会有值2000
billIdString否红字确认单申请单号32
billNoString否红字确认单编号 数电发票时必填32
billUuidString否红字确认单uuid 数电发票时必填32
fastRedTypeInteger否快捷冲红类型 不填或者0为普通快捷冲红 1:数电快捷冲红(数电发票必传1)1
+ +### 返回示例 + +成功示例： + + +++ + + + + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"blueInvoiceId": "21122410310201000295",

+

"blueInvoiceCode": "111100020026",

+

"blueInvoiceNumber": "92482083",

+

"redInvoiceId": "12312312312",

+

"redOrderNo": "12123123123123",

+

"redBillNo": null,

+

"billId": "22222222",

+

"billNo": "22222222",

+

"billUuid": "123456",

+

"fastRedType": 1,

+

"reason": ""

+

}

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"blueInvoiceId": "21122410310201000295",

+

"blueInvoiceCode": "111100020026",

+

"blueInvoiceNumber": "92482083",

+

"redInvoiceId": null,

+

"redOrderNo": null,

+

"redBillNo": null,

+

"redBillNo": null,

+

"billId": "22222222",

+

"billNo": "22222222",

+

"billUuid": "123456",

+

"fastRedType": 1,

+

"reason": "未知异常"

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/成品油库存下载接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/成品油库存下载接口.md new file mode 100644 index 0000000..2fb8c6d --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/成品油库存下载接口.md @@ -0,0 +1,122 @@ +--- +title: 成品油库存下载接口 +aliases: + - 成品油库存下载接口 + - 诺税通成品油库存下载接口 + - 专项能力-成品油库存下载接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 成品油库存下载接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/oilStock/downloadProductOil.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 成品油库存下载接口 + +### 接口说明 + +触发从税局局端下载成品油库存到税盘的接口 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/oilStock/downloadProductOil.do | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 是 | 分机号，纯数字 | \- | +| machineNumber | String | 否 | 机器编号，12位数字 | 12 | +| taxCode | String | 是 | 税收分类编码 | 19 | +| num | Double | 是 | 下载数量（升） | \- | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": 0,

+

"machineNumber": "661565671900",

+

"num": 1,

+

"sellerTaxnum": "150301199811285326",

+

"taxCode": "1070101060100000000"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 913,

+

"message": "[AA99]库存不够！",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量查询发票xmlUrl接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量查询发票xmlUrl接口.md new file mode 100644 index 0000000..3008589 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量查询发票xmlUrl接口.md @@ -0,0 +1,124 @@ +--- +title: 批量查询发票xmlUrl接口 +aliases: + - 批量查询发票xmlUrl接口 + - 诺税通批量查询发票xmlUrl接口 + - 车辆辅助与回传-批量查询发票xmlUrl接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 批量查询发票xmlUrl接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/queryInvoiceXml.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 批量查询发票xmlUrl接口 + +### 接口说明 + +获取发票的xmlUrl + +### 接口地址 + +| | +|:-------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/queryInvoiceXml.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 企业税号 | 20 | +| dataStream | Integer | 否 | 是否返回数据流 0不返回 1返回 | \- | +| invoiceCodeAndNumbers | List\ | 否 | 发票查询信息 | 50 | +| InvoiceCodeNumDto发票信息参数 | | | | | +| invoiceCode | String | 否 | 发票代码 | 8 | +| invoiceNumber | String | 是 | 发票号码 | 20 | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"dataStream": 1,

+

"invoiceCodeAndNumbers": [

+

{

+

"invoiceCode": "12345678",

+

"invoiceNumber": "2302171651331000014"

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| sellerTaxnum | String | 是 | 150301199811285326 | 企业税号 | | +| invoiceCode | String | 是 | 12345678 | 发票代码 | | +| invoiceNumber | String | 是 | 2302171651331000014 | 发票号码 | | +| xmlUrl | String | 是 | | 发票xml地址(存在xml则返回) | | +| dataStream | String | 否 | | 发票xml数据流(Base64) | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

[

+

{

+

"dataStream": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8RUludm9pY2U+CiAgICA8SGVhZGVyPgogICAgICAgIDxFSWlkPjIyNDQyMDAwMDAwMDAyMDQwMjYxPC9FSWlkPgogICAgICAgIDxFSW52b2ljZVRhZz5TV0VJNDQwMDwvRUludm9pY2VUYWc+CiAgICAgICAgPFZlcnNpb24+MC4yPC9WZXJzaW9uPgogICAgICAgIDxJbmhlcmVudExhYmVsPgogICAgICAgICAgICA8SW5Jc3N1VHlwZT4KICAgICAgICAgICAgICAgIDxMYWJlbENvZGU+WTwvTGFiZWxDb2RlPgogICAgICAgICAgICAgICAgPExhYmVsTmFtZT7mmK/lkKbok53lrZflj5HnpajmoIflv5c8L0xhYmVsTmFtZT4KICAgICAgICAgICAgPC9Jbklzc3VUeXBlPgogICAgICAgICAgICA8RUludm9pY2VUeXBlPgogICAgICAgICAgICAgICAgPExhYmVsQ29kZT4wMTwvTGFiZWxDb2RlPgogICAgICAgICAgICAgICAgPExhYmVsTmFtZT7nlLXlrZDlj5Hnpag8L0xhYmVsTmFtZT4KICAgICAgICAgICAgPC9FSW52b2ljZVR5cGU+CiAgICAgICAgICAgIDxHZW5lcmFsT3JTcGVjaWFsVkFUPgogICAgICAgICAgICAgICAgPExhYmVsQ29kZT4wMjwvTGFiZWxDb2RlPgogICAgICAgICAgICAgICAgPExhYmVsTmFtZT7mma7pgJrlj5Hnpag8L0xhYmVsTmFtZT4KICAgICAgICAgICAgPC9HZW5lcmFsT3JTcGVjaWFsVkFUPgogICAgICAgICAgICA8VGF4cGF5ZXJUeXBlPgogICAgICAgICAgICAgICAgPExhYmVsQ29kZT4xPC9MYWJlbENvZGU+CiAgICAgICAgICAgICAgICA8TGFiZWxOYW1lPuS4gOiIrOe6s+eojuS6ujwvTGFiZWxOYW1lPgogICAgICAgICAgICA8L1RheHBheWVyVHlwZT4KICAgICAgICA8L0luaGVyZW50TGFiZWw+CiAgICAgICAgPFVuZGVmaW5lZExhYmVsPgogICAgICAgICAgICA8TGFiZWw+CiAgICAgICAgICAgICAgICA8TGFiZWxUeXBlPuS8geS4muihjOS4muaAp+i0qOexu+agh+etvjwvTGFiZWxUeXBlPgogICAgICAgICAgICAgICAgPExhYmVsQ29kZT4zNiwxNywwMiwzNyw0MCwwMywwOCxEUywxMSwyMDwvTGFiZWxDb2RlPgogICAgICAgICAgICAgICAgPExhYmVsTmFtZT7lhpzkuqflk4HmlLbotK3kvIHkuJos5Y2354Of55Sf5Lqn5LyB5LiaLOaIkOWTgeayuee7j+mUgOS8geS4mizlhYnkvI/mlLbotK3kvIHkuJos5YaN55Sf6LWE5rqQ5Zue5pS2LOWbveWGheacuuWKqOi9pueUn+S6p+S8geS4mizkuozmiYvovabnu4/plIDkvIHkuJosRFMs56iA5Zyf5Ya254K85YiG56a75LyB5LiaLOeUn+S6p+Wei+WHuuWPo+S8geS4mjwvTGFiZWxOYW1lPgogICAgICAgICAgICA8L0xhYmVsPgogICAgICAgICAgICA8TGFiZWw+CiAgICAgICAgICAgICAgICA8TGFiZWxUeXBlPuWPkeelqOW8gOWFt+aWueW8j+agh+etvjwvTGFiZWxUeXBlPgogICAgICAgICAgICAgICAgPExhYmVsQ29kZT4xPC9MYWJlbENvZGU+CiAgICAgICAgICAgICAgICA8TGFiZWxOYW1lPue9kemhteW8gOelqDwvTGFiZWxOYW1lPgogICAgICAgICAgICA8L0xhYmVsPgogICAgICAgIDwvVW5kZWZpbmVkTGFiZWw+CiAgICA8L0hlYWRlcj4KICAgIDxFSW52b2ljZURhdGE+CiAgICAgICAgPFNlbGxlckluZm9ybWF0aW9uPgogICAgICAgICAgICA8U2VsbGVySWROdW0+MTAxMjJBQUZGQUQ1N0NEM0U8L1NlbGxlcklkTnVtPgogICAgICAgICAgICA8U2VsbGVyTmFtZT7kuIDoiKznurPnqI7kurrogqHku73mnInpmZDlhazlj7g8L1NlbGxlck5hbWU+CiAgICAgICAgICAgIDxTZWxsZXJBZGRyPuaWsOWfjuWMuumUoeael+i3r+ihl+mBk+WKnuS6i+WkhDIzNDIzNDIzNDwvU2VsbGVyQWRkcj4KICAgICAgICAgICAgPFNlbGxlclRlbE51bT4xMzAyMjIyODg4ODwvU2VsbGVyVGVsTnVtPgogICAgICAgICAgICA8U2VsbGVyQmFua05hbWU+5YyX5Lqs6ZO26KGM5rW35reA5Yy65riF5rKz5pSv6KGMPC9TZWxsZXJCYW5rTmFtZT4KICAgICAgICAgICAgPFNlbGxlckJhbmtBY2NOdW0+NDQzMDAwMDEwNTAwMTY2MzE8L1NlbGxlckJhbmtBY2NOdW0+CiAgICAgICAgPC9TZWxsZXJJbmZvcm1hdGlvbj4KICAgICAgICA8QnV5ZXJJbmZvcm1hdGlvbj4KICAgICAgICAgICAgPEJ1eWVySWROdW0+OTExMTAxMDhNQTAxRUxISDlQPC9CdXllcklkTnVtPgogICAgICAgICAgICA8QnV5ZXJOYW1lPuWwj+inhOaooee6s+eojuS6uuiCoeS7veaciemZkOWwj+inhOaooee6s+eojuS6uuiCoeS7veaciemZkOWwjyAgICAg5qih57qz56iO5Lq66IKh5Lu95pyJ6ZmQ5bCP6KeE5qih57qz56iO5Lq66IKh5Lu95pyJ6ZmQ5bCP6KeE5qih57qz56iO5Lq66IKh5Lu95pyJ6ZmQPC9CdXllck5hbWU+CiAgICAgICAgICAgIDxCdXllckFkZHI+5LiA5LqM5LiJ5Zub5LqU5YWt5LiD5YWr5Lmd5Y2B5LiA5LqM5LiJ5Zub5LqU5YWt5LiD5YWr5Lmd5Y2B5LiA5LqM5LiJ5Zub5LqU5YWt5LiD5YWr5Lmd5Y2B5LiA5LqM5LiJ5Zub5LqU5YWt5LiD5YWr5Lmd5Y2B5LiA5LqM5LiJ5Zub5LqU5YWt5LiD5YWr5Lmd5Y2BPC9CdXllckFkZHI+CiAgICAgICAgICAgIDxCdXllclRlbE51bT4xMjM0NTY3ODkwMTIzNDU2NzA8L0J1eWVyVGVsTnVtPgogICAgICAgICAgICA8QnV5ZXJCYW5rTmFtZT7kuK3lm70gIOmTtuihjOW5v+W3nuesrOS4gOaUr+ihjOS4reWbvemTtuihjOW5v+W3niDnrKzkuIDmlK/ooYzkuK3lm73pk7booYzlub/lt57nrKzkuIDmlK/ooYzkuK3lm73pk7booYzlub/lt57nrKzkuIDmlK/ooYzkuK3lm73pk7booYzlub/lt57nrKzkuIDmlK/ooYw8L0J1eWVyQmFua05hbWU+CiAgICAgICAgICAgIDxCdXllckJhbmtBY2NOdW0+MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM2Nzg5MDwvQnV5ZXJCYW5rQWNjTnVtPgogICAgICAgICAgICA8QnV5ZXJIYW5kbGluZ05hbWU+PC9CdXllckhhbmRsaW5nTmFtZT4KICAgICAgICA8L0J1eWVySW5mb3JtYXRpb24+CiAgICAgICAgPEJhc2ljSW5mb3JtYXRpb24+CiAgICAgICAgICAgIDxUb3RhbEFtV2l0aG91dFRheD45OC4yMzwvVG90YWxBbVdpdGhvdXRUYXg+CiAgICAgICAgICAgIDxUb3RhbFRheEFtPjEyLjc3PC9Ub3RhbFRheEFtPgogICAgICAgICAgICA8VG90YWxUYXgtaW5jbHVkZWRBbW91bnQ+MTExLjAwPC9Ub3RhbFRheC1pbmNsdWRlZEFtb3VudD4KICAgICAgICAgICAgPFRvdGFsVGF4LWluY2x1ZGVkQW1vdW50SW5DaGluZXNlPuWjueS9sOWjueaLvuWjueWchuaVtDwvVG90YWxUYXgtaW5jbHVkZWRBbW91bnRJbkNoaW5lc2U+CiAgICAgICAgICAgIDxEcmF3ZXI+5byg55uK6L6+PC9EcmF3ZXI+CiAgICAgICAgICAgIDxSZXF1ZXN0VGltZT4yMDIyLTA5LTIxPC9SZXF1ZXN0VGltZT4KICAgICAgICA8L0Jhc2ljSW5mb3JtYXRpb24+CiAgICAgICAgPElzc3VJdGVtSW5mb3JtYXRpb24+CiAgICAgICAgICAgIDxJdGVtTmFtZT4q5aKo5rC0KumSoueslOaZrumAmumbtjwvSXRlbU5hbWU+CiAgICAgICAgICAgIDxTcGVjTW9kPjwvU3BlY01vZD4KICAgICAgICAgICAgPE1lYVVuaXRzPjwvTWVhVW5pdHM+CiAgICAgICAgICAgIDxRdWFudGl0eT4xPC9RdWFudGl0eT4KICAgICAgICAgICAgPFVuUHJpY2U+OTguMjMwMDg4NDk1NTc1MjwvVW5QcmljZT4KICAgICAgICAgICAgPEFtb3VudD45OC4yMzwvQW1vdW50PgogICAgICAgICAgICA8VGF4UmF0ZT4wLjEzMDAwMDwvVGF4UmF0ZT4KICAgICAgICAgICAgPENvbVRheEFtPjEyLjc3MDAwMDwvQ29tVGF4QW0+CiAgICAgICAgICAgIDxUb3RhbHRheEluY2x1ZGVkQW1vdW50PjExMS4wMDAwMDA8L1RvdGFsdGF4SW5jbHVkZWRBbW91bnQ+CiAgICAgICAgICAgIDxUYXhDbGFzc2lmaWNhdGlvbkNvZGU+MTA2MDQwNDAyMDAwMDAwMDAwMDwvVGF4Q2xhc3NpZmljYXRpb25Db2RlPgogICAgICAgIDwvSXNzdUl0ZW1JbmZvcm1hdGlvbj4KICAgICAgICA8U3BlY2lmaWNJbmZvcm1hdGlvbi8+CiAgICAgICAgPEFkZGl0aW9uYWxJbmZvcm1hdGlvbi8+CiAgICA8L0VJbnZvaWNlRGF0YT4KICAgIDxTZWxsZXJBdXRoZW50aWNhdGlvbj4KICAgICAgICA8QXV0aGVudGljYXRpb25NZXRob2RzPjAyPC9BdXRoZW50aWNhdGlvbk1ldGhvZHM+CiAgICA8L1NlbGxlckF1dGhlbnRpY2F0aW9uPgogICAgPFRheFN1cGVydmlzaW9uSW5mbz4KICAgICAgICA8SW52b2ljZU51bWJlcj4yMjQ0MjAwMDAwMDAwMjA0MDI2MTwvSW52b2ljZU51bWJlcj4KICAgICAgICA8SXNzdWVUaW1lPjIwMjItMDktMjEgMjA6MTY6Mjg8L0lzc3VlVGltZT4KICAgICAgICA8VGF4QnVyZWF1Q29kZT4xNDQwMDAwMDAwMDwvVGF4QnVyZWF1Q29kZT4KICAgICAgICA8VGF4QnVyZWF1TmFtZT7lm73lrrbnqI7liqHmgLvlsYDlub/kuJznnIHnqI7liqHlsYA8L1RheEJ1cmVhdU5hbWU+CiAgICA8L1RheFN1cGVydmlzaW9uSW5mbz4KICAgIDxUYXhCdXJlYXVTaWduYXR1cmU+CiAgICAgICAgPFJlZmVyZW5jZSBVUkk9Ii9FaW52b2ljZS9IZWFkZXJ8L0VpbnZvaWNlL0VpbnZvaWNlRGF0YXwvRWludm9pY2UvU2VsbGVyQXV0aGVudGljYXRpb258L0VpbnZvaWNlL1RheFN1cGVydmlzaW9uSW5mb3wvRWludm9pY2UvVGF4QnVyZWF1U2lnbmF0dXJlL1NpZ25hdHVyZVRpbWUiLz4KICAgICAgICA8U2lnbmF0dXJlQWxnb3JpdGhtPjEuMi4xNTYuMTAxOTcuMS41MDE8L1NpZ25hdHVyZUFsZ29yaXRobT4KICAgICAgICA8U2lnbmF0dXJlRm9ybWF0PkRFVEFDSDwvU2lnbmF0dXJlRm9ybWF0PgogICAgICAgIDxTaWduYXR1cmVUaW1lPjIwMjItMDktMjMgMjA6MTc6NDI8L1NpZ25hdHVyZVRpbWU+CiAgICAgICAgPFNpZ25hdHVyZVZhbHVlPjwvU2lnbmF0dXJlVmFsdWU+CiAgICAgICAgPEtleUluZm8vPgogICAgPC9UYXhCdXJlYXVTaWduYXR1cmU+CjwvRUludm9pY2U+Cg==",

+

"invoiceCode": "12345678",

+

"invoiceNumber": "2302171651331000014",

+

"sellerTaxnum": "9151010020260067X4",

+

"xmlUrl": "https://cmp-brh.nntest.cn/fd/M00/BC/5D/wKjScGPjCLaAVgJkAAASx_Qt__k274.xml"

+

}

+

]

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量获取信息转换配置接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量获取信息转换配置接口.md new file mode 100644 index 0000000..bc71eeb --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量获取信息转换配置接口.md @@ -0,0 +1,100 @@ +--- +title: 批量获取信息转换配置接口 +aliases: + - 批量获取信息转换配置接口 + - 诺税通批量获取信息转换配置接口 + - 设备企业与配置-批量获取信息转换配置接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 批量获取信息转换配置接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/infoConvert/batch.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 批量获取信息转换配置接口 + +### 接口说明 + +批量获取信息转换配置，供应链使用，最多支持500个税号的查询。 + +### 接口地址 + +| | +|:---------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/infoConvert/batch.do | + +请求方式：POST + +Content-Type：application/x-www-form-urlencoded + +### 请求参数 + +| | | | | | +|:----------:|:----------:|:--------:|:-------------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| taxNumList | String\[\] | 是 | 销方税号列表，最多支持500组税号 | \- | + +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | +| data内字段说明 | | | | | +| taxnum | String | 是 | 销方税号 | | +| customerOpenFlag | int | 是 | 客户信息转换开关:0-关，1-开，默认值0 | | +| customerProcessNode | String | 是 | 客户信息处理节点：提交开票时SUBMIT_INVOICE,创建订单时ORDER_SAVE,开票时INVOICE | | +| goodsOpenFlag | int | 是 | 商品信息转换开关:0-关，1-开，默认值0 | | +| goodsProcessNode | String | 是 | 商品信息处理节点：提交开票时SUBMIT_INVOICE,创建订单时ORDER_SAVE,开票时INVOICE | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"taxnum": "150301199811285326",

+

"goodsOpenFlag": 1,

+

"goodsProcessNode": "INVOICE",

+

"customerOpenFlag": 1,

+

"customerProcessNode": "INVOICE"

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量获取备注配置信息接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量获取备注配置信息接口.md new file mode 100644 index 0000000..bf78d87 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/批量获取备注配置信息接口.md @@ -0,0 +1,148 @@ +--- +title: 批量获取备注配置信息接口 +aliases: + - 批量获取备注配置信息接口 + - 诺税通批量获取备注配置信息接口 + - 设备企业与配置-批量获取备注配置信息接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 批量获取备注配置信息接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/config/remarkConf/batch.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 批量获取备注配置信息接口 + +### 接口说明 + +批量获取备注配置信息，供应链使用，最多支持500组数据的查询。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/config/remarkConf/batch.do | + +### 请求参数 + +| | | | | | +|:------------:|:--------:|:--------:|:--------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| taxnum | String | 否 | 企业税号 | 20 | +| businessType | String | 否 | 业务标识 | 2 | +| processNode | String | 否 | 处理节点 | 100 | +| buyerTaxnum | String | 否 | 购方税号 | 20 | +| buyerName | String | 否 | 购方名称 | 100 | + +### 请求示例 + + +++ + + + + + +

[

+

{

+

"businessType": "1",

+

"buyerName": "",

+

"buyerTaxnum": "",

+

"processNode": "INVOICE",

+

"taxnum": "3333333333333333"

+

}

+

]

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | | **类型** | **必填** | **描述** | **长度** | +| code | | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | | String | 是 | 详细信息 | 1024 | +| data | | Object | | | | +| data内字段说明 | | | | | | +| taxnum | | String | | 企业税号 | 20 | +| businessType | | String | | 业务标识 | 2 | +| processNode | | String | | 处理节点 | 100 | +| buyerTaxnum | | String | | 请求中的购方税号 | 20 | +| buyerName | | String | | 请求中的购方名称 | 100 | +| configs | | Object | | 备注配置信息 | \- | +| buyerInfoList | | Object | | 模板的全部购方信息 | \- | +| configs内字段说明 | | | | | | +| idx | | int | | 序号 | | +| paramCode | | String | | 对应参数代码 | | +| remarkTitle | | String | | 备注名称 | | +| rowNo | | int | | 行号 | | +| valSource | | int | | 取值来源 | | +| buyerInfoList内字段说明 | | | | | | +| buyerTaxnum | String | | | 购方税号 | | +| buyerName | String | | | 购方名称 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"taxnum": "3333333333333333",

+

"businessType": "1",

+

"processNode": "INVOICE",

+

"buyerName": "",

+

"buyerTaxnum": "",

+

"configs": [

+

{

+

"idx": 0,

+

"rowNo": 1,

+

"remarkTitle": "出口",

+

"paramCode": "",

+

"valSource": 1

+

},

+

{

+

"idx": 1,

+

"rowNo": 2,

+

"remarkTitle": "外币金额:",

+

"paramCode": "FOREIGN_CURRENCY_AMOUNT",

+

"valSource": 1

+

}

+

]

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/抄报清卡.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/抄报清卡.md new file mode 100644 index 0000000..da8fa5a --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/抄报清卡.md @@ -0,0 +1,121 @@ +--- +title: 抄报清卡 +aliases: + - 抄报清卡 + - 诺税通抄报清卡 + - 专项能力-抄报清卡 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 抄报清卡 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/extensioninfo/reportAndClear.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 抄报清卡 + +### 接口说明 + +触发抄报清卡 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/extensioninfo/reportAndClear.do | + +### 请求参数 + +| | | | | | +|:------------:|:--------:|:--------:|:--------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| taxnum | String | 是 | 销方税号 | 20 | +| extensionNum | String | 否 | 分机号 | | +| machineNum | String | 否 | 机器号 | | + +### 请求示例 + + +++ + + + + + +

{

+

"taxnum": "150301199811285326",

+

"extensionNum": "1",

+

"machineNum": "123456789123"

+

}

+ +### 返回参数 + +| | | | | | +|:------------:|:--------:|:--------:|:--------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | String | 否 | 触发失败的原因以及设备信息 | | +| extensionNum | String | 否 | 分机号 | | +| machineNum | String | 否 | 机器号 | | +| reason | String | 否 | 触发失败的原因 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

+ +失败返回示例： + + +++ + + + + + +

{

+

"code": 400,

+

"message": "税号不能为空",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/授信额度刷新接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/授信额度刷新接口.md new file mode 100644 index 0000000..1ea352e --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/授信额度刷新接口.md @@ -0,0 +1,124 @@ +--- +title: 授信额度刷新接口 +aliases: + - 授信额度刷新接口 + - 诺税通授信额度刷新接口 + - 专项能力-授信额度刷新接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 授信额度刷新接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/creditQuota/query.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 授信额度刷新接口 + +### 接口说明 + +获取数电发票税局最新授信额度,该接口根据不同设备类型，返回不同结果。如果乐企模式，则同步返回授信额度数据。如果非乐企模式，为异步查询，需搭配接口3.57使用，来获取查询结果。 + +### 接口地址 + +| | +|:---------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/creditQuota/query.do | + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| taxNum | String | 是 | 需要查询的企业税号 | 企业税号 | 20 | +| type | Integer | 否 | 分机号与请求类型二选一必填，均传入已分机号匹配到的设备为准 | 请求类型 0:乐企 1:数电普通 | \- | +| extensionNum | Integer | 否 | 分机号与请求类型二选一必填，均传入已分机号匹配到的设备为准 | 分机号 | 0-99999 | + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"type": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| 乐企模式返回字段 | | | | | | +| creditFlag | String | 是 | Y | 暂停授信标志 Y：暂停 N：未暂停 | 1 | +| creditQuotaAmount | BigDecimal | 是 | 10000.00 | 本月授信额度 | 12,2 | +| downloadAmount | BigDecimal | 是 | 10000.00 | 可用剩余额度 | 12,2 | +| downloadRemainAmount | BigDecimal | 是 | 10000.00 | 已下载额度 | 12,2 | +| remainAmount | BigDecimal | 是 | 10000.00 | 已下载未使用额度 | 12,2 | +| taxnum | String | 是 | 150301199811285326 | 企业税号 | 20 | +| vestPeriod | String | 否 | 202303 | 属期 格式：yyyyMM | | +| creditUpdateTime | Date | 是 | 2023-03-06 00:00:00 | 授信额度更新时间 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": "200",

+

"message": "查询成功" ,

+

"data": {

+

"creditFlag": "Y",

+

"creditQuotaAmount": "10000.00" ,

+

"downloadAmount": "10000.00",

+

"downloadRemainAmount": "10000.00",

+

"remainAmount": "10000.00",

+

"taxnum": "150301199811285326",

+

"vestPeriod": "202303",

+

"creditUpdateTime": "2023-03-06 00:00:00"

+

}

+

}

+

非乐企:

+

{

+

"code": "200",

+

"message": "查询成功" ,

+

"data": ""

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/收票入库接口_本地提取发票.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/收票入库接口_本地提取发票.md new file mode 100644 index 0000000..bf87bbd --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/收票入库接口_本地提取发票.md @@ -0,0 +1,1148 @@ +--- +title: 收票入库接口（本地提取发票） +aliases: + - 收票入库接口（本地提取发票） + - 诺税通收票入库接口（本地提取发票） + - 车辆辅助与回传-收票入库接口（本地提取发票） +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 收票入库接口（本地提取发票） + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/ receiveLocalInvoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 收票入库接口（本地提取发票） + +### 接口说明 + +将第三方的发票通过此接口推送至诺税通销项发票系统。 + +### 接口地址 + +| | +|:------------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/ receiveLocalInvoice.do | + +注：此接口以 application/json 方式提交数据 + +### 请求参数 + + +++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必须示例值更多限制描述最大长度
sellerTaxnumString否　　销方税号和组织编码必填其一销方税号20
sellerNameString是　　销方名称100
companyCodeString否销方税号和组织编码必填其一组织编码20
businessTypeString否业务标识(基础模块设置的业务类型枚举值)业务标识2
sellerAddressString否　　销方地址100
sellerPhoneString否　　销方电话20
sellerBankString否　　销方开户银行100
sellerAccountString否　　销方银行账号30
clerkerString是　　开票员20
payeeString否　　收款人20
checkerString否　　复核人20
buyerNameString是　　购方名称100
buyerTaxnumString否　　购方税号20
buyerAddressString否　　购方地址100
buyerPhoneString否　　购方电话50
buyerBankString否　　购方开户银行100
buyerAccountString否　　购方银行账户30
orderNoString否　　订单编号64
orderDateString否2022-05-12年-月-日订单日期10
deliverDateString否2022-05-12年-月-日发货日期10
invoiceTypeString是　　1：蓝票；2：红票。发票类型2
taxAmountTotalBigDecimal是　　含税金额　
taxFreeAmountTotalBigDecimal是　　不含税金额　
taxTotalBigDecimal是　　合计税额　
invoiceLineString是　　p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票发票种类2
createTimeDate否　　创建时间　
invoiceTimeDate是　　开票时间　
invalidTimeDate否　　作废时间　
invalidStateInteger否　0 未提交 , 1 作废成功 , 2 作废失败 , 3 已提交(作废中)作废状态2
requestSrcInteger否　0-API调用，1-手工开票，2-批量导入，3-防伪开票，4-扫码开票，5-本地提取，6-诺诺发票，默认5请求来源1
remarkString否　　备注

数电电票：200(中文计算一位)

+

其他发票：230(中文计算两位)

invoiceCodeString是　不足请左补0发票代码12
invoiceNumberString是　不足请左补0发票号码8
oriInvoiceCodeString否　不足请左补0对应蓝票代码12
oriInvoiceNumberString否　不足请左补0对应蓝票号码8
listFlagInteger是　　清单标志2
listGoodsNameString否　　清单发票项目名称90
extensionNumInteger否　　分机号5
machineNumerString否　　机器编号12
terminalNumInteger否　　终端号5
pdfUrlString否　　发票pdf地址255
paperPdfUrlString否　　纸票pdf地址255
imageUrlString否　　图片地址(多个图片使用逗号隔开)255
checkCodeString否　　校验码32
qrCodeString否　　二维码100
invoiceCipherString否　　发票密文200
ofdUrlString否　　ofd地址255
pictureUrlString否　　发票详情地址255
substituteFlagInteger是　0非代开;1代开。默认值0代开标志2
departmentIdLong否　　部门门店id20
userIdLong否　　开票员Id20
productOilFlagInteger是　0非成品油，1成品油成品油标志2
vehicleFlagInteger否0非机动车，1机动车，默认为0专票机动车标志2
billInfoNoString否　　对应红字信息表编号24
columnFirstString否　　自定义列一255
columnSecondString否　　自定义列二255
columnThreeString否　　自定义列三255
bizCallbackUrlString否　　业务系统回调地址255
departCodeString否部门编码50
projectCodeString否项目编码64
projectNameString否项目名称300
freshInvoiceLimitFlagInteger否0-不更新，1-更新，默认-0是否更新项目开票限额标志
detailList是　明细数组电子发票明细　
detailIndexInteger是　明细行索引。机动车非必填明细序号5
detailTypeInteger是　0,正常行;1,折扣行;2,被折扣行。机动车非必填明细行性质2
goodsNameString是　非机动车发时，必填。机动车非必填。商品名称90
withTaxFlagInteger是　

0:不含税,1:含税。

+

机动车票非必填。机动车非必填。

单价含税标志2
goodsPriceBigDecimal否　　含税单价　
taxFreePriceBigDecimal否　　不含税单价　
goodsNumBigDecimal否　　数量　
taxrateString是　红票时选填税率10
specTypeString否　　规格型号40
goodsUnitString否　　单位22
goodsCodeString否　　税收分类编码19
goodsCodeAbbString否　　税收分类编码简称200
selfCodeString否　　自行编码20
favouredPolicyFlagInteger是　0：不使用，1：使用。机动车票非必填。优惠政策标识2
favouredPolicyNameString否　标识为1时内容必填。优惠政策内容50
zeroRateFlagString否　零税率标识:空-非零税率;1-免税;2-不征税;3-普通零税率零税率标识2
deductionBigDecimal否　　扣除额　
taxAmountBigDecimal否　机动车必填。含税金额　
taxFreeAmountBigDecimal否　机动车必填。不含税金额　
taxBigDecimal否　机动车必填。税额　
columnFirstString否明细自定义列1255
columnSecondString否明细自定义列2255
columnThreeString否明细自定义列3255
columnFourString否明细自定义列4255
columnFiveString否明细自定义列5255
subjectAccountCodeString否T123核算主体编码维护在诺税通的“核算主体编码”200
subjectAccountString否核算主体名称核算主体名称核算主体名称200
机动车发票明细机动车发票明细
vehicleTypeString否　机动车发票时必填车辆类型40
brandModelString否　机动车发票时必填厂牌型号60
productOriginString否　机动车发票时必填产地32
certificateString否　　合格证号50
importCertifyNumString否　　进口说明书号50
inspectionOddNumString否　　商检单号50
engineNumString否　　发动机号50
vehicleCodeString否机动车发票时必填车架号码/车辆识别代号50
measureUnitsString否　　吨位20
maxCapacityString否　　限乘人数10
organizationCodeString否　机动车发票时必填身份证号/组织机构代码25
produceCompanyNameString否　　生产企业名称50
taxOfficeCodeString否　　税务机关代码100
taxOfficeNameString否　　税务机关名称100
intactCertificateNumString否　　完整凭证号码50
+ +### 请求示例 + + +++ + + + + + +

{

+

"buyerName": "测试购方企业",

+

"clerker": "小红",

+

"vehicleFlag" : 1,

+

"detail": [

+

{

+

"tax": "3",

+

"taxrate": "0.03",

+

"taxFreeAmount": "100",

+

"taxAmount": "103",

+

"vehicleType": "轿车",

+

"brandModel": "宝马3系",

+

"productOrigin": "北京",

+

"certificate": "WDL042613263551",

+

"importCertifyNum": "646464",

+

"engineNum": "1001111",

+

"vehicleCode": "LHGK43284342384234",

+

"intactCertificateNum": "1221",

+

"measureUnits": "3",

+

"maxCapacity": "5",

+

"taxOfficeCode": "665",

+

"taxOfficeName": "0564"

+

}

+

],

+

"machineNumber": "5454",

+

"terminalNum": "5454",

+

"extensionNum": "5454",

+

"invoiceCode": "000011112955",

+

"invoiceNumber": "00001111",

+

"invoiceLine": "j",

+

"invoiceTime": "2021-03-12T14:59:25.715",

+

"invoiceType": 1,

+

"listFlag": 0,

+

"productOilFlag": 0,

+

"requestSrc": 5,

+

"sellerName": "移动测试盘326",

+

"sellerTaxnum": "150301199811285326",

+

"substituteFlag": 0,

+

"taxAmountTotal": "12.01",

+

"taxFreeAmountTotal": "12.01",

+

"taxTotal": "12.01"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | Integer | 是 | 200 | | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | | 收票状态 | | +| data | String | | | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": ""

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 2505,

+

"message": "公司不存在"

+

}

+ +### 状态码说明 + +| | | +|:--:|:--:| +| **状态码** | **描述** | +| 2505 | 公司不存在 | +| 2686 | 含税标识错误 | +| 26960 | 明细中（单价、商品数量）和（不含税金额、含税金额、税额）不能同时为空 | +| 2696 | 明细中商品数量不能为空，且长度不能超过29位 | +| 2705 | 明细中折扣行必须紧挨被折扣行之后 | +| 26770 | 明细中序号不能为空 | +| 2680 | 发票行性质错误 | +| 2800 | 车辆类型必填 | +| 2801 | 车辆类型超长 | +| 2802 | 厂牌号必填 | +| 2803 | 厂牌号超长 | +| 2804 | 产地必填 | +| 2805 | 产地超长 | +| 2806 | 车架号必填 | +| 2807 | 车架号超长 | +| 2808 | 身份证号必填 | +| 2809 | 身份证号超长 | +| 2810 | 生产企业名称必填 | +| 2811 | 生产企业名称超长 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/新增_修改企业开票信息.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/新增_修改企业开票信息.md new file mode 100644 index 0000000..85cb4e9 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/新增_修改企业开票信息.md @@ -0,0 +1,123 @@ +--- +title: 新增/修改企业开票信息 +aliases: + - 新增/修改企业开票信息 + - 诺税通新增/修改企业开票信息 + - 设备企业与配置-新增/修改企业开票信息 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 新增/修改企业开票信息 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/seller/save.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 新增/修改企业开票信息 + +### 接口说明 + +创建/修改企业开票信息接口 + +### 接口地址 + +| | +|:---------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/seller/save.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| taxNum | String | 是 | 企业税号 | 15～20 | +| useScope | Integer | 必填 | 使用范围，0企业,1:个人,2部门,3项目 | 1 | +| clerker | String | 必填 | 使用范围是个人时必填，填入用户管理手机号，使用范围为公司、部门、项目时非必填，直接填入值 | 100 | +| sellerAddress | String | 必填 | 公司地址 | 100 | +| sellerTel | String | 必填 | 公司电话 | 20 | +| sellerBank | String | 必填 | 开户银行 | 100 | +| sellerAccount | String | 必填 | 银行账号 | 50 | +| payee | String | 选填 | 收款人 | 20 | +| checker | String | 选填 | 复核人 | 20 | +| projectCode | String | 选填 | 当前企业下的项目编码 使用范围为项目时必填 | 64 | +| departmentName | String | 选填 | 当前企业下的部门名称 使用范围为部门时必填 | 100 | + +注意： + +1. 公司地址+公司电话总共不得超过100个字符 + +2. 开户银行+银行账号总共不得超过100个字符 + +### 请求示例 + + +++ + + + + + +

{

+

  "taxNum": "33333333333333333",

+

  "useScope": 1,

+

  "clerker": "13655554433",

+

  "sellerAddress": "地址",

+

  "sellerTel": "tel",

+

  "sellerAccount": "account",

+

  "sellerBank": "bank",

+

  "payee": "",

+

  "checker": "",

+

"projectCode": "test123",

+

  "departmentName": "测试部门"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/更新发票票据关联状态接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/更新发票票据关联状态接口.md new file mode 100644 index 0000000..fb6d05f --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/更新发票票据关联状态接口.md @@ -0,0 +1,107 @@ +--- +title: 更新发票票据关联状态接口 +aliases: + - 更新发票票据关联状态接口 + - 诺税通更新发票票据关联状态接口 + - 车辆辅助与回传-更新发票票据关联状态接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 更新发票票据关联状态接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/updateInvoiceAssociationStatus.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 更新发票票据关联状态接口 + +### 接口说明 + +更新发票票据关联状态接口。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/updateInvoiceAssociationStatus.do | + +### 请求参数(用json格式接收) + +| | | | | | | +|:---------------------:|:--------:|:--------:|:--------------:|:---:|:--------:| +| **名称** | **类型** | **必填** | **描述** | | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | | 20 | +| uploadStatus | String | 是 | 工信部上传状态 | | 12 | +| **发票代码+发票号码** | | | | | | +| invoiceCode | String | 是 | 发票代码 | 12 | | +| invoiceNumber | String | 是 | 发票号码 | 8 | | + +### 请求示例 + + +++ + + + + + +

{

+

"invoiceAssociations": [

+

{

+

"invoiceCode": "1500020560",

+

"invoiceNumber": "87609473"

+

}

+

],

+

"sellerTaxnum": "150301199811285326",

+

"uploadStatus": "上传成功"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

    "code":200,

+

    "message":"成功",

+

    "data":  null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询可下载发票库存列表接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询可下载发票库存列表接口.md new file mode 100644 index 0000000..703e901 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询可下载发票库存列表接口.md @@ -0,0 +1,125 @@ +--- +title: 查询可下载发票库存列表接口 +aliases: + - 查询可下载发票库存列表接口 + - 诺税通查询可下载发票库存列表接口 + - 库存票源与打印-查询可下载发票库存列表接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 查询可下载发票库存列表接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/stock/getDownloadableStock.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 查询可下载发票库存列表接口 + +### 接口说明 + +查询诺税通库中可下载发票库存列表 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/stock/getDownloadableStock.do | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 否 | 分机号，纯数字 | \- | +| machineNumber | String | 否 | 机器编号，12位数字 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": 28,

+

"machineNumber": "661103844159",

+

"sellerTaxnum": "110101999999999618"

+

}

+ +### 返回参数 + +| | | | | | +|:------------------:|:----------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | 是 | | | +| data内字段说明 | | | | | +| sellerTaxnum | String | | 销方税号 | | +| extensionNum | String | | 分机号 | | +| machineNumber | String | | 机器编号 | | +| invoiceCode | String | | 发票代码 | | +| invoiceLine | String | | 发票种类 | | +| invoiceNumStart | String | | 发票号码起始值 | | +| invoiceNumEnd | String | | 发票代码终止值 | | +| num | Integer | | 发票可下载数量 | | +| singleBillingLimit | BigDecimal | | 单张开票限额 | | +| updatedTime | String | | 更新时间 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"sellerTaxnum": "110101999999999618",

+

"extensionNum": 28,

+

"machineNumber": "661103844159",

+

"invoiceLine": "p",

+

"invoiceCode": "050002000208",

+

"num": 39899,

+

"singleBillingLimit": null,

+

"invoiceNumStart": "93666868",

+

"invoiceNumEnd": null,

+

"updatedTime": "2022-05-25 13:24:54"

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询成品油库存列表接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询成品油库存列表接口.md new file mode 100644 index 0000000..936d06c --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询成品油库存列表接口.md @@ -0,0 +1,121 @@ +--- +title: 查询成品油库存列表接口 +aliases: + - 查询成品油库存列表接口 + - 诺税通查询成品油库存列表接口 + - 专项能力-查询成品油库存列表接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 查询成品油库存列表接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/oilStock/getOilStockInfoList.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 查询成品油库存列表接口 + +### 接口说明 + +查询诺税通库中成品油库存列表接口，包括税盘可使用的和局端可下载的。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/oilStock/getOilStockInfoList.do | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 是 | 分机号，纯数字 | \- | +| machineNumber | String | 否 | 机器编号，12位数字 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum": 0,

+

"machineNumber": "661565671900",

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | +| data内字段说明 | | | | | +| sellerTaxnum | String | 是 | 销方税号 | | +| extensionNum | String | 是 | 分机号 | | +| machineNumber | String | 是 | 机器编号 | | +| oilType | String | 是 | 成品油类型 | | +| taxCode | String | 是 | 税收分类编码 | | +| downloadedStockAmount | String | 是 | 开票设备中已下载可使用库存（升） | | +| downloadableStockAmount | String | 是 | 局端可下载库存（升） | | +| updateTime | String | 是 | 更新时间 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

    "code":200,

+

    "message":"成功",

+

    "data":[

+

        {

+

"sellerTaxnum": "150301199811285326",

+

"extensionNum": 0,

+

"machineNumber": "661565671900",

+

            "oilType":"汽油",

+

            "taxCode":"1070101010100000000",

+

            "downloadedStockAmount":"8366796.99",

+

            "downloadableStockAmount":"0.00",

+

            "updateTime":"2021-12-24 14:06:37"

+

        }

+

    ]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询授信额度数据.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询授信额度数据.md new file mode 100644 index 0000000..ae9343c --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询授信额度数据.md @@ -0,0 +1,136 @@ +--- +title: 查询授信额度数据 +aliases: + - 查询授信额度数据 + - 诺税通查询授信额度数据 + - 专项能力-查询授信额度数据 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 查询授信额度数据 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/creditQuota/queryLocalData.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 查询授信额度数据 + +### 接口说明 + +获取数电发票授信额度,该接口根据不同设备类型，返回不同结果。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/creditQuota/queryLocalData.do | + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| taxNum | String | 是 | 需要查询的企业税号 | 企业税号 | 20 | +| type | Integer | 否 | 分机号与请求类型二选一必填，均传入已分机号匹配到的设备为准 | 请求类型 0:乐企 1:数电普通 | \- | +| extensionNum | Integer | 否 | 分机号与请求类型二选一必填，均传入已分机号匹配到的设备为准 | 分机号 | 0-99999 | + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"type": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| 乐企模式返回字段 | | | | | | +| creditFlag | String | 是 | Y | 暂停授信标志 Y：暂停 N：未暂停 | 1 | +| creditQuotaAmount | BigDecimal | 是 | 10000.00 | 本月授信额度 | 12,2 | +| downloadAmount | BigDecimal | 是 | 10000.00 | 可用剩余额度 | 12,2 | +| downloadRemainAmount | BigDecimal | 是 | 10000.00 | 已下载额度 | 12,2 | +| remainAmount | BigDecimal | 是 | 10000.00 | 已下载未使用额度 | 12,2 | +| taxnum | String | 是 | 150301199811285326 | 企业税号 | 20 | +| vestPeriod | String | 否 | 202303 | 属期 格式：yyyyMM | | +| creditUpdateTime | Date | 是 | 2023-03-06 00:00:00 | 授信额度更新时间 | | +| 非乐企模式返回字段 | | | | | | +| creditQuotaAmount | BigDecimal | 是 | 10000.00 | 本月授信额度 | 12,2 | +| remainAmount | BigDecimal | 是 | 10000.00 | 可用剩余额度 | 12,2 | +| queryStatus | Integer | 是 | 1 | 查询状态 0:查询中 1:查询成功 2:查询失败 | 1 | +| creditUpdateTime | Date | 是 | 2023-03-06 00:00:00 | 授信额度更新时间 | | +| message | String | 否 | 分机信息不存在 | 查询失败原因 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": "200",

+

"message": "查询成功",

+

"data":{

+

"creditFlag": "Y",

+

"creditQuotaAmount": "10000.00" ,

+

"downloadAmount": "10000.00",

+

"downloadRemainAmount": "10000.00",

+

"remainAmount": "10000.00",

+

"taxnum": "150301199811285326",

+

"vestPeriod": "202303",

+

"creditUpdateTime": "2023-03-06 00:00:00"

+

}

+

}

+

非乐企:

+

{

+

"code": "200",

+

"message": "查询成功",

+

"data": {

+

"creditQuotaAmount": "10000.00",

+

"downloadAmount": "10000.00",

+

"queryStatus":1,

+

"creditUpdateTime": "2023-03-06 00:00:00",

+

"message": "分机信息不存在"

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询获取车架号是否可开票结果接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询获取车架号是否可开票结果接口.md new file mode 100644 index 0000000..bd3f582 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/查询获取车架号是否可开票结果接口.md @@ -0,0 +1,134 @@ +--- +title: 查询获取车架号是否可开票结果接口 +aliases: + - 查询获取车架号是否可开票结果接口 + - 诺税通查询获取车架号是否可开票结果接口 + - 车辆辅助与回传-查询获取车架号是否可开票结果接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 查询获取车架号是否可开票结果接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/query/queryVehicleCodeIsInvoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 查询获取车架号是否可开票结果接口 + +### 接口说明 + +获取车架号是否可开票结果接口。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/query/queryVehicleCodeIsInvoice.do | + +### 请求参数(用json格式接收) + +| | | | | | +|:---------------:|:----------:|:--------:|:----------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| vehicleCodeList | String\[\] | 是 | 车架号，支持最多2000个 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"vehicleCodeList": [

+

"111"

+

]

+

}

+ +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | | 查询成功则返回车架号记录信息 | | +| **车架号记录信息** | | | | | +| sellerTaxnum | String | 是 | 销方税号 | 20 | +| companyCode | String | 是 | 企业编码 | 20 | +| vehicleCode | String | 是 | 车架号 | 23 | +| status | String | 是 | 车架号状态：1-可开票;2-查询中;3-未知;4-不可开票;5-已开票 | 2 | +| certificate | String | \- | 合格证号，查询到车架号所属该税号且未开票时后端返回有值 | 50 | +| machineNum | String | \- | 设备编号，查询到车架号所属该税号且未开票时后端返回有值 | 12 | +| importCertifyNum | String | \- | 进口证明书编号，查询到车架号所属该税号且未开票时后端返回有值 | 32 | +| message | String | 否 | 描述信息，举例：合格证已被使用； | 1024 | +| requestSrc | String | 是 | 请求来源(0:未知;1-页面添加;2-页面导入;3-api进项调用;4-api用户调用;5-开票) | 2 | +| brandModel | String | 否 | 厂牌型号 | 60 | +| engineNum | String | 否 | 发动机号码 | 50 | +| vehicleType | String | 否 | 车辆类型 | 40 | +| inspectionOddNum | String | 否 | 商检单号 | 32 | +| productOrigin | String | 否 | 产地 | 32 | +| displacement | String | 否 | 排量 | 50 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"sellerTaxnum": "150301199811285326",

+

"companyCode": "1100",

+

"vehicleCode": "111",

+

"status": 2,

+

"certificate": "1",

+

"machineNum": "134874514782",

+

"importCertifyNum": "13242234",

+

"message": "未查询到合格证信息，不允许开具发票",

+

"requestSrc": "3",

+

"brandModel": "",

+

"engineNum": "",

+

"vehicleType": "",

+

"inspectionOddNum": "",

+

"productOrigin": ""

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/根据业务标识查询对应值列表接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/根据业务标识查询对应值列表接口.md new file mode 100644 index 0000000..f03c6c3 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/根据业务标识查询对应值列表接口.md @@ -0,0 +1,127 @@ +--- +title: 根据业务标识查询对应值列表接口 +aliases: + - 根据业务标识查询对应值列表接口 + - 诺税通根据业务标识查询对应值列表接口 + - 设备企业与配置-根据业务标识查询对应值列表接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 根据业务标识查询对应值列表接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/oa/getOaOptionList.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 根据业务标识查询对应值列表接口 + +### 接口说明 + +根据业务标识查询对应的值列表，给OA审批流使用 + +### 接口地址 + +| | +|:----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/oa/getOaOptionList.do | + +### 请求参数 + +| | | | | +|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | +| type | String | 是 | 业务类型：开票方式:requestSrc,发票种类:invoiceLine,组织名称:organize,部门名称:dept,开票员:clerk,作废来源：invalidSrc | +| name | String | 否 | 名称，根据名称模糊查询 | +| pageNum | int | 否 | 当前页，默认为1 | +| pageSize | int | 否 | 分页条数，默认为15 | + +### 请求示例 + + +++ + + + + + +

{

+

"pageNum": 1,

+

"pageSize": 15,

+

"type": "dept",

+

"name": "测试部门2"

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | Integer | 是 | 200 | | 状态,200-成功，非200-失败 | 6 | +| message | String | | 成功 | | 详细信息 | 1024 | +| data | Object | | | | 数据对象 | | +| **数据信息** | | | | | | | +| pageNum | int | 是 | 1 | | 当前页数 | | +| pageSize | int | 是 | 15 | | 每页条数 | | +| pages | int | 是 | 1 | | 总页数 | | +| total | int | 是 | 2 | | 数据总数 | | +| list | List | | | | 查询成功则返回具体信息 | | +| **具体信息** | | | | | | | +| key | String | | 201127 | | 唯一标识 | | +| name | String | | 测试部门2 | | 名称 | | +| companyId | long | | 10162 | | 企业id，业务类型为dept、clerk时返回 | | +| companyName | String | | 移动测试盘326 | | 企业名称，业务类型为dept、clerk时返回 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"total": "9",

+

"list": [

+

{

+

"key": "201127",

+

"name": "测试部门2-2",

+

"companyName": "移动测试盘326",

+

"companyId": "10162"

+

}

+

],

+

"pageNum": 1,

+

"pageSize": 2,

+

"pages": 5

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/登录扫码认证确认接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/登录扫码认证确认接口.md new file mode 100644 index 0000000..601ef96 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/登录扫码认证确认接口.md @@ -0,0 +1,255 @@ +--- +title: 登录扫码认证确认接口 +aliases: + - 登录扫码认证确认接口 + - 诺税通登录扫码认证确认接口 + - 设备企业与配置-登录扫码认证确认接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 登录扫码认证确认接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/auth/authAffirm.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 登录扫码认证确认接口 + +### 接口说明 + +用于3.53获取登录扫码认证二维码（对应qrCodeType=1、2、3、4）后的二次确认登录操作 + +注意：电子税务局认证操作的数电账号（分机号） 和 登录二次确认操作的数电账号（分机号）必须为同一个 + +### 接口地址 + +| | +|:-------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/auth/authAffirm.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
taxNumString是税号20
extensionNumInteger否分机号，分机号和数电账号任一必填-
accountString否数电账号，分机号和数电账号任一必填20
opTypeInteger否

操作类型：

+

0-扫码登录验证完成操作（默认）

+

1-查询扫码登录结果

+

2-短信登录提交登录（此时填写verifyCode）

+

3-查询短信登录结果

1
verifyCodeString否

短信验证码（当数电发票开具进行短信验

+

证码登录时才需要传）

10
+ +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326"，

+

"extensionNum": 1，

+

"account": "123456"，

+

"opType": 2，

+

"verifyCode": "1236"

+

}

+ +### 返回参数 + + ++++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填示例值描述长度
codeInteger是200状态,200-成功，非200-失败6
messageString是成功详细信息1024
dataObject结果
statusString10-登录执行中；1-成功；2-失败
messageString登录成功结果信息（登录成功/失败原因）
loginTypeInteger

登录方式：

+
    +

  1. 扫码登录

    2. +

  2. 短信验证码登录

    3. +
taxNumString339901999999199税号
extensionNumInteger100分机号
accountString138****1234用户名/手机号（脱敏处理）
+ +### 返回示例 + +成功示例： + + +++ + + + + + +

{
+"code":200,
+"message": "成功"，

+

"data":

+

{

+

"account": "123456",

+

"taxNum": "1234567890",

+

"status": "1",

+

"message": "登录成功",

+

"loginType": 2,

+

"extensionNum": 123

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/票源下载接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/票源下载接口.md new file mode 100644 index 0000000..ac29db9 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/票源下载接口.md @@ -0,0 +1,117 @@ +--- +title: 票源下载接口 +aliases: + - 票源下载接口 + - 诺税通票源下载接口 + - 库存票源与打印-票源下载接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 票源下载接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/stock/downInvoiceSource.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 票源下载接口 + +### 接口说明 + +票源下载接口 + +### 接口地址 + +| | +|----| +| http\[s\]://\\[:\\]/salescore/lan/stock/downInvoiceSource.do | + +### 请求参数 + +| | | | | | | +|:------------:|:--------:|:--------:|:--------------------------:|:--------:|:--------:| +| **名称** | **类型** | **必填** | **更多限制** | **描述** | **长度** | +| sellerTaxnum | String | 是 | | 销方税号 | 20 | +| extensionNum | String | 否 | 至少分机号或机器号任一必填 | 分机号 | 5 | +| machineNum | String | 否 | 至少分机号或机器号任一必填 | 机器号 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum":"0",

+

"machineNum":"661565671900",

+

"sellerTaxnum":"150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | + +### 返回示例 + +成功示例 + + +++ + + + + + +

{

+

    "code": 200,

+

    "message": "成功",

+

    "data": null

+

}

+ +失败示例 + + +++ + + + + + +

{

+

    "code": 27761,

+

    "message": "请传入分机号或机器编号",

+

    "data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/空白发票作废申请.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/空白发票作废申请.md new file mode 100644 index 0000000..0776788 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/空白发票作废申请.md @@ -0,0 +1,111 @@ +--- +title: 空白发票作废申请 +aliases: + - 空白发票作废申请 + - 诺税通空白发票作废申请 + - 作废重开与冲红-空白发票作废申请 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 空白发票作废申请 + +> [!info] 导航 +> 上级索引：[[README]] · [[03_作废重开与冲红]] +> 文档链接：[总索引](../README.md) · [分组页](../03_作废重开与冲红.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[03_作废重开与冲红]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/blankInvoiceInvalid.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 空白发票作废申请 + +### 接口说明 + +空白发票作废申请接口 + +### 接口地址 + +| | +|:-----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/blankInvoiceInvalid.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | 20 | +| extensionNum | String | 是 | 分机号 | 5 | +| machineNum | String | 是 | 税控设备号（机器编码） | 12 | +| terminalNum | String | 否 | 终端号 | 10 | +| invoiceLine | String | 必填，发票种类对应枚举值，例:p:普通发票(电子) | 发票种类，c:增值税普通发票(纸票)，s:增值税专用发票，f:收购发票(纸质)，j：机动车发票，u：二手车发票 | 1 | +| invoiceCode | String | 是 | 发票代码 | 12 | +| invoiceNum | String | 是 | 发票号码 | 8 | +| invalidNum | String | 否 | 作废份数，目前仅支持作废1张，默认为1 | 1 | +| userId | Long | 否 | 诺税通用户ID | | +| departmentId | Long | 否 | 诺税通部门ID | | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"extensionNum":" 1",

+

"machineNum":" 661929539468",

+

"invoiceLine": "c"

+

"invoiceCode":" 033001800105",

+

"invoiceNum":" 33111355",

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | String | | 查询成功则返回申请流水号 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": "123456789"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表_红字确认单回传.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表_红字确认单回传.md new file mode 100644 index 0000000..e17a028 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表_红字确认单回传.md @@ -0,0 +1,644 @@ +--- +title: 红字信息表/红字确认单回传 +aliases: + - 红字信息表/红字确认单回传 + - 诺税通红字信息表/红字确认单回传 + - 红字信息表-红字信息表/红字确认单回传 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表/红字确认单回传 + +> [!info] 导航 +> 上级索引：[[README]] · [[04_红字信息表]] +> 文档链接：[总索引](../README.md) · [分组页](../04_红字信息表.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[04_红字信息表]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`用户通过红字信息表/确认单申请请求中的bizCallbackUrl字段进行回调，若接口不传回传地址，则使用开票配置中配置的红字信息表/红字确认单回传地址。` +> - 请求方式：`POST` +> - 是否回调：是 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字信息表/红字确认单回传 + +### 接口说明 + +返回红字信息表/红字确认单信息。 + +注意：请按照文档要求提供接口。 + +### 接口地址 + +用户通过红字信息表/确认单申请请求中的bizCallbackUrl字段进行回调，若接口不传回传地址，则使用开票配置中配置的红字信息表/红字确认单回传地址。 + +数电票种回传红字确认单信息，非数电票种回传红字信息表。通过backType类型区分回传红字信息表或红字确认单。 + +信息表触发回传的状态：申请失败、审核通过、审核未通过、已撤销、撤销失败 + +确认单触发回传的状态：无需确认、购销双方已确认、作废（销方录入购方否认）、作废（购方录入销方否认）、作废（超72小时未确认）、作废（发起方撤销）、作废（确认方撤销） + +### 请求参数(用json格式接收) + +backType=1时，回传红字信息表结果。 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
backTypeInteger是回传类型, 1: 红字信息表 2：红字确认单2
billNoString是申请单号24
billTypeString否

信息表类型(0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回

+

4、矿产品类专用信息表（涉及销售数量和金额变更）

+

5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动）

1
oriInvoiceCodeString否对应蓝票代码12
oriInvoiceNumberString否对应蓝票号码8
oriInvoiceTimeString否

对应蓝票开票日期

+

yyyy-MM-dd HH:mm:ss

19
taxTypeString否税种类别(0:营业税 1:增值税)1
taxRateString否税率：单税率就保存税率，如0.13；多税率M1
buyerNameString否购方名称100
buyerTaxnumString否购方税号20
buyerAddressString否购方地址100
buyerPhoneString否购方电话50
buyerBankString否购方银行100
buyerAccountString否购方账号30
sellerNameString否销方名称100
sellerTaxnumString否销方税号20
taxFreeAmountTotaldecimal否不含税金额15.2
taxTotaldecimal否合计税额15.2
billTimeString否

填开时间

+

yyyy-MM-dd HH:mm:ss

19
applyRemarkString否申请说明（购方已抵扣：1100000000,购方未抵扣：1010000000,销售方申请：0000000100）10
businessTaxCodeString否营业税标志10
billInfoNoString否信息表编号24
billStatusString否

信息表状态(-1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销

+

-2:删除成功)

2
billMessageString否[信息表状态代码]信息表状态描述300
pdfUrlString否申请表pdf url255
detailListList是明细列表
specificFactorString否

特定要素：0普通发票 01成品油 03建筑服务 04货物运输发票 05不动产销售发票 06不动产租赁发票 09旅客运输发票 14机动车 16农产品收购 33二手车反向开具

+

35 矿产品发票

50
+ +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **商品明细** detailList | | | | | +| **名称** | **类型** | **必填** | **描述** | **长度** | +| detailIndex | String | 是 | 单据明细序号 | 5 | +| goodsName | String | 是 | 商品名称 | 90 | +| goodsUnit | String | 否 | 单位 | 22 | +| specType | String | 否 | 规格型号 | 40 | +| withTaxFlag | int | 是 | 单价含税标志，0:不含税,1:含税 | 1 | +| goodsPrice | decimal | 否 | 含税单价 | decimal(32,16) | +| taxFreePrice | decimal | 否 | 不含税单价 | decimal(32,16) | +| goodsNum | decimal | 否 | 数量 | decimal(32,16) | +| taxFreeAmount | decimal | 否 | 不含税金额 | (15,2) | +| tax | decimal | 否 | 税额 | (15,2) | +| taxAmount | decimal | 否 | 含税金额 | (15,2) | +| taxrate | decimal | 是 | 税率 | 1 | +| goodsCode | String | 否 | 税收分类编码 | 19 | +| goodsCodeAbb | String | 否 是 | 税收分类编码简称 | 200 | +| selfCode | String | 否 | 自行编码 | 20 | +| favouredPolicyFlag | String | 是 | 优惠政策标识，0:不使用;1:使用 | 2 | +| favouredPolicyName | String | 否 | 优惠政策内容，如：即征即退、免税、不征税、简易征收等 | 50 | +| zeroRateFlag | String | 否 | 零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率 | 2 | +| deduction | decimal | 否 | 扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00 | (15,2) | + +backType=2，则回传红字确认单。 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
backTypeInteger是回传类型, 1: 红字信息表 2：红字确认单2
billIdString是申请单号32
billNoString否确认单编号32
billUuidString否确认单uuid32
billStatusString是

确认单状态

+

-1 提交失败

+

00 提交中

+

01 无需确认

+

02 销方录入待购方确认

+

03 购方录入待销方确认

+

04 购销双方已确认

+

05 作废（销方录入购方否认）

+

06 作废（购方录入销方否认）

+

07 作废（超72小时未确认）

+

08 作废（发起方撤销）

+

09 作废（确认方撤销）

+

15 提交税局中

+

16 提交税局失败

4
billMessageString否[确认单状态代码]确认单状态描述300
openStatusString否

开具状态

+

0：未开具

+

1：已开具

2
applySourceString是

申请来源

+

0 销方

+

1 购方

2
billTimeString否

填开时间

+

yyyy-MM-dd HH:mm:ss

19
taxFreeAmountTotaldecimal否不含税金额15.2
taxTotaldecimal否合计税额15.2
taxAmountTotaldecimal否含税金额15.2
blueInvoiceNumberString否对应蓝票号码20
blueInvoiceNoString否蓝字增值税发票号码(如果蓝票为增值税发票，则增值税代号码必填)8
blueInvoiceCodeString否蓝字增值税发票代码(如果蓝票为增值税发票，则增值税代号码必填)12
blueInvoiceLineString否

蓝票票种

+

bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)

+

p:电子增值税普通发票，

+

c:增值税普通发票(纸票)，

+

s:增值税专用发票，

+

b:增值税电子专用发票

5
sellerNameString否销方名称100
sellerTaxnumString否销方税号20
buyerNameString否购方名称100
buyerTaxnumString否购方税号20
vatUsageString否蓝字发票增值税用途2
saleTaxUsageString否蓝字发票消费税用途2
accountStatusString否发票入账状态2
redReasonString是

冲红原因

+

1开票有误

+

2销货退回

+

3服务中止

+

4销售折让

2
detailList否确认单明细
+ +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **确认单明细** detail | | | | | +| **名称** | **类型** | **必填** | **描述** | **长度** | +| detailIndex | Integer | 是 | 单据明细序号 | 5 | +| blueDetailIndex | Integer | 是 | 对应数电蓝票明细行 | 5 | +| goodsName | String | 是 | 商品名称 | 90 | +| goodsUnit | String | 否 | 单位 | 22 | +| specType | String | 否 | 规格型号 | 40 | +| withTaxFlag | int | 是 | 单价含税标志，0:不含税,1:含税 | 1 | +| goodsPrice | decimal | 否 | 含税单价 | decimal(32,16) | +| taxFreePrice | decimal | 否 | 不含税单价 | decimal(32,16) | +| goodsNum | decimal | 否 | 数量 | decimal(32,16) | +| taxFreeAmount | decimal | 否 | 不含税金额 | (15,2) | +| tax | decimal | 否 | 税额 | (15,2) | +| taxAmount | decimal | 否 | 含税金额 | (15,2) | +| taxrate | String | 是 | 税率 | 10 | +| goodsCode | String | 否 | 税收分类编码 | 19 | +| goodsCodeAbb | String | 否 是 | 税收分类编码简称 | 200 | +| selfCode | String | 否 | 自行编码 | 20 | +| favouredPolicyFlag | String | 是 | 优惠政策标识 | 10 | +| favouredPolicyName | String | 否 | 优惠政策内容，如：即征即退、免税、不征税、简易征收等 | 50 | +| zeroRateFlag | String | 否 | 零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率 | 2 | +| deduction | decimal | 否 | 扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00 | (15,2) | + +### 请求示例 + +成功示例： + + +++ + + + + + +

{

+

"billNo": "12345678901234567890097q",

+

"billType": "0",

+

"oriInvoiceCode": "005000181530",

+

"oriInvoiceNumber": "45625450",

+

"oriInvoiceTime": null,

+

"taxType": "1",

+

"taxRate": "0",

+

"buyerName": "officia in irure",

+

"buyerTaxnum": "CILLUM",

+

"sellerName": "Excepteur dolor ",

+

"sellerTaxnum": "150301199811285326",

+

"taxFreeAmountTotal": "-1.00",

+

"taxTotal": "-1.00",

+

"billTime": "2020-05-26 03:14:15",

+

"applyRemark": "0000000100",

+

"businessTaxCode": "0000000000",

+

"billInfoNo": "",

+

"billStatus": 2,

+

"billMessage": "[B900006]申请单号不能为空或者格式不正确",

+

"pdfUrl": "",

+

"detailList": [

+

{

+

"detailIndex": 1,

+

"goodsName": "Ut min",

+

"withTaxFlag": null,

+

"goodsPrice": "0.0000000000000000",

+

"taxFreePrice": "0.0900000000000000",

+

"goodsNum": "-1.0000000000000000",

+

"taxrate": "0.09",

+

"specType": "nost",

+

"goodsUnit": "aliqu",

+

"goodsCode": "esseonsequ",

+

"goodsCodeAbb": "irure in",

+

"favouredPolicyFlag": 0,

+

"zeroRateFlag": "",

+

"favouredPolicyName": "",

+

"selfCode": "sed Lorem",

+

"deduction": "0.00",

+

"taxAmount": "-0.01",

+

"taxFreeAmount": "-0.09",

+

"tax": "-0.01"

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | String | 是 | 0000 | | 状态码，字符串”0000”表示成功，非”0000”的字符串表示失败 | 6 | +| message | String | 是 | 同步成功 | | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": "0000",

+

"message": "业务方接收同步成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": "9999",

+

"message": "同步失败的异常信息"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表下载接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表下载接口.md new file mode 100644 index 0000000..017423c --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表下载接口.md @@ -0,0 +1,187 @@ +--- +title: 红字信息表下载接口 +aliases: + - 红字信息表下载接口 + - 诺税通红字信息表下载接口 + - 红字信息表-红字信息表下载接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表下载接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[04_红字信息表]] +> 文档链接：[总索引](../README.md) · [分组页](../04_红字信息表.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[04_红字信息表]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/red-apply-down` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字信息表下载接口 + +### 接口说明 + +销方可调用专用发票红字信息表下载接口下载购买方申请的红字信息表。仅触发下载指令，需配合红字信息表查询接口获取详细的信息表信息。 + +### 接口地址 + +| | +|:---------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/red-apply-down | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
invoiceLineString是发票种类2
billInfoNoString否信息表编号24
sellerTaxnumString是销方税号20
buyerTaxnumString否购方税号20
redApplyStartTimeString否红字申请时间-查询起期（yyyyMMdd），时间跨度不能超过30天8
redApplyEndTimeString否

红字申请时间-查询止期（yyyyMMdd）

+

时间跨度不能超过30天

8
userIdLong否开票人id-
extensionNumInteger否分机号-
machineNumberString否机器编号12
+ +注意： + +1.查询开始时间、结束时间允许同时为空，或者同时不为空 + +2.如果时间同时为空，则信息表编号必填 + +### 请求示例 + + +++ + + + + + +

{

+

"billInfoNo": "",

+

"sellerTaxnum": "150301199811285326",

+

"buyerTaxnum": "339901999999513",

+

"invoiceLine": "s",

+

"redApplyStartTime": "20201201",

+

"redApplyEndTime": "20201229",

+

"userId": 1,

+

"extensionNum": 0,

+

"machineNumber": "661565671900"

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表撤销接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表撤销接口.md new file mode 100644 index 0000000..c520c2d --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表撤销接口.md @@ -0,0 +1,101 @@ +--- +title: 红字信息表撤销接口 +aliases: + - 红字信息表撤销接口 + - 诺税通红字信息表撤销接口 + - 红字信息表-红字信息表撤销接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表撤销接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[04_红字信息表]] +> 文档链接：[总索引](../README.md) · [分组页](../04_红字信息表.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[04_红字信息表]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/red-apply-cancel` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字信息表撤销接口 + +### 接口说明 + +专用发票红字信息表撤销申请接口。 + +### 接口地址 + +| | +|:-----------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/red-apply-cancel | + +### 请求参数 + +| | | | | | +|:-------------:|:--------:|:--------:|:----------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| billInfoNo | String | 是 | 信息表编号 | 24 | +| userId | Long | 否 | 开票人id | \- | +| extensionNum | Integer | 否 | 分机号 | \- | +| machineNumber | String | 否 | 机器编号 | 12 | + +### 请求示例 + + +++ + + + + + +

{

+

"billInfoNo": "1403011905003535",

+

"userId": 1,

+

"extensionNum": 0,

+

"machineNumber": "661565671900"

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表查询接口.md new file mode 100644 index 0000000..dbf7022 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表查询接口.md @@ -0,0 +1,407 @@ +--- +title: 红字信息表查询接口 +aliases: + - 红字信息表查询接口 + - 诺税通红字信息表查询接口 + - 红字信息表-红字信息表查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[04_红字信息表]] +> 文档链接：[总索引](../README.md) · [分组页](../04_红字信息表.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[04_红字信息表]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/red-apply-query` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字信息表查询接口 + +### 接口说明 + +专用发票红字信息表查询接口。 + +### 接口地址 + +| | +|:----------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/red-apply-query | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| billNo | String | 否 | 信息表流水号(12位税盘编号+12位蓝票开票时间YYMMDDHHMMSS) | 24 | +| billInfoNo | String | 否 | 信息表编号 | 24 | +| buyerTaxnum | String | 否 | 购方税号 | 20 | +| redApplyStartTime | String | 否 | 红字申请时间-查询起期（yyyy-MM-dd HH:mm:ss） | 19 | +| redApplyEndTime | String | 否 | 红字申请时间-查询止期（yyyy-MM-dd HH:mm:ss） | 19 | +| sellerTaxnum | String | 是 | 销方税号 | 20 | + +注意： + +1.billInfoNo或billNo为空时，redApplyStartTime必填。 + +2.billInfoNo或billNo为空时，redApplyEndTime不填时默认当前日期，并且时间范围不能超过60天。 + +### 请求示例 + + +++ + + + + + +

{

+

"billInfoNo": "",

+

"billNo": "",

+

"buyerTaxnum": "339901999999513",

+

"redApplyEndTime": "2020-12-29 23:00:00",

+

"redApplyStartTime": "2020-11-01 00:00:00",

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
codeInteger是状态,200-成功，非200-失败6
messageString是详细信息1024
dataList查询成功则返回红字申请信息
发票信息
billNoString否信息表流水号(12位税盘编号+12位蓝票开票时间YYMMDDHHMMSS)24
billTypeString否

信息表类型(0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回

+

4、矿产品类专用信息表（涉及销售数量和金额变更）

+

5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动）

1
oriInvoiceCodeString否对应蓝票代码12
oriInvoiceNumberString否对应蓝票号码8
oriInvoiceTimeString否

对应蓝票开票日期

+

yyyy-MM-dd HH:mm:ss

19
taxTypeString否税种类别(0:营业税 1:增值税)1
taxRateString否多税率标志(0:一票一税率 1:一票多税率)1
buyerNameString否购方名称100
buyerTaxnumString否购方税号20
buyerAddressString否购方地址100
buyerPhoneString否购方电话50
buyerBankString否购方银行100
buyerAccountString否购方账号30
sellerNameString否销方名称100
sellerTaxnumString否销方税号20
taxFreeAmountTotaldecimal否不含税金额15.2
taxTotaldecimal否合计税额15.2
billTimeString否

填开时间

+

yyyy-MM-dd HH:mm:ss

19
applyRemarkString否申请说明（购方已抵扣：1100000000,购方未抵扣：1010000000,销售方申请：0000000100）10
businessTaxCodeString否营业税标志10
billInfoNoString否信息表编号24
billStatusString否信息表状态(-1:未提交 0:申请中 1:审核成功 2:审核失败 3:申请成功 4:申请失败 5:已开具 6:撤销中 7:撤销失败 8:已撤销)2
billMessageString否[信息表状态代码]信息表状态描述300
pdfUrlString否申请表pdf url255
specificFactorString否

特定要素特定要素：0普通发票（默认）01成品油 14机动车 31建安发票 32房地产销售发票 34电子烟发票、35矿产品发票

+

注：开具矿产品发票时必传，此时billType只能为4或5

50
+ +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **商品明细** detailList | | | | | +| **名称** | **类型** | **必填** | **描述** | **长度** | +| detailIndex | String | 是 | 单据明细序号 | 5 | +| goodsName | String | 是 | 商品名称 | 90 | +| goodsUnit | String | 否 | 单位 | 22 | +| specType | String | 否 | 规格型号 | 40 | +| withTaxFlag | int | 是 | 单价含税标志，0:不含税,1:含税 | 1 | +| goodsPrice | decimal | 否 | 含税单价 | decimal(32,16) | +| taxFreePrice | decimal | 否 | 不含税单价 | decimal(32,16) | +| goodsNum | decimal | 否 | 数量 | decimal(32,16) | +| taxFreeAmount | decimal | 否 | 不含税金额 | (15,2) | +| tax | decimal | 否 | 税额 | (15,2) | +| taxAmount | decimal | 否 | 含税金额 | (15,2) | +| taxrate | decimal | 是 | 税率 | 1 | +| goodsCode | String | 否 | 税收分类编码 | 19 | +| goodsCodeAbb | String | 否 是 | 税收分类编码简称 | 200 | +| selfCode | String | 否 | 自行编码 | 20 | +| favouredPolicyFlag | String | 是 | 优惠政策标识，0:不使用;1:使用 | 2 | +| favouredPolicyName | String | 否 | 优惠政策内容，如：即征即退、免税、不征税、简易征收等 | 50 | +| zeroRateFlag | String | 否 | 零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率 | 2 | +| deduction | decimal | 否 | 扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00 | (15,2) | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"billNo": "12345678901234567890097q",

+

"billType": "0",

+

"oriInvoiceCode": "005000181530",

+

"oriInvoiceNumber": "45625450",

+

"oriInvoiceTime": null,

+

"taxType": "1",

+

"taxRate": "0",

+

"buyerName": "officia in irure",

+

"buyerTaxnum": "CILLUM",

+

"sellerName": "Excepteur dolor ",

+

"sellerTaxnum": "150301199811285326",

+

"taxFreeAmountTotal": "-1.00",

+

"taxTotal": "-1.00",

+

"billTime": "2020-05-26 03:14:15",

+

"applyRemark": "0000000100",

+

"businessTaxCode": "0000000000",

+

"billInfoNo": "",

+

"billStatus": 2,

+

"billMessage": "[B900006]申请单号不能为空或者格式不正确",

+

"pdfUrl": "",

+

"detailList": [

+

{

+

"id": "178",

+

"billNo": "12345678901234567890097q",

+

"detailIndex": 1,

+

"goodsName": "Ut min",

+

"withTaxFlag": null,

+

"goodsPrice": "0.0000000000000000",

+

"taxFreePrice": "0.0900000000000000",

+

"goodsNum": "-1.0000000000000000",

+

"taxrate": "0.09",

+

"specType": "nost",

+

"goodsUnit": "aliqu",

+

"goodsCode": "esseonsequ",

+

"goodsCodeAbb": "irure in",

+

"favouredPolicyFlag": 0,

+

"zeroRateFlag": "",

+

"favouredPolicyName": "",

+

"selfCode": "sed Lorem",

+

"deduction": "0.00",

+

"taxAmount": "-0.01",

+

"taxFreeAmount": "-0.09",

+

"tax": "-0.01",

+

"createTime": "2020-06-04 11:13:00",

+

"updateTime": "2020-06-04 11:13:00"

+

}

+

]

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表申请接口_不支持拆分_不推荐使用.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表申请接口_不支持拆分_不推荐使用.md new file mode 100644 index 0000000..0b6c08d --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表申请接口_不支持拆分_不推荐使用.md @@ -0,0 +1,418 @@ +--- +title: 红字信息表申请接口（不支持拆分，不推荐使用） +aliases: + - 红字信息表申请接口（不支持拆分，不推荐使用） + - 诺税通红字信息表申请接口（不支持拆分，不推荐使用） + - 红字信息表-红字信息表申请接口（不支持拆分，不推荐使用） +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表申请接口（不支持拆分，不推荐使用） + +> [!info] 导航 +> 上级索引：[[README]] · [[04_红字信息表]] +> 文档链接：[总索引](../README.md) · [分组页](../04_红字信息表.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[04_红字信息表]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/red-apply-submit` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字信息表申请接口（不支持拆分，不推荐使用） + +### 接口说明 + +针对专用发票进行红字信息表申请接口，不支持机动车专票按退货方式（信息表类型为2时）申请红字信息表时，自动拆分成8行一个信息表。 + +### 接口地址 + +| | +|:-----------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/red-apply-submit | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
invoiceLineString是发票种类2
billNoString否24位申请单号（12位开票设备编号+12位流水）24
billTypeString否

信息表类型(0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更）

+

5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动）

+

默认为：0正常

+

注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单）

+

若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填。

2
oriInvoiceCodeString否对应蓝票代码12
oriInvoiceNumberString否对应蓝票号码8
oriInvoiceTimeString否

蓝票填开时间（yyyy-MM-dd HH:mm:ss）

+

除了购方已抵扣，若没有对应的蓝票信息，oriInvoiceTime需必填

19
blueInvoiceTimeString否

蓝票填开时间（YYYYMM）

+

除了购方已抵扣，若没有对应的蓝票信息，blueInvoiceTime需必填，新局端要求上传对应蓝字发票开具时间（年月）

19
sellerNameString是销方名称100
sellerTaxnumString是销方税号20
buyerNameString是购方名称100
buyerTaxnumString是购方税号20
buyerAddressString否购方地址100
buyerPhoneString否购方电话50
buyerBankString否购方银行100
buyerAccountString否购方账号30
operatorString否经办人20
applyRemarkString是

申请说明

+

(购方已抵扣：1100000000 购方未KJ抵扣：1010000000 销售方申请：0000000100)

10
productOilFlagString否

成品油标识 0,非成品油;1,成品油

+

若没有对应的蓝票信息，productOilFlag必填

1
extensionNumberString否分机号11
terminalNumberString否终端号11
machineNumberString否机器号12
deptIdString否部门门店id（本地系统中的id）20
userIdString否开票人id（本地系统中的id）20
bizCallbackUrlString否业务系统回调地址255
detailListList是商品明细无
specificFactorString否

特定要素：0普通发票（默认）01成品油 14机动车 31建安发票 32房地产销售发票 34电子烟发票、35矿产品发票

+

注：开具矿产品发票时必传，此时billType只能为4或5，成品油发票特定要素和成品油标识选一即可，均传以特定要素为准。

50
notifyPhoneString否交付手机号码20
notifyEmailString否交付邮箱地址50
ccPhoneString否抄送手机号，当推送手机notifyPhone有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个100
ccEmailString否抄送邮箱，当推送邮箱notifyEmail有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个250
+ +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **商品明细** detailList | | | | | +| **名称** | **类型** | **必填** | **描述** | **长度** | +| detailIndex | String | 是 | 单据明细序号 | 5 | +| commodityCode | String | 否 | 商品编码 | 64 | +| goodsName | String | 是 | 商品名称 | 90 | +| goodsUnit | String | 否 | 单位 | 22 | +| specType | String | 否 | 规格型号 | 40 | +| withTaxFlag | int | 是 | 单价含税标志，0:不含税,1:含税 | 1 | +| goodsPrice | decimal | 否 | 含税单价 | decimal(32,16) | +| taxFreePrice | decimal | 否 | 不含税单价 | decimal(32,16) | +| goodsNum | decimal | 否 | 数量 | decimal(32,16) | +| taxFreeAmount | decimal | 否 | 不含税金额 | (15,2) | +| tax | decimal | 否 | 税额 | (15,2) | +| taxAmount | decimal | 否 | 含税金额 | (15,2) | +| taxrate | decimal | 是 | 税率 | (15,2) | +| goodsCode | String | 否 | 税收分类编码 | 19 | +| goodsCodeAbb | String | 否 是 | 税收分类编码简称 | 200 | +| selfCode | String | 否 | 自行编码 | 20 | +| favouredPolicyFlag | String | 是 | 优惠政策标识，0:不使用;1:使用 | 2 | +| favouredPolicyName | String | 否 | 优惠政策内容，如：即征即退、免税、不征税、简易征收等 | 50 | +| zeroRateFlag | String | 否 | 零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率 | 2 | +| deduction | decimal | 否 | 扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00 | (15,2) | + +### 请求示例 + + +++ + + + + + +

{

+

"invoiceLine": "s",

+

"billNo": "",

+

"billType": "0",

+

"oriInvoiceCode": "5000201530",

+

"oriInvoiceNumber": "67523624",

+

"oriInvoiceTime": "2020-11-12 00:00:00",

+

"sellerName": "移动测试盘326",

+

"sellerTaxnum": "150301199811285326",

+

"buyerName": "326专26",

+

"buyerTaxnum": "339901999999513",

+

"operator": "超级管理员",

+

"applyRemark": "0000000100",

+

"productOilFlag": 0,

+

"extensionNumber": "",

+

"terminalNumber": "",

+

"departmentId": "",

+

"userId": "",

+

"detailList": [

+

{

+

"deduction": 0.0,

+

"detailIndex": 1,

+

"favouredPolicyFlag": 1,

+

"favouredPolicyName": "即征即退",

+

"goodsCode": "商品编码",

+

"goodsCodeAbb": "商品编码简称",

+

"goodsName": "商品名称",

+

"goodsNum": -1,

+

"goodsPrice": 1,

+

"goodsUnit": "元",

+

"selfCode": "企业自行编码",

+

"specType": "规格型号",

+

"tax": -0.03,

+

"taxAmount": -1.03,

+

"taxFreeAmount": -1,

+

"taxFreePrice": 1,

+

"taxrate": "0.03",

+

"withTaxFlag": 0,

+

"zeroRateFlag": "1"

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 查询成功 | 详细信息 | 1024 | +| data | String | 否 | "661545615505210618135603" | 提交成功则返回billNo申请编号 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message":"成功",

+

"data": "661545615505210618135603"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code":"400",

+

"message":"参数校验失败"

+

}

+ +### 状态码说明 + +| | | +|:-----------|:-------------| +| **状态码** | **描述** | +| 200 | 查询成功 | +| 400 | 参数校验失败 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表申请接口_支持拆分.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表申请接口_支持拆分.md new file mode 100644 index 0000000..4fe0ff4 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字信息表申请接口_支持拆分.md @@ -0,0 +1,410 @@ +--- +title: 红字信息表申请接口（支持拆分） +aliases: + - 红字信息表申请接口（支持拆分） + - 诺税通红字信息表申请接口（支持拆分） + - 红字信息表-红字信息表申请接口（支持拆分） +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字信息表申请接口（支持拆分） + +> [!info] 导航 +> 上级索引：[[README]] · [[04_红字信息表]] +> 文档链接：[总索引](../README.md) · [分组页](../04_红字信息表.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[04_红字信息表]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/red-apply-submit-split` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字信息表申请接口（支持拆分） + +### 接口说明 + +专用发票红字信息表申请接口，支持机动车专票按退货方式（信息表类型为2时）申请红字信息表时自动拆分成8行一个信息表。 + +### 接口地址 + +| | +|:-----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/red-apply-submit-split | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
invoiceLineString是发票种类2
billNoString否24位申请单号（12位开票设备编号+12位蓝票开票时间YYMMDDHHMMSS）24
billTypeString否

信息表类型(0:正常 1:逾期(仅销方开具)，2:机动车专票-退货和开具错误，3:机动车专票-销售折让和合格证不退回)，4、矿产品类专用信息表（涉及销售数量和金额变更）

+

5、矿产品类专用信息表（仅涉及销售金额变更，不涉及数量变动）

+

默认为：0正常

+

注：信息表类型为2：退货时，信息表展示蓝票所有明细行，每次提交信息表开具时，不允许超过8行，且不转换成固定一行明细（详见正数发票及清单）

+

若根据蓝票代码号码匹配不到对应的蓝票机动车标识，billType需必填。

2
oriInvoiceCodeString否对应蓝票代码12
oriInvoiceNumberString否对应蓝票号码8
blueInvoiceTimeString否

蓝票填开时间（YYYYMM）

+

除了购方已抵扣，若没有对应的蓝票信息，blueInvoiceTime需必填，新局端要求上传对应蓝字发票开具时间（年月）

19
sellerNameString是销方名称100
sellerTaxnumString是销方税号20
buyerNameString是购方名称100
buyerTaxnumString是购方税号20
buyerAddressString否购方地址100
buyerPhoneString否购方电话50
buyerBankString否购方银行100
buyerAccountString否购方账号30
operatorString否经办人20
applyRemarkString是

申请说明

+

(购方已抵扣：1100000000 ，购方未抵扣：1010000000， 销售方申请：0000000100)

10
productOilFlagString否

成品油标识 0,非成品油;1,成品油

+

若没有对应的蓝票信息，productOilFlag必填

1
extensionNumberString否分机号11
terminalNumberString否终端号11
machineNumberString否机器编号12
deptIdString否部门门店id（本地系统中的id）20
userIdString否开票人id（本地系统中的id）20
bizCallbackUrlString否业务系统回调地址255
detailListList是商品明细无
specificFactorString否

特定要素：0普通发票（默认）01成品油 14机动车 31建安发票 32房地产销售发票 34电子烟发票、35矿产品发票

+

注：开具矿产品发票时必传，此时billType只能为4或5，成品油发票特定要素和成品油标识选一即可，均传以特定要素为准。

50
notifyPhoneString否交付手机号码20
notifyEmailString否交付邮箱地址50
ccPhoneString否抄送手机号，当推送手机notifyPhone有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个100
ccEmailString否抄送邮箱，当推送邮箱notifyEmail有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个250
+ +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **商品明细** detailList | | | | | +| **名称** | **类型** | **必填** | **描述** | **长度** | +| detailIndex | String | 是 | 单据明细序号 | 5 | +| commodityCode | String | 否 | 商品编码 | 64 | +| goodsName | String | 是 | 商品名称 | 90 | +| goodsUnit | String | 否 | 单位 | 22 | +| specType | String | 否 | 规格型号 | 40 | +| withTaxFlag | int | 是 | 单价含税标志，0:不含税,1:含税 | 1 | +| goodsPrice | decimal | 否 | 含税单价 | decimal(32,16) | +| taxFreePrice | decimal | 否 | 不含税单价 | decimal(32,16) | +| goodsNum | decimal | 否 | 数量 | decimal(32,16) | +| taxFreeAmount | decimal | 否 | 不含税金额 | (15,2) | +| tax | decimal | 否 | 税额 | (15,2) | +| taxAmount | decimal | 否 | 含税金额 | (15,2) | +| taxrate | decimal | 是 | 税率 | (15,2) | +| goodsCode | String | 否 | 税收分类编码 | 19 | +| goodsCodeAbb | String | 否 是 | 税收分类编码简称 | 200 | +| selfCode | String | 否 | 自行编码 | 20 | +| favouredPolicyFlag | String | 是 | 优惠政策标识，0:不使用;1:使用 | 2 | +| favouredPolicyName | String | 否 | 优惠政策内容，如：即征即退、免税、不征税、简易征收等 | 50 | +| zeroRateFlag | String | 否 | 零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率 | 2 | +| deduction | decimal | 否 | 扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00 | (15,2) | + +### 请求示例 + + +++ + + + + + +

{

+

"invoiceLine": "s",

+

"billNo": "",

+

"billType": "0",

+

"oriInvoiceCode": "5000201530",

+

"oriInvoiceNumber": "67523624",

+

"oriInvoiceTime": "2020-11-12 00:00:00",

+

"sellerName": "移动测试盘326",

+

"sellerTaxnum": "150301199811285326",

+

"buyerName": "326专26",

+

"buyerTaxnum": "339901999999513",

+

"operator": "超级管理员",

+

"applyRemark": "0000000100",

+

"productOilFlag": 0,

+

"extensionNumber": "",

+

"terminalNumber": "",

+

"departmentId": "",

+

"userId": "",

+

"detailList": [

+

{

+

"deduction": 0.0,

+

"detailIndex": 1,

+

"favouredPolicyFlag": 1,

+

"favouredPolicyName": "即征即退",

+

"goodsCode": "商品编码",

+

"goodsCodeAbb": "商品编码简称",

+

"goodsName": "商品名称",

+

"goodsNum": -1,

+

"goodsPrice": 1.03,

+

"goodsUnit": "元",

+

"selfCode": "企业自行编码",

+

"specType": "规格型号",

+

"tax": -0.03,

+

"taxAmount": -1.03,

+

"taxFreeAmount": -1,

+

"taxFreePrice": 1,

+

"taxrate": "0.03",

+

"withTaxFlag": 0,

+

"zeroRateFlag": "1"

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 查询成功 | 详细信息 | 1024 | +| data | String | 否 | "661545615505210618135603,661545615505210618135604" | 提交成功则返回billNo申请编号，多个以英文逗号分隔 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message":"成功",

+

"data": "661545615505210618135603,661545615505210618135604"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code":"400",

+

"message":"参数校验失败"

+

}

+ +### 状态码说明 + +| | | +|:-----------|:-------------| +| **状态码** | **描述** | +| 200 | 查询成功 | +| 400 | 参数校验失败 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单下载接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单下载接口.md new file mode 100644 index 0000000..dc5d097 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单下载接口.md @@ -0,0 +1,186 @@ +--- +title: 红字确认单下载接口 +aliases: + - 红字确认单下载接口 + - 诺税通红字确认单下载接口 + - 红字确认单-红字确认单下载接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字确认单下载接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[05_红字确认单]] +> 文档链接：[总索引](../README.md) · [分组页](../05_红字确认单.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[05_红字确认单]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/redConfirm/download.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字确认单下载接口 + +### 接口说明 + +数电发票红字确认单下载接口。 + +### 接口地址 + +| | +|:-----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/redConfirm/download.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
taxNumString是税号20
identityInteger是

购销身份：

+

0：我是销售方

+

1：我是购买方

2
billUuidString否红字确认单uuid32
billStatusString否

购销身份为1：我是购买方时，必填

+

确认单状态，0.待确认 1.已确认 2.已过期 3.销方否认 4.已撤销

4
startTimeString否填开起始时间（确认单billuuid有值时，可为空，允许最大查询范围为90天 yyyy-MM-dd）-
endTimeString否填开结束时间(确认单编号有值时，可为空，允许最大查询范围为90天 yyyy-MM-dd)-
extensionNumInteger否分机号-
departmentIdLong否部门门店id（诺税通中的部门id）20
userIdLong否开票人id（诺税通中的用户id）20
+ +注意： + +1、有红字确认单uuid时，走精确查询；（查询的税号需要符合红字确认单中的销方或购方） + +2、无红字确认单uuid时，必须传购销身份及确认单填开的起始结束时间 + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"identity": 0,

+

"billUuid": "1fdsafda350301132998",

+

"startTime": "2020-11-12",

+

"endTime": "2020-11-14",

+

"extensionNum": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单撤销接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单撤销接口.md new file mode 100644 index 0000000..ec91185 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单撤销接口.md @@ -0,0 +1,185 @@ +--- +title: 红字确认单撤销接口 +aliases: + - 红字确认单撤销接口 + - 诺税通红字确认单撤销接口 + - 红字确认单-红字确认单撤销接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字确认单撤销接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[05_红字确认单]] +> 文档链接：[总索引](../README.md) · [分组页](../05_红字确认单.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[05_红字确认单]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/redConfirm/cancel.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字确认单撤销接口 + +### 接口说明 + +数电发票红字确认单撤销接口。 + +### 接口地址 + +| | +|:---------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/redConfirm/cancel.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
taxNumString否税号（和组织编码任一必填）20
companyCodeString否组织编码-
identityInteger是

撤销方身份：

+

0：销方

+

1：购方

2
billUuidString否红字确认单uuid32
billIdString否红字确认单申请单号32
billNoString否红字确认单编号32
extensionNumInteger否分机号-
departmentIdLong否部门门店id（诺税通中的部门id）20
userIdLong否开票人id（诺税通中的用户id）20
+ +注： + +3. 有红字确认单申请号、红字确认单编号、红字确认单uuid任一必传 + +4. 税号和企业编码任一必填，可通过企业编码转换为税号 + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"companyCode": "1234324231",

+

"identity": 0,

+

"billUuid": "1fdsafda350301132998",

+

"extensionNum": 1，

+

"userId": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单查询接口.md new file mode 100644 index 0000000..d82a828 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单查询接口.md @@ -0,0 +1,501 @@ +--- +title: 红字确认单查询接口 +aliases: + - 红字确认单查询接口 + - 诺税通红字确认单查询接口 + - 红字确认单-红字确认单查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字确认单查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[05_红字确认单]] +> 文档链接：[总索引](../README.md) · [分组页](../05_红字确认单.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[05_红字确认单]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/redConfirm/query.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字确认单查询接口 + +### 接口说明 + +数电发票红字确认单查询接口。 + +### 接口地址 + +| | +|:--------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/redConfirm/query.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
taxNumString是税号20
applySourceInteger是

申请方身份：

+

0 销方

+

1 购方

2
billStatusString否

红字确认单状态：

+

01 无需确认

+

02 销方录入待购方确认

+

03 购方录入待销方确认

+

04 购销双方已确认

+

05 作废（销方录入购方否认）

+

06 作废（购方录入销方否认）

+

07 作废（超72小时未确认）

+

08 作废（发起方撤销）

+

09 作废（确认方撤销）

4
billIdString否红字确认单申请单号32
billNoString否红字确认单编号32
billUuidString否红字确认单uuid32
startTimeString否填开起始时间（确认单申请号/编号/uuid有值时，可为空，允许最大查询范围为90天 yyyy-MM-dd）-
endTimeString否填开结束时间(确认单申请号/编号/uuid有值时，可为空，允许最大查询范围为90天 yyyy-MM-dd)-
+ +注： + +1、有红字确认单申请号、红字确认单编号、红字确认单uuid时（一个或多个时），走精确查询；（查询的税号需要符合红字确认单中的销方或购方） + +2、无红字确认单申请号、红字确认单编号、红字确认单uuid时，必须传申请方身份及确认单填开的起始结束时间 + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"applySource": 1,

+

"billStatus": "01",

+

"billId": "342234232432432423",

+

"billNo": "32432f342df324sewerwe",

+

"billUuid": "3423423dgv324234dfg43r34g43",

+

"startTime": "2022-06-22",

+

"endTime": "2022-06-23"

+

}

+ +### 返回参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
codeInteger是状态,200-成功，非200-失败6
messageString是详细信息1024
dataList查询成功则返回红字确认单信息
发票信息
billIdString是申请单号32
billNoString否确认单编号32
billUuidString否确认单uuid32
billStatusString是

确认单状态

+

-1 提交失败

+

00 提交中

+

01 无需确认

+

02 销方录入待购方确认

+

03 购方录入待销方确认

+

04 购销双方已确认

+

05 作废（销方录入购方否认）

+

06 作废（购方录入销方否认）

+

07 作废（超72小时未确认）

+

08 作废（发起方撤销）

+

09 作废（确认方撤销）

+

15 提交税局中

+

16 提交税局失败

4
billMessageString否[确认单状态代码]确认单状态描述300
openStatusString否

开具状态

+

0：未开具

+

1：已开具

2
applySourceString是

申请来源

+

0 销方

+

1 购方

2
billTimeString否

填开时间

+

yyyy-MM-dd HH:mm:ss

19
taxFreeAmountTotaldecimal否不含税金额15.2
taxTotaldecimal否合计税额15.2
taxAmountTotaldecimal否含税金额15.2
blueInvoiceNumberString否对应蓝票数电号码20
blueInvoiceNoString否蓝字增值税发票号码(如果蓝票为增值税发票，则增值税代号码必填)8
blueInvoiceCodeString否蓝字增值税发票代码(如果蓝票为增值税发票，则增值税代号码必填)12
blueInvoiceLineString否

蓝票票种

+

bs:数电专票(电子),pc:数电普票(电子)，es:数电专票(纸质)；ec:数电普票(纸质)

+

p:电子增值税普通发票，

+

c:增值税普通发票(纸票)，

+

s:增值税专用发票，

+

b:增值税电子专用发票

5
sellerNameString否销方名称100
sellerTaxnumString否销方税号20
buyerNameString否购方名称100
buyerTaxnumString否购方税号20
vatUsageString否蓝字发票增值税用途2
saleTaxUsageString否蓝字发票消费税用途2
accountStatusString否发票入账状态2
redReasonString是

冲红原因

+

1开票有误

+

2销货退回

+

3服务中止

+

4销售折让

2
detailList否确认单明细
+ +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **确认单明细** detail | | | | | +| **名称** | **类型** | **必填** | **描述** | **长度** | +| detailIndex | Integer | 是 | 单据明细序号 | 5 | +| blueDetailIndex | Integer | 是 | 对应数电蓝票明细行 | 6 | +| goodsName | String | 是 | 商品名称 | 90 | +| goodsUnit | String | 否 | 单位 | 22 | +| specType | String | 否 | 规格型号 | 40 | +| withTaxFlag | int | 是 | 单价含税标志，0:不含税,1:含税 | 1 | +| goodsPrice | decimal | 否 | 含税单价 | decimal(32,16) | +| taxFreePrice | decimal | 否 | 不含税单价 | decimal(32,16) | +| goodsNum | decimal | 否 | 数量 | decimal(32,16) | +| taxFreeAmount | decimal | 否 | 不含税金额 | (15,2) | +| tax | decimal | 否 | 税额 | (15,2) | +| taxAmount | decimal | 否 | 含税金额 | (15,2) | +| taxrate | String | 是 | 税率 | 10 | +| goodsCode | String | 否 | 税收分类编码 | 19 | +| goodsCodeAbb | String | 否 是 | 税收分类编码简称 | 200 | +| selfCode | String | 否 | 自行编码 | 20 | +| favouredPolicyFlag | String | 是 | 优惠政策标识 | 10 | +| favouredPolicyName | String | 否 | 优惠政策内容，如：即征即退、免税、不征税、简易征收等 | 50 | +| zeroRateFlag | String | 否 | 零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率 | 2 | +| deduction | decimal | 否 | 扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00 | (15,2) | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [

+

{

+

"billId": "12345678901234567890097q",

+

"billNo": "12345678901234567890097q",

+

"billUuid": "sdfcvs3g3554y5y4y54y55445t54",

+

"billStatus": "01",

+

"billMessage": "[B900006]申请单号不能为空或者格式不正确",

+

"openStatus": 1,

+

"applySource": 1,

+

"billTime": "2020-05-26 03:14:15",

+

"taxFreeAmountTotal": "-1.00",

+

"taxTotal": "-1.00",

+

"taxAmountTotal": "-1.00",

+

"blueInvoiceNumber": "45625450",

+

"blueInvoiceTime": null,

+

"blueInvoiceLine": "bs",

+

"sellerName": "Excepteur dolor ",

+

"sellerTaxnum": "150301199811285326",

+

"buyerName": "officia in irure",

+

"buyerTaxnum": "150301199811285326",

+

"vatUsage": "2",

+

"saleTaxUsage": "1",

+

"accountStatus": "1",

+

"redReason": "1",

+

"detailList": [

+

{

+

"billId": "12345678901234567890097q",

+

"detailIndex": 1,

+

"blueDetailIndex": 2,

+

"goodsName": "Ut min",

+

"withTaxFlag": 0,

+

"goodsPrice": "0.0000000000000000",

+

"taxFreePrice": "0.0900000000000000",

+

"goodsNum": "-1.0000000000000000",

+

"taxrate": "0.09",

+

"specType": "nost",

+

"goodsUnit": "aliqu",

+

"goodsCode": "esseonsequ",

+

"goodsCodeAbb": "irure in",

+

"favouredPolicyFlag": 0,

+

"zeroRateFlag": "",

+

"favouredPolicyName": "",

+

"selfCode": "sed Lorem",

+

"deduction": "0.00",

+

"taxAmount": "-0.01",

+

"taxFreeAmount": "-0.09",

+

"tax": "-0.01"

+

}

+

]

+

}

+

]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单申请接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单申请接口.md new file mode 100644 index 0000000..34ca3f8 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单申请接口.md @@ -0,0 +1,526 @@ +--- +title: 红字确认单申请接口 +aliases: + - 红字确认单申请接口 + - 诺税通红字确认单申请接口 + - 红字确认单-红字确认单申请接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字确认单申请接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[05_红字确认单]] +> 文档链接：[总索引](../README.md) · [分组页](../05_红字确认单.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[05_红字确认单]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/redConfirm/apply.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字确认单申请接口 + +### 接口说明 + +数电发票红字确认单申请接口。 + +注：对数电蓝票进行部分冲红确认单申请时，明细中蓝票序号对应冲红蓝票的明细序号，在开具蓝票时，需保证蓝票的序号为从1开始的连续数字。 + +开具蓝票为增值税发票(只支持专票、普票)的红字确认单，暂只支持乐企开票模式。 + +### 接口地址 + +| | +|:--------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/redConfirm/apply.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
billIdString否红字确认单申请单号（需要保持唯一，不传的话系统自动生成一个）32
applySourceInteger是

申请方身份：

+

0 销方

+

1 购方

2
taxNumString否税号(税号、组织编码其一必填)20
companyCodeString否组织编码(税号、组织编码其一必填)20
billTimeString否

填开时间

+

默认当前时间

+

yyyy-MM-dd HH:mm:ss

-
blueInvoiceNumberString否对应蓝票数电号码（数电普票、数电专票都需要，蓝票为数电票必填）20
blueInvoiceNoString否蓝字增值税发票号码(如果蓝票为增值税发票，则增值税代号码必填)8
blueInvoiceCodeString否蓝字增值税发票代码(如果蓝票为增值税发票，则增值税代号码必填)12
blueInvoiceLineString否

蓝票未在系统时，需要必填

+

蓝票数电发票种类:

+

bs:数电专票(电子),

+

pc:数电普票(电子)，

+

es:数电专票(纸质)；

+

ec:数电普票(纸质)，

+

p:电子增值税普通发票，

+

c:增值税普通发票(纸票)，

+

s:增值税专用发票，

+

b:增值税电子专用发票

5
sellerNameString否销方名称100
sellerTaxnumString否销方税号20
buyerNameString否购方名称100
buyerTaxnumString否购方税号20
vatUsageString否蓝字发票增值税用途（预留字段可为空）2
saleTaxUsageString否蓝字发票消费税用途（预留字段可为空）2
accountStatusString否发票入账状态（预留字段可为空）2
redReasonString是

冲红原因：

+

1销货退回

+

2开票有误

+

3服务中止

+

4销售折让

2
bizCallbackUrlString否业务系统回调地址255
extensionNumInteger否分机号11
departmentIdLong否部门门店id（诺税通中的部门id）20
userIdLong否开票人id（诺税通中的用户id）20
notifyPhoneString否交付手机号码20
notifyEmailString否交付邮箱地址50
ccPhoneString否抄送手机号，当推送手机notifyPhone有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个100
ccEmailString否抄送邮箱，当推送邮箱notifyEmail有值时，才允许填写，多个中间用英文逗号隔开，最多可填写5个250
+ + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
确认单明细 details
名称类型必填描述长度
blueDetailIndexInteger是对应数电蓝票的明细序号5
goodsNameString是商品名称90
goodsUnitString否单位22
specTypeString否规格型号40
withTaxFlagint是单价含税标志，0:不含税,1:含税1
goodsPricedecimal否含税单价decimal(32,16)
taxFreePricedecimal否不含税单价decimal(32,16)
goodsNumdecimal否数量（传负数）decimal(32,16)
taxFreeAmountdecimal是不含税金额（传负数）(15,2)
taxdecimal是税额（传负数）(15,2)
taxAmountdecimal是含税金额（传负数）(15,2)
taxrateString是税率10
goodsCodeString否税收分类编码19
goodsCodeAbbString否税收分类编码简称200
selfCodeString否自行编码20
favouredPolicyFlagString否

优惠政策标识

+

01：简易征收 02：稀土产品 03：免税 04：不征税 05：先征后退 06：100%先征后退 07：50%先征后退 08：按3%简易征收 09：按5%简易征收 10：按5%简易征收减按1.5%计征 11：即征即退30% 12：即征即退50% 13：即征即退70% 14：即征即退100% 15：超税负3%即征即退 16：超税负8%即征即退 17：超税负12%即征即退 18：超税负6%即征即退

10
favouredPolicyNameString否优惠政策内容，如：即征即退、免税、不征税、简易征收等50
zeroRateFlagString否零税率标识，空:非零税率;1:免税;2:不征税;3:普通零税率2
deductiondecimal否扣除额：传空或字段不传，都表示非差额征税；传0.00才表示差额征税:0.00(15,2)
+ +注： + +1\. 确认单明细不填时，进行全额冲红申请，填写明细信息，为部分冲红申请。 + +### 请求示例 + + +++ + + + + + +

{

+

"billId": "661545615505210618135603",

+

"applySource": 1,

+

"billTime": "2020-11-12 00:00:00",

+

"blueInvoiceNumber": "5000201530",

+

"blueInvoiceLine": "bs",

+

"sellerName": "移动测试盘326",

+

"sellerTaxnum": "150301199811285326",

+

"buyerName": "326专26",

+

"buyerTaxnum": "339901999999513",

+

"vatUsage": "1",

+

"saleTaxUsage": "2",

+

"accountStatus": "1",

+

"redReason": "1",

+

"extensionNum": "0",

+

"departmentId": 123,

+

"userId": 1,

+

"details": [

+

{

+

"blueDetailIndex": 2,

+

"favouredPolicyName": "",

+

"goodsCode": "1070304080000000000",

+

"goodsCodeAbb": "中成药",

+

"goodsName": "胶囊",

+

"goodsNum": -1,

+

"goodsPrice": 13.56,

+

"goodsUnit": "盒",

+

"specType": "中成药胶囊1",

+

"tax": -1.56,

+

"taxAmount": -13.56,

+

"taxFreeAmount": -12.00,

+

"taxFreePrice": 12,

+

"taxrate": "0.13",

+

"withTaxFlag": 1,

+

"zeroRateFlag": ""

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 查询成功 | 详细信息 | 1024 | +| data | String | 否 | "661545615505210618135603" | 提交成功则返回billId申请编号 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message":"成功",

+

"data": "661545615505210618135603"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code":"400",

+

"message":"参数校验失败"

+

}

+ +### 状态码说明 + +| | | +|:-----------|:-------------| +| **状态码** | **描述** | +| 200 | 查询成功 | +| 400 | 参数校验失败 | diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单确认接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单确认接口.md new file mode 100644 index 0000000..b40bd94 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/红字确认单确认接口.md @@ -0,0 +1,201 @@ +--- +title: 红字确认单确认接口 +aliases: + - 红字确认单确认接口 + - 诺税通红字确认单确认接口 + - 红字确认单-红字确认单确认接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 红字确认单确认接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[05_红字确认单]] +> 文档链接：[总索引](../README.md) · [分组页](../05_红字确认单.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[05_红字确认单]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/redConfirm/confirm.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 红字确认单确认接口 + +### 接口说明 + +数电发票红字确认单确认接口。 + +### 接口地址 + +| | +|:----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/redConfirm/confirm.do | + +### 请求参数 + + +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
名称类型必填描述长度
taxNumString否税号（和组织编码任一必填）20
companyCodeString否组织编码-
identityInteger是

确认方身份：

+

0：销方

+

1：购方

2
billUuidString否红字确认单uuid32
billIdString否红字确认单申请单号32
billNoString否红字确认单编号32
confirmAgreementInteger是处理意见 0拒绝 1同意2
confirmReasonString否处理理由200
extensionNumInteger否分机号-
departmentIdLong否部门门店id（诺税通中的部门id）20
userIdLong否开票人id（诺税通中的用户id）20
+ +注： + +1. 有红字确认单申请号、红字确认单编号、红字确认单uuid任一必传 + +2. 税号和企业编码任一必填，可通过企业编码转换为税号 + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326",

+

"companyCode": "1234324231",

+

"identity": 0,

+

"billUuid": "1fdsafda350301132998",

+

"confirmAgreement": 0,

+

"confirmReason": "通过",

+

"extensionNum": 1，

+

"userId": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--------:|:--------:|:--------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/自定义票源下载接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/自定义票源下载接口.md new file mode 100644 index 0000000..a3f4760 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/自定义票源下载接口.md @@ -0,0 +1,132 @@ +--- +title: 自定义票源下载接口 +aliases: + - 自定义票源下载接口 + - 诺税通自定义票源下载接口 + - 库存票源与打印-自定义票源下载接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 自定义票源下载接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/stock/downloadStockCustomize.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 自定义票源下载接口 + +### 接口说明 + +仅支持开票服务器类型为诺诺机柜、诺诺开票。下载成功之后客户端会重新上报可下载库存，之后可以调用查询接口刷新列表数据。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/stock/downloadStockCustomize.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| extensionNum | Integer | 是 | 分机号，纯数字 | \- | +| machineNumber | String | 是 | 机器编号，12位数字 | 12 | +| downloadableStockList | List | 是 | 可下载票源数量信息列表 | | +| 可下载票源数量信息列表 | | | | | +| invoiceCode | String | 是 | 要下载号段的发票代码 | | +| invoiceLine | String | 是 | 发票种类 | | +| invoiceNumStart | String | 是 | 要下载号段的起始发票号码 | | +| downloadNum | Integer | 是 | 想要下载的份数，**需要小于等于可下载数量** | | + +### 请求示例 + + +++ + + + + + +

{

+

"extensionNum":0,

+

"machineNumber":"661565671900",

+

"sellerTaxnum":"150301199811285326",

+

"downloadableStockList":[

+

{

+

"invoiceCode":"5000201530",

+

"invoiceLine":"p",

+

"invoiceNumStart":"93669589",

+

"downloadNum":10

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | Object | | | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": null

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": 900,

+

"message": "下载份数要小于等于发票份数",

+

"data": null

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取DAT加密包文件流接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取DAT加密包文件流接口.md new file mode 100644 index 0000000..4a765e9 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取DAT加密包文件流接口.md @@ -0,0 +1,106 @@ +--- +title: 获取DAT加密包文件流接口 +aliases: + - 获取DAT加密包文件流接口 + - 诺税通获取DAT加密包文件流接口 + - 车辆辅助与回传-获取DAT加密包文件流接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取DAT加密包文件流接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[08_车辆辅助与回传]] +> 文档链接：[总索引](../README.md) · [分组页](../08_车辆辅助与回传.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[08_车辆辅助与回传]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/getEncryptedStream.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取DAT加密包文件流接口 + +### 接口说明 + +获取加密包文件流接口，最多支持获取500张发票的加密包。 + +### 接口地址 + +| | +|:----------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/getEncryptedStream.do | + +### 请求参数(用json格式接收) + +| | | | | | | +|:---------------------:|:--------:|:--------:|:--------:|:---:|:--------:| +| **名称** | **类型** | **必填** | **描述** | | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | | 20 | +| **发票代码+发票号码** | | | | | | +| invoiceCode | String | 是 | 发票代码 | 12 | | +| invoiceNumber | String | 是 | 发票号码 | 8 | | + +### 请求示例 + + +++ + + + + + +

{

+

"invoiceAssociations": [

+

{

+

"invoiceCode": "1500020560",

+

"invoiceNumber": "87609473"

+

}

+

],

+

"sellerTaxnum": "150301199811285326"

+

}

+ +### 返回参数 + +| | | | | | +|:--------:|:--------:|:--------:|:-------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | String | | 返回base64加密的文件内容 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": "dkSMheZ+2xkuW55b5HY5yzBIyrmKhRyhc9gnXHG5UOLUQnJoGCZkCg6h8hSgBAuneXD3z9uuT3rFd5VJBUripEa2IUWj5NYYvwkoku8ZSYL8xp4WGVx/Mkvprat8olT4WgDlIhJ1H8w1SVQ7oyoi8AcMBFTxDQ40eWBssK7tDaV5ND250xBe+qi1mso17pAkGvUzo2Kxz2VsWDd258sGYl3/7iEqyR5+eE4HwTc8h0+tuhPJtSw/WvyEEAcTHJFUZDW3mKqtXYHvWtRI9qqx2DU9bt+M2BveaWdLDqB6oXdluQJojWW7YjDT/MVVVnONVZnQXv5mtGKZNFG1snj/zTZdT4ucEKa7e0GSujP2HT6HNQcXLGfnB4QoLpTVpgNrDjrZJZSuTBTO/V7J2aEVVNzYODfKMIcDBp3mpVhD2HUUNl/bqnLemOkjkVJ6cCaa4lUOBz9nSD8TfNAagkrzph12M/ltmcRZrXTOdlaDwUF+GD15Vjv4MtKLHxnlYFK71CsDCT/F0lR8fo7NNiQJb7qnuadsRyAraK1lcneByLwJldkKpcYjOeO+4D/Sx0G/7WTw5mJTP08nXPUpwiP96PVI+jHmiQlK6IglFzZTrC6X5dMtWnxr1zdsF//I7rugfumlU1uS+IGLEpv/zTR9mxkZ1sOVzgjz+V8P3POrXU0Oi6O7n019qZd4a6hx2dGjau8STDevRNNm2Qz93HROjsdTWTC+5GYuCLbp+TVNJEx36BnIOgAR6+tj+jtCw4+cW7u7ILY1AkYA/anshTeTnUlCdglZuVsyFDTz+riy6wVwkcpqR0tN7t9rZPNLd3B/xeHxYsf50Th/kcVjo5qaSw=="

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取下一张发票号码代码接口_A9机柜.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取下一张发票号码代码接口_A9机柜.md new file mode 100644 index 0000000..b4a176f --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取下一张发票号码代码接口_A9机柜.md @@ -0,0 +1,119 @@ +--- +title: 获取下一张发票号码代码接口（A9+机柜） +aliases: + - 获取下一张发票号码代码接口（A9+机柜） + - 诺税通获取下一张发票号码代码接口（A9+机柜） + - 库存票源与打印-获取下一张发票号码代码接口（A9+机柜） +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取下一张发票号码代码接口（A9+机柜） + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/getNextInvoice.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取下一张发票号码代码接口（A9+机柜） + +### 接口说明 + +获取下一张发票号码代码，全本地（A9+机柜），半本地（机柜） + +### 接口地址 + +| | +|:------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/getNextInvoice.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | 20 | +| extensionNum | String | 是 | 分机号 | 5 | +| machineNum | String | 是 | 税控设备号（机器编码） | 12 | +| terminalNum | String | 否 | 终端号 | 10 | +| invoiceLine | String | 必填，发票种类对应枚举值，例:p:普通发票(电子) | 发票种类，c:增值税普通发票(纸票)，s:增值税专用发票，f:收购发票(纸质)，j：机动车发票，u：二手车发票 | 1 | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"extensionNum":" 1",

+

"machineNum":" 661929539468",

+

"invoiceLine": "c"

+

}

+ +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | | 查询成功 | | +| 信息 | | | | | +| invoiceLine | String | 必填，发票种类对应枚举值 | 发票种类，c:增值税普通发票(纸票)，s:增值税专用发票，f:收购发票(纸质)，j：机动车发票，u：二手车发票 | 1 | +| nextInvoiceCode | String | 是 | 下一张发票代码 | 12 | +| nextInvoiceNum | String | 是 | 下一张发票号码 | 8 | +| remainNum | Integer | 否 | 剩余发票份数 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": [{

+

"invoiceLine": "c",

+

"nextInvoiceCode": "150010020011",

+

"nextInvoiceNum": "23499027",

+

"remainNum": 487

+

},{

+

"invoiceLine": "c",

+

"nextInvoiceCode": "150010020011",

+

"nextInvoiceNum": "23499028",

+

"remainNum": 486

+

}]

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取关联发票接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取关联发票接口.md new file mode 100644 index 0000000..7fa0e32 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取关联发票接口.md @@ -0,0 +1,147 @@ +--- +title: 获取关联发票接口 +aliases: + - 获取关联发票接口 + - 诺税通获取关联发票接口 + - 作废重开与冲红-获取关联发票接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取关联发票接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[03_作废重开与冲红]] +> 文档链接：[总索引](../README.md) · [分组页](../03_作废重开与冲红.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[03_作废重开与冲红]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/queryInvoiceAsscciationList.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取关联发票接口 + +### 接口说明 + +获取关联发票接口。 + +### 接口地址 + +| | +|:---| +| http\[s\]://\\[:\\]/salescore/lan/queryInvoiceAsscciationList.do | + +### 请求参数(用json格式接收) + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | 20 | +| dateType | Integer | 是 | 时间类型（0：创建时间，1：开票时间） | 1 | +| startDate | String | 是 | 开始时间，最大跨度不得超过180天，格式为yyyy-MM-dd HH:mm:ss | 20 | +| endDate | String | 是 | 结束时间，最大跨度不得超过180天，格式为yyyy-MM-dd HH:mm:ss | 20 | +| certificateOwnership | String | 选填 | 合格证归属，可多个，多个用英文逗号隔开 | 50 | +| uploadStatus | String | 选填 | 工信部上传状态，可多个，多个用英文逗号隔开 | 50 | +| buyerName | String | 选填 | 购方名称 | 100 | +| invoiceLines | String\[\] | 选填 | 发票种类列表—p电子增值税普通发票，c增值税普通发票(纸票)，s增值税专用发票，e收购发票(电子)，f收购发票(纸质)，u：二手车发票 | \- | +| productNatures | Integer\[\] | 选填 | 发票性质列表—0：普通发票；1：成品油发票；2：机动车类专用发票；默认：0：普通发票 | \- | +| pageNum | Integer | 选填 | 页码，默认是1，每页条数为20条 | | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"dateType": 0,

+

"startDate": "2021-09-20 10:00:00",

+

"endDate": "2021-09-21 10:00:00",

+

"certificateOwnership": "三厂",

+

"uploadStatus": "上传成功",

+

"buyerName": "浙江师范大学",

+

"invoiceLines": [

+

"p"

+

],

+

"productNatures": [

+

0

+

],

+

pageNum:1

+

}

+ +### 返回参数 + +| | | | | | +|:----------------:|:----------:|:--------:|:--------------------------:|:--------:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | | 查询成功则返回发票关联信息 | | +| **数据信息** | | | | | +| pageNum | Integer | 是 | 当前页数 | | +| pageSize | Integer | 是 | 每页条数，为固定值20 | | +| pages | Integer | 是 | 总页数 | | +| total | Integer | 是 | 数据总数 | | +| list | List | | 查询成功则返回发票关联信息 | | +| **发票关联信息** | | | | | +| buyerName | String | 是 | 购方名称 | 100 | +| buyerTaxnum | String | 是 | 购方税号 | 20 | +| invoiceCode | String | 是 | 发票代码 | 12 | +| invoiceNumber | String | 是 | 发票号码 | 8 | +| specTypes | String\[\] | 是 | 规格型号列表 | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"data": {

+

"pageNum": 1,

+

"pageSize": 20,

+

"pages": 1,

+

"total": 1,

+

"list": [

+

{

+

"buyerName": "浙江师范大学",

+

"buyerTaxnum": "339901999999142",

+

"invoiceCode": "1500020560",

+

"invoiceNumber": "87609471",

+

"specTypes": [

+

"得力0231"

+

]

+

}

+

]

+

},

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取发票勾选入账状态接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取发票勾选入账状态接口.md new file mode 100644 index 0000000..923729b --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取发票勾选入账状态接口.md @@ -0,0 +1,164 @@ +--- +title: 获取发票勾选入账状态接口 +aliases: + - 获取发票勾选入账状态接口 + - 诺税通获取发票勾选入账状态接口 + - 专项能力-获取发票勾选入账状态接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取发票勾选入账状态接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[09_专项能力]] +> 文档链接：[总索引](../README.md) · [分组页](../09_专项能力.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[09_专项能力]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/redConfirm/queryFpgxStatus.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取发票勾选入账状态接口 + +### 接口说明 + +销方通过接口查询到蓝票的勾选入账状态,接口异步 + +核心逻辑： 先进行operateType=1进行数据从数据初始化查询，间隔一会儿之后再进行operateType=0进行查询数据的获取 + +限制条件： + +1. operateType=1请求30s一次 + +2. 税号+数电账号，每天最多20次 + +### 接口地址 + +| | +|----| +| http\[s\]://\\[:\\]/salescore/lan/redConfirm/queryFpgxStatus.do | + +### 请求参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **说明** | **描述** | **长度** | +| saleTaxNum | String | 是 | 销方税号 | 销售发票的纳税人识别号或统一社会信用代码 | 15-20 | +| elecInvoiceNumber | String | 否 | 蓝字数电票号码 | 数电号码、蓝票号码代码必须选择其一 | 20 | +| invoiceCode | Stirng | 否 | 蓝票发票代码 | | | +| invoiceNumber | String | 否 | 蓝票发票号码 | | | +| operateType | Integer | 是 | 操作类型 | 操作类型，0-查询，1-税局获取 | 1 | +| extensionNum | String | 否 | 分机号 | | | + +### 请求示例 + + +++ + + + + + +

{

+

    "saleTaxNum":"339901999999008",

+

    "elecInvoiceNumber":"23312000000000540819",

+

    "invoiceCode":"",

+

    "invoiceNumber":"",

+

    "extensionNum":"1",

+

    "operateType":0

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | 是 | | 查询对象 | | +| **数据信息** | | | | | | +| invoiceCode | String | 否 | 033001600111 | 发票代码 | | +| invoiceNumber | String | 否 | 45738316 | 发票号码 | | +| elecInvoiceNumber | String | 否 | 23312000000000540819 | 数电号码 | 20 | +| sellerTaxnum | String | 是 | 339902999999789109 | 销方税号 | | +| sellerName | String | 是 | 航信培训企业789109 | 销方名称 | | +| buyerTaxnum | String | 是 | 915110247729829567 | 购方税号 | | +| buyerName | String | 是 | 威远县和平洗煤设备 | 购方名称 | | +| invoiceTime | String | 是 | 2023-06-08 13:00:22 | 开票时间 | | +| taxFreeAmountTotal | String | 是 | 0.92 | 合计不含税金额 | | +| taxAmountTotal | String | 是 | 1.00 | 价税合计 | | +| taxTotal | String | 是 | 0.08 | 合计税额 | | +| vatUsageCode | String | 是 | 01 | 增值税用途代码 ：00 已勾选未确认, 01已确认, 03未勾选 | 2 | +| saleTaxUsageCode | String | 是 | 00 | 消费税用途代码 :00 未勾选,非00 已勾选 | 2 | +| accountStatus | String | 是 | 00 | 发票入账状态代码 :00 未入账，01:已入账 | | + +### 返回示例 + +失败示例 + + +++ + + + + + +

{

+

    "code": 900,

+

    "message": "该功能暂停使用或访问，请稍后再试！",

+

    "data": null

+

}

+ +成功示例 + + +++ + + + + + +

{

+

    "code": 200,

+

    "message": "成功",

+

    "data": {

+

        "invoiceCode": "",

+

        "invoiceNumber": "20882305231323060035",

+

        "elecInvoiceNumber": "20882305231323060035",

+

        "sellerTaxnum": "339902999999789109",

+

        "sellerName": "航信培训企业789109",

+

        "buyerTaxnum": "915110247729829567",

+

        "buyerName": "威远县和平洗煤设备",

+

        "invoiceTime": "2023-06-08 13:00:22",

+

        "taxFreeAmountTotal": "0.92",

+

        "taxAmountTotal": "1.00",

+

        "taxTotal": "0.08",

+

        "vatUsageCode": "00",

+

        "saleTaxUsageCode": "00",

+

        "accountStatus": "01"

+

    }

+

}

+ +# 附录 diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取指定票种当前代码号码.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取指定票种当前代码号码.md new file mode 100644 index 0000000..4e338e8 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取指定票种当前代码号码.md @@ -0,0 +1,124 @@ +--- +title: 获取指定票种当前代码号码 +aliases: + - 获取指定票种当前代码号码 + - 诺税通获取指定票种当前代码号码 + - 库存票源与打印-获取指定票种当前代码号码 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取指定票种当前代码号码 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/getInvoiceCode.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取指定票种当前代码号码 + +### 接口说明 + +指定票种当前代码号码查询接口。 + +目前仅支持全自建-A9服务器。 + +### 接口地址 + +| | +|:------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/getInvoiceCode.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号 | 20 | +| extensionNum | String | 选填，至少分机号或机器编号任一必填 | 分机号 | 5 | +| machineNum | String | 选填，至少分机号或机器编号任一必填 | 机器编号 | 12 | +| terminalNum | String | 否 | 终端号 | 10 | +| invoiceLine | String | 必填，发票种类对应枚举值，例:p:普通发票(电子) | 发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票 | 1 | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"extensionNum":" 1",

+

"terminalNum":" 1",

+

"invoiceLine": "p"

+

}

+ +### 返回参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| code | Integer | 是 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 详细信息 | 1024 | +| data | List | | 查询成功则返回 | | +| 信息 | | | | | +| sellerTaxnum | String | 否 | 销方税号 | 20 | +| extensionNum | String | 否 | 分机号 | 5 | +| machineNum | String | 否 | 机器编号 | 12 | +| terminalNum | String | 否 | 终端号 | 10 | +| invoiceLine | String | 必填，发票种类对应枚举值，例:p:普通发票(电子) | 发票种类，p:电子增值税普通发票，c:增值税普通发票(纸票)，s:增值税专用发票，e:收购发票(电子)，f:收购发票(纸质)，r:增值税普通发票(卷式)，b:增值税电子专用发票，j：机动车发票，u：二手车发票 | 1 | +| invoiceCode | String | 是 | 当前发票代码 | 12 | +| invoiceNum | String | 是 | 当前发票号码 | 8 | +| remainNum | Integer | 否 | 剩余发票份数 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code": 200,

+

"message": "成功",

+

"data": {

+

"sellerTaxnum": "150301199811285326",

+

"extensionNum": "1",

+

"machineNum": null,

+

"terminalNum": "1",

+

"invoiceLine": "p",

+

"invoiceCode": "150010020011",

+

"invoiceNum": "23499027",

+

"remainNum": 487

+

}

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取查询数电登录认证_开票实名认证二维码.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取查询数电登录认证_开票实名认证二维码.md new file mode 100644 index 0000000..7ae2102 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取查询数电登录认证_开票实名认证二维码.md @@ -0,0 +1,118 @@ +--- +title: 获取查询数电登录认证、开票实名认证二维码 +aliases: + - 获取查询数电登录认证、开票实名认证二维码 + - 诺税通获取查询数电登录认证、开票实名认证二维码 + - 设备企业与配置-获取查询数电登录认证、开票实名认证二维码 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取查询数电登录认证、开票实名认证二维码 + +> [!info] 导航 +> 上级索引：[[README]] · [[07_设备企业与配置]] +> 文档链接：[总索引](../README.md) · [分组页](../07_设备企业与配置.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[07_设备企业与配置]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/auth/authQr.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取查询数电登录认证、开票实名认证二维码 + +### 接口说明 + +用于数电发票开具时登录扫码认证、短信验证 或 开票实名认证的时候，进行获取或查询认证二维码 + +### 接口地址 + +| | +|:---------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/auth/authQr.do | + +### 请求参数 + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| taxNum | String | 是 | 税号 | 20 | +| extensionNum | Integer | 否 | 分机号，分机号和数电账号任一必填 | \- | +| account | String | 否 | 数电账号，分机号和数电账号任一必填 | 20 | +| opType | Integer | 否 | 操作类型 0：刷新(认证二维码) 1：查询(认证二维码) 2：刷新(登录二维码) 3：查询(登录二维码) 4：发送短信验证码（短信验证码登录时）5：查询短信验证发送状态,默认1 | 1 | + +### 请求示例 + + +++ + + + + + +

{

+

"taxNum": "150301199811285326"，

+

"extensionNum": 1，

+

"account": "123456"，

+

"opType": 1

+

}

+ +### 返回参数 + +| | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **示例值** | **描述** | **长度** | +| code | Integer | 是 | 200 | 状态,200-成功，非200-失败 | 6 | +| message | String | 是 | 成功 | 详细信息 | 1024 | +| data | Object | | | 结果 | | +| 二维码信息 | | | | | | +| account | String | 否 | 138\*\*\*\*1234 | 用户名/手机号（脱敏处理） | 20 | +| taxNum | String | 否 | 150301199811285326 | 税号 | 20 | +| qrCodeType | String | 否 | 1 | 二维码类型 1:登录扫码认证多源二维码 2:登录扫码认证税APP二维码 3:登录扫码认证电子营业执照二维码 4:开票实名认证二维码 | 1 | +| status | String | 否 | 0 | 获取状态0-获取二维码中/短信发送中；1-成功；2-失败 | 1 | +| message | String | 否 | 获取中 | 信息 | 300 | +| qrCode | String | 否 | | 登录扫码认证 或 开票实人认证二维码qrcode | \- | + +### 返回示例 + +成功示例： + + +++ + + + + + +

{
+"code":200,
+"message": "成功"，

+

"data":

+

{

+

"account": "123456",

+

"taxNum": "1234567890",

+

"qrCodeType": "1",

+

"status": "0",

+

"message": "获取中",

+

"qrCode": "1fsd34s"

+

}
+}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取纸票打印编号接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取纸票打印编号接口.md new file mode 100644 index 0000000..4d62bcd --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/获取纸票打印编号接口.md @@ -0,0 +1,127 @@ +--- +title: 获取纸票打印编号接口 +aliases: + - 获取纸票打印编号接口 + - 诺税通获取纸票打印编号接口 + - 库存票源与打印-获取纸票打印编号接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 获取纸票打印编号接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[06_库存票源与打印]] +> 文档链接：[总索引](../README.md) · [分组页](../06_库存票源与打印.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[06_库存票源与打印]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`/salescore/lan/print/ batchPrintInvoiceDecrypt.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 获取纸票打印编号接口 + +### 接口说明 + +通过该接口获取可以拉起打印助手的加密字符串。 + +注意：请按照文档要求提供接口，最多可打印500张发票。 + +### 接口地址 + +/salescore/lan/print/ batchPrintInvoiceDecrypt.do + +### 请求参数(用json格式接收) + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| sellerTaxnum | String | 是 | | | 销方税号 | | +| invoiceCodeNumbers | List | 是 | | | 代码号码参数列表 | 100 | +| 票据号码金额明细列表 | | | | | | | +| invoiceCode | String | 是 | | | 票据代码 | | +| invoiceNumber | String | 是 | | | 票据号码 | | +| taxAmountTotal | String | 是 | | | 价税合计 | | + +### 请求示例 + + +++ + + + + + +

{

+

"sellerTaxnum": "150301199811285326",

+

"invoiceCodeNumbers": [

+

{

+

"invoiceCode": "5000191650",

+

"invoiceNumber": "54523588",

+

"taxAmountTotal": "1.09"

+

}

+

]

+

}

+ +### 返回参数 + +| | | | | | | | +|:--:|:--:|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必须** | **示例值** | **更多限制** | **描述** | **最大长度** | +| code | String | 是 | 200 | | 状态码，字符串”200”表示成功，非”200”的字符串表示失败 | 6 | +| message | String | 是 | 同步成功 | | 详细信息 | 1024 | +| data | String | | | | 用以拉起打印助手的参数，拼接规则如下“webprint: 2,150301199811285326%215d09ed6548424aed811e8cfd39583a03%2102”即可拉起打印助手 | | + +\#####注意拼接规则 webprint:+data (不要带加号) + +### 返回示例 + +成功示例： + + +++ + + + + + +

{

+

"code":200,

+

"data":"2,150301199811285326%215d09ed6548424aed811e8cfd39583a03%2102",

+

"message":"成功"

+

}

+ +失败示例： + + +++ + + + + + +

{

+

"code": "9999",

+

"message": ""

+

}

diff --git a/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/蓝字发票剩余可冲红的金额_税额查询接口.md b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/蓝字发票剩余可冲红的金额_税额查询接口.md new file mode 100644 index 0000000..8bae074 --- /dev/null +++ b/docs/guides/NUOSHUITONG_INTERFACE_SPEC/interfaces/蓝字发票剩余可冲红的金额_税额查询接口.md @@ -0,0 +1,197 @@ +--- +title: 蓝字发票剩余可冲红的金额、税额查询接口 +aliases: + - 蓝字发票剩余可冲红的金额、税额查询接口 + - 诺税通蓝字发票剩余可冲红的金额、税额查询接口 + - 作废重开与冲红-蓝字发票剩余可冲红的金额、税额查询接口 +tags: + - water-docs + - nuoshuitong + - invoice-api + - obsidian + - single-interface +source_docx: ../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx +source_type: converted-and-split +--- +# 蓝字发票剩余可冲红的金额、税额查询接口 + +> [!info] 导航 +> 上级索引：[[README]] · [[03_作废重开与冲红]] +> 文档链接：[总索引](../README.md) · [分组页](../03_作废重开与冲红.md) · [实施清单](../../NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md) + +> [!note] 来源 +> 来源原件：[诺诺网-诺税通销项服务对外接口规范v1.3.18.docx](../../../design/04_Appendix/Archive/03_Design_Docs/诺诺网-诺税通销项服务对外接口规范v1.3.18.docx) +> 接口分组：[[03_作废重开与冲红]] + +## 字段摘要 + +> [!summary] 接口元信息 +> - 接口地址：`http[s]://\[:\]/salescore/lan/scm/query-invoice-red.do` +> - 请求方式：`POST` +> - 是否回调：否 +> - 是否主链路：否 +> - 推荐优先级：扩展/按需 + + + +## 蓝字发票剩余可冲红的金额、税额查询接口 + +### 接口说明 + +提供蓝字发票剩余可冲红的金额、税额查询接口 + +### 接口地址 + +| | +|--------------------------------------------------------------------------| +| http\[s\]://\\[:\\]/salescore/lan/scm/query-invoice-red.do | + +### 请求参数(用json格式接收) + +| | | | | | +|:--:|:--:|:--:|:--:|:--:| +| **名称** | **类型** | **必填** | **描述** | **长度** | +| sellerTaxnum | String | 是 | 销方税号，15-20位 | 20 | +| buyerName | String | 是 | 购方名称，精确匹配 | \- | +| buyerTaxnum | String | 否 | 购方税号，精确匹配 | \- | +| invoiceStartTime | String | 否 | 包含头尾，起始日期，精确到日 | \- | +| invoiceEndTime | String | 否 | 包含头尾，截止日期，精确到日 | | +| invoiceNumber | String | 否 | 发票号码，精确匹配 发票代码有值时，发票号码必填 | | +| orderNo | String | 否 | 模糊匹配出全部拆分后规则的订单，举例：入参：A，可返回A_00001 、A_00002 | | +| taxAmountTotal | String | 否 | 含税金额，查询大于等于入参金额的发票。 | | +| taxFreeAmountTotal | String | 否 | 不含税金额，查询大于等于入参金额的发票。 | | +| invoiceLine | List\ | 是 | 发票种类 | | +| goodsName | String | 否 | 商品名称，模糊匹配，只要商品明细中包含传入商品名称就返回对应发票信息 | | +| invoiceType | Integer | 是 | 发票类型 1,蓝票 | | +| invoiceIds | List\ | 否 | 发票流水号 | | +| invoiceCode | String | 否 | 发票代码 | | +| allElectronicInvoiceNumber | String | 否 | 数电发票号码 | | +| pageNum | Integer | 否 | 当前页，默认为1 | | +| pageSize | Integer | 否 | 分页条数，默认为15 | | + +### 请求参数示例 + + +++ + + + + + +

{

+

"buyerName": "浙江师范大学",

+

"goodsName": "谷物细粉",

+

"invoiceLine": [

+

"p",

+

"j"

+

],

+

"invoiceType": 1,

+

"pageNum": 1,

+

"pageSize": 15,

+

"sellerTaxnum": "150301199811285326",

+

"invoiceIds": ["21102610281401000004"]

+

}

+ +### 返回参数 + +| | | | | +|:--------------------------:|:----------:|:-------------------------:|:--------:| +| **名称** | **类型** | **描述** | **长度** | +| code | Integer | 状态,200-成功，非200-失败 | 6 | +| message | String | 详细信息 | 1024 | +| data | list | 查询结果 | | +| buyerName | String | 购方名称 | | +| buyerTaxnum | String | 购方税号 | \- | +| invoiceTime | Date | 开票时间 | \- | +| invoiceCode | String | 发票代码 | | +| invoiceNumber | String | 发票号码 | | +| invoiceId | String | 发票流水号 | | +| orderNo | String | 订单编号 | | +| taxAmountTotal | BigDecimal | 含税金额 | | +| taxFreeAmountTotal | BigDecimal | 不含税金额 | | +| taxTotal | BigDecimal | 合计税额 | | +| invoiceLine | String | 发票种类 | | +| pdfUrl | String | 发票pdf地址 | | +| imageUrl | String | 发票图片地址 | | +| ofdUrl | String | 发票ofd地址 | | +| redTaxAmount | BigDecimal | 可冲红含税金额 | | +| redTaxFreeAmount | BigDecimal | 可冲红不含税金额 | | +| redTaxTotal | BigDecimal | 可冲红税额 | | +| allElectronicInvoiceNumber | String | 数电发票号码 | | +| pageNum | Integer | 当前页 | | +| pageSize | Integer | 每页显示条数 | | +| pages | Integer | 总页数 | | +| total | Integer | 总条数 | | + +### 返回示例 + +成功示例： + + +++ + + + + + +
+++ + + + + + +

{

+

"code": 200,

+

"data": {

+

"list": [

+

{

+

"buyerName": "浙江师范大学",

+

"buyerTaxnum": "339901999999142",

+

"imageUrl": "https://invtest.nntest.cn/fp/4ZVOcdXd-2mNx4YoP3hNXrINJSHYL3HA4gm70TaLrdGz3G1YmhriRKQyCM8qH1k5xu0zgSkfY9RvPW2qY442Fw.jpg",

+

"invoiceCode": "011001901011",

+

"invoiceId": "21092615495801000039",

+

"invoiceLine": "p",

+

"invoiceNumber": "92446751",

+

"invoiceTime": 1632642784000,

+

"ofdUrl": "",

+

"orderNo": "458fe678107c4f45867ce1d441a9626d",

+

"pdfUrl": "https://invtest.nntest.cn/fp/4ZVOcdXd-2mNx4YoP3hNXsj5w-6soDHl59Y-RJmc3-_OBpMxMxMjDRKdB-P36JpWGj5uUtg51-_NjiIgM7LTiw.pdf",

+

"redTaxAmount": 1.03,

+

"redTaxFreeAmount": 1.00,

+

"redTaxTotal": 0.03,

+

"taxAmountTotal": 1.03,

+

"taxFreeAmountTotal": 1.00,

+

"taxTotal": 0.03

+

},

+

{

+

"buyerName": "浙江师范大学",

+

"buyerTaxnum": "339901999999142",

+

"imageUrl": "",

+

"invoiceCode": "",

+

"invoiceId": "21102610460701000007",

+

"invoiceLine": "p",

+

"invoiceNumber": "",

+

"orderNo": "c7ab4c44656146d799930c29ca9befb4",

+

"pdfUrl": "",

+

"redTaxAmount": 1.03,

+

"redTaxFreeAmount": 1.00,

+

"redTaxTotal": 0.03,

+

"taxAmountTotal": 1.03,

+

"taxFreeAmountTotal": 1.00,

+

"taxTotal": 0.03

+

}

+

],

+

"pageNum": 1,

+

"pageSize": 15,

+

"pages": 9,

+

"total": 121

+

},

+

"message": "成功"

+

}

diff --git a/docs/guides/NUOSHUITONG_PG_OPENGAUSS_DDL_GUIDE.md b/docs/guides/NUOSHUITONG_PG_OPENGAUSS_DDL_GUIDE.md new file mode 100644 index 0000000..e58691f --- /dev/null +++ b/docs/guides/NUOSHUITONG_PG_OPENGAUSS_DDL_GUIDE.md @@ -0,0 +1,342 @@ +# 诺税通 DDL（PostgreSQL 16 / openGauss 适配建议） + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 项目名称 | 福建水务营收系统 | +| 文档类型 | 外部平台对接数据库方言适配建议 | +| 对接平台 | 诺税通 saas | +| 适用范围 | PostgreSQL 16、openGauss 场景下的诺税通对接表结构实现 | +| 版本 | v1.0 | +| 日期 | 2026-03-24 | +| 状态 | 草案 | + +## 适用说明 + +本文档基于以下文档继续细化： +- `docs/guides/NUOSHUITONG_DATABASE_DESIGN.md` +- `docs/guides/NUOSHUITONG_DDL_DRAFT.md` + +本文不重复给出全部业务设计，而聚焦 PostgreSQL 16 / openGauss 下的结构落地差异、字段类型建议、主键策略、索引策略与兼容性注意事项，作为后续正式数据库实现与迁移脚本编制的输入。 + +## 总体结论 + +对于当前诺税通对接表，PostgreSQL 16 与 openGauss 可基本沿用同一套逻辑模型，差异主要集中在： +- 自增主键策略 +- `text/json/jsonb` 选型 +- 时间类型与默认值写法 +- 索引能力与语法细节 +- 约束命名、在线变更和迁移脚本组织方式 + +建议策略如下： +- **逻辑模型统一**：表结构、字段名、状态字段口径统一维护 +- **DDL 方言分层**：保留一份逻辑 DDL 草案，再针对 PG16/openGauss 输出方言版本 +- **优先使用兼容类型**：避免过度依赖仅单方言增强特性 + +## 类型适配建议 + +### 主键与数值 +| 逻辑类型 | PostgreSQL 16 建议 | openGauss 建议 | 说明 | +| --- | --- | --- | --- | +| 主键 ID | `bigint` + sequence / identity | `bigint` + sequence / identity | 两侧均可用 | +| 整数 | `integer` / `bigint` | `integer` / `bigint` | 保持一致 | +| 金额 | `numeric(18,2)` | `numeric(18,2)` | 替代通用 DDL 中的 `decimal(18,2)` | +| 数量/单价 | `numeric(18,6)` | `numeric(18,6)` | 保持一致 | +| 布尔语义标志 | `smallint` | `smallint` | 建议继续用 `0/1`，避免历史口径不一致 | + +### 字符与大文本 +| 逻辑类型 | PostgreSQL 16 建议 | openGauss 建议 | 说明 | +| --- | --- | --- | --- | +| 短文本 | `varchar(n)` | `varchar(n)` | 保持一致 | +| 长文本报文 | `text` | `text` | 不再使用 MySQL 风格 `longtext` | +| URL | `varchar(1024)` | `varchar(1024)` | 保持一致 | + +### 时间类型 +| 逻辑类型 | PostgreSQL 16 建议 | openGauss 建议 | 说明 | +| --- | --- | --- | --- | +| 业务时间 | `timestamp without time zone` | `timestamp without time zone` | 若系统全局统一时区，可保持此口径 | +| 创建/更新时间 | `timestamp without time zone` | `timestamp without time zone` | 与主文档风格统一 | +| 默认当前时间 | `CURRENT_TIMESTAMP` | `CURRENT_TIMESTAMP` | 两侧兼容 | + +### JSON / 扩展字段 +| 场景 | PostgreSQL 16 建议 | openGauss 建议 | 说明 | +| --- | --- | --- | --- | +| 对接原文强留痕 | `text` | `text` | 最稳妥 | +| 需要结构化查询的 JSON 字段 | `jsonb` | `json` 或 `text`（视版本能力） | 若需强兼容，优先 `text` | +| 当前诺税通场景 | `text` 优先 | `text` 优先 | 如 `specific_factor_json`、`payload_json` | + +**建议**：诺税通对接首期以兼容优先，所有原始报文与扩展对象字段统一先落 `text`，避免在 openGauss 与 PostgreSQL 16 之间引入额外 JSON 运算差异。 + +## 主键策略建议 + +### 推荐策略 +建议统一采用： +- `bigint` 主键 +- 显式 sequence 或 identity +- 由应用层雪花 ID / 序列服务统一发号更佳 + +### PostgreSQL 16 建议写法 +```sql +id bigint generated by default as identity primary key +``` + +### openGauss 建议写法 +若版本兼容 identity，则保持一致；否则可退回： +```sql +id bigint not null default nextval('seq_ns_invoice') +``` + +### 实施建议 +为了避免不同数据库版本行为差异，若你们当前已有统一 ID 生成器，建议： +- 数据库字段仅定义 `bigint not null` +- 主键值由应用生成 + +这样迁移和多库兼容会最稳。 + +## 约束与索引适配建议 + +### 唯一索引 +当前草案中的以下唯一约束可直接保留： +- `uk_ns_invoice_sys_request_no` +- `uk_ns_red_document_bill_no` +- `uk_ns_enterprise_billing_config_tax_num` +- `uk_ns_platform_event_log_event_key` +- `uk_ns_platform_request_log_request_id` + +### 可空唯一索引注意事项 +如： +- `uk_ns_invoice_platform_serial_num` +- `uk_ns_red_document_bill_id` + +在 PostgreSQL 16 / openGauss 中，多数情况下允许多个 `NULL`，一般符合当前需求；但若你后续要求“非空且唯一”，建议改成： +- 业务侧先判空 +- 数据库侧用部分索引（若目标方言支持并确认兼容） + +### 索引字段建议 +对以下场景重点保留组合索引： +- 发票状态补偿：`request_status, invoice_status, delivery_status` +- 发票查询：`seller_tax_no, invoice_time` +- 重试调度：`next_try_time` +- 红字查询：`document_type, bill_status, open_status` +- 设备健康：`device_status, report_tax_status, clear_card_status` +- 库存快照：`seller_tax_no, invoice_line, snapshot_time` + +## 时间字段适配建议 + +原 DDL 草案中使用了 `DATETIME`。建议在 PostgreSQL 16 / openGauss 中统一替换为： +```sql +timestamp without time zone +``` + +### 推荐替换规则 +| 草案写法 | PG/openGauss 建议写法 | +| --- | --- | +| `DATETIME` | `timestamp without time zone` | +| `created_at DATETIME NOT NULL` | `created_at timestamp without time zone not null` | +| `updated_at DATETIME NOT NULL` | `updated_at timestamp without time zone not null` | + +## 核心表方言适配示例 + +## `ns_invoice` PostgreSQL 16 / openGauss 建议写法 + +```sql +CREATE TABLE ns_invoice ( + id bigint NOT NULL, + sys_request_no varchar(64) NOT NULL, + order_no varchar(64), + source_business_type varchar(32), + source_business_id varchar(64), + platform_invoice_serial_num varchar(64), + invoice_id varchar(64), + invoice_code varchar(32), + invoice_no varchar(32), + all_electronic_invoice_no varchar(64), + seller_tax_no varchar(32) NOT NULL, + 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 numeric(18,2), + amount_without_tax numeric(18,2), + tax_amount numeric(18,2), + request_status varchar(32) NOT NULL, + 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), + ofd_url varchar(1024), + image_url varchar(1024), + paper_pdf_url varchar(1024), + invoice_time timestamp without time zone, + request_time timestamp without time zone, + invalid_time timestamp without time zone, + last_sync_time timestamp without time zone, + ori_invoice_code varchar(32), + ori_invoice_no varchar(32), + old_electronic_invoice_no varchar(64), + remark varchar(1000), + specific_factor_json text, + latest_result varchar(1000), + latest_error varchar(1000), + try_count integer, + last_try_time timestamp without time zone, + next_try_time timestamp without time zone, + created_at timestamp without time zone NOT NULL, + updated_at timestamp without time zone NOT NULL, + created_by varchar(64), + updated_by varchar(64), + CONSTRAINT pk_ns_invoice PRIMARY KEY (id), + CONSTRAINT uk_ns_invoice_sys_request_no UNIQUE (sys_request_no) +); +``` + +### 推荐索引 +```sql +CREATE UNIQUE INDEX uk_ns_invoice_platform_serial_num + ON ns_invoice (platform_invoice_serial_num); + +CREATE INDEX idx_ns_invoice_order_no + ON ns_invoice (order_no); + +CREATE INDEX idx_ns_invoice_status + ON ns_invoice (request_status, invoice_status, delivery_status); + +CREATE INDEX idx_ns_invoice_seller_tax_no + ON ns_invoice (seller_tax_no); + +CREATE INDEX idx_ns_invoice_invoice_time + ON ns_invoice (invoice_time); + +CREATE INDEX idx_ns_invoice_next_try_time + ON ns_invoice (next_try_time); +``` + +## `ns_platform_event_log` PostgreSQL 16 / openGauss 建议写法 + +```sql +CREATE TABLE ns_platform_event_log ( + id bigint NOT NULL, + event_type varchar(32) NOT NULL, + event_key varchar(128) NOT NULL, + seller_tax_no varchar(32), + business_key varchar(128), + payload_json text NOT NULL, + process_status varchar(32) NOT NULL, + process_message varchar(1000), + processed_at timestamp without time zone, + created_at timestamp without time zone NOT NULL, + CONSTRAINT pk_ns_platform_event_log PRIMARY KEY (id), + CONSTRAINT uk_ns_platform_event_log_event_key UNIQUE (event_key) +); +``` + +## `ns_invoice_stock_snapshot` PostgreSQL 16 / openGauss 建议写法 + +```sql +CREATE TABLE ns_invoice_stock_snapshot ( + id bigint NOT NULL, + device_id bigint, + seller_tax_no varchar(32) NOT NULL, + 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 integer, + is_default smallint, + source_type varchar(16) NOT NULL, + snapshot_time timestamp without time zone NOT NULL, + created_at timestamp without time zone NOT NULL, + CONSTRAINT pk_ns_invoice_stock_snapshot PRIMARY KEY (id) +); +``` + +## openGauss 特别注意事项 + +### 1. 避免首期过度依赖 JSONB +虽然部分 openGauss 版本具备 JSON 能力，但在迁移期为了降低差异，建议： +- `specific_factor_json` 用 `text` +- `payload_json` 用 `text` +- `request_body/response_body` 用 `text` + +### 2. 避免直接依赖部分索引、表达式索引的高级特性 +如果后续确实需要，请在 PG16 与 openGauss 两侧分别验证后再引入。 + +### 3. 约束命名统一 +建议所有主键、唯一约束、外键、索引均显式命名，避免迁移工具自动生成差异名称。 + +### 4. 时间默认值与更新策略 +不要依赖 MySQL 风格的 `on update current_timestamp`；建议： +- `created_at` 默认应用层写入 +- `updated_at` 由应用更新 +- 或用触发器，但触发器策略需单独治理 + +## PostgreSQL 16 特别建议 + +### 1. 可考虑使用 identity +若项目主键策略准备切换到数据库发号，可优先在 PostgreSQL 16 使用： +```sql +generated by default as identity +``` + +### 2. 后续可逐步将部分 `text` 字段演进为 `jsonb` +适用于： +- 平台事件检索增强 +- `specific_factor_json` 局部结构化查询 + +但建议等 openGauss 迁移策略稳定后再做。 + +## 迁移实施建议 + +### 第一阶段：逻辑模型统一 +- 保持当前 `ns_` 表结构不变 +- 所有长文本字段先统一使用 `text` +- 所有时间字段统一替换为 `timestamp without time zone` + +### 第二阶段：DDL 方言拆分 +输出两份实际执行脚本： +- `postgresql/nuoshuitong_ddl.sql` +- `opengauss/nuoshuitong_ddl.sql` + +### 第三阶段：兼容性验证 +重点验证： +- 唯一约束在空值场景下的行为 +- 外键创建顺序 +- 索引创建语句 +- 迁移工具（如 Flyway/Liquibase）执行兼容性 + +## 推荐优先落地表 +建议在 PostgreSQL 16 / openGauss 两侧先优先验证以下 5 张表： +- `ns_invoice` +- `ns_invoice_item` +- `ns_invoice_reversal` +- `ns_billing_device` +- `ns_platform_request_log` + +原因： +- 覆盖主链路核心对象 +- 覆盖状态流转 +- 覆盖设备与日志两类最容易暴露方言差异的场景 + +## 后续建议 + +建议在本文档基础上继续输出： +- PostgreSQL 16 实际可执行版 DDL +- openGauss 实际可执行版 DDL +- 字段注释脚本 +- 初始化枚举字典脚本 +- Flyway / Liquibase 迁移脚本编排建议 diff --git a/docs/guides/NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md b/docs/guides/NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md new file mode 100644 index 0000000..0868380 --- /dev/null +++ b/docs/guides/NUOSHUITONG_SAAS_INTEGRATION_CHECKLIST.md @@ -0,0 +1,555 @@ +# 诺税通 saas 对接实施清单 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 项目名称 | 福建水务营收系统 | +| 文档类型 | 外部平台对接实施清单 | +| 对接平台 | 诺税通 saas | +| 适用范围 | 销项开票、发票查询、PDF 获取、重新交付、作废、库存与客户端状态检查 | +| 版本 | v1.0 | +| 日期 | 2026-03-24 | +| 状态 | 已整理 | + +## 适用说明 + +本文档用于指导福建水务营收系统对接诺税通 saas 的首期实施工作，聚焦销项发票主链路。内容覆盖接口优先级、字段映射建议、业务流程、错误码处理策略与沙箱测试清单，适合作为实施前评审、开发拆解与联调验收的统一依据。 + +当前口径以诺诺开放平台中“诺税通 saas”接口组为准，不再沿用通用 `ElectronInvoice` 接口组作为主实施入口。 + +## 接口优先级 + +### P0：首批必须接入 + +#### 请求开具发票 +- 方法：`nuonuo.OpeMplatform.requestBillingNew` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100607` +- 作用：提交开票请求，获取平台发票流水号，是销项开票主入口。 + +#### 发票列表查询 +- 方法：`nuonuo.OpeMplatform.queryInvoiceList` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100687` +- 作用：查询发票列表、状态与基础结果，是查询与状态核对主入口。 + +#### 获取电子发票 PDF +- 方法：`nuonuo.OpeMplatform.getPDF` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100694` +- 作用：获取已开票发票的 PDF 地址，用于下载、预览与交付。 + +### P1：首批强烈建议接入 + +#### 发票重新交付 +- 方法：`nuonuo.OpeMplatform.deliveryInvoice` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100696` +- 作用：对未收到发票的用户重新通过短信或邮件进行交付。 + +#### 发票作废 +- 方法：`nuonuo.OpeMplatform.invoiceCancellation` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100591` +- 作用：退款、撤销或错误开票后的作废处理。 + +### P1：开票前保障接口 + +#### 企业发票余量查询 +- 方法：`nuonuo.OpeMplatform.getInvoiceStock` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100599` +- 作用：检查票源余量，避免无票或票段不足时继续开票。 + +#### 客户端在线状态检测 +- 方法：`nuonuo.OpeMplatform.GetClientStatus` +- 文档入口：`https://jss.com.cn/open/#/api-doc/common-api?id=100598` +- 作用：确认客户端或设备在线状态，是开票前健康检查的重要前置条件。 + +## 统一接入规范 + +### 网关地址 +- 正式环境：`https://sdk.nuonuo.com/open/v1/services` +- 沙箱环境：`https://sandbox.nuonuocs.cn/open/v1/services` + +### 通用消息头 +- `Content-type` +- `X-Nuonuo-Sign` +- `accessToken` +- `userTax` +- `method` + +### 通用消息体 +- `senid` +- `nonce` +- `timestamp` +- `appkey` + +### 平台侧基础凭据 +实施前需准备以下内容： +- `appKey` +- `appSecret` +- `accessToken` +- 销方税号 / 授权税号 +- 如采用客户端设备模式，还需准备分机号、机器编号、部门 ID 等运行态配置 + +## 请求 / 响应字段映射建议 + +### 请求开具发票 + +#### 接口 +`nuonuo.OpeMplatform.requestBillingNew` + +#### 请求结构 +平台私有请求参数顶层为： +- `order: Object` + +即业务字段全部封装在 `order` 对象中。 + +#### 建议内部模型 + +##### 发票主对象 `InvoiceOrder` +- `orderNo`：业务订单号 +- `invoiceType`：开票类型，建议内部固定枚举蓝票/红票 +- `sellerTaxNo`：销方税号 +- `buyerName`：购方名称 +- `buyerTaxNo`：购方税号 +- `buyerAddress`：购方地址 +- `buyerTel`：购方电话 +- `buyerAccount`：购方开户行及账号 +- `email`：交付邮箱 +- `phone`：交付手机号 +- `invoiceLine`：发票类型线别 +- `listFlag`：清单标志 +- `pushMode`：交付方式 +- `departmentId`：部门 ID +- `machineCode`：机器编号 +- `clerkId`：开票员 ID +- `payee`：收款人 +- `remark`：备注 + +##### 发票明细对象 `InvoiceItem` +- `goodsName`：商品名称 +- `goodsCode`：税收分类编码 +- `taxRate`：税率 +- `quantity`：数量 +- `unitPrice`：单价 +- `taxIncludedAmount`：含税金额 +- `taxExcludedAmount`：不含税金额 +- `tax`：税额 +- `invoiceLineProperty`：明细行属性 + +#### 响应字段 +- `invoiceSerialNum`：平台发票流水号 + +#### 建议落库字段 +- `platformInvoiceSerialNum` +- `requestStatus` +- `requestTime` +- `sellerTaxNo` +- `orderNo` + +### 发票列表查询 + +#### 接口 +`nuonuo.OpeMplatform.queryInvoiceList` + +#### 已确认关键请求字段 +- `taxnum`：企业税号 +- `requestType`：查询类型 + - `0`：按发票添加时间查询 + - `1`：按开票时间查询 + - `2`：按发票状态更新时间查询 + +#### 建议内部查询参数 +- `sellerTaxNo` +- `queryMode` +- `startTime` +- `endTime` +- `pageNo` +- `pageSize` +- `invoiceStatus` + +#### 建议响应映射 +- `platformInvoiceSerialNum` +- `invoiceCode` +- `invoiceNo` +- `invoiceType` +- `invoiceStatus` +- `invoiceStatusText` +- `buyerName` +- `buyerTaxNo` +- `totalAmount` +- `taxAmount` +- `invoiceTime` +- `pdfUrl` +- `orderNo` + +### 获取电子发票 PDF + +#### 接口 +`nuonuo.OpeMplatform.getPDF` + +#### 请求字段 +- `invoiceCode`：发票代码，数电票时可为空 +- `invoiceNo`：发票号码，数电票传 20 位号码 + +#### 响应字段 +- `pdfurl`：PDF 地址 + +#### 建议内部映射 +请求： +- `invoiceCode` +- `invoiceNo` + +响应： +- `pdfUrl` +- `fetchedAt` + +### 发票重新交付 + +#### 接口 +`nuonuo.OpeMplatform.deliveryInvoice` + +#### 请求字段 +- `taxnum`：销方税号 +- `invoiceCode`：发票代码，全电发票可为空 +- `invoiceNum`：发票号码 +- `phone`：交付手机号 +- `mail`：交付邮箱 + +约束：手机号和邮箱至少一个非空。 + +#### 响应字段 +- `code` +- `describe` +- `result` + +#### 建议内部映射 +请求： +- `sellerTaxNo` +- `invoiceCode` +- `invoiceNo` +- `deliveryPhone` +- `deliveryEmail` + +响应： +- `deliveryStatus` +- `deliveryMessage` +- `deliveryTime` + +### 发票作废 + +#### 接口 +`nuonuo.OpeMplatform.invoiceCancellation` + +#### 请求字段 +- `invoiceId` +- `invoiceCode` +- `invoiceNo` +- `invalidReason` +- `specificReason` + +其中： +- `invalidReason` 在全电纸票作废时需要传，取值为 `1` 销货退回、`2` 开票有误、`3` 服务中止、`4` 其他 +- `specificReason` 在作废原因为“其他”时填写具体原因 + +#### 响应字段 +- `invoiceId` + +#### 建议内部映射 +请求： +- `platformInvoiceSerialNum` +- `invoiceCode` +- `invoiceNo` +- `cancelReasonCode` +- `cancelReasonText` + +响应： +- `platformInvoiceSerialNum` + +### 企业发票余量查询 + +#### 接口 +`nuonuo.OpeMplatform.getInvoiceStock` + +#### 请求字段 +- `departmentId` +- `extensionNums` +- `machineCode` +- `extMachineCodePairs` + +#### 响应字段 +- `extensionNumber` +- `terminalNumber` +- `invoiceLine` +- `machineCode` +- `remainNum` +- `invoiceNumStart` +- `invoiceNumEnd` +- `updateTime` + +#### 建议内部映射 +- `sellerTaxNo` +- `machineCode` +- `invoiceLine` +- `remainNum` +- `invoiceNumStart` +- `invoiceNumEnd` +- `lastSyncTime` + +### 客户端在线状态检测 + +#### 接口 +`nuonuo.OpeMplatform.GetClientStatus` + +#### 请求字段 +- `sellerTaxNo` +- `extensionNumber` +- `machineCode` + +#### 响应字段 +- `sellerTaxNo` +- `sellerName` +- `extensionNumber` +- `machineCode` +- `clientVersion` +- `onlineStatus`：`0` 不在线，`1` 在线 +- `date` + +#### 建议内部映射 +- `sellerTaxNo` +- `machineCode` +- `extensionNumber` +- `clientVersion` +- `onlineStatus` +- `checkedAt` + +## 业务流程图 + +### 开票主流程 + +```mermaid +flowchart TD + A[业务订单满足开票条件] --> B[检查客户端在线状态] + B -->|不在线| B1[返回不可开票并告警] + B -->|在线| C[检查发票余量] + C -->|无余量或异常| C1[返回不可开票并告警] + C -->|正常| D[组装开票请求 order] + D --> E[调用 requestBillingNew] + E -->|失败| E1[记录失败原因] + E -->|成功| F[保存 invoiceSerialNum] + F --> G[调用 queryInvoiceList 或状态查询] + G -->|未开票完成| G1[轮询或等待回调] + G -->|开票完成| H[调用 getPDF] + H --> I[保存 pdfUrl] + I --> J[交付给用户] + J --> K[结束] +``` + +### 补发流程 + +```mermaid +flowchart TD + A[用户未收到发票] --> B[查到已开票记录] + B --> C[收集手机号或邮箱] + C --> D[调用 deliveryInvoice] + D -->|成功| E[记录补发成功] + D -->|失败| F[记录失败原因并转人工处理] +``` + +### 作废流程 + +```mermaid +flowchart TD + A[订单退款或撤销或开票错误] --> B[查询发票记录] + B --> C[确认 invoiceId invoiceCode invoiceNo] + C --> D[调用 invoiceCancellation] + D -->|成功| E[更新作废申请状态] + D -->|失败| F[记录失败原因] +``` + +## 错误码处理策略 + +### A 类：参数错误，直接拦截 +典型错误码： +- `E4000` +- `E9101` +- `E9102` +- `E9104` +- `E9106` + +处理建议： +- 不重试 +- 记录请求校验失败 +- 直接返回调用方明确提示 + +### B 类：资质或权限错误，升级处理 +典型错误码： +- `E9301` +- `E9302` +- `E9338` +- `E9513` +- `E9548` +- `E1001` + +处理建议： +- 不自动重试 +- 标记为配置或权限异常 +- 通知实施、运维或平台管理员处理 + +### C 类：业务状态异常，需要人工介入 +典型场景： +- 发票不存在 +- 发票不可重复冲红 +- 发票不能重新交付 +- 平台返回 `E9999` 且语义为业务错误 + +处理建议： +- 记录完整请求参数与上下文 +- 进入人工处理队列 + +### D 类：环境与设备状态异常 +典型场景： +- 客户端不在线 +- 分机号错误 +- 票源余量不足 + +处理建议： +- 在开票前即拦截 +- 不进入正式开票流程 +- 发出运行告警 + +### 建议错误处理表 + +| 错误类型 | 是否重试 | 是否告警 | 是否人工介入 | +| --- | --- | --- | --- | +| 参数错误 | 否 | 否 | 否 | +| 企业资质/权限错误 | 否 | 是 | 是 | +| 发票不存在 | 否 | 否 | 是 | +| 客户端离线 | 否 | 是 | 是 | +| 库存不足 | 否 | 是 | 是 | +| 平台系统错误 | 有限重试 | 是 | 视情况 | + +### 建议重试策略 +仅对明显的平台瞬时失败做有限重试： +- 最多 2~3 次 +- 使用指数退避 +- 对参数错误、资质错误、业务状态错误不重试 + +## 沙箱测试清单 + +### 环境准备 +- [ ] 获取沙箱 `appKey` +- [ ] 获取沙箱 `appSecret` +- [ ] 获取沙箱 `accessToken` +- [ ] 确认沙箱测试税号 +- [ ] 确认已开通 API 开票权限 +- [ ] 确认测试设备、分机号、机器编号 + +### 接口连通性 +- [ ] 成功调用统一网关 +- [ ] 签名计算正确 +- [ ] `accessToken` 可用 +- [ ] `userTax` 配置正确 + +### 开票前检查 +- [ ] `GetClientStatus` 返回在线 +- [ ] `getInvoiceStock` 返回库存信息 +- [ ] 分机号与机器编号识别正确 + +### 开票测试 +- [ ] 成功开具一张蓝票 +- [ ] 返回 `invoiceSerialNum` +- [ ] 发票列表可查到该票 +- [ ] PDF 地址获取成功 +- [ ] 邮箱交付成功 +- [ ] 手机交付成功 + +### 异常测试 +- [ ] 缺少必填字段触发 `E4000` +- [ ] 错误税号触发资质或权限异常 +- [ ] 错误发票号获取 PDF 失败 +- [ ] 错误发票号重新交付失败 +- [ ] 错误发票号作废失败 + +### 作废测试 +- [ ] 正常作废成功 +- [ ] 返回新的 `invoiceId` +- [ ] 作废后列表状态与平台侧一致 + +### 结果核验 +- [ ] 业务订单号与平台流水号绑定成功 +- [ ] PDF 地址成功保存 +- [ ] 错误日志与请求日志完整 +- [ ] 所有请求报文可追踪 +- [ ] 沙箱字段模型与正式环境字段模型保持一致 + +## 建议的数据落库字段 + +### 发票主表 +- `order_no` +- `seller_tax_no` +- `buyer_name` +- `buyer_tax_no` +- `invoice_type` +- `invoice_code` +- `invoice_no` +- `platform_invoice_serial_num` +- `invoice_status` +- `invoice_status_text` +- `pdf_url` +- `total_amount` +- `tax_amount` +- `invoice_time` +- `created_at` +- `updated_at` + +### 平台交互日志表 +- `request_id` +- `method` +- `request_headers_masked` +- `request_body` +- `response_body` +- `response_code` +- `success_flag` +- `error_message` +- `created_at` + +### 交付记录表 +- `invoice_id` +- `delivery_type` +- `delivery_target` +- `delivery_status` +- `delivery_message` +- `delivery_time` + +## 实施建议 + +### 第一阶段 +优先打通： +- 在线状态检测 +- 余量查询 +- 请求开票 +- 列表查询 +- PDF 获取 + +### 第二阶段 +补齐： +- 重新交付 +- 作废 + +### 第三阶段 +再扩展： +- 回调与轮询优化 +- 自动重试 +- 监控与告警 +- 对账与审计 + +## 当前明确结论 + +福建水务营收系统对接诺税通 saas 时，应以以下方法名作为首期实施主入口： +- `nuonuo.OpeMplatform.requestBillingNew` +- `nuonuo.OpeMplatform.queryInvoiceList` +- `nuonuo.OpeMplatform.getPDF` +- `nuonuo.OpeMplatform.deliveryInvoice` +- `nuonuo.OpeMplatform.invoiceCancellation` +- `nuonuo.OpeMplatform.getInvoiceStock` +- `nuonuo.OpeMplatform.GetClientStatus` + +不再以通用 `ElectronInvoice` 接口组作为主实施口径。 diff --git a/docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md b/docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md new file mode 100644 index 0000000..046966a --- /dev/null +++ b/docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md @@ -0,0 +1,487 @@ +# REV-004 旧账务数据迁移实施方案 v0 + +## 1. 文档定位 + +本文档用于起草福建水务营收系统中“旧账务模型迁移到新系统模型”的第一版实施方案，重点聚焦 `REV-004` 账务处理一期及其直接关联的收费、预存、退款、冲正、坏账、发票追溯对象。 + +本文档不是最终迁移脚本，也不是最终数据口径裁决书，而是后续正式立项、迁移设计、实现拆解和验收校对的基础方案。 + +## 2. 背景与目标 + +当前仓库已经明确： + +- `REV-004` 当前正式模型是“账务处理控制模型” +- 旧系统数据字典体现的是“营业账 + 收费 + 预存账户 + 调整申请单 + 发票”的业务财务模型 +- 新系统不计划机械复制旧系统的全部精细账务台账表族 +- 但若存在旧业务继续迁移与历史查询要求，则必须保证迁移后数据可承接、可追溯、可核对 + +因此，本方案的目标不是“把旧表名原样搬过来”，而是： + +1. 识别旧账务对象与新系统能力边界 +2. 明确哪些数据进入新系统在线主模型 +3. 明确哪些数据作为历史只读保留 +4. 明确哪些数据只保留映射与追溯关系 +5. 形成可执行的迁移批次、校验规则和风险控制方案 + +## 3. 迁移范围 + +### 3.1 本轮纳入范围 + +- `AT_CHARGES`、`AT_CHARGE_DETAILS` +- `CT_ACCOUNTS`、`CT_ACCOUNT_LOGS` +- `AT_REFUNDS` +- `PM_ACCOUNT_RECORDS`、`PM_ACCOUNT_RECORD_DETAILS` +- `PM_AMOUNT_RECORDS`、`PM_AMOUNT_RECORD_DETAILS` +- `PM_PRICE_RECORDS`、`PM_PRICE_RECORD_DETAILS` +- `PM_PAYMENT_RECORDS`、`PM_PAYMENT_RECORD_DETAILS` +- `PM_KNOTTY_RECORDS`、`PM_KNOTTY_RECORD_DETAILS` +- `PM_LATEFEE_RECORDS`、`PM_LATEFEE_RECORD_DETAILS` +- `PM_PAY_COLLECTS`、`PM_PAY_SUBTOTALS`、`PM_PAY_DETAILS` +- `IV_INVOICE_INFOS`、`IV_INVOICE_DETAIL_INFOS`、`IV_CHARGE_INVOICE_MAPPINGS` + +### 3.2 本轮关联参考范围 + +- `营收数据字典.md` +- `docs/guides/BACKEND_TABLE_MAPPING.md` +- `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 `REV-004` 迁移补充 +- `docs/design/03_Technical_Design/03_Interface_Design.md` 中“历史查询与迁移校验接口口径” + +### 3.3 本轮暂不纳入范围 + +- 独立总账、明细账、会计分录体系重建 +- 独立账务中台或账本引擎 +- 旧审批流引擎的完整在线复刻 +- 超出 `REV-004` 一期范围的新业务规则扩展 + +## 4. 迁移原则 + +### 4.1 语义迁移优先于表结构平移 + +迁移对象首先是业务语义、状态语义、追溯语义和查询语义，而不是旧表结构本身。 + +### 4.2 在线承接与历史保留分层 + +新系统中必须明确区分： + +- 在线主模型承接 +- 历史只读承接 +- 映射追溯承接 + +不得把所有历史表都作为在线业务表原样重建。 + +### 4.3 汇总对账与明细追溯并重 + +迁移验收必须同时支持： + +- 汇总级核对 +- 明细级追溯 + +避免只对总数、不支持差异定位。 + +### 4.4 新旧标识必须保留映射 + +迁移后至少应保留以下映射能力： + +- 原账单号 ↔ 新账单号 +- 原流水号 ↔ 新流水号 +- 原申请单 ↔ 新业务单号 +- 原发票号 ↔ 新发票对象 +- 原处理记录 ↔ 新留痕记录 + +### 4.5 历史查询只读 + +历史查询接口只承担查询、比对和审计职责，不承担迁移修正、状态补写或在线业务处理职责。 + +## 5. 新旧模型差异判断 + +### 5.1 旧模型特征 + +旧模型主要表现为： + +- 以 `FeeId` 为核心的营业账模型 +- 以 `AccountId / AccLogId` 为核心的预存账户与流水模型 +- 以“汇总表 + 明细表 + 流程字段”构成的账务申请单模型 +- 以收费汇总、小计、明细、实时收费日志构成的收费结果模型 +- 以发票主表、发票明细、账单映射表构成的发票模型 + +### 5.2 新模型特征 + +当前 `REV-004` 正式口径主要表现为： + +- 统一入口：`IF-REV-007` +- 统一场景：水量调整、金额调整、退款、冲正、坏账申请 +- 统一共性控制：范围校验、状态校验、原交易校验、留痕、审批边界 +- 统一结果表达：`AccountingResult` +- 统一留痕对象：`OperationLog` +- 在线主模型承接以 `biz_charge*`、`bk_transaction*`、`biz_operat_log*` 为主 + +### 5.3 迁移结论 + +本次迁移不应追求“旧表 = 新表”的结构兼容，而应采用三层承接模型： + +1. 标准业务承接层 + 由新系统正式在线对象承接当前有效业务数据与后续处理能力。 + +2. 兼容映射层 + 记录旧标识、新标识、状态映射、来源类型和迁移批次，支撑核对和追溯。 + +3. 历史只读层 + 保留旧系统难以在线抽象但必须可查的历史明细、审批痕迹与台账信息。 + +## 6. 迁移分层设计 + +### 6.1 在线主模型承接层 + +建议由以下对象主承接： + +- `biz_charge` / `biz_charge_detail` +- `bk_transaction*` +- `biz_operat_log*` +- `biz_invoice*` +- `biz_cust_invoice` +- `biz_collection` / `bk_*` 支付与对账对象 + +适合进入在线主模型的典型数据： + +- 当前有效账单 +- 当前有效账单明细 +- 当前有效收费结果 +- 当前有效发票结果 +- 当前可继续参与账务处理的退款、冲正、坏账关联对象 + +### 6.2 兼容映射层 + +建议新增或规划一组“迁移映射对象”，至少覆盖： + +- `legacy_charge_mapping` +- `legacy_account_log_mapping` +- `legacy_finance_record_mapping` +- `legacy_invoice_mapping` +- `legacy_business_trace_mapping` + +每条映射建议至少保留： + +- `legacySystem` +- `legacyTable` +- `legacyId` +- `legacyBizNo` +- `targetDomain` +- `targetId` +- `targetBizNo` +- `mappingType` +- `migrationBatchNo` +- `migrationTime` +- `mappingStatus` + +### 6.3 历史只读层 + +以下对象默认优先按历史只读保留： + +- 旧审批节点痕迹 +- 旧汇总/明细台账中的页面型冗余字段 +- 旧系统专门为菜单、导出、统计、补打而拆出的历史辅助表 + +历史只读层必须满足： + +- 能按原单号、客户号、账期、处理类型查询 +- 能返回新旧标识映射 +- 能支持迁移验收和审计追溯 + +## 7. 迁移对象分类与策略 + +| 对象类别 | 典型旧表 | 建议策略 | 说明 | +| --- | --- | --- | --- | +| 账单主明细 | `AT_CHARGES`、`AT_CHARGE_DETAILS` | 在线承接 + 映射 | 属于新系统核心主对象，必须进入在线模型 | +| 账户余额与流水 | `CT_ACCOUNTS`、`CT_ACCOUNT_LOGS` | 在线承接 + 映射 + 历史补充 | 预存相关场景必须可追溯 | +| 收费结果 | `PM_PAY_*`、实时收费日志 | 在线承接 + 历史只读 | 主结果进入在线模型，细粒度日志可保留只读 | +| 退款对象 | `AT_REFUNDS`、`PM_ACCOUNT_RECORD*` | 在线承接场景语义 + 历史明细只读 | 统一挂到退款场景，不强求一对一新实体 | +| 调整对象 | `PM_AMOUNT_*`、`PM_PRICE_*`、`PM_PAYMENT_*` | 场景归并 + 映射 + 历史只读 | 进入金额/水量调整、冲正等统一场景 | +| 坏账对象 | `PM_KNOTTY_*` | 场景归并 + 映射 | 统一纳入坏账申请场景 | +| 滞纳金减免 | `PM_LATEFEE_*` | 场景归并 + 历史只读 | 视为账务处理衍生场景 | +| 发票对象 | `IV_*` | 在线承接 + 历史映射 | 发票主对象与账单关系必须保留 | + +## 8. 推荐迁移批次 + +### 批次 1：基础主数据与主业务对象 + +目标： + +- 锁定客户、账户、账单主明细的迁移基线 + +对象： + +- 客户相关主数据 +- `CT_ACCOUNTS` +- `AT_CHARGES` +- `AT_CHARGE_DETAILS` + +输出： + +- 账单主键映射 +- 账户主键映射 +- 批次级基础对账报告 + +### 批次 2：收费结果与交易对象 + +目标： + +- 锁定收费、核销、支付、对账相关迁移基线 + +对象： + +- `PM_PAY_COLLECTS` +- `PM_PAY_SUBTOTALS` +- `PM_PAY_DETAILS` +- 实时收费日志 +- `bk_transaction*` 对应交易承接对象 + +输出： + +- 收费汇总对账 +- 明细流水映射 +- 异常流水清单 + +### 批次 3：账务处理历史对象 + +目标： + +- 锁定 `REV-004` 相关旧账务处理历史的承接方式 + +对象： + +- `PM_ACCOUNT_RECORD*` +- `PM_AMOUNT_*` +- `PM_PRICE_*` +- `PM_PAYMENT_*` +- `PM_KNOTTY_*` +- `PM_LATEFEE_*` +- `AT_REFUNDS` + +输出： + +- 场景归并结果表 +- 新旧状态映射表 +- 历史只读查询口径 + +### 批次 4：发票对象与账单关系 + +目标： + +- 锁定账单与发票的历史关系、结果状态和追溯路径 + +对象： + +- `IV_INVOICE_INFOS` +- `IV_INVOICE_DETAIL_INFOS` +- `IV_CHARGE_INVOICE_MAPPINGS` + +输出： + +- 发票映射表 +- 账单-发票关系校验报告 +- 历史补打与历史查询口径 + +## 9. 必要映射矩阵 + +本方案落地前，至少需要产出以下四份矩阵： + +### 9.1 旧表到新对象映射矩阵 + +字段建议： + +- 旧表名 +- 旧对象语义 +- 新对象域 +- 新对象名 +- 承接方式 +- 是否在线承接 +- 是否历史只读 +- 风险说明 + +### 9.2 旧字段到新字段映射矩阵 + +字段建议： + +- 旧字段 +- 新字段 +- 转换规则 +- 默认值规则 +- 是否允许为空 +- 是否需要枚举转换 +- 是否需要补充追溯字段 + +### 9.3 旧状态到新状态映射矩阵 + +字段建议： + +- 旧表名 +- 旧状态字段 +- 旧状态值 +- 新状态字段 +- 新状态值 +- 是否完全等价 +- 若不等价的补充字段 + +### 9.4 新旧标识映射矩阵 + +字段建议： + +- 原系统单号 +- 原表主键 +- 新系统业务单号 +- 新系统主键 +- 迁移批次 +- 映射状态 +- 是否核验通过 + +## 10. 最小兼容字段建议 + +若新模型需要完整支撑迁移与追溯，建议至少预留以下兼容字段或扩展属性： + +- `legacySystem` +- `legacyTable` +- `legacyId` +- `legacyBizNo` +- `legacyState` +- `sourceFeeId` +- `sourceAccLogId` +- `sourceInvoiceId` +- `targetBizNo` +- `migrationBatchNo` +- `migrationRemark` +- `tracePayload` + +这些字段不一定都进入核心业务主表，但必须有稳定承接位置。 + +## 11. 迁移校验方案 + +### 11.1 数量校验 + +至少校验： + +- 账单总数 +- 账单明细总数 +- 账户总数 +- 账户流水总数 +- 收费明细总数 +- 发票总数 +- 迁移历史记录总数 + +### 11.2 金额校验 + +至少校验： + +- 应收金额汇总 +- 实收金额汇总 +- 预存余额汇总 +- 退款金额汇总 +- 坏账金额汇总 +- 发票金额汇总 + +### 11.3 关系校验 + +至少校验： + +- 账单 ↔ 账单明细 +- 账单 ↔ 收费明细 +- 账单 ↔ 发票映射 +- 账户 ↔ 账户流水 +- 调整记录 ↔ 原账单 / 新账单 +- 退款记录 ↔ 原流水 / 目标流水 + +### 11.4 业务抽样校验 + +建议每类场景至少抽样： + +- 1 笔预存退款 +- 1 笔已销调整 +- 1 笔价差调整 +- 1 笔坏账申请 +- 1 笔发票回写 +- 1 笔收费红冲 + +要求在新系统中能完整回答： + +- 原记录是谁 +- 对应新记录是谁 +- 状态是否一致 +- 金额是否一致 +- 关联关系是否完整 +- 审计追溯是否可查 + +## 12. 查询与验收接口要求 + +迁移后至少应满足以下查询能力： + +- 按原账单号 / 新账单号查询迁移关系 +- 按原流水号 / 新流水号查询收费与退款关系 +- 按客户号、账期、处理类型查询历史账务处理记录 +- 按发票号、申请单号查询账单与发票关系 +- 按迁移批次查看汇总对账结果与差异明细 + +这些查询能力应优先挂靠现有 `IF-REV-*` 接口族扩展，不建议为迁移单独发明新的正式接口编号体系。 + +## 13. 风险清单 + +### 风险 1：旧模型一表多义 + +部分旧表同时承载业务申请、审批流程、结果记录和页面展示字段，难以直接映射到新系统单一对象。 + +应对： + +- 拆分“在线承接字段”和“历史只读字段” +- 不强行一对一建表 + +### 风险 2：状态机不完全等价 + +旧系统中的 `State`、`ProcType`、`BusinessType`、审批节点状态与新系统结果状态不一定一一对应。 + +应对： + +- 必做状态映射矩阵 +- 对不等价状态保留 `legacyState` + +### 风险 3：旧审批流无法在线复刻 + +旧模型中大量存在 `TaskId`、`StepId`、`FlowRemark`，但当前 `REV-004` 只保留审批能力位。 + +应对： + +- 流程痕迹优先按历史只读保留 +- 在线模型仅保留审批边界和结果位 + +### 风险 4：收费、发票、退款链条断链 + +若只迁主对象，不迁关联映射，后续核对、审计和客户查询会断链。 + +应对： + +- 强制保留新旧标识映射 +- 发票、收费、退款场景必须建立关系校验 + +## 14. 推荐实施顺序 + +1. 完成旧对象清单与迁移分层判断 +2. 完成四类映射矩阵 +3. 补齐新模型兼容字段与映射承接设计 +4. 设计迁移批次与回滚策略 +5. 再进入迁移脚本开发与试迁 +6. 最后执行汇总校验、明细抽样校验和差异修正 + +## 15. 当前待补充项 + +本方案作为 v0 草稿，下一轮至少还需要补以下内容： + +- 旧表到当前 backend 真实表的逐表映射 +- `REV-004` 新模型兼容字段的正式落位位置 +- 迁移批次的执行窗口与冻结策略 +- 试迁环境、脚本入口和回滚方案 +- 差异处理与复迁规则 + +## 16. 参考来源 + +- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` +- `docs/guides/BACKEND_TABLE_MAPPING.md` +- `docs/design/02_Detailed_Design/12_REV_Detailed.md` +- `docs/design/03_Technical_Design/03_Interface_Design.md` +- `docs/design/00_Management/07_Migration_Mapping_Template.md` diff --git a/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md b/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md new file mode 100644 index 0000000..119099c --- /dev/null +++ b/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md @@ -0,0 +1,888 @@ +# Speckit 工作流的人类友好教学文档 + +## 1. 先说结论 + +`Speckit` 的理论基础，不是“先写一堆文档”，而是先把一个需求拆成一连串可验证的小闭环，再让每个闭环都留下明确工件。 + +在这个工作区里，它本质上是在解决四个老问题： + +1. 需求很容易一开始就说大了，最后越做越散。 +2. 文档、代码、验证和台账经常各说各话。 +3. 多仓协作时，大家都在干活，但没人能准确回答“现在到底做到哪了”。 +4. 交付时只能靠口头解释，缺少稳定的追溯链。 + +所以 `Speckit` 不是“文档优先”这么简单，它更准确的说法是： + +**用规格驱动的方式，把需求澄清、方案收敛、任务拆解、实现验证、结论回写做成一个个可追溯闭环。** + +--- + +## 2. 它基于什么理论 + +结合本仓库的 `constitution`、模板和工作流说明，`Speckit` 的底层思想主要来自以下几类工程方法。 + +### 2.1 单一真源 + +核心思想是：正式结论必须有唯一归属，不能让多个版本并行竞争。 + +在本仓库里，这被明确成： + +- 正式内容优先回写主文档 +- `specs/` 是过程工件和治理工件 +- `Archive` 是来源，不是正式结论 +- backend/frontend 负责实现，不负责定义正式规格 + +这对应的是经典的软件工程思想：**single source of truth**。 + +### 2.2 逐步求精 + +同一个需求，不在一开始就展开到代码细节，而是逐层收敛： + +1. 先确认到底要解决什么问题 +2. 再确认边界和约束 +3. 再确认要怎么拆 +4. 再进入实现和验证 + +这对应的是：**stepwise refinement**，也就是逐步求精。 + +### 2.3 需求到交付的可追溯性 + +每个阶段都要能回答两个问题： + +- 你这个结论是从哪里来的？ +- 你这个结果后来落到哪里去了？ + +所以它天然要求： + +- spec 能追到 source of truth +- plan 能追到 spec +- tasks 能追到 user story / requirement +- implementation / evidence 能追到 tasks +- 最终结论能回写正式文档和台账 + +这对应的是：**traceability**。 + +### 2.4 小步闭环，而不是大步推进 + +很多团队的问题，不是不会做，而是喜欢一次推进太多内容，导致： + +- 范围没锁住 +- 任务没拆清 +- 验证没前置 +- 回写没人做 + +`Speckit` 的做法是把系统构建看成多个连续闭环，而不是一个大瀑布。 + +这更接近：**iterative delivery** 和 **feedback loop**。 + +--- + +## 3. 它到底怎么通过一个个闭环构建系统 + +可以把 `Speckit` 理解成 6 个连续闭环。 + +前一个闭环的输出，是后一个闭环的输入。 + +### 闭环 1：范围闭环 + +目标：先回答“这次到底做什么，不做什么”。 + +输入： + +- 用户意图 +- 主文档 +- Archive 历史资料 +- 当前代码现状 + +输出： + +- `spec.md` +- 明确的纳入范围 +- 明确的排除范围 +- 明确的验收口径 + +闭环成功的标志： + +- 评审者只看 `spec.md` 就能判断是否超范围 +- 团队不会把“以后可能做”误当成“这轮必须做” + +这一步解决的是“方向漂移”。 + +### 闭环 2：决策闭环 + +目标：把范围内仍然模糊的关键问题收敛成可执行决策。 + +输入： + +- `spec.md` +- 现有设计文档 +- 冲突来源 +- 需要裁决的问题 + +输出： + +- `research.md` +- 一组关键决策和理由 + +闭环成功的标志： + +- 后续规划不再反复争论同一个问题 +- 每个重要选择都能说清“为什么这样定” + +这一步解决的是“大家都觉得自己理解对，但没有正式裁决”。 + +### 闭环 3：设计闭环 + +目标：把“需求”转成“可落地结构”。 + +输入： + +- `spec.md` +- `research.md` + +输出： + +- `plan.md` +- `data-model.md` +- `contracts/*` +- `quickstart.md` + +闭环成功的标志： + +- 已经知道涉及哪些文档、哪些仓、哪些接口、哪些数据对象 +- 已经知道最小验证动作是什么 +- 已经知道正式主文档后续该怎么回写 + +这一步解决的是“知道要做什么，但还不知道怎么组织”。 + +### 闭环 4：任务闭环 + +目标：把设计转成可分配、可执行、可检查的任务。 + +输入： + +- `plan.md` +- `data-model.md` +- `contracts/*` +- `quickstart.md` + +输出： + +- `tasks.md` + +闭环成功的标志： + +- 每个任务都能映射到具体文件、具体仓、具体验证动作 +- 每个 user story 都可以独立评审 +- 任务不是“继续完善一下”这种抽象话，而是明确动作 + +这一步解决的是“设计有了，但执行还是靠临场发挥”。 + +### 闭环 5：实现与验证闭环 + +目标：把任务变成实际改动，并证明改动有效。 + +输入： + +- `tasks.md` +- docs/backend/frontend 各 lane 的执行结果 + +输出： + +- 正式文档修改 +- 代码改动 +- 校验结果 +- evidence / final verdict + +闭环成功的标志： + +- 改动完成后有对应验证 +- 验证结果能追溯到具体基线 +- 不是“我本地看起来可以”，而是有可复核证据 + +这一步解决的是“做了，但没人能确定真的完成了什么”。 + +### 闭环 6：治理回写闭环 + +目标：把阶段结果沉淀回正式体系，而不是停留在聊天记录或临时分支里。 + +输入： + +- 已完成的文档和代码结果 +- 验证结果 +- feature 基线 + +输出： + +- 主文档回写 +- `01_Project_Progress.md` +- `03_Task_Checklist.md` +- 必要的 evidence 与最终结论 + +闭环成功的标志： + +- 别人不看聊天记录，也能知道当前状态 +- 后续 feature 可以直接站在当前结论上继续推进 + +这一步解决的是“这次做完了，但组织记忆没有留下来”。 + +--- + +## 4. 一个需求是怎么一步步长成系统的 + +可以把整个过程理解成下面这条链： + +```text +用户问题 +-> spec 锁范围 +-> research 锁关键决策 +-> plan 锁实施结构 +-> tasks 锁执行清单 +-> implementation 锁实际改动 +-> verification 锁完成证据 +-> ledger/main docs 锁组织记忆 +``` + +这条链最重要的地方在于： + +**每一步都不是为了“写文档”，而是为了减少下一步的不确定性。** + +举例： + +- `spec` 不是为了写需求书，而是为了防止做着做着变成另一个项目 +- `plan` 不是为了写方案书，而是为了让任务拆解有稳定骨架 +- `tasks` 不是为了列清单，而是为了让 lane 执行可分配、可验收 +- `verification` 不是为了走流程，而是为了把“我觉得好了”变成“证据表明好了” + +--- + +## 5. 为什么它适合复杂系统，而不只是适合写文档 + +因为复杂系统最怕的不是工作量大，而是下面这四种失控： + +1. 需求失控：边界不清，越做越大 +2. 结构失控：模块、接口、数据口径互相冲突 +3. 执行失控：任务拆不稳，协作互相阻塞 +4. 认知失控：做完后没人说得清当前状态 + +`Speckit` 的价值，就在于它把这四种失控分别放进不同闭环里处理： + +- `spec` 管需求失控 +- `plan` / `contracts` / `data-model` 管结构失控 +- `tasks` 管执行失控 +- `verification` / `ledger sync` 管认知失控 + +所以它不是“文档流程”，而是一个 **复杂系统治理流程**。 + +--- + +## 6. 在这个仓库里，Speckit 的真实落地方式 + +在 `water-workspace` 里，`Speckit` 不是独立于实现的平行世界，而是正式治理层。 + +职责边界是： + +- `water-docs`：负责正式 `spec/plan/tasks/evidence` 和主文档回写 +- `water-backend`：负责后端实现与后端验证 +- `water-frontend`：负责前端实现与前端验证 +- `tmux + worktree`：负责并行执行现场 + +也就是说： + +```text +Speckit 定义“应该做什么、如何验收” +lane 执行“具体怎么做出来” +water-docs 负责“最终正式结论落到哪里” +``` + +这就是为什么仓库里一直强调： + +- `.specify/` 只保留在 `water-docs` +- backend/frontend 不复制第二套 spec-kit +- 正式工件统一回到 `water-docs` + +--- + +## 7. 人最容易误解的几个点 + +### 误解 1：Speckit 就是先写文档再开发 + +不准确。 + +更准确的说法是：**先把决策和验收条件固定，再进入开发。** + +如果一个需求很小，完全可以不走完整流程。 + +### 误解 2：有了 spec，就等于已经设计好了 + +不对。 + +`spec` 主要回答“做什么”和“做到什么算完成”。 + +真正回答“怎么组织、怎么拆、怎么验证”的，是 `plan`、`data-model`、`contracts` 和 `tasks`。 + +### 误解 3：tasks 只是项目管理清单 + +不对。 + +`tasks` 在这里是执行接口，作用是把规格层结论翻译成 lane 可以直接消费的动作。 + +### 误解 4：验证是收尾动作 + +不对。 + +在 `Speckit` 里，验证条件应该从 `spec` 和 `plan` 阶段就开始定义，而不是等实现完才临时想。 + +--- + +## 8. 对新人最实用的理解方式 + +如果你不想一上来记所有命令，可以只记下面四句话： + +1. `spec`：先把边界锁住。 +2. `plan`：再把结构和依赖锁住。 +3. `tasks`：再把执行动作锁住。 +4. `verify + 回写`：最后把结果锁进正式系统。 + +把它翻成更口语的话就是： + +```text +先确认做什么 +再确认怎么做 +再确认谁去做 +最后确认做完没有，并把结论留下来 +``` + +这就是 `Speckit` 最朴素、也最重要的本质。 + +--- + +## 9. 一张总图 + +```text +用户需求 + ↓ +specify / clarify + 产出：范围、边界、验收口径 + 闭环：范围闭环 + ↓ +plan + 产出：方案、决策、模型、合同、最小验证 + 闭环：决策闭环 + 设计闭环 + ↓ +tasks + 产出：可执行任务、lane 映射、独立验收切片 + 闭环：任务闭环 + ↓ +implement / verify + 产出：代码、文档、验证证据 + 闭环：实现与验证闭环 + ↓ +ledger sync / main docs update + 产出：正式结论、项目进度、任务状态、基线 + 闭环：治理回写闭环 +``` + +--- + +## 10. 推荐给团队的教学方式 + +如果你要拿这套流程教别人，建议不要从命令开始讲，而是按下面顺序讲： + +1. 先讲为什么团队会失控：范围、结构、执行、认知四种失控。 +2. 再讲 `Speckit` 用哪些闭环分别处理这四种失控。 +3. 再讲 `spec -> plan -> tasks -> verify -> 回写` 的工件链。 +4. 最后才讲仓库里具体怎么落地到 `water-docs`、`water-backend`、`water-frontend`。 + +这样新人先理解“为什么”，再理解“怎么做”，吸收速度会快很多。 + +--- + +## 11. 与本仓库口径对应的参考来源 + +本说明基于以下仓内材料整理： + +- `water-docs/.specify/memory/constitution.md` +- `water-docs/.specify/templates/spec-template.md` +- `water-docs/.specify/templates/plan-template.md` +- `water-docs/.specify/templates/tasks-template.md` +- `docs/TMUX_WORKTREE_TEAM_WORKFLOW.md` +- `water-docs/AGENTS.md` +- 现有 `water-docs/specs/*` 工件样例 + +如果这些基础材料后续更新，本教学文档也应同步修订。 + +--- + +## 12. Speckit 与工程控制论的关系 + +如果从方法论上看，`Speckit` 和钱学森提出的工程控制论确实很接近。 + +但要说得准确一些，不是“完全一样”，而是： + +**`Speckit` 可以理解为一种面向软件研发治理的工程控制论实践。** + +### 12.1 相似之处 + +两者都关心同一件事： + +**怎样让一个复杂系统朝目标稳定演化，而不是边做边失控。** + +在 `Speckit` 里，这种相似性主要体现在下面几项。 + +#### 1. 都先定义目标状态 + +工程控制论强调，控制之前必须先明确目标。 + +`Speckit` 里对应的是： + +- `spec` 定义目标 +- `spec` 定义边界 +- `spec` 定义完成条件 + +也就是说，系统不是“先干起来再说”，而是先定义希望到达什么状态。 + +#### 2. 都强调观测当前状态 + +控制不能脱离观测。 + +`Speckit` 在进入规划和实施前，都会先看： + +- 主文档现状 +- Archive 来源 +- backend / frontend 当前实现 +- 验证结果 +- 台账状态 + +这相当于先观察系统当前状态，而不是只看目标。 + +#### 3. 都依赖偏差分析 + +控制的核心不是“下命令”，而是发现偏差、修正偏差。 + +`Speckit` 实际上一直在比较： + +- 目标和现状是否一致 +- 文档和代码是否一致 +- 接口、数据、设计之间是否一致 +- 任务完成状态和验收标准是否一致 + +只要不一致，就说明存在偏差，需要继续修正。 + +#### 4. 都通过反馈回路持续校正 + +这和传统“一路写到最后再看结果”的思路不同。 + +`Speckit` 的典型反馈方式是： + +- 范围不清，回到 `spec` +- 关键决策冲突，回到 `research` 或 `plan` +- 设计与接口不一致，回到 `contracts` / `data-model` +- 验证不过，回到任务或实现 +- 结论未沉淀，回到主文档和台账 + +这本质上就是反馈控制。 + +#### 5. 都有分层控制结构 + +工程控制论往往不是单层控制，而是多层协同。 + +`Speckit` 也一样： + +- `spec` 控目标层 +- `plan` 控结构层 +- `tasks` 控执行层 +- `verify` 控结果层 +- `ledger sync` 控组织记忆层 + +每一层控制的对象不同，但共同服务于整体稳定性。 + +### 12.2 不同之处 + +两者也有明显区别。 + +钱学森的工程控制论，更多研究的是： + +- 物理工程系统 +- 工业过程 +- 技术系统运行中的控制规律 + +而 `Speckit` 控制的不是设备本身，而是： + +- 需求如何收敛 +- 设计如何对齐 +- 任务如何拆解 +- 实现如何验证 +- 结论如何沉淀 + +所以它控制的是： + +**研发过程和交付过程。** + +不是狭义的设备控制，而是过程治理。 + +### 12.3 为什么这个类比有价值 + +把 `Speckit` 理解成“工程控制系统”，会比把它理解成“文档流程”更准确。 + +因为这样你会自然意识到： + +1. `spec` 不是装饰品，而是目标设定器。 +2. `plan` 不是空洞方案，而是结构控制器。 +3. `tasks` 不是待办清单，而是执行调度器。 +4. `verify` 不是收尾动作，而是反馈传感器。 +5. `ledger` 不是行政记录，而是组织状态记忆。 + +这样一来，团队就不会把每个工件当成独立文件，而会把它们看成控制链上的不同节点。 + +### 12.4 一个更贴切的理解 + +可以把 `Speckit` 理解成下面这个模型： + +```text +目标设定 +-> 状态观测 +-> 偏差识别 +-> 方案校正 +-> 执行调节 +-> 结果验证 +-> 组织回写 +-> 下一轮控制 +``` + +这条链本身就是一个闭环控制系统。 + +而 `Speckit` 的价值，正是在于它把软件研发从“经验驱动、口头协调、事后补救”，变成了“目标明确、过程可观测、偏差可修正、结果可追溯”的受控过程。 + +### 12.5 教学时可以怎么讲 + +如果要对团队解释这层关系，建议直接用这句话： + +**`Speckit` 不是让大家多写文档，而是用工程控制论的思路，把复杂研发过程变成一个有目标、有反馈、有校正的闭环系统。** + +这句话通常比单纯讲命令和模板更容易让人真正理解它的价值。 + +--- + +## 13. 小闭环是怎么组织成大闭环的 + +这是理解 `Speckit` 最关键的一步。 + +很多人会以为： + +- `spec` 是一个闭环 +- `plan` 是一个闭环 +- `tasks` 是一个闭环 +- `implement` 是一个闭环 + +然后这些闭环只是顺序排开。 + +其实不是。 + +更准确的理解是： + +**小闭环是分层嵌套的，前一个闭环的输出会变成后一个闭环的控制输入；很多 feature 闭环继续累积，才会形成系统级大闭环。** + +### 13.1 先看四层结构 + +在这个工作区里，可以把闭环分成四层。 + +#### 第一层：动作闭环 + +这是最小闭环，通常是一组非常具体的动作： + +```text +修改 +-> 校验 +-> 修正 +-> 记录结果 +``` + +例如： + +- 改 `12_REV_Detailed.md` +- 执行 `make validate-file` +- 如有链接变更再跑 `make check-links` +- 结果写入 quickstart 或最终结论 + +这一层解决的是“这一个动作到底有没有做实”。 + +#### 第二层：用户故事闭环 + +这是把多个动作闭环拼成一个可以独立评审的能力片段： + +```text +一个用户故事 +-> 若干文档动作 +-> 若干代码动作 +-> 独立验证 +-> 形成局部结论 +``` + +这一层解决的是“这一个业务片段是否已经独立成立”。 + +#### 第三层：feature 闭环 + +这是把多个用户故事闭环拼成一个 feature 的完成链： + +```text +spec +-> plan +-> tasks +-> implement +-> verify +-> ledger sync +``` + +这一层解决的是“这个 feature 是否已经成为系统中的稳定能力单元”。 + +#### 第四层：系统交付闭环 + +这是最大的闭环： + +```text +需求池 +-> feature 闭环 1 +-> feature 闭环 2 +-> feature 闭环 3 +-> 主文档与台账持续更新 +-> 系统能力版图逐步收敛 +``` + +这一层解决的是“整个系统是否在有秩序地长出来”。 + +### 13.2 最重要的一句话 + +可以把这四层关系记成一句话： + +**动作闭环保证局部真实，故事闭环保证片段成立，feature 闭环保证能力落地，系统闭环保证整体演进。** + +--- + +## 14. 用你当前系统做案例讲解 + +下面直接用你仓库里的 `REV-004` 和 `REV-005` 来讲。 + +### 14.1 系统目标不是一次性实现，而是逐块实现 + +你现在这个营收系统，不是靠“一次大开发”完成的，而是靠多个 feature 闭环逐步长成。 + +从当前仓库可以看到几个典型能力块： + +- `REV-004`：账务处理一期 +- `REV-005`：发票业务流 +- `REV-006`：催缴与通知 +- `REV-007`：统计分析 + +这四个 feature 不是平行孤岛，而是在共同补齐营收系统的核心业务版图。 + +也就是说，系统级大闭环大致是： + +```text +营收系统目标 +-> 一个个 feature 进入 Speckit +-> 每个 feature 形成可控闭环 +-> 每轮闭环结果回写主文档和台账 +-> 系统整体能力逐步成形 +``` + +### 14.2 先看 `REV-004`：它在补什么系统能力 + +`REV-004` 的本质，不是“写一份账务说明”，而是在给系统补一块能力底座： + +- 明确账务处理一期边界 +- 统一 `IF-REV-007` +- 统一留痕、原始依据、结果状态 +- 再按场景拆到账务调整、退款、冲正、坏账申请 + +这意味着 `REV-004` 的价值不是单一功能点，而是： + +**先把账务处理域里的共性控制骨架搭起来。** + +如果这块不闭合，后面的退款、冲正、坏账等就会各自长成不同口径。 + +所以 `REV-004` 这个 feature 闭环，本质上是在给系统建立： + +- 账务场景边界 +- 账务接口边界 +- 账务留痕边界 +- 账务状态边界 + +这是一块“平台型能力闭环”。 + +### 14.3 再看 `REV-005`：它在补什么系统能力 + +`REV-005` 的计划更接近实现闭环。 + +从 [002-rev005-invoice-flow/plan.md](/Volumes/Dpan/github/water-workspace/water-docs/specs/002-rev005-invoice-flow/plan.md) 可以看出，它要补的是： + +- 后台发票申请 +- 后台单笔/批量开票 +- `SYS-008` 异步申请与查询兜底 +- 发票结果回写 +- 账单与发票关联 +- 客户侧查询/下载/推送 + +这说明 `REV-005` 不是一个接口修补，而是在补一个完整业务结果链： + +```text +收费账单 +-> 发票申请 +-> 外部发票服务协同 +-> 查询补偿 +-> 结果回写 +-> 客户消费结果 +``` + +这是一块“流程型能力闭环”。 + +### 14.4 为什么 `REV-004` 和 `REV-005` 能拼成更大的闭环 + +因为它们不是随机 feature，而是在系统业务链上前后衔接。 + +可以这样理解： + +- `REV-004` 负责账务处理域中的调整、退款、冲正、坏账等控制逻辑 +- `REV-005` 负责收费后发票结果的业务闭环 + +两者共同服务的是“营收处理全过程”的可控性。 + +举个直白例子： + +如果系统里发生退款或冲正，账务状态一定会影响后续发票状态、发票可用性、结果展示和客户消费体验。 + +所以： + +- 没有 `REV-004`，`REV-005` 可能会缺失上游账务一致性约束 +- 没有 `REV-005`，`REV-004` 的结果又无法完整延伸到发票交付链 + +它们拼起来，才更接近真实的营收业务闭环。 + +### 14.5 从小闭环拼成大闭环的真实过程 + +下面用更接近执行的方式来描述。 + +#### 第一步：先闭合 `REV-004` 内部的小闭环 + +例如先闭这些： + +1. 范围闭环 +2. `IF-REV-007` 统一合同闭环 +3. 留痕与结果状态统一闭环 +4. 退款/冲正原交易校验闭环 +5. 正式文档与执行手册回写闭环 + +这些闭完后，`REV-004` 才算从“讨论账务”变成“系统已有一套稳定账务处理骨架”。 + +#### 第二步：再闭合 `REV-005` 内部的小闭环 + +例如继续闭这些： + +1. 发票申请闭环 +2. `SYS-008` 查询兜底闭环 +3. 发票结果回写闭环 +4. 账单-发票关联闭环 +5. 客户侧查询/下载/推送闭环 +6. backend 编译与文档回写闭环 + +这些闭完后，`REV-005` 才算从“发票规划”变成“系统已有一条稳定发票结果链”。 + +#### 第三步：再把 feature 闭环在系统层面接起来 + +这一步不是再写一份大而全的总方案，而是靠以下机制自然接起来： + +- 主文档持续回写 +- 接口设计持续统一 +- 数据库承接口径持续统一 +- 项目进度与任务台账持续记录 +- 新 feature 继续站在前一轮闭环结论上推进 + +这就形成了系统级大闭环： + +```text +账务闭环稳定 +-> 发票闭环接入 +-> 通知闭环接入 +-> 统计闭环接入 +-> 各能力通过主文档、接口、数据、台账不断统一 +-> 营收系统形成整体受控结构 +``` + +### 14.6 为什么主文档和台账这么重要 + +很多团队的大闭环之所以拼不起来，不是因为他们没有做 feature，而是因为： + +- 每个 feature 的结论只留在聊天记录里 +- 代码改了但主文档没回写 +- 台账不更新，没人知道当前真实状态 +- 下一个 feature 启动时，又重新猜一遍现状 + +这样 feature 虽然一个个做了，但系统级大闭环拼不起来。 + +而你这个仓库里一直强调： + +- 主文档单一真源 +- 重要结果回写 `01_Project_Progress.md` +- 任务闭环更新 `03_Task_Checklist.md` + +它的真正作用就是： + +**让上一个 feature 的输出，成为下一个 feature 的稳定输入。** + +这正是大闭环成立的关键条件。 + +--- + +## 15. 一个更贴近实现目标的系统级示意图 + +如果你的最终目标是“把营收系统真实实现出来”，可以把当前过程理解成下面这张图： + +```text +系统目标：形成可交付、可实现、可验证的营收系统 + ↓ +Feature A：REV-004 账务处理一期 + - 闭合范围 + - 闭合接口 + - 闭合留痕与状态 + - 闭合账务场景控制骨架 + ↓ +Feature B：REV-005 发票业务流 + - 闭合申请 + - 闭合查询兜底 + - 闭合结果回写 + - 闭合客户消费链路 + ↓ +Feature C：REV-006 催缴与通知 + - 闭合任务生成 + - 闭合消息协同 + - 闭合结果回写 + ↓ +Feature D：REV-007 统计分析 + - 闭合统计口径 + - 闭合指标来源 + - 闭合输出与追溯 + ↓ +主文档 / 接口设计 / 数据库设计 / 台账 / evidence 持续统一 + ↓ +系统级大闭环：各业务域能力逐步收敛成一个整体系统 +``` + +这张图里最重要的是： + +不是先有“大闭环设计”，再去硬塞小闭环。 + +而是每个 feature 先形成稳定能力块，再通过统一主文档、统一接口、统一数据库口径、统一台账回写，把这些能力块拼成系统级闭环。 + +--- + +## 16. 给当前实施目标的直接建议 + +如果你现在的目标是“以系统实现为目的继续推进”，那最实用的策略不是问“什么时候整个系统才算闭环”，而是每一轮都问下面三个问题： + +1. 当前这个 feature，补的是系统里的哪一块能力？ +2. 这块能力内部还有哪些小闭环没闭？ +3. 这轮闭合后的结果，会通过哪些主文档、接口、数据和台账，变成下一个 feature 的输入？ + +只要这三个问题一直答得清楚，系统级大闭环就会自然长出来。 + +反过来说，如果这三个问题答不清楚，就算团队一直在干活，也很容易变成“局部热闹，整体失控”。 diff --git a/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md b/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md new file mode 100644 index 0000000..99a59ea --- /dev/null +++ b/docs/guides/SYSTEM_CAPABILITY_CLOSURE_MAP.md @@ -0,0 +1,335 @@ +# 营收系统能力地图与闭环进度图 + +## 1. 文档目的 + +本文用于回答三个实际问题： + +1. 当前 `REV-004`、`REV-005`、`REV-006`、`REV-007` 分别在补系统的哪一块能力？ +2. 这些 feature 当前各自走到了 `spec / plan / tasks / implement / verify / 回写` 的哪一步？ +3. 如果目标是“继续把系统实现出来”，下一轮最应该优先闭哪一块？ + +这份图不是替代 `specs/`，而是把多个 feature 的局部闭环放到同一张系统视角里，帮助统一判断整体推进顺序。 + +--- + +## 2. 一张总图 + +```text +福建水务营收系统 + ↓ +收费与账单主链 + - REV-002 开账计费与账单生成 + - REV-003 收费核销处理 + ↓ +账后控制与结果链 + - REV-004 账务处理一期 + - REV-005 发票业务流 + - REV-006 催缴与通知 + - REV-007 营收统计查询 + ↓ +主文档 / 接口设计 / 数据库设计 / 台账 / evidence 持续统一 + ↓ +系统级大闭环 +``` + +这条链的意思不是“后面的 feature 必须等前面的全做完才能动”，而是： + +- `REV-004`、`REV-005`、`REV-006`、`REV-007` 都属于收费后处理与经营结果链条 +- 它们既可以分阶段推进，也必须最终回到统一的主文档、接口、数据库和治理台账上 + +--- + +## 3. 当前能力地图 + +### 3.1 feature 与系统能力的对应关系 + +| Feature | 系统能力类型 | 核心目标 | 当前角色 | +| --- | --- | --- | --- | +| `REV-004` | 账后控制能力 | 统一账务调整、退款、冲正、坏账申请的一期边界、接口、留痕和状态口径 | 底座型闭环 | +| `REV-005` | 发票结果链能力 | 打通发票申请、外部协同、查询兜底、结果回写与客户侧消费 | 流程型闭环 | +| `REV-006` | 催缴协同能力 | 打通催缴对象生成、通知协同、结果回写、停复水边界和历史查询口径 | 协同型闭环 | +| `REV-007` | 经营观察能力 | 明确统计主题、指标口径、查询维度、接口边界和数据承接口径 | 观察型闭环 | + +### 3.2 这四块能力在业务链上的位置 + +```text +账单 / 收费结果 + ├─ REV-004：账后调整与异常处理 + ├─ REV-005：发票申请、开具、回写、客户消费 + ├─ REV-006：欠费提醒、通知协同、结果承接 + └─ REV-007：经营统计、收费统计、欠费统计、渠道分析 +``` + +因此这四个 feature 不是平级替代关系，而是共同围绕“收费后的业务控制、结果消费、消息协同、经营观察”形成系统后半段。 + +--- + +## 4. 闭环进度图 + +## 4.1 统一阶段定义 + +为了避免“已经做了很多”但说不清做到哪，下面统一用六段来标识每个 feature 的阶段： + +1. `spec`：范围和验收口径已锁定 +2. `plan`：结构、依赖、接口/数据设计已组织 +3. `tasks`：任务拆解已能直接指导执行 +4. `implement`：文档或代码已进入实际落地 +5. `verify`：已有验证证据或待补证据边界已明确 +6. `ledger sync`：主文档、进度台账、任务台账已统一回写 + +## 4.2 当前 feature 闭环进度 + +| Feature | spec | plan | tasks | implement | verify | ledger sync | 当前判断 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `REV-004` | 已完成 | 已完成 | 已完成 | 文档 implement 已完成 | 文档校验已完成 | 已完成 | 文档闭环完成，代码闭环未启动 | +| `REV-005` | 已完成 | 已完成 | 已完成 | 已进入 backend implement 并完成 US1~US4 | Verification Pending | 已完成 | 实现态闭环基本完成，运行态证据待补 | +| `REV-006` | 已完成 | 已完成 | 已完成 | implement 阶段文档收口已完成 | 文档校验已完成 | 已完成 | 治理闭环完成，backend 仍未见明确实现 | +| `REV-007` | 已完成 | 已完成 | 已完成 | implement 阶段正式文档收口推进中 | 文档校验与治理校验为主 | 已完成 | 设计闭环已建立，代码入口未见明确实现 | + +### 4.3 用符号再看一遍 + +```text +REV-004: spec ✓ -> plan ✓ -> tasks ✓ -> implement(文档) ✓ -> verify(文档) ✓ -> ledger ✓ +REV-005: spec ✓ -> plan ✓ -> tasks ✓ -> implement(代码+文档) ✓ -> verify(运行态待补) △ -> ledger ✓ +REV-006: spec ✓ -> plan ✓ -> tasks ✓ -> implement(文档) ✓ -> verify(文档) ✓ -> ledger ✓ +REV-007: spec ✓ -> plan ✓ -> tasks ✓ -> implement(文档) ✓ -> verify(设计/治理) ✓ -> ledger ✓ +``` + +最关键的区别是： + +- `REV-004 / REV-006 / REV-007` 当前主要是“文档与治理闭环” +- `REV-005` 已经进入“代码实现闭环” + +这决定了后续系统推进的优先级不能一刀切。 + +--- + +## 5. 依赖关系图 + +## 5.1 业务依赖 + +```text +REV-002/REV-003 产出账单与收费结果 + ↓ +REV-004 处理账后调整、退款、冲正、坏账 + ↓ +REV-005 消费收费/账单结果形成发票闭环 + ↓ +REV-006 基于欠费/催缴对象形成通知协同闭环 + ↓ +REV-007 对账单、收费、欠费、渠道、客户结果做统计观察 +``` + +## 5.2 方法依赖 + +```text +REV-004 先统一账务状态、留痕、原交易校验口径 + ↓ +有助于 REV-005 / REV-006 / REV-007 在状态、日志、追溯上保持一致 +``` + +因此： + +- `REV-004` 更像后续 feature 的控制骨架 +- `REV-005` 更像当前最接近真实交付的结果链 +- `REV-006` 更像待转实现的协同链 +- `REV-007` 更像待转实现的观察链 + +--- + +## 6. 从“小闭环”到“系统大闭环”的拼接方式 + +## 6.1 feature 内部怎么闭 + +每个 feature 先把自己内部的小闭环闭起来。 + +### `REV-004` + +- 范围闭环：五类场景收敛 +- 合同闭环：`IF-REV-007` +- 共性能力闭环：留痕、原始依据、结果状态、审批边界 +- 治理闭环：执行手册、项目进度、任务清单回写 + +### `REV-005` + +- 申请闭环：后台发票申请与校验 +- 协同闭环：`SYS-008` 异步申请与查询兜底 +- 回写闭环：发票状态、账单关联、客户侧消费 +- 二期入口闭环：作废与红冲最小入口 +- 验证闭环：实现态证据已补，运行态样本待补 + +### `REV-006` + +- 设计闭环：催缴对象、通知事件、结果状态四态、停复水边界 +- 接口闭环：`IF-REV-013` 与 `IF-EXT-008` +- 治理闭环：implement 阶段文档收口与台账回写 + +### `REV-007` + +- 设计闭环：统计主题、维度、指标与排除项 +- 接口闭环：`IF-REV-010` +- 数据闭环：聚合来源与承接口径 +- 治理闭环：实现评估与正式台账回写 + +## 6.2 feature 之间怎么拼 + +系统大闭环不是再额外建一个“超级文档”，而是依靠四类统一机制把它们接起来： + +1. 主文档统一 +所有结论最终回到 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` + +2. 台账统一 +重要动作回写 `01_Project_Progress.md`、`03_Task_Checklist.md` + +3. 接口统一 +各 feature 都落到同一套 `IF-*` 体系中 + +4. 数据承接口径统一 +不让每个 feature 各自发明自己的状态、日志、承接模型 + +这四类统一机制的作用就是： + +**让上一个闭环的输出，自动成为下一个闭环的稳定输入。** + +--- + +## 7. 当前系统视角下的真实判断 + +### 7.1 哪些 feature 已经是“稳定能力块” + +- `REV-004`：是，文档与治理层面已稳定 +- `REV-005`：是，已形成实现态稳定能力块 +- `REV-006`：是，设计与治理层面已稳定 +- `REV-007`：是，设计与治理层面已稳定 + +### 7.2 哪些 feature 还不是“完整业务闭环” + +- `REV-004`：还不是完整实现闭环，因为代码侧尚未启动 +- `REV-006`：还不是完整实现闭环，因为 backend 仍未见明确实现 +- `REV-007`：还不是完整实现闭环，因为代码入口仍未见明确实现 +- `REV-005`：最接近完整业务闭环，但仍缺运行态样本、联调统计与物理 DDL 风险闭合 + +### 7.3 当前系统最大的断点在哪里 + +当前最大的断点不是设计断点，而是： + +**设计闭环与实现闭环之间的转换断点。** + +换句话说： + +- `REV-006` 和 `REV-007` 都已经具备进入实现的前置条件 +- 但还没有真正转成 backend 可验证的实现链 + +这说明现在系统推进的主矛盾，已经不是“要不要继续补文档”，而是： + +**哪一块设计基线应当最先转成实现闭环。** + +--- + +## 8. 面向“系统实现”为目标的优先级建议 + +## 8.1 第一优先级：完成 `REV-005` 的 verify 收口 + +原因： + +- 它是四个 feature 里唯一已经深入到 backend implement 的 +- 再补少量运行态证据，就能形成最完整的一条真实业务闭环 +- 这会给后续 feature 提供一个“设计如何转实现、实现如何转验证”的标准样板 + +建议优先补： + +- 运行态联调样本 +- `T055`、`T060 ~ T063` 对应的验证记录 +- `biz_invoice` 物理 DDL / migration 风险的最终判断 + +## 8.2 第二优先级：启动 `REV-006` 的 backend 最小实现闭环 + +原因： + +- `REV-006` 已完成 `spec -> plan -> tasks -> implement(文档)` 全链条 +- 它适合作为“从设计闭环转实现闭环”的下一块 +- 相比 `REV-007`，它更直接落在业务控制与消息协同链上，更贴近真实业务运行 + +最小切入建议： + +- 先做催缴对象生成 +- 再做通知事件触发 +- 再做结果回写 +- 最后做停复水边界联动 + +## 8.3 第三优先级：评估 `REV-004` 二期还是 `REV-007` 实现入口 + +这一步要看你的系统目标偏哪边： + +- 如果更偏“业务控制完善”，优先 `REV-004` +- 如果更偏“经营观察与管理看板”，优先 `REV-007` + +当前从系统运行价值看，我更建议： + +**`REV-004` 优先于 `REV-007`。** + +原因是： + +- `REV-004` 会影响退款、冲正、坏账、账务状态与留痕一致性 +- 这是多个后续流程共享的控制骨架 +- `REV-007` 的价值也高，但它更偏“看清系统”，不是“先让系统可控” + +--- + +## 9. 一个可以直接执行的推进顺序 + +如果以“尽快把系统大闭环往前推”为目标，建议按下面顺序推进： + +```text +第一步：补完 REV-005 verify 收口 + 目标：形成第一条最完整的实现态业务闭环 + +第二步：启动 REV-006 backend 最小实现 + 目标：把设计闭环成功转成协同实现闭环 + +第三步：启动 REV-004 二期实现 + 目标：把账务控制骨架从文档闭环转成实现闭环 + +第四步：启动 REV-007 最小查询实现 + 目标：让经营观察能力从“设计已定义”进入“查询可验证” +``` + +这条顺序的逻辑是： + +- 先拿 `REV-005` 固化“实现闭环样板” +- 再拿 `REV-006` 证明“设计闭环可转实现闭环” +- 再拿 `REV-004` 固化系统控制骨架 +- 最后拿 `REV-007` 打开经营观察能力 + +--- + +## 10. 结论 + +当前仓库已经不是“还在摸索 feature 是什么”，而是已经形成了四块明确的系统能力板块。 + +真实状态可以概括为： + +- `REV-004`：账务控制骨架已闭合，待转实现 +- `REV-005`：实现链最完整，待补运行态证据 +- `REV-006`：协同设计已闭合，待转实现 +- `REV-007`：统计设计已闭合，待转实现 + +因此，从系统大闭环视角看，下一阶段最重要的事情不是继续横向铺更多 spec，而是： + +**把已经完成设计闭环的能力块，逐步转成实现闭环。** + +这就是当前从“文档治理阶段”走向“系统实现阶段”的真正分水岭。 + +--- + +## 11. 参考依据 + +本文基于以下仓内工件整理： + +- `specs/001-rev004-accounting/` +- `specs/002-rev005-invoice-flow/` +- `specs/003-rev006-reminder-event-design/` +- `specs/004-rev007-revenue-statistics-design/` +- `docs/design/00_Management/01_Project_Progress.md` +- `docs/design/00_Management/03_Task_Checklist.md` +- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` diff --git a/output/08_Integrated_Deployment_Design_PlanB_含图表.docx b/output/08_Integrated_Deployment_Design_PlanB_含图表.docx new file mode 100644 index 0000000..c2fa72e Binary files /dev/null and b/output/08_Integrated_Deployment_Design_PlanB_含图表.docx differ diff --git a/output/08_planb_network.drawio b/output/08_planb_network.drawio new file mode 100644 index 0000000..f807187 --- /dev/null +++ b/output/08_planb_network.drawio @@ -0,0 +1,419 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/output/08_planb_network_engineering_canvas.html b/output/08_planb_network_engineering_canvas.html new file mode 100644 index 0000000..143a31c --- /dev/null +++ b/output/08_planb_network_engineering_canvas.html @@ -0,0 +1,74 @@ + + + + + + PlanB Network Security Zones + + + +

福建水务营收系统网络安全域图

+

按“互联网区（DMZ）/ 非互联网区”两大安全域重绘，仅保留应用系统相关对象。防火墙与路由器仅做抽象表达。

+
+ +
+ + + diff --git a/output/diagrams/planb_network_links.png b/output/diagrams/planb_network_links.png new file mode 100644 index 0000000..3b98d7e Binary files /dev/null and b/output/diagrams/planb_network_links.png differ diff --git a/output/diagrams/planb_network_zones.png b/output/diagrams/planb_network_zones.png new file mode 100644 index 0000000..55fbc8c Binary files /dev/null and b/output/diagrams/planb_network_zones.png differ diff --git a/output/diagrams_variants/planb_links_lr_balanced.png b/output/diagrams_variants/planb_links_lr_balanced.png new file mode 100644 index 0000000..53084c8 Binary files /dev/null and b/output/diagrams_variants/planb_links_lr_balanced.png differ diff --git a/output/diagrams_variants/planb_links_lr_compact.png b/output/diagrams_variants/planb_links_lr_compact.png new file mode 100644 index 0000000..ecb9f9f Binary files /dev/null and b/output/diagrams_variants/planb_links_lr_compact.png differ diff --git a/output/diagrams_variants/planb_links_tb_balanced.png b/output/diagrams_variants/planb_links_tb_balanced.png new file mode 100644 index 0000000..4d7e036 Binary files /dev/null and b/output/diagrams_variants/planb_links_tb_balanced.png differ diff --git a/output/diagrams_variants/planb_links_tb_compact.png b/output/diagrams_variants/planb_links_tb_compact.png new file mode 100644 index 0000000..9387464 Binary files /dev/null and b/output/diagrams_variants/planb_links_tb_compact.png differ diff --git a/scripts/api-tools/validate-all.js b/scripts/api-tools/validate-all.js new file mode 100644 index 0000000..79ce6f0 --- /dev/null +++ b/scripts/api-tools/validate-all.js @@ -0,0 +1,285 @@ +#!/usr/bin/env node + +const fs = require('fs'); +const path = require('path'); +const YAML = require('js-yaml'); +const { glob } = require('glob'); + +class OpenAPIValidator { + constructor() { + this.errors = []; + this.warnings = []; + this.stats = { + totalFiles: 0, + validFiles: 0, + invalidFiles: 0 + }; + } + + // 验证YAML文件格式 + validateYAMLSyntax(filePath) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + YAML.load(content); + return { valid: true }; + } catch (error) { + return { + valid: false, + error: `YAML语法错误: ${error.message}` + }; + } + } + + // 验证OpenAPI规范 + validateOpenAPISpec(filePath) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + const doc = YAML.load(content); + + // 基本结构检查 + if (filePath.endsWith('openapi.yaml')) { + return this.validateMainSpec(doc); + } else if (filePath.includes('/schemas/')) { + return this.validateSchemas(doc); + } else if (filePath.includes('/paths/')) { + return this.validatePaths(doc); + } else if (filePath.includes('/components/')) { + return this.validateComponents(doc); + } + + return { valid: true }; + } catch (error) { + return { + valid: false, + error: `规范验证错误: ${error.message}` + }; + } + } + + // 验证主文档 + validateMainSpec(doc) { + const errors = []; + + if (!doc.openapi) { + errors.push('缺少 openapi 版本号'); + } else if (!doc.openapi.startsWith('3.0')) { + errors.push('openapi 版本应为 3.0.x'); + } + + if (!doc.info) { + errors.push('缺少 info 部分'); + } else { + if (!doc.info.title) errors.push('缺少 info.title'); + if (!doc.info.version) errors.push('缺少 info.version'); + } + + if (!doc.paths) { + errors.push('缺少 paths 部分'); + } + + return { + valid: errors.length === 0, + errors: errors + }; + } + + // 验证数据模型 + validateSchemas(doc) { + const errors = []; + + for (const [name, schema] of Object.entries(doc)) { + if (typeof schema !== 'object') continue; + + // 检查必要字段 + if (!schema.type && !schema.$ref && !schema.allOf && !schema.oneOf && !schema.anyOf) { + errors.push(`模型 ${name} 缺少 type 或引用定义`); + } + + // 检查描述 + if (schema.type === 'object' && schema.properties) { + for (const [propName, prop] of Object.entries(schema.properties)) { + if (!prop.description) { + errors.push(`模型 ${name}.${propName} 缺少描述`); + } + } + } + } + + return { + valid: errors.length === 0, + errors: errors + }; + } + + // 验证路径定义 + validatePaths(doc) { + const errors = []; + + for (const [pathName, pathItem] of Object.entries(doc)) { + if (typeof pathItem !== 'object') continue; + + for (const [method, operation] of Object.entries(pathItem)) { + if (!['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(method)) { + continue; + } + + // 检查必要字段 + if (!operation.tags) { + errors.push(`路径 ${pathName}.${method} 缺少 tags`); + } + if (!operation.summary) { + errors.push(`路径 ${pathName}.${method} 缺少 summary`); + } + if (!operation.description) { + errors.push(`路径 ${pathName}.${method} 缺少 description`); + } + if (!operation.operationId) { + errors.push(`路径 ${pathName}.${method} 缺少 operationId`); + } + if (!operation.responses) { + errors.push(`路径 ${pathName}.${method} 缺少 responses`); + } + } + } + + return { + valid: errors.length === 0, + errors: errors + }; + } + + // 验证组件定义 + validateComponents(doc) { + const errors = []; + + // 基本组件结构检查 + for (const [name, component] of Object.entries(doc)) { + if (typeof component !== 'object') continue; + + // 检查是否有必要的属性 + if (!component.description && !component.$ref) { + errors.push(`组件 ${name} 建议添加描述`); + } + } + + return { + valid: errors.length === 0, + errors: errors + }; + } + + // 验证单个文件 + async validateFile(filePath) { + console.log(`验证文件: ${filePath}`); + + this.stats.totalFiles++; + + // YAML语法验证 + const syntaxResult = this.validateYAMLSyntax(filePath); + if (!syntaxResult.valid) { + this.errors.push(`${filePath}: ${syntaxResult.error}`); + this.stats.invalidFiles++; + return false; + } + + // OpenAPI规范验证 + const specResult = this.validateOpenAPISpec(filePath); + if (!specResult.valid) { + this.stats.invalidFiles++; + if (specResult.errors) { + specResult.errors.forEach(error => { + this.errors.push(`${filePath}: ${error}`); + }); + } else { + this.errors.push(`${filePath}: ${specResult.error}`); + } + return false; + } + + this.stats.validFiles++; + return true; + } + + // 验证所有文档文件 + async validateAll() { + console.log('🔍 开始验证 OpenAPI 文档...\n'); + + try { + // 查找所有YAML文件 + const yamlFiles = await glob('docs/**/*.yaml', { + cwd: process.cwd(), + absolute: true + }); + + if (yamlFiles.length === 0) { + console.log('⚠️ 未找到任何 YAML 文件'); + return false; + } + + console.log(`找到 ${yamlFiles.length} 个 YAML 文件\n`); + + // 验证每个文件 + for (const file of yamlFiles) { + await this.validateFile(file); + } + + return this.generateReport(); + + } catch (error) { + console.error('验证过程中出现错误:', error); + return false; + } + } + + // 生成验证报告 + generateReport() { + console.log('\n📊 验证报告'); + console.log('='.repeat(50)); + console.log(`总文件数: ${this.stats.totalFiles}`); + console.log(`有效文件: ${this.stats.validFiles}`); + console.log(`无效文件: ${this.stats.invalidFiles}`); + + if (this.errors.length > 0) { + console.log('\n❌ 发现的错误:'); + this.errors.forEach((error, index) => { + console.log(`${index + 1}. ${error}`); + }); + } + + if (this.warnings.length > 0) { + console.log('\n⚠️ 警告信息:'); + this.warnings.forEach((warning, index) => { + console.log(`${index + 1}. ${warning}`); + }); + } + + const isValid = this.errors.length === 0; + + if (isValid) { + console.log('\n✅ 所有文档验证通过！'); + } else { + console.log('\n❌ 文档验证失败，请修复上述错误。'); + } + + return isValid; + } +} + +// 主执行函数 +async function main() { + const validator = new OpenAPIValidator(); + const isValid = await validator.validateAll(); + + // 设置退出码 + process.exit(isValid ? 0 : 1); +} + +// 如果直接运行此脚本 +if (require.main === module) { + main().catch(error => { + console.error('验证脚本执行失败:', error); + process.exit(1); + }); +} + +module.exports = OpenAPIValidator; \ No newline at end of file diff --git a/scripts/generate_planb_diagrams.py b/scripts/generate_planb_diagrams.py new file mode 100644 index 0000000..1ce776b --- /dev/null +++ b/scripts/generate_planb_diagrams.py @@ -0,0 +1,163 @@ +#!/usr/bin/env python3 +""" +正式网络图生成脚本。 + +用途： +- 生成 PlanB 当前正式口径下的网络分区图与网络连接图 +- 作为 output/diagrams/ 下正式产物的唯一来源 + +说明： +- 如需试验不同布局，请使用 scripts/generate_planb_diagrams_variants.py +""" +from pathlib import Path + +from diagrams import Cluster, Diagram, Edge +from diagrams.generic.network import Router, Switch +from diagrams.onprem.compute import Server +from diagrams.onprem.network import HAProxy, Internet, Nginx +from diagrams.onprem.storage import Ceph + + +ROOT = Path(__file__).resolve().parents[1] +OUT = ROOT / "output" / "diagrams" +OUT.mkdir(parents=True, exist_ok=True) + + +GRAPH_ATTR = { + "fontsize": "20", + "bgcolor": "white", + "pad": "0.2", + "ranksep": "0.55", + "nodesep": "0.35", + "splines": "ortho", + "labelloc": "t", + "fontname": "PingFang SC", + "margin": "0.15", + "rankdir": "LR", + "newrank": "true", +} + +NODE_ATTR = { + "fontname": "PingFang SC", + "fontsize": "13", +} + +EDGE_ATTR = { + "fontname": "PingFang SC", + "fontsize": "11", +} + + +def zone_diagram(): + with Diagram( + "PlanB Network Zones", + filename=str(OUT / "planb_network_zones"), + outformat="png", + show=False, + graph_attr=GRAPH_ATTR, + node_attr=NODE_ATTR, + edge_attr=EDGE_ATTR, + ): + with Cluster("Untrust\n外网区域", graph_attr={"style": "rounded,filled", "color": "#ea580c", "fillcolor": "#fff7ed"}): + mobile = Internet("移动端用户") + third = Internet("第三方系统") + + with Cluster("DMZ\n对外服务区", graph_attr={"style": "rounded,filled", "color": "#d97706", "fillcolor": "#fffbeb"}): + nginx_entry = Nginx("Nginx 入口") + ftp_host = Server("SFTP/FTP 文件交换服务器") + + with Cluster("LAN\n办公与应用区", graph_attr={"style": "rounded,filled", "color": "#2563eb", "fillcolor": "#eff6ff"}): + office_pc = Server("PC 端用户\n办公网段") + app_sw = Switch("应用区交换") + app_cluster = Server("业务应用集群\n2 节点") + svc_host = Server("综合节点") + + with Cluster("Core\n核心数据区", graph_attr={"style": "rounded,filled", "color": "#059669", "fillcolor": "#ecfdf5"}): + db_primary = Server("PostgreSQL 主库") + db_standby = Server("PostgreSQL 热备") + backup = Ceph("备份归档存储") + + # enforce left-to-right zone order and keep the zone centers aligned + mobile - Edge(style="invis", weight="10") - nginx_entry + nginx_entry - Edge(style="invis", weight="10") - office_pc + office_pc - Edge(style="invis", weight="10") - db_primary + + mobile >> Edge(label="HTTPS 443") >> nginx_entry + third >> Edge(label="HTTPS / API") >> nginx_entry + office_pc >> Edge(label="办公网访问") >> nginx_entry + + nginx_entry >> app_sw >> app_cluster + app_cluster >> svc_host + app_cluster >> Edge(label="文件交换 21/22") >> ftp_host + svc_host >> Edge(label="数据库访问") >> db_primary + svc_host >> Edge(label="探测/控制") >> db_standby + db_primary >> Edge(label="主备同步") >> db_standby + db_primary >> Edge(label="备份/WAL") >> backup + db_standby >> Edge(label="备份副本") >> backup + svc_host >> Edge(label="文件归档") >> backup + + +def link_diagram(): + graph_attr = dict(GRAPH_ATTR) + graph_attr["ranksep"] = "0.75" + graph_attr["nodesep"] = "0.3" + with Diagram( + "PlanB Network Links", + filename=str(OUT / "planb_network_links"), + outformat="png", + show=False, + graph_attr=graph_attr, + node_attr=NODE_ATTR, + edge_attr=EDGE_ATTR, + ): + with Cluster("Untrust\n外网区域", graph_attr={"style": "rounded,filled", "color": "#ea580c", "fillcolor": "#fff7ed"}): + mobile = Internet("移动端用户") + third = Internet("第三方系统") + bank_net = Internet("银行系统\n公网/专线") + + with Cluster("DMZ\n对外服务区", graph_attr={"style": "rounded,filled", "color": "#d97706", "fillcolor": "#fffbeb"}): + nginx_entry = Nginx("Nginx 入口") + bank = Server("SFTP/FTP 文件交换服务器") + + with Cluster("LAN\n办公与应用区", graph_attr={"style": "rounded,filled", "color": "#2563eb", "fillcolor": "#eff6ff"}): + pc = Server("PC 端用户\n办公网段") + app_switch = Switch("应用区交换") + app1 = Server("业务应用节点 1\nGateway + Biz") + app2 = Server("业务应用节点 2\nGateway + Biz") + svc = Server("综合节点") + haproxy = HAProxy("HAProxy / PgBouncer / Patroni") + + with Cluster("Core\n核心数据区", graph_attr={"style": "rounded,filled", "color": "#059669", "fillcolor": "#ecfdf5"}): + dbm = Server("PostgreSQL 主库") + dbs = Server("PostgreSQL 热备") + backup = Ceph("备份归档存储") + + # enforce left-to-right zone order: Untrust -> DMZ -> LAN -> Core + mobile - Edge(style="invis", weight="10") - nginx_entry + nginx_entry - Edge(style="invis", weight="10") - pc + pc - Edge(style="invis", weight="10") - dbm + + mobile >> Edge(label="HTTPS 443") >> nginx_entry + third >> Edge(label="HTTPS / 接口") >> nginx_entry + bank_net >> Edge(label="21/22") >> bank + pc >> Edge(label="办公网访问") >> nginx_entry + + nginx_entry >> app_switch + app_switch >> Edge(label="Gateway / API") >> app1 + app_switch >> Edge(label="Gateway / API") >> app2 + app_switch >> Edge(label="业务访问") >> svc + app_switch >> Edge(label="文件交换 21/22") >> bank + svc >> Edge(label="缓存 / 配置 / 文件") >> haproxy + haproxy >> Edge(label="5432 写流量") >> dbm + haproxy >> Edge(label="5432 状态探测", style="dashed") >> dbs + dbm >> Edge(label="主备同步") >> dbs + svc >> Edge(label="文件归档") >> backup + dbm >> Edge(label="WAL / 备份") >> backup + dbs >> Edge(label="备份副本") >> backup + + +if __name__ == "__main__": + zone_diagram() + link_diagram() + print(OUT / "planb_network_zones.png") + print(OUT / "planb_network_links.png") diff --git a/scripts/generate_planb_diagrams_variants.py b/scripts/generate_planb_diagrams_variants.py new file mode 100644 index 0000000..e5e7e77 --- /dev/null +++ b/scripts/generate_planb_diagrams_variants.py @@ -0,0 +1,131 @@ +#!/usr/bin/env python3 +""" +试验版布局脚本。 + +用途： +- 仅用于对比不同 diagrams / graphviz 布局参数的效果 +- 不作为正式交付图的唯一来源 + +正式图来源： +- scripts/generate_planb_diagrams.py +""" +from pathlib import Path + +from diagrams import Cluster, Diagram, Edge +from diagrams.generic.network import Switch +from diagrams.onprem.compute import Server +from diagrams.onprem.network import HAProxy, Internet, Nginx +from diagrams.onprem.storage import Ceph + + +ROOT = Path(__file__).resolve().parents[1] +OUT = ROOT / "output" / "diagrams_variants" +OUT.mkdir(parents=True, exist_ok=True) + + +BASE_GRAPH_ATTR = { + "fontsize": "20", + "bgcolor": "white", + "pad": "0.18", + "ranksep": "0.65", + "nodesep": "0.35", + "splines": "ortho", + "labelloc": "t", + "fontname": "PingFang SC", + "margin": "0.12", + "newrank": "true", +} + +NODE_ATTR = { + "fontname": "PingFang SC", + "fontsize": "13", +} + +EDGE_ATTR = { + "fontname": "PingFang SC", + "fontsize": "11", +} + +ZONE_STYLE = { + "Untrust": {"style": "rounded,filled", "color": "#ea580c", "fillcolor": "#fff7ed"}, + "DMZ": {"style": "rounded,filled", "color": "#d97706", "fillcolor": "#fffbeb"}, + "LAN": {"style": "rounded,filled", "color": "#2563eb", "fillcolor": "#eff6ff"}, + "Core": {"style": "rounded,filled", "color": "#059669", "fillcolor": "#ecfdf5"}, +} + + +def build_nodes(): + with Cluster("Untrust\n外网区域", graph_attr=ZONE_STYLE["Untrust"]): + mobile = Internet("移动端用户") + third = Internet("第三方系统") + bank_net = Internet("银行系统\n公网/专线") + + with Cluster("DMZ\n对外服务区", graph_attr=ZONE_STYLE["DMZ"]): + nginx_entry = Nginx("Nginx 入口") + bank = Server("SFTP/FTP 文件交换服务器") + + with Cluster("LAN\n办公与应用区", graph_attr=ZONE_STYLE["LAN"]): + pc = Server("PC 端用户\n办公网段") + app_switch = Switch("应用区交换") + app1 = Server("业务应用节点 1\nGateway + Biz") + app2 = Server("业务应用节点 2\nGateway + Biz") + svc = Server("综合节点") + ctrl = HAProxy("HAProxy / PgBouncer / Patroni") + + with Cluster("Core\n核心数据区", graph_attr=ZONE_STYLE["Core"]): + dbm = Server("PostgreSQL 主库") + dbs = Server("PostgreSQL 热备") + backup = Ceph("备份归档存储") + + return mobile, third, bank_net, nginx_entry, bank, pc, app_switch, app1, app2, svc, ctrl, dbm, dbs, backup + + +def wire(nodes): + mobile, third, bank_net, nginx_entry, bank, pc, app_switch, app1, app2, svc, ctrl, dbm, dbs, backup = nodes + mobile >> Edge(label="HTTPS 443") >> nginx_entry + third >> Edge(label="HTTPS / 接口") >> nginx_entry + bank_net >> Edge(label="21/22") >> bank + pc >> Edge(label="办公网访问") >> nginx_entry + + nginx_entry >> app_switch + app_switch >> Edge(label="Gateway / API") >> app1 + app_switch >> Edge(label="Gateway / API") >> app2 + app_switch >> Edge(label="文件交换 21/22") >> bank + app_switch >> Edge(label="业务访问") >> svc + svc >> Edge(label="缓存 / 配置 / 文件") >> ctrl + ctrl >> Edge(label="5432 写流量") >> dbm + ctrl >> Edge(label="5432 状态探测", style="dashed") >> dbs + dbm >> Edge(label="主备同步") >> dbs + svc >> Edge(label="文件归档") >> backup + dbm >> Edge(label="WAL / 备份") >> backup + dbs >> Edge(label="备份副本") >> backup + + +def make_variant(name: str, rankdir: str, ranksep: str, nodesep: str): + graph_attr = dict(BASE_GRAPH_ATTR) + graph_attr["rankdir"] = rankdir + graph_attr["ranksep"] = ranksep + graph_attr["nodesep"] = nodesep + with Diagram( + f"PlanB {name}", + filename=str(OUT / name), + outformat="png", + show=False, + graph_attr=graph_attr, + node_attr=NODE_ATTR, + edge_attr=EDGE_ATTR, + ): + nodes = build_nodes() + wire(nodes) + + +if __name__ == "__main__": + variants = [ + ("planb_links_lr_compact", "LR", "0.65", "0.30"), + ("planb_links_lr_balanced", "LR", "0.9", "0.45"), + ("planb_links_tb_compact", "TB", "0.75", "0.35"), + ("planb_links_tb_balanced", "TB", "1.0", "0.45"), + ] + for name, rankdir, ranksep, nodesep in variants: + make_variant(name, rankdir, ranksep, nodesep) + print(OUT / f"{name}.png") diff --git a/specs/007-sys009-design-align/baseline.md b/specs/007-sys009-design-align/baseline.md new file mode 100644 index 0000000..856fbf1 --- /dev/null +++ b/specs/007-sys009-design-align/baseline.md @@ -0,0 +1,31 @@ +# Baseline: SYS-009设计整合与实现对齐 + +## Repository Baselines + +| Repo | Branch | Commit | Role in This Feature | +|------|--------|--------|----------------------| +| `water-docs` | `007-sys009-design-align` | working tree | 正式规格、计划与后续文档修订入口 | +| `water-backend` | `develop` | `68ab72ae6330e33afa0fec3817c0605829973ec2` | `SYS-009` 当前实现证据基线 | +| `water-frontend` | `develop` | `ae65939045449894c0fccab53fee08521e538ddd` | 范围排除依据，仅说明本轮不承接银行运营界面 | + +## Baseline Rules + +1. 所有实现成熟度判断均以 `water-backend` 当前 commit 为准。 +2. 若后续代码基线变化，必须同步更新本文件和 `final-verdict.md`。 +3. frontend 不作为本轮正式承接范围，只保留“无完整银行批次/回盘/对账运营界面”的边界说明。 + +## Key Evidence Anchors + +- 实时收费： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/payceb/PayCebController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/payceb/PayCebServiceImpl.java` +- 代扣： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankwithholding/BankWithholdingController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingServiceImpl.java` +- 托收： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankcollection/BankCollectionController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankcollection/BankCollectionServiceImpl.java` +- 表结构与后台运营： + - `../water-backend/sw-business-bank/docs/建表sql.sql` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/admin/` + diff --git a/specs/007-sys009-design-align/checklists/requirements.md b/specs/007-sys009-design-align/checklists/requirements.md new file mode 100644 index 0000000..b6aa057 --- /dev/null +++ b/specs/007-sys009-design-align/checklists/requirements.md @@ -0,0 +1,36 @@ +# Specification Quality Checklist: SYS-009设计整合与实现对齐 + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-03-20 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Validation iteration 1 passed. +- Mandatory sections are complete, no clarification markers remain, and the scope is bounded to formal document integration plus backend evidence alignment. +- Implementation file paths are used only as brownfield evidence anchors, not as prescribed implementation work for this round. diff --git a/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md b/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md new file mode 100644 index 0000000..97a43d3 --- /dev/null +++ b/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md @@ -0,0 +1,30 @@ +# Contract: SYS-009 Capability Alignment + +## Purpose + +定义外部 `SYS-009` 能力簇与本仓库正式文档落点之间的最小对齐契约，供后续文档修订、任务拆解和验收复用。 + +## Alignment Matrix + +| Capability | Formal Domain | Primary Formal Target | Secondary Target | Expected Verdict Types | +|-----------|---------------|-----------------------|------------------|------------------------| +| 实时收费查询/缴费 | `REV-003` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/03_Interface_Design.md` `IF-EXT-003` | 已实现 / 部分实现 | +| 当日未对账红冲 | `REV-003` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 代扣签约 | `REV-008` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/03_Interface_Design.md` | 已实现 / 部分实现 | +| 代扣解约 | `REV-008` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/03_Interface_Design.md` | 已实现 / 部分实现 | +| 代扣客户状态查询 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 送盘 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` `IF-EXT-001` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 | +| 送盘状态查询 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 取消送盘 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 回盘 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` `IF-EXT-002` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 | +| 回盘状态查询 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 对账文件与对账请求 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/03_Technical_Design/01_Database_Design.md` | 部分实现 | +| 结算状态协同 | `REV-008` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/01_Database_Design.md` | 文档先行 / 部分实现 | + +## Contract Rules + +1. 任何能力簇都必须先映射到既有正式主文档，再允许写入计划、任务和验收结论。 +2. 若外部设计存在而 backend 缺少闭环实现，正式文档必须保留目标设计边界，同时显式标注当前成熟度。 +3. 不允许为单个能力簇创建新的平行正式文档。 +4. 若能力簇涉及 `bk_*` 表族，数据库设计只补承接口径，不下沉到实现脚本级细节。 + diff --git a/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md b/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md new file mode 100644 index 0000000..03e991e --- /dev/null +++ b/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md @@ -0,0 +1,37 @@ +# Contract: SYS-009 Status Verdicts + +## Purpose + +定义能力簇状态判定的统一准则，避免在主文档、验证工件和后续任务中出现不同口径。 + +## Verdict Definitions + +| Verdict | Required Evidence | Disallowed Shortcut | +|--------|-------------------|---------------------| +| 已实现 | 具备明确路由/入口、核心业务校验、数据写入或状态更新、结果回写或留痕 | 仅有表结构、仅有后台管理页面、仅有 DTO | +| 部分实现 | 具备接口骨架、DTO、服务接口、部分业务逻辑或局部闭环，但存在 TODO、空实现、未打通的外部文件/状态处理 | 仅凭“将来准备实现”的设计说明 | +| 文档先行 | 有正式设计目标和对象口径，但当前未定位到足够代码证据支撑 | 以外部参考文档直接推断已实现 | + +## Capability Verdicts For This Feature + +| Capability | Initial Verdict | Evidence Anchor | +|-----------|-----------------|-----------------| +| 实时收费查询 | 已实现 | `PayCebController#getChargeSearch` / `PayCebServiceImpl#getChargeSearch` | +| 实时收费缴费 | 已实现 | `PayCebController#getChargeOffs` / `PayCebServiceImpl#getChargeOffs` | +| 代理收费对账 | 部分实现 | `PayCebController#paymentCheck` TODO，占位未闭环 | +| 代扣签约 | 已实现 | `BankWithholdingController#signing` / `BankWithholdingServiceImpl#signing` | +| 代扣解约 | 已实现 | `BankWithholdingController#termination` / `BankWithholdingServiceImpl#termination` | +| 代扣客户状态查询 | 已实现 | `BankWithholdingController#customerCheck` / `BankWithholdingServiceImpl#customerCheck` | +| 送盘 | 已实现 | `BankWithholdingController#sendDisc` / `BankWithholdingServiceImpl#sendDisc` | +| 送盘状态查询 | 已实现 | `BankWithholdingController#sendDiscCheck` / `BankWithholdingServiceImpl#sendDiscCheck` | +| 取消送盘 | 已实现 | `BankWithholdingController#cancelDisc` / `BankWithholdingServiceImpl#cancelDisc` | +| 回盘 | 已实现 | `BankWithholdingController#backDisc` / `BankWithholdingServiceImpl#backDisc` | +| 回盘状态查询 | 已实现 | `BankWithholdingController#backDiscCheck` / `BankWithholdingServiceImpl#backDiscCheck` | +| 托收平行链路 | 部分实现 | `BankCollection*` 路径已存在，成熟度未全闭环 | +| 运营侧批次/对账/结算管理 | 已具备入口 | `WithholdingBatchController` / `ReconcileBatchController` / `SettlementBatchController` | + +## Contract Rules + +1. 主文档中同一能力簇的 verdict 必须与 `final-verdict.md` 保持一致。 +2. 若后续代码变化导致 verdict 升降级，必须同时更新基线和依据。 +3. `已具备入口` 不是独立 verdict，只能作为 supporting note，最终仍需归入三类正式 verdict 之一。 diff --git a/specs/007-sys009-design-align/data-model.md b/specs/007-sys009-design-align/data-model.md new file mode 100644 index 0000000..a9ed0ae --- /dev/null +++ b/specs/007-sys009-design-align/data-model.md @@ -0,0 +1,113 @@ +# Data Model: SYS-009设计整合与实现对齐 + +## 1. Source Capability + +### Purpose + +表示外部 `water-bank-api-doc` 中一个可被正式文档吸收的银行协同能力簇。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `capability_id` | 能力标识，如 `REALTIME_PAY`、`WITHHOLD_SIGNING` | 必填，唯一 | +| `capability_name` | 能力名称 | 必填 | +| `business_domain` | 业务归属，如 `REV-003`、`REV-008` | 必填，必须落在当前正式模块范围内 | +| `source_docs` | 来源文档列表 | 至少 1 个 | +| `formal_targets` | 正式承接文档与章节 | 至少 1 个 | +| `current_status` | 当前实现状态 | 必填，取值仅限 `已实现` / `部分实现` / `文档先行` | +| `notes` | 边界说明 | 可选 | + +### Relationships + +- 一个 `Source Capability` 必须映射到至少一个 `Formal Document Section` +- 一个 `Source Capability` 可以关联多个 `Backend Evidence Item` + +## 2. Formal Document Section + +### Purpose + +表示本仓库中承接 `SYS-009` 设计整合结论的正式章节或表格位置。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `document_path` | 正式文档路径 | 必填，必须是既有主文档或治理文档 | +| `section_anchor` | 章节锚点或节标题 | 必填 | +| `section_type` | 章节类型，如范围摘要、业务流程、接口契约、数据对象 | 必填 | +| `update_intent` | 本轮更新意图 | 必填 | +| `consistency_impacts` | 受影响的一致性项 | 至少 1 项 | + +### Relationships + +- 一个 `Formal Document Section` 可承接多个 `Source Capability` +- 一个 `Formal Document Section` 可引用多个 `Backend Evidence Item` + +## 3. Backend Evidence Item + +### Purpose + +表示用于判定当前实现状态的代码或表结构证据。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `evidence_path` | 证据文件路径 | 必填 | +| `evidence_type` | 类型，如 `controller`、`service`、`table_sql`、`admin_entry` | 必填 | +| `capability_scope` | 覆盖的能力簇 | 必填 | +| `maturity_signal` | 成熟度信号，如完整实现、TODO、骨架接口、表结构已具备 | 必填 | +| `baseline_sha` | 对应 backend 基线 | 必填 | +| `remarks` | 备注 | 可选 | + +### State Interpretation + +| Maturity Signal | Verdict | +|----------------|---------| +| 完整请求处理 + 业务校验 + 数据写入/状态更新 + 日志留痕 | 已实现 | +| 有路由 / DTO / service 接口 / 部分逻辑，但存在 TODO 或空实现 | 部分实现 | +| 只有正式设计目标，没有明确代码证据 | 文档先行 | + +## 4. Alignment Verdict + +### Purpose + +表示对单个能力簇的正式对齐结论。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `capability_id` | 对应能力标识 | 必填 | +| `formal_target` | 正式落点 | 必填 | +| `verdict` | 对齐结论 | 必填，取值仅限 `已实现` / `部分实现` / `文档先行` | +| `basis_summary` | 判定依据摘要 | 必填 | +| `follow_up_action` | 后续动作 | 必填 | + +### State Transitions + +```text +文档先行 -> 部分实现 -> 已实现 +``` + +触发条件： +- `文档先行 -> 部分实现`：出现 controller/service/DTO/表结构等明确工程骨架 +- `部分实现 -> 已实现`：业务链路、状态更新和留痕闭环完成，且有稳定代码证据 + +## 5. Verification Artifact + +### Purpose + +表示本轮用于追踪计划、研究、对齐和结论的工件。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `artifact_name` | 工件名称 | 必填 | +| `artifact_path` | 工件路径 | 必填 | +| `artifact_role` | 作用，如基线、研究、契约、最终结论 | 必填 | +| `depends_on` | 依赖工件 | 可选 | +| `completion_rule` | 何时可判定完成 | 必填 | + diff --git a/specs/007-sys009-design-align/final-verdict.md b/specs/007-sys009-design-align/final-verdict.md new file mode 100644 index 0000000..2b34040 --- /dev/null +++ b/specs/007-sys009-design-align/final-verdict.md @@ -0,0 +1,56 @@ +# Final Verdict: SYS-009设计整合与实现对齐 + +## Current Implementation Verdict + +本轮已完成正式主文档修订、实现边界回写、`BankWithholding` 六条银行入口补齐及最小编译验证，当前结论如下： + +- `PayCeb`：基础实时查询/缴费闭环已实现，对账回传未实现。 +- `BankWithholding`：签约、解约、客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询均已具备 controller/service 路由、核心校验、批次/明细状态更新或留痕能力，已形成最小实现态闭环。 +- `BankCollection`：与代扣平行，整体为部分实现。 +- `bk_*` 表族与后台管理入口：对象层与资源管理层基本齐备，可支撑代扣批处理状态管理，但仍不能替代真实银行文件联调与运行态样本证据。 +- 正式文档回写仍采用“目标设计边界 + 当前成熟度注记”的双层表达，并将实现态闭环与运行态风险分层记录。 + +## Completed Changes + +1. 已修订 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，补充 `REV-003`、`REV-008` 的实现边界与当前成熟度说明。 +2. 已修订 `docs/design/03_Technical_Design/03_Interface_Design.md`，补充签约、解约、状态查询、取消送盘、回盘状态和当前状态说明。 +3. 已修订 `docs/design/03_Technical_Design/01_Database_Design.md`，明确 `bk_*` 表族对象齐备但业务编排未闭环的边界。 +4. 已修订 `docs/design/01_Overview/03_Summary_Design.md`，将 `SYS-009` 从强实现表述收敛为“已落地能力 + 后续完善项”口径。 +5. 已修订 `specs/007-sys009-design-align/plan.md`、`research.md`、`quickstart.md`，同步范围、工件和执行结果。 +6. 已复核 backend `BankWithholdingController`、`BankWithholdingServiceImpl`、`TransactionMapper` 与相关 DTO/DO/Mapper，实现 `customerCheck`、`sendDisc`、`sendDiscCheck`、`cancelDisc`、`backDisc`、`backDiscCheck` 六条银行入口从 TODO/null 到实现态闭环的升级。 + +## Validation Results + +- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`：通过，0 个问题 +- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`：通过，0 个问题 +- `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`：通过，0 个问题 +- `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md`：通过，0 个问题 +- `make check-links`：通过，仓库级链接检查无问题 +- `make validate-mermaid`：通过，Mermaid 语法验证无问题 +- `mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am -DskipTests compile`：通过，backend 最小编译验证成功 +- `mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am test`：通过，当前模块无失败测试（本轮输出为 `No tests to run`） + +## Governance Sync + +1. 已回写 `docs/design/00_Management/01_Project_Progress.md`，记录本轮 `SYS-009` 设计整合、银行代扣六条入口实现态闭环与剩余运行态风险。 +2. 已回写 `docs/design/00_Management/03_Task_Checklist.md`，登记本轮任务闭环状态、六条银行入口补齐结果与最小验证结论。 +3. 已回写 `specs/007-sys009-design-align/contracts/sys009-status-verdicts.md`，将 `BankWithholding` 六条银行入口 verdict 与当前实现态证据同步。 + +## Remaining Risks + +1. `PayCeb` 当前仅可确认欠费查询与缴费处理闭环，对账回传仍未落地。 +2. `BankWithholding` 六条银行入口虽已形成最小实现态闭环，但 `backDisc` 仍为最小化结果分发实现，尚未接入真实银行回盘文件解析、SFTP/文件通道联调和运行态样本补证。 +3. `BankCollection` 仍处于部分实现状态；与 `BankWithholding` 平行的托收闭环尚未同步补齐。 +4. `bk_*` 表族和后台资源管理入口已具备对象层基础，但不能替代银行 app 协同闭环的运行态验证证据。 + +## Feature Artifacts Produced + +- `spec.md` +- `plan.md` +- `baseline.md` +- `research.md` +- `data-model.md` +- `quickstart.md` +- `contracts/sys009-capability-alignment.md` +- `contracts/sys009-status-verdicts.md` +- `tasks.md` diff --git a/specs/007-sys009-design-align/plan.md b/specs/007-sys009-design-align/plan.md new file mode 100644 index 0000000..24fcbba --- /dev/null +++ b/specs/007-sys009-design-align/plan.md @@ -0,0 +1,126 @@ +# Implementation Plan: [FEATURE] + +**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] +**Input**: Feature specification from `/specs/[###-feature-name]/spec.md` + +**Note**: This template is filled in by the `/speckit.plan` command. For this project, planning is document-first and multi-repo aware. + +## Summary + +[Extract from feature spec: primary requirement + target documents + intended update approach] + +## Repository Scope + +- **Formal workflow home**: `water-docs` +- **Target repos in scope**: + - `water-docs`: [Yes / No] + - `water-backend`: [Yes / No] + - `water-frontend`: [Yes / No] +- **Primary delivery mode**: [Document closure / Code evidence alignment / Backend implementation / Frontend implementation / Mixed] + +## Code Baseline + +- **Backend baseline**: [commit SHA / branch / N/A] +- **Frontend baseline**: [commit SHA / branch / N/A] +- **Baseline capture plan**: [How code evidence will be tied to a stable commit] + +## Technical Context + +**Primary Work Product**: [Markdown design docs, management docs, evidence files, backend code, frontend code] +**Source of Truth Documents**: [List the authoritative docs that this change must align with] +**Reference Sources**: [Archive/guides/other references allowed for verification] +**Validation Commands**: [e.g., make validate-file FILE=..., make check-links, make validate-mermaid, compile/build/test commands] +**Target Scope**: [specific chapters, main docs, code modules, or verification slices] +**Project Type**: 文档治理仓库 + 多仓实现协作 +**Constraints**: [no new parallel formal docs, no invented business rules, relative links only, branch rules, baseline rules] +**Scale/Scope**: [single document / cross-document / multi-repo / verification-heavy] + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [ ] **主文档归属已确认**：正式结论优先落在 `water-docs` 既有主文档或治理文档，不新增平行正式稿。 +- [ ] **多仓范围已确认**：已明确本轮是否涉及 `water-backend`、`water-frontend`，以及各自只是取证还是需要改代码。 +- [ ] **代码基线已确认**：backend/frontend 的 commit 或 branch 基线已记录，避免文档结论失去实现版本锚点。 +- [ ] **Archive 使用方式合规**：Archive 仅作为来源/核对输入，不直接替代正式口径。 +- [ ] **一致性影响已列出**：已识别系统名称、数据库口径、编号、图表、链接、术语、接口契约等受影响项。 +- [ ] **校验与台账动作已规划**：已明确需要执行的文档校验、代码验证、evidence 更新，以及是否需要更新 `01_Project_Progress.md` / `03_Task_Checklist.md`。 + +## Project Structure + +### Feature Artifacts + +```text +specs/[###-feature]/ +├── spec.md +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +├── tasks.md +└── verification.md / final-verdict.md +``` + +### Repository Touchpoints + +```text +water-docs/ +├── docs/design/ +├── specs/ +└── .specify/ + +water-backend/ +└── [backend modules in scope] + +water-frontend/ +└── [frontend modules in scope] +``` + +**Structure Decision**: [Document the exact files or modules to be updated and the reason each is in scope] + +## Phase 0: Research & Alignment + +### Research Inputs + +- [List unresolved questions about docs, backend, frontend, baseline, or validation] + +### Deliverables + +- `research.md` +- [Optional evidence note if brownfield code audit is required] + +## Phase 1: Design & Contracts + +### Planned Artifacts + +- `data-model.md` +- `contracts/*` +- `quickstart.md` +- `verification.md` or `final-verdict.md` if the feature is verification-heavy + +### Design Decisions + +- [List the intended docs-first and multi-repo decisions] + +## Validation Plan + +- **Document validation**: [make validate-file / check-links / mermaid checks] +- **Backend validation**: [compile / unit test / smoke / N/A] +- **Frontend validation**: [build / lint / typecheck / smoke / N/A] +- **Evidence output**: [baseline.md / docs-validation.md / backend-validation.md / frontend-validation.md / final-verdict.md] + +## Ledger Sync Plan + +- **Project progress update required**: [Yes / No] +- **Task checklist update required**: [Yes / No] +- **Evidence or verification summary update required**: [Yes / No] + +## Complexity Tracking + +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| [e.g., temporary appendix doc] | [current need] | [why existing main doc could not safely absorb it] | +| [e.g., Archive citation exception] | [specific traceability reason] | [why normal main-doc source was insufficient] | diff --git a/specs/007-sys009-design-align/quickstart.md b/specs/007-sys009-design-align/quickstart.md new file mode 100644 index 0000000..5b48664 --- /dev/null +++ b/specs/007-sys009-design-align/quickstart.md @@ -0,0 +1,83 @@ +# Quickstart: SYS-009设计整合与实现对齐 + +## 1. 准备上下文 + +1. 在 `water-docs` 根目录确认当前分支为 `007-sys009-design-align`。 +2. 阅读以下文件： + - `docs/design/00_Management/01_Project_Progress.md` + - `docs/design/00_Management/02_Delivery_Standards.md` + - `docs/design/00_Management/03_Task_Checklist.md` + - `docs/design/01_Overview/03_Summary_Design.md` + - `docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `docs/design/03_Technical_Design/01_Database_Design.md` + - `docs/design/03_Technical_Design/03_Interface_Design.md` + +## 2. 固定代码基线 + +1. 记录 backend 分支和 commit： + - `git -C ../water-backend rev-parse --abbrev-ref HEAD` + - `git -C ../water-backend rev-parse HEAD` +2. 如仅做范围说明，可记录 frontend 分支和 commit： + - `git -C ../water-frontend rev-parse --abbrev-ref HEAD` + - `git -C ../water-frontend rev-parse HEAD` +3. 将结果写入 `baseline.md` 与 `final-verdict.md`。 + +## 3. 收集对齐证据 + +1. 核对外部设计来源： + - `/Users/tangweijie/github/water-bank-api-doc/营收系统缴费接口.md` + - `/Users/tangweijie/github/water-bank-api-doc/营收系统接口规范设计文档.md` +2. 核对 backend 关键证据： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../controller/app/payceb/PayCebController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../service/payceb/PayCebServiceImpl.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../controller/app/bankwithholding/BankWithholdingController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../service/bankwithholding/BankWithholdingServiceImpl.java` + - `../water-backend/sw-business-bank/docs/建表sql.sql` +3. 按“已实现 / 部分实现 / 文档先行”归档能力簇结论。 + +## 4. 更新正式文档 + +1. 在 `12_REV_Detailed.md` 补 `REV-003` 与 `REV-008` 的能力边界与成熟度说明。 +2. 在 `03_Interface_Design.md` 补签约、解约、状态查询、取消送盘、对账文件规则等接口契约。 +3. 在 `01_Database_Design.md` 补 `bk_*` 表族与外部能力簇的承接口径。 +4. 在 `03_Summary_Design.md` 同步 `SYS-009` 范围摘要和外部接口表。 + +## 5. 生成与更新证据工件 + +1. 更新或新增： + - `baseline.md` + - `research.md` + - `data-model.md` + - `contracts/*` + - `final-verdict.md` +2. 若本轮已完成正式文档修订，同步更新： + - `docs/design/00_Management/01_Project_Progress.md` + - `docs/design/00_Management/03_Task_Checklist.md` + +## 6. 执行校验 + +1. `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` +2. `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` +3. `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` +4. `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` +5. `make check-links` +6. `make validate-mermaid` + +## 7. 形成最终结论 + +1. 在 `final-verdict.md` 汇总： + - 本轮基线 + - 已整合的能力簇 + - 每个能力簇的成熟度结论 + - 已更新的正式文档 + - 已执行的校验 + - 剩余未闭环项 + +## 8. 当前已执行结果 + +- 已完成 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`03_Summary_Design.md` 的 SYS-009 正式口径修订。 +- 已完成以下单文件校验并通过： + - `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` + - `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` + - `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` diff --git a/specs/007-sys009-design-align/research.md b/specs/007-sys009-design-align/research.md new file mode 100644 index 0000000..3f1fd23 --- /dev/null +++ b/specs/007-sys009-design-align/research.md @@ -0,0 +1,77 @@ +# Phase 0 Research: SYS-009设计整合与实现对齐 + +## 1. 外部设计归并路径 + +Decision：实时收费能力归并到 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-003 营业收费`，并在 `docs/design/03_Technical_Design/03_Interface_Design.md` 的 `IF-EXT-003 银行实时收费接口` 承接查询、缴费和当日未对账红冲约束。 +Rationale：实时收费首先影响账单查询、缴费处理和收费结果回写，业务归属在收费主链路；外部资料新增的是银行协议细节，不需要为其新建独立 `SYS-009` 正式章节。 +Alternatives considered：全部并入 `REV-008`；被放弃，因为这样会弱化实时收费与营业收费核销主链的关联。 + +Decision：代扣签约/解约归并到 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-008 代收与银行业务`，并在 `docs/design/03_Technical_Design/03_Interface_Design.md` 增补签约、解约接口小节。 +Rationale：`bk_withholding_agreement` 已是正式数据库对象，但当前接口专项缺少签约/解约契约，外部资料正好补足该缺口。 +Alternatives considered：归入客户资料模块；被放弃，因为签解约属于银行协同交易动作，不是客户主数据维护。 + +Decision：送盘/回盘继续以 `IF-EXT-001`、`IF-EXT-002` 为主承接，在接口专项中补充批次号、文件名、时间窗口和文件交互规则，在 `REV-008` 中保留业务主流程。 +Rationale：正式文档已有批次下发和回盘时序，外部资料主要补的是操作细节和文件规则。 +Alternatives considered：在概要设计扩写送盘/回盘细节；被放弃，因为概要设计不适合承载文件交互细节。 + +Decision：送盘状态查询、回盘状态查询、代扣客户状态查询、取消送盘统一归并到 `docs/design/03_Technical_Design/03_Interface_Design.md`，并在 `REV-008` 中仅保留业务边界和状态流转说明。 +Rationale：这些能力本质是外部协同补偿和批次生命周期控制，最适合作为正式接口契约补充。 +Alternatives considered：只在详细设计文字说明中顺带提及；被放弃，因为无法形成可验收的接口边界。 + +Decision：对账能力在接口专项中补对账文件规则、文件命名和应答约束，结算能力保持正式文档现有抽象，不凭空制造外部结算报文。 +Rationale：外部资料对对账文件和对账请求定义较清晰，但未提供独立结算报文；正式文档当前以 `bk_settlement_batch` 和结算状态协同承接更稳妥。 +Alternatives considered：把对账与结算都写成独立外部接口；被放弃，因为当前证据不足，会制造新的正式口径风险。 + +## 2. 当前 backend 实现成熟度 + +Decision：`PayCeb` 应判定为“已实现（基础闭环）”，但代理收费对账仅为“部分实现”。 +Rationale：`PayCebController` + `PayCebServiceImpl` 已完成欠费查询、缴费的解密、反序列化、业务校验、调用 `ChargeApi`/`CustApi`/`DeptApi`、流水唯一性控制和交易日志留痕；`paymentCheck` 仍为 TODO，占位返回。正式文档应写成“实时查询与缴费已实现，对账回传未实现”，而不是笼统写“PayCeb 全部已完成”。 +Alternatives considered：将整个实时收费能力统一标记为“部分实现”；被放弃，因为查询/缴费确有真实闭环，不应被 TODO 对账能力整体拉低。 + +Decision：代扣签约与解约可判定为“已实现”，代扣客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询均判定为“部分实现”。 +Rationale：`BankWithholdingController` 与 `BankWithholdingServiceImpl` 中签约/解约已完成解密、报文解析、机构/客户/协议校验、协议写入或状态更新、交易日志留痕；其余能力保留 controller TODO 和 service 空实现。 +Alternatives considered：将除签约外的全部能力标记为“文档先行”；被放弃，因为 app controller 路由、DTO 和服务接口已存在，说明已进入骨架实现阶段。 + +Decision：银行托收路径与代扣路径结构平行，成熟度整体为“部分实现”。 +Rationale：`BankCollectionController` / `BankCollectionServiceImpl` 具备签约、解约、客户状态查询、送盘、回盘、取消等接口与服务定义，但完整实现闭环尚不统一成熟。 +Alternatives considered：本轮不写托收；被放弃，因为外部设计和正式文档都把托收作为 `REV-008` 范围一部分。 + +Decision：`bk_*` 表族应判定为“表结构与对象层基本齐备，但业务编排仅部分实现”。 +Rationale：`bk_payment_channel`、`bk_channel_api_config`、`bk_channel_route_rule`、`bk_channel_statistics`、`bk_transaction*`、`bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_batch` 均有 DO/Mapper，且 `sw-business-bank/docs/建表sql.sql` 给出完整建表脚本；但仓库内未见正式迁移脚本统一落位，Mapper XML 也未体现送盘/回盘/对账/结算完整编排。 +Alternatives considered：直接判为“已实现”；被放弃，因为对象齐备不等于业务闭环跑通。也不适合降为“文档先行”，因为交易与协议对象已被真实使用。 + +Decision：后台运营管理对象可判定为“已具备运营侧入口”，但不能据此推断银行 app 协同闭环已完成。 +Rationale：`WithholdingAgreementController`、`WithholdingBatchController`、`ReconcileBatchController`、`SettlementBatchController` 等管理入口已存在，同时后台资源管理层已覆盖交易、协议、批次、明细、对账差异和结算台账。 +Alternatives considered：把后台运营入口视为所有能力已完成的证据；被放弃，因为 app 协议处理、文件交互和状态补偿仍有明显未实现部分。 + +## 3. 正式文档回写策略 + +Decision：正式文档采用“目标设计边界 + 当前成熟度注记”的双层表达。 +Rationale：如果只写设计，会掩盖实现缺口；如果只写现状，会丢失外部设计应承接的正式边界。 +Alternatives considered：只在 `specs/` 中记录成熟度，不回写主文档；被放弃，因为主文档才是正式评审入口。 + +Decision：在 `01_Database_Design.md` 中仅补对象承接与成熟度说明，不新增 DDL 级细节。 +Rationale：当前数据库主文档已明确 `bk_*` 表族口径，本轮重点是把外部设计能力映射到既有对象。 +Alternatives considered：复写外部设计中的示例表结构；被放弃，因为会破坏文档抽象层次。 + +Decision：最终结论以 `final-verdict.md` 汇总，并以 `baseline.md` 锚定 backend 版本。 +Rationale：后续 `/speckit.tasks` 和验收时需要直接复用统一结论。 +Alternatives considered：把所有证据都散落在 plan 或 spec 中；被放弃，因为不利于后续追踪。 + +## 4. 回写重点 + +Decision：`docs/design/01_Overview/03_Summary_Design.md` 对 `SYS-009` 只能保留保守表述。 +Rationale：当前可安全声明的是聚合支付基础能力、银行欠费查询/缴费、代扣/托收签解约、后台资源管理已具备；夜间批量代扣、送盘/回盘、对账、结算不能继续使用“完整支持”的强表述。 +Alternatives considered：延续现有强描述；被放弃，因为会高估实现成熟度。 + +Decision：`docs/design/03_Technical_Design/03_Interface_Design.md` 需显式拆分 `PayCeb Query/Pay`、`PayCheck`、`BankWithholding/BankCollection Signing/Termination` 与其余预留接口。 +Rationale：只有把接口分层定级，后续评审和联调才不会把签解约已实现误读成送盘/回盘/对账也已完成。 +Alternatives considered：仅在 `final-verdict.md` 说明；被放弃，因为正式接口文档本身需要承担契约边界。 + +Decision：`docs/design/03_Technical_Design/01_Database_Design.md` 保留 `bk_*` 为真实承接口径，但要补“业务编排与正式迁移证据仍不完整”的边界。 +Rationale：数据库对象确实存在，但不能让读者从表族完整推断业务闭环完成。 +Alternatives considered：删弱 `bk_*` 口径；被放弃，因为会低估当前真实承接基础。 + +Decision：正式文档修订已按上述研究结论完成首轮回写，并通过 4 份主文档单文件校验。 +Rationale：当前 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`03_Summary_Design.md` 已分别补入成熟度边界、接口扩展说明和数据库承接口径说明，验证了研究结论可直接落入正式主文档。 +Alternatives considered：先只保留 research 结论、延后正式文档回写；被放弃，因为本轮目标是形成可交付、可评审的正式文档闭环。 diff --git a/specs/007-sys009-design-align/spec.md b/specs/007-sys009-design-align/spec.md new file mode 100644 index 0000000..6c2990c --- /dev/null +++ b/specs/007-sys009-design-align/spec.md @@ -0,0 +1,168 @@ +# Feature Specification: SYS-009设计整合与实现对齐 + +**Feature Branch**: `007-sys009-design-align` +**Created**: 2026-03-20 +**Status**: Draft +**Input**: User description: "我需要将 /Users/tangweijie/github/water-bank-api-doc 这里的SYS-009的设计整合到我们文档里面来,并且和现在实现的代码进行对其" + +## Document Scope & Sources *(mandatory)* + +- **Target documents**: + - `docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `docs/design/03_Technical_Design/03_Interface_Design.md` + - `docs/design/03_Technical_Design/01_Database_Design.md` + - `docs/design/01_Overview/03_Summary_Design.md` + - `docs/design/00_Management/01_Project_Progress.md` + - `docs/design/00_Management/03_Task_Checklist.md` +- **Primary source of truth**: + - `docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `docs/design/03_Technical_Design/03_Interface_Design.md` + - `docs/design/03_Technical_Design/01_Database_Design.md` + - `docs/design/00_Management/01_Project_Progress.md` + - `docs/design/00_Management/03_Task_Checklist.md` +- **Reference sources**: + - `/Users/tangweijie/github/water-bank-api-doc/营收系统缴费接口.md` + - `/Users/tangweijie/github/water-bank-api-doc/营收系统接口规范设计文档.md` + - `/Users/tangweijie/github/water-bank-api-doc/docs/README.md` + - `docs/guides/BACKEND_CURRENT_STATUS.md` + - `docs/guides/BACKEND_TABLE_MAPPING.md` + - `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` + - `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_需求规格说明书.md` +- **Scope decision**: 本次需求在范围内，范围判断以 `docs/design/01_Overview/03_Summary_Design.md` 与 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 的交集为准；`SYS-009` 实时收费、代扣、托收、对账相关能力在交集范围内，可进入现有正式主文档整合与当前 backend 实现对齐，不新建平行正式文档。 + +## Repository Scope *(mandatory)* + +- **Target repos**: + - `water-docs`: Required + - `water-backend`: Required + - `water-frontend`: Not Required +- **Expected delivery type**: Document closure / Code evidence alignment +- **Out of scope for this round**: + - 直接修改 `../water-backend` 或 `../water-frontend` 业务代码 + - 新建独立的“SYS-009 正式主文档”替代现有主文档 + - 在无实现证据的前提下把高级银行接口写成“已完成” + - 为银行批次、回盘、对账、结算补做前端运营页面设计 + +## Code Baseline *(mandatory for brownfield work)* + +- **Backend baseline**: `water-backend` `develop` @ `68ab72ae6330e33afa0fec3817c0605829973ec2` +- **Frontend baseline**: `water-frontend` `develop` @ `ae65939045449894c0fccab53fee08521e538ddd`（仅用于范围判断，不作为本轮正式承接基线） +- **Baseline capture rule**: 所有“已实现 / 部分实现 / 文档先行”判断都必须绑定到本次记录的 backend commit SHA，并在后续验证工件中写明对应代码路径与判定理由。 + +## Evidence Scope *(mandatory)* + +- **Document evidence required**: + - `specs/007-sys009-design-align/spec.md` + - 正式文档中与 `SYS-009`、`REV-008`、外部银行接口相关的修订章节 + - 管理台账中的变更记录与任务状态更新 +- **Backend evidence required**: + - 实时收费接口证据：`PayCebController`、`PayCebServiceImpl` + - 银行代扣接口证据：`BankWithholdingController`、`BankWithholdingServiceImpl` + - 银行托收接口证据：`BankCollectionController`、`BankCollectionServiceImpl` + - 数据对象证据：`docs/建表sql.sql`、`bk_transaction*`、`bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_batch` + - 运营侧入口证据：`WithholdingAgreementController`、`WithholdingBatchController`、`ReconcileBatchController`、`SettlementBatchController` +- **Frontend evidence required**: + - 非强制 + - 如需说明边界，仅记录当前客户代扣资料维护入口与缺失的银行批次运营界面，不形成 frontend 改造范围 +- **Verification artifacts required**: + - `specs/007-sys009-design-align/baseline.md` + - `specs/007-sys009-design-align/final-verdict.md` + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - 整合正式设计口径 (Priority: P1) + +作为文档评审人，我需要在现有正式主文档中看到 `SYS-009` 银行侧能力的统一设计口径，这样我可以用一套正式材料评审实时收费、代扣、送盘、回盘、对账与结算能力，而不是同时维护外部原始资料和仓内多份描述。 + +**Why this priority**: 这是本次需求的核心目标；如果正式文档不先吸收 `SYS-009` 设计，后续代码评审、验收和任务拆解都会继续依赖仓外资料，无法形成单一交付入口。 + +**Independent Test**: 仅阅读更新后的正式主文档，即可定位 `SYS-009` 相关能力范围、接口边界、关键数据对象和与 `REV-003` / `REV-008` 的关系，无需再依赖仓外原始接口文档。 + +**Acceptance Scenarios**: + +1. **Given** 正式文档目前仅概括了 `SYS-009` 的实时收费、代扣、对账、结算能力，**When** 本次整合完成，**Then** 正式文档必须明确承接外部来源中的实时收费、代扣签约/解约、送盘、回盘、对账、状态查询与取消等关键能力簇。 +2. **Given** 外部 `water-bank-api-doc` 存在银行协议与接口细节，**When** 设计被回写到正式主文档，**Then** 必须保持当前文档编号、术语和主文档结构稳定，而不是新增平行主稿。 + +--- + +### User Story 2 - 对齐当前实现边界 (Priority: P2) + +作为技术评审人，我需要知道 `SYS-009` 哪些设计已经被当前 backend 实现承接、哪些只是接口骨架或数据模型已具备、哪些仍然只是文档先行，这样我可以据此安排后续开发和验收范围。 + +**Why this priority**: 仅有设计整合但没有实现对齐，会把“接口存在”“代码完成”“数据表已建”混为一谈，直接影响后续任务排序和风险判断。 + +**Independent Test**: 对照文档中的对齐结论和 backend 验证工件，评审人应能独立判断实时收费、代扣签约/解约、客户状态查询、送盘、回盘、对账等能力分别处于哪种状态。 + +**Acceptance Scenarios**: + +1. **Given** backend 已存在 `PayCeb*` 与 `BankWithholding*` 代码入口，**When** 文档完成对齐，**Then** 文档必须区分“已实现”“部分实现”“文档先行”三类状态，而不能统一写成“已支持”。 +2. **Given** backend 中部分接口仍为 TODO 或占位返回，**When** 文档回写正式口径，**Then** 必须把这些能力标记为待补实现或仅保留设计边界，不能误写为已落地闭环。 + +--- + +### User Story 3 - 形成可审计证据链 (Priority: P3) + +作为项目治理人员，我需要这次整合留下可追溯的基线、验证和结论工件，这样后续 `/speckit.plan`、任务拆解和验收结论都能直接复用，不再重复做同一轮对齐判断。 + +**Why this priority**: 没有基线和验证工件，正式文档即使更新，也难以证明它对应的是哪一版实现和哪些证据。 + +**Independent Test**: 只检查 `specs/007-sys009-design-align/` 下的工件与管理台账，即可确认本轮使用的代码基线、核对过的证据路径以及最终结论。 + +**Acceptance Scenarios**: + +1. **Given** 本轮需要引用外部设计与当前代码，**When** 验证结束，**Then** 必须能从工件中看到代码基线、证据路径、结论和未闭环项。 +2. **Given** 正式主文档发生重要更新，**When** 本轮收尾，**Then** `01_Project_Progress.md` 与 `03_Task_Checklist.md` 必须同步回写本次变更摘要和收尾状态。 + +--- + +### Edge Cases + +- 当 `water-bank-api-doc` 的接口设计比当前正式文档更细，但 backend 仅实现了其中一部分时，正式文档必须同时保留目标设计边界和当前实现状态，不能只保留其一。 +- 当外部设计文档的 OpenAPI 版本遗漏了对账、客户状态查询、取消送盘、状态查询等高级接口时，应回退到原始 Markdown 接口说明核对，而不是误判这些能力“不在设计范围”。 +- 当 backend 已有 `bk_*` 表族和后台管理控制器，但银行 app 侧接口仍是 TODO 时，文档必须避免把“后台对象存在”直接等同为“银行协同闭环完成”。 +- 当 frontend 只存在客户代扣资料维护入口而不存在银行批次、回盘、对账运营页面时，正式文档必须明确这是当前范围边界，而不是默认这些页面已落地。 + +## Assumptions + +- 本轮“整合 `SYS-009` 设计”是指回写到现有正式主文档体系，而不是创建新的正式交付主稿。 +- 当前实现对齐以 `water-backend` 为主要证据来源，因为银行协议接口、交易流水、批次、回盘、对账和结算对象都集中在 backend。 +- 对于 controller/service 中仍为 TODO 的能力，本轮会按“部分实现”或“文档先行”处理，而不会要求在本轮直接补代码。 +- `water-bank-api-doc` 是本轮银行接口语义的重要参考，但正式口径仍以本仓库主文档编号、术语和边界约束为准。 + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: 规格必须明确本轮将修改的正式主文档，并以现有主文档为唯一正式承接入口。 +- **FR-002**: 规格必须覆盖外部 `SYS-009` 来源中的关键银行能力簇，至少包括实时收费、缴费结果处理、代扣签约/解约、客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询、对账与结算。 +- **FR-003**: 规格必须定义每个关键能力簇在当前实现中的状态标签，且状态标签至少区分“已实现”“部分实现”“文档先行”三类。 +- **FR-004**: 规格必须要求正式文档中的接口、时序、数据对象和模块描述与当前 backend 的 `bk_transaction*`、`bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_batch` 等对象口径一致。 +- **FR-005**: 规格必须要求正式文档保持当前编号和引用体系稳定，不得为本轮整合发明新的并行编号规则或新的平行正式文档。 +- **FR-006**: 规格必须记录 backend 基线版本，并要求所有实现判断可追溯到具体代码路径和该基线版本。 +- **FR-007**: 规格必须限定本轮以文档修订和代码证据核对为主，不直接包含 backend 或 frontend 业务代码改造。 +- **FR-008**: 规格必须要求在正式文档中明确实时收费与银行代扣是不同协同路径，避免把查询/缴费、送盘/回盘、对账/结算混写为同一处理流程。 +- **FR-009**: 规格必须要求当外部设计与当前实现不一致时，正式文档优先表达当前可落地边界，并对未落地能力保留清晰的待实现说明。 +- **FR-010**: 规格必须要求正式文档同步说明 `REV-003`、`REV-008` 与 `SYS-009` 之间的职责边界，避免把营收业务规则、银行渠道协议和聚合支付职责混淆。 +- **FR-011**: 规格必须要求在本轮输出验证工件，至少包括代码基线、正式文档校验、backend 证据核对和最终结论。 +- **FR-012**: 规格必须要求重要正式文档修改完成后，更新 `docs/design/00_Management/01_Project_Progress.md` 的变更记录。 +- **FR-013**: 规格必须要求当本轮任务项达到可关闭状态时，更新 `docs/design/00_Management/03_Task_Checklist.md` 的任务说明。 +- **FR-014**: 规格必须要求对变更后的正式文档执行适用的最小校验动作，包括单文件校验、链接检查或 Mermaid 检查。 + +### Key Entities *(include if feature involves data)* + +- **Source Capability**: 外部 `water-bank-api-doc` 中定义的一个银行协同能力簇，例如实时收费、代扣签约、送盘、回盘、对账。 +- **Formal Document Section**: 本仓库正式主文档中承接 `SYS-009` 设计的章节或表格单元，是本轮最终交付的正式落点。 +- **Backend Evidence Item**: 用于证明当前实现状态的 controller、service、数据对象、建表 SQL 或管理入口。 +- **Alignment Verdict**: 对单个能力簇给出的实现结论，取值为“已实现”“部分实现”“文档先行”之一。 +- **Code Baseline**: 用于锚定本轮对齐判断的相邻代码仓提交版本。 +- **Verification Artifact**: 本轮在 `specs/007-sys009-design-align/` 下生成的基线、验证和最终结论文档。 + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 正式文档中至少明确 5 组 `SYS-009` 能力簇的承接口径，且每组能力簇都能映射到目标文档中的具体章节或表格位置。 +- **SC-002**: 每个被纳入正式文档的 `SYS-009` 能力簇都至少关联 1 个外部来源和 1 个当前代码证据，或明确标注其仅为文档先行能力。 +- **SC-003**: 评审人能够基于本轮工件独立判断实时收费、代扣签约/解约、送盘、回盘、对账、结算各自属于“已实现”“部分实现”还是“文档先行”。 +- **SC-004**: 本轮基线、文档验证、backend 证据核对和最终结论工件全部具备明确文件名和用途，后续无需重新定义验证结构即可进入 `/speckit.plan`。 +- **SC-005**: 本轮规格中不保留 `[NEEDS CLARIFICATION]` 标记，且范围边界、依赖来源、验证动作和台账更新责任均可直接执行。 diff --git a/specs/007-sys009-design-align/tasks.md b/specs/007-sys009-design-align/tasks.md new file mode 100644 index 0000000..15211a8 --- /dev/null +++ b/specs/007-sys009-design-align/tasks.md @@ -0,0 +1,195 @@ +# Tasks: SYS-009设计整合与实现对齐 + +**Input**: Design documents from `/specs/007-sys009-design-align/` +**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md + +**Validation**: Validation and evidence tasks are NOT optional. Every feature task set MUST include the applicable document validation, code validation, ledger-sync, and final-verdict tasks. + +**Organization**: Tasks are grouped by user story so each slice can be completed, reviewed, and validated independently. + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) +- Include exact file paths in descriptions + +## Path Conventions + +- Formal workflow: `water-docs/` +- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/` +- Governance documents: `docs/design/00_Management/` +- Feature artifacts: `specs/007-sys009-design-align/` +- Backend modules: `water-backend/...` +- Frontend modules: `water-frontend/...` + +## Phase 1: Scope, Baseline & Source Confirmation + +**Purpose**: Confirm the source-of-truth set, repo boundary, required reading set, and code baselines before editing anything. + +- [x] T001 阅读 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/01_Project_Progress.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/02_Delivery_Standards.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/03_Task_Checklist.md` +- [x] T002 阅读 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/02_Detailed_Design/12_REV_Detailed.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/01_Database_Design.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T003 [P] 阅读 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/04_Writing_Guide.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/10_AI_Retrieval_Whitelist.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/11_Main_Doc_Chapter_Index.md` +- [x] T004 Confirm target documents, target repos, user story priorities, and exact chapter targets from `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/spec.md` +- [x] T005 Confirm governing source-of-truth documents, range intersection basis, external references, and validation commands from `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/plan.md` +- [x] T006 [P] Record the stable repo baselines and key evidence anchors in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/baseline.md` +- [x] T007 [P] Confirm the formal alignment contract and verdict rules in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md` and `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md` + +--- + +## Phase 2: Shared Foundation + +**Purpose**: Establish the shared alignment baseline for docs, code evidence, and verification outputs. + +- [x] T008 Normalize capability names, verdict vocabulary, and `REV-003` / `REV-008` / `SYS-009` responsibility terms in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/research.md` +- [x] T009 [P] Prepare the implementation/evidence checklist and execution order in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/quickstart.md` +- [x] T010 [P] Prepare the final evidence output skeleton in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +--- + +## Phase 3: User Story 1 - 整合正式设计口径 (Priority: P1) 🎯 MVP + +**Goal**: 将外部 `SYS-009` 设计吸收进现有正式主文档，使正式评审不再依赖仓外资料。 + +**Independent Test**: 仅阅读 `12_REV_Detailed.md`、`03_Interface_Design.md`、`03_Summary_Design.md`，即可定位实时收费、签解约、送盘/回盘、状态查询、取消送盘、对账/结算的正式口径和章节入口。 + +### Implementation for User Story 1 + +- [x] T011 [US1] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/02_Detailed_Design/12_REV_Detailed.md`，补齐 `REV-003` 实时收费与 `REV-008` 代扣/托收/送盘/回盘/对账/结算的正式业务边界 +- [x] T012 [US1] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md`，补齐签约、解约、客户状态查询、送盘状态查询、取消送盘、回盘状态查询和对账文件规则 +- [x] T013 [US1] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`，同步 `SYS-009` 范围摘要和外部接口表的正式描述 +- [x] T014 [US1] 同步 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md` 中的正式落点结论，确保与主文档实际章节一致 +- [x] T015 [US1] 运行 `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` 并将结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T016 [US1] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 和 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` 并将结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +**Checkpoint**: User Story 1 is independently reviewable with formal `SYS-009` design integrated into the main documents. + +--- + +## Phase 4: User Story 2 - 对齐当前实现边界 (Priority: P2) + +**Goal**: 将当前 backend 的真实成熟度结论回写到正式文档和证据工件，避免高估 `SYS-009` 完成度。 + +**Independent Test**: 对照正式文档与 `final-verdict.md`，评审人能够独立判断 `PayCeb`、`BankWithholding`、`BankCollection`、`bk_*` 表族和后台管理入口分别处于什么成熟度。 + +### Implementation for User Story 2 + +- [x] T017 [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/payceb/PayCebController.java` 和 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/payceb/PayCebServiceImpl.java`，确认实时收费查询/缴费/对账的成熟度结论 +- [x] T018 [P] [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankwithholding/BankWithholdingController.java` 和 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingServiceImpl.java`，确认代扣签解约与其余接口的成熟度结论 +- [x] T019 [P] [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankcollection/BankCollectionController.java` 和 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankcollection/BankCollectionServiceImpl.java`，确认托收平行链路的成熟度结论 +- [x] T020 [P] [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/docs/建表sql.sql` 与 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/admin/` 下后台管理入口，确认 `bk_*` 表族和资源管理层边界 +- [x] T021 [US2] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/01_Database_Design.md`，补充 `bk_*` 表族“对象层齐备但业务编排仅部分实现”的边界说明 +- [x] T022 [US2] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`，将 `PayCeb`、`BankWithholding`、`BankCollection` 的真实成熟度回写为保守口径 +- [x] T023 [US2] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md`，固化本轮实现边界结论 +- [x] T024 [US2] 运行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 并将 backend 证据核对结果写入 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T025 [US2] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 和 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` 并将结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +**Checkpoint**: User Story 2 is independently reviewable and all maturity statements are tied to concrete backend evidence. + +--- + +## Phase 5: User Story 3 - 形成可审计证据链 (Priority: P3) + +**Goal**: 形成可复用的基线、验证、台账和交付摘要，使后续任务和验收可以直接沿用。 + +**Independent Test**: 仅检查 `specs/007-sys009-design-align/` 和治理台账，即可确认本轮基线、修订范围、验证动作和剩余未闭环项。 + +### Implementation for User Story 3 + +- [x] T026 [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/baseline.md`，确认最终使用的 backend/frontend 基线和关键证据路径 +- [x] T027 [P] [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/quickstart.md`，使执行顺序、验证命令和回填位置与实际修订结果一致 +- [x] T028 [P] [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/research.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/data-model.md`，确保研究结论和实体模型与最终正式口径一致 +- [x] T029 [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/01_Project_Progress.md`，记录本轮 `SYS-009` 设计整合与实现对齐变更摘要 +- [x] T030 [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/03_Task_Checklist.md`，回写本轮任务闭环状态和后续待办边界 +- [x] T031 [US3] 复核 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/01_Project_Progress.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/03_Task_Checklist.md` 的更新内容，并将治理同步结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T032 [US3] 汇总已修改文件、校验结果、成熟度结论和剩余风险到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +**Checkpoint**: All planning evidence, governance records, and final conclusions are independently reviewable. + +--- + +## Final Phase: Verification & Closure + +**Purpose**: Ensure repository-wide consistency, baseline traceability, and final verdict output. + +- [x] T033 [P] Re-check source-of-truth alignment across `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`, `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/01_Database_Design.md`, and `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T034 [P] Run `make check-links` and `make validate-mermaid` and record the repository-wide results in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T035 Re-check backend baseline SHAs, evidence citations, and governance sync results in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/baseline.md` and `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Phase 1: Scope, Baseline & Source Confirmation**: No dependencies; MUST finish before edits +- **Phase 2: Shared Foundation**: Depends on Phase 1 and MUST finish before user stories +- **Phase 3: User Story 1**: Depends on Phase 2; MVP slice +- **Phase 4: User Story 2**: Depends on Phase 3 because mature capability wording must align to the integrated formal design +- **Phase 5: User Story 3**: Depends on Phase 3 and Phase 4 because evidence and governance must reflect final doc/evidence state +- **Final Phase**: Depends on all selected user stories being complete + +### User Story Completion Order + +`US1 -> US2 -> US3` + +### Within Each User Story + +- Complete formal doc edits before validation +- Complete backend evidence inspection before maturity wording is finalized +- Complete governance updates after document and evidence conclusions stabilize +- Complete final verdict updates after validation and ledger sync are done + +### Parallel Opportunities + +- `T003`, `T006`, and `T007` can run in parallel after baseline reading +- `T009` and `T010` can run in parallel +- In US2, `T018`, `T019`, and `T020` can run in parallel because they inspect different capability slices +- In US3, `T027` and `T028` can run in parallel because they touch different feature artifacts +- In the final phase, `T033` and `T034` can run in parallel + +## Parallel Execution Examples + +### User Story 1 + +```text +Run T015 after T011 completes +Run T016 after T012 and T013 complete +``` + +### User Story 2 + +```text +Run T018, T019, and T020 together +Run T021 and T022 after T017-T020 complete +Run T023-T025 after T021 and T022 complete +``` + +### User Story 3 + +```text +Run T027 and T028 together +Run T029 and T030 after T026-T028 complete +Run T031 after T029 and T030 complete +Run T032 after T031 complete +``` + +## Implementation Strategy + +### MVP First + +1. Finish Phase 1 and Phase 2 +2. Deliver US1 only: 先完成正式设计整合，让主文档成为单一评审入口 +3. Validate US1 before moving to US2 + +### Incremental Delivery + +1. US1: 正式设计口径收拢 +2. US2: 当前实现成熟度对齐 +3. US3: 证据链和治理台账闭环 + +### Notes + +- Every task preserves the single-source-of-truth model in `water-docs` +- Archive and external docs are used for verification and traceability, not direct formal replacement +- `water-backend` only provides implementation evidence in this round +- Validation, evidence, and ledger tasks are mandatory and already included diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-code-conversion-dictionary-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-code-conversion-dictionary-v1.md new file mode 100644 index 0000000..e14d0b4 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-code-conversion-dictionary-v1.md @@ -0,0 +1,185 @@ +# Dictionary: REV-004 第一批次编码转换字典 v1 + +## 1. 目标 + +本字典用于补齐第一批次试迁中最容易导致字段映射失真的编码转换规则。 + +当前仅覆盖三类核心编码： + +- `PriceListId` +- `PriceCode` +- `PriceItemId` + +它们分别影响： + +- 账单主表中的调价号 / 调价快照承接 +- 账单主表与明细中的用水性质 / 价格模板承接 +- 明细中的费用组成承接 + +## 2. 使用原则 + +- 本字典当前是 v1 规划字典，不假定所有旧编码与新编码已经一一建立物理映射表。 +- 若当前 backend 已存在稳定编码主数据，应优先落到现有主数据对象。 +- 若当前尚未确认稳定编码表，则先保留“旧值 + 映射占位 + 追溯字段”，不要在脚本里硬编码不可验证的转换结果。 + +## 3. 编码转换规则总览 + +| 旧字段 | 旧语义 | 新承接字段 | 当前转换方式 | 当前状态 | 备注 | +| --- | --- | --- | --- | --- | --- | +| `PriceListId` | 调价号 / 水价调整编号 | `adjustmentSnapCode` | `legacy int -> new string code` | `needs-mapping` | 需要形成调价号到快照编码的转换字典 | +| `PriceCode` | 用水性质 / 价格类别编码 | `priceTemplateCode` | `legacy int -> new string template code` | `needs-mapping` | 需要形成旧用水性质到新价格模板编码的转换字典 | +| `PriceItemId` | 费用组成 ID | `costComponentCode` | `legacy int -> new string component code` | `needs-mapping` | 需要形成旧费用项到新费用组成编码的转换字典 | + +## 4. `PriceListId` 转换字典 + +### 4.1 承接目标 + +| 旧字段 | 新字段 | 说明 | +| --- | --- | --- | +| `AT_CHARGES.PriceListId` | `biz_charge.adjustmentSnapCode` | 账单主表调价快照编码 | +| `AT_CHARGE_DETAILS.PriceListId` | `biz_charge_detail.adjustmentSnapCode` | 账单明细调价快照编码 | + +### 4.2 当前转换策略 + +在未建立完整字典前，建议采用两段式处理： + +1. 迁移脚本先保留原值到映射层 +2. 主表字段使用可验证的新编码规则转换，若无法确定则标记待补 + +### 4.3 推荐映射结构 + +| 字段 | 说明 | +| --- | --- | +| `legacyPriceListId` | 旧调价号 | +| `targetAdjustmentSnapCode` | 新调价快照编码 | +| `mappingSource` | 来源：主数据 / 规则推导 / 手工补录 | +| `mappingStatus` | `planned / verified / unresolved` | +| `remark` | 备注 | + +### 4.4 当前脚本建议 + +- 若存在稳定调价快照表和唯一编码，可直接转换。 +- 若不存在稳定映射来源： + - `adjustmentSnapCode` 可先按约定规则生成占位值 + - 同时必须写入 `legacyPriceListId` + - `mappingStatus` 标记为 `unresolved` + +## 5. `PriceCode` 转换字典 + +### 5.1 承接目标 + +| 旧字段 | 新字段 | 说明 | +| --- | --- | --- | +| `AT_CHARGES.PriceCode` | `biz_charge.priceTemplateCode` | 账单主表价格模板编码 | +| `AT_CHARGE_DETAILS.PriceCode` | `biz_charge_detail.priceTemplateCode` | 账单明细价格模板编码 | + +### 5.2 当前转换策略 + +`PriceCode` 在旧模型里是整数型“用水性质”，在新模型里更接近字符串型模板编码。 + +因此本轮不建议简单字符串化后直接当正式编码使用，而应采用： + +- `legacyPriceCode` 保留旧值 +- `targetPriceTemplateCode` 记录新值 +- 明确映射来源 + +### 5.3 推荐映射结构 + +| 字段 | 说明 | +| --- | --- | +| `legacyPriceCode` | 旧用水性质编码 | +| `targetPriceTemplateCode` | 新价格模板编码 | +| `priceCategoryName` | 可选，用于人工核对 | +| `mappingSource` | 来源：价格模板表 / 规则推导 / 手工补录 | +| `mappingStatus` | `planned / verified / unresolved` | + +### 5.4 当前脚本建议 + +- 若已有价格模板主数据且存在旧编码字段，优先按主数据表映射。 +- 若无稳定映射来源，暂不把脚本写成“旧值转字符串”这种伪映射。 +- 所有无法确认的值必须落差异清单。 + +## 6. `PriceItemId` 转换字典 + +### 6.1 承接目标 + +| 旧字段 | 新字段 | 说明 | +| --- | --- | --- | +| `AT_CHARGE_DETAILS.PriceItemId` | `biz_charge_detail.costComponentCode` | 明细费用组成编码 | + +### 6.2 当前转换策略 + +`PriceItemId` 旧模型是费用组成主键，当前新模型更偏编码型字段 `costComponentCode`。 + +这类转换比 `PriceListId` 和 `PriceCode` 更敏感，因为它直接影响费用构成、统计汇总和开票明细。 + +### 6.3 推荐映射结构 + +| 字段 | 说明 | +| --- | --- | +| `legacyPriceItemId` | 旧费用组成 ID | +| `targetCostComponentCode` | 新费用组成编码 | +| `targetCostComponentName` | 新费用组成名称 | +| `mappingSource` | 来源：费用组成主数据 / 手工字典 | +| `mappingStatus` | `planned / verified / unresolved` | + +### 6.4 当前脚本建议 + +- 没有稳定费用组成字典前，不要直接迁移到正式 `costComponentCode`。 +- 可先写入映射表，待字典确认后再回填主表。 +- 对无法映射的费用项必须记录差异，不能静默丢弃。 + +## 7. 第一批次最小字典表建议 + +后续如果进入脚本实施，建议至少准备三张字典或等价数据集： + +| 字典名称 | 用途 | +| --- | --- | +| `legacy_price_list_mapping` | `PriceListId -> adjustmentSnapCode` | +| `legacy_price_code_mapping` | `PriceCode -> priceTemplateCode` | +| `legacy_price_item_mapping` | `PriceItemId -> costComponentCode` | + +每张字典至少包含： + +- `legacyCode` +- `targetCode` +- `targetName` +- `mappingSource` +- `mappingStatus` +- `remark` + +## 8. 当前 v1 的直接结论 + +### 8.1 可以先不阻塞试迁的项 + +- `PriceListId` +- `PriceCode` + +前提是： + +- 原值必须保留 +- 差异必须可追踪 +- 未确认映射不得伪造正式编码 + +### 8.2 不能随便糊过去的项 + +- `PriceItemId` + +因为它直接影响： + +- 费用组成 +- 开票明细 +- 金额汇总 +- 后续统计与审计 + +所以 `PriceItemId` 的字典确认优先级高于前两者。 + +## 9. 后续动作 + +本字典之后，建议继续补： + +1. 第一批次枚举值对照表 + 重点是 `PayState`、`FeeState`、`AccountState` + +2. 第一批次差异清单模板 + 专门记录编码映射缺口、无法确认项和人工补录项 diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-detailed-mapping-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-detailed-mapping-v1.md new file mode 100644 index 0000000..cd9fe73 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-batch1-detailed-mapping-v1.md @@ -0,0 +1,240 @@ +# Matrix: REV-004 第一批次真实迁移映射矩阵细化版 v1 + +## 1. 目标 + +本矩阵用于把第一批次迁移对象细化到“可以直接指导脚本设计”的程度。 + +第一批次范围限定为： + +- `AT_CHARGES` +- `AT_CHARGE_DETAILS` +- `CT_ACCOUNTS` + +本版重点不是覆盖旧表所有字段，而是先锁定： + +- 主键与核心业务标识 +- 核心业务字段 +- 关键状态字段 +- 必要关系字段 +- 映射落库要求 + +## 2. 第一批次总原则 + +- 账单主明细和账户对象属于在线主模型优先承接范围。 +- 旧主键和旧业务标识必须进入映射层，不允许只保留新主键。 +- 当前不能稳定落入主表的旧字段，先进入映射层或历史只读层，不强行污染主对象。 +- 第一批次试迁后必须能回答：原账单是谁、原账户是谁、新对象是谁、金额和状态是否一致。 + +## 3. 表级落位总览 + +| 旧表 | 目标主对象 | 目标映射对象 | 当前 backend 证据 | 当前结论 | +| --- | --- | --- | --- | --- | +| `AT_CHARGES` | `biz_charge` | `legacy_charge_mapping` | `ChargeDO.java` | 可直接作为第一批次主对象 | +| `AT_CHARGE_DETAILS` | `biz_charge_detail` | `legacy_charge_detail_mapping` | `ChargeDetailDO.java` | 可直接作为第一批次明细对象 | +| `CT_ACCOUNTS` | `biz_account` | `legacy_account_mapping` | `AccountDO.java` | 可直接作为第一批次账户对象 | + +## 4. `AT_CHARGES -> biz_charge` 细化映射 + +### 4.1 主键与标识 + +| 旧字段 | 新字段/位置 | 策略 | 备注 | +| --- | --- | --- | --- | +| `FeeId` | `biz_charge.id` | 直接承接或保留旧值映射 | 是否复用旧主键需由迁移脚本策略决定，但映射表必须保留 | +| `FeeId` | `legacy_charge_mapping.legacyId` | 必填 | 新旧账单主线标识 | +| 原账单号（如存在） | `legacy_charge_mapping.legacyBizNo` | 必填 | 若旧表无独立账单号，可用 `FeeId` 兼任 | +| 新账单号（如生成） | `legacy_charge_mapping.targetBizNo` | 选填 | 若新系统仅用主键，可暂为空 | + +### 4.2 核心业务字段 + +| 旧字段 | 新字段 | 策略 | 备注 | +| --- | --- | --- | --- | +| `RecordId` | `recordId` | 直接映射 | 抄表记录引用 | +| `BillMonth` | `billMonth` | 直接映射 | 核心账期字段 | +| `OrgId` | `deptId` | 转换映射 | 旧站点字段名与新部门字段名不同 | +| `BookId` | `bookId` | 直接映射 | 册本引用 | +| `BookSortIndex` | `bookSortIndex` | 直接映射 | 册内顺序 | +| `CustId` | `custId` | 直接映射 | 客户主键 | +| `CustCode` | `custCode` | 直接映射 | 客户编号 | +| `CustName` | `custName` | 直接映射 | 客户名称 | +| `CustAddress` | `custAddress` | 直接映射 | 客户地址 | +| `Populine` | `population` | 字段改名映射 | 旧字段拼写与新字段不同 | +| `PayMethod` | `payMethod` | 直接/枚举转换 | 需核对枚举值是否一致 | +| `LastReading` | `lastReading` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` | +| `LastChildReading` | `lastChildReading` | 类型转换映射 | 同上 | +| `LastReadWater` | `lastReadWater` | 类型转换映射 | 同上 | +| `LastReadDate` | `lastReadDate` | 直接映射 | 时间字段 | +| `LastReadStateId` | `lastReadStateId` | 直接映射 | 状态引用 | +| `Reading` | `reading` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` | +| `ChildReading` | `childReading` | 类型转换映射 | 同上 | +| `ReadWater` | `readWater` | 类型转换映射 | 同上 | +| `ReadDate` | `readDate` | 直接映射 | 时间字段 | +| `ReadStateId` | `readStateId` | 直接映射 | 状态引用 | +| `ReadTimes` | `readTimes` | 直接映射 | 抄次 | +| `MeterReaderId` | `meterReaderId` | 直接映射 | 抄表员 | +| `PriceListId` | `adjustmentSnapCode` 或扩展映射 | 暂按转换映射 | 旧调价号是 `int`，新对象用 `String adjustmentSnapCode` | +| `PriceCode` | `priceTemplateCode` | 转换映射 | 旧用水性质编码映射到新价格模板编码 | +| `TotalWater` | `totalWater` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` | +| `ReplaceWater` | `replaceWater` | 类型转换映射 | 同上 | +| `BillWater` | `billWater` | 类型转换映射 | 同上 | +| `BillAmount` | `billAmount` | 直接映射 | 金额核心字段 | +| `ExtendedAmount` | `extendedAmount` | 直接映射 | 应收金额核心字段 | +| `LastChange` | `lastChange` | 直接映射 | 零头字段 | +| `Change` | `change` | 直接映射 | 零头字段 | +| `BillerId` | `billerId` | 直接映射 | 开账人 | +| `BillDate` | `billDate` | 直接映射 | 开账时间 | +| `LateFeeBeginDate` | `lateFeeBeginDate` | 直接映射 | 滞纳金起算日 | +| `LateFee` | `lateFee` | 直接映射 | 核心金额字段 | +| `CashierId` | `cashierId` | 直接映射 | 收费员 | +| `PayDate` | `payDate` | 直接映射 | 收费时间 | +| `CheckoutDate` | `checkoutDate` | 直接映射 | 结账时间 | +| `ChargeMethod` | `chargeMethod` | 直接/枚举转换 | 需核对枚举 | +| `ChargeWay` | `chargeWay` | 直接/枚举转换 | 需核对枚举 | + +### 4.3 状态与结果字段 + +| 旧字段 | 新字段/位置 | 策略 | 备注 | +| --- | --- | --- | --- | +| `PayState` | `biz_charge.payState` | 状态转换 | 必须按状态矩阵归并 | +| `FeeState` | `biz_charge.feeState` 或 `legacyState` | 状态转换 + 保留旧值 | 若新字段无法完整表达，保留旧值 | +| `InvoiceState` | `biz_charge.invoiceState` + 发票映射层 | 状态转换 | 需与发票主对象一致 | +| `InvoiceError` | `biz_charge.invoiceError` | 直接映射 | 开票失败原因 | +| `PrintState` | `biz_charge.printState` | 直接映射 | 打印状态 | +| `PrintTimes` | `biz_charge.printTimes` | 直接映射 | 打印次数 | +| `LockNum` | `biz_charge.lockNum` | 直接映射 | 锁定编号 | +| `LockoutEndTime` | `biz_charge.lockoutEndTime` | 直接映射 | 锁定时间 | + +### 4.4 关系和追溯字段 + +| 旧字段 | 新字段/位置 | 策略 | 备注 | +| --- | --- | --- | --- | +| `AdjustType` | `biz_charge.adjustType` + `tracePayload.adjustType` | 直接映射 + 追溯保留 | 当前新对象已有该字段 | +| `ContrastFeeId` | `biz_charge.contrastFeeId` + `legacy_charge_mapping.relatedFeeId` | 直接映射 + 映射保留 | 调整前后关系 | +| `ParentFeeId` | `legacy_charge_mapping.sourceFeeId` | 追溯保留 | 新 `ChargeDO` 未见同名字段，必须进映射层 | +| `InvoiceCode` | `biz_charge.invoiceCode` | 直接映射 | 发票代码 | +| `InvoiceDate` | `biz_charge.invoiceDate` | 直接映射 | 开票日期 | +| `InvoiceNumber` | `biz_charge.invoiceNumber` | 直接映射 | 发票号码 | +| `RefundWater` | `biz_charge.refundWater` + `tracePayload.refundWater` | 直接映射 + 追溯保留 | 当前新对象已有该字段 | + +### 4.5 第一批次对 `AT_CHARGES` 的直接建议 + +- `AT_CHARGES` 可直接作为第一批次最优先迁移主表。 +- 需要额外设计： + - `PriceListId -> adjustmentSnapCode` + - `PriceCode -> priceTemplateCode` + - `ParentFeeId` 的映射层保留 + - `PayState / FeeState / InvoiceState` 的状态归并规则 + +## 5. `AT_CHARGE_DETAILS -> biz_charge_detail` 细化映射 + +### 5.1 主键与关系 + +| 旧字段 | 新字段/位置 | 策略 | 备注 | +| --- | --- | --- | --- | +| 明细主键 `Id` | `biz_charge_detail.id` | 直接承接或映射保留 | 视脚本主键策略决定 | +| `FeeId` | `biz_charge_detail.feeId` | 直接映射 | 必须保持主明细关系 | +| 明细主键 | `legacy_charge_detail_mapping.legacyId` | 必填 | 保留旧明细主键 | + +### 5.2 核心业务字段 + +| 旧字段 | 新字段 | 策略 | 备注 | +| --- | --- | --- | --- | +| `PriceListId` | `adjustmentSnapCode` | 转换映射 | 与主账一致，需要调价号转换 | +| `PriceCode` | `priceTemplateCode` | 转换映射 | 与主账一致 | +| `PriceDetailId` | `costAdjustmentId` 或扩展字段 | `tbd` | 需进一步确认新字段语义是否等价 | +| `PriceItemId` | `costComponentCode` | 转换映射 | 旧费用组成 ID 到新费用组成编码 | +| `CalcMode` | `calcMode` | 直接映射 | 计费方式 | +| `LevelType` | `levelType` | 直接映射 | 阶梯模式 | +| `LevelIndex` | `levelIndex` | 直接映射 | 阶梯级别 | +| `StartMonth` | `startMonth` | 直接映射 | 开始月份 | +| `EndMonth` | `endMonth` | 直接映射 | 结束月份 | +| `StartWater` | `startWater` | 类型转换映射 | 旧 `int` 到新 `BigDecimal` | +| `EndWater` | `endWater` | 类型转换映射 | 同上 | +| `SettleMethod` | `settleMethod` | 直接映射 | 分摊方式 | +| `SettleValues` | `settleValues` | 类型转换映射 | 旧 `float` 到新 `BigDecimal` | +| `Price` | `price` | 直接映射 | 单价 | +| `Water` | `water` | 类型转换映射 | 应收水量 | +| `DiscountWater` | `discountWater` | 类型转换映射 | 优惠水量 | +| `WaterNum` | `waterNum` | 直接映射 | 水量系数 | +| `Money` | `money` | 直接映射 | 明细金额 | +| `State` | `state` | 状态转换 | 明细状态需核对枚举 | +| `IsPreferential` | `isPreferential` | 直接映射 | 是否优惠 | +| `BasicNumber` | `basicNumber` | 直接映射 | 基数 | +| `InvoicedState` | `invoicedState` | 状态转换 | 开票状态 | +| `DiscountMoney` | `discountMoney` | 直接映射 | 优惠金额 | +| `OriginalMoney` | `originalMoney` | 直接映射 | 优惠前金额 | +| `IsWaterOver` | `isWaterOver` | 直接映射 | 是否超计划 | +| `ItemInvoiceError` | `itemInvoiceError` | 直接映射 | 明细开票错误 | +| `ItemInvoiceState` | `itemInvoiceState` | 直接映射 | 明细开票状态 | +| `ItemInvoiceType` | `itemInvoiceType` | 直接映射 | 明细开票类型 | + +### 5.3 第一批次对 `AT_CHARGE_DETAILS` 的直接建议 + +- 明细对象整体与 `ChargeDetailDO` 对应度较高，可以直接进入第一批次。 +- 主要需要额外确认的点： + - `PriceDetailId -> costAdjustmentId` 是否语义等价 + - `PriceItemId -> costComponentCode` 的编码转换规则 + +## 6. `CT_ACCOUNTS -> biz_account` 细化映射 + +### 6.1 主键与关系 + +| 旧字段 | 新字段/位置 | 策略 | 备注 | +| --- | --- | --- | --- | +| `AccountId` | `biz_account.id` | 直接承接或映射保留 | 是否复用旧主键由脚本策略决定 | +| `AccountId` | `legacy_account_mapping.legacyId` | 必填 | 账户迁移主线 | +| 原账户编号 | `legacy_account_mapping.legacyBizNo` | 选填 | 若旧系统无独立业务账户号，可用主键兼任 | +| `CustId` | `biz_account.custId` | 直接映射 | 账户与客户关系核心字段 | + +### 6.2 核心业务字段 + +| 旧字段 | 新字段 | 策略 | 备注 | +| --- | --- | --- | --- | +| `Deposit` | `deposit` | 直接映射 | 预存余额 | +| `UnCheckMoney` | `uncheckMoney` | 直接映射 | 未到账金额 | +| `Overdraft` | `overdraft` | 直接映射 | 透支额度 | +| `AccountState` | `status` | 状态转换 | 旧账户状态需与新 `status` 枚举核对 | + +### 6.3 第一批次对 `CT_ACCOUNTS` 的直接建议 + +- `CT_ACCOUNTS` 与 `AccountDO` 的字段匹配度较高，可以直接进入第一批次。 +- 关键点不在字段缺失，而在于： + - `AccountState -> status` 的枚举值核对 + - 账户与客户主数据的一致性校验 + +## 7. 第一批次试迁时必须同步落库的映射对象 + +建议至少同时生成以下映射记录： + +| 映射对象 | 作用 | +| --- | --- | +| `legacy_charge_mapping` | 保留旧账单到新账单关系 | +| `legacy_charge_detail_mapping` | 保留旧账单明细到新明细关系 | +| `legacy_account_mapping` | 保留旧账户到新账户关系 | + +每条映射记录最少包括： + +- `legacyTable` +- `legacyId` +- `legacyBizNo` +- `targetDomain` +- `targetId` +- `targetBizNo` +- `migrationBatchNo` +- `mappingStatus` + +## 8. 第一批次最小脚本出口条件 + +在进入实际试迁脚本开发前，第一批次至少应满足： + +- `AT_CHARGES` 字段映射规则已稳定 +- `AT_CHARGE_DETAILS` 字段映射规则已稳定 +- `CT_ACCOUNTS` 字段映射规则已稳定 +- 三类主对象的状态映射规则已确认 +- 三类主对象的标识映射结构已确认 + +## 9. 当前仍待补的小项 + +本版之后，第一批次还建议继续补两项： + +1. `PriceListId / PriceCode / PriceItemId` 的编码转换字典 +2. `PayState / FeeState / AccountState` 的枚举值对照表 diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-field-mapping-matrix-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-field-mapping-matrix-v1.md new file mode 100644 index 0000000..4dd8329 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-field-mapping-matrix-v1.md @@ -0,0 +1,140 @@ +# Matrix: REV-004 旧字段到新字段映射矩阵 v1 + +## 1. 说明 + +本矩阵用于在“旧对象 -> 新对象”映射基础上，进一步明确关键字段如何承接、转换和保留。 + +本版只覆盖迁移中最关键的字段： + +- 主键与业务标识 +- 账期与客户标识 +- 金额 / 水量 / 滞纳金 +- 退款 / 冲正 / 坏账相关核心字段 +- 账户余额与流水字段 +- 发票状态与票据标识字段 +- 历史追溯必须保留的流程痕迹字段 + +## 2. 字段级承接策略说明 + +- `direct`：可直接映射到现有新字段 +- `transform`：需要转换、重算或状态归并 +- `mapping-only`：不进入在线主对象，仅写入映射层 +- `readonly-retain`：只在历史只读层保留 +- `tbd`：当前需要进一步核对 backend 真实字段或实现 + +## 3. 字段映射矩阵 + +| 旧表 | 旧字段 | 字段语义 | 新对象 | 新字段 / 承接位置 | 承接策略 | 说明 | +| --- | --- | --- | --- | --- | --- | --- | +| `AT_CHARGES` | `FeeId` | 账单主键 | `ChargeAggregate` | `biz_charge.id` + `legacy_charge_mapping.legacyId` | `direct` + `mapping-only` | 新旧账单主键必须双保留 | +| `AT_CHARGES` | `BillMonth` | 账务年月 | `ChargeAggregate` | `biz_charge.billMonth` | `direct` | 核心账期字段直接承接 | +| `AT_CHARGES` | `CustId` | 客户 ID | `ChargeAggregate` | `biz_charge.custId` | `direct` | 与客户主数据联动 | +| `AT_CHARGES` | `CustCode` | 客户编号 | `ChargeAggregate` | `biz_charge.custCode` | `direct` | 用于查询和迁移验收 | +| `AT_CHARGES` | `BillWater` | 开账水量 | `ChargeAggregate` | `biz_charge.billWater` | `direct` | 核心业务量字段 | +| `AT_CHARGES` | `BillAmount` | 开账金额 | `ChargeAggregate` | `biz_charge.billAmount` | `direct` | 与应收金额共同校验 | +| `AT_CHARGES` | `ExtendedAmount` | 应收金额 | `ChargeAggregate` | `biz_charge.extendedAmount` | `direct` | 迁移金额核对核心字段 | +| `AT_CHARGES` | `LateFee` | 滞纳金 | `ChargeAggregate` | `biz_charge.lateFee` | `direct` | 需与减免对象联动核查 | +| `AT_CHARGES` | `PayState` | 收费状态 | `ChargeAggregate` | `biz_charge.payState` + 状态映射表 | `transform` | 需与新收费状态语义核对 | +| `AT_CHARGES` | `InvoiceState` | 开票状态 | `ChargeAggregate` / `InvoiceRelation` | `biz_charge.invoiceState` + `legacy_invoice_mapping` | `transform` | 账单侧状态与发票主对象需联动校验 | +| `AT_CHARGES` | `ParentFeeId` | 调整原始 FeeId | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 是迁移后追溯原账单的关键字段 | +| `AT_CHARGES` | `ContrastFeeId` | 对应费用编号 | `CompatibilityMappingRecord` | `legacy_charge_mapping.relatedFeeId` | `mapping-only` | 用于比对调整前后关系 | +| `AT_CHARGES` | `AdjustType` | 调整类型 | `AccountingEvidence` / 映射层 | `tracePayload.adjustType` | `transform` | 当前新模型统一挂场景，不建议原样主表承接 | +| `AT_CHARGES` | `RefundWater` | 退补水量 | `AccountingEvidence` | `tracePayload.refundWater` | `mapping-only` | 与退款/调整场景相关，保留追溯值 | +| `AT_CHARGE_DETAILS` | `FeeId` | 账单外键 | `ChargeAggregate` | `biz_charge_detail.chargeId` | `direct` | 必须保持主明细关系 | +| `AT_CHARGE_DETAILS` | `PriceItemId` | 费用组成 | `ChargeAggregate` | `biz_charge_detail.priceItemId` | `direct` | 核心费用项映射 | +| `AT_CHARGE_DETAILS` | `Water` | 应收水量 | `ChargeAggregate` | `biz_charge_detail.water` | `direct` | 明细层水量 | +| `AT_CHARGE_DETAILS` | `Money` | 明细金额 | `ChargeAggregate` | `biz_charge_detail.money` | `direct` | 明细层金额 | +| `AT_CHARGE_DETAILS` | `InvoicedState` | 明细开票状态 | `InvoiceRelation` / 映射层 | `legacy_invoice_mapping.detailInvoiceState` | `mapping-only` | 明细开票状态优先保留关系层 | +| `CT_ACCOUNTS` | `AccountId` | 账户主键 | `AccountBalance` | `biz_account.id` + `legacy_account_log_mapping.accountLegacyId` | `direct` + `mapping-only` | 账户主键双保留 | +| `CT_ACCOUNTS` | `CustId` | 客户 ID | `AccountBalance` | `biz_account.custId` | `direct` | 账户与客户绑定核心字段 | +| `CT_ACCOUNTS` | `Deposit` | 预存余额 | `AccountBalance` | `biz_account.deposit` | `direct` / `tbd` | 需最终确认 backend 账户表字段命名 | +| `CT_ACCOUNTS` | `UnCheckMoney` | 未到账金额 | `AccountBalance` | `biz_account.unCheckMoney` 或扩展字段 | `tbd` | 需确认新系统是否有对应字段 | +| `CT_ACCOUNTS` | `Overdraft` | 透支额度 | `AccountBalance` | `biz_account.overdraft` 或扩展字段 | `tbd` | 需核实现有表结构 | +| `CT_ACCOUNT_LOGS` | `AccLogId` | 账户流水主键 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.legacyId` | `mapping-only` | 流水主键必须可追溯 | +| `CT_ACCOUNT_LOGS` | `PayDetailId` | 来源编号 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.sourceDetailId` | `mapping-only` | 用于关联收费或退款来源 | +| `CT_ACCOUNT_LOGS` | `AccLogType` | 暂收类型 | `HistoricalReadonlyRecord` | `legacy_account_log_mapping.legacyType` | `readonly-retain` | 新模型当前未显式在线承接该分类 | +| `CT_ACCOUNT_LOGS` | `AccInOut` | 进出标志 | `HistoricalReadonlyRecord` | `legacy_account_log_mapping.inOutFlag` | `readonly-retain` | 作为账户流水查询语义保留 | +| `CT_ACCOUNT_LOGS` | `LastDeposit` | 上次余额 | `HistoricalReadonlyRecord` | `summarySnapshot.lastDeposit` | `readonly-retain` | 用于迁移验收对账 | +| `CT_ACCOUNT_LOGS` | `InOutMoney` | 收支金额 | `HistoricalReadonlyRecord` / `Transaction` | `summarySnapshot.inOutMoney` | `readonly-retain` / `tbd` | 需结合新交易对象最终判定 | +| `CT_ACCOUNT_LOGS` | `Deposit` | 本次余额 | `HistoricalReadonlyRecord` | `summarySnapshot.deposit` | `readonly-retain` | 用于余额核对 | +| `PM_ACCOUNT_RECORD_DETAILS` | `CustId` | 客户 ID | `AccountingEvidence` | `tracePayload.custId` | `mapping-only` | 退款详情应保留客户维度 | +| `PM_ACCOUNT_RECORD_DETAILS` | `RefundDeposit` | 退款金额 | `AccountingEvidence` / `Transaction` | `tracePayload.refundAmount` + 交易对象金额 | `transform` | 核心退款金额，需和新交易金额对齐 | +| `PM_ACCOUNT_RECORD_DETAILS` | `Deposit` | 原预存金额 | `AccountingEvidence` | `tracePayload.originalDeposit` | `mapping-only` | 用于退款前后余额审计 | +| `PM_ACCOUNT_RECORD_DETAILS` | `AccountLogId` | 被调整流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.sourceAccountLogId` | `mapping-only` | 退款场景断链风险最高字段之一 | +| `PM_ACCOUNT_RECORD_DETAILS` | `TargetAccountLogId` | 目标流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.targetAccountLogId` | `mapping-only` | 用于转退款 / 转销账链路追溯 | +| `PM_ACCOUNT_RECORD_DETAILS` | `ProcType` | 处理方式 | `AccountingResult` / 映射层 | `tracePayload.procType` | `transform` | 当前新模型只保留统一结果位，原处理方式需保留映射 | +| `PM_AMOUNT_RECORD_DETAILS` | `FeeId` | 原账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 调整前账单引用 | +| `PM_AMOUNT_RECORD_DETAILS` | `NewFeeId` | 新账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.targetFeeId` | `mapping-only` | 调整后账单引用 | +| `PM_AMOUNT_RECORD_DETAILS` | `ExtendedAmount` | 调整前账单金额 | `AccountingEvidence` | `tracePayload.beforeExtendedAmount` | `mapping-only` | 核心差异字段 | +| `PM_AMOUNT_RECORD_DETAILS` | `NewExtendedAmount` | 调整后账单金额 | `AccountingEvidence` | `tracePayload.afterExtendedAmount` | `mapping-only` | 核心差异字段 | +| `PM_AMOUNT_RECORD_DETAILS` | `BillWater` | 调整前开账水量 | `AccountingEvidence` | `tracePayload.beforeBillWater` | `mapping-only` | 水量调整场景核心字段 | +| `PM_AMOUNT_RECORD_DETAILS` | `NewBillWater` | 调整后开账水量 | `AccountingEvidence` | `tracePayload.afterBillWater` | `mapping-only` | 水量调整场景核心字段 | +| `PM_AMOUNT_RECORD_DETAILS` | `Reading` | 原底码 | `AccountingEvidence` | `tracePayload.beforeReading` | `mapping-only` | 旧抄表依据必须保留 | +| `PM_AMOUNT_RECORD_DETAILS` | `NewReading` | 新底码 | `AccountingEvidence` | `tracePayload.afterReading` | `mapping-only` | 调整后依据必须保留 | +| `PM_PAYMENT_RECORD_DETAILS` | `FeeId` | 原账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 已销调整/冲正场景核心引用 | +| `PM_PAYMENT_RECORD_DETAILS` | `NewFeeId` | 新账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.targetFeeId` | `mapping-only` | 如有重构账单必须保留 | +| `PM_PAYMENT_RECORD_DETAILS` | `ActualMoney` | 实收金额 | `Transaction` | `bk_transaction.amount` 或扩展金额字段 | `transform` | 需与原交易金额比对 | +| `PM_PAYMENT_RECORD_DETAILS` | `DeductionAmount` | 抵扣金额 | `AccountingEvidence` | `tracePayload.deductionAmount` | `mapping-only` | 当前新模型未见统一在线字段 | +| `PM_PAYMENT_RECORD_DETAILS` | `AccountLogId` | 被调整流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.sourceAccountLogId` | `mapping-only` | 冲正场景关键追溯字段 | +| `PM_PAYMENT_RECORD_DETAILS` | `TargetAccountLogId` | 目标流水记录 | `CompatibilityMappingRecord` | `legacy_account_log_mapping.targetAccountLogId` | `mapping-only` | 冲正后目标记录追溯 | +| `PM_KNOTTY_RECORD_DETAILS` | `FeeId` | 账单 ID | `CompatibilityMappingRecord` | `legacy_charge_mapping.sourceFeeId` | `mapping-only` | 坏账与账单关系必须保留 | +| `PM_KNOTTY_RECORD_DETAILS` | `BillMonth` | 账务年月 | `AccountingEvidence` | `tracePayload.billMonth` | `mapping-only` | 用于坏账账龄与核对 | +| `PM_KNOTTY_RECORD_DETAILS` | `ExtendedAmount` | 账单应收金额 | `AccountingEvidence` | `tracePayload.extendedAmount` | `mapping-only` | 与坏账金额核对 | +| `PM_KNOTTY_RECORD_DETAILS` | `ProcType` | 处理方式 | `AccountingResult` / 映射层 | `tracePayload.procType` | `transform` | 坏账类型和结果需映射 | +| `IV_INVOICE_INFOS` | `Id` | 发票主键 | `InvoiceRecord` | `biz_invoice.id` + `legacy_invoice_mapping.legacyInvoiceId` | `direct` + `mapping-only` | 发票主键双保留 | +| `IV_INVOICE_INFOS` | `FeeId` | 费用 ID | `InvoiceRelation` | `legacy_invoice_mapping.sourceFeeId` | `mapping-only` | 账单与发票主关系核心字段 | +| `IV_INVOICE_INFOS` | `SerialNo` | 交易流水号 | `InvoiceRecord` / `Transaction` | `biz_invoice.sysRequestNo` 或关系映射 | `transform` | 需与当前发票协同请求号核对 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 发票状态 | `InvoiceRecord` | `biz_invoice.invoiceState` + 状态映射表 | `transform` | 必做旧状态到新状态映射 | +| `IV_INVOICE_INFOS` | `InvoiceCode` | 发票代码 | `InvoiceRecord` | `biz_invoice.invoiceCode` | `direct` | 核心票据标识 | +| `IV_INVOICE_INFOS` | `InvoiceNumber` | 发票号码 | `InvoiceRecord` | `biz_invoice.invoiceNumber` | `direct` | 核心票据标识 | +| `IV_INVOICE_INFOS` | `InvoiceDate` | 发票日期 | `InvoiceRecord` | `biz_invoice.invoiceDate` | `direct` | 核心票据时间 | +| `IV_INVOICE_INFOS` | `InvoicePath` | 电子票地址 | `InvoiceRecord` | `biz_invoice.fileUrl` 或等价字段 | `transform` | 需核对当前 DO/VO 字段名 | +| `IV_INVOICE_INFOS` | `CndnCode` | 原发票代码 | `InvoiceRecord` | `biz_invoice.originalInvoiceCode` 或扩展字段 | `tbd` | 当前新系统存在类似字段，但需最终核实命名 | +| `IV_INVOICE_INFOS` | `CndnNumber` | 原发票号码 | `InvoiceRecord` | `biz_invoice.originalInvoiceNumber` 或扩展字段 | `tbd` | 与红冲、作废场景强关联 | +| `IV_INVOICE_INFOS` | `LastTryTime` | 最后查询时间 | `InvoiceRecord` | `biz_invoice.lastTryTime` | `direct` | 当前 REV-005 已引入类似重试字段 | +| `IV_INVOICE_INFOS` | `NextTryTime` | 下一次查询时间 | `InvoiceRecord` | `biz_invoice.nextTryTime` | `direct` | 当前 REV-005 已引入类似重试字段 | +| `IV_INVOICE_INFOS` | `TryCount` | 查询次数 | `InvoiceRecord` | `biz_invoice.tryCount` | `direct` | 当前 REV-005 已引入类似字段 | + +## 4. 当前 v1 的直接落地建议 + +### 4.1 可直接进入字段级迁移设计的对象 + +- `AT_CHARGES` +- `AT_CHARGE_DETAILS` +- `IV_INVOICE_INFOS` + +这些对象的核心字段与当前新模型最接近，可以优先进入试迁字段设计。 + +### 4.2 必须补“映射层字段”的对象 + +- `CT_ACCOUNT_LOGS` +- `PM_ACCOUNT_RECORD_DETAILS` +- `PM_AMOUNT_RECORD_DETAILS` +- `PM_PAYMENT_RECORD_DETAILS` +- `PM_KNOTTY_RECORD_DETAILS` + +这些对象的关键价值不在于在线主字段一一映射，而在于： + +- 原账单引用 +- 原流水引用 +- 前后差异值 +- 处理方式 +- 原始处理痕迹 + +### 4.3 当前仍需进一步核实的字段 + +以下字段建议进入下一轮字段核实清单： + +- `CT_ACCOUNTS.Deposit / UnCheckMoney / Overdraft` 在当前 backend 的精确落点 +- `PM_PAY_DETAILS.ActualMoney` 到 `bk_transaction*` 的最终字段承接方式 +- `IV_INVOICE_INFOS.SerialNo` 与当前发票协同请求号 / 受理号的对应关系 +- `IV_INVOICE_INFOS.CndnCode / CndnNumber` 在当前新模型中的正式字段名 + +## 5. 后续动作 + +后续建议继续补两张矩阵： + +1. `旧状态 -> 新状态` 映射矩阵 +2. `新旧标识` 映射矩阵 + +字段级矩阵完成后，才适合正式设计迁移脚本的字段转换逻辑。 diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-gap-assessment-contract.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-gap-assessment-contract.md new file mode 100644 index 0000000..c417672 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-gap-assessment-contract.md @@ -0,0 +1,42 @@ +# Contract: REV-004 功能缺失判定矩阵 + +## 1. 目标 + +本合同用于统一判定旧账务对象相对当前 backend 的承接成熟度，避免将“旧表缺失”直接误判为“功能缺失”。 + +## 2. 判定字段 + +| Field | Required | Description | +| --- | --- | --- | +| `legacyObjectName` | Yes | 旧对象名称 | +| `legacyTable` | Yes | 旧表名 | +| `expectedCapability` | Yes | 旧对象期望承载的业务能力 | +| `currentVerdict` | Yes | `implemented` / `partial` / `readonly` / `missing` | +| `evidenceType` | Yes | `controller` / `service` / `do` / `mapping-doc` / `none` | +| `evidencePath` | Yes | 证据路径或文档路径 | +| `whyNotFullyImplemented` | No | 为什么不能判定为完全实现 | +| `recommendedHandling` | Yes | `reuse` / `extend` / `readonly-retain` / `implement-later` | +| `migrationImpact` | Yes | 对迁移的影响：低 / 中 / 高 | +| `notes` | No | 其他补充说明 | + +## 3. 判定规则 + +- `implemented`：当前 backend 已有稳定在线能力，且核心业务语义可被当前对象直接承接。 +- `partial`：已有部分能力、控制器、服务或数据对象，但无法完整表达旧模型全部语义。 +- `readonly`：不建议在线重建，只要求查询、比对和追溯能力。 +- `missing`：当前未看到稳定承接能力或映射出口，后续需补设计或开发。 + +## 4. 使用约束 + +- 不允许仅凭“未看到同名表”判定为 `missing`。 +- 必须优先核对统一场景入口、服务逻辑、日志承接和历史只读口径。 +- 对于旧审批流相关对象，若当前只保留审批能力位，可优先判为 `readonly` 或 `partial`，而不是默认 `missing`。 + +## 5. 示例 + +| legacyObjectName | currentVerdict | evidencePath | recommendedHandling | 说明 | +| --- | --- | --- | --- | --- | +| 营业账 | implemented | `ChargeDO.java` / `biz_charge` | reuse | 已有主对象承接 | +| 预存退款详情 | partial | `ChargeServiceImpl.adjustAccounting` + `bk_transaction*` | extend | 退款语义已有，旧细明台账未一对一落地 | +| 账单-呆坏账详情 | partial | `ChargeServiceImpl.adjustAccounting` | extend | 坏账申请语义已有，但旧细表未独立承接 | +| 特账明细 | missing | `BACKEND_TABLE_MAPPING.md` | implement-later or readonly-retain | 当前未见稳定承接 | diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-identifier-mapping-matrix-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-identifier-mapping-matrix-v1.md new file mode 100644 index 0000000..e5490bb --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-identifier-mapping-matrix-v1.md @@ -0,0 +1,104 @@ +# Matrix: REV-004 新旧标识映射矩阵 v1 + +## 1. 说明 + +本矩阵用于定义迁移后必须保留的新旧标识关系，确保以下能力不丢失： + +- 迁移验收对账 +- 历史明细追溯 +- 审计与问题定位 +- 旧单据到新业务对象的关系恢复 + +如果没有这张矩阵，即使数据迁过去，后续也很容易出现“查得到结果，但找不回原单据链”的问题。 + +## 2. 标识映射原则 + +- 每一类核心业务对象都必须保留“旧主键 + 旧业务单号 + 新主键 + 新业务单号”的最小映射能力。 +- 对于账单、流水、申请单、发票号等强业务标识，不允许只保留新值不保留旧值。 +- 若新系统不存在完全等价的新业务单号，至少保留新主键和映射批次号。 +- 新旧标识映射对象必须可按批次、对象类型和映射状态查询。 + +## 3. 映射矩阵 + +| 旧对象 | 旧主键 | 旧业务标识 | 新对象 | 新主键 | 新业务标识 | 映射承接层 | 最低保留要求 | 说明 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 营业账 | `FeeId` | 原账单号 / 历史账单编号 | `biz_charge` | `chargeId` | 新账单号或业务编号 | `mapping-layer` | `legacyId`、`targetId`、`legacyBizNo`、`targetBizNo` | 账单是迁移核查主线之一 | +| 营业账明细 | `Id` 或明细主键 | 无统一业务单号时可为空 | `biz_charge_detail` | `chargeDetailId` | 可选 | `mapping-layer` | `legacyId`、`targetId`、`sourceFeeId` | 明细至少能挂回主账单 | +| 账户 | `AccountId` | 原账户编号 | 账户承接对象 | `accountId` | 新账户编号 | `mapping-layer` | `legacyId`、`targetId`、`legacyBizNo`、`targetBizNo` | 预存余额迁移核查主线 | +| 账户流水 | `AccLogId` | 原流水号 / 原暂收流水号 | 账户流水承接对象或只读映射 | `accountLogId` 或映射主键 | 新流水号 | `mapping-layer` + `history-readonly` | `legacyId`、`legacyBizNo`、`targetId/targetBizNo` | 退款、冲正、转预存必须依赖该链路 | +| 收费汇总 | `CollectId` | 结账批次号 / 汇总编号 | 收费汇总承接对象 | `collectId` | 新汇总编号 | `mapping-layer` + `history-readonly` | `legacyId`、`targetId`、批次号 | 汇总核对主线 | +| 收费小计 | `SubtotalId` | 原小计编号 | 小计承接对象或只读映射 | `subtotalId` | 新小计编号 | `history-readonly` | `legacyId`、`targetId` | 一般不作为主业务单号，但需追溯 | +| 收费明细 | `DetailId` | `TradeCode` / `ThirdPartyNum` / 第三方流水号 | 交易对象 / 收费明细承接对象 | `transactionId` 或映射主键 | 新交易流水号 | `mapping-layer` | `legacyId`、`legacyBizNo`、`targetId`、`targetBizNo` | 收费、退款、冲正核查关键链路 | +| 退款账 | `RefundId` | 原退款单号 | 退款场景映射对象 | 映射主键 | 新调整单号 / 新退款单号 | `mapping-layer` | `legacyId`、`targetBizNo` | 若新系统无独立退款主键，至少保留新业务单号 | +| 预存退款汇总 | `Id` | 原申请单号 | 退款申请映射对象 | 映射主键 | 新调整单号 | `mapping-layer` + `history-readonly` | `legacyId`、`legacyBizNo`、`targetBizNo` | 旧申请单是历史审批追溯主线 | +| 预存退款详情 | `Id` | 原详情单号 | 退款明细映射对象 | 映射主键 | 新明细引用 | `mapping-layer` + `history-readonly` | `legacyId`、`sourceAccountLogId`、`targetAccountLogId` | 重点保留原流水到目标流水关系 | +| 调整减免汇总 | `Id` | 原调整申请单号 | 调整场景映射对象 | 映射主键 | 新调整单号 | `mapping-layer` + `history-readonly` | `legacyId`、`legacyBizNo`、`targetBizNo` | 金额/水量调整的历史入口 | +| 调整减免明细 | `Id` | 无统一业务单号 | 调整明细映射对象 | 映射主键 | 新账单引用 / 新明细引用 | `mapping-layer` | `legacyId`、`sourceFeeId`、`targetFeeId` | 前后账单链必须保留 | +| 价差调整汇总 | `Id` | 原价差调整申请单号 | 价差调整映射对象 | 映射主键 | 新调整单号 | `mapping-layer` + `history-readonly` | `legacyId`、`legacyBizNo`、`targetBizNo` | 若不单独在线化，也必须保留申请号映射 | +| 已销调整汇总 | `Id` | 原已销调整申请单号 | 冲正/调整映射对象 | 映射主键 | 新调整单号 | `mapping-layer` + `history-readonly` | `legacyId`、`legacyBizNo`、`targetBizNo` | 与收费结果链强关联 | +| 坏账汇总 | `Id` | 原坏账申请单号 | 坏账申请映射对象 | 映射主键 | 新调整单号 / 新申请单号 | `mapping-layer` + `history-readonly` | `legacyId`、`legacyBizNo`、`targetBizNo` | 坏账审批与生效查询主线 | +| 坏账明细 | `Id` | 无统一业务单号 | 坏账明细映射对象 | 映射主键 | 新账单引用 | `mapping-layer` | `legacyId`、`sourceFeeId` | 保证坏账记录能追到原账单 | +| 发票主表 | `Id` / `InvoiceInfoId` | `InvoiceCode + InvoiceNumber` / `OrderNo` / `SerialNo` | `biz_invoice` | `invoiceId` | 新申请单号 / 新受理号 / 新发票号 | `mapping-layer` | `legacyId`、`legacyBizNo`、`targetId`、`targetBizNo` | 发票查询、补打和对账主线 | +| 发票明细 | `Id` | 无统一业务单号 | 发票明细承接对象或只读映射 | `invoiceDetailId` | 可选 | `mapping-layer` + `history-readonly` | `legacyId`、`targetId`、`invoiceId` | 明细至少挂回发票主对象 | +| 营业账开票映射 | `Id` | 账单号 + 发票号组合 | 发票关系映射对象 | 映射主键 | 新账单号 + 新发票号组合 | `mapping-layer` | `sourceFeeId`、`targetChargeId`、`legacyInvoiceNo`、`targetInvoiceNo` | 发票关系迁移验收的核心对象 | + +## 4. 映射记录建议字段 + +建议统一的标识映射记录至少包含： + +| Field | Description | +| --- | --- | +| `mappingId` | 映射记录主键 | +| `legacySystem` | 原系统标识 | +| `legacyTable` | 旧表名 | +| `legacyId` | 旧主键 | +| `legacyBizNo` | 旧业务单号 / 流水号 / 发票号 | +| `targetDomain` | 新领域名称 | +| `targetId` | 新主键 | +| `targetBizNo` | 新业务单号 / 受理号 / 发票号 | +| `sourceLegacyId` | 源旧主键（用于前后关系对象） | +| `sourceTargetId` | 源新主键 | +| `mappingStatus` | `planned / migrated / verified / failed` | +| `migrationBatchNo` | 迁移批次号 | +| `verifiedAt` | 校验时间 | +| `remark` | 备注 | + +## 5. 当前 v1 的直接结论 + +### 5.1 必须优先落映射的主线标识 + +以下标识是迁移最容易断链、也最必须优先保留的： + +- `FeeId` +- `AccLogId` +- 收费流水号 / 第三方流水号 +- 旧调整申请单号 +- 旧坏账申请单号 +- 发票代码 + 发票号码 +- 发票申请单号 / 订单号 / 受理号 + +### 5.2 最容易被忽略但必须保留的关系标识 + +- `ParentFeeId` +- `ContrastFeeId` +- `AccountLogId` +- `TargetAccountLogId` +- 账单与发票映射关系中的组合标识 + +这些字段如果不在迁移时显式保留，后续几乎无法恢复“调整前后”“退款前后”“原交易与后续交易”“原账单与新账单”的链路。 + +### 5.3 对后续脚本设计的直接约束 + +迁移脚本设计时，不允许只写“插入新表”逻辑，还必须同步写： + +1. 标识映射入库逻辑 +2. 关系标识补链逻辑 +3. 批次号和映射状态回写逻辑 + +## 6. 后续动作 + +在对象、字段、状态、标识四张矩阵都具备后，下一步建议进入： + +1. 试迁校验清单 +2. 差异分类与复迁规则 +3. 批次化执行与回滚方案 diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-legacy-mapping-contract.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-legacy-mapping-contract.md new file mode 100644 index 0000000..952290f --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-legacy-mapping-contract.md @@ -0,0 +1,55 @@ +# Contract: REV-004 旧账务迁移映射矩阵 + +## 1. 目标 + +本合同用于统一旧账务对象到新系统承接对象的映射矩阵结构，供后续迁移实施、校验和差异定位复用。 + +## 2. 映射矩阵字段 + +| Field | Required | Description | +| --- | --- | --- | +| `legacyTable` | Yes | 旧表名 | +| `legacyObjectName` | Yes | 旧对象名称 | +| `legacyPrimaryKey` | Yes | 旧主键字段 | +| `legacyBusinessKey` | No | 旧业务单号 / 流水号 / 外部单号 | +| `legacyMeaning` | Yes | 业务语义说明 | +| `targetDomain` | Yes | 新承接领域 | +| `targetCarrier` | Yes | 新承接物理对象或只读对象 | +| `carrierLayer` | Yes | `online-main` / `mapping-layer` / `history-readonly` | +| `mappingType` | Yes | `one-to-one` / `many-to-one` / `one-to-many` / `readonly-only` | +| `statusMappingRequired` | Yes | 是否需要状态映射 | +| `identifierMappingRequired` | Yes | 是否需要新旧标识映射 | +| `historicalRetentionRequired` | Yes | 是否必须保留历史只读 | +| `evidenceSource` | Yes | backend / doc / archive 证据来源 | +| `migrationAction` | Yes | `migrate-online` / `retain-readonly` / `mapping-only` / `implement-later` | +| `riskNote` | No | 风险说明 | + +## 3. 填写规则 + +- 不允许只填写旧表名，不说明业务语义。 +- 每个旧对象必须明确进入哪个承接层。 +- 若 `carrierLayer = online-main`，必须明确在线主模型对象和主键映射规则。 +- 若 `carrierLayer = history-readonly`，必须明确最小查询维度和原始标识保留要求。 +- 若 `mappingAction = implement-later`，必须附功能缺失理由和后续建议。 + +## 4. 最小保留字段要求 + +对于需要迁移或只读保留的旧对象，最少保留以下类型字段： + +- 原单据标识 +- 原账单标识 +- 原流水标识 +- 处理类型 +- 处理原因 +- 处理前后金额或水量 +- 申请时间、审批时间、生效时间 +- 经办人 +- 附件或依据引用 + +## 5. 示例判定 + +| legacyObjectName | targetDomain | carrierLayer | migrationAction | 说明 | +| --- | --- | --- | --- | --- | +| 预存退款 | AccountingRequest / Transaction | online-main + history-readonly | migrate-online | 核心退款结果需在线承接，旧审批细节可只读保留 | +| 价差调整明细 | ChargeAggregate / OperationLog | online-main + mapping-layer | migrate-online | 调整结果进入账单主对象，旧明细字段保留映射 | +| 特账明细 | HistoricalReadonlyRecord | history-readonly | retain-readonly | 当前未见稳定在线承接能力 | diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-old-to-new-mapping-matrix-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-old-to-new-mapping-matrix-v1.md new file mode 100644 index 0000000..bcdfb26 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-old-to-new-mapping-matrix-v1.md @@ -0,0 +1,80 @@ +# Matrix: REV-004 旧表到新对象映射矩阵 v1 + +## 1. 说明 + +本矩阵用于回答三个问题： + +1. 旧表在新系统中由谁承接。 +2. 该承接属于在线主模型、兼容映射层还是历史只读层。 +3. 当前应判定为复用、扩展、只读保留还是后续补实现。 + +本矩阵是 v1，只覆盖 `REV-004` 迁移中最核心的账单、账户、收费、调整、退款、坏账、发票对象。 + +## 2. 承接层定义 + +- `online-main`：进入新系统在线主模型，后续继续参与业务处理。 +- `mapping-layer`：不直接承载在线业务，但保存新旧标识、状态和关系映射。 +- `history-readonly`：只提供查询、审计和迁移验收，不参与在线处理。 + +## 3. 映射矩阵 + +| 旧表名 | 旧对象名称 | 旧语义摘要 | 新承接领域 | 新承接对象 | 承接层 | 当前判定 | 建议动作 | 备注 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `AT_CHARGES` | 营业账 | 账单主对象，承接账期、应收、收费、开票、调整痕迹 | `ChargeAggregate` | `biz_charge` | `online-main` | `implemented` | `reuse` | 新系统账单主表核心承接对象 | +| `AT_CHARGE_DETAILS` | 营业账明细 | 账单费用组成、水量、金额、开票状态 | `ChargeAggregate` | `biz_charge_detail` | `online-main` | `implemented` | `reuse` | 明细层已存在稳定承接对象 | +| `CT_ACCOUNTS` | 账户信息 | 预存余额、未到账金额、透支额度 | `AccountBalance` | `biz_account` / 账户相关对象 | `online-main` | `partial` | `extend` | 需进一步确认与旧 `CT_ACCOUNTS` 字段对齐程度 | +| `CT_ACCOUNT_LOGS` | 账户流水 | 预存进出、余额变化、暂收流水 | `AccountTransaction` | `legacy_account_log_mapping` + 账户流水承接对象 | `mapping-layer` + `history-readonly` | `partial` | `extend` | 当前 `REV-004` 正式主口径未把账户流水建成核心在线对象 | +| `PM_PAY_COLLECTS` | 收费汇总 | 结账周期、收费总笔数、总金额、柜员/网点汇总 | `CollectionSummary` | `biz_collection` + 汇总查询结果 | `online-main` + `history-readonly` | `partial` | `extend` | 汇总语义可承接，旧统计台账宜只读保留 | +| `PM_PAY_SUBTOTALS` | 收费小计 | 按渠道、收费类型、收退标识的小计结果 | `CollectionSummary` | `biz_collection` + 汇总查询结果 | `history-readonly` | `readonly` | `retain-readonly` | 不建议为旧小计表单独在线重建 | +| `PM_PAY_DETAILS` | 收费明细 | 实收、实销、滞纳金、红冲关联、收费员 | `Transaction` / `CollectionDetail` | `bk_transaction*` + 收费结果关系 | `online-main` + `mapping-layer` | `partial` | `extend` | 需补旧收费明细到新交易对象的映射关系 | +| `AT_REFUNDS` | 退款账 | 退款金额、退款状态、退款时间、退款人 | `AccountingRequest` / `Transaction` | `IF-REV-007` 退款场景 + `bk_transaction*` | `online-main` + `mapping-layer` | `partial` | `extend` | 退款语义已有，旧退款账未见独立在线对象 | +| `PM_ACCOUNT_RECORDS` | 预存退款汇总 | 预存退款申请单、申请人、流程审批信息 | `AccountingRequest` | `legacy_finance_record_mapping` | `mapping-layer` + `history-readonly` | `partial` | `extend` | 在线保留申请语义，旧审批字段按只读保留 | +| `PM_ACCOUNT_RECORD_DETAILS` | 预存退款详情 | 客户、退款金额、原流水、目标流水、处理方式 | `AccountingEvidence` / `Transaction` | `legacy_finance_record_mapping` + `bk_transaction*` | `mapping-layer` + `history-readonly` | `partial` | `extend` | 需要重点保留原流水、目标流水和退款金额映射 | +| `PM_AMOUNT_RECORDS` | 调整减免汇总 | 水量/金额调整申请、原因、流程审批 | `AccountingRequest` | `IF-REV-007` 调整场景 + `legacy_finance_record_mapping` | `mapping-layer` + `history-readonly` | `partial` | `extend` | 新系统已有统一入口，但旧申请单结构未一对一承接 | +| `PM_AMOUNT_RECORD_DETAILS` | 调整减免明细 | 原账单、新账单、前后金额/水量、底码、累积量变化 | `AccountingEvidence` / `ChargeAggregate` | `biz_charge` / `biz_charge_detail` + 映射层 | `online-main` + `mapping-layer` | `partial` | `extend` | 关键是保留前后差异和新旧账单关联 | +| `PM_PRICE_RECORDS` | 价差调整汇总 | 调价差额修正申请、调价号、原因、审批 | `AccountingRequest` | `legacy_finance_record_mapping` | `mapping-layer` + `history-readonly` | `partial` | `extend` | 汇总申请宜按迁移映射保留 | +| `PM_PRICE_RECORD_DETAILS` | 价差调整明细 | 原账单、新账单、调价前后金额、滞纳金差额 | `ChargeAggregate` / `AccountingEvidence` | `biz_charge` / `biz_charge_detail` + 映射层 | `online-main` + `mapping-layer` | `partial` | `extend` | 语义已部分被账单重算能力承接 | +| `PM_PAYMENT_RECORDS` | 已销调整汇总 | 已收费后修正申请单、原因、流程 | `AccountingRequest` | `legacy_finance_record_mapping` | `mapping-layer` + `history-readonly` | `partial` | `extend` | 不建议按旧汇总表在线重建 | +| `PM_PAYMENT_RECORD_DETAILS` | 已销调整明细 | 原账单、新账单、实收金额、抵扣金额、退款人员 | `AccountingEvidence` / `Transaction` | `IF-REV-007` 冲正场景 + `bk_transaction*` + 映射层 | `online-main` + `mapping-layer` | `partial` | `extend` | 与冲正、退款、原交易校验强相关 | +| `PM_KNOTTY_RECORDS` | 呆坏账汇总 | 坏账申请单、申请原因、审批流程 | `AccountingRequest` | `IF-REV-007` 坏账场景 + `legacy_finance_record_mapping` | `mapping-layer` + `history-readonly` | `partial` | `extend` | 坏账申请语义已有，旧流程单需映射保留 | +| `PM_KNOTTY_RECORD_DETAILS` | 呆坏账明细 | 账单、账期、坏账金额、处理人、处理时间 | `AccountingEvidence` / `AccountingResult` | `biz_charge` + `biz_operat_log*` + 映射层 | `online-main` + `mapping-layer` | `partial` | `extend` | 需保留账龄、原因、结果和核销状态 | +| `PM_LATEFEE_RECORDS` | 违约金减免汇总 | 滞纳金减免申请、原因、审批 | `AccountingRequest` | `legacy_finance_record_mapping` | `mapping-layer` + `history-readonly` | `readonly` | `retain-readonly` | 当前一期不建议独立在线化 | +| `PM_LATEFEE_RECORD_DETAILS` | 违约金减免明细 | 原滞纳金、减免金额、调整后滞纳金 | `AccountingEvidence` | `legacy_finance_record_mapping` | `history-readonly` | `readonly` | `retain-readonly` | 保留明细追溯即可 | +| `IV_INVOICE_INFOS` | 发票信息表 | 发票状态、发票号、票据结果、查询重试、原票关联 | `InvoiceRecord` | `biz_invoice*` | `online-main` | `partial` | `reuse` + `extend` | 发票主对象已有，但旧字段需逐项核对 | +| `IV_INVOICE_DETAIL_INFOS` | 发票明细表 | 商品项、税率、税额、数量、单价 | `InvoiceRecord` | `biz_invoice*` + 历史明细映射 | `online-main` + `history-readonly` | `partial` | `extend` | 视当前 `biz_invoice` 明细承接能力决定在线化粒度 | +| `IV_CHARGE_INVOICE_MAPPINGS` | 营业账合并开票映射 | 账单与发票的多对多关系 | `InvoiceRelation` | `legacy_invoice_mapping` + 账单发票关系承接 | `mapping-layer` | `partial` | `extend` | 是迁移验收和历史补打的重要关系层 | + +## 4. 当前 v1 的直接判断 + +### 4.1 已有稳定在线承接基础的对象 + +- `AT_CHARGES` +- `AT_CHARGE_DETAILS` + +### 4.2 已有业务语义承接，但需要扩展映射与历史只读能力的对象 + +- `CT_ACCOUNTS` +- `CT_ACCOUNT_LOGS` +- `PM_PAY_*` +- `AT_REFUNDS` +- `PM_ACCOUNT_RECORD*` +- `PM_AMOUNT_RECORD*` +- `PM_PRICE_RECORD*` +- `PM_PAYMENT_RECORD*` +- `PM_KNOTTY_RECORD*` +- `IV_*` + +### 4.3 当前更适合历史只读保留的对象 + +- `PM_LATEFEE_RECORDS` +- `PM_LATEFEE_RECORD_DETAILS` + +## 5. 基于 v1 的后续动作 + +后续至少继续补三张矩阵： + +1. 旧字段到新字段映射矩阵 +2. 旧状态到新状态映射矩阵 +3. 新旧标识映射矩阵 + +在这三张矩阵完成前，不建议直接进入批量迁移脚本开发。 diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-status-mapping-matrix-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-status-mapping-matrix-v1.md new file mode 100644 index 0000000..e0f5ae9 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-status-mapping-matrix-v1.md @@ -0,0 +1,100 @@ +# Matrix: REV-004 旧状态到新状态映射矩阵 v1 + +## 1. 说明 + +本矩阵用于定义旧账务模型中的关键状态、处理方式和流程状态，如何映射到当前新系统对象中的状态表达。 + +本版重点覆盖： + +- 账单收费状态 +- 发票状态 +- 退款 / 冲正 / 坏账相关状态 +- 旧流程字段与新审批能力位的关系 + +## 2. 映射原则 + +- 不允许只保留旧状态值而不说明新状态语义。 +- 若新系统无法一一表达旧状态，必须采用“新状态 + 扩展追溯字段”组合承接。 +- 若旧状态只对历史查询有意义，不强制进入在线主状态机，但必须保留 `legacyState`。 +- 审批节点级状态本轮优先保留为历史只读，不在线复刻完整流转。 + +## 3. 状态映射矩阵 + +| 旧对象 | 旧字段 | 旧值/旧语义 | 新对象 | 新状态字段 | 新状态值/新语义 | 映射方式 | 备注 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `AT_CHARGES` | `PayState` | 未收费 | `ChargeAggregate` | `payState` | 未收费 | `direct/transform` | 需与当前 backend 枚举最终对齐 | +| `AT_CHARGES` | `PayState` | 已收费 | `ChargeAggregate` | `payState` | 已收费 | `direct/transform` | 是退款/冲正前置条件 | +| `AT_CHARGES` | `PayState` | 坏账 | `ChargeAggregate` | `payState` | `UNCOLLECTIBLE` / 坏账 | `transform` | 当前 backend 已见 `PayStateEnum.UNCOLLECTIBLE(-2)` | +| `AT_CHARGES` | `FeeState` | 正常 / 作废 / 特定旧费用状态 | `ChargeAggregate` | `chargeState` 或 `legacyState` | 当前有效状态 / 历史状态 | `transform` + `readonly-retain` | 若新系统无完全等价字段，则保留 `legacyState` | +| `AT_CHARGES` | `InvoiceState` | 未开票 | `InvoiceRecord` / `ChargeAggregate` | `invoiceState` | 待开票 / 未开票 | `transform` | 账单侧与发票主对象需保持一致 | +| `AT_CHARGES` | `InvoiceState` | 开票中 / 查询中 | `InvoiceRecord` | `invoiceState` | `PENDING` / 处理中 | `transform` | 当前新模型发票结果采用异步申请 + 查询兜底 | +| `AT_CHARGES` | `InvoiceState` | 已开票 | `InvoiceRecord` | `invoiceState` | `SUCCESS` | `transform` | 同时回写账单开票状态 | +| `AT_CHARGES` | `InvoiceState` | 开票失败 | `InvoiceRecord` | `invoiceState` | `FAIL` | `transform` | 失败原因保留在扩展字段或返回消息中 | +| `AT_CHARGES` | `InvoiceState` | 红冲 / 作废相关旧状态 | `InvoiceRecord` | `invoiceState` | `INVALID` / `RED_INK` | `transform` | 与 REV-005 二期口径保持一致 | +| `AT_REFUNDS` | `RefundState` | 申请中 / 未处理 | `AccountingResult` | `resultStatus` | `PENDING_APPROVAL` 或 `PENDING` | `transform` | 需结合是否存在审批链字段判定 | +| `AT_REFUNDS` | `RefundState` | 已退款成功 | `AccountingResult` | `resultStatus` | `SUCCESS` | `transform` | 同时要求 `writeBackStatus=WRITTEN` 或等价值 | +| `AT_REFUNDS` | `RefundState` | 退款失败 | `AccountingResult` | `resultStatus` | `FAIL` | `transform` | 保留失败原因 | +| `AT_REFUNDS` | `RefundState` | 已作废 / 已取消 | `HistoricalReadonlyRecord` | `legacyState` | 原状态保留 | `readonly-retain` | 不强制进入在线状态机 | +| `PM_ACCOUNT_RECORDS` | `State` | 正常 / 流程中 | `AccountingResult` | `resultStatus` | `PENDING_APPROVAL` / `PENDING` | `transform` | 汇总申请单优先映射为“待处理”状态 | +| `PM_ACCOUNT_RECORDS` | `State` | 作废 | `HistoricalReadonlyRecord` | `legacyState` | 原状态保留 | `readonly-retain` | 历史流程单保留只读即可 | +| `PM_AMOUNT_RECORDS` | `State` | 正常 | `AccountingResult` | `resultStatus` | `SUCCESS` / `PENDING_APPROVAL` | `transform` | 需结合是否已生效区分 | +| `PM_AMOUNT_RECORDS` | `State` | 作废 | `HistoricalReadonlyRecord` | `legacyState` | 原状态保留 | `readonly-retain` | 不强制在线复刻 | +| `PM_PRICE_RECORDS` | `State` | 正常 | `AccountingResult` | `resultStatus` | `SUCCESS` / `PENDING_APPROVAL` | `transform` | 调价差额生效逻辑需通过生效时间补充判断 | +| `PM_PRICE_RECORDS` | `State` | 作废 | `HistoricalReadonlyRecord` | `legacyState` | 原状态保留 | `readonly-retain` | 历史记录保留 | +| `PM_PAYMENT_RECORDS` | `State` | 正常 | `AccountingResult` | `resultStatus` | `SUCCESS` | `transform` | 主要对应冲正/已销调整结果 | +| `PM_PAYMENT_RECORDS` | `State` | 作废 | `HistoricalReadonlyRecord` | `legacyState` | 原状态保留 | `readonly-retain` | 历史记录保留 | +| `PM_KNOTTY_RECORDS` | `State` | 申请中 / 未审批 | `AccountingResult` | `resultStatus` | `PENDING_APPROVAL` | `transform` | 坏账申请典型待审批状态 | +| `PM_KNOTTY_RECORDS` | `State` | 已生效 / 已确认坏账 | `AccountingResult` | `resultStatus` | `SUCCESS` | `transform` | 同时影响账单收费状态为坏账 | +| `PM_KNOTTY_RECORDS` | `State` | 作废 / 驳回 | `AccountingResult` / `HistoricalReadonlyRecord` | `resultStatus` 或 `legacyState` | `FAIL` 或原状态保留 | `transform` + `readonly-retain` | 若驳回语义明确，优先映射为 `FAIL` | +| `PM_LATEFEE_RECORDS` | `State` | 正常 / 作废 | `HistoricalReadonlyRecord` | `legacyState` | 原状态保留 | `readonly-retain` | 当前一期不强制在线化 | +| `PM_ACCOUNT_RECORD_DETAILS` | `ProcType` | 转预存 | `AccountingResult` / `tracePayload` | `writeBackStatus` + `procType` | 结果已回写 + `TRANSFER_TO_DEPOSIT` | `transform` + `mapping-only` | 当前新模型需通过扩展字段保留旧处理方式 | +| `PM_ACCOUNT_RECORD_DETAILS` | `ProcType` | 转退款 | `AccountingResult` / `tracePayload` | `resultStatus` + `procType` | `SUCCESS` + `REFUND` | `transform` + `mapping-only` | 退款主语义进入结果状态，旧处理方式保留映射 | +| `PM_ACCOUNT_RECORD_DETAILS` | `ProcType` | 转销账 | `AccountingResult` / `tracePayload` | `writeBackStatus` + `procType` | 结果回写 + `WRITE_OFF` | `transform` + `mapping-only` | 当前新模型未见等价主字段，保留追溯值 | +| `PM_ACCOUNT_RECORD_DETAILS` | `ProcType` | 线下退款 | `AccountingResult` / `tracePayload` | `resultStatus` + `procType` | `SUCCESS/FAIL` + `OFFLINE_REFUND` | `transform` + `mapping-only` | 线下路径必须与普通退款区分 | +| `PM_AMOUNT_RECORD_DETAILS` | `ProcType` | 账务处理方式 | `AccountingResult` / `tracePayload` | `resultStatus` + `procType` | 统一结果位 + 原处理方式 | `transform` + `mapping-only` | 不建议原样进入主状态机 | +| `PM_PAYMENT_RECORD_DETAILS` | `ProcType` | 已销调整处理方式 | `AccountingResult` / `tracePayload` | `resultStatus` + `procType` | `SUCCESS/FAIL` + 原处理方式 | `transform` + `mapping-only` | 与冲正、退款结果强相关 | +| `PM_KNOTTY_RECORD_DETAILS` | `ProcType` | 呆坏账处理方式 | `AccountingResult` / `tracePayload` | `resultStatus` + `procType` | `PENDING_APPROVAL/SUCCESS/FAIL` + 原处理方式 | `transform` + `mapping-only` | 需结合坏账申请场景 | +| `PM_*_RECORDS` | `TaskId` | 审批流程任务 ID | `HistoricalReadonlyRecord` | `legacyTaskId` | 原值保留 | `readonly-retain` | 当前不在线复刻旧流程 | +| `PM_*_RECORDS` | `StepId` | 流程节点 ID | `HistoricalReadonlyRecord` | `legacyStepId` | 原值保留 | `readonly-retain` | 当前不在线复刻旧流程 | +| `PM_*_RECORDS` | `FlowRemark` | 流程审批意见 | `HistoricalReadonlyRecord` | `legacyFlowRemark` | 原值保留 | `readonly-retain` | 作为迁移验收与审计依据 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 未申请 / 初始 | `InvoiceRecord` | `invoiceState` | `INIT` / `PENDING` | `transform` | 需与当前发票流程状态定义对齐 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 已受理 / 查询中 | `InvoiceRecord` | `invoiceState` | `PENDING` | `transform` | 对应当前异步申请中间态 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 开票成功 | `InvoiceRecord` | `invoiceState` | `SUCCESS` | `transform` | 核心票据结果 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 开票失败 | `InvoiceRecord` | `invoiceState` | `FAIL` | `transform` | 失败消息保留在返回消息字段 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 已作废 | `InvoiceRecord` | `invoiceState` | `INVALID` | `transform` | 对应当前作废场景 | +| `IV_INVOICE_INFOS` | `InvoiceState` | 已红冲 | `InvoiceRecord` | `invoiceState` | `RED_INK` | `transform` | 对应当前红冲场景 | + +## 4. 当前 v1 的关键判断 + +### 4.1 可较稳定归并到新状态机的状态 + +- 账单收费状态中的“未收费 / 已收费 / 坏账” +- 发票状态中的“处理中 / 成功 / 失败 / 作废 / 红冲” +- 坏账申请中的“待审批 / 已生效 / 驳回” +- 退款结果中的“待处理 / 成功 / 失败” + +### 4.2 更适合保留为 `legacyState` 或历史只读的状态 + +- 各类旧汇总表中的“作废”细分状态 +- 旧流程引擎相关 `TaskId / StepId / FlowRemark` +- 旧处理方式 `ProcType` 中难以直接等价为新主状态的值 + +### 4.3 迁移实现时必须补的辅助字段 + +若要保证状态迁移后可追溯，建议至少补以下扩展字段： + +- `legacyState` +- `legacyTaskId` +- `legacyStepId` +- `legacyFlowRemark` +- `procType` +- `writeBackStatus` + +## 5. 后续动作 + +下一步建议补： + +1. `新旧标识映射矩阵` +2. `试迁校验清单` + +只有状态矩阵和标识矩阵都具备后，迁移脚本的转换规则才能稳定落地。 diff --git a/specs/008-rev004-legacy-finance-migration/contracts/rev004-trial-migration-checklist-v1.md b/specs/008-rev004-legacy-finance-migration/contracts/rev004-trial-migration-checklist-v1.md new file mode 100644 index 0000000..a5ea300 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/contracts/rev004-trial-migration-checklist-v1.md @@ -0,0 +1,168 @@ +# Checklist: REV-004 试迁校验清单 v1 + +**Purpose**: 用于指导 `REV-004` 旧账务数据试迁后的最小验收校验，确保数量、金额、关系、状态和追溯链条在试迁阶段就能被发现问题。 +**Created**: 2026-03-23 +**Feature**: [spec.md](/Volumes/Dpan/github/water-workspace/water-docs/specs/008-rev004-legacy-finance-migration/spec.md) + +## 1. 使用方式 + +- 本清单面向“试迁批次”使用，不是最终割接验收清单。 +- 每完成一个迁移批次，都应至少完成一次数量校验、金额校验、关系校验和抽样校验。 +- 若某项校验失败，不应直接进入下一批次，而应先定位是： + - 映射矩阵问题 + - 字段转换问题 + - 状态归并问题 + - 标识断链问题 + +## 2. 批次 1：账户与营业账主明细 + +### 2.1 数量校验 + +- [ ] `AT_CHARGES` 迁移记录数与 `biz_charge` 承接数一致，或差异已登记并有解释 +- [ ] `AT_CHARGE_DETAILS` 迁移记录数与 `biz_charge_detail` 承接数一致，或差异已登记并有解释 +- [ ] `CT_ACCOUNTS` 迁移记录数与账户承接对象一致，或差异已登记并有解释 + +### 2.2 金额校验 + +- [ ] 旧 `AT_CHARGES.ExtendedAmount` 汇总与新账单主对象应收金额汇总一致 +- [ ] 旧 `AT_CHARGES.BillAmount` 汇总与新账单主对象开账金额汇总一致 +- [ ] 旧 `AT_CHARGES.LateFee` 汇总与新账单主对象滞纳金汇总一致 +- [ ] 旧 `CT_ACCOUNTS.Deposit` 汇总与新账户余额汇总一致，或差异已解释 + +### 2.3 关系校验 + +- [ ] 每条迁移后的账单主记录都能找到对应明细记录 +- [ ] 每条旧账单都能通过映射表找到新账单主键 +- [ ] 若存在 `ParentFeeId` / `ContrastFeeId`，迁移后仍能定位原账单与目标账单关系 + +### 2.4 抽样校验 + +- [ ] 随机抽 3 笔普通账单，核对客户号、账期、金额、状态一致 +- [ ] 随机抽 2 笔带调整关系的账单，核对原账单与新账单映射关系一致 +- [ ] 随机抽 2 个账户，核对余额和客户关系一致 + +## 3. 批次 2：收费结果与交易对象 + +### 3.1 数量校验 + +- [ ] `PM_PAY_COLLECTS`、`PM_PAY_SUBTOTALS`、`PM_PAY_DETAILS` 迁移或承接数量已核对 +- [ ] 旧收费明细与新交易对象 / 收费承接对象数量差异已解释 +- [ ] 实时收费日志如仅保留历史只读，其归档记录数已校对 + +### 3.2 金额校验 + +- [ ] 旧收费明细 `ActualMoney` 汇总与新交易金额汇总一致 +- [ ] 旧收费明细 `SoldMoney` 汇总与新核销金额汇总一致，或差异已解释 +- [ ] 旧收费汇总 `TotalMoney` 与新汇总结果一致 +- [ ] 第三方交易流水涉及的金额抽样与新交易对象一致 + +### 3.3 关系校验 + +- [ ] 每笔收费明细都能追到原账单或新账单映射 +- [ ] 每笔收费明细的重要流水号都能追到新交易对象 +- [ ] 若存在红冲引用，原收费记录与后续记录链条未断裂 + +### 3.4 抽样校验 + +- [ ] 随机抽 3 笔柜台收费，核对原流水号、金额、收费时间、收费员 +- [ ] 随机抽 2 笔第三方渠道收费，核对第三方流水号与新交易号映射 +- [ ] 随机抽 1 笔红冲关联收费，核对原单与后续记录关系 + +## 4. 批次 3：账务处理历史对象 + +### 4.1 数量校验 + +- [ ] `PM_ACCOUNT_RECORD*`、`PM_AMOUNT_RECORD*`、`PM_PRICE_RECORD*`、`PM_PAYMENT_RECORD*`、`PM_KNOTTY_RECORD*` 已按对象分类统计 +- [ ] 每类旧账务处理对象都已判定为在线承接、历史只读或映射保留之一 +- [ ] 当前未在线承接的对象，历史只读记录数已归档核对 + +### 4.2 金额校验 + +- [ ] 预存退款金额汇总与新退款承接结果或映射结果一致 +- [ ] 调整前后金额差额与新账单差异值一致，或差异已解释 +- [ ] 坏账金额汇总与新坏账场景承接结果一致，或差异已解释 +- [ ] 已销调整 / 价差调整的关键差额字段已核对 + +### 4.3 关系校验 + +- [ ] 每笔退款类记录都能追到原流水和目标流水 +- [ ] 每笔调整类记录都能追到原账单和目标账单 +- [ ] 每笔坏账记录都能追到原账单和处理结果 +- [ ] `TaskId`、`StepId`、`FlowRemark` 等审批痕迹已进入历史只读或追溯字段 + +### 4.4 抽样校验 + +- [ ] 随机抽 2 笔预存退款，核对申请、原流水、目标流水、退款金额 +- [ ] 随机抽 2 笔金额/水量调整，核对前后金额/水量和原账单、新账单关系 +- [ ] 随机抽 1 笔已销调整或冲正，核对原收费记录与后续处理关系 +- [ ] 随机抽 1 笔坏账申请，核对账单、金额、审批痕迹、结果状态 + +## 5. 批次 4：发票对象与账单关系 + +### 5.1 数量校验 + +- [ ] `IV_INVOICE_INFOS` 迁移数与新发票承接对象数量一致，或差异已解释 +- [ ] `IV_INVOICE_DETAIL_INFOS` 若进入在线承接或历史只读，记录数已校对 +- [ ] `IV_CHARGE_INVOICE_MAPPINGS` 关系数已校对 + +### 5.2 金额校验 + +- [ ] 发票总金额汇总与新发票对象金额汇总一致 +- [ ] 发票与账单映射的金额汇总一致 + +### 5.3 关系校验 + +- [ ] 每张旧发票都能找到新发票主键或新业务单号 +- [ ] 每张旧发票都能追到原账单或新账单关系 +- [ ] 原发票代码 / 原发票号码在红冲或作废场景下未断链 + +### 5.4 抽样校验 + +- [ ] 随机抽 2 张正常发票，核对发票号、账单号、状态、电子票地址 +- [ ] 随机抽 1 张作废或红冲相关发票，核对原票引用链是否完整 +- [ ] 随机抽 1 张多账单映射发票，核对账单关系是否一致 + +## 6. 通用状态与标识校验 + +### 6.1 状态校验 + +- [ ] 收费状态已按状态矩阵归并，未出现无法解释的孤立状态 +- [ ] 发票状态已按状态矩阵归并，未出现成功/失败/作废/红冲混乱 +- [ ] 退款 / 冲正 / 坏账相关状态已按结果状态和 `legacyState` 双层承接 + +### 6.2 标识校验 + +- [ ] `FeeId` ↔ 新账单主键映射可查 +- [ ] `AccLogId` ↔ 新流水映射可查 +- [ ] 旧申请单号 ↔ 新调整单号映射可查 +- [ ] 发票代码 / 号码 ↔ 新发票对象映射可查 + +## 7. 差异分类规则 + +若试迁中发现差异，优先按以下类型记录： + +- [ ] A 类：对象映射错误 +- [ ] B 类：字段转换错误 +- [ ] C 类：状态归并错误 +- [ ] D 类：标识断链 +- [ ] E 类：历史只读遗漏 +- [ ] F 类：真实功能缺失 + +## 8. 通过标准 + +一次试迁批次至少满足以下条件，才允许进入下一批次： + +- [ ] 数量差异已全部解释 +- [ ] 关键金额差异已全部解释 +- [ ] 主关系链未断裂 +- [ ] 抽样场景能完整追溯 +- [ ] 状态和标识映射无重大断链 +- [ ] 所有未解决问题已形成差异清单 + +## 9. 后续动作 + +本清单完成后，下一步应补： + +1. 差异清单模板 +2. 复迁规则 +3. 批次回滚方案 diff --git a/specs/008-rev004-legacy-finance-migration/data-model.md b/specs/008-rev004-legacy-finance-migration/data-model.md new file mode 100644 index 0000000..a323c83 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/data-model.md @@ -0,0 +1,145 @@ +# Data Model: REV-004 旧账务迁移映射与功能缺失分析 + +## 1. 模型目标 + +本模型用于定义旧账务迁移规划阶段的核心对象，重点覆盖： + +- 旧对象如何分类 +- 新系统如何承接 +- 映射记录如何表达 +- 功能缺失如何判定 +- 迁移批次如何组织 + +## 2. Core Entities + +### 2.1 LegacyFinanceObject + +表示旧系统中的一个业务财务对象。 + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `legacyTable` | string | Yes | 旧表名，如 `AT_CHARGES`、`PM_ACCOUNT_RECORDS` | +| `legacyObjectName` | string | Yes | 旧对象名称，如“营业账”“预存退款” | +| `domainCategory` | string | Yes | 领域分类：账单 / 账户 / 收费 / 调整 / 退款 / 坏账 / 发票 | +| `primaryIdentifier` | string | Yes | 旧对象主标识，如 `FeeId`、`AccLogId`、`InvoiceInfoId` | +| `businessMeaning` | string | Yes | 旧对象业务语义 | +| `containsWorkflowFields` | boolean | Yes | 是否携带审批或流程字段 | +| `containsHistoricalOnlyData` | boolean | Yes | 是否包含明显历史只读数据 | + +### 2.2 TargetDomainObject + +表示新系统中用于承接旧语义的目标对象。 + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `targetDomain` | string | Yes | 新领域名，如 `ChargeAggregate`、`Transaction`、`OperationLog` | +| `targetPhysicalCarrier` | string | Yes | 物理承接对象，如 `biz_charge`、`bk_transaction` | +| `carrierType` | string | Yes | `online-main` / `mapping-layer` / `history-readonly` | +| `supportsOnlineProcessing` | boolean | Yes | 是否参与在线业务处理 | +| `supportsHistoricalQuery` | boolean | Yes | 是否支持历史查询 | + +### 2.3 CompatibilityMappingRecord + +表示旧对象与新对象之间的映射关系。 + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `legacySystem` | string | Yes | 原系统标识 | +| `legacyTable` | string | Yes | 旧表名 | +| `legacyId` | string | Yes | 旧主键值 | +| `legacyBizNo` | string | No | 旧业务单号/流水号 | +| `targetDomain` | string | Yes | 目标领域 | +| `targetId` | string | No | 新主键值 | +| `targetBizNo` | string | No | 新业务单号 | +| `mappingType` | string | Yes | `one-to-one` / `many-to-one` / `one-to-many` / `readonly-only` | +| `mappingStatus` | string | Yes | `planned` / `migrated` / `verified` / `failed` | +| `migrationBatchNo` | string | Yes | 迁移批次号 | +| `tracePayload` | string | No | 扩展追溯信息 | + +### 2.4 HistoricalReadonlyRecord + +表示仅保留查询与审计用途的历史记录。 + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `legacyTable` | string | Yes | 原表名 | +| `legacyId` | string | Yes | 原主键 | +| `legacyStatus` | string | No | 原状态 | +| `originalIdentifiers` | string[] | Yes | 原单号、原账单号、原流水号等 | +| `summarySnapshot` | string | Yes | 历史摘要 | +| `queryDimensions` | string[] | Yes | 可查询维度，如客户号、账期、处理类型 | +| `readonlyReason` | string | Yes | 为什么只读保留 | + +### 2.5 GapVerdict + +表示旧对象相对于当前 backend 的承接状态判定。 + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `legacyObjectName` | string | Yes | 旧对象名称 | +| `verdict` | string | Yes | `implemented` / `partial` / `readonly` / `missing` | +| `evidenceType` | string | Yes | `controller` / `service` / `do` / `table-mapping` / `doc-only` | +| `evidencePath` | string | Yes | 证据路径 | +| `gapDescription` | string | No | 缺失说明 | +| `recommendedAction` | string | Yes | `reuse` / `extend` / `readonly-retain` / `implement-later` | + +### 2.6 MigrationBatch + +表示一个迁移批次。 + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `batchNo` | string | Yes | 批次编号 | +| `batchName` | string | Yes | 批次名称 | +| `scope` | string[] | Yes | 纳入对象列表 | +| `dependsOn` | string[] | No | 前置批次 | +| `validationFocus` | string[] | Yes | 校验重点 | +| `rollbackScope` | string[] | Yes | 回滚范围 | + +## 3. Relationships + +```text +LegacyFinanceObject + -> maps to -> TargetDomainObject + -> produces -> CompatibilityMappingRecord + -> may retain as -> HistoricalReadonlyRecord + -> is judged by -> GapVerdict + +MigrationBatch + -> groups -> LegacyFinanceObject + -> validates -> CompatibilityMappingRecord / GapVerdict +``` + +## 4. Validation Rules + +- 每个 `LegacyFinanceObject` 必须至少对应一种承接方式：在线主模型、兼容映射层或历史只读层之一。 +- 每个被判定为 `implemented` 或 `partial` 的 `GapVerdict` 必须绑定 backend 证据路径。 +- 每个 `HistoricalReadonlyRecord` 必须能返回原系统标识和最小查询维度。 +- 每个 `CompatibilityMappingRecord` 必须带 `migrationBatchNo` 和 `mappingStatus`。 +- 每个迁移批次必须先定义校验重点，再进入实际迁移脚本设计。 + +## 5. Recommended State Semantics + +### 5.1 Mapping Status + +```text +planned -> migrated -> verified +planned -> failed +migrated -> failed +``` + +### 5.2 Gap Verdict + +```text +implemented +partial +readonly +missing +``` + +语义说明： + +- `implemented`：当前 backend 已有稳定在线承接能力 +- `partial`：已有部分承接，但与旧模型仍有明显差距 +- `readonly`：不建议在线重建，仅保留历史查询与追溯 +- `missing`：当前确实未见稳定承接能力，后续需补设计或实现 diff --git a/specs/008-rev004-legacy-finance-migration/plan.md b/specs/008-rev004-legacy-finance-migration/plan.md new file mode 100644 index 0000000..f52db6d --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/plan.md @@ -0,0 +1,162 @@ +# Implementation Plan: REV-004 旧账务迁移映射与功能缺失分析 + +**Branch**: `008-rev004-legacy-finance-migration` | **Date**: 2026-03-23 | **Spec**: `/specs/008-rev004-legacy-finance-migration/spec.md` +**Input**: Feature specification from `/specs/008-rev004-legacy-finance-migration/spec.md` + +**Note**: This plan is document-first and brownfield-evidence aware. The current round focuses on migration planning artifacts rather than migration code execution. + +## Summary + +本轮围绕 `REV-004` 旧账务迁移规划形成一套可直接衔接后续实施的 planning 产物，核心目标有两项：一是明确旧账务对象如何形成迁移映射，按在线主模型、兼容映射层和历史只读层三层承接；二是明确当前 backend 相对旧模型存在的已承接能力、弱映射点和功能缺失，避免后续把“旧表未原样存在”误判为“必须整表重建”。 + +本次计划输出以现有正式文档和 backend 证据为准：继续保持 `REV-004` 账务处理一期的统一控制模型，不新增独立账本引擎，不直接写迁移脚本；后续迁移实施按“映射矩阵先行、批次设计其次、试迁与校验最后”的顺序组织。 + +## Repository Scope + +- **Formal workflow home**: `water-docs` +- **Target repos in scope**: + - `water-docs`: Yes + - `water-backend`: Yes + - `water-frontend`: No +- **Primary delivery mode**: Document closure / Code evidence alignment + +## Code Baseline + +- **Backend baseline**: `water-backend` `HEAD` @ `1c47b922ceca9256482b7f5d2a39040fd2ef99e2` +- **Frontend baseline**: `water-frontend` `HEAD` @ `ae65939045449894c0fccab53fee08521e538ddd` +- **Baseline capture plan**: 所有功能缺失或已承接判断都绑定到当前 backend baseline，并在 `research.md` 中记录代码路径、DO、Controller、Service 或测试证据。 + +## Technical Context + +**Primary Work Product**: 迁移规划工件，包括研究结论、迁移数据模型、映射合同、缺失分析合同和执行 quickstart。 +**Source of Truth Documents**: +- `specs/008-rev004-legacy-finance-migration/spec.md` +- `.specify/memory/constitution.md` +- `docs/design/02_Detailed_Design/12_REV_Detailed.md` +- `docs/design/03_Technical_Design/03_Interface_Design.md` +- `docs/design/03_Technical_Design/01_Database_Design.md` +- `docs/guides/BACKEND_TABLE_MAPPING.md` +**Reference Sources**: +- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` +- `docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md` +- `docs/design/00_Management/07_Migration_Mapping_Template.md` +- `water-backend/sw-business/.../ChargeController.java` +- `water-backend/sw-business/.../ChargeServiceImpl.java` +- `water-backend/sw-business/.../ChargeServiceAccountingAdjustTest.java` +**Validation Commands**: +- `make validate-file FILE=specs/008-rev004-legacy-finance-migration/spec.md` +- `make validate-file FILE=specs/008-rev004-legacy-finance-migration/plan.md` +- `make validate-file FILE=specs/008-rev004-legacy-finance-migration/research.md` +- `make validate-file FILE=specs/008-rev004-legacy-finance-migration/data-model.md` +- `make validate-file FILE=specs/008-rev004-legacy-finance-migration/quickstart.md` +- `make check-links` +**Target Scope**: +- `REV-004` 旧账务迁移映射方法 +- `REV-004` 相关旧对象的功能缺失判定 +- 映射矩阵结构、迁移分批、最小校验动作 +- 历史只读与迁移验收查询边界 +**Project Type**: 文档治理仓库 + 多仓实现协作 +**Constraints**: +- 不新增平行正式主稿 +- 不发明超出主文档与 Archive 交集的新业务规则 +- 本轮不写迁移脚本、不改 backend 业务代码 +- 历史查询接口只读，不承担状态修正 +- 不把旧表未原样存在直接等同于功能缺失 +- 相对路径与现有 `IF-*` 编号体系保持稳定 +**Scale/Scope**: 跨文档 migration planning，覆盖 1 份 spec、1 份 plan、1 份 research、1 份 data-model、2 份 contracts 和 1 份 quickstart。 + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [x] **主文档归属已确认**：本轮 planning 产物落在 `specs/008-rev004-legacy-finance-migration/`，后续正式结论仍应回写 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，不新增平行正式主稿。 +- [x] **多仓范围已确认**：本轮涉及 `water-docs` 规划工件与 `water-backend` 取证，不涉及 `water-frontend`。 +- [x] **代码基线已确认**：backend 和 frontend baseline 已记录，用于绑定当前实现判断和排除前端范围。 +- [x] **Archive 使用方式合规**：`营收数据字典.md` 仅作为旧模型来源和迁移核对依据，不直接替代正式口径。 +- [x] **一致性影响已列出**：已识别旧对象命名、新旧状态映射、账单/流水/发票关系、历史查询接口口径与功能缺失判定标准。 +- [x] **校验与台账动作已规划**：已明确 planning 产物最小校验命令；本轮仅生成规划工件，暂不强制更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。 + +## Project Structure + +### Feature Artifacts + +```text +specs/008-rev004-legacy-finance-migration/ +├── spec.md +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +└── contracts/ + ├── rev004-legacy-mapping-contract.md + └── rev004-gap-assessment-contract.md +``` + +### Repository Touchpoints + +```text +water-docs/ +├── docs/design/ +├── docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md +├── docs/guides/BACKEND_TABLE_MAPPING.md +└── .specify/ + +water-backend/ +└── sw-business/sw-business-server/src/main/java/... +``` + +**Structure Decision**: +- `spec.md`：定义迁移映射规划与功能缺失分析的边界、验收和工件范围。 +- `plan.md`：组织本轮研究、设计、合同和 quickstart 结构。 +- `research.md`：沉淀迁移分层模型、映射形成方法、功能缺失判定标准和现状结论。 +- `data-model.md`：定义迁移映射对象、历史只读对象、缺失判定对象和批次对象。 +- `contracts/rev004-legacy-mapping-contract.md`：固化旧对象到新对象的映射矩阵结构与字段规则。 +- `contracts/rev004-gap-assessment-contract.md`：固化功能缺失判定的字段、取值和证据要求。 +- `quickstart.md`：给后续迁移实施前的工件准备、批次顺序和最小校验动作提供统一入口。 + +## Phase 0: Research & Alignment + +### Research Inputs + +- 如何从“旧表平移”转成“语义映射 + 三层承接”？ +- 哪些旧对象可视为已被当前 backend 语义承接？ +- 哪些旧对象属于弱映射或真正功能缺失？ +- 迁移验收需要保留哪些最小查询字段和关系？ +- 后续迁移实施前必须先补哪些映射矩阵？ + +### Deliverables + +- `research.md` + +## Phase 1: Design & Contracts + +### Planned Artifacts + +- `data-model.md` +- `contracts/rev004-legacy-mapping-contract.md` +- `contracts/rev004-gap-assessment-contract.md` +- `quickstart.md` + +### Design Decisions + +- 采用“在线主模型 + 兼容映射层 + 历史只读层”三层迁移结构。 +- 映射单元以旧业务对象语义为主，不以旧表名平移为主。 +- 功能缺失按“已承接 / 部分承接 / 历史只读 / 功能缺失”四类判定。 +- 后续迁移实施优先补映射矩阵和批次设计，再进入脚本开发与试迁。 + +## Validation Plan + +- **Document validation**: `make validate-file FILE=specs/008-rev004-legacy-finance-migration/.md`、`make check-links` +- **Backend validation**: 本轮以代码路径与测试证据核对为主，N/A for compile +- **Frontend validation**: N/A +- **Evidence output**: `research.md`、`data-model.md`、`contracts/*`、`quickstart.md` + +## Ledger Sync Plan + +- **Project progress update required**: No +- **Task checklist update required**: No +- **Evidence or verification summary update required**: No + +## Complexity Tracking + +本计划未发生 Constitution 违规项，无需豁免说明。 diff --git a/specs/008-rev004-legacy-finance-migration/quickstart.md b/specs/008-rev004-legacy-finance-migration/quickstart.md new file mode 100644 index 0000000..bd9b682 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/quickstart.md @@ -0,0 +1,97 @@ +# Quickstart: REV-004 旧账务迁移规划评审与最小校验 + +## 1. 评审入口 + +本轮目标是： + +- 明确旧账务迁移映射如何形成 +- 明确当前 backend 相对旧模型的功能缺失、弱映射点和历史只读对象 +- 为后续迁移脚本设计、试迁和迁移验收提供统一规划入口 + +本轮验收重点检查： + +- 映射方法是否稳定 +- 功能缺失判定是否有证据 +- 后续迁移批次和矩阵工件是否可直接执行 + +## 2. 评审步骤 + +### 步骤一：映射方法校验 + +确认方案采用以下原则： + +- 以业务语义映射为主，而不是旧表逐表平移 +- 采用在线主模型、兼容映射层、历史只读层三层承接 +- 不把所有旧精细台账都当成必须重建的在线对象 + +### 步骤二：功能缺失判定校验 + +确认每个旧对象都按以下四类之一判定： + +- `implemented` +- `partial` +- `readonly` +- `missing` + +并确认每条判定都绑定 backend 或文档证据。 + +### 步骤三：最小保留集校验 + +确认迁移最少保留： + +- 原单据标识 +- 原账单标识 +- 原流水标识 +- 原发票标识 +- 处理前后金额/水量 +- 处理原因 +- 申请/审批/生效时间 +- 经办人与依据 + +### 步骤四：批次顺序校验 + +确认后续迁移按以下顺序推进： + +1. 账户与营业账主明细 +2. 收费结果与交易对象 +3. 账务处理历史对象 +4. 发票对象与账单关系 + +### 步骤五：接口边界校验 + +确认历史查询与迁移验收遵循以下边界： + +- 接口只读 +- 统一挂靠既有 `IF-REV-*` 接口族 +- 同时支持汇总对账和明细追溯 +- 返回新旧标识映射 + +## 3. 后续实施前必须补齐的工件 + +后续正式进入迁移脚本开发前，至少补齐： + +1. 旧表到新对象映射矩阵 +2. 旧字段到新字段映射矩阵 +3. 旧状态到新状态映射矩阵 +4. 新旧标识映射矩阵 + +## 4. 最小校验命令 + +```bash +make validate-file FILE=specs/008-rev004-legacy-finance-migration/spec.md +make validate-file FILE=specs/008-rev004-legacy-finance-migration/plan.md +make validate-file FILE=specs/008-rev004-legacy-finance-migration/research.md +make validate-file FILE=specs/008-rev004-legacy-finance-migration/data-model.md +make validate-file FILE=specs/008-rev004-legacy-finance-migration/quickstart.md +make check-links +``` + +## 5. 通过标准 + +满足以下条件即可进入下一阶段： + +- 映射方法和三层承接模型已明确 +- 功能缺失判定标准已明确 +- 后续必做矩阵工件已明确 +- 迁移分批顺序已明确 +- 历史查询和迁移验收边界已明确 diff --git a/specs/008-rev004-legacy-finance-migration/research.md b/specs/008-rev004-legacy-finance-migration/research.md new file mode 100644 index 0000000..f7d32ac --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/research.md @@ -0,0 +1,85 @@ +# Phase 0 Research: REV-004 旧账务迁移映射与功能缺失分析 + +## Decision 1: 迁移映射以“业务语义”而非“旧表平移”为主 + +- **Decision**: 迁移映射的基本单元定义为“旧业务对象语义”，如营业账、账户流水、预存退款、已销调整、价差调整、坏账、发票关系，而不是直接按旧表名原样对应一个新表。 +- **Rationale**: 旧模型以“汇总表 + 明细表 + 流程字段”承载很多业务，而新 `REV-004` 正式模型强调统一账务控制入口和共性规则；若按旧表名逐表平移，会破坏现有正式口径并导致在线模型过度回退。 +- **Alternatives considered**: + - 旧表逐表原样在线重建：被否决，因为与当前 `REV-004` 主口径“不新增独立账务台账表族”冲突。 + - 完全忽略旧表结构，只保留抽象结论：被否决，因为不满足迁移验收和历史追溯要求。 + +## Decision 2: 采用“三层承接模型”组织迁移 + +- **Decision**: 新系统迁移承接采用三层结构：在线主模型承接层、兼容映射层、历史只读层。 +- **Rationale**: `12_REV_Detailed.md` 已明确旧精细账务台账不要求全部转为独立在线实体，但必须形成可追溯闭环；`03_Interface_Design.md` 也要求历史查询接口只读且支持汇总对账与明细追溯。三层结构能同时满足在线处理、迁移核查和审计要求。 +- **Alternatives considered**: + - 所有旧数据统一进入在线主模型：被否决，因为会污染新模型并放大状态机复杂度。 + - 所有旧数据只做历史归档：被否决，因为当前有效账单、收费、发票和部分账务场景仍需在线承接。 + +## Decision 3: 在线主模型优先承接账单、交易、留痕和发票主对象 + +- **Decision**: 在线主模型优先由 `biz_charge`、`biz_charge_detail`、`bk_transaction*`、`biz_operat_log*`、`biz_invoice*`、`biz_cust_invoice` 等对象承接。 +- **Rationale**: `BACKEND_TABLE_MAPPING.md` 和当前 backend 代码已明确这些对象存在；`ChargeServiceImpl.adjustAccounting` 也证明退款、冲正、坏账申请等场景已开始围绕账单、原交易和操作日志形成统一处理骨架。 +- **Alternatives considered**: + - 为退款、坏账、价差、已销调整分别新增独立在线主实体：被否决，因为当前 backend 未形成稳定一一对应对象，且与正式文档边界不一致。 + +## Decision 4: 功能缺失判定必须区分四类状态 + +- **Decision**: 对旧对象相对当前 backend 的承接状态，统一使用四类判定：`已承接`、`部分承接`、`历史只读`、`功能缺失`。 +- **Rationale**: 当前仓库已出现大量“旧对象无同名表，但语义已被新对象承接”的情况；若只用“有表/没表”二元判断，会把语义承接误判为缺失。四类判定更适合迁移规划和后续开发排优先级。 +- **Alternatives considered**: + - 仅用“已实现 / 未实现”：被否决，因为无法表达历史只读与弱映射。 + - 仅用“有表 / 无表”：被否决，因为结构缺失不等于业务能力缺失。 + +## Decision 5: 当前 `REV-004` 核心账务控制能力已具备“部分承接”基础 + +- **Decision**: 当前 backend 对 `REV-004` 已具备部分承接基础，主要证据是： + - `ChargeController` 存在 `/business/charge/accounting-adjust` + - `ChargeServiceImpl.adjustAccounting` 已支持 `AMOUNT`、`WATER`、`REFUND`、`REVERSE`、`BAD_DEBT` 等调整类型 + - `ChargeServiceAccountingAdjustTest` 已覆盖退款、冲正、坏账申请等关键路径 + - `ChargeDO` / `ChargeDetailDO` / `OperatLogDO` / `OperatLogDetailDO` 已承接账单与留痕 +- **Rationale**: 这些证据说明新系统不是从零开始，而是已经具备统一账务处理入口、原交易校验和日志留痕能力。 +- **Alternatives considered**: + - 将 `REV-004` 判定为完全未实现：被否决，因为已有明确控制器、服务和测试证据。 + - 将 `REV-004` 判定为完全闭环：被否决，因为旧模型的大量精细对象并未一一在线承接。 + +## Decision 6: 当前明显缺失的是“精细账务对象的独立在线承接”和“迁移专用映射/只读能力” + +- **Decision**: 相对旧数据字典，当前 backend 明显缺失或未明确形成稳定在线承接的主要是： + - 退款账独立对象 + - 特账 / 特账明细 + - 跨周期水量 + - 阶梯累计量 + - 预存退款 / 已销调整 / 价差调整 / 滞纳金减免 / 呆坏账等旧汇总表和明细表的一对一在线对象 + - 专门面向迁移验收的新旧标识映射层 + - 历史只读查询的统一在线出口 +- **Rationale**: `BACKEND_TABLE_MAPPING.md` 已明确这些属于弱映射或当前缺口；`ChargeServiceImpl` 虽有统一账务调整入口，但并未等价于旧模型的每类精细台账对象都已在线落地。 +- **Alternatives considered**: + - 认为这些缺失都必须在线重建：被否决，因为部分对象应以历史只读和映射承接。 + +## Decision 7: 旧审批流字段优先保留为历史只读，不在线复刻 + +- **Decision**: 旧模型中的 `TaskId`、`StepId`、`FlowRemark` 等审批痕迹，本轮规划为优先按历史只读和追溯字段保留，不要求在线复刻完整审批引擎。 +- **Rationale**: 当前 `REV-004` 一期正式口径只保留审批能力位与边界说明；若迁移阶段强行复刻旧审批流，会显著扩大范围。 +- **Alternatives considered**: + - 在线完整复刻旧审批流：被否决，因为超出一期边界。 + - 完全丢弃审批痕迹：被否决，因为不满足迁移验收和审计要求。 + +## Decision 8: 后续迁移实施必须先补四类矩阵工件 + +- **Decision**: 正式进入脚本开发前，必须先补四类矩阵：旧表到新对象映射、旧字段到新字段映射、旧状态到新状态映射、新旧标识映射。 +- **Rationale**: 当前最大风险不是“脚本写不出来”，而是没有统一映射基线会导致每个批次各自理解旧模型，最终差异不可控。 +- **Alternatives considered**: + - 先写 SQL，再回头补映射：被否决，因为会放大返工和核对成本。 + +## Decision 9: 迁移实施按“基础主对象 -> 收费结果 -> 账务处理历史 -> 发票关系”分批 + +- **Decision**: 推荐四个迁移批次： + 1. 账户与营业账主明细 + 2. 收费结果与交易对象 + 3. 账务处理历史对象 + 4. 发票对象与账单关系 +- **Rationale**: 这种顺序能先锁定主键和核心关系，再逐步迁入衍生对象，降低断链风险。 +- **Alternatives considered**: + - 按模块菜单顺序迁移：被否决，因为会打乱主键和依赖关系。 + - 按表名前缀整体迁移：被否决，因为无法体现业务依赖。 diff --git a/specs/008-rev004-legacy-finance-migration/spec.md b/specs/008-rev004-legacy-finance-migration/spec.md new file mode 100644 index 0000000..4b26c31 --- /dev/null +++ b/specs/008-rev004-legacy-finance-migration/spec.md @@ -0,0 +1,170 @@ +# Feature Specification: REV-004 旧账务迁移映射与功能缺失分析 + +**Feature Branch**: `008-rev004-legacy-finance-migration` +**Created**: 2026-03-23 +**Status**: Draft +**Input**: User description: "帮我根据这份文档进行规划下 怎么形成迁移 映射 ?以及是否存在功能缺失" + +## Document Scope & Sources *(mandatory)* + +- **Target documents**: + - `docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md` + - `docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `docs/design/03_Technical_Design/03_Interface_Design.md` + - `docs/design/03_Technical_Design/01_Database_Design.md` + - `specs/008-rev004-legacy-finance-migration/spec.md` + - `specs/008-rev004-legacy-finance-migration/plan.md` + - `specs/008-rev004-legacy-finance-migration/research.md` + - `specs/008-rev004-legacy-finance-migration/data-model.md` + - `specs/008-rev004-legacy-finance-migration/quickstart.md` + - `specs/008-rev004-legacy-finance-migration/contracts/` +- **Primary source of truth**: + - `docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `docs/design/03_Technical_Design/03_Interface_Design.md` + - `docs/design/03_Technical_Design/01_Database_Design.md` + - `docs/guides/BACKEND_TABLE_MAPPING.md` + - `.specify/memory/constitution.md` +- **Reference sources**: + - `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` + - `docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md` + - `docs/design/00_Management/07_Migration_Mapping_Template.md` + - `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` +- **Scope decision**: In scope。本轮聚焦 `REV-004` 旧账务模型迁移规划，明确迁移映射如何形成、哪些旧对象进入在线主模型、哪些仅保留历史只读、以及当前 backend 相对旧模型存在的功能缺失；本轮不直接执行数据迁移脚本，不进入 backend 代码改造。 + +## Repository Scope *(mandatory)* + +- **Target repos**: + - `water-docs`: Required + - `water-backend`: Required + - `water-frontend`: Not Required +- **Expected delivery type**: Document closure / Code evidence alignment +- **Out of scope for this round**: + - 直接开发迁移程序、ETL 脚本或数据库批处理脚本 + - 在本轮为旧账务台账逐表重建新的在线实体表族 + - 重建完整会计总账、明细账或借贷分录引擎 + - 前端迁移、前端兼容页面和前端查询适配 + +## Code Baseline *(mandatory for brownfield work)* + +- **Backend baseline**: `water-backend` `HEAD` @ `1c47b922ceca9256482b7f5d2a39040fd2ef99e2` +- **Frontend baseline**: `water-frontend` `HEAD` @ `ae65939045449894c0fccab53fee08521e538ddd`（仅用于范围排除） +- **Baseline capture rule**: 所有“已实现 / 部分实现 / 文档先行 / 历史只读”判断都必须绑定当前 backend baseline，并在研究结论中写明对应代码路径、DO/Controller/Service 或表映射证据。 + +## Evidence Scope *(mandatory)* + +- **Document evidence required**: + - `specs/008-rev004-legacy-finance-migration/spec.md` + - `specs/008-rev004-legacy-finance-migration/plan.md` + - `specs/008-rev004-legacy-finance-migration/research.md` + - `specs/008-rev004-legacy-finance-migration/data-model.md` + - `specs/008-rev004-legacy-finance-migration/contracts/rev004-legacy-mapping-contract.md` + - `specs/008-rev004-legacy-finance-migration/contracts/rev004-gap-assessment-contract.md` + - `specs/008-rev004-legacy-finance-migration/quickstart.md` +- **Backend evidence required**: + - `ChargeController.java` + - `ChargeServiceImpl.java` + - `ChargeServiceAccountingAdjustTest.java` + - `ChargeDO.java` + - `ChargeDetailDO.java` + - `OperatLogDO.java` + - `OperatLogDetailDO.java` + - `PriceCostAdjustmentDO.java` + - `PriceTierAdjustmentDO.java` + - `bk_transaction*` 相关实现与文档映射 +- **Frontend evidence required**: + - N/A +- **Verification artifacts required**: + - `research.md` + - `data-model.md` + - `contracts/*` + - `quickstart.md` + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - 形成旧到新的迁移映射方法 (Priority: P1) + +作为迁移方案设计人员，我需要先把旧账务模型中的账单、账户、收费、调整、退款、坏账和发票对象映射到新系统的承接层、映射层和历史只读层，这样后续迁移时不会陷入“旧表逐表平移”或“语义丢失”的两种极端。 + +**Why this priority**: 如果迁移映射方法不先锁定，后续迁移脚本、校验方案和实现拆解都会失去统一基线。 + +**Independent Test**: 审阅者仅通过 `research.md`、`data-model.md` 与迁移映射合同，即可判断每类旧账务对象的承接方式、映射规则和保留层次。 + +**Acceptance Scenarios**: + +1. **Given** 旧系统账务对象存在大量“汇总表 + 明细表 + 流程字段”组合， **When** 本轮规划完成， **Then** 审阅者能够明确哪些对象进入在线主模型、哪些仅作为历史只读、哪些只保留映射关系。 +2. **Given** 新系统 `REV-004` 当前采用统一账务控制模型， **When** 评审迁移方案， **Then** 不会再要求按旧表名原样重建全部在线表族。 + +--- + +### User Story 2 - 判定功能缺失与实现成熟度 (Priority: P2) + +作为技术评审人员，我需要看到旧账务模型相对于当前 backend 的功能缺失、弱映射点和已存在承接能力，这样后续才能区分“需要开发”“仅需迁移”“只需历史查询保留”三类工作。 + +**Why this priority**: 如果不区分功能缺失与仅缺表名映射，容易把迁移工程误做成无边界的功能重构。 + +**Independent Test**: 审阅者仅通过 `research.md` 和功能缺失合同，即可判断哪些 `REV-004` 相关能力已经存在、哪些属于部分实现、哪些仍然缺失。 + +**Acceptance Scenarios**: + +1. **Given** backend 已存在 `/business/charge/accounting-adjust` 与相关测试， **When** 审阅本轮结论， **Then** 能明确退款、冲正、坏账申请等核心场景已具备一定承接能力，但并未完整覆盖旧模型所有精细台账对象。 +2. **Given** 数据字典中存在退款账、特账、跨周期水量、坏账明细等旧对象， **When** 审阅缺失分析， **Then** 能明确哪些只是独立表缺失、哪些属于在线能力缺失、哪些应保留为历史只读。 + +--- + +### User Story 3 - 为后续迁移实施提供执行入口 (Priority: P3) + +作为后续实施负责人，我需要一套可以直接衔接迁移脚本开发和验收的规划工件，包括分批策略、映射矩阵、最小校验动作和差异定位入口，这样后续不会重复讨论方案框架。 + +**Why this priority**: 没有执行入口，本轮规划只能停留在概念层，无法顺利进入试迁、校验和差异修正阶段。 + +**Independent Test**: 审阅者仅通过 `plan.md` 与 `quickstart.md`，即可明确后续迁移实施的批次顺序、必做矩阵和最小校验动作。 + +**Acceptance Scenarios**: + +1. **Given** 后续需要开发迁移脚本或数据校验脚本， **When** 阅读本轮计划， **Then** 能直接知道应先产出哪些映射矩阵、按什么批次迁移、如何做最小校验。 +2. **Given** 当前阶段仍以规划为主， **When** 审阅本轮结果， **Then** 能明确本轮尚未进入实际数据迁移执行，也不会把迁移脚本视为已完成产物。 + +--- + +### Edge Cases + +- 当旧对象在数据字典中存在，但 backend 未看到同名独立表时，必须区分“语义已承接”“弱映射承接”和“功能缺失”，不得直接判定为必须原样重建。 +- 当旧对象同时携带业务结果、审批流程和页面冗余字段时，必须拆分在线承接字段、历史只读字段和追溯映射字段，避免单表平移污染新模型。 +- 当退款、冲正等场景与原交易、发票或收费结果强关联时，必须保留原交易标识与新标识映射关系，避免迁移后审计断链。 +- 当历史查询需要支持迁移验收时，不得把历史只读接口设计成状态变更接口。 + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: Specification MUST identify the exact migration-planning artifacts to be produced under `specs/008-rev004-legacy-finance-migration/`. +- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`BACKEND_TABLE_MAPPING.md` as the main source-of-truth inputs for migration planning. +- **FR-003**: Specification MUST define the migration scope by old object categories rather than by flat table copy lists only. +- **FR-004**: Specification MUST record backend code baseline and use it to judge whether a capability is implemented, partially implemented, or document-first. +- **FR-005**: Specification MUST preserve the single-source-of-truth model and MUST NOT assume creation of new parallel formal main documents. +- **FR-006**: Specification MUST define a three-layer migration model: online main model, compatibility mapping layer, and historical readonly layer. +- **FR-007**: Specification MUST define at least one mapping contract for old object to new object, field/state mapping, and identifier traceability. +- **FR-008**: Specification MUST define how functionality gaps are judged, including distinctions between missing table, weak mapping, and missing business capability. +- **FR-009**: Specification MUST define the minimum retention set for legacy migration, including original identifiers, original bill/transaction references, before/after values, operator, timestamps, and approval traces where applicable. +- **FR-010**: Specification MUST define the migration batch order and minimum validation actions before implementation. +- **FR-011**: Specification MUST require readonly historical query capability for migration acceptance and traceability. +- **FR-012**: Specification MUST list the applicable validation commands for the planning artifacts. + +### Key Entities *(include if feature involves data)* + +- **Legacy Finance Object**: 数据字典中的旧账务对象，如营业账、预存退款、已销调整、坏账、发票关系等。 +- **Online Main Model**: 新系统中继续承接在线业务处理的标准对象。 +- **Compatibility Mapping Record**: 用于保存旧标识、新标识、状态映射、来源类型和迁移批次的映射记录。 +- **Historical Readonly Record**: 仅保留查询与审计能力、不再作为在线处理主对象的历史记录。 +- **Gap Verdict**: 对旧对象在当前 backend 中的承接状态判定，如已承接、部分承接、历史只读、功能缺失。 +- **Migration Batch**: 数据迁移执行的分批单元，用于控制顺序、校验和回滚。 + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 审阅者可依据本轮工件明确至少 8 类旧账务对象的承接方式和迁移层次。 +- **SC-002**: 审阅者可依据本轮工件明确至少 5 类 `REV-004` 相关旧对象是否存在已实现、部分实现或功能缺失。 +- **SC-003**: 审阅者可依据本轮工件直接列出至少 4 份后续迁移实施前必须补齐的映射矩阵或校验工件。 +- **SC-004**: 本轮工件不把“旧表未原样落地”等同于“功能完全缺失”，能够区分语义承接与结构缺失。 +- **SC-005**: 本轮工件可直接作为后续迁移脚本设计、试迁和迁移验收的规划输入。