更新一下

docs/7月迭代/7月迭代禅道研发需求逐条录入稿.md

@@ -157,10 +157,11 @@
 页面入口：店铺新建、店铺编辑、店铺列表、店铺详情。
 
 页面结构：
-1. 新建和编辑表单增加“平台业务员”可搜索下拉，可为空。
+1. 超级管理员和平台账号的新建、编辑表单增加“平台业务员”可搜索下拉，可为空；代理账号只读展示，不出现选择或清空控件。
 2. 候选项展示账号名和手机号摘要，只显示启用的平台账号。
 3. 店铺列表增加业务员列和业务员筛选项。
 4. 店铺详情展示业务员名称和手机号摘要。
+5. 代理创建下级店铺时提示“默认继承直属上级当前业务员”；继承由后端保证。
 
 接口约定：
 - POST /api/admin/shops、PUT /api/admin/shops/{id} 增加 business_owner_account_id:int64|null。
@@ -168,7 +169,7 @@
 - 业务员候选复用 GET /api/admin/accounts?account_type=platform&status=1，items至少返回 account_id、account_name、phone_masked。
 - 列表和详情返回 business_owner_account_id:int64|null、business_owner_name:string、business_owner_phone_masked:string。
 
-交互规则：不出现分销、佣金或发展层级文案；已停用业务员仍可在历史详情显示，但编辑候选中不可选。
+交互规则：不出现分销、佣金或发展层级文案；代理不能通过构造请求修改业务员；已停用业务员仍可在历史详情显示，但编辑候选中不可选；上级店铺后续变更不自动级联既有下级。
 
 完成标准：创建、编辑、筛选、详情展示一致，并覆盖清空业务员和无可选账号状态。
 ```
@@ -197,6 +198,8 @@
 2. 字段不参与店铺层级、数据权限、佣金或分销关系计算。
 3. 账号停用或删除后保留历史关联，通知时跳过不可用账号。
 4. 变更前后值写入审计。
+5. 代理创建下级店铺时由服务端复制所选直属上级店铺当时的业务员；代理请求只要出现该字段即拒绝。
+6. 只有超级管理员和平台账号可以显式设置、清空或更换；父店铺后续变更不向既有子孙店铺级联。
 
 完成标准：创建、修改、清空和筛选均生效，不能绑定代理账号或停用平台账号。
 ```
@@ -214,24 +217,22 @@
 **描述**
 
 ```markdown
-目标：让运营能看懂资产当前轮询策略和最近同步情况，不新增第二个同步按钮。
+目标：让运营通过统一审计查看业务事件和回调的同步轨迹；保留现有手动刷新和轮询展示，不新增第二个同步按钮或活跃轮询字段。
 
 预计工时：前端2～3小时。
 
 页面入口：卡详情、设备详情、全局审计外部集成页。
 
 页面结构：
-1. 详情页同步区域展示轮询是否启用、活跃级别、最后活跃时间、最后活跃场景和下次轮询时间。
-2. 保留现有手动刷新按钮。
-3. 增加“查看同步轨迹”，跳转全局审计并自动带入资产筛选。
-4. 同步轨迹按立即、3分钟、5分钟连续展示结果。
+1. 保留现有手动刷新按钮及现有轮询状态展示，不新增活跃级别、最后活跃场景或下次轮询字段。
+2. 增加“查看同步轨迹”，跳转全局审计并自动带入资产筛选。
+3. 同步轨迹按立即、3分钟、5分钟连续展示结果，并显示运营商回调和现有周期轮询的Integration Log。
 
 接口约定：
-- GET /api/admin/assets/resolve/{identifier} 返回 polling:{enabled:bool,activity_level:string,last_activity_at:string|null,last_activity_scene:string,next_poll_at:string|null}。
 - 现有手动刷新接口保持原契约。
 - GET /api/admin/audit/integrations 支持 resource_type、resource_key、correlation_id 查询。
 
-交互规则：rate_limited 只展示本次失败，不显示自动退避倒计时；无下次轮询时显示“-”。
+交互规则：事件序列的rate_limited只展示本次失败，不显示自动退避倒计时；前端不根据事件轨迹推算或展示新的周期轮询时间。
 
 完成标准：卡和设备均能展示同步状态并跳转到过滤后的轨迹页，加载、空记录和失败状态完整。
 ```
@@ -241,28 +242,28 @@
 **标题**
 
 ```text
-[BE][UR#94] 资产状态同步DDD收口与轮询优化
+[BE][UR#94] 卡状态公共写入、事件触发与运营商实名回调
 ```
 
 **描述**
 
 ```markdown
-目标：将轮询、业务事件、手动刷新和运营商回调统一进入卡状态应用用例。
+目标：将现有轮询查询结果、业务事件、手动刷新和运营商回调统一进入卡状态应用用例，同时保持现有轮询调度不变。
 
 预计工时：后端7～9小时。
 
 规则：
-1. 只保留全局 enable_polling 开关，按活跃和不活跃卡使用不同轮询间隔。
+1. 现有tb_polling_config、Redis分片队列、各同步类型间隔、卡级开关、失败重排、并发控制和监控全部保持现状，只替换查询成功后的状态写入及联动。
 2. 关键业务成功边界创建立即、3分钟、5分钟三个无自动重试任务；达到预期状态后后续任务提前完成。
 3. Gateway 超频只记录 rate_limited，不做 blocked_until 或指数退避。
 4. ApplyCardObservation 是实名、流量和网络状态的唯一写入口。
 5. 行业卡是否实名由运营商 realname_link_type 决定。
 
-接口：不新增显式同步接口；资产详情 Query 返回 polling；同步轨迹进入统一 Integration Log 和审计 Query。
+接口：不新增显式同步接口或活跃轮询字段；现有手动刷新保持原契约；同步轨迹进入统一Integration Log和审计Query；只为已掌握真实报文的移动/电信实名成功及联通解除实名增加回调Translator。
 
 架构：迁移到 card Domain、同步 Application、Gateway Adapter 和 Query，旧轮询及刷新逻辑改为调用统一用例。
 
-完成标准：三条自动通道和手动刷新结果一致，事件序列可追踪，旧逻辑不再直接修改卡状态。
+完成标准：现有轮询、事件序列、手动刷新和回调结果一致，事件序列可追踪，旧逻辑不再直接修改卡状态；改造前后轮询配置、下次入队、失败重排和监控统计保持一致。
 ```
 
 ## UR#86 资产详情中换货标识
@@ -677,18 +678,19 @@
 
 页面结构：
 1. 两个独立按钮：批量分配代理、批量分配套餐系列。
-2. 两个弹框都包含前端静态模板下载、目标选择、Excel上传和提交按钮。
+2. 两个弹框都包含前端静态CSV模板下载、目标选择、CSV上传和提交按钮；不接受Excel。
 3. 创建成功后进入任务进度区，展示状态、总数、成功数、失败数和失败明细。
 4. 页面刷新后根据 task_id 恢复进度。
 
 接口约定：
-- POST /api/admin/devices/batch-assign-shop，multipart包含 file、shop_id、request_id。
-- POST /api/admin/devices/batch-assign-series，multipart包含 file、series_id、request_id。
+- 前端先调用现有对象存储预签名上传接口，purpose=device_batch_allocation，将UTF-8 CSV直传私有对象存储。
+- POST /api/admin/devices/batch-assign-shop，JSON body={file_key,shop_id}。
+- POST /api/admin/devices/batch-assign-series，JSON body={file_key,series_id}。
 - GET /api/admin/devices/batch-allocation/{task_id} 返回 task_id、operation_type、status、status_name、total_count、success_count、failed_count、failed_items。
 
 交互规则：一个任务只能选择一种操作；任务处理中按2、3、5秒后最大10秒轮询；页面不可见时暂停。
 
-完成标准：两个入口互不混淆，部分成功和失败原因可查看，模板由前端静态文件提供。
+完成标准：两个入口互不混淆，平台代理权限与现有同步用例一致，长设备号按文本预览，部分成功和失败原因可查看，CSV模板由前端静态文件提供。
 ```
 
 ### 后端研发需求
@@ -710,12 +712,13 @@
 
 规则：
 1. operation_type 只能是 assign_shop 或 assign_series，一个任务只修改一个目标字段。
-2. 文件最大10MB、最多1000行、Worker每批200条。
+2. 只接受单列UTF-8 CSV，固定表头“设备号”；文件最大10MB、最多1000行、Worker每批200条。
 3. 设备号去重后批量查询；失败明细最多保存1000条。
-4. 已属于目标值按幂等成功；assign_shop 遇到其他代理资产失败；assign_series 不修改 shop_id。
-5. Asynq载荷只传结构化ID和对象存储Key，不传本地路径或文件字节。
+4. 平台只能分配平台库存；代理只能把自己名下设备分给直属下级。assign_series时代理只能操作自己设备并使用自己当前授权系列。
+5. 已属于目标值按幂等成功；assign_shop遇到其他代理资产失败；assign_series不修改shop_id。
+6. 业务接口只接收file_key，不接收multipart字节；Asynq载荷只传结构化task_id，不传对象Key、本地路径或文件字节。
 
-完成标准：任务支持部分成功、进度恢复和request_id防重，两种命令的数据边界清晰。
+完成标准：任务支持部分成功和进度恢复，Worker重试幂等，平台及代理数据边界正确，两种命令的数据边界清晰。
 ```
 
 ## UR#48 不同资产使用不同支付方式
@@ -744,10 +747,10 @@
 
 接口约定：
 - GET /api/c/v1/asset/info 返回 allowed_payment_methods:string[]，值为 alipay、wechat、wallet。
-- POST /api/c/v1/orders/create 和 POST /api/c/v1/orders/{id}/pay 入参 payment_method:string。
+- POST /api/c/v1/orders/create 必须提交payment_method:string并固化；POST /api/c/v1/orders/{id}/pay 不允许选择或修改payment_method，只提交固定方式执行所需附加参数。
 - GET /api/admin/system/config?module=payment 查询配置；PUT /api/admin/system/config/{config_key} 保存卡和设备允许的支付方式。
 
-交互规则：钱包是否可选完全使用后端返回；创建或支付时后端拒绝的方式直接展示错误，不由前端兜底放行。
+交互规则：钱包是否可选完全使用后端返回；创建成功后展示订单已选方式且不提供切换。需要换方式时先取消待支付订单再重新创建；强充由创建接口按所选微信/支付宝立即拉起，钱包不能用于给自身强充。
 
 完成标准：卡、设备、配置异常和无可用方式四类场景展示正确。
 ```
@@ -763,13 +766,13 @@
 **描述**
 
 ```markdown
-目标：按资产类型返回允许支付方式，并在订单创建及支付阶段强校验。
+目标：按资产类型返回允许支付方式，在订单创建时决定并固化支付方式，并在后续实际支付时再次强校验。
 
 预计工时：后端2～3小时。
 
 接口：GET /api/c/v1/asset/info 增加 allowed_payment_methods；订单创建和支付接口校验 payment_method；后台复用系统配置接口。
 
-规则：卡默认支付宝和钱包；设备默认微信和钱包；钱包始终允许；配置异常时使用安全默认值并记录错误，不能放开全部方式。
+规则：卡默认支付宝和钱包；设备默认微信和钱包；钱包始终允许；配置异常时使用安全默认值并记录错误，不能放开全部方式。普通订单创建保存不可变payment_method，/pay只能读取订单快照执行；管理员后来禁用该方式时拒绝支付，不自动换渠道。强充在创建流程立即使用所选方式，wallet强充拒绝。
 
 完成标准：前端隐藏不能绕过后端校验，订单创建和支付使用同一策略，配置变更写审计。
 ```
@@ -794,14 +797,14 @@
 页面入口：卡详情、设备详情。
 
 页面结构：
-1. “设置限速”弹框包含 speed_kbps 正整数输入框和确认按钮。
-2. “取消限速”使用独立确认操作，提交 speed_kbps=0。
+1. “手动限速”弹框只展示后端返回的固定语义档位，不允许输入任意速率或上游code。
+2. “恢复不限速”提交speed_level=unlimited；“限到0kbps”提交speed_level=zero_kbps，两者严格区分。
 3. 设备详情必须显示本次实际作用的当前卡ICCID；无当前卡时禁用操作并展示原因。
 4. 不展示“Gateway当前实际限速”，除非接口未来明确返回查询结果。
 
-接口约定：POST /api/admin/assets/{identifier}/speed-limit，body={speed_kbps:int}；返回 asset_type、asset_identifier、card_no、speed_kbps、result、message。
+接口约定：POST /api/admin/assets/{identifier}/speed-limit，body={speed_level:string}；返回asset_type、asset_identifier、card_no、speed_level、channel_code、applied_speed、channel_raw_value、result、message。
 
-交互规则：单位固定展示kbps；提交中禁用按钮；失败保留输入值；成功后展示后端结果。
+交互规则：提交中禁用按钮；失败保留所选档位；中国电信/广电按后端能力展示，联通/移动或映射缺失时禁用并展示原因；结果未知不能显示成功。
 
 完成标准：卡限速、设备解析当前卡、取消限速和无当前卡四类场景完整。
 ```
@@ -821,13 +824,13 @@
 
 预计工时：后端2～3小时。
 
-接口：POST /api/admin/assets/{identifier}/speed-limit，入参 speed_kbps；正数为设置，0为取消。
+接口：POST /api/admin/assets/{identifier}/speed-limit，入参为固定语义枚举speed_level；恢复不限速与限到0kbps是不同值，前端和业务层不得接触渠道code。
 
-规则：资产为卡时读取ICCID；资产为设备时解析 is_current=true 的有效当前卡；不存在当前卡则拒绝；绝不把设备号传给Gateway。取消仍调用同一Gateway端口，由适配器转换上游取消参数。
+规则：资产为卡时读取ICCID；资产为设备时解析is_current=true的唯一有效当前卡；不存在或多条当前卡都拒绝；绝不把设备号传给Gateway。仅中国电信和中国广电直连POST /flow-card/speedLimit；Adapter按Gateway账号+运营商+speed_level映射code，缺失映射不猜测。外部副作用关闭自动重试，超时等结果不明记录unknown。
 
 非目标：不建立套餐固定限速，不因激活、到期、停机或切卡自动限速，不增加自动补偿Worker。
 
-完成标准：返回最终card_no和调用结果，每次请求记录操作审计及Integration Log。
+完成标准：返回最终card_no、语义档位和规范化调用结果；电信、广电、联通、移动、映射缺失、明确失败和结果未知均有正确行为；每次请求记录操作审计及Integration Log。
 ```
 
 ## UR#46 资产信息详情字段新增
@@ -960,7 +963,7 @@
 
 接口约定：GET /api/admin/refunds、GET /api/admin/agent-recharges、GET /api/admin/exchanges 的items增加 submitter_name、approval_source、approval_status、approval_status_name、current_approver_summary、processing_status、processing_status_name。
 
-交互规则：approval_source=none时审批列显示“-”；legacy只读展示；wecom展示企微状态。长审批人摘要使用省略和悬浮完整文本。
+交互规则：approval_source=none时审批列显示“-”；legacy只读展示；wecom展示企微状态。平台/超级管理员按业务权限展示当前审批人摘要，长摘要使用省略和悬浮完整文本；代理不展示审批人列，接口摘要固定为空。
 
 完成标准：三类列表字段和空值规则一致，分页切换不会额外逐行请求审批详情。
 ```
@@ -982,7 +985,7 @@
 
 接口：扩展现有三类列表返回 submitter_name、approval_source、approval_status_name、current_approver_summary、processing_status_name。
 
-规则：提交人保存业务快照；企微摘要按当前页实例ID批量查询，禁止N+1；历史本地审批返回approval_source=legacy；无审批返回none。
+规则：提交人保存业务快照；企微摘要按当前页实例ID批量查询，禁止N+1；历史本地审批返回approval_source=legacy；无审批返回none。当前审批人属于平台内部信息，仅平台/超级管理员按业务权限返回；代理响应中的current_approver_summary固定为空。
 
 完成标准：列表查询次数稳定，历史数据可读，审批摘要与详情状态一致。
 ```
@@ -1008,13 +1011,15 @@
 
 页面结构：
 1. 两个入口复用同一套餐候选表格。
-2. 列包含套餐名称、编码、公司成本价、当前授权成本价、建议售价、授权状态。
-3. is_authorized=true 的行显示“已授权”、复选框置灰且不可全选。
-4. 未授权套餐支持多选并一次提交。
+2. 首次授权读取现有套餐列表；后续管理再读取现有系列授权详情，前端按package_id合并，不新增候选接口。
+3. 列按当前调用视角区分上级当前成本价、目标代理授权成本价、建议售价和授权状态；平台代理视角不得都误标为公司成本。
+4. is_authorized=true的行在新增模式置灰；授权、调价、移除分别使用独立操作模式。
+5. 未授权套餐支持多选并一次提交。
 
 接口约定：
-- GET /api/admin/shop-series-grants/{id}/package-options 返回 items:{package_id,package_name,package_code,company_cost_price,authorized_cost_price,suggested_retail_price,is_authorized}。
-- PUT /api/admin/shop-series-grants/{id}/packages，body={package_ids:int64[]}。
+- 首次授权复用GET /api/admin/packages?series_id=...和POST /api/admin/shop-series-grants，POST必须同时提交至少一个packages项。
+- 后续管理复用GET /api/admin/packages?series_id=...与GET /api/admin/shop-series-grants/{id}。
+- PUT /api/admin/shop-series-grants/{id}/packages，body={operation_type:authorize|update_cost|remove,packages:[{package_id,cost_price?}]}。
 
 交互规则：三类价格按分转元；提交成功后重新加载候选列表；空候选和全部已授权状态有明确提示。
 
@@ -1026,25 +1031,25 @@
 **标题**
 
 ```text
-[BE][UR#43] 系列套餐候选Query与重复授权幂等
+[BE][UR#43] 首次套餐授权与后续批量命令明确化
 ```
 
 **描述**
 
 ```markdown
-目标：复用现有批量授权接口，新增可供前端一次选择的套餐候选Query。
+目标：首次授权继续同时创建系列与套餐；后续复用现有批量接口，并把新增、调价、移除拆成明确命令；不新增候选Query。
 
 预计工时：后端0.5～1小时。
 
-接口：GET /api/admin/shop-series-grants/{id}/package-options；复用 PUT /api/admin/shop-series-grants/{id}/packages。
+接口：复用GET /api/admin/packages、GET /api/admin/shop-series-grants/{id}、POST /api/admin/shop-series-grants和PUT /api/admin/shop-series-grants/{id}/packages。
 
-返回：package_id、名称、编码、company_cost_price、authorized_cost_price、suggested_retail_price、is_authorized。
+首次授权：POST中的packages改为必填且至少1项，系列与套餐在同一事务全成全败，不允许空系列授权。
 
-规则：重复套餐按幂等处理；后端不依赖前端置灰；查询遵守代理、系列和套餐可见范围；三个价格字段语义分开。
+后续规则：PUT必须提交operation_type=authorize|update_cost|remove，一次只执行一种命令、最多100项、事务内全成全败；authorize同价重复幂等、不同价重复冲突，不能静默改价；所有系列、套餐、直属下级与价格边界由后端校验。
 
-架构：候选列表走Query，批量授权走轻量Application事务脚本。
+读取：前端组合现有套餐列表和授权详情；已授权但当前不在普通列表中的存量项仍从详情只读展示。成本字段按操作者视角准确命名。
 
-完成标准：首次和后续授权共用契约，重复提交不生成重复关系。
+完成标准：首次授权不会产生空系列；新增、调价和移除无语义混用；重复提交不生成重复关系或静默覆盖并发价格；前后端同批切换。
 ```
 
 ## UR#42 导出功能
@@ -1054,33 +1059,47 @@
 **标题**
 
 ```text
-[FE][UR#42] 导出字段选择权限配置与任务进度
+[FE][UR#42] 自动权限导出、角色字段配置与受保护附件访问
 ```
 
 **描述**
 
 ```markdown
-目标：用户按权限选择导出字段，管理员可给角色配置各场景可导出字段。
+目标：用户按当前查询条件直接导出角色已授权的全部字段；管理员可给角色配置各场景可导出字段；导出文件中的退款/充值凭证和企微审批附件可通过后台登录态安全访问。
 
-预计工时：前端3～4小时。
+预计工时：按本冻结范围重新评估；原3～4小时估算未包含受保护附件落地页，不能继续沿用。
 
-页面入口：卡、钱包流水、套餐、退款、换货、充值、临期列表的导出弹框；角色权限配置页。
+页面入口：卡、设备、订单、钱包流水、套餐、退款、换货、充值、临期列表的导出入口；角色权限配置页；后台附件落地页 `/export-attachments/:attachment_ref`。
 
 页面结构：
-1. 导出弹框先加载当前scene可选字段，使用复选框选择，未授权字段不展示。
-2. 支持xlsx/csv格式及当前列表查询条件。
-3. 创建后展示任务状态、进度、失败原因和下载按钮。
-4. 角色配置按scene分组展示字段复选框并保存。
+1. 列表导出只选择xlsx/csv格式并沿用当前查询条件，不展示字段复选框；实际列完全由后端权限解析。
+2. 页面可加载当前scene最终字段；返回空数组时禁用导出并提示“当前角色未配置该场景的导出字段”。
+3. 创建后展示任务状态、进度、失败原因、取消和下载按钮；页面刷新后按任务ID恢复轮询。
+4. 角色配置按scene分组展示代码支持字段，全量保存该角色单个scene的字段；允许清空，保存后重新读取服务端结果。
+5. 新增受保护附件落地页，展示加载中、登录恢复、无权限/不存在、文件不可用、解析失败和成功跳转状态。
 
 接口约定：
-- GET /api/admin/export-fields?scene= 返回 fields:{field_key,label,selected_by_default}[]。
-- POST /api/admin/export-tasks，body={scene,format,query,fields:string[]}，返回 task_id。
+- GET /api/admin/export-fields?scene= 返回当前账号最终会导出的 fields:{key,label}[]；它不是字段选择候选集。
+- POST /api/admin/export-tasks，body={scene,format,query}，返回 task_id；前端不得提交fields。
 - GET /api/admin/export-tasks/{id} 返回 status、status_name、progress、download_url、error_message。
-- GET/PUT /api/admin/roles/{role_id}/export-fields 查询和保存场景字段。
+- GET/PUT /api/admin/roles/{role_id}/export-fields 查询代码目录及保存角色场景字段；PUT按单个scene全量替换，空数组表示收回全部字段。
+- GET /api/admin/attachments/{attachment_ref}/download-url 返回 data:{download_url,expires_at,file_name}；请求必须携带后台当前Bearer Token。
 
-交互规则：下载地址为空时禁用下载；任务轮询复用统一异步任务规则；字段为空时禁止提交。
+导出流程：
+1. 用户在列表页发起导出，前端提交scene、format和当前筛选条件；分页参数不进入导出条件。
+2. 后端创建任务后，前端进入现有任务进度流程；download_url为空时禁用任务文件下载。
+3. 导出文件中的附件地址是后台前端绝对地址 `{admin_frontend_base_url}/export-attachments/{attachment_ref}`，不是后端接口地址或对象存储地址。
 
-完成标准：字段权限、任务恢复、失败重试和文件下载流程完整。
+附件访问流程：
+1. 浏览器打开附件落地页；未登录时保存当前站内路径并进入后台登录，登录成功后返回该附件页。
+2. 页面从路由读取attachment_ref，使用Bearer Token调用附件解析接口；禁止把attachment_ref替换为file_key，也禁止接收外部returnUrl。
+3. 后端根据附件关联的退款、充值或审批业务重新检查当前账号权限，成功返回短期私有对象地址。
+4. 前端在当前页跳转download_url，避免异步后新开窗口被浏览器拦截；地址过期时用户重新打开稳定落地页即可重新解析。
+5. 401按后台统一登录失效流程处理并保留当前附件页；无权与不存在展示统一不可访问状态；对象文件不可用或解析失败展示可重试错误，不展示file_key、media_id或底层存储错误。
+
+交互规则：用户不能选择导出字段；角色权限后来变化不改变已经创建任务的文件列，但打开附件时始终按当前权限重新鉴权；任务失败时展示后端原因，不自动重复创建任务。
+
+完成标准：平台、不同层级代理分别验证最终列和数据行范围；无字段状态、任务刷新恢复、CSV/XLSX下载、附件未登录返回、当前有权、权限后来收回、引用不存在和对象不可用流程完整。后端接口发布后，前端只需按上述固定契约接入，不再等待字段选择或永久对象URL方案。
 ```
 
 ### 后端研发需求
@@ -1088,23 +1107,29 @@
 **标题**
 
 ```text
-[BE][UR#42] 统一导出场景与角色字段权限
+[BE][UR#42] 统一导出、角色字段权限与受保护附件解析
 ```
 
 **描述**
 
 ```markdown
-目标：复用现有导出任务体系，增加本期场景和角色字段级权限。
+目标：复用现有导出任务体系，增加本期场景和角色字段级权限，并为退款/充值业务凭证和企微审批附件提供稳定引用、当前权限复核及短期私有下载地址解析。
 
-预计工时：后端4～6小时。
+预计工时：按本冻结范围重新评估；原4～6小时估算未包含全部新增场景、附件本地化与鉴权解析，不能继续沿用。
 
-接口：GET /api/admin/export-fields；POST /api/admin/export-tasks；GET /api/admin/export-tasks/{id}；GET/PUT /api/admin/roles/{role_id}/export-fields。
+接口：GET /api/admin/export-fields；POST /api/admin/export-tasks；GET /api/admin/export-tasks/{id}；GET/PUT /api/admin/roles/{role_id}/export-fields；GET /api/admin/attachments/{attachment_ref}/download-url。
 
-规则：最终字段=用户申请字段∩角色授权字段并集∩场景支持字段；超级管理员拥有全部字段；字段授权不能扩大数据行范围；创建任务时快照字段和表头；权限解析失败直接拒绝。
+规则：最终字段=当前账号有效角色授权字段并集∩场景代码支持字段；超级管理员拥有全部代码目录字段；前端不传fields，账号获授权字段全部导出；字段授权不能扩大菜单、接口、场景或数据行范围；创建任务时快照字段、表头、查询条件和数据范围；Worker不重读实时角色权限；权限解析失败或普通账号最终字段为空时不创建任务。
 
-场景：iot_card、agent_wallet_transaction、package、refund、exchange、agent_recharge、expiring_asset。审批附件只导出数量，不导出对象Key或永久URL。
+场景：扩展device、iot_card、order，并增加agent_wallet_transaction、package、refund、exchange、agent_recharge、expiring_asset。agent_recharge保留支付方式、不导出支付通道。
 
-完成标准：Count与Fetch条件一致，审批摘要批量查询，导出任务可恢复且无越权字段。
+字段目录：密码、密钥、Token、对象Key、企微media_id等永不允许导出的内容不注册；对已注册字段，角色配置是权威，不再增加主观敏感字段层。发布不迁移普通角色默认授权，停机窗口由业务使用超级管理员完成配置后再恢复服务。
+
+附件规则：退款/充值业务凭证与企微审批附件按字段权限导出稳定前端落地页URL，但字段授权不能突破审批主体可见性；代理可导出业务范围内的退款凭证，不能导出或解析平台内部企微审批附件。每个本地附件使用不可变、不可枚举attachment_ref，私有file_key不出后端。企微附件须先保存到本地私有对象存储；不得把临时media_id或预签名URL写入导出文件。
+
+解析流程：前端携带Bearer Token请求attachment_ref；后端解析其关联业务，在每次访问时重新校验当前业务查看权限、数据范围和附件种类可见性；成功返回短期download_url、expires_at、file_name。无权与不存在返回统一错误；权限后来收回后旧导出链接也不可下载，已知引用的代理也不能解析企微内部审批附件。
+
+完成标准：Count与Fetch条件一致，审批摘要和附件引用批量查询，无N+1；字段/表头/权限快照可恢复且无越权列或越权行；导出文件不含file_key、media_id或预签名URL；前后端按未登录、有权、权限收回、引用不存在、对象不存在和附件未本地化完成联调。
 ```
 
 ## UR#40 套餐设计
@@ -1185,15 +1210,16 @@
 2. 店铺资金页展示现金余额、冻结金额、实际信用额度、可用金额、欠款金额和版本。
 3. 店铺实际额度使用独立调整弹框，展示修改前后金额预览。
 4. 平台员工角色不展示信用配置。
+5. 代理账号即使能查看自己或下级代理资金，也不展示实际额度修改入口；平台账号只有取得独立信用额度管理权限后才展示。
 
 接口约定：
 - PUT /api/admin/roles/{id}/default-credit，body={credit_enabled:bool,credit_limit:int64}。
 - PUT /api/admin/shops/{id}/credit-limit，body={credit_enabled:bool,credit_limit:int64,version:int64}。
 - GET /api/admin/shops/fund-summary 返回 balance、frozen_balance、credit_enabled、credit_limit、available_balance、is_in_debt、debt_amount、version。
 
-交互规则：金额不在前端重新计算；并发冲突时刷新最新资金概况；关闭信用时额度输入归零。
+交互规则：金额不在前端重新计算；并发冲突时刷新最新资金概况；关闭信用时额度输入归零；不设置产品层固定额度上限，只执行分/元精确转换和接口整数安全范围校验。欠款只按接口is_in_debt/debt_amount展示，冻结金额不由前端换算为欠款。
 
-完成标准：角色默认、创建店铺初始化、已有店铺调额和并发冲突提示完整。
+完成标准：角色默认、创建店铺初始化、已有店铺调额、代理禁止调额、平台有/无独立权限、降低额度失败和并发冲突提示完整。
 ```
 
 ### 后端研发需求
@@ -1217,9 +1243,11 @@
 
 规则：修改角色不更新已有店铺；店铺后续角色变化不影响钱包；余额、冻结、信用、版本和资金流水在同一事务维护；调额按version乐观锁更新。
 
+权限：代理账号不得调整自己或任何下级代理额度，不能复用CanManageShop或普通店铺管理权限推导调额权；只有超级管理员或具备独立信用额度管理权限的平台账号可以修改实际额度。角色默认模板只允许超级管理员或具备相应角色管理权限的平台账号配置。信用额度不设产品层固定上限，但必须在int64范围内并拒绝负数与算术溢出。
+
 架构：钱包资金规则迁入Wallet Domain，查询走资金Query。
 
-完成标准：扣款、冻结、解冻、充值、退款回充和调额都维护同一不变量并写资金审计。
+完成标准：扣款、冻结、解冻、充值、退款回充和调额都维护同一不变量并写资金审计；代理调额请求始终拒绝；额度变更写Audit Event但不伪造金额为0的钱包流水。
 ```
 
 ## UR#37 审核流转
@@ -1229,34 +1257,40 @@
 **标题**
 
 ```text
-[FE][UR#37] 企微配置账号绑定与审批只读详情
+[FE][UR#37] 平台企微绑定、代理固定代提交与审批只读详情
 ```
 
 **描述**
 
 ```markdown
-目标：使用企业微信完成审批，本系统只负责配置、账号扫码绑定、状态查看和异常恢复。
+目标：平台/超级管理员绑定本人企微发起审批，代理使用固定企微账号代提交；本系统负责配置、状态查看和异常恢复，页面展示的申请人始终是本系统真实业务提交人。
 
-预计工时：前端6～8.5小时，包含多人审批业务映射展示。
+预计工时：前端6～8.5小时，包含平台账号扫码绑定、代理固定代提交状态和多人审批业务映射展示。
 
-页面入口：/system/wecom、个人中心、/operations/wecom-approvals、退款和线下充值详情。
+页面入口：/system/wecom、平台用户个人中心、/operations/wecom-approvals、退款和线下充值详情。
 
 页面结构：
-1. 企微配置页：连接状态、审批场景状态、模板版本列表、模板读取和业务字段到控件的可视化映射发布。
-2. 个人中心：绑定状态、成员名称、扫码绑定、重新绑定、解绑；不提供userid输入框。
-3. 审批运行页：业务类型、业务单号、sp_no、状态、模板版本、申请人、更新时间和异常标识；详情抽屉展示审批人、意见、附件、时间线和业务处理结果。
-4. 业务详情复用统一approval区块，只读展示，不提供通过、驳回、退回按钮。
+1. 企微配置页：连接状态、代理固定代提交账号就绪状态与成员显示名、审批场景状态、模板版本列表、模板读取和业务字段到控件的可视化映射发布；不提供固定userid在线修改入口。
+2. 平台用户个人中心：绑定状态、成员名称、扫码绑定、重新绑定、解绑；代理账号不展示绑定入口。
+3. 审批运行页：业务类型、业务单号、sp_no、状态、模板版本、真实业务提交人、企微发起身份来源、更新时间和异常标识；平台详情抽屉展示审批人、意见、附件、时间线和业务处理结果。
+4. 业务详情复用统一approval区块，只读展示，不提供通过、驳回、退回按钮；代理视图只展示真实业务提交人、审批状态、状态时间和业务处理结果，不展示平台内部审批人、意见或审批附件。
 
 接口约定：
 - GET /api/admin/wecom/status。
 - PUT /api/admin/wecom/approval-scenes/{scene_code}/status。
 - POST /api/admin/wecom/approval-templates/inspect、POST /api/admin/wecom/approval-templates/publish、GET /api/admin/wecom/approval-templates。
-- POST /api/admin/wecom/account-binding/sessions，返回 session_id、login_url、expires_at；GET /api/admin/wecom/account-binding/sessions/{session_id} 查询结果；GET/DELETE /api/admin/wecom/account-binding/me。
+- POST /api/admin/wecom/account-binding/sessions，返回session_id、login_url、expires_at；GET /api/admin/wecom/account-binding/sessions/{session_id}查询结果；GET/DELETE /api/admin/wecom/account-binding/me。
 - GET /api/admin/wecom/approvals、GET /api/admin/wecom/approvals/{id}、POST /api/admin/wecom/approvals/{id}/sync。
+- POST /api/admin/wecom/approvals/{id}/bind-sp-no，提交sp_no和必填恢复原因，由后端完成全量业务快照核对后绑定。
+- POST /api/admin/wecom/approvals/{id}/confirm-not-created-and-resend，提交必填恢复原因，仅用于人工确认企微未创建后重新发送同一审批申请。
 
-交互规则：扫码绑定页面轮询会话；未绑定创建审批时原地提供绑定入口；立即同步只拉取企微详情；通过后撤销且业务已执行时显示高风险提示。
+交互规则：平台/超级管理员未绑定时原地提供绑定入口，绑定成功后继续当前表单；代理不要求绑定，固定代提交账号不可用时按后端错误保留表单。审批列表和详情的“申请人”展示真实业务提交人，并可只读标识企微发起身份来源；立即同步只拉取企微详情；通过后撤销且业务已执行时显示高风险提示。
 
-完成标准：配置、绑定、列表、详情、同步和异常状态均有加载、空、失败及权限状态。
+权限约定：/system/wecom、场景/模板维护、账号绑定列表和强制解绑仅超级管理员可见；平台账号只能管理本人绑定，具备独立“企微审批运营”权限后才显示审批运行页和立即同步；“企微审批运营”不包含模板配置、绑定管理或异常恢复。代理不展示企微配置、绑定和运行页，只在其业务数据范围内的退款详情查看审批区块。
+
+信息可见性：代理自己提交的退款资料和业务凭证仍按退款查看权限展示，但企微审批人、内部意见及审批人上传的附件仅平台/超级管理员按退款查看权限访问。详情接口、受保护附件下载和导出执行同一主体权限投影，不能通过attachment_ref或历史导出链接绕过当前权限。
+
+完成标准：配置、平台绑定、代理固定身份状态、列表、详情、同步和异常状态均有加载、空、失败及权限状态。
 ```
 
 ### 后端研发需求
@@ -1264,7 +1298,7 @@
 **标题**
 
 ```text
-[BE][UR#37] 企业微信审批模板账号绑定回调与补偿
+[BE][UR#37] 企业微信审批模板、平台绑定、代理代提交、回调与补偿
 ```
 
 **描述**
@@ -1272,16 +1306,20 @@
 ```markdown
 目标：以稳定业务场景码接入企微审批，替代本地审批流。
 
-预计工时：后端9～11.5小时，包含多人审批场景映射。
+预计工时：后端9～11.5小时，包含平台账号扫码绑定、代理固定代提交和多人审批场景映射。
 
-接口：实现企微状态、场景暂停恢复、模板读取发布、扫码绑定、绑定管理、审批列表详情、立即同步及企微回调接口。
+接口：实现企微状态、场景暂停恢复、模板读取发布、平台账号扫码绑定与绑定管理、审批列表详情、立即同步及企微回调接口。
 
 规则：
 1. 场景码固定为 refund_approval、offline_recharge_approval，模板ID和控件ID按不可变版本映射。
 2. 模板编辑前暂停场景，发布新映射后恢复；历史实例保留模板和提交快照。
-3. 系统账号通过5分钟一次性会话扫码绑定企微userid，account_id和userid均唯一。
+3. applyevent发起身份按账号类型分流：平台/超级管理员必须使用当前账号扫码绑定的本人userid；代理使用部署配置中的固定企微userid。真实业务提交人以本地账号和显示快照独立保存，并写入模板必填submitter字段；审批实例保存实际userid与self_binding/agent_proxy来源，列表、详情、通知、权限和审计均以真实业务提交人为准。
 4. 回调只验签解密并触发统一SyncApprovalStatus；getapprovaldetail为状态权威来源；审批中实例每2分钟兜底轮询。
 5. 首次终态同事务写业务Outbox，business_processed_at保证只执行一次。
+6. applyevent已发出但结果未知时禁止自动重试；超级管理员或具备独立异常恢复权限的平台账号可选择“校验并绑定已有sp_no”或“确认未创建后重新发送”。重新发送属于同一审批申请的技术尝试，不创建业务审批轮次；绑定前必须核对企业、模板、实例中的实际企微userid及来源、业务场景、真实业务提交人字段和业务快照，两种动作均保留原尝试并写高风险审计。
+7. 场景暂停或模板失效时，新退款/线下充值在任何业务单、审批实例和Outbox落库前直接拒绝；前端保留表单，恢复后由用户重新提交。暂停前已经创建的审批继续回调、轮询同步和处理终态，不受暂停影响。
+8. 权限必须拆分：场景暂停恢复、模板读取发布、绑定列表和强制解绑仅超级管理员；平台账号只能管理本人绑定；审批运行列表/详情/立即同步要求独立“企微审批运营”权限；提交未知恢复要求独立“企微审批异常恢复”权限；代理无公共企微管理接口权限，只能按现有业务数据范围查看退款详情中的审批摘要。
+9. 审批详情按主体投影：代理只能读取真实业务提交人、审批状态/时间、业务处理结果及其业务范围内的退款资料和业务凭证；审批人、内部意见和审批人上传附件仅平台/超级管理员按业务查看权限读取。附件解析和导出必须复用当前主体权限，禁止旁路访问。
 
 架构：使用wecomapproval、wecomidentity Domain/Application，外部API和加解密进入WeCom Adapter，列表详情走Query。
 
@@ -1301,24 +1339,27 @@
 **描述**
 
 ```markdown
-目标：运营按一个代理和一种支付方式批量导入套餐订单，并查看逐行结果。
+目标：运营按一种支付方式批量导入套餐订单；同一CSV可包含不同代理的资产，系统逐行解析结算代理并展示结果。
 
 预计工时：前端3～4小时。
 
 页面入口：批量订购套餐页或现有订单页批量入口。
 
+权限：仅超级管理员或具备独立“批量订购套餐”权限的平台账号展示入口并调用创建、任务详情和明细接口；代理和企业账号不展示入口，后端仍必须独立拒绝。
+
 页面结构：
-1. 选择代理、整批支付方式（线下或代理钱包）、上传Excel；线下支付时上传整批凭证。
-2. 模板下载使用前端静态文件。
+1. 选择整批支付方式（线下或代理钱包）并上传CSV；不选择代理，线下支付时上传整批凭证，不接受Excel。
+2. CSV模板下载使用前端静态文件，编码为UTF-8并允许BOM。
 3. 创建后展示任务号、状态、总数、成功数、失败数、金额汇总和失败明细表。
 4. 失败明细包含行号、资产、套餐编码、错误原因；支持按任务ID恢复页面。
 
 接口约定：
-- POST /api/admin/bulk-purchases，multipart包含 shop_id、payment_method、file、voucher_file、request_id。
+- CSV先调用POST /api/admin/storage/upload-url，purpose=bulk_purchase，使用返回的upload_url直传后取得file_key；线下凭证按附件用途直传取得voucher_keys。
+- POST /api/admin/bulk-purchases只接收JSON：request_id、payment_method、file_key、voucher_keys；不接收shop_id、multipart或文件字节。
 - GET /api/admin/bulk-purchases/{task_id} 返回任务汇总。
 - GET /api/admin/bulk-purchases/{task_id}/items?page=&size=&status= 返回逐行结果。
 
-交互规则：一个批次不能混合支付方式；部分成功视为任务终态；钱包余额不足只影响对应行或后续行，不回滚已成功行。
+交互规则：一个批次不能混合支付方式；同一CSV允许不同代理资产，代理归属由后端逐行解析，前端不提交或猜测；部分成功视为任务终态；某代理钱包余额不足只影响使用该钱包的相应行，不回滚已成功行。
 
 完成标准：上传、进度恢复、部分成功、失败筛选和凭证展示完整。
 ```
@@ -1340,9 +1381,9 @@
 
 接口：POST /api/admin/bulk-purchases；GET /api/admin/bulk-purchases/{task_id}；GET /api/admin/bulk-purchases/{task_id}/items。
 
-规则：整批选择offline或agent_wallet；模板按套餐编码匹配；文件最大10MB、最多1000行；request_id唯一返回原任务；行幂等键为bulk_purchase:{task_id}:{row_no}。
+权限：仅超级管理员或具备独立“批量订购套餐”权限的平台账号可创建和读取任务；代理、企业账号一律拒绝。规则：整批选择offline或agent_wallet，不接收shop_id；同一CSV可以包含不同代理资产，逐行以资产当前归属解析结算代理；CSV和凭证先直传私有对象存储，业务接口只接收稳定file_key/voucher_keys；仅接受UTF-8 CSV（允许BOM），不接受Excel；模板按套餐编码匹配；文件最大10MB、最多1000行；同一文件按“资产类型+标准化资产标识+套餐编码”判重，首行正常处理、后续重复行失败并指出首行号，同一资产的不同套餐不算重复；request_id唯一返回原任务；行幂等键为bulk_purchase:{task_id}:{row_no}。
 
-钱包行事务：锁主钱包，按信用不变量校验，订单、扣款、流水和明细成功状态同事务；单行失败不回滚其他行；任务统计从明细重新聚合。线下凭证只做本批资料，不校验跨批唯一。
+钱包行事务：锁该行资产所属代理的主钱包，按信用不变量校验，订单、扣款、流水、结算代理快照和明细成功状态同事务；无代理归属、无有效主钱包或余额不足只失败对应行，单行失败不回滚其他行；任务统计从明细重新聚合。线下凭证只做本批资料，不校验跨批唯一。
 
 完成标准：Worker处理租约、重复消费、进程中断恢复和部分成功均不产生重复订单或重复扣款。
 ```
@@ -1376,11 +1417,10 @@
 接口约定：
 - POST /api/admin/refunds 创建退款。
 - GET /api/admin/refunds/{id} 返回退款数据、approval对象和processing_status。
-- POST /api/admin/refunds/{id}/resubmit，仅已驳回、已撤销或已删除可重新申请。
 - attachments使用现有对象存储上传结果，提交结构为 {file_key,file_name,file_size}[]。
 - approval结构至少包含 source、sp_no、status、status_name、template_version、applicant、approvers、comments、attachments、timeline、business_process_result。
 
-交互规则：非代理钱包由财务在系统外人工退款后再在企微通过；重新申请可改金额、凭证和原因，不可改订单、资产和提交人快照。
+交互规则：非代理钱包由财务在系统外人工退款后再在企微通过。企微拒绝后当前退款单终结，详情只读且不提供编辑或重提；业务人员处理拒绝原因后仍需退款时，重新进入创建退款流程并填写金额、凭证和原因，成功后展示新的退款ID、退款单号和审批信息。
 
 完成标准：审批中、通过处理中、处理成功、驳回、撤销和通过后撤销异常状态均展示明确。
 ```
@@ -1400,14 +1440,14 @@
 
 预计工时：后端4～5小时。
 
-接口：POST /api/admin/refunds；GET /api/admin/refunds/{id}；POST /api/admin/refunds/{id}/resubmit；下线原approve/reject/return路由。
+接口：POST /api/admin/refunds；GET /api/admin/refunds/{id}；下线原approve/reject/return/resubmit路由。
 
 规则：
 1. 非代理钱包支付由财务人工退款，企微通过代表人工退款已确认，不调用渠道退款API。
 2. 代理钱包订单通过后按原扣款流水幂等回溯原代理主钱包并写退款流水。
 3. 个人客户或资产钱包不自动回款。
 4. 驳回更新为已拒绝；撤销/删除更新为已撤销；通过后撤销且资金已执行不自动冲正，记录critical审计。
-5. 重新申请创建round_no+1企微实例并保留历史。
+5. 一张退款单只创建一条企微审批申请，业务表保存唯一approval_instance_id并由(biz_type,biz_id)唯一约束防重。正常结果只有同意或拒绝，任一结果产生后审批与退款单同时完结；拒绝后原退款单不可修改、不可重提。若仍需退款，必须重新调用创建接口，生成新的退款ID、退款单号、业务快照、提交人快照和企微审批；旧单只保留为历史事实，已拒绝退款不阻止新建，但仍需阻止存在其他活跃退款时重复创建。撤销、删除或通过后撤销只作外部异常处置，不作为自动放行新退款的依据。
 
 完成标准：审批状态与业务处理状态分离，重复终态不重复回款，失败任务可可靠重试。
 ```
@@ -1778,12 +1818,12 @@
 完成标准：后台、C端、临期列表、通知和导出使用同一套餐生命周期结果。
 ```
 
-### INT-04 Excel批量任务与导出联调
+### INT-04 CSV批量任务与导出联调
 
 **标题**
 
 ```text
-[INT-04] Excel批量任务与导出联调
+[INT-04] CSV批量任务与导出联调
 ```
 
 **描述**
@@ -1837,9 +1877,9 @@
 
 参与工时参考：前端1.5～2小时、后端1.5～2小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
 
-进入条件：模板映射、扫码绑定、审批提交、回调、2分钟轮询、退款和线下充值终态处理完成。
+进入条件：模板映射、平台账号绑定、代理固定代提交账号验证、审批提交、回调、2分钟轮询、退款和线下充值终态处理完成。
 
-联调范围：账号扫码绑定、未绑定拦截、模板发布、发起审批、意见附件、通过/驳回/撤销/删除、回调重复、立即同步、退款人工处理、代理钱包回溯、线下充值入账和列表审批摘要。
+联调范围：平台账号扫码绑定与未绑定拦截、代理固定代提交账号有效/失效拦截、两类企微发起身份、真实业务提交人展示、模板发布、发起审批、意见附件、通过/驳回/撤销/删除、回调重复、立即同步、退款人工处理、代理钱包回溯、线下充值入账和列表审批摘要。
 
 完成标准：本系统无审批按钮，企微状态与业务处理状态分离，终态重复同步不重复执行资金动作。
 ```
@@ -1861,7 +1901,7 @@
 
 进入条件：统一限速接口、卡和设备详情入口、Gateway联调配置完成。
 
-联调范围：单卡设置、设备解析当前卡、speed_kbps单位、0取消限速、设备无当前卡、Gateway失败及审计记录。
+联调范围：单卡固定speed_level、设备解析当前卡、恢复不限速与限到0kbps区分、设备无当前卡、电信/广电档位映射、联通/移动不支持、Gateway失败/结果未知及审计记录。
 
 完成标准：Gateway收到的cardNo始终为卡ICCID，设备号不会被发送，上游结果在页面和审计中可追踪。
 ```