产品需求，
可以逐条查阅。

文档版本：1.6｜日期：2026-10-31｜产品负责人：杨天文

版本范围：MVP 核心采集闭环。交付形态：macOS 本地应用与浏览器操作界面。

一、背景与目标

1.1 阶段与版本范围

Roadmap 阶段：需求与方案确定 → MVP 开发 → 测试与试采 → 用户试用 → 发布。

本版本交付起点导入、目标管理、单批次即时/定时采集、执行监控、异常处理和 Excel 明细导出，打通从任务配置到结果核查的完整流程。

个人研究中需要跨起终点、方向和时段重复获取驾驶距离与时间。逐条查询和手工记录会割裂输入、采集时间与结果，难以识别漏采和重复。产品将这些操作组织为可追踪的本地任务。

1.2 本版本成功判据

首次成功率 = 首次真实请求即取得有效结果的观测数 / 已发起首次真实请求的观测数。模拟、未发起和重复尝试不计入分母；统计时记录时间范围及过滤规则。

二、交付计划与里程碑

2.1 周期与责任

MVP 计划周期为 10 个工作日，T0 为需求范围、投入时间、测试设备和服务账号确认日。需求冻结时完成工作量评估并确定日历日期；范围或资源变化时同步调整里程碑。

杨天文负责需求分析、功能规划、组织 AI Agent 开发、结果核查和发布确认。试用参与者完成指定任务并反馈操作问题。

2.2 不可发布与回退条件

以下任一情况未关闭，延期发布：输入映射错误、方向错置、超窗请求误标为窗口内、成功记录丢失或重复计数、模拟来源混淆、Key 泄露、导出与记录不一致、阻断规则仍未确定。

发布后出现同类问题，立即暂停新任务，保留数据库副本和日志，核定受影响范围。旧版本仅在数据格式兼容时回退；不覆盖唯一数据副本。错过的采集时段保留缺测，不补写历史时间。

三、产品概述

3.1 一句话说明

将经确认的起终点和采集计划转成批量驾驶路线查询任务，交付包含时间、方向、状态与来源的 Excel 明细。

3.2 功能模块与优先级

四、目标用户与核心使用场景

4.1 用户与角色

核心用户为需要批量驾驶路线数据的研究人员。当前为单机单用户，由本地所有者配置账号、准备数据、创建任务并确认结果用途。

本版本独立试用用于验证他人能否理解流程，不引入团队账户、管理员或审批角色。

4.2 核心任务与主路径

具体场景：用户已经整理好一组起点和目标，需要在指定窗口采集两者之间的驾驶路线数据，随后进入表格分析。

主路径：启动应用 → 配置地图服务 → 导入起点 → 检查字段和坐标 → 选择目标 → 设置即时/定时与方向 → 确认规模 → 执行 → 查看异常及结果 → 导出 Excel。

失败分支：查看失败原因 → 修正凭据、输入或预算 → 继续未完成任务或重试失败项 → 重新核查。窗口已过的观测保留缺测；再次采集使用新任务。

五、需求范围说明

图 1 · 业务责任泳道。按用户、本地程序和数据产物划分责任与交接。

5.1 MVP 范围

最小闭环为单机、单批次、完整比较模式。导入 CSV 起点，选择已有或新建目标，选择模拟/高德服务、即时/定时、去程/返程，执行后查看记录并导出 Excel 明细。

必需能力：输入校验、模式标识、计划观测展开、实际请求时间、有限重试、暂停恢复、本地保存和结构化导出。没有 Excel 明细或异常处理，不算闭环完成。

5.2 延后与不做

5.3 系统边界与分工

用户提供坐标、计划和高德 Web 服务 Key，并核查账号权限、配额与费用。程序执行校验、调度、限流、存储和导出。高德返回路线估算；本地程序不生成或补造路线数值。

AI Agent 承担程序实现和问题定位，产品负责人确认需求、测试结果和发布。外部地图服务的权限与计费以用户账号为准，本机预算只约束本软件。

六、详细需求说明

6.0 全局规则与数据口径

• 用户可见采集时间采用北京时间 UTC+08:00；计划时间、实际请求时间及响应时间分别保存与展示。
• 观测由任务、起点、目标、批次和方向确定；重试增加尝试记录，不增加计划观测数。
• 完整比较模式计划数 = 有效起点数 × 所选目标数 × 各批次方向数之和。3 起点 × 2 目标 × 单方向 = 6，双向 = 12。
• 去程为起点至目标，返程为目标至起点，分别请求。
• 模拟数据标识为模拟测试，不能标为真实试采或正式采集。失败或未采的距离和耗时留空，不以 0 代表。
• 任务使用创建时的输入快照；后续编辑地点不改写历史观测。
• 提交中的操作按钮禁用，失败显示原因并保留可继续编辑的输入；保存成功不代表外部服务权限已验证。
• 验收记录采用“输入与前置 → 操作 → 实际结果 → 通过/失败 → 证据文件”，不以页面可打开代替功能验收。

图 2 · 关键页面交互线框。表单与任务摘要对应 FR-02—04，结果筛选和导出对应 FR-07—08。

FR-01 地图服务与凭据配置

用户任务：保存真实查询所需配置，确认模拟与真实模式。

交互：从首页“前往系统设置”或侧栏“系统设置”进入；选择默认地图服务，输入 Web 服务 Key，调整频率与预算，点击“保存设置”。保存中禁用按钮，成功反馈已保存，失败在当前页显示原因。Key 输入框留空表示不修改已有 Key。

规则：默认模拟服务；QPS 默认 3，服务端范围大于 0 且不超过 20；前端输入步长 0.1。并发默认 3、范围 1—8；每日上限默认 1000、范围 1—1,000,000；自动重试默认 3、范围 0—5。默认存入系统凭据库，只有用户勾选明文选项才写入本机未加密文件。单用户拥有设置权限。

异常：凭据库不可用时显示保存失败，保留明文保存选项供用户选择；不自动降级为明文。真实模式无 Key 时阻止创建真实任务或执行真实查询，不替换为模拟结果。实际权限错误进入 FR-05 的暂停路径。

验收 AC-01：给定无 Key 环境，模拟任务可执行；选择真实服务时提示缺 Key，不产生模拟冒充的真实结果。给定已有 Key，留空保存其他配置后 Key 不变。QPS=21 或并发=9 提交失败。上述任一行为不符即失败。

FR-02 导入起点与字段校验

用户任务：将文件中的起点转换为可查询、可追溯的数据集。

交互：进入“新建分析任务”第一步“导入客源地”，选择 CSV 或已导入数据集；上传后展示字段映射，第二步“检查客源地”确认编号、名称、经纬度映射并校验；查看有效、异常、重复及空行计数，再确认坐标。异常提示含行号与原因，有效数据可继续，异常行保留用于检查。

规则：上传上限为 100×1024×1024 字节；MVP 使用 CSV，XLSX 列入扩展。CSV 依次尝试 UTF-8 BOM、GB18030、UTF-16，支持逗号、分号、制表符；扩展 XLSX 读取活动工作表的值。首行为表头，重复列名阻止上传。经纬度必须映射到不同列，必须为有限数字，经度范围 [-180,180]、纬度 [-90,90]。编号空缺按原始行号生成 ROW-行号；名称未映射可留空。

坐标系允许 WGS84、GCJ-02、BD-09。有效的行级坐标系优先于文件选择；行级为空时使用文件坐标系，非法行级值使该行无效。坐标同时存在多组时优先识别路线用 GCJ-02 列，用户可修改映射。

重复规则：同文件中重复原编号或原始经纬度数值相同即标记重复；重复行保留，坐标合法时仍可采集。保留原编号，同时为冲突来源生成含原始行号的唯一来源 ID。重复统计可与有效统计重叠，不能将二者相加作为总行数。同文件再次上传创建新数据集，不与历史数据集合并去重；同一未被任务使用的数据集重新校验替换其点位。已用于任务的数据集禁止修改映射。

异常：空文件、损坏文件、重复表头和超限文件提示具体原因；非法坐标行不进入有效集合。没有有效起点不能继续建任务。本版本不提供多工作表选择、跨数据集自动合并或自动修正坐标。

验收 AC-02：文件含 A=(114,30)、A=(115,31)、B=(114,30)、C=(181,30)、D=(NaN,30)，坐标系 GCJ-02。校验后共 5 行、有效 3 行、无效 2 行、重复 2 行；前三行保留，来源 ID 各不相同。将经纬度映射同列，校验失败。CSV 字段与原始行可对应。计数、保留策略或映射限制不符即失败。

FR-03 目标地点管理

用户任务：建立和选择本次查询的目标地点。

交互：侧栏“目标地点”进入列表，点击新增或编辑，填写名称、经纬度和坐标系，点击“保存目标”；成功回到更新后的列表，失败在表单内显示。新建任务第四步“选择重点村”选择本次目标。删除前展示不可撤销确认，确认后刷新列表。

规则：名称 1—120 字；经纬度范围同 FR-02；坐标系默认 GCJ-02；备注上限 500 字。目标集合不能为空。目标编辑、删除不改写已有任务的输入快照和结果。用户在真实试采前确认目标坐标及导航入口。

异常：非法坐标或空名称阻止保存，目标已不存在时提示刷新。批量操作有任一目标不存在时返回错误，不按部分成功默默处理。

验收 AC-03：新增一个合法目标后可在任务中选中；用其创建任务，再编辑或删除目标，原任务的名称、坐标与历史结果不变。空名、经度 181 保存失败。出现历史数据改变或无效目标进入任务即失败。

FR-04 单批次任务创建

用户任务：确定采集对象、方向、时刻和服务，生成可核对的计划。

交互：依次完成“导入客源地 → 检查客源地 → 确认坐标 → 选择重点村 → 安排采集 → 选择地图服务 → 检查并开始”。第五步选择即时或定时；定时填写日期、时刻及窗口。第六步选择完整比较、服务、路线策略、去程/返程，并确认结果为实际查询期间的估算。最后展示任务名、数据用途、计划数量与容量提示；点击“开始采集”或“创建定时采集”，提交中禁用，成功进入任务查看路径，失败保留草稿及错误提示。

规则：任务名 1—120 字，至少一个目标和一个方向；默认即时、完整比较、去程。单批次任务窗口默认 30 分钟、范围 1—120 分钟。模拟用途不得选择真实试采/正式采集。路线策略默认 32，界面提供推荐、少收费、大路优先、速度最快选项。

即时任务创建后 queued，未来定时任务 scheduled；到达时间进入待执行/执行链路。计划只决定何时发请求，高德接口返回请求时的当前路线估算。容量估计不包含重试，不作为完成时长保证。

异常：无有效输入、无目标、无方向、无 Key 或缺必要确认时阻止提交并定位字段；重叠批次、历史日期提交规则按 Q-02 澄清后冻结。

验收 AC-04：3 有效起点、2 目标、1 个批次，单向计划 6 条，双向 12 条，每条方向正确。未来任务在计划前不发真实请求。模拟服务提交正式用途失败；连续点击提交不得创建多个任务。数量、方向或模式不符即失败。

FR-05 计划执行、限流与预算

用户任务：在允许窗口内发起查询，查看真实进度和调用量。

交互：任务中心进入任务详情，显示状态、计划数、成功/失败数和进度；运行期间约每 2 秒刷新任务信息。额度、凭据等异常显示原因及下一步，例如“每日查询上限已达到，请核查预算后继续”。

规则：定时窗口约束每次真实请求的启动时刻，区间为 [计划时刻, 计划时刻+窗口)。首次与重试均重新检查窗口。窗口结束后仍未发起的观测标记失败，并记录错过原因；不请求当前结果补作历史结果。在窗口内启动、窗口后响应的请求保存实际响应时间和跨窗标记，质量判断与请求成功状态分开。

执行器使用本机共享的请求启动限流器，QPS 与并发分别限制；任务由工作器调度，不承诺多个任务同时运行。就绪定时任务按最早到期批次选取；长任务抢占策略见 Q-03。每日调用按北京时间自然日、提供器累计，包含失败和重试，不含模拟；达到上限暂停，不自动等待次日恢复。用户确认后继续。

真实查询单次网络超时配置为 15 秒。自动重试为首次之外追加 N 次，默认最多 4 次尝试；退避依次 1、2、4、8、16 秒。网络错误、HTTP 429/5xx、非 JSON 或结构无效响应，以及提供器指定临时错误码可重试。无可用路线等非重试错误直接记失败；Key/权限等致命错误暂停任务。高德当前取返回的首条路线。

异常：不对真实失败自动切换模拟。原始响应保存失败标记写入异常；数据无法持久化属于发布阻断问题，立即人工检查磁盘和权限。失去网络仍按有限重试处理。

验收 AC-05：重试设 2，注入前两次超时、第三次成功，产生 3 条尝试和 1 条成功观测，最多新增 3 次调用。重试设 0 只尝试一次。预算仅余 1 次时不再启动第二次真实请求。QPS=3 时用请求开始时间验证任意一秒窗口不超限。在窗口内启动、窗口后返回时保留成功及跨窗标记；窗口外不启动下一次请求。无限重试、超预算或改写时间即失败。

图 3 · 采集时间窗口。区分窗口内完成、跨窗响应、尚未发起及超窗重试四种情况。

FR-06 暂停、继续、失败重试与恢复

用户任务：保留已成功结果，只处理尚未完成或失败部分。

交互：任务中心/详情点击暂停，状态变 paused；提示“已暂停后续请求，在途请求可能继续返回”。点击继续后进入 queued，重新检查计划、预算和窗口。点击重试失败项，将失败观测转回 pending 并入队；活跃任务先暂停。异常退出后重新启动，查看恢复状态再继续。

规则：pause 适用于 running/queued/scheduled；resume 适用于 paused/failed。retry 适用于非活跃任务，只重置失败项，不清除成功项，历史请求尝试保留。暂停不取消已发出的请求；在途结果可保存。进程中断后未完成的在途声明恢复为待处理，可能再次发起真实请求，但已持久化成功观测不重复计数。窗口已过时即使继续/重试，也按超窗处理。

异常：已完成且无失败任务不提供有效重试操作。恢复时无 Key 或预算不足则保持暂停/返回明确原因。暂停后立即导出的在途一致性按 Q-04 验收，未解决前必须等待在途结束。

验收 AC-06：固定 6 条观测，先持久化 2 条成功后暂停并重启；继续后最终成功仍为 6 条，前 2 条无新增成功记录。注入 1 条失败并重试，该条新增尝试而成功项不重算。超窗继续不产生新的超窗请求。数据丢失、成功数重复或无提示恢复失败即失败。

FR-07 任务、结果查看与删除

用户任务：理解每条观测的状态，筛选结果并管理历史任务。

交互：任务中心查看任务名称、用途、状态和计数，进入详情筛选状态、目标、方向和批次；加载、空结果和查询失败分别显示。失败提供错误原因。任务改名或改用途后刷新，删除须确认不可撤销。活跃任务点击删除提示“请先暂停任务”。

规则：结果列表默认按记录 ID 升序，接口默认每页 50、上限 200。去返程分别统计。模拟用途不能改为真实试采/正式。删除 queued/running/scheduled 任务被拒绝。删除非活跃任务会级联删除数据库内关联结果；已下载文件不受影响，原始响应文件清理规则见 Q-05。空结果不意味着没有计划观测，须核对筛选条件。

验收 AC-07：对 6 条结果筛选只成功项，显示条数等于成功计数；切换方向不混入另一方向。全部观测均以业务失败结束时任务为 partial，不是内部错误 failed。活跃任务删除返回冲突，暂停后确认删除，任务及其关联结果消失。模拟改正式被拒绝。计数不一致或越过删除限制即失败。

6.1 状态与操作矩阵

completed 表示观测处理结束且没有失败，不等同于所有结果都满足研究分析条件；跨窗、来源及质量标记仍须检查。

图 4 · 任务状态流转。任务级状态与恢复路径，观测记录保留独立的成功、失败及待处理状态。

FR-08 Excel 明细导出

用户任务：取得与当前查询条件一致、字段可追踪的结果文件。

交互：在任务详情确认状态和筛选条件，点击明细导出，提示“正在生成 Excel…”，成功后开始浏览器下载，失败显示原因并保留原数据。活跃任务提示“请暂停任务或等待完成后导出一致结果”。

规则：本版本必交付 XLSX 明细，不以其他格式替代。明细沿用当前搜索、状态、目标、时长、批次、方向及排序条件，导出所有匹配行，不仅当前页。默认无状态筛选时包括成功、失败和待处理记录。

文件名：路线明细_任务名_北京时间YYYYMMDD-HHMMSS_任务ID前8位.xlsx；名称中的文件系统非法字符替换为下划线，任务名部分最多 60 字。工作表为“路线明细”，每满 1,000,000 行续建“路线明细2”等。磁盘生成文件使用独立标识，浏览器重复下载重命名由用户/浏览器决定。

核心字段：任务及观测标识、起终点标识与坐标、方向、计划时间、实际请求时间、响应时间、服务与数据来源、路线策略、成功/失败状态、错误原因、距离和耗时。内部距离米、耗时秒，明细另有公里和分钟换算。北京时间采用带 +08:00 的时间表示；失败数值为空。开发前冻结表头、顺序、字段类型及空值样例。

异常：导出失败不修改采集结果；磁盘不可写时反馈生成失败。暂停但仍有在途时，等待请求结束再执行本版本一致性验收。后续 ZIP 数据包按完整任务导出，独立于明细筛选。

验收 AC-08：固定任务有 4 成功、1 失败、1 待处理。无筛选导出 6 行；筛选成功导出 4 行。比对标识、方向、时间、单位及状态逐项相同，失败距离/耗时为空。文件可打开，表名和文件名符合规则。生成失败后原数据库不变。任一数量、字段或筛选语义错误即失败。

FR-09 本地启动与退出

用户任务：可靠启动应用，退出后保留数据，理解后台运行条件。

交互：打开 macOS 应用，浏览器进入本机页面；端口冲突时使用可用端口。再次打开应用进入已有实例。关闭网页后任务继续，点击“退出应用”结束后台。首次安排定时采集前提示“请保持电脑开机、联网且不休眠”。

规则：仅本机回环监听并校验会话；同一数据目录只运行一个实例。系统凭据库中的 Key 独立于数据目录备份。备份先退出应用再复制整个数据目录。具体 macOS/浏览器兼容版本于 T0 确认。

异常：端口不可用、数据目录不可写、凭据访问失败分别给出原因；不启动第二个同时写入相同目录的实例。关机、休眠期间不执行，恢复后超窗观测保留缺测。

验收 AC-09：占用默认端口后仍能进入应用；再次启动不产生第二个写实例。关闭网页后正在运行任务继续；退出应用后无新请求，再启动历史数据仍可读取。错误提示缺失、实例冲突或数据丢失即失败。

七、非功能性需求

性能基线表必须填写：CPU/内存、系统/浏览器、应用版本、起点/目标/观测规模、模拟或真实模式、导入时限、界面响应时限、导出时限、连续运行时长。真实服务等待与本地界面响应分开记录。

八、依赖、假设与风险

8.1 依赖与前提

8.2 风险清单

概率为本版本计划判断，按测试和试用结果更新。

8.3 待澄清与冻结事项

需求冻结前完成上述决策，规则调整同步更新交互步骤、验收条件和测试样例。

九、测试与验收计划

9.1 范围与方法

功能：FR-01—09 全覆盖。回归：缺陷修复及其影响的核心链路。恢复：暂停、强制终止、重启、预算和超窗。兼容：T0 确认的 macOS/浏览器组合。性能：按冻结基线分别执行模拟和真实小样本。

外部故障使用可控替身响应注入，实际账号只进行授权的小规模查询；模拟测试结果不计入真实服务成果。

固定样本：S-A 为 3 个合法起点和 2 个合法目标，用于单向 6/双向 12 条验证；S-B 为 AC-02 的 5 行导入文件；S-C 为 4 成功、1 失败、1 待处理的状态夹具；S-D 为超时、权限、预算和超窗故障配置。各文件保存版本与校验值。

9.2 用例与通过标准

执行状态：待验证。每条记录：版本、环境、样本、前置、步骤、预期、实际、证据、执行人、日期、缺陷编号和复测结论。

9.3 发布前 Checklist

• [ ] 本版本范围、排期和负责人确认，Q-01—07 关闭或对应功能经明确裁剪后重新评审。
• [ ] FR-01—09 及缺陷回归用例通过，数据/安全阻断缺陷为0。
• [ ] 真实小样本的时间、方向、状态、请求数与导出核对一致。
• [ ] 性能、兼容和连续运行达到冻结门槛。
• [ ] 安装、Key配置、试采、运行条件、常见错误、反馈与备份说明随包交付。
• [ ] 备份恢复及版本兼容确认，发布包和回退材料可取得。
• [ ] 负责人确认验收记录和剩余问题，签署发布结论。

9.4 发布后的观察与处理

发布后重点观察前两个真实采集批次：按批次核对计划数量、窗口内有效结果、首次成功率、重试恢复率、超窗量、每日调用量和导出一致性。没有重试样本时恢复率记“不适用”，不填100%。

数据丢失、来源混淆、凭据泄露、重复计数或错误方向出现一次即暂停新任务。非致命服务错误按既定重试处理；任务暂停、连续失败或完整率下降时，杨天文检查日志、配额和窗口，不自动扩大预算。首轮基线不足时逐批人工检查，不新增监控平台。

反馈材料包括应用版本、任务标识、错误时间、操作步骤和脱敏日志；不提交 Key 或私人研究样本。问题修复绑定原 TC，并回归相关链路后再发布。

配图源文件：下载可编辑图集。

9.5 协同交付结论

• 本版本交付单批次采集闭环，核心功能、后续扩展和不做范围分别列明。
• 每项核心需求包含入口、步骤、反馈、规则、异常及可判定的验收条件。
• 尚未冻结的行为集中到 Q-01—07，规定负责人、截止时间和阻断范围。
• MVP 计划周期为10个工作日，需求冻结时确认资源、工作量和发布日期。