Jayway Liu
cd07ba1887
- user-guide.html：面向使用者的完整操作说明（含 AI 模型配置） - gaps-and-testing.html：未实现功能清单、F01-F08 状态、发布门禁与 分层测试方法、验收矩阵、当前基线 - README 加入口链接
317 lines
18 KiB
HTML
317 lines
18 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>TraceIQ 财务分析工作台 · 使用文档</title>
|
||
<style>
|
||
:root {
|
||
--ink: #1a2332;
|
||
--muted: #5b6675;
|
||
--accent: #1f5fa8;
|
||
--accent-soft: #eaf2fb;
|
||
--line: #dfe5ec;
|
||
--bg: #f6f8fa;
|
||
--card: #ffffff;
|
||
--warn: #9a5b00;
|
||
--warn-bg: #fdf3e3;
|
||
}
|
||
* { box-sizing: border-box; }
|
||
body {
|
||
margin: 0;
|
||
font-family: -apple-system, "PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif;
|
||
color: var(--ink);
|
||
background: var(--bg);
|
||
line-height: 1.7;
|
||
}
|
||
header {
|
||
background: linear-gradient(135deg, #16324f, #1f5fa8);
|
||
color: #fff;
|
||
padding: 48px 24px 40px;
|
||
}
|
||
header .inner, main { max-width: 960px; margin: 0 auto; }
|
||
header h1 { margin: 0 0 8px; font-size: 28px; }
|
||
header p { margin: 0; opacity: .85; }
|
||
.layout { max-width: 1160px; margin: 0 auto; display: flex; gap: 32px; padding: 32px 24px 64px; }
|
||
nav.toc {
|
||
flex: 0 0 220px;
|
||
position: sticky; top: 24px; align-self: flex-start;
|
||
background: var(--card); border: 1px solid var(--line); border-radius: 10px;
|
||
padding: 16px 18px; font-size: 14px;
|
||
}
|
||
nav.toc strong { display: block; margin-bottom: 8px; }
|
||
nav.toc a { display: block; color: var(--accent); text-decoration: none; padding: 3px 0; }
|
||
nav.toc a:hover { text-decoration: underline; }
|
||
main { flex: 1; min-width: 0; }
|
||
section {
|
||
background: var(--card); border: 1px solid var(--line); border-radius: 10px;
|
||
padding: 24px 28px; margin-bottom: 24px;
|
||
}
|
||
h2 { font-size: 20px; margin: 0 0 12px; padding-bottom: 8px; border-bottom: 2px solid var(--accent-soft); }
|
||
h3 { font-size: 16px; margin: 20px 0 8px; }
|
||
p { margin: 8px 0; }
|
||
ul, ol { margin: 8px 0; padding-left: 22px; }
|
||
li { margin: 4px 0; }
|
||
code {
|
||
background: #eef1f5; border-radius: 4px; padding: 1px 6px;
|
||
font-family: "SF Mono", Menlo, Consolas, monospace; font-size: .92em;
|
||
}
|
||
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
||
th, td { border: 1px solid var(--line); padding: 8px 12px; text-align: left; }
|
||
th { background: var(--accent-soft); }
|
||
tr:nth-child(even) td { background: #fafcfe; }
|
||
.note {
|
||
background: var(--accent-soft); border-left: 4px solid var(--accent);
|
||
border-radius: 0 8px 8px 0; padding: 10px 16px; margin: 12px 0; font-size: 14px;
|
||
}
|
||
.warn {
|
||
background: var(--warn-bg); border-left: 4px solid var(--warn);
|
||
border-radius: 0 8px 8px 0; padding: 10px 16px; margin: 12px 0; font-size: 14px;
|
||
}
|
||
.kbd {
|
||
display: inline-block; border: 1px solid var(--line); border-bottom-width: 2px;
|
||
border-radius: 4px; background: #fff; padding: 0 6px; font-size: 13px;
|
||
font-family: "SF Mono", Menlo, Consolas, monospace;
|
||
}
|
||
footer { text-align: center; color: var(--muted); font-size: 13px; padding: 24px; }
|
||
@media (max-width: 860px) {
|
||
.layout { flex-direction: column; }
|
||
nav.toc { position: static; flex: none; }
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<header>
|
||
<div class="inner">
|
||
<h1>TraceIQ 财务分析工作台 · 使用文档</h1>
|
||
<p>面向使用者：导入财务表格 → 总览与对比 → 异常追踪与下钻 → 证据核查与导出</p>
|
||
</div>
|
||
</header>
|
||
|
||
<div class="layout">
|
||
<nav class="toc">
|
||
<strong>目录</strong>
|
||
<a href="#start">1. 快速开始</a>
|
||
<a href="#layout">2. 界面导览</a>
|
||
<a href="#import">3. 导入数据</a>
|
||
<a href="#overview">4. 经营总览</a>
|
||
<a href="#anomalies">5. 异常追踪与下钻</a>
|
||
<a href="#contribution">6. 贡献分解</a>
|
||
<a href="#evidence">7. 证据与导出</a>
|
||
<a href="#settings">8. 分析设置</a>
|
||
<a href="#copilot">9. 助手与 AI 模型配置</a>
|
||
<a href="#admin">10. 账号与审计</a>
|
||
<a href="#notes">11. 口径与注意事项</a>
|
||
</nav>
|
||
|
||
<main>
|
||
|
||
<section id="start">
|
||
<h2>1. 快速开始</h2>
|
||
<p>TraceIQ 是证据优先的财务分析工作台：所有指标都能下钻到原始表格行，操作全程留痕。本地开发环境启动方式：</p>
|
||
<ol>
|
||
<li>在仓库根目录执行 <code>scripts/dev_up.sh</code>（自动完成迁移、管理员初始化、前端构建并启动服务）。</li>
|
||
<li>浏览器访问 <code>http://127.0.0.1:8000</code>。</li>
|
||
<li>使用管理员账号登录（本地凭据见 <code>var/local-access.txt</code>，文件权限 0600）。</li>
|
||
</ol>
|
||
<table>
|
||
<tr><th>环境</th><th>用户名</th><th>密码</th></tr>
|
||
<tr><td>本地开发（本机）</td><td><code>admin</code></td><td>见 <code>var/local-access.txt</code>（每次初始化随机生成）</td></tr>
|
||
<tr><td>自动化测试</td><td><code>admin</code></td><td>测试专用库随机生成，可用环境变量 <code>E2E_PASSWORD</code> 指定</td></tr>
|
||
</table>
|
||
<div class="note">停止服务：在运行 <code>dev_up.sh</code> 的终端按 <span class="kbd">Ctrl-C</span>，或另开终端执行 <code>scripts/dev_up.sh --stop</code>。</div>
|
||
</section>
|
||
|
||
<section id="layout">
|
||
<h2>2. 界面导览</h2>
|
||
<p>登录后左侧为导航栏，分两组：</p>
|
||
<table>
|
||
<tr><th>分组</th><th>入口</th><th>说明</th></tr>
|
||
<tr><td rowspan="3">工作台</td><td>经营总览</td><td>核心指标、走势、指标矩阵与同比/环比对比</td></tr>
|
||
<tr><td>异常追踪</td><td>超出阈值的分组列表，可进入调查；有新异常时入口显示数量角标</td></tr>
|
||
<tr><td>数据管理</td><td>数据集列表、导入新表格、数据来源与字段字典、公式工作簿导出</td></tr>
|
||
<tr><td rowspan="4">管理</td><td>分析设置</td><td>默认比较方式、默认指标、异常阈值等个人偏好</td></tr>
|
||
<tr><td>账号与权限</td><td>仅全权限管理员可见：查看账号、角色、状态、科室范围</td></tr>
|
||
<tr><td>操作审计</td><td>仅全权限管理员可见：时间、用户、操作、资源、详情</td></tr>
|
||
<tr><td>AI 模型</td><td>仅全权限管理员可见：配置助手使用的云端或本地模型服务</td></tr>
|
||
</table>
|
||
<p>顶部右侧为<strong>财务分析助手</strong>入口和<strong>退出登录</strong>。页面为响应式布局，手机浏览器可直接使用。</p>
|
||
</section>
|
||
|
||
<section id="import">
|
||
<h2>3. 导入数据</h2>
|
||
<h3>3.1 支持的文件</h3>
|
||
<ul>
|
||
<li>XLSX（Excel）与 UTF-8 编码 CSV。</li>
|
||
<li>支持双行表头：第二行表头作为字段语义说明一并保留。</li>
|
||
<li>单文件不超过 64 MiB（反向代理层限制 66 MB）。</li>
|
||
</ul>
|
||
<h3>3.2 导入流程</h3>
|
||
<ol>
|
||
<li>在「数据管理」页点击 <strong>导入新表格</strong>，选择文件上传。</li>
|
||
<li>系统在弹窗中展示识别出的字段，请逐项<strong>确认导入字段</strong>映射：期间、科室等业务维度、实际收入、成本、毛利贡献、客户编码、应收金额等。</li>
|
||
<li>选择 ROI 公式口径与自营产品范围后，点击 <strong>确认并导入</strong>。</li>
|
||
<li>导入由后台 worker 异步处理，完成后数据自动出现在总览中；列表中可查看状态、数据质量与导入版本。</li>
|
||
</ol>
|
||
<div class="note">
|
||
<strong>去重：</strong>同一组织内完全相同的文件（SHA-256）不会重复导入。<br>
|
||
<strong>原始解释：</strong>原始表头说明随数据保留，可在「数据来源与字段字典」中查看，保证指标口径可追溯。
|
||
</div>
|
||
<div class="warn">原附件中没有的维度（如医生、成本、连续月度数据）不会产生对应排名或环比结论；系统不会虚构数据。</div>
|
||
</section>
|
||
|
||
<section id="overview">
|
||
<h2>4. 经营总览</h2>
|
||
<p>总览页展示所选数据集团范围的核心经营结果：</p>
|
||
<ul>
|
||
<li><strong>KPI 卡片：</strong>实际收入、成本、毛利、ROI、客单价、毛利率、去重人数、自营收入、升单率等可用指标（取决于数据中有哪些字段）。</li>
|
||
<li><strong>收入与毛利走势：</strong>按月份的趋势图；缺月份的区间趋势自动断开，不会用直线伪造连续性。</li>
|
||
<li><strong>经营指标矩阵：</strong>按维度（如科室、产品分类）展开的指标对照表。</li>
|
||
</ul>
|
||
<h3>比较方式</h3>
|
||
<ul>
|
||
<li><strong>同比</strong> / <strong>环比</strong>：一键切换，可自定义开始/结束期间。</li>
|
||
<li>比较必须满足等长月份范围；<strong>缺基期时禁止比较</strong>，对应卡片显示不可用而不是给出误导数字。</li>
|
||
<li>缺成本的数据不显示 ROI 等依赖成本的指标。</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<section id="anomalies">
|
||
<h2>5. 异常追踪与下钻</h2>
|
||
<h3>5.1 异常列表</h3>
|
||
<p>「异常追踪」列出超出分析设置中阈值与最小影响额的分组，按影响额排序。点击分组进入调查视图：</p>
|
||
<ul>
|
||
<li><strong>调查状态：</strong>待调查 / 核查中 / 已处理，保存后持久化。</li>
|
||
<li><strong>调查备注：</strong>自由文本，随状态一并保存。</li>
|
||
</ul>
|
||
<h3>5.2 下钻与面包屑</h3>
|
||
<ul>
|
||
<li>在调查视图可沿自定义层级<strong>继续下钻</strong>（如 科室 → 学科 → 医生等级）。</li>
|
||
<li>顶部<strong>分析路径</strong>面包屑记录当前下钻位置，点击任意一级可跳回。</li>
|
||
<li>列表支持<strong>搜索分组</strong>，方便在大体量维度中定位。</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<section id="contribution">
|
||
<h2>6. 贡献分解</h2>
|
||
<p>调查视图提供两张贡献图，回答"变化是谁带来的"：</p>
|
||
<ul>
|
||
<li><strong>分组变化贡献图：</strong>当前层级各分组对本期与基期差额（变化额/变化贡献）的分解。</li>
|
||
<li><strong>调查范围子级贡献图：</strong>在所选分组内部，按下一级维度继续分解。</li>
|
||
</ul>
|
||
<div class="note">贡献分解只基于权限范围内的数据；科室范围受限的账号看不到范围外的分组。</div>
|
||
</section>
|
||
|
||
<section id="evidence">
|
||
<h2>7. 证据与导出</h2>
|
||
<h3>7.1 证据明细</h3>
|
||
<ul>
|
||
<li>任意数字都可通过<strong>查看证据</strong>打开原始行明细弹窗，逐条对应到源文件行号。</li>
|
||
<li>证据按<strong>本期 / 基期</strong>切换，每页最多 200 行，上一页/下一页翻页加载。</li>
|
||
</ul>
|
||
<h3>7.2 导出</h3>
|
||
<ul>
|
||
<li><strong>导出当前范围：</strong>将当前筛选与下钻范围内的证据导出为 CSV 或 XLSX；Excel 中精确金额以文本单元格导出，避免 15 位有效数字精度丢失。</li>
|
||
<li><strong>生成公式工作簿：</strong>在「数据管理」中生成带公式的 Excel 工作簿，含列计算描述，便于财务同事复核口径。</li>
|
||
</ul>
|
||
<div class="note">客户端不会一次加载全部明细（大文件可达 33 万行），只按需拉取聚合结果与分页证据。</div>
|
||
</section>
|
||
|
||
<section id="settings">
|
||
<h2>8. 分析设置</h2>
|
||
<p>「分析设置」是个人偏好，随账号保存，字段包括：</p>
|
||
<table>
|
||
<tr><th>设置项</th><th>作用</th></tr>
|
||
<tr><td>默认比较</td><td>同比 / 环比</td></tr>
|
||
<tr><td>默认指标</td><td>总览与矩阵默认展示的指标</td></tr>
|
||
<tr><td>异常阈值</td><td>判定异常的变化幅度阈值</td></tr>
|
||
<tr><td>最小影响额</td><td>低于该金额的变化不列为异常，避免噪声</td></tr>
|
||
<tr><td>最小样本数</td><td>样本量过小的分组不参与异常判定</td></tr>
|
||
</table>
|
||
<p>保存使用乐观锁：若他人在你打开设置期间已保存，系统会提示冲突而不是静默覆盖。页面上一般提供保存 / 取消 / 预览能力。</p>
|
||
</section>
|
||
|
||
<section id="copilot">
|
||
<h2>9. 财务分析助手与 AI 模型配置</h2>
|
||
<h3>9.1 使用助手</h3>
|
||
<ul>
|
||
<li>默认启用<strong>本地规则助手</strong>：直接回答指标口径、功能用法等问题，数据不出本机。</li>
|
||
<li>勾选「使用已配置的 AI 模型理解问题」并同意后，问题与维度/当前筛选会发送到你配置的模型服务，<strong>原始数据行不出服务器</strong>。</li>
|
||
<li>无论本地还是外部模型，都只能返回受控意图（如跳转页面、设置筛选），<strong>不能直接改金额、不能提交 SQL、不能改账号</strong>；查询数据仍受后端权限约束。</li>
|
||
<li>模型输出异常或被拒答时，相关执行自动关闭。</li>
|
||
</ul>
|
||
<h3>9.2 配置 AI 模型（全权限管理员）</h3>
|
||
<p>在左侧「管理 → AI 模型」中配置，支持两类服务商：</p>
|
||
<table>
|
||
<tr><th>服务商</th><th>说明</th><th>Base URL 示例</th><th>API Key</th></tr>
|
||
<tr>
|
||
<td>OpenAI</td>
|
||
<td>OpenAI Responses 接口</td>
|
||
<td><code>https://api.openai.com/v1</code>（可留空使用默认）</td>
|
||
<td>必填</td>
|
||
</tr>
|
||
<tr>
|
||
<td>本地 OpenAI 兼容服务</td>
|
||
<td>Ollama、LM Studio、vLLM 等任何兼容 OpenAI 协议的服务</td>
|
||
<td>Ollama：<code>http://127.0.0.1:11434/v1</code><br>LM Studio：<code>http://127.0.0.1:1234/v1</code></td>
|
||
<td>通常可留空</td>
|
||
</tr>
|
||
</table>
|
||
<ol>
|
||
<li>选择服务商，填写 Base URL（本地服务必填）。</li>
|
||
<li>填写 API Key（本地服务通常可留空）。</li>
|
||
<li>点击<strong>获取可用模型</strong>：系统从服务的 <code>/v1/models</code> 接口拉取模型列表。本地服务装了多个模型（如 Ollama 里的 qwen2.5:7b、llama3.1:8b）时，可在下拉列表中挑选，不用手敲名字。</li>
|
||
<li>选中模型后勾选「启用 AI 模型理解问题」，点击<strong>保存配置</strong>。</li>
|
||
<li>回到页面顶部打开「财务分析助手」，勾选「使用已配置的 AI 模型理解问题」并同意后即可提问。</li>
|
||
</ol>
|
||
<div class="note">
|
||
<strong>配置规则：</strong>每个组织一份配置，保存在数据库中，优先于部署环境变量（未配置时回退到
|
||
<code>AI_ENABLED</code> / <code>OPENAI_API_KEY</code> / <code>OPENAI_MODEL</code> / <code>OPENAI_BASE_URL</code>）。
|
||
仅全权限管理员（未限科室范围的管理员角色）可查看和修改；限域管理员、分析师、查看者无此入口。
|
||
</div>
|
||
<div class="note">
|
||
<strong>密钥安全：</strong>API Key 只保存在后端，页面只显示「已配置」，读取接口不回传密钥原文；
|
||
再次保存时留空表示保持原密钥不变。每次配置修改都会记入操作审计（只记服务商、模型与是否启用，不记密钥）。
|
||
</div>
|
||
<h3>9.3 常见问题</h3>
|
||
<ul>
|
||
<li><strong>「获取可用模型」失败？</strong>确认本地服务已启动且 Base URL 正确（Ollama 默认 <code>http://127.0.0.1:11434/v1</code>），并先点击「保存配置」再获取。</li>
|
||
<li><strong>助手提示「尚未配置外部 AI 服务」？</strong>检查「AI 模型」中是否已启用、模型名是否已填写；OpenAI 还需 API Key。</li>
|
||
<li><strong>想停用 AI？</strong>取消勾选「启用 AI 模型理解问题」并保存，助手回到纯本地规则模式。</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<section id="admin">
|
||
<h2>10. 账号与审计（管理员）</h2>
|
||
<h3>10.1 账号与权限</h3>
|
||
<ul>
|
||
<li>全权限管理员（未限科室范围）可在「账号与权限」查看所有账号的<strong>角色</strong>（查看者 / 分析师 / 管理员）、<strong>启用状态</strong>与<strong>科室范围</strong>。</li>
|
||
<li>限域管理员只能管理自己科室范围内的成员，不能管理账号或查看全局审计。</li>
|
||
<li>角色能力概览：查看者可看不可改；分析师可做分析调查；管理员可导入数据并管理账号。</li>
|
||
</ul>
|
||
<h3>10.2 操作审计</h3>
|
||
<p>「操作审计」记录登录、导入、导出、设置修改、调查保存等操作的时间、用户、动作与详情，网页端只读。需要不可抵赖审计时应外送到独立追加写日志平台（数据库管理员理论上可改库内记录）。</p>
|
||
</section>
|
||
|
||
<section id="notes">
|
||
<h2>11. 口径与注意事项</h2>
|
||
<ul>
|
||
<li><strong>毛利口径：</strong>毛利是按产品分类毛利率计算的贡献值，<strong>不等同于已审计净利润</strong>。</li>
|
||
<li><strong>ROI 口径：</strong>提供两种明确公式（如 （收入 − 成本）/ 成本），导入时选择并可在字段字典中回看。</li>
|
||
<li><strong>精度：</strong>后端金额使用高精度定点数存储与计算，JSON 中金额为字符串；浏览器 Number 仅用于绘图显示。</li>
|
||
<li><strong>缺数据原则：</strong>缺基期禁止比较、缺成本显示不可用、缺月份趋势断开——系统宁可显示"不可用"也不给误导数字。</li>
|
||
<li><strong>安全：</strong>登录有频率限制；原始文件私有存储、按组织隔离；审计留痕。</li>
|
||
<li><strong>本地 SQLite 模式</strong>仅限页面测试与开发回归，高精度金额聚合与财务验收请使用 PostgreSQL 环境（见 README）。</li>
|
||
</ul>
|
||
<div class="warn">本文档面向使用者描述当前交付能力；全部需求完成情况与上线门禁以 <code>docs/acceptance.md</code> 为准。</div>
|
||
</section>
|
||
|
||
</main>
|
||
</div>
|
||
|
||
<footer>TraceIQ 使用文档 · 2026-09-26 · 与代码当前版本同步维护</footer>
|
||
|
||
</body>
|
||
</html>
|