需求

需求产出

Signed-off-by: yami <yami@yami.ink>

01-需求文档.md

@@ -0,0 +1,295 @@
+# 路侧停车泊位智能管理系统 · 需求文档
+
+| 项目 | 内容 |
+|---|---|
+| 文档版本 | v1.0（待组内评审） |
+| 所属选题 | 实训考题一 · 路侧停车泊位智能管理系统（基础题，建议 3 人） |
+| 产出角色 | 需求 Agent（安梓骏） |
+| 产出日期 | 2026-09-17 |
+| 下游读者 | 编码 Agent / 测试 Agent / 交付 Agent / 课程设计报告"需求分析"章节 |
+| 评审约定 | 本文档经组内评审、待确认问题（第 10 节）逐条拍板后，方可进入编码；编码阶段若字段/接口与本档冲突，以组内评审结论回写本档为准 |
+
+---
+
+## 1. 项目背景与目标
+
+城市路侧停车位由管理方统一运营，但泊位占用情况与收费记录仍靠人工登记，导致漏收、纠纷与账目不清。
+
+本期目标：上线一套轻量系统，把**泊位状态、车辆进出场与计费**线上化，并为路段管理员提供**经营看板**，解决漏收、纠纷与账目不清三个痛点。
+
+## 2. 项目范围
+
+本期只做以下 4 个模块（构成完整闭环）：
+
+| 模块 | 范围要点 |
+|---|---|
+| M1 泊位档案管理 | 路段、泊位编号、泊位类型（标准/无障碍）、当前状态（空闲/占用/停用） |
+| M2 车辆进出场登记 | 录入车牌与进场时间，出场时结算；支持人工补录与异常修正 |
+| M3 计费与缴费 | 按停车时长阶梯计费，生成缴费订单，记录缴费状态 |
+| M4 经营看板 | 路段泊位占用率、当日收入、异常订单（超时未缴、金额异常） |
+
+**本期明确不做**（约束，防止发明需求外功能）：
+
+- 无感支付、车牌识别设备对接（本期车牌为人工录入）
+- 多停车场/室内车位、车位预约、会员体系
+- 电子发票、第三方支付渠道对接（缴费为线下动作的线上确认）
+- 移动端 App、短信通知
+
+## 3. 参与角色与使用场景
+
+| 角色 | 说明 | 触点 |
+|---|---|---|
+| 路段管理员 | 唯一业务操作角色。日常巡查路段，为进场车辆登记，出场时结算收款，处理免单等异常，查看经营看板 | 现场用手机、后台用电脑操作；**网络可能不稳定**（来自题目背景，NFR-4 需容忍弱网） |
+
+> 本系统没有司机端：司机不直接操作系统，一切登记与结算由路段管理员完成。
+
+## 4. 术语表
+
+| 术语 | 定义 |
+|---|---|
+| 泊位 | 路侧一个可停车位的档案记录，隶属某路段，有唯一编号 |
+| 在场记录 | 一次进出场过程（parking_record），进场生成，出场时结算关闭 |
+| 订单 | 出场结算生成的收费单（parking_order），金额由阶梯计费规则算出 |
+| 免单 | 订单金额免除，状态置为"已免单"，必须记录原因 |
+| 超时未缴 | 出场后超过阈值（Q7，建议 24 小时）仍未缴费的订单 |
+| 阶梯计费 | 前 15 分钟免费；首小时 5 元；之后每 30 分钟 2 元；单日封顶 40 元（详见 BR-6~BR-9） |
+
+## 5. 功能需求清单（FR）
+
+| 编号 | 功能 | 对应用户故事 | 优先级 | 关联业务规则 | 建议接口（以编码阶段 openapi.json 为准） |
+|---|---|---|---|---|---|
+| FR-1 | 泊位档案管理：增删改查 + 按路段批量导入 | US-1 | Must | BR-2、BR-20 | GET/POST /api/spaces；批量导入见 §9 补充建议 |
+| FR-2 | 进场登记：车牌校验、泊位状态校验、重复进场拦截 | US-2 | Must | BR-1~BR-4 | POST /api/records/entry |
+| FR-3 | 出场结算：按阶梯计费生成订单，重复出场拦截 | US-3 | Must | BR-5~BR-12 | POST /api/records/exit |
+| FR-4 | 缴费确认：幂等，状态流转 待缴费→已缴费 | US-4 | Must | BR-13、BR-14 | POST /api/orders/{id}/pay |
+| FR-5 | 免单：待缴费→已免单，记录原因 | US-4 | Must | BR-15 | POST /api/orders/{id}/exempt（§9 补充建议） |
+| FR-6 | 人工补录进场与异常修正（限在场记录） | US-5 | Should | BR-21 | POST /api/records、PUT /api/records/{id}（§9 补充建议） |
+| FR-7 | 经营看板：占用率、当日收入、超时未缴清单、金额异常清单 | US-6 | Must | BR-16~BR-19 | GET /api/dashboard |
+| FR-8 | 泊位状态一屏可视化（占用率进度条/热力） | US-7 | Could（加分项） | — | 随 GET /api/dashboard 扩展 |
+| FR-9 | 按周收入趋势统计 | US-8 | Could（加分项） | — | GET /api/dashboard?range=week 扩展 |
+
+> 一致性约束（对交付 Agent）：README 的功能数 = 接口文档的接口数 = 本表行数口径（FR-8/FR-9 为加分项，若实现则计入）。
+
+## 6. 用户故事与验收标准
+
+共 8 条用户故事，满足 ≥5 条要求；每条含故事描述、优先级（MoSCoW）与 Given-When-Then 验收标准（覆盖正常/边界/异常）。
+
+### US-1 管理泊位档案（Must · FR-1）
+
+**作为**路段管理员，**我希望**能维护路段下的泊位档案（新增、修改、删除、按路段批量导入），**以便**系统里的泊位与路面实际泊位一致。
+
+| 编号 | Given（前置） | When（操作） | Then（预期） | 关联 |
+|---|---|---|---|---|
+| AC1.1 | 管理员在后台 | 新增泊位：路段"人民路"、编号 001、类型"标准" | 保存成功；列表可见；状态默认"空闲" | 正常 |
+| AC1.2 | 已准备按路段的导入数据 | 执行批量导入 | 全部入库，返回成功条数与失败条数及原因 | 正常 |
+| AC1.3 | 同一路段已存在编号 001 的泊位 | 再新增编号 001 | 拒绝，提示"泊位编号已存在" | 边界（重复） |
+| AC1.4 | 某泊位状态为"占用"（有车辆在场） | 删除该泊位 | 拒绝，提示需先处理在场记录 | 异常 |
+| AC1.5 | 录入表单 | 类型填"标准/无障碍"以外、状态填非法值 | 拒绝，参数校验失败 | 边界（取值） |
+
+### US-2 车辆进场登记（Must · FR-2）
+
+**作为**路段管理员，**我希望**录入车牌并选择泊位完成进场登记，**以便**系统记录车辆进场时间并把泊位标记为占用。
+
+| 编号 | Given（前置） | When（操作） | Then（预期） | 关联 |
+|---|---|---|---|---|
+| AC2.1 | 泊位"人民路-001"状态为空闲 | 提交合法车牌"京A12345"进场 | 登记成功；生成在场记录；泊位状态→占用 | 正常 · BR-4 |
+| AC2.2 | 进场表单 | 车牌留空提交 | 拒绝，提示车牌必填 | 边界 · BR-1 |
+| AC2.3 | 进场表单 | 车牌"AB12345"（无省份汉字）/ "京A123456"（8 位，新能源）等非法格式 | 拒绝，提示格式非法（8 位新能源本期不支持，见 Q5） | 边界 · BR-1 |
+| AC2.4 | 泊位状态为"停用" | 提交合法车牌进场 | 拒绝，提示泊位已停用 | 异常 · BR-2 |
+| AC2.5 | 泊位状态为"占用" | 提交合法车牌进场 | 拒绝，提示泊位已占用 | 异常 · BR-2 |
+| AC2.6 | 车牌"京A12345"已有在场记录 | 再次提交该车牌进场（选其他空闲泊位） | 拒绝，提示该车辆已在场 | 异常 · BR-3 |
+
+### US-3 车辆出场结算与阶梯计费（Must · FR-3）
+
+**作为**路段管理员，**我希望**对在场车辆执行出场结算，系统按时长自动算出金额并生成订单，**以便**我不需要人工算钱，收费有依据。
+
+| 编号 | Given（前置） | When（操作） | Then（预期） | 关联 |
+|---|---|---|---|---|
+| AC3.1 | "京A12345"在场 61 分钟 | 执行出场结算 | 生成待缴费订单 7 元；记录状态→已出场；泊位→空闲 | 正常 · BR-8 |
+| AC3.2 | 在场恰好 15 分钟 | 执行出场结算 | 金额 0 元（免费段上限含 15 分钟） | 边界 · BR-6 |
+| AC3.3 | 在场 16 分钟 / 恰好 60 分钟 | 执行出场结算 | 分别为 5 元 / 5 元 | 边界 · BR-7 |
+| AC3.4 | 在场 90 分钟 / 91 分钟 | 执行出场结算 | 分别为 7 元 / 9 元（超出首小时部分不足 30 分钟按 30 分钟计，见 Q6） | 边界 · BR-8 |
+| AC3.5 | 跨天停车 25 小时 | 执行出场结算 | 45 元（按 Q1 建议口径：每天独立计费并各自封顶 40 元后叠加；拍板前以此为准） | 边界 · BR-9 |
+| AC3.6 | 某在场记录已出场结算过 | 再次对该记录执行出场 | 拒绝，提示重复出场 | 异常 · BR-11 |
+| AC3.7 | 传入不存在的记录 ID | 执行出场结算 | 拒绝，提示记录不存在 | 异常 · BR-11 |
+| AC3.8 | 出场成功后 | 查询泊位状态 | 该泊位已回到"空闲"，可再次进场 | 正常 · BR-12 |
+
+### US-4 缴费确认与免单（Must · FR-4 / FR-5）
+
+**作为**路段管理员，**我希望**对待缴费订单做缴费确认或免单，且已缴费订单不能再改，**以便**账目清晰、防重复收费。
+
+| 编号 | Given（前置） | When（操作） | Then（预期） | 关联 |
+|---|---|---|---|---|
+| AC4.1 | 存在待缴费订单 | 执行缴费确认 | 状态→已缴费，记录缴费时间 | 正常 · BR-13 |
+| AC4.2 | 同一订单已缴费 | 再次发起缴费请求 | 幂等返回：不重复生成流水、不重复计费，业务码提示"订单已缴费" | 边界（幂等）· BR-13 |
+| AC4.3 | 存在待缴费订单 | 执行免单并填写原因 | 状态→已免单，原因已保存 | 正常 · BR-15 |
+| AC4.4 | 已缴费订单 | 再次发起缴费/免单/改金额 | 拒绝，提示订单已终态不可变更 | 异常 · BR-14 |
+| AC4.5 | 待缴费订单 | 免单时原因为空 | 拒绝，提示免单原因必填 | 异常 · BR-15 |
+
+> 说明：题目必做清单第 5 条要求订单状态流转支持"待缴费 → 已缴费 / 已免单"，故免单属本期必做（Must）；"异常订单处理页"（记录操作人）为加分项，本期免单至少要落"原因"字段（Q8）。
+
+### US-5 进场补录与异常修正（Should · FR-6）
+
+**作为**路段管理员，**我希望**对漏登记的车辆补录进场记录、修正错录的车牌或进场时间，**以便**账实相符。
+
+| 编号 | Given（前置） | When（操作） | Then（预期） | 关联 |
+|---|---|---|---|---|
+| AC5.1 | 车辆实际已停放在空闲泊位但漏登记 | 补录：车牌 + 过去的进场时间 | 生成在场记录（进口时间按补录值），泊位→占用 | 正常 · BR-21 |
+| AC5.2 | 某在场记录车牌错录 | 修正车牌 | 修改生效，留变更痕迹（修改时间） | 正常 · BR-21 |
+| AC5.3 | 补录时填写的进场时间晚于当前时间 | 提交补录 | 拒绝，提示时间非法 | 边界 · BR-21 |
+| AC5.4 | 目标泊位为占用/停用 | 提交补录 | 拒绝 | 异常 · BR-21 |
+| AC5.5 | 记录已出场（订单已生成） | 尝试修正车牌/时间 | 拒绝，已出场记录不可修正（Q9） | 异常 · BR-21 |
+
+### US-6 经营看板（Must · FR-7）
+
+**作为**路段管理员，**我希望**一眼看到各路段的泊位占用率、当日收入和异常订单清单，**以便**掌握经营情况并及时处理漏收。
+
+| 编号 | Given（前置） | When（操作） | Then（预期） | 关联 |
+|---|---|---|---|---|
+| AC6.1 | 系统内有多个路段的泊位与订单数据 | 打开看板 | 按路段返回占用率与当日收入 | 正常 · BR-18/19 |
+| AC6.2 | 系统内无任何数据（刚初始化） | 打开看板 | 返回空集合/0 值，不报错 | 边界 |
+| AC6.3 | 存在出场后超 24 小时未缴费的订单 | 打开看板 | 该订单出现在"超时未缴"清单（阈值为 Q7 建议值） | 异常 · BR-16 |
+| AC6.4 | 存在金额 > 40 元或 ≤ 0 元的订单（防御性） | 打开看板 | 该订单出现在"金额异常"清单 | 异常 · BR-17 |
+| AC6.5 | 某路段有 2 个泊位停用 | 计算占用率 | 分母不含停用泊位（建议口径） | 边界 · BR-18 |
+
+### US-7 泊位状态一屏可视化（Could · FR-8，加分项）
+
+**作为**路段管理员，**我希望**泊位占用情况在一屏内用进度条/热力直观展示，**以便**巡查前快速了解全路段状态。
+
+- AC7.1：打开可视化页，能看到各路段占用率图形化展示，数值与看板一致。
+
+### US-8 按周收入趋势统计（Could · FR-9，加分项）
+
+**作为**路段管理员，**我希望**看到最近几周的收入趋势，**以便**对比周间经营变化。
+
+- AC8.1：按周返回收入序列，日期维度正确（跨天订单按缴费日归属，BR-19）。
+
+### INVEST 自检摘要
+
+| 故事 | I 独立 | N 可协商 | V 有价值 | E 可估 | S 小 | T 可测 |
+|---|---|---|---|---|---|---|
+| US-1~US-6 | ✔ 可独立开发验收 | ✔ 细节见待确认问题 | ✔ 对应题目必做功能 | ✔ 各 ≤2 天工作量 | ✔ 单一模块 | ✔ GWT 全覆盖 |
+| US-7/US-8 | ✔ 与主干解耦 | ✔ 加分项可裁剪 | ✔ 演示增强 | ✔ | ✔ | ✔ |
+
+## 7. 业务规则清单（BR）
+
+> 本表是编码与测试的**核对基准**：编码 Agent 逐条实现，测试 Agent 逐条对用例。规则中标注（建议）的口径在 Q 表拍板前按建议执行。
+
+| 编号 | 规则名 | 判断条件 | 违反/命中时的行为 |
+|---|---|---|---|
+| BR-1 | 车牌格式 | 车牌 = 省份简称汉字 + 6 位字母/数字，共 7 位（如 京A12345）；为空或格式不符 | 拒绝进场，提示格式非法（新能源 8 位本期不支持，Q5） |
+| BR-2 | 进场·泊位校验 | 泊位必须存在；状态 = 空闲 | 不存在/停用/占用 → 拒绝进场，分别提示 |
+| BR-3 | 进场·车辆查重 | 该车牌不存在"在场中"记录 | 已在场 → 拒绝（重复进场拦截） |
+| BR-4 | 进场成功 | 校验通过 | 生成在场记录（记录进场时间），泊位状态 → 占用 |
+| BR-5 | 计费时长 | duration = 出场时间 − 进场时间，按分钟计；秒数向上取整到 1 分钟（建议，Q10） | — |
+| BR-6 | 免费段 | t ≤ 15 分钟 | 金额 0 元（每车每日次数不限，Q2 建议） |
+| BR-7 | 首小时段 | 15 < t ≤ 60 分钟 | 金额 5 元 |
+| BR-8 | 加时段 | t > 60 分钟 | 金额 = 5 + ⌈(t−60)/30⌉ × 2 元（不足 30 分钟按 30 分钟计，Q6 建议） |
+| BR-9 | 日封顶 | 单日应计金额上限 40 元；跨天按 Q1 建议口径：按 24 小时切片、每片独立计费并各自封顶 40 元后求和 | 超出封顶部分不计 |
+| BR-10 | 计费示例 | 见下方计费示例表（编码/测试共同对齐基准） | — |
+| BR-11 | 重复出场拦截 | 记录状态 = 已出场，或记录不存在 | 拒绝出场结算 |
+| BR-12 | 出场成功 | 结算完成 | 生成"待缴费"订单（含 duration、amount）；记录 → 已出场；泊位 → 空闲 |
+| BR-13 | 缴费幂等 | 订单状态 = 待缴费 → 缴费成功置已缴费；重复请求 | 幂等返回"订单已缴费"，不重复生成流水 |
+| BR-14 | 订单终态 | 已缴费/已免单为终态（题目明确"已缴费不可再改"；免单按终态处理，建议） | 任何修改缴费状态/金额的请求 → 拒绝 |
+| BR-15 | 免单 | 仅待缴费订单可免单；原因必填 | 原因为空 → 拒绝；成功后状态 → 已免单并保存原因 |
+| BR-16 | 超时未缴 | 出场时间距今 > 24 小时（Q7 建议）且订单仍待缴费 | 进入看板"超时未缴"清单 |
+| BR-17 | 金额异常 | 订单金额 > 40 元（超日封顶）或 ≤ 0 元（防御性） | 进入看板"金额异常"清单 |
+| BR-18 | 占用率 | 占用泊位数 ÷ 非停用泊位数（停用不计入分母，建议） | — |
+| BR-19 | 当日收入 | 当日已缴费订单金额求和，按**缴费时间**归属当天（建议） | 免单计 0 元 |
+| BR-20 | 停用泊位 | 停用仅拦截**新**进场 | 在场记录可正常出场结算（Q4 建议） |
+| BR-21 | 补录与修正 | 补录：车牌 + 过去时间 + 空闲泊位；修正：仅限"在场中"记录的车牌/进场时间 | 补录时间非法/泊位非空闲/记录已出场 → 拒绝 |
+
+### 计费示例表（BR-10，编码与测试必须逐行对齐）
+
+| 停车时长 | 应收金额 | 计算过程 |
+|---|---|---|
+| 10 分钟 | 0 元 | BR-6 免费段 |
+| 15 分钟 | 0 元 | 免费段上限（含 15） |
+| 16 分钟 | 5 元 | BR-7 首小时段 |
+| 60 分钟 | 5 元 | 首小时段上限 |
+| 61 分钟 | 7 元 | 5 + ⌈1/30⌉×2 |
+| 90 分钟 | 7 元 | 5 + ⌈30/30⌉×2 |
+| 91 分钟 | 9 元 | 5 + ⌈31/30⌉×2 = 5 + 2×2 |
+| 8 小时（480 分钟） | 33 元 | 5 + ⌈420/30⌉×2 = 5 + 14×2 |
+| 12 小时（720 分钟） | 40 元 | 理论 49 元 → 触发 BR-9 封顶 40 |
+| 25 小时（跨天） | 45 元 | 第 1 天封顶 40 + 第 2 天 60 分钟 5 元（Q1 建议口径） |
+
+> 需求侧提示：金额按整数分（或 BigDecimal）存储后，计费结果只会出现整数元（5、7、9 … 40）。题目测试建议中的"39.9 元与 40.1 元封顶临界"在本规则体系下等价于验证 **40 元封顶恰好生效、41 元不可能出现**；用例设计时请以"39 分 / 4001 分"思路构造防御性断言，而非期望系统产出非整数金额。
+
+## 8. 非功能需求（NFR）
+
+| 编号 | 类别 | 要求 |
+|---|---|---|
+| NFR-1 | 统一返回体 | 所有接口返回 `{code, message, data}`；业务失败 HTTP 400 + 业务码；未捕获异常 HTTP 500 |
+| NFR-2 | 金额精度 | 金额用整数分或 BigDecimal 存储与计算，**禁止 double** |
+| NFR-3 | 幂等 | 重复出场、重复缴费必须幂等拦截（状态判断 + 唯一约束兜底） |
+| NFR-4 | 性能 | 进场/出场/缴费接口响应 ≤ 2 秒；弱网（题目背景）下 ≤ 3 秒且前端有加载提示 |
+| NFR-5 | 合规 | 数据库口令等敏感信息走环境变量，不写死；演示数据车牌全部虚构脱敏；报告附 AI 使用声明 |
+| NFR-6 | 可复现 | 提供建表脚本与初始化数据；换一台电脑按 README 可启动 |
+| NFR-7 | 接口契约 | OpenAPI 文档先行；路径统一前缀 `/api`；错误码集中定义（见第 9 节） |
+| NFR-8 | 技术栈基线 | 后端 Java Spring Boot 3（JDK 17+）或 Python FastAPI；数据库 MySQL 8 或 SQLite；前端 Vue 3 + Element Plus 或原生 HTML + Fetch（现场可演示即可） |
+
+## 9. 错误码规划（建议，最终以编码阶段 openapi.json 为准）
+
+| 业务码 | 含义 | 触发场景示例 | 关联规则 |
+|---|---|---|---|
+| 0 | 成功 | — | — |
+| 1001 | 参数缺失/格式非法 | 车牌为空、车牌不是 7 位 | BR-1 |
+| 1002 | 泊位不存在 | 进场引用无效泊位 | BR-2 |
+| 1003 | 泊位已占用 | 对占用泊位进场 | BR-2 |
+| 1004 | 泊位已停用 | 对停用泊位进场 | BR-2 |
+| 1005 | 车辆已在场 | 同车牌重复进场 | BR-3 |
+| 2001 | 停车记录不存在 | 出场传入无效记录 ID | BR-11 |
+| 2002 | 重复出场 | 已出场记录再次结算 | BR-11 |
+| 3001 | 订单不存在 | 缴费/免单传入无效订单 ID | BR-13/15 |
+| 3002 | 订单已缴费（幂等命中） | 重复缴费请求 | BR-13 |
+| 3003 | 订单已终态不可变更 | 终态订单再修改 | BR-14 |
+| 3004 | 免单原因缺失 | 免单未填原因 | BR-15 |
+| 4001 | 看板查询参数错误 | 日期格式非法 | BR-19 |
+| 5001 | 补录参数非法 | 补录时间晚于当前、目标泊位非空闲 | BR-21 |
+
+### 题目建议接口清单（6 个）与补充建议
+
+题目建议的 6 个接口（必须覆盖）：
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | /api/spaces | 泊位列表（按路段筛选、分页） |
+| POST | /api/spaces | 新增泊位 |
+| POST | /api/records/entry | 进场登记（校验车牌与泊位状态） |
+| POST | /api/records/exit | 出场结算并生成订单 |
+| POST | /api/orders/{id}/pay | 缴费确认（幂等） |
+| GET | /api/dashboard | 看板统计 |
+
+**补充建议 3 个**（支撑必做功能但题目接口表未列，可合并实现，编码 Agent 定夺后回写本档与 openapi.json）：
+
+| 方法 | 路径（建议） | 支撑功能 | 说明 |
+|---|---|---|---|
+| POST | /api/spaces/import | FR-1 批量导入 | 也可设计为 POST /api/spaces 接受数组批量 |
+| POST | /api/orders/{id}/exempt | FR-5 免单 | 必做状态"已免单"的落点 |
+| POST / PUT | /api/records（补录）· /api/records/{id}（修正） | FR-6 | 人工补录与异常修正 |
+
+## 10. 待确认问题清单（组内评审逐条拍板）
+
+> 题目要求：先问、不要自行假设。下表 Q1~Q4 为题目指定必须澄清的问题，Q5~Q10 为需求分析中补充发现的。**拍板前按"建议口径"开发，拍板后立即回写本表与受影响的故事/规则。**
+
+| 编号 | 问题 | 建议口径（未拍板前按此开发） | 影响范围 | 状态 |
+|---|---|---|---|---|
+| Q1 ★ | 跨天停车如何计费？是否按天封顶叠加？ | 按 24 小时切片，每片独立计费并各自封顶 40 元后求和（25 小时 → 45 元） | US-3 / BR-9 / AC3.5 | 待拍板 |
+| Q2 ★ | 免费 15 分钟是否每车每日仅一次？ | 每次出场独立判定，不限次数（实现最简；若限次需加"车牌+当日"判定） | US-3 / BR-6 | 待拍板 |
+| Q3 ★ | 车牌识别是人工录入还是设备对接？ | 本期人工录入（题目建议） | US-2 | 待拍板 |
+| Q4 ★ | 停用泊位上的历史订单如何处理？ | 停用仅拦截新进场；在场记录可正常出场结算 | US-1/2/3 / BR-20 | 待拍板 |
+| Q5 | 新能源车牌（8 位）是否支持？ | 本期仅支持省份简称 + 6 位（共 7 位），8 位按格式非法拒绝并提示 | US-2 / BR-1 | 待拍板 |
+| Q6 | 加时段不足 30 分钟如何计？ | 向上取整为 30 分钟（收 2 元） | US-3 / BR-8 | 待拍板 |
+| Q7 | 超时未缴的阈值是多少小时？ | 出场后 24 小时 | US-6 / BR-16 | 待拍板 |
+| Q8 | 免单是否需要记录操作人与原因？ | 原因必填；操作人本期记录用户名（简化） | US-4 / BR-15 | 待拍板 |
+| Q9 | 已出场记录发现错录如何处理？ | 本期不允许修正已出场记录（订单已生成），线下处理 | US-5 / BR-21 | 待拍板 |
+| Q10 | 秒级时长如何取整？ | 向上取整到 1 分钟 | US-3 / BR-5 | 待拍板 |
+
+（★ = 题目指定的必问项）
+
+## 11. 需求评审与变更约定
+
+1. 组内评审会逐条过第 10 节 Q 表，结论当场填入"状态"列（改为：已拍板 × 结论摘要）。
+2. 编码阶段发现需求缺口：先在小组群提出，由需求 Agent 评估是否纳入本期；纳入则更新 FR/BR/US 并升版本号，**不允许**编码侧私自加字段改语义。
+3. 测试 Agent 的用例必须挂本档的 US 与 BR 编号；交付 Agent 的 README 功能清单逐条对应 FR 编号，保证"需求 → 代码 → 测试 → 文档"四层产物对得上（答辩自检三问之一）。

02-用户故事地图.md

@@ -0,0 +1,57 @@
+# 路侧停车泊位智能管理系统 · 用户故事地图
+
+> 配套文档：`01-需求文档.md`（用户故事全文与 GWT 验收标准）、`03-交接说明.md`（下游如何使用）。
+> 评分对照：本题对应考核项"需求文档与用户故事地图"——需求 Agent 产故事 + 画故事地图（角色 × 流程）。故事少于 5 条直接扣分，本组共 8 条。
+
+## 1. 参与角色
+
+| 角色 | 画像 | 触点与诉求 |
+|---|---|---|
+| 路段管理员（唯一业务角色） | 日常巡查一条或多条路段；现场用手机、回到岗亭/办公室用电脑；所在环境网络可能不稳定 | 手机端：快速登记进场、办理出场收款；电脑端：维护泊位档案、处理免单等异常、看经营看板 |
+
+> 本系统无司机端、无乘客端。司机全程不接触系统，所有操作由路段管理员完成。
+
+## 2. 主干业务流程（端到端闭环）
+
+```
+        ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐
+        │ 准备泊位 │ ───▶ │ 车辆进场 │ ───▶ │ 停车中  │ ───▶ │ 车辆出场 │ ───▶ │ 收费结算 │ ───▶ 经营分析
+        └─────────┘      └─────────┘      └─────────┘      └─────────┘      └─────────┘      └─────────┘
+        建档/导入/停用    验车牌/验泊位     泊位=占用        算时长/算钱      缴费/免单         占用率/收入/
+        （US-1）         拦重复进场       （系统自动）      生成待缴费订单   订单终态锁定      异常订单清单
+                         （US-2/US-5）                    （US-3）        （US-4）         （US-6~8）
+```
+
+一条完整故事线（演示/验收时可照此走）：
+管理员先把"人民路 001–010"泊位导入系统 → 车辆"京A12345"进场，001 变占用 → 停 61 分钟后出场，系统自动算出 7 元生成待缴费订单 → 司机扫码/现金付款，管理员点"缴费确认"，订单变已缴费 → 管理员打开看板看到人民路占用率与当日收入更新。
+
+## 3. 故事地图（阶段 × 活动 × 故事）
+
+| 流程阶段 | 用户活动（要做的事） | 用户故事 | 优先级 | 触点 | 交付形态 |
+|---|---|---|---|---|---|
+| ① 准备泊位 | 新增/修改/删除泊位；按路段批量导入；停用泊位 | US-1 | Must | 电脑后台 | 泊位档案列表 + 导入 |
+| ② 车辆进场 | 选泊位、录车牌、登记进场 | US-2 | Must | 手机/电脑 | 进场登记表单 |
+| ②′ 异常补救 | 漏登补录进场；修正错录车牌/时间 | US-5 | Should | 电脑后台 | 补录与修正入口 |
+| ③ 停车中 | （系统自动维护泊位占用状态，无人工操作） | — | — | — | 泊位状态实时可见 |
+| ④ 车辆出场 | 对在场记录执行出场结算，系统算时长与金额、生成订单 | US-3 | Must | 手机/电脑 | 出场结算页 |
+| ⑤ 收费结算 | 缴费确认（幂等）；免单（必填原因）；终态锁定 | US-4 | Must | 手机/电脑 | 订单操作入口 |
+| ⑥ 经营分析 | 查看各路段占用率、当日收入、超时未缴与金额异常清单 | US-6 | Must | 电脑后台 | 经营看板 |
+| ⑥′ 经营分析增强 | 泊位占用一屏可视化；按周收入趋势 | US-7 / US-8 | Could（加分项） | 电脑后台 | 看板增强视图 |
+
+## 4. 发布切分建议（对应 2 周实训节奏）
+
+| 批次 | 包含故事 | 判定标准（Definition of Done） |
+|---|---|---|
+| MVP（第 3–6 天编码目标） | US-1、US-2、US-3、US-4、US-6（全部 Must） | 主干流程端到端可跑通：建档 → 进场 → 出场 → 缴费/免单 → 看板；对应验收标准全部通过；幂等与拦截规则生效 |
+| 第二批（时间富余再做） | US-5（Should） | 补录与修正可用，且不破坏已结算订单 |
+| 增强（加分项，可裁剪） | US-7、US-8（Could） | 演示效果加分，不影响主干 |
+
+## 5. 故事地图 × 排期对照
+
+| 阶段（题目 8.3 节奏） | 工作 | 本地图对应 |
+|---|---|---|
+| 第 1–2 天 | 选题确认、需求拆解、用户故事与验收标准 | 本文件 + 01-需求文档；Q1~Q10 拍板 |
+| 第 3–6 天 | 数据模型、后端接口、前端页面 | MVP 批次故事 |
+| 第 7–8 天 | 用例设计、Apifox 执行、缺陷回流 | 用例挂 US/BR 编号（见 03-交接说明） |
+| 第 9–10 天 | 交付文档包、演示材料、报告 | README 功能清单挂 FR 编号 |
+| 答辩日 | 现场演示 + 分工阐述 | 按第 2 节"故事线"走 8 分钟演示脚本 |

03-交接说明.md

@@ -0,0 +1,151 @@
+# 交接说明：需求产出 → 编码 / 测试 / 交付
+
+> 交接人：需求 Agent（安梓骏）　日期：2026-09-17
+> 本文件告诉你：拿到什么、先看哪份、怎么用、哪些事必须先拍板。
+
+## 0. 一页速览
+
+| 你是 | 先读 | 你要从需求档拿走什么 | 硬约束 |
+|---|---|---|---|
+| 编码 Agent | 01 §5~§9 | FR 清单、用户故事验收标准、BR 规则表、计费示例表、错误码规划、数据模型与接口建议 | 计费逐条对应 BR/示例表；金额禁 double；幂等必须有 |
+| 测试 Agent | 01 §6~§7、§10 | GWT 验收标准（用例直接从这反推）、BR 规则表、必测边界清单（本文 §3） | 每条用例挂 US 与 BR 编号；业务码断言而非只看 HTTP 200 |
+| 交付 Agent | 01 §5、02 §4 | FR 清单（README 功能清单逐条挂 FR 编号）、发布切分、演示故事线 | README 功能数 = 接口文档接口数；文档字段以代码/openapi.json 为准 |
+| 全体 | 01 §10 | 待确认问题 Q1~Q10 | **评审会先拍板再大规模编码** |
+
+## 1. 建议数据模型（题目建议 4 张表，需求侧细化）
+
+> 字段名是**建议**，编码 Agent 可微调；但语义不得偏离 01-需求文档的 BR 规则，若改动需回写需求档。
+
+**parking_lot（泊位）**
+
+| 字段 | 类型建议 | 说明 |
+|---|---|---|
+| id | 主键 | — |
+| road_name | varchar | 路段名 |
+| space_no | varchar | 泊位编号，同路段唯一（唯一索引 road_name + space_no，AC1.3） |
+| space_type | 枚举 | 标准 / 无障碍（AC1.5） |
+| status | 枚举 | 空闲 / 占用 / 停用 |
+
+**parking_record（在场记录）**
+
+| 字段 | 类型建议 | 说明 |
+|---|---|---|
+| id | 主键 | — |
+| space_id | 外键 | 关联泊位 |
+| plate_no | varchar(8) | 车牌（省份汉字 + 6 位） |
+| entry_time | datetime | 进场时间（补录可填过去时间，BR-21） |
+| exit_time | datetime null | 出场时间，null = 在场中 |
+| status | 枚举 | 在场中 / 已出场 |
+
+**parking_order（订单）**
+
+| 字段 | 类型建议 | 说明 |
+|---|---|---|
+| id | 主键 | — |
+| record_id | 外键 | **唯一索引**（一个记录只出一笔订单，重复出场兜底，NFR-3） |
+| duration_minutes | int | 停车时长（分钟，BR-5） |
+| amount | int / decimal | 金额（整数分或 BigDecimal，NFR-2） |
+| pay_status | 枚举 | 待缴费 / 已缴费 / 已免单（BR-14 终态） |
+| exempt_reason | varchar null | 免单原因（BR-15 必填） |
+| pay_time | datetime null | 缴费时间（BR-19 当日收入归属依据） |
+| created_at | datetime | — |
+
+**fee_rule（可选）**：`id、free_minutes、first_hour_fee、step_fee、daily_cap`。本期规则可先用常量类实现（注释标 US-3）；做 fee_rule 表属配置化增强，非必须。
+
+**防重与幂等三要点（编码必做）**
+
+1. 重复进场：进场前查 `plate_no + status=在场中` 记录（BR-3，应用层校验）。
+2. 重复出场：`parking_order.record_id` 唯一约束兜底 + 记录状态判断（BR-11）。
+3. 重复缴费：订单状态判断 + 缴费动作幂等返回"已缴费"（BR-13，业务码 3002）。
+
+## 2. 建议接口清单（题目 6 个 + 需求侧补充 3 个）
+
+以 01-需求文档 §9 表格为准。补充接口（import / exempt / records 补录修正）可合并实现，**编码 Agent 定稿后以 openapi.json 为唯一契约**，并回写需求档 §9。
+
+## 3. 给测试 Agent：必测边界预告
+
+来自题目要求 + 需求分析补充，设计用例时逐条覆盖，每条挂 US/BR 编号：
+
+| # | 边界/异常场景 | 依据 | 预期（按建议口径） |
+|---|---|---|---|
+| 1 | 出场时间等于进场时间（0 分钟） | BR-5/6 | 金额 0 元，正常出单 |
+| 2 | 恰好 15 分钟 | BR-6 | 0 元（免费上限含 15） |
+| 3 | 16 分钟 / 恰好 60 分钟 | BR-7 | 5 元 / 5 元 |
+| 4 | 90 / 91 分钟（步长进位） | BR-8 | 7 元 / 9 元 |
+| 5 | 跨天停车（25 小时） | BR-9 + Q1 | 45 元（按天切片叠加封顶） |
+| 6 | 日封顶临界：12 小时理论 49 元 | BR-9 | 实收 40 元；40 以上不可能出现（对应题目"39.9/40.1"边界，整数分体系下等价改写，见 01 §7 提示） |
+| 7 | 重复出场（同记录二次结算） | BR-11 | 拦截，业务码 2002 |
+| 8 | 重复缴费（幂等） | BR-13 | 幂等返回"已缴费"，业务码 3002，不重复计费 |
+| 9 | 车牌格式不合法（空 / 6 位 / 8 位新能源 / 带特殊字符） | BR-1 + Q5 | 拒绝，业务码 1001 |
+| 10 | 停用泊位进场 | BR-2 + Q4 | 拒绝，业务码 1004 |
+| 11 | 占用泊位进场 / 同车重复进场 | BR-2/3 | 拒绝，业务码 1003 / 1005 |
+| 12 | 已缴费订单再缴费/再免单/改金额 | BR-14 | 拒绝，业务码 3003 |
+| 13 | 免单原因为空 | BR-15 | 拒绝，业务码 3004 |
+| 14 | 补录时间晚于当前 / 目标泊位非空闲 / 修正已出场记录 | BR-21 + Q9 | 拒绝，业务码 5001 或对应码 |
+| 15 | 看板空数据 | AC6.2 | 返回空集/0 值，不报错 |
+
+Apifox 流程提醒（题目要求）：导入 OpenAPI → 造 Mock 数据（自定义车牌规则）→ 编排测试场景（进场→出场→缴费全链路一条场景）→ 批量执行 → 导出报告。**断言校验业务码，不要只看 HTTP 200**；并发/幂等类用例用"连发两次"验证。
+
+## 4. 给交付 Agent：一致性自查表
+
+| 检查项 | 通过标准 |
+|---|---|
+| README 功能清单 | 逐条挂 FR 编号（FR-1~FR-9），功能数 = 接口文档接口数口径一致 |
+| 接口文档 | 以 openapi.json 为准；错误码表与 01 §9 对齐（编码若改码值，以代码为准并回写需求档） |
+| 部署手册 | 依赖清单 = 构建文件声明；不确定版本标"待核实"；数据库口令走环境变量 |
+| 演示脚本（8 分钟） | 按 02 §2 故事线：导入泊位 → 进场（演一个拦截）→ 出场看计费 → 缴费 → 看板（指出超时未缴清单） |
+| 报告需求分析章节 | 直接复用 01 的用户故事与验收标准、02 的故事地图 |
+
+## 5. 需求 Agent 提示词工程记录（供报告"多 Agent 协同说明"引用）
+
+> 评分要求"提示词工程：保留优化前后两次产出对比"。以下是本环节实际使用的两版提示词与差异说明。
+
+**v1（题目原始提示词，3.4 节第一步）**
+
+```
+【角色】你是资深需求分析师。
+【背景】城市路侧停车运营方要上线泊位管理与计费系统，使用者是路段管理员，
+现场用手机或后台电脑操作，网络可能不稳定。
+【任务】把上面的功能范围拆成不少于 5 条用户故事，符合 INVEST，
+格式为「作为……我希望……以便……」；每条附 Given-When-Then 验收标准，
+覆盖正常、边界、异常；再按 MoSCoW 排优先级。
+【约束】只做本期 4 个模块；不要发明需求外的功能（如无感支付、车牌识别对接）；
+不确定处单独列「待确认问题」。
+```
+
+**v1 产出问题**（人工观察）：故事粒度不齐（把"计费规则"与"出场结算"混在一条）；部分 GWT 只写了正常路径；待确认问题直接替用户做了假设。
+
+**v2（在 v1 基础上追加约束，即本组最终使用版本）**
+
+```
+【追加约束】
+1. 用户故事按模块拆分，一条故事只落一个模块的一个动作簇，编号 US-n；
+2. 每条故事的 GWT 验收标准必须同时覆盖 正常≥1 / 边界≥1 / 异常≥1，编号 AC-n.m；
+3. 把"阶梯计费、幂等、状态终态、拦截规则"全部抽成独立的业务规则清单（BR-n：
+   规则名 / 判断条件 / 违反时的行为），GWT 引用 BR 编号，不许把规则藏在故事正文里；
+4. 附一张计费示例表（≥10 行，含 15/16/60/61/90/91 分钟与跨天、封顶临界），
+   作为编码与测试的共同对齐基准；
+5. 待确认问题只列问题 + 影响范围 + 建议口径，禁止替业务方拍板；
+6. 输出三份：需求文档、用户故事地图（角色×流程+发布切分）、下游交接说明。
+```
+
+**v2 相比 v1 的改进**：规则显式化（BR 表）→ 测试可逐条对照；计费示例表 → 编码/测试口径统一；待确认问题强制"建议而非拍板" → 符合题目"先问不要自行假设"；故事粒度按模块对齐 → 故事地图可画、可排期。
+
+## 6. 人工核对记录与 AI 使用声明（模板，答辩前填签名）
+
+| 环节 | AI 做了什么 | 人工做了什么核对与修改 |
+|---|---|---|
+| 需求拆解 | 按 v2 提示词生成用户故事初稿与 BR 规则初稿 | 逐条核对题目必做功能清单，补入"免单属必做"的判断；把加分项降级为 Could |
+| 计费规则 | 生成阶梯计费与示例表 | 人工验算全部 10 行示例金额；发现题目"39.9/40.1 元"边界在整数分体系下不可达，改写为封顶生效验证并在文档中说明 |
+| 待确认问题 | 初筛 | 人工补充 Q5（新能源车牌）、Q9（已出场记录修正）、Q10（秒取整） |
+| 交接文档 | 汇总生成 | 人工复核接口建议与题目接口表的一致性，补充 3 个接口标注为"补充建议" |
+
+## 7. 待确认问题跟踪表（评审会现场填写）
+
+复制 01-需求文档 §10 的 Q1~Q10 表，评审会逐条把"状态"改为结论。**Q1（跨天计费）与 Q2（免费次数）直接影响金额计算，必须最先拍板**，否则编码与测试会对不上。
+
+## 8. 遗留风险提示
+
+1. **车牌校验口径**：题目只写"省份简称 + 6 位"，未说是否排除字母 I/O、是否校验发牌机关位。需求按宽松口径（汉字 + 6 位字母数字），若答辩被追问按 Q5 口径回答"本期宽松校验，收紧属一期增强"。
+2. **并发场景弱于题目四**：本题并发点只有重复进场/重复出场/重复缴费三处，用"状态判断 + 唯一约束"即可，不要过度引入分布式锁（不发明需求外复杂度）。
+3. **看板"当日收入"口径**：跨天订单按缴费时间归属（BR-19 建议），若评审另有决定，测试用例第 5 条要同步改。