# 交通可达性分析系统 · 产品需求文档

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

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

## 一、背景与目标

### 1.1 阶段与版本范围

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

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

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

### 1.2 本版本成功判据

| 类型 | 指标 / 判据 | 通过门槛 | 统计与核查方式 |
| --- | --- | --- | --- |
| 核心结果 | 固定样本采集与导出闭环 | 第九部分阻断用例全部通过 | 按任务核对计划、观测、请求尝试和文件 |
| 完整性 | 计划观测均有明确去向 | 固定样本中成功、失败及待处理状态可逐条解释，数量对账无差异 | 包括未发起的超窗记录，不只统计成功项 |
| 数据护栏 | 丢失、重复计数、方向错置、模拟混入真实数据 | 验收中出现任一项即不发布 | 数据比对及恢复测试 |
| 安全护栏 | Key / 会话令牌泄露 | 验收日志、截图和导出中均不得出现 | 搜索测试凭据及人工检查 |
| 用户验证 | 独立完成小样本任务 | 计划邀请 3 人，至少 2 人不由作者代操作完成 | 记录求助、错误步骤和最终结果；门槛在 T0 确认 |
| 效率验证 | 人工与工具操作时间差 | 本版本交付对照记录及结论，不预设改善百分比 | 相同输入各 3 轮，分开统计操作、等待及返工 |

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

## 二、交付计划与里程碑

### 2.1 周期与责任

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

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

| 阶段 | 建议时间 | 交付物 | 完成条件 | 责任 |
| --- | --- | --- | --- | --- |
| 范围与规则冻结 | T0—T0+1 工作日 | 范围表、待澄清项结论、样本与字段清单 | 阻断规则问题关闭，确定性能测试条件 | 产品负责人 |
| 开发与联调 | 第 2—4 工作日 | 可运行应用、模块实现与自测记录 | 导入至导出主链路可执行 | 产品负责人组织 AI Agent |
| 功能与回归验收 | 第 5—6 工作日 | 用例结果、缺陷清单、恢复及导出比对记录 | 阻断缺陷为 0 | 验收负责人：杨天文 |
| 真实试采与用户试用 | 第 7—8 工作日 | 小样本真实请求、独立操作及计时记录 | 数据一致，试用有明确结论 | 杨天文与确认后的参与者 |
| 复测与发布准备 | 第 9 工作日 | 最终包、使用说明、备份及回退材料 | 核心用例及缺陷复测通过，兼容性确认 | 杨天文 |
| 发布与观察 | 第 10 工作日及后续两个采集批次 | 发布确认、观察记录 | 无数据与安全护栏异常 | 杨天文 |

### 2.2 不可发布与回退条件

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

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

## 三、产品概述

### 3.1 一句话说明

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

### 3.2 功能模块与优先级

| 编号 | 模块 | 重要性 | 交付要求 |
| --- | --- | --- | --- |
| FR-01 | 地图服务与凭据配置 | 核心 | 完成配置保存、模式区分与凭据异常处理 |
| FR-02 | 起点导入、映射与校验 | 核心 | 完成上传、映射、校验与异常行反馈 |
| FR-03 | 目标地点管理 | 核心 | 完成新增、编辑、选择、删除与任务快照 |
| FR-04 | 单批次任务创建 | 核心 | 生成即时/定时任务与独立方向观测 |
| FR-05 | 执行、限流与预算 | 核心 | 按窗口和预算执行并记录请求尝试 |
| FR-06 | 暂停、继续与重试 | 核心 | 保存成功结果并可继续处理剩余项 |
| FR-07 | 任务、结果与删除 | 核心 | 展示状态、筛选明细并执行任务管理 |
| FR-08 | Excel 明细导出 | 核心 | 生成与筛选条件一致的 Excel 明细 |
| FR-09 | 本地启动与退出 | 核心 | 完成本地启动、单实例与持久化 |
| EX-01 | 多日期、附近目标模式、质量与比较报告 | 非核心 | 后续版本评估，不作为 MVP 发布前置 |
| EX-02 | ZIP 审计包、CSV、汇总及分析表 | 非核心 | 后续版本评估，不作为 MVP 发布前置 |

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

### 4.1 用户与角色

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

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

### 4.2 核心任务与主路径

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

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

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

## 五、需求范围说明

![图 1 · 业务责任泳道](../assets/prd/01-business-flow.png)

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

### 5.1 MVP 范围

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

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

### 5.2 延后与不做

| 范围 | 处理 | 原因 |
| --- | --- | --- |
| XLSX 导入、多日期、附近目标、双向质量比较、审计包 | 延后 | 优先完成单批次采集及明细导出 |
| 自然语言配置、Agent 自主规划、自动研究结论 | 不纳入本版本 | 运行链路为程序调度与地图查询 |
| 云端协作、计费、移动端 | 不做 | 超出本地单用户边界 |
| 车辆实测轨迹、历史路况回放、未来路况预测 | 不做 | 当前服务提供请求时的路线估算 |
| 采集窗口内全量必达承诺 | 不做 | 完成量受账号、网络、频率和重试影响 |

### 5.3 系统边界与分工

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

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

## 六、详细需求说明

### 6.0 全局规则与数据口径

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

![图 2 · 关键页面交互线框](../assets/prd/02-interaction-wireframe.png)

图 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 · 采集时间窗口](../assets/prd/04-collection-window.png)

图 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 状态与操作矩阵

| 当前状态 | 事件 / 操作 | 下一状态 | 结果处理 |
| --- | --- | --- | --- |
| scheduled | 到达计划且轮到执行 | running | 启动窗口检查和查询 |
| queued | 被工作器选中 | running | 执行待处理观测 |
| running/queued/scheduled | 暂停或凭据/预算异常 | paused | 不再启动后续请求，保留在途及成功结果 |
| paused/failed | 继续 | queued | 保留结果，重新检查剩余计划 |
| 非活跃任务 | 重试失败项 | queued | failed 观测转 pending，保留成功及尝试历史 |
| running | 无 pending 且失败数为 0 | completed | 查看和导出 |
| running | 无 pending 且失败数大于 0 | partial | 包括全部业务失败及超窗失败 |
| running | 内部执行异常 | failed | 保留日志，由用户检查后继续 |
| 非活跃任务 | 确认删除 | 删除 | 按 FR-07 处理关联数据 |

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

![图 4 · 任务状态流转](../assets/prd/03-task-states.png)

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

## 七、非功能性需求

| ID | 要求 | 验收方法与门槛 |
| --- | --- | --- |
| NF-01 | 数据一致性 | 固定样本的计划、明细与导出逐项一致；中断后成功项不丢失、不重复 |
| NF-02 | 请求限制 | QPS、并发、预算和重试按 FR-01/05 测试；限流后不得追赶式突发 |
| NF-03 | 本地安全 | 只监听本机，会话有效才可操作；凭据不出现在日志/截图/导出；检查用测试 Key |
| NF-04 | 可理解性 | 核心状态用文字说明；错误包含原因和下一步；空态、加载和失败可区分 |
| NF-05 | 性能与容量 | T0 冻结设备、输入规模、响应和导出时限；未确认前不承诺数值 SLA，Q-06 为排期阻断项 |
| NF-06 | 稳定性 | 定时等待、执行、暂停与恢复均需覆盖；连续运行时长在 T0 按最长计划任务确定 |
| NF-07 | 兼容与备份 | 验收机 macOS 与浏览器版本入档，恢复副本可打开；原目录始终保留 |

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

## 八、依赖、假设与风险

### 8.1 依赖与前提

| 依赖 | 前提 / 责任 |
| --- | --- |
| 输入数据 | 用户确认坐标、坐标系和目标入口；使用脱敏固定样本测试 |
| 地图服务 | 用户提供有效 Web 服务 Key、权限与剩余额度，真实试采前确认 |
| 设备环境 | 采集时开机、联网、不休眠，数据目录可写 |
| 人员投入 | 杨天文确认可投入时间；试用者在第 7 工作日前落实 |
| 开发与验证 | AI Agent 按功能要求实现，负责人核查输出并执行验收 |

### 8.2 风险清单

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

| 风险 | 影响 | 概率 | 缓解与处理 | 负责人 |
| --- | --- | --- | --- | --- |
| 权限、配额或网络异常 | 采集中断或欠采 | 中 | 真实小样本验证、有限重试、预算检查 | 杨天文 |
| 设备休眠/退出 | 错过窗口 | 中 | 采集前检查运行条件，恢复后核查缺测 | 杨天文 / 使用者 |
| 并发、暂停与导出时序 | 数量不一致 | 待验证 | 故障注入，确认在途终止条件 | 杨天文 |
| 坐标与重复规则误解 | 查询地点或计划数量错误 | 中 | 显示校验结果，保留原行与来源标识 | 杨天文 |
| 磁盘或迁移问题 | 数据丢失、无法回退 | 待验证 | 备份恢复演练，保留原目录 | 杨天文 |
| 独立用户或账号未落实 | 无法按期完成试用 | 中 | T0 确认资源，缺失时重排试用里程碑 | 杨天文 |

### 8.3 待澄清与冻结事项

| ID | 问题 | 必须形成的结论 | 截止 | 是否阻断 |
| --- | --- | --- | --- | --- |
| Q-01 | 开发工作量、人员投入和发布日期 | 确认 10 工作日排期或调整，填写具体日期 | T0+1 | 阻断排期 |
| Q-02 | 历史日期、相同时段/重复批次的提交规则 | 分别明确阻止、合并或独立保留，并给出提示文案 | T0+1 | 阻断任务冻结 |
| Q-03 | 长任务与到期任务的抢占边界 | 说明何时切换、已在途请求如何处理；必要时限制本版本并行任务操作 | T0+1 | 阻断定时验收 |
| Q-04 | 暂停后仍有在途请求时的导出 | 验证是否等待、阻止或提供稳定快照；冻结后补 AC-08 并发用例 | T0+1 | 阻断一致性验收 |
| Q-05 | 删除任务后的文件保留 | 明确原始响应、服务端导出文件的保留与清理，提示文案对应实际行为 | T0+1 | 阻断删除规则冻结 |
| Q-06 | 性能与兼容边界 | 填写第七部分基线表及通过阈值 | T0+1 | 阻断性能验收 |
| Q-07 | 完整导出字段版本 | 保存基准文件、表头顺序、类型与空值样例 | 第 4 工作日前 | 阻断导出验收 |

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

## 九、测试与验收计划

### 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 用例与通过标准

| TC | 需求 / 样本 | 操作与预期 | 不通过条件 |
| --- | --- | --- | --- |
| TC-01 | FR-01 | 无 Key 分别建模拟/真实任务，验证模式和设置范围 | 真实暗转模拟、错误设置被接受、Key 被清空 |
| TC-02 | FR-02 / S-B | 按 AC-02 导入、映射、校验；有效3/无效2/重复2 | 自动删重复、来源 ID 冲突、计数不符 |
| TC-03 | FR-02 | 空文件、重复表头、超100MiB、已用于任务的数据集改映射 | 无错误原因或修改历史输入 |
| TC-04 | FR-03 | 创建目标并建任务，编辑/删除目标后查历史 | 快照改变、非法目标可保存 |
| TC-05 | FR-04 / S-A | 分别单向和双向建任务 | 计划数不是6/12、方向错误、重复提交建多任务 |
| TC-06 | FR-05 / S-D | 窗口内发起后跨窗响应，再尝试超窗请求 | 时间改写、跨窗标记缺失、超窗仍启动 |
| TC-07 | FR-05 / S-D | 重试2次、前2次超时第3次成功；再测重试0 | 尝试数非3/1，成功观测重复 |
| TC-08 | FR-05 | 预算余1次、QPS3及并发边界 | 额外请求超预算、启动超限、计数漏重试 |
| TC-09 | FR-06 / S-A | 成功2条后暂停、终止、重启、继续 | 成功丢失或重复；超窗恢复仍发新请求 |
| TC-10 | FR-07 / S-C | 筛选、修改用途、活跃与暂停状态分别删除 | 计数不符、模拟改正式、活跃任务可删除 |
| TC-11 | FR-08 / S-C | 全部与成功筛选导出，对比6/4行及字段 | 数量、时间、方向、空值、单位不一致 |
| TC-12 | FR-08 | 不可写目录；并发导出按Q-04结论测试 | 原数据改变、文件无提示失败、快照不一致 |
| TC-13 | FR-09 | 端口占用、二次启动、关页、退出与备份恢复 | 多实例写入、关页停任务、退出后仍新发请求 |
| TC-14 | FR-01—09 | 缺陷修复后重跑关联核心链路 | 原有通过用例出现回退 |
| TC-15 | NF-05/06 | 按冻结设备、规模、时限和时长执行 | 超过确定阈值、卡死、记录损坏 |
| TC-16 | 用户验证 | 3人独立完成同一小样本，人工/工具各3轮计时 | 未形成结果或未达确认后的试用门槛 |

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

### 9.3 发布前 Checklist

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

### 9.4 发布后的观察与处理

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

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

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

配图源文件：[下载可编辑图集](prd-diagrams.zip)。

### 9.5 协同交付结论

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