团财业务承保统计及手续费核对（第一阶段）— 后端接口清单

需求编号：BYXM-1891
范围：3.2.1 团财承保清单导入、3.2.1 团财批改清单导入、3.2.1 团财保单查询（已存在）、3.2.1 团财批单查询（新增）、3.2.1 影像件上传（新增）、3.2.1 团财保费预估表（暂不实现）。
不包含：3.2.2 产险对账单优化（下次上线）。
BasePath：/property_insurance（承保/批改/保单/批单），影像件上传单独一个控制器：/property_image_upload
鉴权：与现有所有 Controller 一致，从 UserInfoUtil.getUserInfo() 取登录信息（无需在入参里传 token）。
响应统一格式：Result（code / msg / data）。成功码 000000，业务异常码 000001 或 000002。

变更记录

日期	变更
2026-10-13	审批回写补齐关联表（no_car_party / no_car_charge / car_party / car_charge / car_vehicle），见 §2.9
2026-10-16	批改导入改为只写独立批单表 pi_endorse_bill，不回写任何主表；导入接口加 importType（导入/补录）；新增批单查询/导出/详情三个接口读 pi_endorse_bill；批单详情改为复用 PolicyDataDetailVo（与保单详情同构），删除 PolicyEndorseDetailVo。见 §1.4、§2.4、§2.9、§2.142.16、§3、§4.3、§六.14.114.4

---

一、导入模板与字段定义（必读）

模板由业务方提供，共 4 份：

模板	列数	表头结构	数据起始行	落库表
产险车险承保清单导入模板	73	第 1 行分组标题（合并单元格）+ 第 2 行字段名	第 3 行	pi_policy_car_stg
产险非车承保清单导入模板	62	第 1 行分组标题 + 第 2 行字段名	第 3 行	pi_policy_nocar_stg
产险非车被保人清单导入模板	6	第 1 行字段名	第 2 行	pi_policy_insured_stg（新建）
产险批改清单导入模板	15	第 1 行分组标题 + 第 2 行字段名	第 3 行	pi_endorse_car_stg / pi_endorse_nocar_stg

约定：

1. 只允许 .xlsx；禁止修改表头，后端会逐列校验表头，不一致直接拒绝整份文件（错误码 000002）。
2. 表中“必录”= 模板里字体标红的字段，与需求 3.2.1.1.1.2 / 3.2.1.1.1.3 一致。
3. 日期一律 yyyy-MM-dd；证件有效止期可填汉字“长期”，后端落 9999-12-31。
4. 非车保单“被保人类型=团体”时，被保人名称等可不录，改由被保人清单导入。

1.1 车险承保清单（73 列）

表头行 = 第 2 行，数据自第 3 行开始。

列号	信息分组	字段名	必录
1	保单基本信息	投保单号	否
2	保单基本信息	保单号	是
3	保单基本信息	保单状态	否
4	保单基本信息	投保日期 (格式：yyyy-MM-dd)	否
5	保单基本信息	承保日期 (格式：yyyy-MM-dd)	是
6	保单基本信息	生效日期 (格式：yyyy-MM-dd)	否
7	保单基本信息	保险公司代码	是
8	保单基本信息	保险公司名称	否
9	保单基本信息	业务形式	是
10	保单基本信息	业务属性	否
11	业务员信息	归属业务员代码	否
12	业务员信息	归属业务员姓名	否
13	车辆信息	车牌号码	否
14	车辆信息	品牌型号	否
15	车辆信息	车型描述	否
16	车辆信息	车架号	否
17	车辆信息	发动机号	否
18	车辆信息	初次登记日期	否
19	车辆信息	使用性质	否
20	车主信息	车主名称	否
21	车主信息	车主证件类型	否
22	车主信息	车主证件号码	否
23	车主信息	移动电话	否
24	投保人信息	投保人类型	是
25	投保人信息	投保人名称	是
26	投保人信息	投保人证件类型	否
27	投保人信息	投保人证件号码	否
28	投保人信息	证件有效止期 (格式yyyy-MM-dd，长期录入汉字“长期”)	否
29	投保人信息	性别 （投保人类型为“个人”录入）	否
30	投保人信息	国籍 （投保人类型为“个人”录入）	否
31	投保人信息	移动电话 （投保人类型为“个人”录入）	否
32	投保人信息	职业 （投保人类型为“个人”录入）	否
33	投保人信息	联系地址 (省市区+详细地址)	否
34	投保人信息	经营范围 （投保人类型为“企业”录入）	否
35	投保人信息	法定代表人/负责人名称 （投保人类型为“企业”录入）	否
36	投保人信息	授权业务人员名称 （投保人类型为“企业”录入）	否
37	投保人信息	授权业务人员证件类型 （投保人类型为“企业”录入）	否
38	投保人信息	授权业务人员证件号码 （投保人类型为“企业”录入）	否
39	投保人信息	授权业务人员证件有效止期 （投保人类型为“企业”录入）	否
40	投保人信息	授权业务人员移动电话 （投保人类型为“企业”录入）	否
41	被保人信息	被保人类型	否
42	被保人信息	被保险人与投保人关系 (“本人”无需录入被保人其他信息)	否
43	被保人信息	被保人名称	是
44	被保人信息	被保人证件类型	否
45	被保人信息	被保人证件号码	否
46	被保人信息	证件有效止期 (格式yyyy-MM-dd长期录入汉字“长期”)	否
47	被保人信息	性别 （被保人类型为“个人”录入）	否
48	被保人信息	国籍 （被保人类型为“个人”录入）	否
49	被保人信息	移动电话	否
50	被保人信息	职业 （被保人类型为“个人”录入）	否
51	被保人信息	联系地址 (省市区+详细地址)	否
52	受益人信息	受益人标志 （“法定受益人”无需录入后续受益人信息）	否
53	受益人信息	受益人类型	否
54	受益人信息	受益人与被保人关系 （“本人”无需录入后续受益人信息）	否
55	受益人信息	受益人名称	否
56	受益人信息	受益人证件类型	否
57	受益人信息	受益人证件号码	否
58	受益人信息	证件有效止期 (格式yyyy-MM-dd长期录入汉字“长期”)	否
59	受益人信息	性别 （受益人类型为“个人”录入）	否
60	受益人信息	国籍 （受益人类型为“个人”录入）	否
61	受益人信息	移动电话	否
62	受益人信息	职业 （受益人类型为“个人”录入）	否
63	受益人信息	联系地址 (省市区+详细地址)	否
64	险种信息	险种代码	是
65	险种信息	险种名称	是
66	险种信息	险种大类	否
67	险种信息	险种小类	否
68	险种信息	保险金额	否
69	险种信息	险种保费(含税)	是
70	险种信息	险种保费(不含税)	否
71	险种信息	保险起期 (格式yyyy-MM-dd)	否
72	险种信息	保险止期 (格式yyyy-MM-dd)	否
73	险种信息	缴费方式	否

1.2 非车承保清单（62 列）

表头行 = 第 2 行，数据自第 3 行开始。

列号	信息分组	字段名	必录
1	保单基本信息	投保单号	否
2	保单基本信息	保单号	是
3	保单基本信息	保单状态	否
4	保单基本信息	投保日期 (格式：yyyy-MM-dd)	否
5	保单基本信息	承保日期 (格式：yyyy-MM-dd)	是
6	保单基本信息	生效日期 (格式：yyyy-MM-dd)	否
7	保单基本信息	保险公司代码	是
8	保单基本信息	保险公司名称	否
9	保单基本信息	业务形式	是
10	保单基本信息	业务属性	否
11	业务员信息	归属业务员代码	否
12	业务员信息	归属业务员姓名	否
13	投保人信息	投保人类型	是
14	投保人信息	投保人名称	是
15	投保人信息	投保人证件类型	否
16	投保人信息	投保人证件号码	否
17	投保人信息	证件有效止期 (格式yyyy-MM-dd，长期录入汉字“长期”)	否
18	投保人信息	性别 （投保人类型为“个人”录入）	否
19	投保人信息	国籍 （投保人类型为“个人”录入）	否
20	投保人信息	移动电话 （投保人类型为“个人”录入）	否
21	投保人信息	职业 （投保人类型为“个人”录入）	否
22	投保人信息	联系地址 (省市区+详细地址)	否
23	投保人信息	经营范围 （投保人类型为“企业”录入）	否
24	投保人信息	法定代表人/负责人名称 （投保人类型为“企业”录入）	否
25	投保人信息	授权业务人员名称 （投保人类型为“企业”录入）	否
26	投保人信息	授权业务人员证件类型 （投保人类型为“企业”录入）	否
27	投保人信息	授权业务人员证件号码 （投保人类型为“企业”录入）	否
28	投保人信息	授权业务人员证件有效止期 （投保人类型为“企业”录入）	否
29	投保人信息	授权业务人员移动电话 （投保人类型为“企业”录入）	否
30	被保人信息	被保人类型 （团体无需录入被保人信息，通过被保人清单导入）	否
31	被保人信息	被保险人与投保人关系 (“本人”无需录入被保人其他信息)	否
32	被保人信息	被保人名称	是
33	被保人信息	被保人证件类型	否
34	被保人信息	被保人证件号码	否
35	被保人信息	证件有效止期 (格式yyyy-MM-dd长期录入汉字“长期”)	否
36	被保人信息	性别 （被保人类型为“个人”录入）	否
37	被保人信息	国籍 （被保人类型为“个人”录入）	否
38	被保人信息	移动电话	否
39	被保人信息	职业 （被保人类型为“个人”录入）	否
40	被保人信息	联系地址 (省市区+详细地址)	否
41	受益人信息	受益人标志 （“法定受益人”无需录入后续受益人信息）	否
42	受益人信息	受益人类型	否
43	受益人信息	受益人与被保人关系 （“本人”无需录入后续受益人信息）	否
44	受益人信息	受益人名称	否
45	受益人信息	受益人证件类型	否
46	受益人信息	受益人证件号码	否
47	受益人信息	证件有效止期 (格式yyyy-MM-dd长期录入汉字“长期”)	否
48	受益人信息	性别 （受益人类型为“个人”录入）	否
49	受益人信息	国籍 （受益人类型为“个人”录入）	否
50	受益人信息	移动电话	否
51	受益人信息	职业 （受益人类型为“个人”录入）	否
52	受益人信息	联系地址 (省市区+详细地址)	否
53	险种信息	险种代码	是
54	险种信息	险种名称	是
55	险种信息	险种大类	否
56	险种信息	险种小类	否
57	险种信息	保险金额	否
58	险种信息	险种保费(含税)	是
59	险种信息	险种保费(不含税)	否
60	险种信息	保险起期 (格式yyyy-MM-dd)	否
61	险种信息	保险止期 (格式yyyy-MM-dd)	否
62	险种信息	缴费方式	否

1.3 非车被保人清单（6 列）

表头行 = 第 1 行，数据自第 2 行开始；一个保单号可有多行。

列号	信息分组	字段名	必录
1		保单号	是
2		被保人名称	否
3		被保人证件类型	是
4		被保人证件号码	是
5		证件有效止期 (格式yyyy-MM-dd长期录入汉字“长期”)	否
6		移动电话	否

1.4 批改清单（15 列）

表头行 = 第 2 行，数据自第 3 行开始；一个保单号可有多行（一行为一个批单险种）。

列号	信息分组	字段名	必录	落库字段
1	批单基本信息	保单号	是	policy_no
2	批单基本信息	批单号	是	endorse_no
3	批单基本信息	批单承保日期 (格式：YYYY-MM-DD）	是	accept_date
4	批单基本信息	批单生效日期 (格式：YYYY-MM-DD）	否	generate_date
5	批单基本信息	归属业务员代码	否	handler_code
6	批单基本信息	归属业务员姓名	否	handler_name
7	批单险种信息	险种代码	是	risk_code
8	批单险种信息	险种名称	是	risk_name
9	批单险种信息	险种大类	否	risk_class
10	批单险种信息	批单保险金额	否	sum_insured
11	批单险种信息	批单险种保费(含税)	是	premium
12	批单险种信息	批单险种保费(不含税)	否	risk_premium_no_tax
13	批单险种信息	保险起期 (格式yyyy-MM-dd)	否	start_date
14	批单险种信息	保险止期 (格式yyyy-MM-dd)	否	end_date
15	批单险种信息	缴费方式	否	pay_type

批改模板的四条特殊规则（与承保清单不同，务必注意）：

1. 模板没有“产险类型”列。 车险 / 非车由后端按「保单号」反查 car_main、no_car_main 自动判定，判定结果回填 property_type（车险 / 非车），并决定落到 pi_endorse_car_stg 还是 pi_endorse_nocar_stg。前端无需也无法指定。

2. 保单号必须已存在于主表（2026-10-16 需求变更，强化）。 两侧主表都查不到时该行记为错误行，错误信息为「保单号[XXX]在车险/非车保单主表中不存在，请先导入承保清单」（带出具体保单号）。因此批改清单必须在对应承保清单导入并审批回写之后才能导入。

3. 批改数据不回写任何主表（2026-10-16 需求变更）。 导入解析落 pi_endorse_car_stg / pi_endorse_nocar_stg，审批通过后落到独立批单表 pi_endorse_bill；不会修改 car_main / no_car_main，也不会再写 pi_endorse_car_main / pi_endorse_nocar_main。批单查询 / 导出 / 详情（§2.14~2.16）全部读 pi_endorse_bill。

4. 两种导入模式（同一个接口，靠 importType 区分，模板字段完全相同，仅必录不同）：

   importType	页面入口	必录字段	前置校验
   ENDORSE_IMPORT（默认，不传即它）	批改清单导入	模板标红的 6 列：保单号、批单号、批单承保日期、险种代码、险种名称、批单险种保费(含税)	保单号+批单号+险种代码 在文件内及历史（批单表 + 待审 stg）均不得重复
   ENDORSE_SUPPLEMENT	批单信息补录	批单号、险种代码	目标批单（保单号+批单号）必须已导入成功，否则提示「保单号+批单号不存在」；审批时按最新数据 update 批单表

其它校验：日期须为 yyyy-MM-dd；保险止期须 ≥ 保险起期；险种大类枚举「1-企业财产保险 … 14-其他险」共 14 项；缴费方式枚举「趸交 / 按年缴 / 不定期」；金额类字段须为数字且最多 2 位小数；归属业务员代码必须在核心 prpsagent 中存在，业务员姓名以核心值为准（不取用户录入值）。

二、接口清单

所有 POST 请求的 Content-Type：application/json;charset=utf-8
所有 GET 请求的 Content-Type：URL query string
上传接口（除下载外）的 Content-Type：multipart/form-data

2.1.0 承保清单统一导入（兼容旧前端 新增）

这个端点只是为了兼容旧版打包 JS（旧版统一调 /import/policy/upload）。
新前端请直接用 §2.1 /import/car/upload 或 §2.2 /import/nocar/upload，语义更明确。

2.1 车险承保清单导入

落库 pi_policy_car_stg；行级错误写 pi_import_error，可用 §2.5/§2.6 查。
表头校验不通过时返回 code=000002，msg 里会带出具体哪一列被改。
文件没有任何数据行时返回 code=000002（未解析到有效数据行），规则见 §2.2.1。
errorRows > 0 时 msg 会带出行号与原因（最多列前 5 行），例如：
"msg": "车险承保清单导入解析完成；5 行校验失败：第 3 行 受益人标志为“指定受益人”时才能录入其它受益人信息；第 5 行 保单号不能为空；共 5 行失败，详见任务详情的「错误明细」"

2.2 非车承保清单导入（可同时传被保人清单）

承保清单落 pi_policy_nocar_stg，被保人清单落 pi_policy_insured_stg，共用同一个 batchNo，
一次提交、一次审核。需求 3.2.1.1.1.5 第 7 条：被保人类型=团体时必须上传被保人清单。
errorRows > 0 时 msg 会带出行号与原因（最多列前 5 行），与 §2.1 格式一致；
被保人清单部分的失败行也会合并进同一条 msg 与 errorDetails。

2.2.1 同一保单号多次导入（补录）规则（新增）

同一张保单分多次导入时（第一次只录了部分字段，第二次补剩余字段），第二次导入按“补录”处理，不再产生重复记录，也不会覆盖/清空第一次已录入的数据。车险（§2.1）与非车（§2.2）规则一致。

导入时（落 stg 表）

• 按保单号定位同表历史批次（batch_no 不同）里已有的记录，做字段级合并：
  • 历史行里已有有效值的字段 → 全部继承到本次行（本次没导入的字段因此不会被置空）；
  • 历史为空/缺失的字段 → 用本次导入的值补上；
  • 历史与本次都有有效值的字段 → 保留历史值，本次不覆盖（多条历史行时，取最新一条有值的记录）；
  • 系统/流程列（批次号、Excel 行号、记录类型、解析/审核状态等）只取本次的值，不继承。
• 合并后的行仍以本次批次号落库，因此 §2.5 批次明细能查到本次这条记录，明细内容 = 本次导入字段 + 从历史继承的字段（即该保单当前的完整视图）。
• 行校验按合并后的完整行判定：补录文件只录剩余字段（不含必录项）也能通过校验，必录项从历史行继承；历史也缺失的必录项仍会按行报错。
• 同一文件内同一保单号出现多行时，仍按原行为各自成行（批次内不做合并）。
• 返回的 msg / data.mergedRows 会提示本次按补录合并了多少条，例如："msg": "非车承保清单导入解析完成（其中 1 条保单号在历史批次已导入，按补录合并）"。

审批回写主表时

• car_main / no_car_main 的回写改为只写本次有值的列（insert 列清单与on duplicate key update 子句都按非空参数动态生成）：本次为 null 的列不插入、不更新，主表里已有的值原样保留。因此先审批新批次、后审批老批次也不会把数据冲掉。

空文件防护

• 文件里一条数据行都没有（只有表头/空模板）时，不再返回“导入成功”：返回 code=000002，msg="未解析到有效数据行：请确认模板第 3 行起已填写数据后重新导入"，批次状态置为 POST_FAILED（仍会出现在批次列表，total=0，便于追溯）。
• 该防护对**被保人清单单独导入（§2.3，提示为“第 2 行起”）与批改清单导入（§2.4）**同样生效。

2.3 非车被保人清单单独导入（补录场景）

落库 pi_policy_insured_stg。适用于非车保单信息补录时单独补充被保人。
errorRows > 0 时 msg 同样带“第几行、什么原因”（格式同 §2.1）。

2.4 批改清单导入 / 批单信息补录

返回：Result { code, msg, data: { batchNo, totalRows, successRows, errorRows, insuranceScope, errorDetails } }

落库：pi_endorse_car_stg / pi_endorse_nocar_stg（按保单号自动判定，见 §1.4 规则 1）；审批通过后落到独立批单表 pi_endorse_bill（唯一键 policy_no + endorse_no + risk_code，upsert）。不写 car_main / no_car_main 任何列。

返回码与其他导入接口一致：表头不符 000002，解析异常 000001，无数据行 000002（未解析到有效数据行）；errorRows > 0 时 msg 带“第几行、什么原因”。

行级错误文案（会出现在 msg 与 errorDetails 里，前端可直接展示）：

场景	文案
保单号在主表不存在	保单号[10578003903350998852]在车险/非车保单主表中不存在，请先导入承保清单
文件内重复	保单号+批单号+险种代码重复
与历史（批单表/待审 stg）重复	保单号+批单号+险种代码已存在，请勿重复导入
补录时目标批单不存在	保单号+批单号不存在
补录时险种不存在	保单号+批单号+险种代码不存在
业务员代码不在核心	归属业务员代码[XXX]在核心系统中不存在
日期格式	<字段名>须录入yyyy-MM-dd
金额格式	<字段名>只能录入数字且最高精确到小数点后2位
止期 < 起期	保险止期不能小于保险起期
枚举不符	<字段名>取值不在枚举范围内：xxx

调用示例：

导入顺序要求：批改是对已有保单的批改，保单号必须在 car_main / no_car_main 中存在，
即对应承保清单需先导入并审批回写。查不到的行计入 errorRows，
可在 §2.5 批次详情里看到具体行号与错误原因。

2.5 批次详情（解析明细 + 错误明细）

2.6 批次错误明细（仅错误行）

2.6.1 批次审核历史（新增）

• action 取值：UPLOAD（上传解析）/ SUBMIT（提交审核）/ APPROVE（审批通过并回写）/ REJECT（审批驳回）/ POST_FAILED（处理失败）/ DELETE（删除批次）。
• 写日志的埋点：上传解析完成/失败、提交审核、审批通过（含存在回写失败）、审批驳回、异常兜底、删除。
• 前端表格只需要 operator / auditResult / auditRemark / operateTime 四个字段，其余是冗余别名。

2.6.2 删除批次（新增）

• 逻辑删除：只把 pi_import_batch.del_flag 置 1，stg 明细与错误明细一律保留，随时可改回 0 恢复。
• 列表查询 POST /import/batch/list 已过滤 ifnull(del_flag,0)=0，删除后不再出现。
• 状态限制（不满足返回 000001）：
  • APPROVING（待审核）→ 「批次处于“待审核”，不允许删除，请先完成审核或驳回」
  • POSTED（已回写主表）→ 「批次已审批通过并回写主表，不允许删除」
  • 其余状态（UPLOADED / VALIDATED / POST_FAILED / REJECTED）允许删除。
• 删除动作会写一条 DELETE 的审核历史。

2.6.3 任务详情导出（新增）

• 响应：application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，文件名 任务详情_<batchNo>.xlsx，Body 为 xlsx 二进制。
• 三个 sheet：
  1. 批次信息：两列（字段 / 值），字段名与枚举值均为中文（如 批次号、批次状态=已校验）；
  2. 导入明细：双行表头与导入模板一致——第 1 行分组标题（合并单元格），第 2 行中文字段名，列顺序按对应模板列序（承保批次按车险 73 列 / 非车 62 列模板，批改批次按批改 15 列模板），前 N 列与用户导入时用的模板逐列一致；模板中没有的系统/扩展字段（出生日期、审核状态、回写快照 JSON 等）统一排在末尾分组；含 before_snapshot_json / after_snapshot_json等 JSON 快照列，便于排查回写结果；解析/审核/回写状态字段导出为中文；
  3. 错误明细：Excel行号 / 列名 / 错误码 / 错误描述 / 原始行数据 / 创建时间。
• 日期统一格式化为 yyyy-MM-dd HH:mm:ss 字符串，避免导出成数字。
• 要用 window.location.href 或 a[download] 跳转，不要走 ajax（见 2.7 第 5 条）。
• 出错时返回业务异常 000004（如批次不存在、导出失败），json 形态。

2.7 下载导入模板

templateType 为必填参数，取值：

templateType	下载文件名	说明
car	产险车险承保清单导入模板.xlsx	73 列，双行表头
nocar	产险非车承保清单导入模板.xlsx	62 列，双行表头
insured	产险非车被保人清单导入模板.xlsx	6 列，单行表头
endorse	产险批改清单导入模板.xlsx	15 列，双行表头

响应：

• Content-Type: application/octet-stream;charset=ISO8859-1
• Content-disposition: attachment; filename=<上表文件名>
• Body: xlsx 二进制

前端调用注意（容易踩）：

1. 必须带 templateType，且要按用户点击的是哪一类模板动态传值。四个模板对应四个入口，不要用一个固定 URL。
2. 漏传参数不再抛框架异常（原来会报 MissingServletRequestParameterException，浏览器只看到 400 白页），而是返回统一业务响应，前端按普通错误提示即可：
   JSON

   复制成功

   1{

   2 "code": "000004",

   3 "msg": "缺少模板类型参数 templateType。可选值：car（车险承保清单）/ nocar（非车承保清单）/ insured（非车被保人清单）/ endorse（批改清单）。示例：/tabycore/property_insurance/import/downloadTemplate?templateType=car"

   4}

   { "code": "000004", "msg": "缺少模板类型参数 templateType。可选值：car（车险承保清单）/ nocar（非车承保清单）/ insured（非车被保人清单）/ endorse（批改清单）。示例：/tabycore/property_insurance/import/downloadTemplate?templateType=car" }
3. 传了不支持的值同样返回 000004：模板类型不支持：xxx，可选值：car（车险承保清单）/ ...。
4. 参数值大小写与首尾空格后端会自动归一化（Car、car 均可）。
5. 下载类接口建议用 window.location.href 或 a[download] 直接跳转，不要用 ajax（二进制流无法走 JSON 解析）。

2.8 提交审核

2.9 审核（通过/不通过）

审批通过时的回写范围（2026-10-13 补充）：除主表（car_main / no_car_main）外，
还会回写保单详情页依赖的关联表，采用「先删后插」保证重复审批幂等：

• no_car_party：投保人（PARTYFLAG=1）、被保人（2）、受益人（3，仅「指定受益人」且有姓名时写）；

当事人类型 个人→1/企业→2，证件类型 身份证→1/户口本→2/统一社会信用代码→4/出生医学证明→9，
性别 男→1/女→2（「其他」无代码留空），与被保人关系 本人→1/配偶→2/子女→3/父母→4/其他→5；
证件有效期「长期」落 9999-12-31 + LONGFLAG=1

• no_car_charge：险种保费（RISKCODE/RISKNAME/AMOUNT/PREMIUM/起止日期）
• 车险：car_party（同口径）、car_charge（CLASSTYPE=1 商业险）、car_vehicle（车辆信息）

注意：同一张保单分多个批次导入时，关联表内容以最后一次审批的批次为准
（该批次的 stg 行即补录合并后的完整视图）。

批改批次（biz_type=ENDORSE）不适用上面这段（2026-10-16 变更）：审批通过时
只 upsert 独立批单表 pi_endorse_bill（唯一键 policy_no + endorse_no + risk_code，
insert ... on duplicate key update，补录场景即「按最新导入数据更新」），
不写 car_main / no_car_main，也不写 no_car_party / car_party / *_charge / car_vehicle。

2.10 兼容旧接口（前端如果还没改完，可以继续用）

内部均调用 auditBatch。

2.11 团财保单查询（已存在，保持不变）

2.12 团财保单详情（已存在）

2.13 团财保单导出（已存在）

2.14 团财批单查询（新增）

数据源：独立批单表 pi_endorse_bill（§2.4 审批后落地）+ 保单主表 car_main / no_car_main。
展示口径：批改导入文件里有的字段取批单表（批单号、承保日期、生效日期、业务员代码/姓名），
其余字段取样单主表（保险公司名称、地市级机构名称、投保人名称、被保人名称、产险类型）。
列表维度是「保单号 + 批单号」，一个批单下多个险种只展示一行。

返回：Result，data 是 Spring PageImpl（与保单查询 §2.11 完全同构，读 content + totalElements）

code	msg	说明
000000	查询成功
000003	查询条件不能为空	未传 body
000003	承保日期和保单号、批单号必录其一	两个条件都为空
000003	无记录	查询结果为空（此时 data 仍为 Page 对象，content 为空数组）
000001	系统查询异常！	后端异常，看服务日志

字段说明：

• propertyType 返回中文「车险 / 非车」（不再是 1/2）。
• comName 返回去掉「天安佰盈保险销售有限公司」前缀的简称（如「上海分公司本部营业部」）。
• acceptDate / generateDate 是 Date 类型，全站无 jackson 日期配置，序列化为毫秒时间戳（如 1785513600000）。前端请自行格式化；直接 moment(毫秒数) 可用，但不要 moment("1785513600000") 字符串（会得到 Invalid date）。

调用示例：

2.15 团财批单详情（新增）

返回结构与保单详情（§2.12 policyQuery/detail）完全一致，都是 PolicyDataDetailVo，
只是在保单基本信息之外多出两段：endorseBasicInfo（批单基本信息）、endorseRiskInfoList（批单险种信息）。
保单基本信息段直接取车主表/非车主表（与保单详情同逻辑）。

参数	必填	说明
policyNo	是	保单号
endorseNo	否	批单号；不传则取该保单下最新审批的一条批单
propertyType	否	已不再用于路由（产险类型由批单表自身判定），保留仅为兼容前端旧调用

返回：Result，data 是 PolicyDataDetailVo

code	msg	说明
000000	查询成功
000003	保单号不能为空
000003	未查询到批单详情	该保单号下没有已审批的批单（data 为 null）
000001	系统查询异常！

• endorseBasicInfo.totalPremiumTax / totalPremiumNoTax = 该批单下所有险种对应保费的合计（后端 SUM）。
• 日期字段（endorseAcceptDate / endorseEffectDate / startDate / endDate）后端已格式化为 yyyy-MM-dd 字符串，前端可直接渲染。
• settleCommissionRate / settleCommissionBasis 需求文档有这两列，但批改模板未提供，当前恒为 null，前端留空占位即可。

2.16 团财批单导出（新增）

入参、过滤逻辑、排序与 §2.14 完全一致（同一套 PolicyEndorseQueryCondition），只是不分页。
导出列与查询结果 11 列一致，「承保日期和保单号、批单号必录其一」的校验同样生效。

导出列顺序	表头	VO 字段
1	保单号	policyNo
2	批单号	endorseNo
3	承保日期	acceptDate
4	生效日期	generateDate
5	产险类型	propertyType
6	保险公司名称	companyName
7	地市级机构名称	comName
8	业务员代码	agentCode
9	业务员姓名	agentName
10	投保人名称	insureName
11	被保人名称	insuredName

必须走整页跳转（window.location.href = ...）或 responseType: 'blob'，不能走普通 ajax，否则拿不到二进制流。
条件不满足时后端抛 DataIntegrityViolationException（HTTP 500），前端请先复用 §2.14 的校验规则。

2.17 影像件上传（新增）

本模块完全参考寿险影像件上传（ImageUploadController）实现，落库沿用同一张表 imageupload，
与寿险只有两点差异：①接口名不同；②上传目录由 imageUpload/ 改为 propertyimage/。
因此 本次不需要新建任何表（原先准备的 pi_policy_image 建表 SQL 已作废并删除）。
产险当前业务只要求上传「投保人影像」一类。

落盘路径：{oss.upload.dir}/propertyimage/{policyNo}/{影像子目录}/{yyyyMMdd + UUID + 后缀}
影像子目录映射（与寿险一致）：
1→notification、2→homepage、3→insurance、5→policyHolderIdCard、6→insuredIdCard、7→beneficiaryIdCard、其他→trouble
访问 URL：https://{oss.domain}/propertyimage/{policyNo}/{影像子目录}/{文件名}，即 imageupload.imagepathsftp 的值。
失败返回：000002 + 具体原因（"不支持上传此类型文件!可上传类型为:jpg,png,pdf!" / "保单号不能为空" / "系统异常，上传失败"）。

2.18 影像件查询（按保单号，新增）

保单号超链接进入影像上传页面时调用，返回该保单下的全部影像件，按影像分类分组。

imageURL 就是访问地址，前端预览/下载直接用它。查询失败返回 000002。

2.19 影像件删除（新增）

同时删除服务器物理文件与 imageupload 表记录。删完由前端重新调用 2.18 刷新。

删除失败返回 000002 + "图片删除失败!"。前端需先弹框确认"是否确定删除？"。

2.20 影像件下载（新增）

---

三、新增/修改的 VO 字段

PolicyEndorseListVo（产险批单列表 / 导出，11 列）

字段：policyNo, endorseNo, acceptDate(Date), generateDate(Date), propertyType, companyName, comName, agentCode, agentName, insureName, insuredName

• propertyType 返回中文「车险 / 非车」。
• comName 已去掉「天安佰盈保险销售有限公司」前缀。

EndorseBasicInfo（批单基本信息，新增）

字段：endorseNo, endorseAcceptDate(yyyy-MM-dd), endorseEffectDate(yyyy-MM-dd), totalPremiumTax(BigDecimal), totalPremiumNoTax(BigDecimal), agentCode, agentName

EndorseRiskInfo（批单险种信息，新增）

字段：riskClass, riskCode, riskName, sumInsured(BigDecimal), premiumTax(BigDecimal), premiumNoTax(BigDecimal), startDate(yyyy-MM-dd), endDate(yyyy-MM-dd), payType, settleCommissionRate(BigDecimal, 当前恒 null), settleCommissionBasis(当前恒 null)

PolicyDataDetailVo（产险保单/批单详情，已存在）

• 原有字段不变：policyBasicInfo, carInfo, insureInfo, insuredInfoList, syInfoList, agentInfo, tciRiskInfo, vciRiskInfo, noCarRiskInfoMap, noCarRiskInfo

• 本轮新增两段（仅批单详情接口返回，保单详情接口为 null 且因 @JsonInclude(NON_NULL) 不出现在 JSON 里）：

  Java

  复制成功

  1private EndorseBasicInfo endorseBasicInfo;

  2private List<EndorseRiskInfo> endorseRiskInfoList;

  private EndorseBasicInfo endorseBasicInfo; private List<EndorseRiskInfo> endorseRiskInfoList;

PolicyEndorseDetailVo 已于 2026-10-16 删除——批单详情统一复用 PolicyDataDetailVo，
与保单详情（§2.12）保持同构，前端可以复用同一套详情渲染组件。

影像件相关 VO（复用寿险已有的类，无新增）

• 入参 ImageUploadVO：影像件模块用到的字段是 policyNo（保单号）、imageType（影像类型）、imageNameFromSftp（服务器文件地址/整条URL）
• 出参 ImageReturnVO：imageName（文件名）、imageURL（访问地址）

PolicyEndorseQueryCondition

字段：comCode, codeName, comSubCode, comSubName, companyCode, companyName, acceptStartDate, acceptEndDate, policyNo, endorseNo, propertyType（继承自 PageSizeInfo：currentPage、pageSize）

参与过滤的只有：comCode（前缀）、comSubCode（等值）、companyCode（等值）、acceptStartDate/acceptEndDate、
policyNo、endorseNo、propertyType，外加登录人机构权限（按保单主表 COMCODE 前缀，总部 01 / 00000000 看全部）。

---

四、建表 SQL

4.1 影像件

影像件不需要建表。
产险影像件参照寿险实现，直接复用已有的 imageupload 表（该表已有 policyno / filetype / imagename / imagepathsftp / createtime / updatetime / createby / updateby / imagelocation 字段）。
原"团财影像件上传表DDL.sql"（pi_policy_image）方案已废弃，文件已从工程中删除，无需在生产执行。

4.2 承保/批改导入（本轮新增，需在生产执行）

真实导入模板比早期占位模板多了车辆信息、车主信息、企业授权业务人员、受益人信息、险种大类/小类等字段，且非车被保人清单需要独立落表。因此新增一份增量脚本：

团财承保批改_新导入表DDL_增量.sql（工程根目录），包含两段：

段落	内容	适用环境
1	新建 pi_policy_insured_stg（非车被保人清单暂存）	所有环境
2	pi_policy_car_stg / pi_policy_nocar_stg 增列：车辆 7 列、车主 4 列、企业经营/授权人 7 列、受益人 12 列、险种大类/小类 2 列	仅存量库；全新环境执行 团财承保批改_新导入表DDL.sql 即可（CREATE 已含这些列）
3	pi_endorse_car_stg / pi_endorse_nocar_stg 增列 6 列：risk_class、sum_insured、risk_premium_no_tax、start_date、end_date、pay_type（批改清单模板 15 列中有 6 列原表没有）	仅存量库；全新环境执行 团财承保批改_新导入表DDL.sql 即可（CREATE 已含这些列）

已有表 pi_policy_car_stg / pi_policy_nocar_stg / pi_endorse_car_stg / pi_endorse_nocar_stg / pi_import_batch / pi_import_error / pi_endorse_car_main / pi_endorse_nocar_main 通过 团财承保批改_新导入表DDL.sql 建好，不重复创建。

4.3 批单独立表（2026-10-16 需求变更，需在生产执行）

团财批单表_BYXM-1891_20261016.sql（工程根目录，增量 DDL），三段：

段落	内容	说明
1	新建 pi_endorse_bill（25 列，UK uk_endorse_bill(policy_no, endorse_no, risk_code)）	批改清单导入/补录的唯一落地表；审批通过后写入，批单查询/导出/详情全部读它
2	pi_import_batch 增列 import_type	区分 ENDORSE_IMPORT / ENDORSE_SUPPLEMENT
3	pi_endorse_car_stg / pi_endorse_nocar_stg 各增列 import_type、up_com_code、up_com_name	任务详情页按保单号展示佰盈省级机构

重要：pi_endorse_car_main / pi_endorse_nocar_main 两张表自本轮起不再被批改导入写入
（导入只落 pi_endorse_bill）。如生产上已有历史数据，需要单独评估迁移，代码里已解除依赖。

---

五、错误码表

code	含义
000000	成功
000001	业务异常（具体信息看 msg）
000002	模板表头校验不通过（列数/字段名与系统模板不一致，msg 里带出具体列）；或前端校验不通过
000003	文件解析失败（非 xlsx / 模板格式错）
000004	数据回写失败（详见 msg；通常对应某条具体的 stg 行 id）
000005	权限不足（非本公司数据）
000099	系统异常

批单模块（§2.4 / §2.14~2.16）常见 code 速查：

接口	code	msg
2.4 导入	000001	请选择导入文件 / 解析异常
2.4 导入	000002	表头校验不通过（第 N 列应为「XXX」）/ 未解析到有效数据行
2.4 导入	000000 + errorRows>0	msg 带「第 N 行：保单号[XXX]在车险/非车保单主表中不存在，请先导入承保清单」等
2.14 查询	000003	查询条件不能为空 / 承保日期和保单号、批单号必录其一 / 无记录
2.15 详情	000003	保单号不能为空 / 未查询到批单详情
2.16 导出	000003	导出条件不能为空 / 承保日期和保单号、批单号必录其一
2.14~2.16	000001	系统查询异常！/ 系统导出数据异常

---

六、与前端的约定

1. 所有 POST 请求的 body 字段命名沿用驼峰式（与 VO @Data 注解生成的一致）。

2. 导出接口用 GET + queryString；前端如需复杂条件可以用 POST 后端再加。

3. 任何 /upload 接口超时统一 30 秒，前端请用 upload progress 反馈用户。

4. 审核回写是异步的还是同步的？

   • 当前实现：审核接口（/audit、/approve）在事务内同步完成 car_main / no_car_main 的回写；批量 200 行以内 < 5 秒，超过 200 行会返回 000004 并提示"请分批导入"。
   • 后续如果需要异步版本再扩展。

5. 同一保单号已存在时再导入 → 后端拒绝并提示"保单已存在"，不会覆盖。

6. 受益人=指定受益人 时，导入校验要求"受益人姓名、证件、份额"三项；前端录入时也应该在校验层把这三项联动起来。

7. 后端会复用 UserInfoUtil.getUserInfo() 取 comCode / operatorCode；前端传过来的 comCode 仅作为展示用，不参与过滤（避免越权）。

8. 影像件模块（/property_image_upload/*）与寿险影像件上传（/ImageUpload/*）是两套独立接口、同一张 imageupload 表，只是存储目录不同（propertyimage/ vs imageUpload/）。前端请按产险这套接口对接，不要混用。

9. 影像件预览：直接用 2.18 返回的 imageURL 打开即可（走 oss.domain）；如果浏览器需要强制下载，用 2.20 的下载接口。

10. 模板必须走下载接口拿（?templateType=car|nocar|insured|endorse，templateType 必填），不要用前端自己存的旧模板。后端会逐列校验表头，任何改名/删列/加列都会直接拒绝整份文件并返回 000002，msg 里会说明第几列对不上。

11. 车险、非车是两套模板两套接口（73 列 vs 62 列），不能混用；识别方式就是下载时传的 templateType。

12. 非车上传页支持一个承保清单 + 多个被保人清单，一起 multipart 提交（file + insuredFiles[]），后端合并到同一个 batchNo，失败详情里会按文件名+行号定位。

13. 证件有效止期允许填汉字“长期”，后端落 9999-12-31，前端回显时按这个约定处理。

14. 批改清单导入（§2.4）模板不带“产险类型”列，前端不要自行加列，也不要让用户选车险/非车——后端按保单号自动判定并在返回的错误明细里说明原因。导入顺序上，需提示用户先导入对应承保清单并完成审批回写，否则批改行会因保单号不存在而失败。14.1 【2026-10-16 变更】批改导入不碰任何主表。 批改数据审批后只落 pi_endorse_bill，car_main / no_car_main 的一行都不会改。页面上如果原来有“批改会更新保单”的提示请改掉。14.2 【2026-10-16 新增】批改导入接口多一个 importType 表单字段。 页面两个入口共用同一个接口：「批改清单导入」传 ENDORSE_IMPORT（或不传），「批单信息补录」传 ENDORSE_SUPPLEMENT。两者模板完全相同，差别只在必录项：导入是标红 6 列必录，补录只有批单号 + 险种代码必录。14.3 【2026-10-16 新增】批单查询的三个接口返回结构。

    • 查询（§2.14）：data 是 PageImpl，读 data.content 和 data.totalElements（与保单查询一致，不是 rows / total）。
    • 详情（§2.15）：data 是 PolicyDataDetailVo，与保单详情同构，可复用保单详情页组件；批单数据在多出来的 endorseBasicInfo / endorseRiskInfoList 两段里。旧的 PolicyEndorseDetailVo 已删除，如果前端有引用请改成 PolicyDataDetailVo 的读法。
    • 导出（§2.16）：11 列，与查询结果一致，走整页跳转。14.4 批单列表的 propertyType 返回中文「车险 / 非车」；comName 已去掉公司前缀。acceptDate / generateDate 是毫秒时间戳（全站未配 jackson 日期序列化），前端自行格式化。批单详情里的日期后端已格式化成 yyyy-MM-dd，两种接口的日期类型不一致是既有现状，不要混用格式化逻辑。

15. 旧版前端 JS 里的产险调用已与后端不一致，请按下表更新（仓库 static/dist 下打包产物仍含旧调用）：

    旧前端调用	现状	应改为
    GET /property_insurance/import/downloadTemplate（无参数）	会报缺参数	带 `?templateType=car
    POST /property_insurance/import/policy/upload	已加回兼容端点（见 §2.1.0）	建议改用 /import/car/upload 或 /import/nocar/upload；不改也能用，但强烈建议加 `insuranceScope=car
    GET /property_insurance/import/batch/auditHistory	后端已实现（见 §2.6.1）	直接调，入参 batchNo，返回数组
    POST /property_insurance/import/batch/delete	后端已实现（见 §2.6.2）	直接调，入参 {batchNo}，逻辑删除
    POST /property_insurance/import/batch/audit	保留	也可改用 /batch/approve、/batch/reject
    POST /property_insurance/import/endorse/upload	正常	不变
    POST /property_insurance/import/batch/list、/detail、/errors、/submit	正常	不变

    重要：产险导入页的「审核历史 / 删除 / 任务详情导出」三个按钮，前端 api 模块里目前是本地桩，没有发任何请求（static/dist/icrm/js/67.*.js、69.*.js 的 Bdmw 模块）：

    JavaScript

    复制成功

    1// 现状：直接 resolve 一个 000004，页面弹出"…接口暂未开放，需后端补充后启用"

    2function h(){ return w.a.resolve({data:{code:"000004",msg:"批次删除接口暂未开放，需后端补充后启用"}}); } // t.a = 删除

    3function v(){ return w.a.resolve({data:{code:"000004",msg:"审核历史接口暂未开放，需后端补充后启用"}}); } // t.d = 审核历史

    // 现状：直接 resolve 一个 000004，页面弹出"…接口暂未开放，需后端补充后启用" function h(){ return w.a.resolve({data:{code:"000004",msg:"批次删除接口暂未开放，需后端补充后启用"}}); } // t.a = 删除 function v(){ return w.a.resolve({data:{code:"000004",msg:"审核历史接口暂未开放，需后端补充后启用"}}); } // t.d = 审核历史

    后端接口已经补齐，前端需要把这两处桩换成真实请求（导出按钮 exportTaskDetail 同理）：

    JavaScript

    复制成功

    1// 删除：POST /property_insurance/import/batch/delete，body { batchNo }

    2function h(e){ return o("/property_insurance/import/batch/delete","post",e); }

    3 

    4// 审核历史：GET /property_insurance/import/batch/auditHistory?batchNo=xxx

    5function v(e){ return Object(y.a)({url:"/property_insurance/import/batch/auditHistory",method:"get",params:{batchNo:e}}); }

    6 

    7// 任务详情导出：GET /property_insurance/import/batch/detail/export?batchNo=xxx（必须走跳转，不能走 ajax）

    8function k(e){ return "/tabycore/property_insurance/import/batch/detail/export?batchNo=" + encodeURIComponent(e); }

    // 删除：POST /property_insurance/import/batch/delete，body { batchNo } function h(e){ return o("/property_insurance/import/batch/delete","post",e); } // 审核历史：GET /property_insurance/import/batch/auditHistory?batchNo=xxx function v(e){ return Object(y.a)({url:"/property_insurance/import/batch/auditHistory",method:"get",params:{batchNo:e}}); } // 任务详情导出：GET /property_insurance/import/batch/detail/export?batchNo=xxx（必须走跳转，不能走 ajax） function k(e){ return "/tabycore/property_insurance/import/batch/detail/export?batchNo=" + encodeURIComponent(e); }

    三个方法的调用形态（页面里已确定，后端按此实现）：

    • 删除：Object(g.a)({batchNo: row.batchNo})，成功后 fetchList() 刷新；
    • 审核历史：Object(g.d)(row.batchNo)，返回数组，逐行 normalizeAuditHistoryRow；
    • 导出：exportTaskDetail 里改为 window.location.href = <上面的 k(batchNo)>。

16. 所有写库接口都在事务里执行（uploadPolicy / uploadCarPolicy / uploadNoCarPolicy / uploadInsuredList /uploadEndorse / submitBatch / auditBatch / approveBatch / rejectBatch 均有 @Transactional）。stg 表与批次表的写入用的是 EntityManager 的 native query executeUpdate()，Hibernate 强制要求事务，没有事务会直接抛 TransactionRequiredException（全局异常处理器会把它吞成"处理异常，请联系管理员"）。新增或修改写库方法时务必带上 @Transactional，否则现象就是"接口返回 000001 但日志里是 TransactionRequiredException"。