From cd07ba1887d69cabb9e321e1c9a6edefb8039ef2 Mon Sep 17 00:00:00 2001 From: Jayway Liu <14022498+bluejayway@user.noreply.gitee.com> Date: Sun, 11 Oct 2026 09:45:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=B8=8E=E6=9C=AA=E5=AE=9E=E7=8E=B0=E5=8A=9F=E8=83=BD/?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - user-guide.html：面向使用者的完整操作说明（含 AI 模型配置） - gaps-and-testing.html：未实现功能清单、F01-F08 状态、发布门禁与 分层测试方法、验收矩阵、当前基线 - README 加入口链接 --- README.md | 2 +- docs/gaps-and-testing.html | 322 +++++++++++++++++++++++++++++++++++++ docs/user-guide.html | 316 ++++++++++++++++++++++++++++++++++++ 3 files changed, 639 insertions(+), 1 deletion(-) create mode 100644 docs/gaps-and-testing.html create mode 100644 docs/user-guide.html diff --git a/README.md b/README.md index 7cc9f91..411ac99 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # TraceIQ 财务分析工作台 -响应式 Web 前端 + Django API + PostgreSQL。基于分享会话、医院财务 Excel 原始附件及 AG Grid 开发计划实现，当前交付是可运行、经过本地回归的核心业务版本，不等于全部需求完成或已获生产上线认证。缺口与上线门禁见 [验收状态](docs/acceptance.md)。 +响应式 Web 前端 + Django API + PostgreSQL。基于分享会话、医院财务 Excel 原始附件及 AG Grid 开发计划实现，当前交付是可运行、经过本地回归的核心业务版本，不等于全部需求完成或已获生产上线认证。缺口与上线门禁见 [验收状态](docs/acceptance.md) 与 [未实现功能与测试指南](docs/gaps-and-testing.html)，使用者操作说明见 [使用文档](docs/user-guide.html)。 ## 已实现 diff --git a/docs/gaps-and-testing.html b/docs/gaps-and-testing.html new file mode 100644 index 0000000..4db123d --- /dev/null +++ b/docs/gaps-and-testing.html @@ -0,0 +1,322 @@ + + + + + +TraceIQ 未实现功能与测试指南 + + + + +
+
+

TraceIQ 未实现功能与测试指南

+

距离生产商用还差什么 · 每一项怎么测 · 2026-10-08 更新

+
+
+ +
+ + +
+ +
+

1. 结论摘要

+

当前版本不能认定为生产商用完成。核心分析链路（导入 → 总览 → 异常 → 下钻 → 证据 → 导出）已经实现并通过自动化回归；仍有一批 P1/P2 产品功能缺口，以及必须由外部环境和业务方关闭的发布门禁（Excel 实机、财务签字、真实 AI 合规、目标基础设施）。

+
2026-10-08 工程整改：F01–F08 已完成代码修复并补充专项回归；本轮又完成网页自定义列、定义草稿恢复、版本历史、个人/团队共享、公式工作簿输入校验与保护、大文件下载直传。Excel 实机仍是独立门禁。
+
2026-10-11 复核：对当前工作区重新全量验证——ruff/格式/迁移检查通过，SQLite 后端 73 passed（4 skipped），前端构建通过，Playwright 4/4 通过（含原附件验收用例，原附件数据集仍在本机库中）。F01–F08 修复确认有效，无需重复修复；剩余开放项见第 3、4 节。
+

状态口径：本文区分"源码静态确认"（读代码即可判断、尚无专项复现测试）与"实测通过"（有自动化结果）。清单整合自 docs/acceptance.md、docs/remaining-issues-2026-09-26.html 与 2026-09-27 的修复记录；细节以那两个文档为准，本文是单一入口。

+ + + + + +
类别数量最高优先级
已关闭代码问题（F01–F08）8专项回归通过
未实现功能（产品边界）约 7 项P1
发布门禁（外部责任）5 组P0 ×3
+
2026-09-27 已完成、不再属于"未实现"的内容：AI 模型页面配置（云端/本地多模型选择）、证据金额 24 位小数修复、KPI 折行、图表轴标签、表格列遮挡、内部键名暴露等 UI 问题修复。详见第 8 节基线。
+
+ +
+

2. 代码问题与修复记录（F01–F08）

+

以下是历史问题及其当前修复后的验收方式；详细位置与原始建议见 remaining-issues-2026-09-26.html。

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
编号级别问题修复后怎么测
F01P0公式导出失败清理可能沿符号链接父目录删除非任务文件（finance/exporting.py）父目录链接到受保护目录并预置同名文件：执行必须失败、受保护文件字节不变、任务标记 failed；覆盖根目录链接/目标链接/写盘失败/正常重试
F02已修复清理失败被静默吞掉，失败任务的孤儿 .xlsx 缺少回收路径注入 unlink 权限错误：任务仍 failed、有可观察告警；恢复权限后回收成功且不影响其他任务文件
F03已修复证据弹窗重复点击当前期间会让列表停在"加载中"（EvidenceDialog.selectSide）重复点击当前期间、快速本期/基期切换、第二页切期间、空列表、请求失败——均不显示过期数据或永久加载（Playwright E2E）
F04已修复载入已保存定义后追问，没有把原定义带给模型，指代修改不可靠保存定义 A → 重开载入 A → 发送依赖 A 的修改：检查模型请求实际包含 A；未发送补充时禁止生成
F05已修复定义库 50 条上限非原子约束；同名更新最后写入覆盖、无 revision 冲突检测；审计不在同一事务PostgreSQL 下并发保存不得产生第 51 条；两个标签页更新不静默丢失；模拟审计写入失败后定义变更回滚
F06已修复工作簿参数页把毛利率标为"可编辑"但实际公式引用每行 MarginRate，修改不联动每个标为可编辑的输入都对应真实依赖；收入/成本/原价/直接毛利/lookup 毛利率分别改值重算验证
F07已修复对账统一用 0.01 阈值，人数/金额/比率混用；自定义列无独立服务器参考值阈值边界、大数、抵消、极小值、除零、缺失、多层表达式独立黄金样例通过；容差需先经财务确认
F08已修复导出任务执行/下载阶段不重新校验角色；撤权后的下载政策未定义；缺超时/崩溃恢复测试排队后撤权、成功后撤权按签署政策处理；半成品不可下载；worker 崩溃重启不重复发布或卡死在 processing
+

F01–F08 当前均有代码修复和自动化回归；后续验收重点转为 PostgreSQL 并发、Excel 实机和目标部署环境。

+
+ +
+

3. 未实现功能（产品边界）

+ + + + + + + + + + + +
级别功能当前缺口
已实现新列进入网页汇总表从定义库选择的列由服务端安全计算并显示在主分析表、汇总和分组行；E2E 覆盖选择后显示
已实现多列编辑与定义生命周期网页最多选择 10 列；对话草稿会话恢复，定义支持最近 20 个版本、个人更新与全范围账号共享
P1适用范围与表达式能力scope 只是说明文本；不支持任意条件、跨明细新聚合、Excel 函数、维度列、缺失替代策略
部分完成Excel 内编辑防误操作结构、证据、人数和公式工作表已保护；计算明细仅收入/成本/毛利输入/毛利率/原价金额解锁并带数值校验。增删明细行仍需重新导出
P1原附件 332,830 行全量导出产品上限 100,000 行/200 组，原附件一次导不全；需可审计分卷或正式提高上限后再验收
P1结果缓存与大文件下载公式下载已改为浏览器直传，避免前端 Blob 全量驻留；openpyxl/LibreOffice 计算缓存与 /tmp 容量仍需目标环境方案
P1高基数与可访问性聚合分组全量返回，无 SSRM/结果窗口；无键盘/屏幕阅读器/平板专项
P2扩展业务能力多收入字段口径、消费比率、生效期毛利率、退款策略、结构占比、历史阈值、告警渠道、团队调查分派
P2跨平台与高级网格无原生客户端；AG Grid SSRM/Pivot/Tree Data/Master-Detail 未接入（需 Enterprise 许可）
+
本轮 P1 完成：网页自定义列、多列选择、定义草稿恢复/版本历史/共享、Excel 受保护输入与校验、公式下载直传。仍开放：任意条件与跨明细聚合、33 万行分卷/容量、结果缓存、高基数窗口、无障碍专项，以及第 4 节外部发布门禁。
+
另外：趋势/贡献图为 ECharts 折线+横条，不是完整瀑布/Pareto/散点套件；异常规则只有变化率+影响额+样本数，无结构占比、历史分位数与告警投递；无团队工单分派。这些属于需求范围决策，开发前先冻结业务定义。
+
+ +
+

4. 发布门禁（必须由外部关闭）

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
级别门禁责任方关闭证据
P0Microsoft Excel 实机验收财务、QA、目标终端负责人可编辑 Windows/Mac Excel 打开受控样例 → 强制重算 → 保存；改值后依赖链正确；覆盖人数、升单率、空集、缺期
P0财务业务口径签字财务负责人签署收入/实收/原价、退款、成本归属、毛利、ROI、自营、升单与容差；原附件成本全缺，ROI 保持不可用
P0真实 AI 联调与数据合规合规、数据负责人、AI 服务负责人数据处理/出境审批、模型版本与留存策略；真实验证超时/拒答/限流/非法输出。批准前保持 AI 关闭
P1目标基础设施验收运维、安全镜像构建、迁移、非 root/卷权限、TLS、代理、数据库认证、队列、备份恢复、日志脱敏、安全扫描、许可证
P1当前版本 PostgreSQL 与 SLA工程 + 运维在独立 PostgreSQL 跑当前全量测试、并发定义保存、worker 恢复、导出压力；记录 P95、资源预算、RPO/RTO
+
AI 联调现在可以在页面完成配置：管理 → AI 模型，选择 OpenAI 或本地 OpenAI 兼容服务（Ollama / LM Studio / vLLM），"获取可用模型"可多选本地模型。配置入口已实现（见使用文档第 9 节），但"真实模型联调 + 合规审批"这一门禁仍然开放。SQLite 仅用于开发回归，金额验收必须用 PostgreSQL。
+
+ +
+

5. 测试环境准备

+

5.1 快速启动（SQLite 轻量开发库）

+ 
scripts/dev_up.sh            # 迁移 + 管理员 + 前端构建 + API + worker，自动健康检查
+scripts/dev_up.sh --stop     # 停止
+

登录凭据在 var/local-access.txt（用户名 admin，随机密码，权限 0600）。

+

5.2 PostgreSQL（财务验收必需）

+ 
/opt/homebrew/opt/postgresql@17/bin/pg_ctl -D var/postgres -l var/postgres.log \
+  -o '-h 127.0.0.1 -p 55432' start
+export DATABASE_URL='postgresql://jianwel@127.0.0.1:55432/traceiq'
+
SQLite 不保证高精度金额聚合，禁止用于财务验收和生产。对账脚本 scripts/reconcile_reference.py 明确要求 PostgreSQL。
+

5.3 Playwright 浏览器

+ 
npx playwright install chromium   # 首次执行
+
+ +
+

6. 分层测试方法

+

6.1 静态检查与后端单测（每次改动都跑）

+ 
uv run ruff check server finance tests scripts
+uv run ruff format --check server finance tests scripts
+uv run python manage.py makemigrations --check --dry-run
+uv run pytest --cov=finance --cov-report=term-missing --cov-fail-under=85
+

6.2 前端构建与浏览器 E2E

+ 
npm run build
+E2E_PASSWORD='<测试口令>' npm run test:e2e
+

E2E 需要正在运行的本地 API + worker；会真实导入测试 CSV 数据集，不可指向生产环境。覆盖：导入确认、总览 KPI、异常下钻、调查保存、证据分页、设置乐观锁、Copilot、公式工作簿追问与下载、手机布局无横向溢出。

+

6.3 原附件验收用例（本机显式启用）

+ 
REFERENCE_DATASET_NAME='分析数据_原稿(1).xlsx' E2E_PASSWORD='<口令>' npm run test:e2e
+

断言：KPI 精确值（收入 152,419,115.35、毛利 17,868,580.85、人数 38,361）、环比缺 2026-07 禁比、同比 -32.4%、移动端无溢出、无页面脚本错误。附件文件不在仓库中，需本机提供。

+

6.4 真实数据对账（PostgreSQL）

+ 
PYTHONPATH=. uv run python scripts/reconcile_reference.py
+

断言 332,830 行、收入/毛利/人数与历史独立对账一致（误差 0）。原附件 SHA-256：98ef41e898c2…。

+

6.5 公式工作簿重算

+ 
uv run pytest tests/test_formula_recalculation.py \
+          tests/test_formula_recalculation_gross.py   # LibreOffice 重算，7 项
+

LibreOffice 通过 ≠ Excel 通过；Microsoft Excel 实机重算是独立门禁（第 4 节）。

+

6.6 安全与部署检查

+ 
uv run pip-audit
+npm audit --omit=dev
+uv run python manage.py check --deploy   # 需完整生产环境变量
+
依赖审计为 0 漏洞 ≠ 渗透测试通过；check --deploy 无告警 ≠ 基础设施验收通过。
+
+ +
+

7. 验收矩阵：每项怎么算"完成"

+ + + + + + + + + + +
目标通过标准手段
F01–F08 修复各有"修复前失败、修复后通过"的专项断言；覆盖率 ≥ 85%pytest + Playwright（见第 2 节每行）
AI 配置功能保存/脱敏回显/权限/模型列表/助手走配置，接口级测试通过tests/test_assistant_api.py（已实现）
金额精度证据与导出无存储尺度尾零；对账 0 误差test_evidence_amounts_trim_storage_scale + reconcile_reference.py
Excel 引擎门禁目标 Excel 改值重算、保存、重开一致人工按受控样例执行并记录版本与结果（第 4 节）
财务口径门禁财务负责人签字确认口径与容差签字文件；不以技术测试替代
AI 合规门禁审批完成 + 真实模型故障演练通过页面配置真实模型后做超时/拒答/限流演练
基础设施门禁镜像构建、TLS、备份恢复演练、RPO/RTO 记录docker compose + 恢复演练
性能/SLA目标并发下导入/查询 P95 达标；高基数有方案压力测试；高基数维度需 SSRM 或服务端窗口
+
+ +
+

8. 当前基线（最近一次实测）

+ + + + + + + + +
项目结果日期 / 环境
后端单测（本轮复核）73 passed，4 skipped2026-10-11，SQLite 测试库
Playwright E2E（本轮复核）4 passed（桌面综合、手机布局、公式导出、原附件验收）2026-10-11，本地 API + worker
后端单测77 passed，finance 覆盖率 88.45%（门槛 85%）2026-10-08，SQLite；PostgreSQL 77 passed
Playwright E2E3 passed，1 skipped（原附件用例未启用）2026-10-08，本地 API + worker
本轮修复F01–F08、网页自定义列、多列选择、草稿恢复、版本历史与共享、Excel 输入校验/公式保护、公式下载直传；PostgreSQL 运行与 Excel 实机仍需门禁2026-10-08
历史基线（勿直接引用）PostgreSQL 67 项、61 项、44/54 项等旧记录，以及 332,830 行旧峰值 RSS 3.31 GB历史，见 acceptance.md
+

相关文档

+ +
多个历史文档之间存在状态冲突（如"没有定义库"等旧表述）。后续应统一维护单一验收入口，历史文档标题注明"历史"。本文不是上线授权。
+
+ +
+
+ + + + + diff --git a/docs/user-guide.html b/docs/user-guide.html new file mode 100644 index 0000000..fb592c6 --- /dev/null +++ b/docs/user-guide.html @@ -0,0 +1,316 @@ + + + + + +TraceIQ 财务分析工作台 · 使用文档 + + + + +
+
+

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

+

面向使用者：导入财务表格 → 总览与对比 → 异常追踪与下钻 → 证据核查与导出

+
+
+ +
+ + +
+ +
+

1. 快速开始

+

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

+
    +
  1. 在仓库根目录执行 scripts/dev_up.sh（自动完成迁移、管理员初始化、前端构建并启动服务）。
    2. +
  2. 浏览器访问 http://127.0.0.1:8000。
    3. +
  3. 使用管理员账号登录（本地凭据见 var/local-access.txt，文件权限 0600）。
    4. +
+ + + + +
环境用户名密码
本地开发（本机）admin见 var/local-access.txt（每次初始化随机生成）
自动化测试admin测试专用库随机生成，可用环境变量 E2E_PASSWORD 指定
+
停止服务：在运行 dev_up.sh 的终端按 Ctrl-C，或另开终端执行 scripts/dev_up.sh --stop。
+
+ +
+

2. 界面导览

+

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

+ + + + + + + + + +
分组入口说明
工作台经营总览核心指标、走势、指标矩阵与同比/环比对比
异常追踪超出阈值的分组列表，可进入调查；有新异常时入口显示数量角标
数据管理数据集列表、导入新表格、数据来源与字段字典、公式工作簿导出
管理分析设置默认比较方式、默认指标、异常阈值等个人偏好
账号与权限仅全权限管理员可见：查看账号、角色、状态、科室范围
操作审计仅全权限管理员可见：时间、用户、操作、资源、详情
AI 模型仅全权限管理员可见：配置助手使用的云端或本地模型服务
+

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

+
+ +
+

3. 导入数据

+

3.1 支持的文件

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

3.2 导入流程

+
    +
  1. 在「数据管理」页点击 导入新表格，选择文件上传。
    2. +
  2. 系统在弹窗中展示识别出的字段，请逐项确认导入字段映射：期间、科室等业务维度、实际收入、成本、毛利贡献、客户编码、应收金额等。
    3. +
  3. 选择 ROI 公式口径与自营产品范围后，点击 确认并导入。
    4. +
  4. 导入由后台 worker 异步处理，完成后数据自动出现在总览中；列表中可查看状态、数据质量与导入版本。
    5. +
+
+ 去重：同一组织内完全相同的文件（SHA-256）不会重复导入。
+ 原始解释：原始表头说明随数据保留，可在「数据来源与字段字典」中查看，保证指标口径可追溯。 +
+
原附件中没有的维度（如医生、成本、连续月度数据）不会产生对应排名或环比结论；系统不会虚构数据。
+
+ +
+

4. 经营总览

+

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

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

比较方式

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

5. 异常追踪与下钻

+

5.1 异常列表

+

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

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

5.2 下钻与面包屑

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

6. 贡献分解

+

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

+
    +
  • 分组变化贡献图：当前层级各分组对本期与基期差额（变化额/变化贡献）的分解。
    • +
  • 调查范围子级贡献图：在所选分组内部，按下一级维度继续分解。
    • +
+
贡献分解只基于权限范围内的数据；科室范围受限的账号看不到范围外的分组。
+
+ +
+

7. 证据与导出

+

7.1 证据明细

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

7.2 导出

+
    +
  • 导出当前范围：将当前筛选与下钻范围内的证据导出为 CSV 或 XLSX；Excel 中精确金额以文本单元格导出，避免 15 位有效数字精度丢失。
    • +
  • 生成公式工作簿：在「数据管理」中生成带公式的 Excel 工作簿，含列计算描述，便于财务同事复核口径。
    • +
+
客户端不会一次加载全部明细（大文件可达 33 万行），只按需拉取聚合结果与分页证据。
+
+ +
+

8. 分析设置

+

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

+ + + + + + + +
设置项作用
默认比较同比 / 环比
默认指标总览与矩阵默认展示的指标
异常阈值判定异常的变化幅度阈值
最小影响额低于该金额的变化不列为异常，避免噪声
最小样本数样本量过小的分组不参与异常判定
+

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

+
+ +
+

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

+

9.1 使用助手

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

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

+

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

+ + + + + + + + + + + + + + +
服务商说明Base URL 示例API Key
OpenAIOpenAI Responses 接口https://api.openai.com/v1（可留空使用默认）必填
本地 OpenAI 兼容服务Ollama、LM Studio、vLLM 等任何兼容 OpenAI 协议的服务Ollama：http://127.0.0.1:11434/v1
LM Studio：http://127.0.0.1:1234/v1		通常可留空
+
    +
  1. 选择服务商，填写 Base URL（本地服务必填）。
    2. +
  2. 填写 API Key（本地服务通常可留空）。
    3. +
  3. 点击获取可用模型：系统从服务的 /v1/models 接口拉取模型列表。本地服务装了多个模型（如 Ollama 里的 qwen2.5:7b、llama3.1:8b）时，可在下拉列表中挑选，不用手敲名字。
    4. +
  4. 选中模型后勾选「启用 AI 模型理解问题」，点击保存配置。
    5. +
  5. 回到页面顶部打开「财务分析助手」，勾选「使用已配置的 AI 模型理解问题」并同意后即可提问。
    6. +
+
+ 配置规则：每个组织一份配置，保存在数据库中，优先于部署环境变量（未配置时回退到 + AI_ENABLED / OPENAI_API_KEY / OPENAI_MODEL / OPENAI_BASE_URL）。 + 仅全权限管理员（未限科室范围的管理员角色）可查看和修改；限域管理员、分析师、查看者无此入口。 +
+
+ 密钥安全：API Key 只保存在后端，页面只显示「已配置」，读取接口不回传密钥原文； + 再次保存时留空表示保持原密钥不变。每次配置修改都会记入操作审计（只记服务商、模型与是否启用，不记密钥）。 +
+

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）。
    • +
+
本文档面向使用者描述当前交付能力；全部需求完成情况与上线门禁以 docs/acceptance.md 为准。
+
+ +
+
+ + + + +