Agent-System/.doc/remediation/2026-09-17-initial-load-performance-plan.md

title, status, created, updated, artifact_contract, product_contract_source, execution

title	status	created	updated	artifact_contract	product_contract_source	execution
首次加载与工作台初始化性能改进方案	planned	2026-09-17	2026-09-17	ce-unified-plan/v1	ce-plan-bootstrap	code

首次加载与工作台初始化性能改进方案

Goal Capsule

让用户首次访问就能快速看到并操作登录页，登录后优先恢复当前项目与会话，避免下载无关工具或等待所有项目初始化。

采用静态交付优化、按功能加载和请求去重，之后按测量结果优化认证与数据库读取（KTD1–KTD5）。本轮仅交付诊断和方案，业务代码尚未修改；用户授权实施后执行以下单元。

遵守 AGENTS.md/PROJECT.md、现有权限和文档治理契约。若优化要求改变授权、新增跨用户缓存、跳过职责正确性或删除历史数据，停止该单元并回报。每单元独立 feature/fix 分支与模块 mutex；合 dev/容器重建占集成槽。默认不推送，不晋升 test/main。

Product Contract

Problem Frame

诊断 已确认：8080 首屏 2.86 MB，CDP 10 Mbps 冷缓存登录可见 2.64 秒、2 Mbps 11.78 秒；再次访问约 60 ms。字体 CSS 外链阻塞首屏；3100 Vite 首访 207 请求/12.24 MB。登录后存在全项目成员扇出与会话重复同步，服务端认证、文档列表和会话统计有重复工作。

这些数字是单样本实验，不是用户实际公网体验或 p95。用户已确认 3100/8080/8081 在系统重启后首访约十数秒。现有容器启动到打印监听仅约 166/142 ms，不代表整机重启就绪；必须补齐重启矩阵再签优化收益。

Requirements

• R1. 首次登录页只加载认证与基础样式所需资源，外部字体不可阻塞登录表单。
• R2. 登录后先显示可用工作台骨架，优先恢复当前项目/会话；其他项目成员、管理台、导出、文件预览在需要时加载。
• R3. 相同身份和查询键的初始化请求去重；慢响应、快速切换项目、登出/换人不会写回旧状态。失败必须有局部错误与重试入口。
• R4. 所有服务端授权和文档治理保持正确，权限撤销/停用不得因缓存继续放行。计数、摘要与正文沿用相同可见性语义。
• R5. 发布后旧页面仍可打开延迟模块；缓存不得导致 HTML 长期陈旧，也不得泄露用户 API 数据；SSE 流式延迟不能回退。
• R6. 优化收益用可复现冷/热缓存、慢网、字体不可达、多项目和大历史场景证明，结果与镜像/资源 hash 绑定。

Success Criteria

以下是拟定验收预算，不是当前已达标数据。表中静态资源体积及绝对首屏时间预算适用于 8080/8081 构建入口；3100 保留 Vite 开发模式，不套构建产物压缩体积预算，其保留/空依赖缓存与预热状态分别由 U1 固定加载时间预算，U7 检查重启改善；U1 固定机器、Chromium 版本、样本与网络条件，预算不得在看到失败后悄悄放宽。

指标	目标/口径
未登录关键 JS 总传输量	开启压缩后 ≤250 KiB；按首屏实际请求总和而非只看入口文件
普通工作台首次可用前 JS 总量	≤600 KiB；不含用户明确打开的文档预览/导出模块
冷缓存登录可操作	10 Mbps / 80 ms、CPU 4 倍减速下 p75 ≤1.5 s；2 Mbps 同配置 p75 ≤3 s
登录态热刷新	10 Mbps / 80 ms、CPU 4 倍减速下工作台可操作 p75 ≤1.5 s；前提必要 API 达下行预算
登录态冷刷新/登录提交成功后恢复	冷刷新自 navigationStart 起、登录自成功响应起，当前会话历史及输入区就绪 p75 ≤3 s；仅骨架不算完成
必要首屏 API	同宿主 app↔DB 网络下 p95 ≤300 ms；列表大数据场景 p95 ≤500 ms，接口错误率不增加
首屏初始化请求	项目成员初始化从 N 次降为当前项目最多 1 次；静止初始化每个会话列表查询键最多 1 个在途请求且成功后不被成员更新重触发
字体故障	Google 域名完全阻断或延迟 10 秒时，仍满足登录预算，不发首屏外部字体 CSS 请求
无回归	同数据/设备各阶段 p95 不劣化超过 10%；无新增跨用户暴露、错误循环、重复写任务

浏览器每场景 ≥20 次，报告 p50/p75/p95 与原始样本；接口每场景 ≥100 请求、并发 1/10/30。浏览器 p95 仅小样本诊断，不能冒充线上 SLO；稳定发布后再累计真实用户分位数。

Scope Boundaries

包括浏览器入口、静态资源交付、当前工作台数据初始化、与首屏相关的查询。没有业务语义变更，不调整 PI 模型、Prompt、文档租约时长、授权范围或工作流门禁。

Deferred to Follow-Up Work：Redis/CDN、新 SSR 框架、全面 App.tsx 重写、全站统一数据框架、数据库分库、文档全文缓存。只有 U1 的证据表明必要时另开任务；目前不需要先增加基础设施。

Outstanding Questions

• 待补测：已知端口 3100/8080/8081，重启涵盖宿主机/应用/Vite 的具体范围、慢发生阶段、真实网络与设备；不会阻止可独立证明的 U2/U3，但阻止宣称用户现场问题已经彻底解决。
• 待补测：登录态瀑布、真实数据规模、SQL/连接池等待；U6 的查询改写/索引必须由这些证据选择。

Planning Contract

Key Technical Decisions

• KTD1. 保留 React/Vite + Go 架构。正式体验使用构建产物入口；3100 保留开发热更新用途，不把开发模块请求数量当生产目标。先确认真实反代 upstream，不盲改 FRP。
• KTD2. 首屏用系统字体栈；需要保留 Inter/JetBrains Mono 时仅选必需 WOFF2 并同源部署、按需加载。保留 KaTeX 渲染所需字体，但不要求登录页加载数学资源。
• KTD3. 按功能边界动态 import，登录壳与工作台隔离；管理台、DOCX/XLSX 导出、Word/Excel 预览、Mermaid 按使用加载。仅 manualChunks 拆文件不能减少关键路径下载，必须验证依赖图没有静态回引。
• KTD4. 现有 Go serveSPA 作为默认静态交付修复点，构建期生成 gzip/br（若工具链已支持）而非每请求高压缩。若真实统一代理已负责压缩，则由它单层处理并记录；不得重复编码。哈希资源 public,max-age=31536000,immutable；HTML no-cache；压缩变体 Vary: Accept-Encoding；用户 API 不共享缓存。保留 identity、HEAD、条件请求、Range 正确性。
• KTD5. 将请求状态按身份/项目/会话/过滤器键管理，先用局部 hook/loader 和在途合并解决，不强制引入新数据框架。身份切换清空缓存与取消在途请求，成员更新不作为会话获取的依赖。未知成员/权限不靠全量成员预取推导：使用服务端明确的当前用户权限摘要，未就绪保持 fail-closed。
• KTD6. 请求内复用已认证 principal，授权不跨请求长期缓存。减少 session 续期写入须明确 idle TTL/绝对过期/撤销语义后再落地，保留停用与撤销实时检查。
• KTD7. 文档列表先保留治理正确性；先补齐所有写路径与历史修复，再移出 GET 同步 heal。轮询保持原有租约新鲜度，优先复用 SSE/可见性控制与单请求在途，不能直接延长租约或无限延迟 busy 显示。

High-Level Technical Design

flowchart LR
  A[HTML与同源基础样式] --> B[轻量认证壳]
  B --> C[认证结果与工作台模块并行准备]
  C --> D[当前用户可见项目与会话]
  D --> E[当前项目权限与聊天窗口]
  E --> F[可操作工作台]
  F --> G[按需管理台/导出/预览]

有保存会话时，可在校验期间预加载不含用户数据的工作台代码；受保护 API 与用户内容显示仍由认证门禁控制。无会话时不加载工作台代码。项目/会话列表在认证后并行，解析有效当前项目后再发其范围内请求；不是让全站等待所有项目成员。

sequenceDiagram
  participant UI as 浏览器
  participant API as Go API
  participant DB as PostgreSQL
  UI->>API: 首屏必要请求（按查询键去重）
  API->>DB: 验证当前会话/用户状态
  API->>API: 请求内复用 principal / 权限解析
  API->>DB: 当前页/当前项目数据
  API-->>UI: 权限范围内的结果
  UI->>UI: 核对身份与查询代次后更新

Implementation Units

U1. 固定完整性能基线（P0，约 0.5–1 天）

Requirements: R6；后续全部单元的依赖。

Files: 新增 web/e2e/initial-load-performance.spec.ts、诊断指标辅助模块；更新 .doc/test-reports/。本轮探针与结果可作为起点。

Approach: 固定真实入口、部署 hash、登录角色、项目数/历史量，捕获资源瀑布、FCP/LCP、长任务、输入区与历史就绪、必要 API TTFB。用专用验收账号/夹具测登录，不在真实会话发送诊断消息。先检查 GET 副作用，文档列表暂有 heal，数据库分析使用只读事务和 statement_timeout。分别测空缓存、热缓存、10/2 Mbps、CPU 4x、字体失联、1/30/100 项目与大历史。本轮不重启共享服务；实施时 U7 在隔离环境重现应用/依赖/宿主启动过程，记录 ready 与第一次导航的时间关系。

Test scenarios: 新浏览器、保存有效/过期会话、无项目、普通成员与管理员、慢 API/失败、项目快速切换；每份结果保留参数与原始样本但无 token/用户正文。

Verification: 形成基线报告，能回答耗时在哪一阶段，并确认性能指标可重复。登录态测量缺失不得用未登录测试代替。

U2. 修复字体与静态资源交付（P0，约 0.5–1 天） — done 2026-09-17

Dependencies: U1 的未登录基线；Requirements: R1、R5、R6；Files: web/index.html、web/src/styles/index.css、web/vite.config.ts、internal/server/server.go、新增 internal/server/static_assets_test.go；必要时实际 Docker 构建文件。

Approach: 按 KTD2/KTD4 去除外部阻塞 CSS、提供压缩变体与明确缓存头。缺失 /assets/* 返回 404，不回退 HTML；客户端路由仍允许 SPA fallback。发布资源保留至少当前与上一版本并明确旧标签页支持窗口；窗口外加载失败提示用户保留编辑后刷新，不自动刷新丢失草稿。

Test scenarios: gzip/br/identity 协商、q=0 禁用、Vary、GET/HEAD、304、Range、未知资源 404、客户端路由回退；字体域名黑洞仍出现表单；SSE 首事件/持续事件不缓冲；受保护 API 无 public 缓存；部署后旧标签页首次打开尚未加载的模块。

Verification: curl 与浏览器确认真正压缩响应，JS 传输量下降；HTML 不被长期缓存。此单元不宣称已达到拆包预算。

交付证据: U2 测试报告；dev merge feature/initial-load-perf-u2；8080 主 JS br 传输 623,898 B；登录冷缓存可见 ~205 ms。U1/U3–U7 仍未完成。

U3. 登录壳与重功能按需加载（P0，约 1–2 天）

Dependencies: U1；可与 U2 分开开发，合入仍串行。Requirements: R1、R2、R5；Files: web/src/main.tsx、web/src/App.tsx、新增认证壳组件、web/src/components/doc/preview/FilePreviewPanel.tsx、web/src/features/replyExport/download.ts、web/src/engine/docxRenderer.ts、web/src/components/doc/blocks/MermaidBlockView.tsx、U1 浏览器用例。

Approach: 按 KTD3 建立真实 lazy 边界；将工作台 hooks/缓存初始化移入工作台挂载周期。导出按钮点击才 import 引擎；预览根据文件类型加载；Mermaid 只在存在图块时加载。每边界提供局部加载/失败重试与错误边界。限定此重构服务于加载，保留既有文档编辑状态机。

Test scenarios: 未登录资源中不出现导出/预览/管理台/图表重模块；登录成功恢复当前会话；失效会话不展示缓存敏感数据；首次导出 DOCX/XLSX 内容有效；Word/Excel 预览、数学公式与 Mermaid 正确；动态 chunk 失败可以重试且不重复提交业务动作；首次打开功能耗时同时记录。

Verification: 满足 R1 首屏预算及功能按需请求证据，不把延迟全部转移成首次按钮不可用。检查 gzip 后所有首屏 chunks 总和。

U4. 收敛初始化扇出与重复同步（P1，约 1–2 天）

Dependencies: U1、U3；Requirements: R2、R3、R4；Files: web/src/App.tsx、web/src/api/projectWorkflow.ts、web/src/api/chatSessions.ts、web/src/data/storage.ts、新增初始化 loader/hook 及其测试；必要时项目列表 DTO/服务端 handler 补当前用户成员摘要。

Approach: 当前项目成员优先，其他完整成员按打开面板加载；会话 fetch 依赖稳定身份/查询键，项目名称映射与网络获取分离；查询代次 + AbortController + 在途合并；每次成员响应不再全量写 projects/持久化。只有实测长任务证明需要时增加去重/批量保存，不把权威服务器文档写入延迟缓存作为成功。

Test scenarios: 1/30/100 项目首次请求数量稳定；成员结果乱序不会重复请求会话；快速切项目/登出/换用户不串状态；普通成员看到的项目/会话范围与改动前一致；错误后手动重试；成员增删后局部失效刷新；离线缓存不绕过权限验证。

Verification: 达到初始化去重预算，记录必要 API 次数与工作台就绪时间；跨用户负例、当前会话恢复、文档编辑刷新持久性通过。

U5. 认证请求去重与续期写入收敛（P1，约 0.5–1 天）

Dependencies: U1 的认证测量；Requirements: R3、R4、R6；Files: internal/server/auth_handlers.go、internal/server/auth_middleware.go、internal/auth/service.go、internal/auth/pg_store.go 及相邻测试。

Approach: /auth/me 复用 middleware principal；合并会话及用户读取，避免重复查同一用户。先度量 session UPDATE 锁/连接等待；只有证明其成本且明确既有过期语义后采用有界续期/last_seen 写入策略。鉴权失败不缓存成成功，撤销/停用每请求生效。

Test scenarios: 同 token 1/10/30 并发；me 请求中只验证一次；撤销/停用后的下一请求拒绝；idle 边界/绝对过期/并发续期；DB 异常 fail-closed；匿名静态资源仍可访问。

Verification: 展示改前/后 DB 操作数、锁等待和 p95；身份安全回归通过。若节流会改变过期语义，则只交付请求内复用，将节流留待独立决定。

U6. 按测量优化列表与租约读取（P2，约 2–4 天；按证据选子项）

Dependencies: U1、U4；Requirements: R2、R4、R6；Files: internal/docgov/project_docs.go、internal/docduty/store.go、成员/职责写路径、internal/ctxmgr/chat_history.go、internal/projectworkflow/store.go、web/src/App.tsx 及相邻 PG/浏览器测试；确需索引时新增 Goose migration。

Approach: (a) 先验证成员创建/转交/退出/撤销各路径事务内同步职责，并以显式受控任务修复历史，之后去掉列表读时 heal；(b) 租约查询避免每次全量文档修复，单请求在途、隐藏页暂停并在可见时立即同步，复用现有 SSE 失效事件；(c) 会话先按原可见性/排序选页，再仅统计页内数据，项目列表视数据量分页。维持 COUNT/latest 内容授权规则与排序稳定性，不能把当前全量总计改为页内总计却不告知调用方。

Test scenarios: 文档 GET 零 UPDATE/advisory lock，重复读不变 updated_at；成员变动职责立即正确；两标签 busy/释放不晚于原可见性基线、断 SSE 可恢复；慢查询轮询不重叠；分页无重复/丢项且计数不泄漏；EXPLAIN 对照现有索引与扫描行数；项目 143 不做写入修复测试。

Verification: PG 真库夹具 + 真实页面操作证明治理与编辑/刷新链路无回归；SQL 扫描、锁等待和 p95 确实改善。没有对应瓶颈时不为“优化”增加索引/摘要/新接口。

U7. 重启后首访链路与开发预热（P0 诊断 / 按证据修复，约 0.5–1.5 天）

Dependencies: U1；Requirements: R1、R2、R6；Files: web/vite.config.ts、cmd/server/main.go、internal/app/app.go、internal/bizdev/service.go、scripts/env-service.sh、实际入口健康检查配置与启动测试。

Approach: 重启矩阵覆盖：仅 Vite 重启（保留/空依赖缓存）、仅 app 重启、依赖服务一起启动。每项再分浏览器保留缓存/清缓存与保存登录态/未登录；记录启动命令、DB healthy、app listen、ready、首次 HTML、首 API、UI ready。共享重启须占槽并避开正在执行任务，在隔离环境优先验证。Go 初始化分段计时；Vite 确认无缓存编译主导后，使用锁定 Vite 版本支持的 server.warmup/clientFiles 预热关键入口并保留 node_modules/.vite 缓存，禁止为暖机触发聊天或文档生成。

若 DB/迁移/seed 才是主耗时，先将重复扫描与种子写入改为有版本依据的幂等增量；必需迁移和授权数据未完成时 ready 必须失败。不要为看起来快而提前假报就绪。若是健康探测/代理等待，优化实际就绪探测与放流时序，不能把 start_period 直接当固定延时删除。对于后端暂时不可用，登录壳给出服务准备中和有限重试，不能无提示白屏或把瞬时不可达误当身份失效清空会话。

Test scenarios: 同版本无迁移重启、首次/有迁移启动、DB延迟就绪/不可用、依赖缓存失效、warmup 失败、过期登录态、保存有效登录态但网络暂时中断；多环境隔离保持。

Verification: 无待执行迁移且 DB 已就绪时 app restart→ready p95 ≤3 s；完整依赖启动单列，不承诺未测硬件的整机开机时间。8080/8081 ready 后首次访问须符合 Success Criteria 绝对预算；3100 分别符合 U1 在实施前固定的 Vite 冷/暖预算，不套生产压缩体积预算。三个入口在各自匹配的真实重启场景首访耗时均较基线下降至少 50%，同时记录从启动命令到 UI ready 总耗时，防止仅把等待搬到后台预热而宣称消失。若实测无法达到，保留未达标项与原因，不伪报完成。

Verification Contract

• 前端：cd web && npm test && npm run build；单独运行 U1 的 Playwright 性能用例与现有文档修订/历史恢复相关浏览器回归。检查构建依赖与实际请求，不能只检查构建日志大小。
• Go：go vet ./...、go test -short ./...；认证/文档/会话修改补相关真实 PG 集成，覆盖撤销、跨用户、分页和职责同步。
• 合入/运行验证：占 CURRENT 集成槽，在主仓 merge 后 ./scripts/env-service.sh dev rebuild，验证 /health、/ready 与资源 hash；健康不代表性能通过。禁止 worktree 启停共享服务。
• 真实 UI：登录、刷新当前会话、切项目、首开预览、首导出、文档编辑保存后刷新/重开、双标签 busy。涉及文档治理改变时按 PROJECT 补真实 PI + MiniMax 全链路，stub 不可替代交付。
• 证据：报告记录 commit/image/资源 hash、浏览器与硬件、网络/CPU 设置、缓存状态、数据规模、样本数/分位数、失败样本、请求数和 SQL 变化。脱敏，不保存登录 token、会话正文或原始授权头。

Definition of Done

1. R1–R6 与性能预算有前后对比和真实 UI 证据；未覆盖项明确列残余，不因 health PASS 关闭。
2. 字体不可达仍可操作，首次登录无重功能模块；初始化不随全部项目成员返回重复发会话请求。
3. 授权/文档职责/租约/保存持久性不回退，分页可见性一致，SSE 不缓冲，旧版本 chunk 失效有恢复路径。
4. 更新任务、CURRENT、FEATURE-MATRIX、test-report，完成后任务归档；明确本地分支/提交、是否合 dev、是否推送。

Rollout and Rollback

顺序：U1 → U2/U3 与 U7 → U4/U5 → 按数据选择 U6，每波独立复测并归档，预计核心 U1–U5 约 3.5–7 工程日，U7 另需 0.5–1.5 日，U6 另需 2–4 日（估算，含回归，非交付承诺）。先 dev，再按项目既有授权晋升 test/main。

压缩/缓存只作用静态资产，发现编码/缓存问题可回退独立提交；保留对应完整 HTML+资源集，避免仅回滚 HTML。拆包可回滚组件边界，但禁止强制刷新正在编辑的用户。认证和查询优化各独立提交；职责修复迁移必须可重入，停用新读路径时保留既有安全修复，不删除数据/索引作为临时回滚。若 p95 回退超过 10%、401/403 异常、文档职责偏差或租约不可见，停止晋升并回退相应单元。

Appendix

• 审计与数值证据
• 诊断测量报告
• HTTP 压缩协商与 Vary：MDN。缓存版本化资源与 HTML 策略：MDN HTTP caching。
• 外部字体与阻塞 CSS：web.dev 字体实践。Vite 开发请求瀑布：Vite performance。这些资料用于原则核验；具体配置以仓库锁定的 Vite 7.1.x 为准，不照搬官网当前版本构建 API。

Plan Review

已完成同模型的 coherence、feasibility、design、security、scope、adversarial 六视角只读复核（3 个代理分别承担两视角，不作为6份模型独立验证）。修正1项：明确3100开发入口与8080/8081构建入口使用不同资源预算；保留三入口真实重启与总耗时验证。未进行外部跨模型复核，不声称具有跨模型验证。置信度：资源/字体机制高，用户重启现场主因中等，须U1/U7闭环。