# 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
```ts
interface RawTable {
  headers: string[];
  rows: string[][];
}
```

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

### 3.3 SankeyBuildResult
```ts
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 未变更前，禁止实现任何后端功能。