基于Django的财务数据可视化分析平台

API: POST /api/auth/register，入参 username/email/password/password_confirm，校验：用户名3-20字符、邮箱格式、密码8位以上含大小写+数字、两次密码一致，返回用户信息与JWT token。前端注册表单含实时字段校验提示，三态：loading提交、成功跳转登录、错误inline message。

API: POST /api/auth/login，入参 username+password，返回 access_token + refresh_token。前端登录表单含"记住我"选项（延长token有效期至7天），失败时提示"用户名或密码错误"（不区分具体原因），三态：loading按钮禁用、成功跳转仪表盘首页、错误toast提示。

管理员可在后台创建/编辑角色（如：超级管理员、财务主管、普通财务、只读访客），为每个角色配置功能权限（仪表盘查看、编辑、数据导入、用户管理等模块开关）。API: GET/POST/PUT /api/roles，普通用户不可访问此接口。

规则：每个仪表盘可设置可见角色范围，用户登录后只能看到授权角色范围内的仪表盘。后端中间件校验JWT后从数据库查询用户角色，过滤仪表盘列表和数据接口返回。无权限访问时返回403，前端显示"无权访问此仪表盘"。

API: POST /api/auth/logout，将 refresh_token 加入黑名单使其失效。前端全局监听token过期（401响应），自动跳转登录页并提示"登录已过期，请重新登录"。支持修改密码后强制所有设备重新登录。

API: PUT /api/auth/password，入参 old_password + new_password + new_password_confirm，校验：旧密码正确、新密码8位以上含大小写+数字、两次一致、不能与旧密码相同。成功后返回提示"密码修改成功，请重新登录"，强制所有设备token失效。前端表单三态：loading提交中、成功toast+3秒后跳转登录页、错误inline message。

管理员可见的用户管理页面：表格展示所有用户（用户名/邮箱/角色/注册时间/状态），支持按用户名/邮箱搜索、按角色筛选、按状态（启用/禁用）切换。管理员可操作：启用/禁用账号、分配角色、强制重置密码（生成临时密码并提示用户首次登录修改）。API: GET /api/admin/users 列表、PUT /api/admin/users/{id} 更新状态/角色、POST /api/admin/users/{id}/reset-password。

前端上传组件支持拖拽文件和点击选择两种方式，接受 .xlsx/.xls/.csv 格式，单文件上限 20MB。上传过程中显示进度条和文件名，三态：未选择时显示拖拽区域提示、上传中进度动画、完成后展示文件信息卡片（文件名、大小、行数预览）。

API: POST /api/datasets/upload，入参 multipart/form-data(file)，后端用 openpyxl/pandas 解析文件。返回解析到的字段列表，用户可手动映射到系统标准字段（日期→date、金额→amount、科目→account、部门→department等）。支持保存映射模板供下次复用。

后端清洗规则：1) 金额列去除货币符号和千分位逗号转数值；2) 日期列统一为 YYYY-MM-DD；3) 空值行/全重复行自动标记并跳过；4) 异常值检测（金额超出均值±3σ标记为可疑）。返回清洗报告：总行数、跳过行数、异常行数及明细。用户确认后调用 POST /api/datasets/{id}/confirm 正式入库；放弃则调用 DELETE /api/datasets/{id} 丢弃本次导入数据。

大文件导入采用异步任务（Celery），前端轮询或WebSocket获取进度。导入完成后展示结果报告页：成功导入行数、跳过行数、异常行数，异常明细表格（行号、字段、原因）。支持下载异常数据CSV供用户修正后重新导入。

用户上传文件后完成字段映射时，可保存当前映射为模板（命名+描述）。再次上传时可从模板下拉列表中选择复用，自动填充映射关系。支持模板重命名、删除。API: GET /api/mapping-templates 列表、POST /api/mapping-templates 保存、DELETE /api/mapping-templates/{id} 删除。模板按用户隔离存储。

系统预设科目类别树：资产类（流动资产/固定资产/无形资产）、负债类（流动负债/长期负债）、权益类、收入类、支出类。管理员可在后台管理页面新增/编辑/禁用自定义科目类别，调整分类树结构。用户导入数据映射科目字段时，下拉列表展示所有启用状态的科目类别。API: GET /api/account-categories 获取类别树（所有用户可用）、POST/PUT/DELETE /api/admin/account-categories 管理（仅管理员）。

前端数据集列表页：表格展示数据集名称、导入时间、数据行数、文件类型、状态标签（状态枚举：importing-导入中、ready-可用、error-导入失败、discarded-已丢弃）。支持按名称关键词搜索、按导入时间范围筛选、按状态筛选、按行数/时间排序，默认每页20条。三态：loading骨架屏、空数据引导上传、正常表格。API: GET /api/datasets?page=&search=&sort=&status=&date_from=&date_to=。

点击数据集行进入详情页：展示字段列表与类型、数据预览表格（前100行）、摘要统计卡片（总收入、总支出、净额、交易笔数、覆盖时间范围）。API: GET /api/datasets/{id} 返回字段schema + 聚合统计；GET /api/datasets/{id}/preview?limit=100 返回前N行数据。

删除操作弹出二次确认弹窗："删除数据集后，关联该数据集的所有图表将失效，确定删除？"。确认后 API: DELETE /api/datasets/{id} 软删除数据集（标记 deleted_at），同时清理关联的图表缓存和聚合数据。软删除后数据集在列表中不可见，管理员可在后台回收站查看并在30天内恢复，超期自动物理删除。返回删除成功toast并刷新列表。

用户点击"新建仪表盘"，弹出表单填写：名称（必填，1-30字符）、描述（可选）、可见角色（多选，默认仅自己可见）。API: POST /api/dashboards 创建，PUT /api/dashboards/{id} 编辑。仪表盘创建后默认空白，引导用户添加第一张图表卡片。

左侧或顶部导航栏展示用户有权限的仪表盘列表，当前选中的仪表盘高亮。支持通过下拉或标签页方式切换仪表盘。API: GET /api/dashboards 返回用户可见的仪表盘列表（按最近访问排序）。

在仪表盘编辑模式下，点击"添加图表"弹出配置面板：选择图表类型（趋势图/饼图/瀑布图/柱状图）、选择数据源（已导入的数据集）、配置维度（X轴/分类字段）与指标（Y轴/数值字段）、设置标题和颜色主题。API: POST /api/dashboards/{id}/cards，返回卡片配置与布局位置。

仪表盘采用网格布局（12列栅格），卡片支持拖拽移动和右下角拖拽调整大小。布局变更后自动保存（防抖2秒），API: PUT /api/dashboards/{id}/layout，入参 cards:[{id, x, y, w, h}]。刷新页面后恢复上次布局。

仪表盘卡片右上角更多菜单含"删除仪表盘"选项，弹出二次确认"删除后不可恢复，确定？"。API: DELETE /api/dashboards/{id}，级联删除关联的卡片配置和布局数据。删除后自动跳转到用户第一个可用仪表盘。

业务规则：单用户最多创建 20 个仪表盘，超过时提示"已达仪表盘数量上限（20个），请清理不再使用的仪表盘后再创建"。每个仪表盘最多添加 12 张图表卡片，超过时"添加图表"按钮置灰并提示。后端 API 在创建时校验并返回 422。管理员角色不受此限制。

ECharts渲染月度/季度/年度收入与支出双折线或面积图。X轴为时间维度，Y轴为金额，两条系列分别表示收入与支出。图表上方提供时间范围快捷切换（近3月/6月/1年/自定义），切换时同步更新全局过滤面板。悬浮数据点显示具体金额和同比变化率（首年无数据则隐藏同比）。数据通过 POST /api/charts/query（chart_type=trend, granularity=month|quarter|year）统一获取。

ECharts渲染资产与负债分类占比环形图（双环或两个图表），按科目类别（流动资产/固定资产/流动负债/长期负债等系统预设类别）聚合。图例可点击切换显示/隐藏，扇区悬浮显示类别名称、金额和占比百分比。数据通过 POST /api/charts/query（chart_type=pie, type=asset|liability）统一获取。

ECharts瀑布图展示期初余额→各项收入（向上堆积绿色）→各项支出（向下红色）→期末余额的累计变化。每根柱子上标注具体金额，悬浮显示明细（科目名称、金额、类型）。数据通过 POST /api/charts/query（chart_type=waterfall）统一获取。

ECharts分组柱状图/堆叠柱状图，按科目类别或部门维度对比各期收入/支出。支持切换对比维度（按科目/按部门/按项目），可设置Top N显示。数据通过 POST /api/charts/query（chart_type=bar, dimension=category|department|project, top_n=10）统一获取。

所有图表支持：1) 工具栏：区域缩放、还原、导出PNG/SVG图片；2) 图例点击切换数据系列显隐；3) 数据点悬浮tooltip显示详细数值；4) 空数据时显示"暂无数据"占位图；5) 加载中显示骨架/loading动画。前端封装为统一ChartCard组件，props传入类型和配置即可渲染。

仪表盘顶部全局过滤栏，包含：时间范围选择器（日期范围快捷选+自定义）、科目类别多选下拉框、金额区间滑块（最小值-最大值）、部门/项目多选下拉框。过滤条件变更时触发仪表盘内所有图表重新查询。过滤栏支持折叠/展开以节省屏幕空间。

API: POST /api/charts/query，入参 dataset_id + filters:{date_from, date_to, categories[], amount_min, amount_max, departments[]} + chart_type + dimension + metric。后端按过滤条件动态构建SQL聚合查询，返回图表数据。前端防抖300ms后统一发起批量图表查询请求，loading期间图表显示骨架屏。

图表卡片内提供维度切换控件：用户可将趋势图X轴从"按月"切换为"按季度"或"按年"聚合；柱状图分类维度可在"科目类别"/"部门"/"项目"之间切换。切换后即时重新请求数据。API的granularity/dimension参数控制聚合层级。

所有API统一响应格式：{code: 200, data: {}, message: "ok"}。错误响应：{code: 4xx/5xx, data: null, message: "具体错误描述"}。错误码规范：400参数校验失败、401未认证、403无权限、404资源不存在、422业务逻辑错误、500服务器内部错误。全局异常拦截器统一处理并返回标准格式。

核心数据表：users(用户+角色)、datasets(数据集元信息)、financial_records(清洗后的财务明细记录，含date/amount/account/category/department等字段)、dashboards(仪表盘)、dashboard_cards(卡片配置+布局)。使用Django ORM定义模型，makemigrations+migrate管理表结构变更，数据库字符集utf8mb4。

使用 Redis 同时承担缓存和 Celery 消息代理：仪表盘图表聚合数据缓存TTL=5分钟，数据集摘要统计缓存TTL=10分钟。缓存键格式：chart:{dashboard_id}:{card_id}:{filter_hash}。数据导入或删除时主动清除相关缓存。Celery 异步任务（文件解析/清洗/入库）使用同一 Redis 实例作为 broker。使用 django-redis 集成，配置连接池防止连接泄漏。

Django中间件默认开启CSRF保护；前端所有用户输入做HTML实体编码防XSS；所有数据库查询使用ORM参数化查询防SQL注入；JWT token存储在httpOnly cookie中防XSS窃取；密码使用bcrypt哈希存储；API限流中间件限制单IP每分钟最多100次请求。

financial_records表超10万行时：1) 在date/account/category/department字段建立联合索引；2) 按月预聚合汇总表 materialized_summary 定时刷新（每日凌晨）；3) 图表查询优先走汇总表，明细查询走索引；4) 使用 Django ORM 的 select_related/prefetch_related 减少N+1查询；5) 数据库连接池使用 django-db-connection-pool。超50万行时降级策略：全局过滤面板默认时间范围自动收窄至近3个月，用户可手动放宽但提示"数据量较大，查询可能较慢"。

性能基准：仪表盘内任意图表卡片数据查询（含过滤条件）在10万条记录规模下，P95响应时间不超过2秒，P99不超过5秒。通过Redis缓存+预聚合汇总表+联合索引三重策略保障。前端图表超过2秒未响应时显示loading动画并提示"数据量较大，请稍候"。

前端全局捕获未处理异常，展示友好错误页"页面出错了，点击刷新重试"，不暴露技术栈信息。后端500错误记录日志并返回通用错误消息。数据库连接断开时自动重试3次。文件上传失败时保留用户已填写信息。关键操作（导入/删除）失败时支持重试。