TraceIQ 财务分析工作台 · 使用文档

1. 快速开始

TraceIQ 是证据优先的财务分析工作台：所有指标都能下钻到原始表格行，操作全程留痕。本地开发环境启动方式：

1. 在仓库根目录执行 scripts/dev_up.sh（自动完成迁移、管理员初始化、前端构建并启动服务）。
2. 浏览器访问 http://127.0.0.1:8000。
3. 使用管理员账号登录（本地凭据见 var/local-access.txt，文件权限 0600）。

2. 界面导览

登录后左侧为导航栏，分两组：

顶部右侧为财务分析助手入口和退出登录。页面为响应式布局，手机浏览器可直接使用。

3. 导入数据

3.1 支持的文件

• XLSX（Excel）与 UTF-8 编码 CSV。
• 支持双行表头：第二行表头作为字段语义说明一并保留。
• 单文件不超过 64 MiB（反向代理层限制 66 MB）。

3.2 导入流程

1. 在「数据管理」页点击 导入新表格，选择文件上传。
2. 系统在弹窗中展示识别出的字段，请逐项确认导入字段映射：期间、科室等业务维度、实际收入、成本、毛利贡献、客户编码、应收金额等。
3. 选择 ROI 公式口径与自营产品范围后，点击 确认并导入。
4. 导入由后台 worker 异步处理，完成后数据自动出现在总览中；列表中可查看状态、数据质量与导入版本。

4. 经营总览

总览页展示所选数据集团范围的核心经营结果：

• KPI 卡片：实际收入、成本、毛利、ROI、客单价、毛利率、去重人数、自营收入、升单率等可用指标（取决于数据中有哪些字段）。
• 收入与毛利走势：按月份的趋势图；缺月份的区间趋势自动断开，不会用直线伪造连续性。
• 经营指标矩阵：按维度（如科室、产品分类）展开的指标对照表。

比较方式

• 同比 / 环比：一键切换，可自定义开始/结束期间。
• 比较必须满足等长月份范围；缺基期时禁止比较，对应卡片显示不可用而不是给出误导数字。
• 缺成本的数据不显示 ROI 等依赖成本的指标。

5. 异常追踪与下钻

5.1 异常列表

「异常追踪」列出超出分析设置中阈值与最小影响额的分组，按影响额排序。点击分组进入调查视图：

• 调查状态：待调查 / 核查中 / 已处理，保存后持久化。
• 调查备注：自由文本，随状态一并保存。

5.2 下钻与面包屑

• 在调查视图可沿自定义层级继续下钻（如 科室 → 学科 → 医生等级）。
• 顶部分析路径面包屑记录当前下钻位置，点击任意一级可跳回。
• 列表支持搜索分组，方便在大体量维度中定位。

6. 贡献分解

调查视图提供两张贡献图，回答"变化是谁带来的"：

• 分组变化贡献图：当前层级各分组对本期与基期差额（变化额/变化贡献）的分解。
• 调查范围子级贡献图：在所选分组内部，按下一级维度继续分解。

7. 证据与导出

7.1 证据明细

• 任意数字都可通过查看证据打开原始行明细弹窗，逐条对应到源文件行号。
• 证据按本期 / 基期切换，每页最多 200 行，上一页/下一页翻页加载。

7.2 导出

• 导出当前范围：将当前筛选与下钻范围内的证据导出为 CSV 或 XLSX；Excel 中精确金额以文本单元格导出，避免 15 位有效数字精度丢失。
• 生成公式工作簿：在「数据管理」中生成带公式的 Excel 工作簿，含列计算描述，便于财务同事复核口径。

8. 分析设置

「分析设置」是个人偏好，随账号保存，字段包括：

保存使用乐观锁：若他人在你打开设置期间已保存，系统会提示冲突而不是静默覆盖。页面上一般提供保存 / 取消 / 预览能力。

9. 财务分析助手与 AI 模型配置

9.1 使用助手

• 默认启用本地规则助手：直接回答指标口径、功能用法等问题，数据不出本机。
• 勾选「使用已配置的 AI 模型理解问题」并同意后，问题与维度/当前筛选会发送到你配置的模型服务，原始数据行不出服务器。
• 无论本地还是外部模型，都只能返回受控意图（如跳转页面、设置筛选），不能直接改金额、不能提交 SQL、不能改账号；查询数据仍受后端权限约束。
• 模型输出异常或被拒答时，相关执行自动关闭。

9.2 配置 AI 模型（全权限管理员）

在左侧「管理 → AI 模型」中配置，支持两类服务商：

1. 选择服务商，填写 Base URL（本地服务必填）。
2. 填写 API Key（本地服务通常可留空）。
3. 点击获取可用模型：系统从服务的 /v1/models 接口拉取模型列表。本地服务装了多个模型（如 Ollama 里的 qwen2.5:7b、llama3.1:8b）时，可在下拉列表中挑选，不用手敲名字。
4. 选中模型后勾选「启用 AI 模型理解问题」，点击保存配置。
5. 回到页面顶部打开「财务分析助手」，勾选「使用已配置的 AI 模型理解问题」并同意后即可提问。

9.3 常见问题

• 「获取可用模型」失败？确认本地服务已启动且 Base URL 正确（Ollama 默认 http://127.0.0.1:11434/v1），并先点击「保存配置」再获取。
• 助手提示「尚未配置外部 AI 服务」？检查「AI 模型」中是否已启用、模型名是否已填写；OpenAI 还需 API Key。
• 想停用 AI？取消勾选「启用 AI 模型理解问题」并保存，助手回到纯本地规则模式。

10. 账号与审计（管理员）

10.1 账号与权限

• 全权限管理员（未限科室范围）可在「账号与权限」查看所有账号的角色（查看者 / 分析师 / 管理员）、启用状态与科室范围。
• 限域管理员只能管理自己科室范围内的成员，不能管理账号或查看全局审计。
• 角色能力概览：查看者可看不可改；分析师可做分析调查；管理员可导入数据并管理账号。

10.2 操作审计

「操作审计」记录登录、导入、导出、设置修改、调查保存等操作的时间、用户、动作与详情，网页端只读。需要不可抵赖审计时应外送到独立追加写日志平台（数据库管理员理论上可改库内记录）。

11. 口径与注意事项

• 毛利口径：毛利是按产品分类毛利率计算的贡献值，不等同于已审计净利润。
• ROI 口径：提供两种明确公式（如 （收入 − 成本）/ 成本），导入时选择并可在字段字典中回看。
• 精度：后端金额使用高精度定点数存储与计算，JSON 中金额为字符串；浏览器 Number 仅用于绘图显示。
• 缺数据原则：缺基期禁止比较、缺成本显示不可用、缺月份趋势断开——系统宁可显示"不可用"也不给误导数字。
• 安全：登录有频率限制；原始文件私有存储、按组织隔离；审计留痕。
• 本地 SQLite 模式仅限页面测试与开发回归，高精度金额聚合与财务验收请使用 PostgreSQL 环境（见 README）。