chore: import existing codebase as baseline

2026-09-26 01:12:10 +08:00
commit 0ac0c4eb56
77 changed files with 14155 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 验收状态与上线门禁
+
+日期：2026-09-24，Asia/Singapore。本文区分实现状态和验证状态，不把编译成功等同于生产商用验收。
+
+## 公式工作簿与对话新增列
+
+本轮新增校验：对话模型、导出 API 及最终工作簿生成器均只允许引用当前数据映射可计算的指标；模型误报完整或客户端绕过对话直接提交时，服务端仍会拒绝缺少来源字段的自定义列。
+
+> **当前发布判断：** 本轮后端 61 passed、finance 覆盖率 87.66%；公式工作簿版本 3 已改为流式写入，100,000 行产品上限实测峰值 RSS 约 136.4 MB。新增列流程覆盖追问、补充、定义确认、数据映射可用性防护及公式工作簿下载。LibreOffice 重算测试覆盖特定黄金样例；Microsoft Excel、财务口径签字、真实 AI 合规、原附件 332,830 行范围方案及目标环境部署仍未验收。
+
+| 需求 | 状态 | 实现 / 尚缺内容 |
+| --- | --- | --- |
+| 对话定义自定义列 | 已实现；mock 端到端通过 | 用户描述列名、含义、范围及计算；缺项时模型主动追问，补充后结合全对话重审；只接受既有指标/常数和白名单运算树。编辑补充时保留当前定义供核对，未发送的草稿会禁用确认；最多 6 轮，限 10 列、8 层表达式。真实外部模型联调未做。 |
+| 自定义列公式导出 | 已实现；小样本验证通过 | 异步任务生成 XLSX；自定义列引用汇总指标公式，并包含使用说明、参数口径、计算明细、原始证据和对账页；另保留原有证据快照导出。 |
+| Excel 公式引擎验收 | 尚未通过发布门禁 | 消费人数与升单率改用随机去标识 CustomerRoster 固定人数表 + COUNTIFS，不依赖 UNIQUE/FILTER；4 项 LibreOfficeDev 重算测试已通过。Microsoft Excel 仅打开过样本并在公式栏看到 COUNTIFS/SUMIFS；Excel 为只读无法保存重算副本，且所见分组与预期不匹配，故 Excel 实机重算结果仍未验收。身份、分组和期间是固定快照，编辑金额可重算，不支持通过改客户身份改变人数。 |
+| 生产上线资格 | 未完成 | 公式导出最大 100,000 行/200 组，真实附件 332,830 行尚不能一次导出；真实 AI 服务联调、数据出境审批、目标 Excel 兼容、性能及安全审查均未完成。 |
+
+## 最新验证（2026-09-24）
+
+- 对话新增列及公式导出回归：后端全量 `61 passed`，finance 覆盖率 `87.66%`；新增用例覆盖流式工作簿、精确文本条件、未分类对账、Excel 长度限制、公式注入、保留列冲突、任务文件权限/路径、授权快照顺序和路径准备失败恢复。
+
+- 当前源码自动化基线（2026-09-24）：61 passed，finance 覆盖率 87.66%（85% 门槛）；包含列定义追问、数据映射可用性防护、流式导出和 LibreOffice 公式重算回归。Ruff lint/format、TypeScript/Vite 构建、Django check、迁移检查通过。
+- 本轮隔离 SQLite Playwright：3 passed、1 skipped；新增列追问与下载、桌面综合工作流、手机布局通过；原附件 UI 用例因未设置 `REFERENCE_DATASET_NAME` 跳过。隔离数据库和媒体目录位于 `/tmp/caiwu-roadmap-e2e*`；登录成功的正式用例使用临时口令环境变量。
+- 完整临时生产配置下 `check --deploy` 无告警；pip-audit 和 npm audit 均为 0 已知漏洞。Docker 镜像构建未运行（Docker daemon 不可连接），Compose 校验未运行（真实 `.env` 不存在）。
+- 真实附件 PostgreSQL 17 对账通过：332,830 行、5 个分组，收入/毛利/人数与历史独立对账一致，缺成本 332,830 行、ROI 不可用。完整公式工作簿生成基准 96.94 秒、51,532,457 字节、峰值 RSS 3,308,617,728 字节；单机单次生成不等于资源/SLA 通过。
+- 本轮以安装的 LibreOfficeDev 执行 `tests/test_formula_recalculation.py`（3 项）与 `tests/test_formula_recalculation_gross.py`（1 项）：共 4 项通过，覆盖自定义汇总/变化率、编辑明细金额后的联动、零成本 ROI、缺失基期，以及 direct/lookup 毛利来源。该结果不是 Microsoft Excel 实机验收。
+- 流式容量基准：公式版本 3 的 20,000 行合成工作簿生成 5.26 秒、3,265,273 字节、峰值 RSS 77,922,304 字节；100,000 行生成 25.96 秒、16,217,767 字节、峰值 RSS 136,429,568 字节。100,000 行产物 ZIP/OOXML 完整性、7 个工作表、表格关系、版本及汇总公式读取通过；这是本机隔离 SQLite 单次基准，不是目标环境并发 SLA。
+- Microsoft Excel 桌面检查记录：在只读 Excel 中打开 `/tmp/caiwu-excel-validation.xlsx`，公式栏可见 COUNTIFS/SUMIFS；无法保存重算副本，且所选样例分组为 `Test`、与预期不匹配。结果仅证明样本中存在公式，不证明 Excel 计算正确，发布门禁维持未通过。
+- `compose.yaml` 已配置 `cleanup_formula_exports --loop` 常驻清理服务，清理逻辑有 3 项测试覆盖；目标环境仍需确认运行与告警。
+
+## 剩余功能与发布阻断
+| P0 | Microsoft Excel 公式引擎验收 | 已有 LibreOfficeDev 小样本公式缓存证据，仍需目标 Excel Windows/Mac 重算和兼容性验收。 |
+| P0 | 真实附件范围与业务口径 | 100,000 行/200 组产品上限已用流式版本实测；原附件 332,830 行仍超范围，需选择可审计分卷或正式提高上限后再验。财务签字仍未完成。 |
+| P0 | 真实 AI 合规与商用环境 | 真实模型联调、数据出境/隐私审批和目标环境安全验证尚缺。 |
+
+| 优先级 | 未完成项 | 发布影响 / 下一步 |
+| --- | --- | --- |
+| P0 | Microsoft Excel 公式引擎验收 | 人数公式使用静态去重辅助表 + COUNTIFS；仍需目标 Excel Windows/Mac 打开、重算、保存，覆盖人数、升单率、空集、缺期及金额编辑后的计算。 |
+| P0 | 真实附件全量公式导出 | 当前上限 100,000 明细行/200 分组，原附件 332,830 行；100,000 行流式资源压测已完成，仍需定义切分导出并保证跨文件口径，或批准扩大产品范围后做 332,830 行目标引擎验收。 |
+| P0 | 财务业务口径签字 | 确认 N 列实际收入与 I 列实收、退款、成本归属、毛利、ROI、升单、自营产品集和舍入规则；真实附件成本缺失且 ROI 不可用。 |
+| P0 | 外部 AI 合规与真实联调 | 完成真实模型超时/限额/故障演练、数据出境和隐私审批；未批准前保持 AI 关闭。 |
+| P1 | 对话定义可扩展性 | 当前仅支持既有指标/常数与加减乘除；不支持任意 Excel 函数、跨明细新聚合、按零替代/跳过缺失、生成维度列或保存复用定义。新能力需逐项安全与黄金样例验证。 |
+| P1 | 工作簿操作完整性 | 当前固定导出范围，不支持在 Excel 增加明细行后自动扩展所有报表；结构变化需重新导出。验证参数编辑、结构变化提示、模板版本和列字典。 |
+| P1 | 定义体验差距 | 证据弹窗已支持本期/基期切换并通过 E2E；公式定义对话仍没有持久化草稿/定义库。确认复用范围后实现并补 E2E。 |
+| P1 | 商业部署验收 | Docker 构建、HTTPS/证书、PostgreSQL/TLS、备份恢复、并发/SLA、审计监控、渗透测试、AG Grid Enterprise 商用许可需在目标环境验证/审批。 |
+
+
+
+
+## 需求覆盖
+
+| 需求 | 状态 | 实现 / 尚缺内容 |
+| --- | --- | --- |
+| 网页前端、手机适配 | 已实现，本地浏览器回归 | React + 响应式 CSS，无原生客户端 |
+| XLSX/CSV、双行表头、解释型映射 | 已实现 | 标准别名建议 + 人工确认，不宣称通用 AI 自动识别全部表格 |
+| 原始文件版本、重复上传、失败回滚 | 已实现并测试 | SHA-256 组织内唯一，源文件私有，成功版本不可修改 |
+| 收入/毛利/成本/ROI/人数/客单价 | 已实现并测试 | 缺字段返回不可用；ROI 在导入时明确公式 |
+| 自营收入/升单率/原价客单价 | 已实现并测试 | 新导入配置 self_operated_products；旧版本未配置时不可用，不偷偷改历史口径 |
+| 同比/环比/自定义多月 | 已实现并测试 | 基期等长且不能重叠，缺失期间不比较 |
+| 趋势/贡献/矩阵/异常列表 | 已实现 | ECharts 折线/横条图，非完整瀑布/Pareto/散点套件 |
+| 动态下钻/面包屑/证据 | 已实现并测试 | 来源、区域、科室、学科、产品等映射维度；医生仅有字段才出现 |
+| 设置保存/取消/预览、调查状态 | 已实现并测试 | 个人设置版本锁，调查按上下文持久化；没有团队工单分派 |
+| CSV/Excel 导出 | 双模式已实现 | 既有 CSV/XLSX 为证据快照；公式 XLSX 为独立异步工作簿，含自定义公式列、说明页和固定人数去重辅助表。Microsoft Excel 引擎和全量附件门禁未通过，不可视为生产验收 |
+| 账号/组织/科室权限/CSRF/审计 | 已实现并测试 | 应用层隔离；无数据库 RLS、SSO、MFA、自助密码找回 |
+| Copilot | 本地规则助手可用；外部接口已实现 | 外部模型成功/拒答/非法意图以 mock 测试，尚未真实 API 联调 |
+| AG Grid Enterprise | 部分接入 | 授权后注册模块；SSRM/Pivot/Tree Data/Master-Detail 未实现；现在使用服务端聚合 + 分页证据 |
+| 全部过渡表口径重建 | 未完成 | 消费比率、实收/实际收入多口径、跨表 lookup 编辑、生效期毛利率、退款口径切换仍缺 |
+| 异常规则 | 基础实现 | 不利变化率 + 影响金额 + 两期样本数；结构占比、历史分位数、告警投递尚未实现 |
+| 原始附件 | 全量已导入并对账 | 不含医生/成本；只有两个单月，不允许虚构连续期间 |
+| Docker/HTTPS/CI | 配置已交付，验证不完整 | Compose 使用示例环境文件替换后的配置校验通过；基础镜像 metadata 下载长时间无响应，已取消构建；无正式域名证书与远端 CI 运行记录 |
+
+原始附件“过渡表2”同时使用“实收金额”“收入”“实际收入”字样，产品扣率分子存在歧义。当前产品扣率与客单价明确使用选定的实际收入字段，原附件采用 N 列；不能直接当作 I 列实收口径通过财务签字。旧导入版本也不会因为新代码增加自营产品范围而静默更改映射。
+
+## 真实数据对账
+
+来源 SHA-256：`98ef41e898c24f0929a9da6ec185b7331f69f0478b52056cbc7834e1ef5877ec`。
+
+| 指标 | 2025-08 | 2026-08 |
+| --- | ---: | ---: |
+| 明细行数 | 157512 | 175318 |
+| N 列实际收入 | 225550255.4187610638720 | 152419115.348455502666069 |
+| 产品毛利贡献 | 24790335.405853982758000 | 17868580.85186759073400145 |
+| 去重消费人数 | 33147 | 38361 |
+
+总计 332830 行；收入同比 -32.4234%，毛利贡献同比 -27.9212%；ROI 不可用。独立逐行读取与数据库精确聚合一致，科室贡献变化合计等于总体变化。原数据 11990 行收入超过 4 位小数，未在落库时四舍五入到 4 位。
+
+质量核查：负收入 12338 行、G/L 应收差异 14154 行、I/N 实收与实际收入差异 11991 行、成本缺失 332830 行、毛利率未匹配 0 行。本机单次完整查询约 3 秒，仅为一次开发机测量，不是并发性能 SLA。
+
+## 测试记录
+- 本轮源码测试：44 passed，finance 覆盖率 86.95%；常规 pytest 在本机 SQLite 测试配置运行，独立 PostgreSQL CI 未启动；另在本机 PostgreSQL 17 隔离库执行原附件对账和完整公式工作簿生成基准。
+- 本轮浏览器回归：完整隔离 SQLite Playwright 3 passed、1 skipped；跳过未配置 `REFERENCE_DATASET_NAME` 的原附件 UI 专测。
+
+- PostgreSQL 17：67 项后端测试通过（22.32 秒），finance 总覆盖率 89.17%，analysis 98%、assistant 90%、importing 86%、views 84%；CI 覆盖率门槛 85%。
+- 检查内容：Decimal 金额、人数去重、加权比率、零分母、退款、缺期、新增/消失分组贡献、XLSX 表头与 lookup、导入原子性、重复上传、非法映射、跨组织/科室隔离、CSRF、会话、登录限流、设置冲突、调查记录、导出公式注入、模型意图白名单与敏感字段最小化、worker 恢复、CLI 初始化。
+- TypeScript / Vite 生产构建通过；Django `check`、迁移检查及完整临时生产变量下的 `check --deploy` 均通过。目标部署环境仍未验收。
+- Python pip-audit 与前端 npm audit（生产依赖）均报告 0 个已知漏洞；这不是渗透测试或未来无漏洞保证。
+- 既有 Playwright 历史记录：3 项用例通过；当前分支 E2E 覆盖见上方 2026-09-24 最新验证，不能用历史结果替代本轮重跑。
+- 回归发现并修复调查控件标签定位与图表网格最小宽度问题。原附件截图为 `reference-desktop.png` / `reference-mobile.png`；截图文件已生成，但工具未可靠展示图片供逐像素人工复核，视觉精修仍应由产品人员验收。
+- 新增可信代理登录限流测试：未启用信任时忽略伪造客户端头，启用后仅接受合法 IP。生产 Caddy 覆盖 X-Real-IP，web 不得直接暴露公网。
+- 产物位于本机 `test-results/`、`playwright-report/`，未提交真实财务数据和凭据。
+
+## 必须完成的上线门禁
+
+1. 财务负责人确认收入/实收/原价、退款、升单、自营、成本归属与 ROI 定义；补齐缺失的业务口径和字段。
+2. 若要求原开发计划全部功能，补齐上述未完成项并逐项签字。当前版本不能标记为“所有前后端需求已完成”。
+3. 在目标基础设施完成 Docker 镜像构建、HTTPS、数据库认证/TLS、上传限制、非 root 容器及重启恢复验收。
+4. 用目标并发用户数、最大文件/维度基数做导入与查询压力测试，确定 SLA 和资源配额。当前聚合会返回所有分组，高基数维度需 SSRM 或服务端结果窗口。
+5. 完成真实 OpenAI 接口联调、超时/限额演练和数据出境/隐私审批；没有审批时保持关闭。
+6. 外部安全审查与渗透测试、最小权限数据库账号、密钥轮换、加密存储、访问日志脱敏、不可变审计与告警接入。
+7. 执行数据库 + 源文件一致性备份及恢复演练，记录 RPO/RTO，确定留存和删除流程。
+8. AG Grid Enterprise 若启用须有适用商业许可；完成所有依赖许可证盘点。
+
+以上商用门禁不因本地自动化测试通过而自动满足；较早的 44、54 项测试及旧非流式 332,830 行峰值 RSS 约 3.31 GB 均为历史基线，不能替代当前版本的目标环境验收。