国际地图统一钱包计费需求文档 v1.0

版本：v1.0 | 创建日期：2026-08-10

最近修订：2026-08-16

需求来源：混合来源（用户沟通、研发确认、历史 Wiki、GCP 账单、本地代码、Google 官方文档）

优先级：待确认

文档状态：待确认

需求变更记录

依赖需求 Story 列表

当前无已确认的依赖 Story，评审拆分后补充。

一、需求概述

1.1 客户反馈

客户反馈结论： 无关联客户反馈。本需求来源于国际地图产品整合、供应商成本治理及产品与研发内部对齐，不虚构客户反馈。

1.2 系统现状

当前 Google 国际地图能力被拆分为一个开通产品及 PaaS 对象、外勤、服务通三个场景资源包。各场景分别维护余额和扣减规则，客户购买次数与 Google 实际计费 SKU 之间不是一一对应关系，无法直接比较销售收入、租户消费和供应商成本。

用户提供的线上产品截图显示，当前产品列表至少包含国际地图-服务通（1,200 元/财务成本 1,000 元）、国际地图应用（1,200 元/财务成本 1,000 元）、国际地图-外勤（1,800 元/财务成本 1,500 元）和国际地图-PaaS 对象（1,000 元/财务成本 550 元）。这里的“财务成本”是产品列表中的内部成本字段，不等同于本需求测算的 Google GCP 供应商成本，不能单独用来判断地图接口是否盈利。

研发已确认典型业务动作与 Google 接口的关系如下。Atmosphere Data、Contact Data 会随每次 Nearby Search、Text Search 固定产生，当前链路无法去除，必须计入 Places 综合成本。

Google 接口与业务操作场景对照

以下是按当前产品链路对 Google SKU 的业务化解释，用于帮助产品、研发和财务理解“一个接口调用大概对应什么操作”。它是场景映射，不等同于 Google 账单中的一次业务动作；正式扣费仍以实际成功计费事件和费率版本为准。

2026 年 1—7 月 fxiaoke-i18n 项目核心地图账单共 9,294.20 美元，月均 1,327.74 美元；按固定汇率 6.7936、税率 6% 折算含税人民币成本 66,929.54 元。其中 Atmosphere、Contact 成本合计约 1,706.09 美元，占核心地图成本约 18.4%。原始账单可以证明供应商 SKU 的调用量和金额，但不包含租户、License、业务对象和业务动作，因此只能用于成本与总量对账，不能直接作为租户实时扣费流水。

Data SKU 的口径： Atmosphere Data、Contact Data 已计入本方案的 Nearby Places、Text Places 综合成本，但此前只在组合字段中表达，未在成本结构表中单独展开。本版补充底层 SKU 明细，避免把它们误读为“未计入”。它们不是额外业务动作，却是每次 Nearby/Text 搜索必须承担的供应商成本。

1.3 竞品现状

本需求不涉及 CRM 竞品能力比较。外部规则仅用于确认供应商计费事件及账单结构：Google 官方说明，一个服务请求可能触发一个或多个 SKU，并作为独立账单行出现；Dynamic Maps 的计费事件为成功地图加载。由此可知，纷享内部的“一次业务动作”不能直接等同于 Google 的“一次调用”或“一条账单”。

1.4 产品价值

采用统一钱包不是单纯为了合并产品名称，而是由当前计费结构的四个问题共同决定：

1. 资源权益与供应商成本不一致。 一个 PaaS 计次会触发 Nearby、Text 以及两类 Data SKU，外勤还增加 Details；原来的“1 次”不是统一成本单位，按场景固定次数售卖容易出现高成本场景被低价覆盖。
2. 客户使用场景会交叉。 同一企业可能同时在 PaaS、外勤和服务通使用国际地图，分开购买会造成一边余额不足、另一边余额闲置，客户无法按真实使用情况调配已购买资源。
3. 供应商价格和接口组合会变化。 Google 账单按 SKU 和成功计费事件变化，统一钱包可以只调整版本化费率，不必频繁重做三套资源包和 License 参数。
4. 财务和客户都需要可对账。 一个钱包把业务动作、底层 SKU、客户扣减和 GCP 月账单串成一条流水，既能实时展示消费，也能在月底做差异对账。

上述统一方向是用户在多轮沟通中已确认的产品目标：首次开通产品后，后续购买统一资源包，钱包不区分业务场景，按实际 Google 接口费用扣减。对客户，统一钱包提供跨 PaaS、外勤、服务通使用的余额和消费明细；对公司，建立“业务动作—Google 计费事件—钱包扣减—GCP 月账单”的可追溯链路，使产品售价能够覆盖真实供应商成本并保留明确毛利，同时降低多套 License 的销售和维护成本。

三赢的局面：

对产品：产品线更清晰，盈利模式更清晰，同时减少国际地图产品的咨询

对实施/客成：减少咨询和沟通成本

对客户：不需要区分产品购买，避免部分场景冗余+部分场景闲置的问题

1.5 需求目标

1. 新购企业通过一次国际地图开通产品启用能力并获得初始额度，后续只购买统一额度包，不再区分 PaaS、外勤、服务通资源包。
2. PaaS、外勤、服务通发生 Google 可计费事件时，系统按当时生效的人民币费率实时扣减同一钱包，并生成可追溯消费流水。
3. 存量企业的旧场景剩余次数按原权益对应的接口组合换算为钱包额度，保证迁移前已购买权益的可用能力不因计费模型切换而被压缩。

二、产品方案

2.1 整体产品方案

2.2 具体方案说明

2.2.1 产品与钱包结构

钱包额度是国际地图资源权益。建议资源包订单金额与到账额度按 1:1 记账，例如购买 1,000 元额度包到账 1,000.000 地图额度；计费精度和取整规则见 2.2.3。

方案 2： 只保留一个产品，这个产品即是首次开通产品，也是后续的额度包，相当于开通产品不收费，按额度用量收费。

2.2.2 业务动作与计费项映射

客户不再购买“PaaS 次数”“外勤次数”或“服务通次数”。系统应在业务动作发生时识别实际产生的计费项并累加扣减：

典型 PaaS 动作可理解为 Nearby Places + Text Places + Dynamic Maps，典型外勤动作在此基础上增加 Places Details，服务通为 Geocoding。该组合只用于成本解释和测试用例，正式扣费不得直接写死为一个场景固定金额，而应按该次业务动作实际触发的计费项累加。

Dynamic Maps 与 Atmosphere、Contact 的定位不同。Atmosphere、Contact 是 Places 搜索请求固定带出的 Data SKU，已经合并在 Nearby Places、Text Places 的综合计费项中；Dynamic Maps 属于独立的 Maps API SKU，计费事件是一次成功的地图加载。它只有在业务动作实际渲染地图时才产生，不是每次 Nearby/Text 搜索必然一比一产生的附加项。

从 2026 年 1—7 月账单看，Nearby + Text 共 220,252 次，而 Dynamic Maps 为 171,945 次，约为搜索次数的 78.1%，也不等于 PaaS 或外勤动作数。因此底层计量和对账必须保留 Dynamic Maps 独立 SKU；客户侧可以在确认真实日志中的典型动作组合后，将它作为 PaaS/外勤综合动作的一部分展示或定价，但不得直接并入 Nearby Places、Text Places 的基础单项费率。这样既能表达业务动作的完整成本，也不会掩盖独立地图加载或平台重试带来的成本差异。

2.2.3 费率发布与实时扣减

客户 SKU 费率的首版测算公式为：

客户 SKU 费率 = 供应商有效单位成本 ÷（1 - 目标供应商成本毛利率）

• 供应商有效单位成本：按最近 3—7 个完整自然月 GCP 实际账单计算，并纳入汇率和税费。
• 首版目标供应商成本毛利率：暂按 35%，待财务确认。
• 费率版本：每个计费项保存版本号、生效时间、失效时间、客户费率、成本观察口径和发布人。
• 扣减精度：钱包保留 3 位小数，单次业务动作汇总金额按 0.001 额度向上取整。
• 生效规则：新费率只用于生效时间之后产生的计费事件，历史消费不追溯重算。
• 调价触发：建议按季度评估；连续两个月实际成本偏差超过 15% 时可提前发起调价评审。
• 月末对账：GCP 账单仅用于核对总调用量、总成本和各 SKU 偏差，不更改已经向客户展示的历史消费金额。

2.2.4 首版成本与费率草案

以下草案基于 2026 年 1—7 月 fxiaoke-i18n 实际账单、汇率 6.7936、税率 6% 和 35% 目标毛利。该表是评审输入，不是已发布价格。

底层 Google SKU 的 1—7 月供应商含税单位成本如下。Atmosphere、Contact 两行必须参与 Places 综合费率，不能从成本模型中删除：

由底层 SKU 加总得到客户计费项：

加入 7 月账单后，各核心 SKU 的加权单位成本相对上半年仅变化约 +0.1%—+1.5%，未出现改变钱包计费方向的结构性偏差。

2.2.5 现行资源包的盈亏分析

本项用于回答“现行按几个资源包分别计价，结合当前 Google 成本是否亏损”。由于 Google 账单没有租户和 License 流水，以下分两层看：

第一层：产品列表价格与内部财务成本。 线上截图显示的单品价格减财务成本均为正：服务通、国际地图应用各约 16.7% 的列表毛利，外勤约 16.7%，PaaS 对象约 45.0%。但这只能说明产品列表的内部成本字段没有倒挂，不能证明 Google 接口成本已经被覆盖。

第二层：按 Google 实际成本和旧资源包权益估算。 以历史测算采用的 10,000 次资源包为口径，按当前确认的接口组合计算如下。这里不把“理论消费值”当作实际销售收入；它是用账单代理事件量乘旧单次售价得到的可比指标。

上表是“单个旧资源包完全消费”的权益压力测试；为了把账单代理量、成本和差额直接对上，再按历史测算沿用的分摊规则复算 2026 年 1—7 月。PaaS 代理量为 Nearby + Text - Details，外勤代理量为 Details，服务通代理量为 Geocoding；Nearby、Text、Atmosphere、Contact、Dynamic Maps 的共享成本按 PaaS/外勤代理量比例分摊，Details 全部归入外勤，Geocoding 全部归入服务通。

该表的“分摊成本/次”是为复核账单总额而采用的历史代理分摊口径，不代表 Google 已经按租户或 License 直接归因；三类分摊总成本之和与 1—7 月国际地图核心 GCP 含税成本 66,929.54 元一致。正式财务损益仍需补齐同月订单收入、赠送额度、未消费余额、折扣和 License 消费流水。

理论毛利率的口径是“理论消费值”作为分母，而不是供应商成本作为分母：

理论消费值 = 账单代理调用次数 × 旧单价/次
分摊总成本 = 账单代理调用次数 × 分摊成本/次（含税）
理论差额 = 理论消费值 - 分摊总成本
理论毛利率 = 理论差额 ÷ 理论消费值

以 PaaS 为例：理论消费值为 133,987 × 0.10 = 13,398.70 元，分摊总成本为 133,987 × 0.2364 ≈ 31,676.47 元，理论差额为 13,398.70 - 31,676.47 = -18,277.77 元，所以理论毛利率为 -18,277.77 ÷ 13,398.70 ≈ -136.4%。它表示成本约为理论消费值的 2.36 倍；这里的“理论”是因为账单代理量尚未和实际 License 订单收入、赠送额度、折扣及租户流水逐笔关联。

按账单代理事件量对 2026 年 1—7 月做总体复算：PaaS 代理量为 Nearby + Text - Details = 133,987，外勤代理量为 Details = 86,265，服务通代理量为 Geocoding = 284,568。按旧单价得到理论消费值 63,074.56 元，同期国际地图核心成本 66,929.54 元，差额约 -3,854.98 元，理论毛利率约 -6.1%。上半年单独测算为理论消费 52,370.10 元、含税成本 55,294.27 元、理论毛利率 -5.6%。测算依据为[历史成本与定价模型](/Users/soren/Desktop/work/00-Output/国际地图统一License计费方案/国际地图统一License成本与定价模型_v0.1_20260803.xlsx)及 2026 年 1—7 月 GCP 账单。

因此，当前证据支持的结论是：现行模式整体存在成本倒挂风险，主要由 PaaS 和外勤资源包造成；服务通可以覆盖 Google 成本，但无法抵消前两类高成本场景的亏损。 这不是实际财务收入损益表，因为缺少企业实际购买金额、赠送额度、未消费余额、折扣、续购和 License 消费流水；正式结论必须在同月 License 流水补齐后复核。

统一钱包的直接价值之一，就是将这些场景的真实接口成本统一计入钱包费率，不再用一个低价场景的次数余额隐性补贴另一个高成本场景。

2.2.6 扣费责任与幂等规则

每次地图业务动作必须生成唯一 bizActionId，每次供应商请求必须生成唯一 requestId，并记录租户、业务场景、业务记录、计费项、调用结果、费率版本、扣减金额和扣后余额。同一 requestId 只能入账一次；无法完成租户和业务动作归因的调用不得直接进入正式客户扣费，应进入异常池人工核对。

2.2.7 余额与消费管理

企业管理后台新增“国际地图额度”入口：

首版页面位置建议：将“国际地图额度”先放入企业管理后台的“许可信息”页面，在现有“资源池”区域占位，后续再补充余额、累计消费、费率版本和消费明细等字段。以下截图仅作为位置示意，不代表最终交互和字段定稿。

消费明细默认按业务动作汇总为一条，展开后查看 Nearby Places、Text Places、Details、Dynamic Maps、Geocoding 等计费项。客户侧不展示 Google 采购成本、汇率、内部毛利，也不把 Atmosphere、Contact 解释为额外业务动作。

余额不足时，首版建议禁止发起新的 Google 可计费调用，并提示企业管理员购买额度。是否允许签约客户透支属于商务政策，未确认前不提供默认透支。

2.2.8 历史资源包迁移

历史余额按旧次数实际代表的接口权益迁移：

迁移钱包额度 = 旧场景剩余次数 × 切换日冻结的该旧场景接口组合客户费率

例如某企业剩余 5,000 次 PaaS，按当前草案迁入 5,000 × 0.606 = 3,030 额度。0.606 已包含两类搜索固定产生的 Atmosphere、Contact，不包含过去未纳入 PaaS 次数权益的 Dynamic Maps。

需要特别区分“旧单价”和“迁入额度/次”：旧 PaaS 单价 0.10 元/次 是历史资源包的销售计量；迁移值 0.606 是把旧 1 次所代表的两类接口权益，按切换日客户费率换算成新钱包额度，计算为 Nearby Places 0.362 + Text Places 0.244 = 0.606。同理，外勤为 0.606 + Places Details 0.112 = 0.718，服务通为 Geocoding 0.047。因此 0.606 不是新的 PaaS 售价，也不是供应商成本；它是旧权益向统一钱包的价值换算系数。Dynamic Maps 当前不计入迁移系数，是因为历史 PaaS 次数权益被确认只代表 Nearby + Text；若研发日志或历史规则证明旧权益实际还承诺了地图加载，则必须在切换日前重新评估迁移系数。

Dynamic Maps 暂不纳入迁移的原因不是它没有成本，而是迁移首先要还原“历史已购买的客户权益”，不能把历史未单独售卖、未在旧次数定义中明确承诺的技术调用，直接追溯为存量客户权益。当前已确认的历史口径是：PaaS 1 次代表 Nearby Search 1 次 + Text Search 1 次，外勤在此基础上增加 Places Details 1 次；Dynamic Maps 是这些业务页面可能同时产生的独立加载事件，不能仅凭账单中存在调用就证明它属于旧资源包的 1 次权益。Atmosphere、Contact 则不同，它们已确认是每次 Nearby/Text 固定产生，因此必须随搜索权益一起迁移。

因此迁移有两个口径，需在切换前根据历史商品说明和调用日志定案：

当前推荐先采用“历史权益保全”，原因是证据链更完整、不会无依据扩大存量赠予；若产品、销售和研发确认旧客户购买的是完整地图动作而不是搜索接口权益，则应切换为“功能完整等价”，并重新生成企业级迁移清单。无论采用哪一种，Dynamic Maps 上线后的新调用都必须继续按独立 SKU 计量，不能因为迁移时是否赠送而改变后续实际扣费规则。

迁移必须使用“客户费率”而不是供应商成本。这里“保证迁移前已购买权益的可用能力不减少”是指：按冻结费率测算，迁入余额至少能继续完成与旧剩余次数等量的旧接口组合；并不保证未来调价后永久拥有相同业务次数。

迁移上线前应输出企业级清单，包含旧产品、原购买次数、剩余次数、冻结费率、迁入额度、有效期和处理状态，由销售与客户成功复核。迁移额度独立标记，不可退款、提现或转让；有效期、扣减顺序和企业汇总取整方式待评审确认。

2.2.9 异常与影响范围

• 计费服务不可用：地图业务是否降级放行待技术方案确认；放行产生的供应商成本不得在恢复后无依据补扣客户。
• 余额并发：钱包扣减必须保证原子性，避免并发请求造成负余额或重复入账。
• 费率版本缺失：停止正式扣费并报警，不得使用未发布的临时价格。
• 人工调账：仅限授权运营人员，必须填写原因并生成前后值审计日志。
• 影响端：PaaS Web/移动端、外勤移动端、服务通、License/订单、计量与钱包服务、客户管理后台、运营后台、财务对账。
• 开放能力：首版不向客户开放钱包扣减接口；是否提供余额和明细查询 OpenAPI 后续评估。

2.3 待确认事项

三、规范检查项

3.1 业务文案多语言 Key

以下为首版页面核心词条，正式 Key 由研发按现有命名规范确认。

3.2 需求埋点

本需求的计费事件、钱包流水和对账记录属于核心业务账务数据，不使用普通前端埋点代替。页面使用分析是否另加产品埋点待交互方案确定后补充。

3.3 沙盒/更改集能力

3.4 PaaS 国际化兼容检查

3.5 新对象/新字段 BI 分析申请

3.6 操作日志说明

以下操作必须记录操作人/系统、操作时间、租户、业务单据、原因、变更前值、变更后值和关联流水号：费率创建与发布、人工调账、历史迁移入账、订单充值入账、赠送额度、额度作废、异常冲正。客户业务消费还必须记录 bizActionId、requestId、业务场景、计费项、费率版本、调用结果、扣减金额和扣后余额。日志保存期限及脱敏规则由技术与合规评审确定。

3.7 需求风险点检测

3.8 上线策略

3.8.1 收费标准

• [ ] 不收费
• [X] 收费

收费方式：购买首次开通产品和统一国际地图额度包；使用时按生效人民币费率实时扣减钱包额度。正式价格和赠送额度须在上线前完成财务审批。

3.8.2 上线节奏

• [ ] 全网
• [X] 灰度

3.8.3 适用版本