cas / fw-pms-ai

tasks.md 9.01 KB

实现计划：重构分析报告功能

概述

全栈重构分析报告功能，从清理现有代码开始，依次重建数据库表、数据模型、统计计算、LLM 提示词、并发节点、API 接口、前端页面。使用 Python + LangGraph + FastAPI + Chart.js 技术栈。

任务

  • 1. 清理现有分析报告专属文件

    • 1.1 清空 src/fw_pms_ai/models/analysis_report.py，仅保留文件头注释和必要 import，移除现有 AnalysisReport dataclass 的所有字段和方法
    • 1.2 清空 src/fw_pms_ai/agent/analysis_report_node.py，仅保留文件头注释和必要 import，移除 _load_prompt、_calculate_suggestion_stats、_calculate_risk_stats、_build_suggestion_summary、generate_analysis_report_node 等所有函数
    • 1.3 清空 prompts/analysis_report.md 的内容
    • 注意：此步骤仅清理分析报告专属文件，不修改 tasks.py、app.js、result_writer.py 等共享文件（这些文件中的报告相关代码将在后续重建步骤中以替换方式更新）
    • Requirements: 1.1, 1.2, 1.3, 1.5

  • 2. 重建数据库表和数据模型

    • 2.1 重写 sql/migrate_analysis_report.sql，创建新表结构（inventory_overview、sales_analysis、inventory_health、replenishment_summary 四个 JSON 字段 + LLM 元数据字段）
    • Requirements: 6.1, 6.2, 6.3, 6.4, 6.5
    • 2.2 在已清空的 src/fw_pms_ai/models/analysis_report.py 中编写新的 AnalysisReport dataclass（四个 Dict 字段 + to_dict 方法）
    • Requirements: 10.1, 10.3
    • 2.3 替换 src/fw_pms_ai/services/result_writer.py 中的 save_analysis_report 方法为新版本，适配新表结构（四个 JSON 字段序列化写入），不修改该文件中的其他方法
    • Requirements: 10.2
    • [ ]* 2.4 编写属性测试：报告数据模型序列化 round-trip
    • Property 5: 报告数据模型序列化 round-trip
    • Validates: Requirements 10.2, 10.3

  • 3. 实现四大板块统计计算函数

    • 3.1 在已清空的 src/fw_pms_ai/agent/analysis_report_node.py 中实现 calculate_inventory_overview(part_ratios) 函数
    • 计算有效库存（valid_storage_cnt = in_stock_unlocked_cnt + on_the_way_cnt + has_plan_cnt）总数量/总金额、三项构成明细、库销比
    • Requirements: 2.1, 2.2, 2.3, 2.5
    • 3.2 实现 calculate_sales_analysis(part_ratios) 函数
    • 计算月均销量总数量/总金额、各组成部分（out_stock_cnt/storage_locked_cnt/out_stock_ongoing_cnt/buy_cnt）总量、有销量/无销量配件数
    • Requirements: 3.1, 3.2, 3.4
    • 3.3 实现 calculate_inventory_health(part_ratios) 函数
    • 将配件分类为缺货/呆滞/低频/正常，计算各类型数量/金额/百分比，生成 chart_data
    • Requirements: 4.1, 4.2
    • 3.4 实现 calculate_replenishment_summary(part_results) 函数
    • 按优先级（1=急需/2=建议/3=可选）统计配件种类数和金额
    • Requirements: 5.1, 5.2
    • [ ]* 3.5 编写属性测试：库存概览统计一致性
    • Property 1: 库存概览统计一致性
    • Validates: Requirements 2.1, 2.2, 2.3
    • [ ]* 3.6 编写属性测试：销量分析统计一致性
    • Property 2: 销量分析统计一致性
    • Validates: Requirements 3.1, 3.2, 3.4
    • [ ]* 3.7 编写属性测试：健康度分类完备性与一致性
    • Property 3: 健康度分类完备性与一致性
    • Validates: Requirements 4.1, 4.2
    • [ ]* 3.8 编写属性测试：补货建议统计一致性
    • Property 4: 补货建议统计一致性
    • Validates: Requirements 5.1, 5.2

  • 4. Checkpoint - 确保统计计算函数和属性测试通过

    • 确保所有测试通过，如有问题请向用户确认。

  • 5. 创建 LLM 提示词文件

    • 5.1 创建 prompts/report_inventory_overview.md，包含库存概览分析提示词（资金占用评估、库销比诊断、库存结构建议），确保分析专业且有实际决策价值
    • Requirements: 7.2
    • 5.2 创建 prompts/report_sales_analysis.md，包含销量分析提示词（销量构成解读、销售活跃度、需求趋势判断），确保分析专业且有实际决策价值
    • Requirements: 7.2
    • 5.3 创建 prompts/report_inventory_health.md，包含健康度分析提示词（健康度评分、问题诊断、资金释放机会、改善优先级），确保分析专业且有实际决策价值
    • Requirements: 7.2
    • 5.4 创建 prompts/report_replenishment_summary.md，包含补货建议分析提示词（紧迫度评估、资金分配建议、执行节奏、风险提示），确保分析专业且有实际决策价值
    • Requirements: 7.2
    • 5.5 删除旧的 prompts/analysis_report.md 文件（已在步骤1.3清空，此处正式删除）
    • Requirements: 1.3

  • 6. 实现 LangGraph 并发 LLM 分析节点

    • 6.1 在 src/fw_pms_ai/agent/analysis_report_node.py 中实现四个 LLM 分析函数（llm_analyze_inventory_overview、llm_analyze_sales、llm_analyze_inventory_health、llm_analyze_replenishment_summary），每个函数加载对应提示词、填充统计数据、调用 LLM、解析 JSON 响应
    • Requirements: 7.2, 7.3
    • 6.2 使用 LangGraph StateGraph 构建并发子图，四个 LLM 节点从 START fan-out 并发执行，结果 fan-in 汇总
    • Requirements: 7.1, 7.4
    • 6.3 实现新的 generate_analysis_report_node(state) 主函数，串联统计计算 → 并发 LLM 分析 → 汇总报告 → 写入数据库，单板块 LLM 失败不影响其他板块
    • Requirements: 7.4, 7.5
    • 6.4 确认 src/fw_pms_ai/agent/replenishment.py 中的工作流引用无需修改（generate_analysis_report_node 函数签名保持不变）
    • Requirements: 7.1

  • 7. Checkpoint - 确保后端报告生成流程完整

    • 确保所有测试通过，如有问题请向用户确认。

  • 8. 重建 API 接口

    • 8.1 替换 src/fw_pms_ai/api/routes/tasks.py 中的 AnalysisReportResponse 模型为新版本（inventory_overview、sales_analysis、inventory_health、replenishment_summary 四个 Dict 字段），不修改该文件中的其他模型和端点
    • Requirements: 8.1
    • 8.2 替换 get_analysis_report 端点实现，从新表读取数据并解析 JSON 字段，不修改该文件中的其他端点
    • Requirements: 8.1, 8.2, 8.3

  • 9. 重建前端报告页面

    • 9.1 在 ui/index.html 中引入 Chart.js CDN
    • Requirements: 9.6
    • 9.2 替换 ui/js/app.js 中的 renderReportTab 方法为新版本，渲染四大板块框架，同时移除旧的 renderOverallAssessment、renderRiskAlerts、renderStrategy、renderExpectedImpact 方法，不修改该文件中的其他方法
    • Requirements: 9.1, 1.4
    • 9.3 实现 renderInventoryOverview 方法，渲染库存概览板块（统计卡片 + 五项构成明细 + LLM 分析文本）
    • Requirements: 9.2
    • 9.4 实现 renderSalesAnalysis 方法，渲染销量分析板块（统计卡片 + 构成明细 + LLM 分析文本）
    • Requirements: 9.3
    • 9.5 实现 renderInventoryHealth 方法，渲染健康度板块（统计卡片 + Chart.js 环形图 + LLM 分析文本）
    • Requirements: 9.4, 9.6
    • 9.6 实现 renderReplenishmentSummary 方法，渲染补货建议板块（优先级统计表 + LLM 分析文本）
    • Requirements: 9.5
    • 9.7 在 ui/css/style.css 中添加新报告板块的样式（统计卡片、图表容器、分析文本区域），不修改现有样式
    • Requirements: 9.1

  • 10. Final Checkpoint - 全栈集成验证

    • 确保所有测试通过，如有问题请向用户确认。

安全约束：不影响补货建议功能

本次重构严格限定在分析报告模块范围内，以下补货建议相关代码禁止修改：

  • src/fw_pms_ai/agent/nodes.py — 补货建议核心节点（fetch_part_ratio、sql_agent、allocate_budget）
  • src/fw_pms_ai/agent/replenishment.py — 补货建议工作流（仅确认无需修改，不做任何改动）
  • src/fw_pms_ai/agent/sql_agent/ — SQL Agent 目录
  • src/fw_pms_ai/models/part_ratio.py — 配件库销比模型
  • src/fw_pms_ai/models/replenishment_*.py — 补货建议相关模型
  • result_writer.py 中的 save_task、update_task、save_details、save_part_summaries、save_execution_log 等方法
  • tasks.py 中的任务列表、任务详情、配件明细、配件汇总、执行日志等端点
  • app.js 中的任务列表、任务详情、配件明细等渲染方法
  • prompts/ 中的 part_shop_analysis*.md、suggestion*.md、sql_agent.md 等提示词文件

备注

  • 标记 * 的任务为可选任务，可跳过以加快 MVP 进度
  • 每个任务引用了具体的需求编号以保证可追溯性
  • 属性测试使用 hypothesis 库，每个属性至少 100 次迭代
  • Checkpoint 用于阶段性验证，确保增量正确
  • 共享文件（tasks.py、app.js、result_writer.py、style.css）中的修改均采用"替换特定函数/类"方式，明确不修改其他部分