TraceIQ 未实现功能与测试指南

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。

编号	级别	问题	修复后怎么测
F01	P0	公式导出失败清理可能沿符号链接父目录删除非任务文件（`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. 发布门禁（必须由外部关闭）

级别	门禁	责任方	关闭证据
P0	Microsoft 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 skipped	2026-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 E2E	3 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