店铺物流配置产品 PRD

状态：review-passed（采用店铺运营管理下的二级菜单架构）

产品 PRD 版本：1.1

当前变更：CR-20260805-014

交付包：prd-package.json

本 PRD 的页面结构、交互方式、组件行为、权限控制与状态定义，均遵循《UI 交互规范主文件》；未单独说明者，默认按该规范执行。

0. 输出策略

项目	内容
写入方式	分阶段评审、分阶段写入；每一段经 Freddy 明确确认后立即写入。
已写入	Phase 1–5：范围、流程、字段、交互、权限、历史数据和验收口径。
架构修正	Phase 1–5 中已确认的平台能力与边界继续有效；原“独立店铺物流配置页面”不再是有效页面方案。
Phase 6 本轮结论	保持原店铺运营管理列表、店铺状态、筛选文案和归属配置交互不变；店铺名称进入单店运营档案全页，不新增总览列、店铺范围概念或漏配/配错筛选控件。
Phase 7 当前结论	在“店铺运营管理”内设置“运营归属管理 / 平台后台管理”二级菜单；原页面完整归入前者，新增能力只在后者及其单店后台档案中承接。
Phase 8 当前结论	平台后台管理内再按“全部 / Shopee / Lazada / TikTok Shop”平台页签分组店铺；移除“已接入后台能力”列，行操作统一为“查看”。
Phase 9 当前结论	仅平台页签使用小尺寸平台识别 Logo；“平台后台管理”二级菜单保持文字，Logo 仅用于快速识别平台分组，不改变页签语义。
Phase 10 当前结论	外部平台交互必须以字段级 API 契约为准：官方资料 URL、生产 URL/方法、请求映射、回包留存、回读与错误策略均进入 PRD 交付包；未核验字段不允许进入实现。
Phase 11 当前结论	当前模块采用原型同级交付目录；需求日志记录本次发布，原型与交付目录已发布至稳定在线地址。

0.1 店铺运营管理整合修正（Phase 6 已确认事实）

已确认事实	对页面方案的约束
店铺运营管理用于统一管理和查阅店铺运营侧信息。	物流配置必须是店铺运营信息的一部分，而不是脱离店铺上下文的独立模块。
业务单元、销售员、客服缺失是当前页已存在的运营准备问题。	原有异常筛选、批量归属配置和直接字段展示必须保留。
地址/仓库、物流渠道等是卖家在平台店铺创建时完成的后台基础设置。	本系统没有其“待完成/未配置”的数据来源；不形成运营待办、状态、筛选或告警。单店详情仅在平台接口允许时查询或维护既有对象。
账号管理部负责新增店铺、授权和凭据；业务团队不持有店铺密码。	页面不展示或操作授权、密码、新增店铺；业务团队只处理运营归属、基础设置和经营数据。
店铺后台指标用于业务团队查看店铺后台经营表现。	不再使用“后台健康”承载授权、到期或同步故障；没有经核验的平台指标契约时只展示中性空态，不虚构指标或阈值。

0.2 方案替代记录

早期“店铺选择器 + 能力集合 + 店铺运营总览/Drawer”的方案已被 §0.4–§0.5 的二级菜单与单店后台档案方案替代，不再作为可实现规格。保留替代记录仅用于解释历史评审，不保留旧字段、旧交互或旧页面要求。

替代项	当前有效方案
店铺选择器进入配置	在“平台后台管理”列表按平台筛选并点击店铺名称或“查看”进入单店后台档案。
面向页面下发“能力集合”	服务端按平台、店铺类型、接口契约和权限逐个判定动作；该门控不作为页面字段、筛选条件或列表列。
店铺运营总览/归属治理快捷查询	运营归属管理保留原页；平台后台管理负责后台表现与单店档案入口。
详情 Drawer	使用单店后台档案全页；地址编辑和角色设置仍使用轻量 Drawer/Modal。

0.4 原页面基线保留修正（Phase 6 已确认；Phase 7 归入“运营归属管理”）

原页面已确认设计	本期处理	不允许的改动
左侧“店铺管理 / 店铺状态 / 未分配店铺 / 全部店铺”	原样保留名称、层级与筛选含义。	不改为“店铺范围”，不新增归属异常树节点。
右侧“店铺管理”表	原列顺序保持店铺名称、所属平台、销售员、客服、业务单元、操作。	不增加站点、后台评分/表现、归属治理等总览列。
平台下拉、跨 BU 店铺搜索，以及全部/待分配/缺销售/缺客服筛选	原样保留。	不替换为多字段检索表单，不增加“漏配/配错”筛选 Chip。
编辑/批量配置店铺归属	原字段、必填性、生效日期、长期有效和结束日期交互保持一致。	不以简化表单替代现有配置/编辑归属弹窗。
新增运营能力入口	原列表不新增后台档案入口；平台后台能力从二级菜单“平台后台管理”进入。	不用 Drawer 把评分、表现、后台设置和归属挤在原列表旁。

“配错”的便捷查询需要人员 BU 归属、人员状态、归属有效期等正式数据源。该数据未核验前，不能在原页面虚构筛选项；一期先沿用已确认的未分配、缺销售、缺客服查询能力，并在单店档案中提供运营信息查阅。

0.5 二级菜单架构（Phase 7 已确认）

0.5.1 信息架构与边界

店铺运营管理 是一级模块；二级菜单按数据归属与业务责任划分，而不是按“信息/配置”这类模糊动词划分。这样经营指标不会从物流配置中游离，也不会污染归属治理列表。

二级菜单	定位	数据与操作	明确不包含
运营归属管理	内部运营责任归属的治理入口。	保留原左侧店铺状态、原列表列序、平台与跨 BU 搜索、全部/待分配/缺销售/缺客服、单店编辑、批量配置和既有转移。	平台指标、地址/仓库、物流渠道、平台设置档案入口。
平台后台管理	按平台分组查阅店铺在平台后台的经营数据，并进入后台档案。	“全部 / Shopee / Lazada / TikTok Shop”页签、店铺搜索、店铺类型、实际经营指标摘要与“查看”。	店铺授权、密码、账号生命周期、新增店铺；“已接入后台能力”列表列，以及以“配置完成度”或“待配置”管理平台创建期资料。
单店后台档案	一个店铺的平台后台信息与设置操作页。	店铺身份、经营表现、平台后台设置、操作记录；Shopee 已核验能力可操作并回读。	业务单元/销售员/客服的配置与归属编辑。

0.5.2 页面流与操作归属

销售运营管理
└─ 店铺运营管理
   ├─ 运营归属管理（原页面，不改其表内结构）
   │  └─ 配置/编辑/转移运营归属
   └─ 平台后台管理（本期新增）
      └─ 单店后台档案
         ├─ 经营表现（只读；无指标时中性空态）
         ├─ 平台后台设置（仅实际已接入能力）
         └─ 操作记录

规则	已确认行为
原页面保护	“运营归属管理”仅在页面标题下新增二级菜单定位；其左侧筛选、表格列序、筛选文案、归属弹窗和操作保持原设计。
后台表现	指标接口未核验前，平台后台管理仅标识“暂无已接入指标”，单店档案使用中性空态；不伪造评分、趋势或异常。
平台设置	平台接口能力仅用于单店后台档案内决定可见动作，不作为跨店列表字段，也不表示卖家后台设置是否齐全。
平台分组	平台后台管理使用“全部 / Shopee / Lazada / TikTok Shop”页签切换店铺集合；平台页签来自本期三平台范围，不用“全部平台”下拉替代。
行操作	后台管理列表统一使用“查看”，避免重复说明“后台档案”这一已由页面上下文表达的对象。
平台识别	Shopee、Lazada、TikTok Shop 平台页签在名称左侧使用 16–20px 平台识别 Logo；二级菜单“平台后台管理”保持纯文字。名称不可省略，Logo 不单独承载状态、权限或配置完成度。
归属与后台解耦	运营归属不在单店后台档案内编辑；平台后台设置也不出现在运营归属管理列表中。

1. 背景与目标（Phase 1）

1.1 业务问题梳理

模块	业务背景	当前问题	根因分析	目标结果	影响范围	优先级	风险点	待确认项
店铺物流配置	运营人员需要查看和维护店铺平台侧的地址/仓库、地址角色和物流渠道。	各平台能力不同，不能按统一 CRUD 处理。	平台后台能力、Open API 和店铺履约类型存在差异。	单店上下文中只展示平台实际可接入的对象和动作。	店铺、平台地址、仓库、渠道、COD、同步记录。	P0	把平台后台能力误当 Open API 能力。	现有权限角色映射。

1.2 冻结事实与约束

ID	事实 / 约束	状态	影响
F-001	模块只服务店铺后台配置，不进入订单发货。	已确认	不设计订单侧地址、仓库或渠道选择。
F-002	Shopee 先通过 `get_address_list` 读取已有地址；Open API 可更新既有地址内容，不支持 API 新增。	已确认	不提供新增。
F-003	Shopee 地址内容与默认、揽收/发货、退件角色分开操作；角色使用 `set_address_config`。	已确认	两个独立保存动作。
F-004	Shopee 3PF 店仓库仅读取，系统已有 3PF 标识。	已确认	不新建识别逻辑，前后端均禁止编辑。
F-005	Shopee 渠道可更新启用状态与 COD。	已确认	渠道与 COD 的配置必须回读确认。
F-006	Shopee `delete_address` 是否当前开放未核验；本期不接入删除。	已确认范围	仅保留平台侧移除历史。
F-007	Lazada 已确认仓库读取/编辑接口；TikTok Shop 已确认普通店/跨境仓库读取及仓库渠道读取接口。字段、权限和错误码仍按各接口单独核验。	接入条件已冻结	已确认接口能力不等于字段级可实现；未核验前不展示编辑入口或虚构字段。
F-008	地址页面不脱敏；操作日志不记录完整地址、电话原值。	已确认	展示与审计明细分离。

1.3 目标与成功标准

类型	目标	口径	当前基线	目标值	验收方式
业务	平台能力受控接入	无能力即无功能	未建立统一模块	无伪按钮、无本地替代写入	P0 场景验收。
用户	横向查看店铺表现并在单店档案完成已接入配置的查看与维护	不离开当前 ERP 模块	待量化	总览 + 单店全页档案 + 轻量编辑弹层闭环	交互验收。
数据	平台快照可追溯	成功、失败、平台移除均有状态	待建立	同步失败不误标移除	异常验收。
定量 KPI	操作耗时、同步成功率	后续埋点定义	未提供	本期不设目标值	原型验收不以虚构 KPI 代替业务验收。

2. 用户与场景（Phase 1）

角色	主要任务	数据范围	权限边界	用户故事
店铺物流配置查看者	查看地址/仓库、渠道、同步与历史记录。	授权店铺。	只读与同步。	从平台后台管理进入单店档案后确认平台当前配置。
店铺物流配置操作人	修改 Shopee 已开放的地址、角色、渠道配置。	授权店铺。	仅平台能力与店铺类型均允许时可写。	受控修改后以平台回读确认结果。

场景 ID	场景	前置条件	触发动作	理想结果
S-001	查看配置	有店铺查看权限	从平台后台管理点击“查看”	展示单店档案；无字段级契约的设置使用中性空态。
S-002	更新 Shopee 地址	普通店、地址有效、具备写权限	编辑地址	内容更新后回读，角色不变化。
S-003	设置 Shopee 角色	普通店、具备角色能力	设置地址角色	角色独立更新，内容不变化。
S-004	更新 Shopee 渠道	普通店、具备渠道写能力	变更渠道/COD	平台回读成功后才刷新。

3. 产品方案（Phase 2）

3.1 MVP 范围

范围项	本期	优先级	纳入 / 排除理由	依赖
单店后台档案内的平台后台设置	是	P0	配置绑定唯一店铺，避免误改；入口由平台后台管理列表行提供。	现有店铺主数据与后台档案。
地址/仓库同步、详情、移除历史	是	P0	平台对象统一读取与追溯基础。	平台读取接口。
Shopee 地址内容更新	是	P0	已确认 `update_address` 能力。	写入与回读。
Shopee 地址角色设置	是	P0	已确认 `set_address_config` 能力。	写入与回读。
Shopee 渠道/COD 更新	是	P0	已确认 `update_channel` 能力。	写入与回读。
Lazada 仓库读取/编辑、TikTok Shop 仓库/渠道读取	条件包含	P0/P1	已确认平台接口入口；仅字段契约与授权核验后开放对应数据表面或写操作。	平台适配器。
新增、删除、订单发货、多店批量	否	—	不在已确认边界。	—

3.2 核心流程

flowchart LR
  A[平台后台管理按平台筛选店铺] --> B[进入单店后台档案]
  B --> C[服务端按平台、店铺类型、接口契约和权限判定动作]
  C --> D{地址/仓库读取动作已开放}
  D -- 是 --> E[同步平台快照]
  D -- 否 --> F[展示中性空态，不提供操作]
  E --> G{Shopee普通店且写入动作已开放}
  G -- 更新内容 --> H[update_address后回读]
  G -- 设置角色 --> I[set_address_config后回读]
  C --> J{渠道读取动作已开放}
  J -- 是 --> K[同步渠道]
  J -- 否 --> L[展示中性空态，不提供操作]
  K --> M{渠道写入动作已开放}
  M -- 是 --> N[确认变更后update_channel并回读]
  M -- 否 --> O[只读]

3.3 能力门控

平台 / 店铺类型	地址/仓库读取	地址内容编辑	地址角色	渠道读取	渠道/COD更新	删除
Shopee 普通店	是	是	是	是	是	否
Shopee 3PF 店	是	否	否	待权限核验	待权限核验	否
Lazada	接口已确认，字段待核验	接口已确认，字段待核验	不适用/待确认	未确认接口	未确认接口	否
TikTok Shop	接口已确认：普通店字段已核验；跨境字段待核验	否	不适用/待确认	接口已确认，字段待核验	未确认接口	否

4. 功能范围（Phase 2）

排除 ID	不做内容	排除原因	若误做的风险
OOS-001	ERP 新增平台地址/仓库	Shopee 已确认不支持 API 新增；其他平台未核验。	生成无法下发的平台孤儿数据。
OOS-002	ERP 调用平台删除地址	用户明确不接入，且接口开放状态未核验。	错删平台履约配置。
OOS-003	订单发货页选择地址或渠道	用户明确仅服务店铺后台。	与订单履约逻辑混淆。
OOS-004	3PF 仓库编辑	用户明确禁止。	违反平台履约限制。
OOS-005	多店批量配置	仅确认单店上下文。	跨店部分失败难以恢复。

5. 功能设计与业务规则（Phase 3）

5.1 店铺能力判断与同步

5.1.1 功能定义

优先级	角色	功能点	触发条件	前置条件	业务结果
P0	查看者/操作人	进入单店后台档案	从平台后台管理点击店铺名称或“查看”	有店铺查看权限	返回店铺上下文、最近快照、经营表现和当前可执行动作的展示结果。
P0	查看者/操作人	同步地址/仓库或渠道	在单店后台档案点击当前设置页签的同步	对应读取动作已按接口契约和权限开放	写入/更新平台快照。

5.1.1.1 同步功能的 API 对接与字段映射

业务功能	API 名称	官方文档 URL	已核验生产地址 / 方法	平台传参	返参记录与业务处理	当前可用性
同步 Shopee 既有地址	`get_address_list`	https://open.shopee.com/documents/v2/v2.logistics.get_address_list?module=95&type=1	`GET https://partner.shopeemobile.com/api/v2/logistics/get_address_list`	无业务 Body；服务端注入 `partner_id,timestamp,access_token,shop_id,sign`。	记录 `request_id,error,message,response.show_pickup_address`；逐条保存 `address_id,region,state,city,address,zipcode,district,town,address_type[]`。仅完整成功才参与移除对账。	可实现。
同步 Shopee 物流渠道	`get_channel_list`	https://open.shopee.com/documents/v2/v2.logistics.get_channel_list?module=95&type=1	`GET https://partner.shopeemobile.com/api/v2/logistics/get_channel_list`	无业务 Body；服务端注入 Shopee V2 公共参数。	保存 `logistics_channel_id,logistics_channel_name,enabled,cod_enabled,force_enable,mask_channel_id,compulsory_channel,channel_relation_rules,auto_call_driver_setting`；其余已返回字段保存至原始快照。	可实现。
同步 TikTok Shop 普通店仓库	`Get Warehouse List`	https://partner.tiktokshop.com/docv2/page/get-warehouse-list-202309	`GET https://open-api.tiktokglobalshop.com/logistics/202309/warehouses`	Header：`x-tts-access-token`、`content-type: application/json`；Query：`app_key,sign,timestamp,shop_cipher`；无业务 Body。	记录 `code,message,request_id`；逐条保存 `id,entity_id,name,effect_status,type,sub_type,is_default,address`，以及已核验地址字段 `region,state,city,distict,town,contact_person,first_name,last_name,first_name_local_script`。	可实现；`code != 0` 不视为同步成功。
同步 Lazada 仓库	`QueryWarehouseDetailInfoBySellerId`	https://open.lazada.com/apps/doc/api?path=%2Frc%2Fwarehouse%2Fdetail%2Fget	已确认仓库读取接口路径 `/rc/warehouse/detail/get`；方法、Host、参数和返参均未核验。	不发起调用。	不创建字段解析或快照。	接口能力已确认；字段级同步冻结，待获取官方参数表和样例回包。
同步 TikTok Shop 跨境仓库 / 仓库渠道	`Get Global Seller Warehouse` / `Get Warehouse Delivery Options`	https://partner.tiktokshop.com/docv2/page/get-global-seller-warehouse-202309 https://partner.tiktokshop.com/docv2/page/get-warehouse-delivery-options-202309	已确认跨境仓库读取与仓库渠道读取接口入口；方法、Host、参数和返参均未核验。	不发起调用。	不创建字段解析或快照。	接口能力已确认；字段级同步冻结。

统一留存：每次调用记录 ERP operation_id、平台/店铺/对象 ID、HTTP 状态、平台 request_id、错误码/文案、发起/完成时间与最终状态。原始回包加密受控保存；业务操作日志不写完整地址、电话、令牌、签名或密钥。

5.1.2 字段取值逻辑

字段名称	类型	必填	默认值	取值逻辑	枚举值	校验规则	空值/异常显示
当前店铺 ID	string	是	路由参数	从平台后台管理行“查看”或店铺名称进入时写入路由上下文	当前店铺	单店档案只能绑定一个店铺	缺失时返回平台后台管理，不加载档案。
平台	enum	是	店铺主数据回填	单店后台档案头部只读展示	`SHOPEE`/`LAZADA`/`TIKTOK_SHOP`	前端不可改	`—`。
店铺类型	enum	否	店铺主数据回填	单店后台档案头部只读展示	普通/3PF/其他注册类型	服务端判定	未返回显示 `—`。
动作门控结果	server-only object	是	不对页面下发字段	服务端按平台、店铺类型、接口字段契约、权限和店铺范围逐个判定读取/写入动作；仅据此返回可展示对象与可见操作	读取/写入/只读/不支持	不作为列表列、筛选或页面字段；前端不得自行推断	不支持时显示该设置的中性空态，不展示伪按钮。
同步状态	enum	是	`IDLE`	最近同步任务，按店铺与对象类型分别记录	`IDLE`/`RUNNING`/`SUCCESS`/`FAILED`	同店同对象类型互斥	失败显示重试。

5.1.3 交互说明

场景	组件	触发动作	前端交互	后端逻辑	错误处理
进入单店档案	`Typography.Link` / 行操作“查看”	点击店铺名称或“查看”	保留平台页签、搜索和分页上下文；以当前店铺 ID 路由进入档案	读取店铺主数据、快照和服务端动作门控结果	无权限不进入档案，返回标准无权反馈。
同步	`Button`、`Spin`、`Message`、`Alert`	点击	按钮 loading，禁止重复提交	完整读取、分页完成后更新快照	失败保留旧快照，不标记移除。

5.1.4 正向与异常路径

路径	用户动作	系统行为	结果
正向	进入单店档案后点击当前设置页签的同步	服务端判定动作、完整读取、保存快照	展示已接入对象及当前允许的操作。
异常	平台超时、限流、分页失败	记录失败，不执行移除对账	Alert + 重试；历史有效记录不变。

5.1.5 逆向流程

逆向场景	触发条件	数据影响	修正规则	限制	审计
同步失败重试	最近同步失败	不覆盖最近成功快照	重试成功后刷新	同店同对象类型互斥	记录结果摘要。

5.1.6 权限

角色	页面	按钮	字段	数据范围	无权反馈
查看者	可见	查看、同步	只读	授权店铺	不展示写操作。
操作人	可见	按能力同步和写入	按能力可编辑	授权店铺	无能力即隐藏。

5.1.7 历史数据

数据对象	来源	是否迁移	初始化	历史状态	回滚	验证
平台快照	首次完整同步	否	首次结果为初始快照	无历史不推断移除	删除本模块快照后重新同步	与平台响应比对。

5.2 地址与仓库快照及平台移除历史

5.2.1 功能定义

优先级	角色	功能点	前置条件	业务结果
P0	查看者/操作人	查看地址/仓库	已成功同步或存在历史快照	展示有效平台对象。
P0	查看者/操作人	查看已移除记录	勾选“含已移除记录”	只读展示平台侧移除历史。

5.2.2 字段取值逻辑

字段名称	类型	必填	默认值	取值逻辑	枚举值	校验规则	空值/异常显示
平台对象 ID	string	是	—	平台返回	—	平台+店铺+类型+ID 唯一	缺失不写快照。
对象类型	enum	是	—	适配器映射	`ADDRESS`/`WAREHOUSE`	不混用 ID	`—`。
完整地址	string	否	`—`	平台原文	—	只读	`—`。
联系人/电话	string	否	`—`	平台原文	—	页面不脱敏；日志不记录原值	`—`。
生命周期	enum	是	`ACTIVE`	完整成功同步对账	`ACTIVE`/`PLATFORM_REMOVED`	失败同步不得改变	灰色移除 Tag。
最后同步时间	datetime	是	—	最近成功读取	—	服务端时间	`—`。
移除发现时间	datetime	否	`—`	完整成功同步未返回旧对象时写入	—	不可手动设定	有效记录显示 `—`。

5.2.3 交互说明

场景	组件	前端交互	后端逻辑	错误处理
列表	`ProTable`、`Tag`、`Input`、`Select`	默认仅有效；常驻查看	查询本模块快照	区分未同步与筛选无结果。
详情	`Drawer`、`ProDescriptions`、`Tabs`	基本信息和操作记录	读取快照与日志	已移除对象只读。

5.2.4 正向与异常路径

路径	用户动作	系统行为	结果
正向	同步后查看列表	显示 `ACTIVE` 对象	当前配置可查。
正向	勾选含已移除记录	查询历史快照	显示移除发现时间。
异常	平台返回不完整	不做移除对账	不误报移除。

5.2.5 逆向流程

逆向场景	触发条件	数据影响	修正规则	限制	审计
平台对象重新出现	已移除对象在后续完整同步再次返回	状态回到 `ACTIVE`	保留移除历史并刷新内容	同一平台对象 ID	记录恢复发现。

5.2.6 权限

角色	页面	按钮	字段	数据范围	无权反馈
查看者	可见	查看、筛选	只读	授权店铺	无店铺权限时无数据入口。
操作人	可见	同查看者；写操作另按能力	不允许本地直接编辑	授权店铺	无写能力不展示编辑。

5.2.7 历史数据

数据对象	来源	是否迁移	初始化	历史状态	回滚	验证
已移除记录	快照对账	否	首次同步不生成	仅后续完整成功同步产生	删除快照后重新全量同步	连续成功同步验证。

5.3 Shopee 地址编辑与地址角色

5.3.1 功能定义

优先级	角色	功能点	前置条件	业务结果
P0	操作人	更新地址内容	普通店、写权限、`update_address` 能力	平台地址内容更新并回读。
P0	操作人	设置地址角色	普通店、角色权限、`set_address_config` 能力	角色独立更新并回读。

5.3.1.1 地址功能的 API 对接与字段映射

业务功能	API 名称	官方文档 URL	已核验生产地址 / 方法	平台入参（类型 / 来源）	返参记录与回读	业务规则
保存地址内容	`update_address`	https://open.shopee.com/documents/v2/v2.logistics.update_address?module=95&type=1	`POST https://partner.shopeemobile.com/api/v2/logistics/update_address`，JSON	必传 `address_id:int64`，来自最近成功地址快照；可选 `region,state,city,district,town,address,zipcode,name,phone,geo_info:string`，来自已核验表单字段。	返回只记录 `request_id,error,message`，无业务 response；成功后强制调用 `get_address_list` 回读，回读成功才覆盖有效地址快照。	`region` 不允许更新；不传地址角色；`geo_info` 保持原值时不传，清空传 `""` 或 `{}`。
设置地址角色	`set_address_config`	https://open.shopee.com/documents/v2/v2.logistics.set_address_config?module=95&type=1	`POST https://partner.shopeemobile.com/api/v2/logistics/set_address_config`，JSON	可选 `show_pickup_address:boolean`；可选 `address_type_config`，含 `address_id:int64,address_type:string[]`。	返回只记录 `request_id,error,message`，无业务 response；成功后强制回读地址列表，保存 `address_type[]` 与 `show_pickup_address`。	内容保存与角色保存分请求；请求枚举 `PICKUP_ADDRESS` 与回读枚举 `PICK_UP_ADDRESS` 拼写不同，必须按联调映射处理，禁止自行改写。

UI 展示字段	Shopee 返回 JSON Key	数据类型	落库 / 业务口径
平台地址 ID	`address_id`	int64	唯一定位既有地址，也是两类写入接口的目标。
行政区和详细地址	`region,state,city,district,town,address,zipcode`	string	地址快照；完整成功读取后用于展示与移除对账。
地址角色	`address_type[]`	string array	保存默认、揽收、退件及入库揽收角色；使用平台原值。
是否展示揽收地址	`show_pickup_address`	boolean	地址角色配置的回读值。

5.3.2 字段取值逻辑

字段名称	类型	必填	默认值	取值逻辑	枚举值	校验规则	空值/异常显示
地址内容表单	object	是	当前平台回读值	仅呈现已核验 `update_address` 字段	以接口契约为准	前后端同校验	未核验字段不渲染。
地址角色	array	否	当前回读值	仅由角色接口修改	`DEFAULT`/`PICKUP`/`RETURN`	以平台规则为准	无角色显示 `—`。
平台对象 ID	string	是	当前地址 ID	详情上下文回填	—	不可编辑	缺失禁止提交。

5.3.3 交互说明

场景	组件	前端交互	后端逻辑	错误处理
编辑地址	`DrawerForm`、`Form`	联系人、行政区、详细地址按 Schema 分组；保存中锁定	更新后回读	失败不改本地快照。
设置角色	`Modal`、`Checkbox.Group`	只展示角色配置	设置后回读	失败不回滚此前成功的内容更新。

5.3.4 正向与异常路径

路径	用户动作	系统行为	结果
正向	编辑地址并保存	校验、更新、回读	仅地址内容刷新。
正向	设置地址角色并确认	设置、回读	仅角色 Tag 刷新。
异常	平台写入成功但回读失败	保留旧有效展示	Notification：待确认。

5.3.5 逆向流程

逆向场景	触发条件	数据影响	修正规则	限制	审计
地址内容修正	需再次修正	平台地址再次更新	以最新成功回读为准	不支持 ERP 撤销或新增	记录更新摘要。
角色调整	需改变角色	平台角色再次更新	不影响地址内容	以平台规则为准	记录角色摘要。

5.3.6 权限

角色	页面	按钮	字段	数据范围	二次确认 / 无权反馈
查看者	可见	查看	只读	授权店铺	编辑/角色入口隐藏。
Shopee 普通店操作人	可见	编辑、设置角色	仅接口允许字段可编辑	授权店铺	角色设置确认；3PF/能力缺失隐藏。

5.3.7 历史数据

数据对象	来源	是否迁移	初始化	历史状态	回滚	验证
地址角色	Shopee 首次同步	否	平台回读值	不从旧 ERP 推断	重新回读恢复	与接口返回一致。

5.4 物流渠道与 COD 配置

5.4.1 功能定义

优先级	角色	功能点	前置条件	业务结果
P0	查看者/操作人	查看渠道	渠道读取能力	展示平台返回渠道和当前配置。
P0	操作人	更新 Shopee 渠道/COD	普通店、写权限、`update_channel` 能力	平台配置更新并回读。

5.4.1.1 渠道功能的 API 对接与字段映射

业务功能	API 名称	官方文档 URL	已核验生产地址 / 方法	平台入参（类型 / 来源）	返参记录与回读	业务规则
读取渠道和 COD	`get_channel_list`	https://open.shopee.com/documents/v2/v2.logistics.get_channel_list?module=95&type=1	`GET https://partner.shopeemobile.com/api/v2/logistics/get_channel_list`	无业务 Body；服务端注入 Shopee V2 公共参数。	记录 `error,message,response.logistics_channel_list[]`，写入渠道快照。	读取成功才允许展示渠道/COD 当前值。
保存渠道启用 / COD	`update_channel`	https://open.shopee.com/documents/v2/v2.logistics.update_channel?module=95&type=1	`POST https://partner.shopeemobile.com/api/v2/logistics/update_channel`，JSON	必传 `logistics_channel_id:int64`，来自渠道快照；可选 `enabled:boolean`、`cod_enabled:boolean` 或 `auto_call_driver_setting`。	记录 `request_id,error,message,response`；`response` 保存 `shop_id,enabled,cod_enabled,logistics_channel_id,updated_channels[],is_multi_warehouse,auto_call_driver_setting`；成功后回读渠道列表。	一次仅变更一个渠道的一个配置项；禁传已废弃 `preferred`。`enabled=true` 且平台要求时，`preparation_time` 必须在读取返回的 min/max 内。

UI 展示字段	Shopee 返回 JSON Key	数据类型	落库 / 业务口径
渠道 ID / 名称	`logistics_channel_id` / `logistics_channel_name`	int64 / string	渠道唯一标识与列表展示。
启用 / COD	`enabled` / `cod_enabled`	boolean	只展示平台回读值；不乐观更新。
强制与依赖约束	`force_enable,compulsory_channel,channel_relation_rules,mask_channel_id`	boolean / object / int64	控制是否可关闭及关联渠道提示。
自动叫车约束	`auto_call_driver_setting`	object	保存资格、启用状态、准备时间与区间；仅平台支持时显示。

5.4.2 字段取值逻辑

字段名称	类型	必填	默认值	取值逻辑	枚举值	校验规则	空值/异常显示
平台渠道 ID	string	是	—	平台返回	—	平台+店铺+ID 唯一	缺失不可更新。
渠道名称	string	是	—	平台返回	—	只读	`—`。
启用状态	boolean	否	回读值	平台明确返回才展示	`true`/`false`	写入后回读	不支持显示 `—`。
COD 状态	boolean	否	回读值	平台明确支持才展示	`true`/`false`	写入后回读	不支持显示 `—`。

5.4.3 交互说明

场景	组件	前端交互	后端逻辑	错误处理
渠道列表	`ProTable`、`Switch`、`Tag`	无写能力时只读	查询渠道快照	无渠道与同步失败分别提示。
更新渠道/COD	`Modal`、`Switch`、`Notification`	不乐观切换，确认中禁用	写入后回读实际配置	失败保持旧值并可重试。

5.4.4 正向与异常路径

路径	用户动作	系统行为	结果
正向	点击开关	展示当前值、目标值与影响	未确认不写入。
正向	确认变更	写入并回读	开关按平台回读刷新。
异常	平台拒绝或回读失败	不改有效展示	错误提示或待确认通知。

5.4.5 逆向流程

逆向场景	触发条件	数据影响	修正规则	限制	审计
反向调整渠道/COD	业务需恢复原状态	平台再次更新	仅以最新回读为准	一次只改一个渠道的一个配置项	记录变更摘要。

5.4.6 权限

角色	页面	按钮	字段	数据范围	二次确认 / 无权反馈
查看者	可见	查看、同步	开关只读	授权店铺	不展示确认入口。
具备 Shopee 渠道能力的操作人	可见	更新渠道/COD	仅支持字段可操作	授权店铺	每次变更确认；无能力隐藏。

5.4.7 历史数据

数据对象	来源	是否迁移	初始化	历史状态	回滚	验证
渠道快照	平台首次同步	否	平台回读值	不从旧 ERP 推断	重新同步恢复	与平台回读逐条比对。

6. 数据与口径（Phase 3）

数据项	定义	数据来源	刷新规则	权限影响	缺失/异常处理
地址/仓库快照	一次成功完整同步后保存的平台对象	平台读取接口	手动同步、写操作后强制回读	按店铺权限可见	失败保留上次成功快照。
平台已移除	旧快照在后续完整成功同步中不再返回	快照对账	仅完整成功同步后计算	只读	分页/超时/错误不触发。
地址角色	默认、揽收/发货、退件属性	Shopee 回读	角色设置后回读	按地址角色权限	不支持显示 `—`。
渠道/COD	平台渠道启用和 COD 配置	平台回读	手动同步、配置后回读	按渠道权限	不支持字段显示 `—`。
操作记录	关键动作审计摘要	ERP 操作日志	成功、失败、发现移除时记录	按日志权限	不写完整地址/电话原值。

7. 权限、状态与异常（Phase 3）

stateDiagram-v2
  [*] --> ACTIVE: 首次完整成功同步返回对象
  ACTIVE --> ACTIVE: 后续完整成功同步仍返回
  ACTIVE --> PLATFORM_REMOVED: 完整成功同步未返回旧对象
  PLATFORM_REMOVED --> ACTIVE: 后续完整成功同步再次返回

状态/异常	触发条件	用户文案	可执行操作	数据影响	恢复方式
缺少店铺上下文	未从平台后台管理进入档案	未找到店铺上下文	返回平台后台管理	不加载数据	重新从店铺行进入。
当前设置无已接入操作	当前店铺没有已完成字段级契约且授权的读取/写入动作	当前店铺暂无已接入的平台后台设置操作	查看其他页签或返回列表	不创建对象	接口契约和权限核验后另行开放。
同步失败	超时、限流、分页失败	同步失败，请重试；当前展示为最近成功数据	重试	保留旧快照	成功同步。
平台已移除	完整成功同步未返回旧对象	已从平台移除	查看历史	标记历史，不删除	对象再次返回。
写入待确认	写成功但回读失败	平台已接收请求，暂未确认最终结果	重新同步	不更新有效展示	成功回读。

8. 前端功能限制

限制 ID	限制内容	前端处理	后端兜底
FL-001	单店后台档案只能从平台后台管理行进入	以当前店铺 ID 维护路由上下文；不展示店铺选择器	拒绝缺失或跨店的档案/写入请求。
FL-002	不新增、不删除平台地址/仓库	不展示按钮	拒绝相关请求。
FL-003	3PF 仓库只读	隐藏编辑和角色入口	按现有 3PF 标识拒绝写入。
FL-004	未核验能力不展示	隐藏页签、按钮、表单	不暴露未注册路由。
FL-005	渠道不乐观更新	保持回读值、提交中禁用	仅回读成功后更新快照。

8.1 前端页面与交互（Phase 4）

页面/弹窗/抽屉	场景目标	信息层级与布局	组件	状态与反馈	风险控制
平台后台管理	按平台查阅店铺并进入后台档案	平台页签 → 店铺搜索 → 店铺、类型、经营表现、查看	`PageContainer`、`Tabs`、`ProTable`	无指标中性空态	不展示能力集合、配置完成度或后台档案以外的设置操作。
单店后台档案	单店查看和维护平台配置	店铺身份 → 经营表现 / 平台后台设置 / 操作记录 → 当前设置同步或维护	`PageContainer`、`ProDescriptions`、`Tabs`、`ProTable`	首屏 `Skeleton`；同步 `Spin`；空态、失败 `Alert`	不展示店铺选择器；服务端门控决定对象和动作。
地址/仓库详情	查看完整信息和操作记录	基本信息 → 操作记录	`Drawer`、`ProDescriptions`、`Tabs`	历史移除对象只读	不提供删除或恢复。
地址编辑	更新 Shopee 地址内容	按已核验 Schema 分组表单	`DrawerForm`、`Form`	字段级校验；成功 `Message`；回读失败 `Notification`	仅普通店、写权限和能力都具备时显示。
地址角色设置	独立设置角色	当前角色 → 目标角色 → 确认	`Modal`、`Checkbox.Group`	提交禁用；回读刷新	不与地址内容编辑合并。
渠道配置确认	更新渠道/COD	当前值 → 目标值 → 影响 → 确认	`Modal`、`Switch`	不乐观更新；失败保持旧值	每次仅变更一个渠道的一个配置项。

页面状态	表现
默认	地址与仓库、物流渠道为平级页签；无读取能力的页签不出现。
空	未选店铺、未同步、平台返回空、筛选无结果分别提供对应文案和下一步。
异常	显示失败原因、最近成功同步时间和“重试同步”。
无权限	不需要感知的能力隐藏；可见但条件不足时禁用并说明原因。
操作记录	仅使用操作人、操作类型、操作对象、操作详情、操作时间；不记录完整地址/电话。

9. 业务验收标准

Scenario	Given 前置条件	When 触发动作	Then 预期结果	And 附加预期
AC-001	已授权 Shopee 普通店且读取成功	同步地址/仓库	显示平台地址和同步时间	无新增、删除按钮。
AC-002	已授权 Shopee 3PF 店	查看地址/仓库	可查看平台仓库	前后端均拒绝编辑。
AC-003	Shopee 普通店具备地址写能力	保存地址内容	回读成功后刷新内容	角色不改变。
AC-004	Shopee 普通店具备角色能力	设置角色	回读成功后刷新角色 Tag	内容不改变。
AC-005	Shopee 普通店具备渠道写能力	确认渠道或 COD 变更	回读值刷新	失败保持旧值。
AC-006	平台超时、限流、分页失败	同步	展示失败与重试	原有效记录不标记移除。
AC-007	历史对象本次完整同步未返回	包含已移除记录	显示灰色历史记录	无写操作。
AC-008	无已接入读取能力	选择对应店铺	显示空态	不展示伪操作。

10. 权限、历史与原型冻结（Phase 5）

10.1 权限与数据范围

权限能力	复用现有角色	数据范围	前端表现	服务端约束
查看	店铺物流配置查看者、操作人	授权店铺	可见已接入能力、详情和日志	店铺范围外不返回数据。
同步	店铺物流配置查看者、操作人	授权店铺	显示当前页签同步入口	对应读取能力和店铺范围均校验。
地址内容更新	店铺物流配置操作人	Shopee 普通店	仅在 `update_address` 能力存在时显示	3PF、无能力或无权一律拒绝。
地址角色设置	店铺物流配置操作人	Shopee 普通店	仅在 `set_address_config` 能力存在时显示	独立校验后写入并回读。
渠道 / COD 配置	店铺物流配置操作人	Shopee 普通店	仅在 `update_channel` 能力存在时显示	一次只允许一个渠道的一个配置变更。
操作记录查看	复用现有日志查看权限	授权店铺	Drawer 内只读显示	不返回完整地址、电话原值。

不新增角色、权限码或店铺识别规则；现有店铺范围、3PF 标识与日志权限是唯一权威来源。

10.2 历史数据与快照初始化

项目	已确认规则
历史迁移	不迁移旧 ERP 地址、仓库或渠道数据。
首次同步	一次完整成功同步建立初始快照；首次同步不推断任何对象为平台已移除。
后续同步	仅在后续完整成功同步中，未返回的旧有效对象标记为 `PLATFORM_REMOVED`。
失败同步	超时、限流、字段错误或分页不完整时，保留最近一次成功快照，且不得改变生命周期。
对象回归	后续完整成功同步再次返回时恢复为 `ACTIVE`，保留历史审计记录。

10.3 原型的三平台展示规则

平台	原型可见内容	可操作内容	不展示内容
Shopee	地址/仓库、地址角色、渠道/COD 与同步状态	在普通店与能力允许时编辑地址、设置角色、配置渠道/COD	新增、删除、3PF 编辑。
Lazada	平台状态、仓库接入状态和最后同步状态	无	编辑按钮、未核验字段或本地替代保存。
TikTok Shop	平台状态、普通/跨境仓库与渠道接入状态、最后同步状态	无	编辑按钮、未核验字段或本地替代保存。

10.4 页面画像冻结

项目	已确认决策
产品范式	ERP 规则配置。
页面母版	`ManagementPage` + `DetailPage`，用 `ProLayout`、`PageContainer`、`ProTable`、`ProDescriptions`、Tabs、Drawer/Modal 组合实现。
密度策略	`standard`。
视觉强调	`data-first`；总览强调后台表现摘要和归属治理提示，档案强调当前店铺身份与当前页签。
动效策略	`minimal`；仅使用组件默认的抽屉、Modal、反馈动效。

11. 风险与未决问题（已冻结接入前置项）

类型	问题/风险	影响	策略
已确认	现有角色、店铺范围和日志查看权限映射	权限	复用现有权限，不新建角色。
接入前置项	Lazada 仓库读取/编辑字段、权限、错误码、适用范围	平台接入	未完成核验前，只有能力状态，无读写业务表面。
接入前置项	TikTok 普通店/跨境店仓库和渠道的路由、字段、权限	平台接入	未完成核验前，只有能力状态，无读写业务表面。
已核验待联调	Shopee 写接口字段契约已登记，但地址角色有 `PICKUP_ADDRESS` / `PICK_UP_ADDRESS` 文档拼写差异。	角色保存与回读映射	适配器显式保留映射待联调项，不可自行归一；联调成功后才解除写入门禁。

12. 全局一致性锚点（Phase 5）

类别	内容	来源	状态
统一术语	店铺物流配置、平台地址、平台仓库、地址角色、平台已移除、物流渠道、COD	PRD §1–§7	已确认。
范围边界	单店、店铺后台、能力门控；不新增、不删除、不进订单	PRD §3–§4	已确认。
平台差异	Shopee 已确认动作；Lazada/TikTok 条件接入；3PF 只读	PRD §1.2/§3.3	已确认。
页面表面	运营归属管理原列表、平台后台管理、单店后台档案；地址等轻量维护使用 Drawer/Modal	PRD §0.4–§0.5、§8	已确认。
设计画像	`ManagementPage + DetailPage` / `standard` / `data-first` / `minimal`	PRD §0.4–§0.5、§10.4、`frontend-contract.md` §4	已确认。
Decision Log	Phase 1–5 于 2026-08-05 确认并立即写入	CR-20260805-002	已确认。

店铺物流配置 产品 PRD