sankey/BACKEND_STRUCTURE.md

BACKEND_STRUCTURE.md

1. 当前结论（v0.1）

当前项目为纯前端本地处理架构：

• 无后端服务
• 无数据库
• 无认证系统
• 无远程 API

这不是遗漏，而是产品范围定义（见 PRD.md 的 Non-Goals）。

2. 数据处理位置

所有数据处理均在客户端完成：

• 文件解析：src/core/parser.ts
• 聚合构建：src/core/sankey.ts
• 状态承载：
  • Web：src/App.vue（响应式状态 + localStorage 持久化）
  • 小程序：miniapp/pages/index/index.js（页面状态）
• 小程序端聚合与解析：miniapp/utils/sankey.js

3. 当前“数据结构合同”

虽然没有数据库，但有稳定的数据结构合同。

3.1 RawTable

interface RawTable {
  headers: string[];
  rows: string[][];
}

3.2 MappingConfig

interface MappingConfig {
  sourceDataColumn: number | null;
  sourceDescriptionColumns: number[];
  targetDescriptionColumns: number[];
  delimiter: string;
}

3.3 SankeyBuildResult

interface SankeyBuildResult {
  nodes: Array<{ name: string; kind: 'source' | 'target' }>;
  links: Array<{ source: string; target: string; value: number }>;
  meta: {
    droppedRows: number;
    warnings: string[];
  };
}

4. 存储规则

• Web：
  • 映射配置与上传文件快照持久化到 localStorage（刷新可恢复）。
  • 导出结果通过浏览器下载能力交付给用户。
• 小程序：
  • 页面状态在当前会话内存中维护（当前未做本地持久化恢复）。
  • PNG 导出保存到系统相册；SVG 导出写入用户数据目录文件。

5. 认证与权限

• 当前不存在用户登录、权限校验、租户隔离。
• 所有用户在本地环境有相同行为能力。

6. API 合约

• 当前无 HTTP API。
• 唯一远程读取是静态样例文件：GET /data/example0.xlsx（同站静态资源，不是业务 API）。

7. 边界与异常处理

• 文件类型不支持：直接抛错并提示。
• 解析错误：保留页面可操作状态，允许重新上传。
• 聚合错误：展示错误信息，不产生图表。
• 行级数据问题：通过 warning 列表给出行号并跳过坏行。

8. 未来后端接入约束（预留）

仅当 PRD 明确扩展范围（账号、云保存、协作）时，才允许新增后端。届时必须先补充：

1. 数据库表结构（表、字段、类型、索引、关系）
2. API OpenAPI 合约
3. 认证模型（会话、令牌、权限）
4. 存储策略（文件与图快照）

在 PRD 未变更前，禁止实现任何后端功能。