sankey/IMPLEMENTATION_PLAN.md

IMPLEMENTATION_PLAN.md

1. 目的

将 PRD 的需求拆为可执行、可验证的小步任务，减少实现时猜测。

关联文档：

• PRD.md
• APP_FLOW.md
• TECH_STACK.md
• FRONTEND_GUIDELINES.md
• BACKEND_STRUCTURE.md

2. 里程碑视图

• M1：工程与核心数据层
• M2：Web 交互与图表预览
• M3：导出与体验增强
• M4：质量门禁与文档闭环
• M5：小程序从骨架到可用

3. 详细步骤

M1 工程与核心数据层

• 1.1 初始化 Vue + TS + Vite 工程
• 1.2 按 TECH_STACK 安装依赖并配置脚本
• 1.3 建立 src/core 模块边界
• 1.4 实现 CSV 解析为 RawTable
• 1.5 实现 XLS/XLSX 解析为 RawTable
• 1.6 实现 MappingConfig 与 SankeyBuildResult 类型
• 1.7 实现 target 向下补全 + 聚合算法
• 1.8 覆盖核心单元测试

验收命令：

• npm run test

M2 Web 交互与图表预览

• 2.1 实现主页面结构（头部、左侧、预览）
• 2.2 实现文件点击上传
• 2.3 实现拖拽上传
• 2.4 实现 source/target 列映射交互
• 2.5 建立实时重算机制（watchEffect）
• 2.6 接入 ECharts Sankey 渲染
• 2.7 支持方向切换
• 2.8 支持 gap/padding 调节
• 2.9 支持主题选择器与配色应用
• 2.10 增加错误与告警展示
• 2.11 首次加载默认样例文件

验收命令：

• npm run type-check
• npm run lint

M3 导出与体验增强

• 3.1 实现 SVG 导出（DOM 序列化优先）
• 3.2 实现 PNG 导出（pixelRatio=2）
• 3.3 统一导出命名规则（时间戳）
• 3.4 增加目标总和显示开关

验收清单：

• 本地下载文件可打开
• 命名格式符合约定

M4 质量门禁与文档闭环

• 4.1 建立/维护测试命令
• 4.2 建立/维护 lint 与 type-check 门禁
• 4.3 补充 README 与规划文档
• 4.4 补充本轮知识库文档（PRD/Flow/Stack/Guidelines/Backend/Plan）
• 4.5 更新会话记忆文件 progress.txt

验收命令：

• npm run test
• npm run type-check
• npm run lint
• npm run format

M5 小程序从骨架到可用

• 5.1 接入文件上传能力（csv/xls/xlsx）
• 5.2 对齐 Web 聚合规则（默认映射、向下补全、告警）
• 5.3 接入小程序原生 canvas 预览容器
• 5.4 接入导出能力（PNG 到相册、SVG 文件导出）
• 5.5 建立小程序端测试与验收用例（待补）

4. 每次迭代执行模板

1. 从 progress.txt 读取上下文
2. 选择一个最小可交付任务
3. 实现并补充/更新测试
4. 运行质量命令
5. 更新 progress.txt 与相关规范文档

5. 变更控制

• 任何超出 PRD 范围的能力，先改 PRD，再改计划。
• 任何新增依赖，先确认，再更新 TECH_STACK。