# 主力资金动向需求文档

## 1. 项目目标

建设一个“主力资金动向”模块，用于接收用户上传的资金流向截图，调用 Kimi 多模态模型进行识别，生成结构化数据，并在人工校对后保存到数据库中。

该模块分为两部分：

1. 列表查询页
2. 新增/识别/校对/保存页

本阶段以数据库存储为准，不再使用 JSON 作为正式业务存储。

## 2. 业务背景

当前无法直接依赖 Wind API 获取相关数据，因此改为通过截图识别的方式采集“主力资金动向”数据。

识别链路要求如下：

1. 用户上传图片
2. 后端调用 Kimi 进行视觉识别
3. 模型返回结构化识别结果
4. 前端展示识别结果供用户人工校对
5. 用户确认或修改后点击保存
6. 数据写入数据库

说明：

1. 每个交易日只生成一条记录
2. 图片需要保留原始文件，支持列表点击查看详情
3. `intraday_summary` 只描述日内资金走势，不重复金额字段

## 3. 功能范围

### 3.1 列表页

列表页用于查看已保存的“主力资金动向”记录。

列表字段包括：

1. 日期
2. 机构资金
3. 主力资金
4. 大户资金
5. 散户资金
6. 走势
7. 总结
8. 图片详情入口

列表能力要求：

1. 支持按日期倒序展示
2. 支持点击某一行查看详情
3. 支持点击图片或详情按钮查看原图
4. 默认一页展示最近记录

### 3.2 新增页

新增页用于生成并保存当日记录。

页面交互流程：

1. 用户点击“新增”
2. 选择并上传图片
3. 后端调用 Kimi 识别
4. 前端展示识别结果
5. 用户可手动修改识别结果
6. 用户点击“保存”
7. 后端进行唯一性校验并写入数据库

新增页展示字段：

1. 日期
2. 机构资金
3. 主力资金
4. 大户资金
5. 散户资金
6. 走势
7. 总结
8. 原始图片预览

### 3.3 详情页

详情页用于查看某日记录完整内容。

详情页内容包括：

1. 原图
2. 日期
3. 机构资金
4. 主力资金
5. 大户资金
6. 散户资金
7. 走势
8. 总结
9. 创建时间
10. 更新时间

## 4. 业务规则

### 4.1 唯一性规则

同一个日期只允许存在一条正式记录。

处理策略建议：

1. 保存时按 `trade_date` 做唯一校验
2. 若当天数据已存在，则提示“该日期记录已存在”
3. 后续如需要覆盖更新，可增加“编辑”模式，不在本期范围内默认覆盖

### 4.2 识别规则

Kimi 识别后返回字段：

1. `trade_date`
2. `subject`
3. `snapshot_time`
4. `main_force_amount_yi`
5. `institution_amount_yi`
6. `large_household_amount_yi`
7. `retail_amount_yi`
8. `overall_trend`
9. `intraday_summary`

识别要求：

1. 金额字段单独存储
2. 总结只描述走势，不重复罗列金额
3. 如果图片中未显示日期，则允许前端人工填写
4. 如果识别结果不准确，用户可直接修改后再保存

### 4.3 图片存储规则

1. 原图必须保存
2. 数据库中保存图片访问路径
3. 后续列表和详情页通过路径展示图片

## 5. 前端需求

### 5.1 页面结构

主力资金动向模块包括：

1. 列表页
2. 新增弹窗或新增页面
3. 图片详情预览能力

### 5.2 列表页交互

页面顶部：

1. 模块标题：“主力资金动向”
2. 新增按钮

页面主体：

1. 表格展示历史记录
2. 每行可查看图片详情
3. 每行可点击进入详情

建议字段顺序：

1. 日期
2. 机构资金
3. 主力资金
4. 大户资金
5. 散户资金
6. 走势
7. 总结
8. 图片详情

### 5.3 新增页交互

新增页流程：

1. 上传图片
2. 点击“识别”
3. 等待 Kimi 返回结果
4. 展示识别结果表单
5. 用户人工修正
6. 点击“保存”

新增页按钮建议：

1. 上传图片
2. 开始识别
3. 保存
4. 取消

状态要求：

1. 识别中需要显示加载状态
2. 识别失败时需要显示错误提示
3. 保存成功后返回列表并刷新

## 6. 后端需求

### 6.1 接口设计

建议后端提供以下接口：

1. `GET /api/main-capital-flows`
   用于获取列表数据

2. `GET /api/main-capital-flows/{id}`
   用于获取详情数据

3. `POST /api/main-capital-flows/recognize`
   用于上传图片并调用 Kimi 识别，返回识别结果，但不落正式业务表

4. `POST /api/main-capital-flows`
   用于保存经人工确认后的正式数据

5. `GET /main-capital-flow-images/{filename}`
   用于访问原图

### 6.2 后端处理流程

识别接口：

1. 接收图片
2. 保存临时图片
3. 调用 Kimi
4. 解析模型返回 JSON
5. 返回给前端展示

保存接口：

1. 接收前端确认后的字段
2. 校验日期是否已存在
3. 保存原图路径和业务数据
4. 返回保存结果

## 7. 数据库设计

建议建立表：`main_capital_flow`

字段设计如下：

1. `id`
   主键，自增或 UUID

2. `trade_date`
   交易日期，`DATE`，唯一

3. `subject`
   标的名称，`VARCHAR(64)`，可为空

4. `snapshot_time`
   图片中截图时间，`VARCHAR(16)`，可为空

5. `institution_amount_yi`
   机构资金，`DECIMAL(12,2)`，可为空

6. `main_force_amount_yi`
   主力资金，`DECIMAL(12,2)`，可为空

7. `large_household_amount_yi`
   大户资金，`DECIMAL(12,2)`，可为空

8. `retail_amount_yi`
   散户资金，`DECIMAL(12,2)`，可为空

9. `overall_trend`
   整体走势，`VARCHAR(64)`，可为空

10. `intraday_summary`
    日内走势总结，`TEXT`

11. `image_path`
    图片路径，`VARCHAR(255)`

12. `image_name`
    图片原始名称，`VARCHAR(255)`

13. `created_at`
    创建时间，`DATETIME`

14. `updated_at`
    更新时间，`DATETIME`

建议索引：

1. `UNIQUE KEY uk_trade_date (trade_date)`
2. `KEY idx_created_at (created_at)`

建议建表 SQL：

```sql
CREATE TABLE main_capital_flow (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  trade_date DATE NOT NULL,
  subject VARCHAR(64) NULL,
  snapshot_time VARCHAR(16) NULL,
  institution_amount_yi DECIMAL(12,2) NULL,
  main_force_amount_yi DECIMAL(12,2) NULL,
  large_household_amount_yi DECIMAL(12,2) NULL,
  retail_amount_yi DECIMAL(12,2) NULL,
  overall_trend VARCHAR(64) NULL,
  intraday_summary TEXT NOT NULL,
  image_path VARCHAR(255) NOT NULL,
  image_name VARCHAR(255) NOT NULL,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY uk_trade_date (trade_date),
  KEY idx_created_at (created_at)
);
```

## 8. 非功能要求

1. 识别结果返回时间尽量控制在 10 到 60 秒内
2. 图片原图必须可追溯
3. 保存前必须支持人工校正
4. 保存接口必须防止重复日期写入
5. 后端日志中要记录识别失败原因，便于排查 Kimi 调用问题

## 9. 本期开发范围

本期要完成：

1. 数据库建表
2. 后端识别接口
3. 后端保存接口
4. 后端列表接口
5. 后端详情接口
6. 前端列表页
7. 前端新增并人工校对页面
8. 原图预览

本期暂不做：

1. 编辑历史记录
2. 删除功能
3. 批量上传
4. 多用户权限管理

## 10. 验收标准

1. 用户可以上传一张资金流向截图
2. Kimi 可以返回结构化识别结果
3. 用户可以在保存前修改识别结果
4. 点击保存后数据成功写入数据库
5. 列表页能展示已保存记录
6. 每条记录都可以查看原图和详情
7. 同一天不能重复保存两条正式记录