文件
hyb-oa/.trellis/tasks/07-26-trellis-upgrade-project-audit/research/current-state-audit.md
T

7.3 KiB
原始文件 Blame 文件历史

当前项目状态多维审查

结论摘要

  • 当前业务代码仍处于 LOCAL_CANDIDATE_PASS,不是已部署或可公网测试;07-18 收口后的业务代码没有新增提交。
  • 本次重新执行完整本地门禁通过:Prisma schema 有效,服务端 161 个测试文件 / 985 项测试全部通过,前端 typecheck 与 production build 通过,流程合同、Trellis governance、敏感扫描和功能矩阵通过。
  • Trellis 项目版本为 0.5.19,本机 CLI 为 0.6.8,npm 最新为 0.6.9。升级应直接以 0.6.9 为目标。
  • 当前最需要优先处理的新增工程风险是前端 React Router 两项 moderate advisory;最重要的既有业务开放项仍是统一导出安全与客户端离线数据生命周期。

Trellis 升级审查

实施结果(2026-07-26)

  • 全局 CLI 与项目模板已从 0.6.8 / 0.5.19 对齐到 0.6.9,并完成官方 migration。
  • 升级时临时隔离仅含本地设置的 .claude/,恢复后未生成 Claude 托管资产;项目继续保持 Codex-only。
  • 四个冲突文件按设计完成合并,保留 Trellis-first overlay、Codex inline、禁止自动提交和 workspace/ 忽略规则;未保留 .new 冲突副本。
  • 0.6.9 runtime 的 task_context.py 包含 Python 3.9.2 不接受的嵌套多行 f-string;已改为先构造 warning 再着色,并通过全量 compileall 与 task runtime 验证。
  • 升级后 dry-run 不再改变 manifest,仅报告 task_context.py、config.yaml、.gitignore、workflow.md、AGENTS.md 五个有意保留的项目定制。

升级前版本与差异

  • 项目:0.5.19。
  • 本机 CLI:0.6.8。
  • npm latest:0.6.9。
  • 0.6.9 将更新 Trellis runtime、共享 skills、Codex agents/hooks/config,并新增 .trellis/agents/、trellis-channel、trellis-session-insight 和拼写修正后的 trellis-spec-bootstrap。
  • AGENTS.md、.trellis/workflow.md、.trellis/config.yaml、.trellis/.gitignore 被识别为本地修改,必须三方合并。

已确认风险

  1. 仅因为项目存在 .claude/settings.local.json,CLI 就把 Claude 判定为已配置平台,计划新增整套 .claude/ commands、skills、agents、hooks 与 settings;这与 Codex-only 边界冲突。
  2. 0.6.9 的 update --dry-run 会实际清理 .template-hashes.json 中旧拼写 trellis-spec-bootstarp 的 5 个条目,尽管结尾显示 No changes made。预演后的非预期修改已恢复。
  3. 上游建议 --migrate,涉及旧拼写目录迁移;不能手工提前删除旧 skill 或强制覆盖本地 workflow。

推荐升级路径

  1. 升级全局 CLI 到 0.6.9。
  2. 临时安全保存 .claude/ 本地目录,使 Trellis 只检测到 Codex。
  3. 在干净提交点上执行保守更新和 migration;冲突文件生成 .new,不使用 force。
  4. 逐文件合并四个本地定制文件,保留中文沟通、方案批准、Codex inline、no auto commit、生产授权边界。
  5. 恢复 .claude/settings.local.json,确认没有新增 Claude 托管资产。
  6. 验证 context、task lifecycle、hooks、governance、完整本地门禁并单独提交升级。

代码、测试与依赖

  • 规模:服务端约 200 个跟踪源文件,前端约 297 个跟踪源文件;服务端 161 个单元测试文件,前端测试目录 81 个文件;Prisma migration 61 项。
  • 全量门禁:985/985 服务端测试通过;前端 typecheck/build 通过。
  • 覆盖率配置能生成报告,但没有风险阈值;既有 QA-COVERAGE-001 仍开放。建议针对认证、付款、worker、迁移/恢复入口建立风险型阈值,不追求全仓统一百分比。
  • 前端生产依赖审计报告 2 项 moderate,均来自 React Router 6.30.4;公开修复指向 7.18.1,属于需要专项回归的 major migration。
  • 服务端 npm audit 因 npm quick-audit endpoint 返回 invalid package tree 而不可用;npm ls 无 problem、npm ci --dry-run 可完成,说明更像审计接口/锁树兼容问题,但仍应在依赖维护任务中闭合。
  • 可安全优先升级一批服务端 patch/minor;Vitest、React、Vite、Tailwind、pg-boss 等 major 不应混成一次升级。
  • 构建观察:PWA precache 约 2.1 MiB,扫码 vendor chunk 约 411 KiB,Material Symbols 字体约 479 KiB;目前无行为故障证据,先测真实首屏/弱网再优化。
  • 非阻断工具提示:Node punycode 弃用;Browserslist 数据约 6 个月未更新。

业务与交付状态

  • 07-18 已本地验证:认证代理信任、附件主动内容、员工敏感字段、员工合同附件、付款状态机/审计、核心长表单、移动考勤、响应式表格、权限显隐与本地发布门禁等。
  • 上述本地修复仍未部署和公网复核;两个原 P0 的 Gate 0 外部验证仍需单独授权。
  • 当前 P1 开放项:统一 CSV/表格导出中和;退出/换账号后的离线数据隔离与清除。
  • P2 持续治理:下载凭证日志面、未执行 ACL 元数据、CSP、防误触、通知/搜索定位、路由元数据、错误恢复、冻结差旅入口、错误文案、移动权限与可访问性。
  • 这些 P2 不应打包成巨型重构,按触达页面或独立小任务收敛。

文档与治理

  • 事实源矩阵最近审计为 07-16,已正确声明当前可信基线与 Trellis-first 优先级。
  • audit-docs --check-registry 报 22 个未注册文件,但这 22 个文件都在同一文档后续“当前事实源/手册/证据/技术参考”章节列出;脚本只解析首个主表,因此 warning 噪声高。
  • 建议让 registry checker 识别后续分类表,或把 22 项合并进主台账;优先改检查器,避免复制 22 行冗长元数据。
  • 历史 Issue CSV 共 349 个、约 3 MiB;Trellis archive 78 个 task、850 个文件、约 5.7 MiB。体积不大且有审计价值,不建议本轮物理删除。
  • 后续应停止向历史 Issue CSV 增长;Trellis archive 只保留 PRD/设计/关键结论和最小证据,不再重复提交大批 raw log。

仓库卫生

  • 整体工作目录约 1.2 GiB,但 Git 仓库仅约 27 MiB;主要是本地依赖与忽略产物,不是 Git 历史膨胀。
  • server/node_modules 约 644 MiB,client/node_modules 约 253 MiB,属于可重建依赖缓存。
  • ignored 证据/输出中,output 约 154 MiB、artifacts 约 17 MiB,加上 build/report/coverage 可安全回收约 174 MiB;当前 .gitignore 已覆盖这些路径。
  • 建议新增一个显式的本地清理命令,只删除已忽略且可重建的固定路径;默认不删 node_modules,不清理已跟踪 Trellis archive。

建议优先级

P0 / 本轮升级

  • 安全升级 Trellis 至 0.6.9,隔离 Claude 误检测、dry-run 写 manifest 和本地四文件合并风险。
  • 保持 LOCAL_CANDIDATE_PASS 状态上限;未经授权不部署、不做公网/真实数据验证。

P1 / 下一批独立任务

  • React Router 安全升级与导航/重定向回归。
  • 统一导出安全 + 客户端离线数据生命周期,沿用既有 WP-5。
  • 消除 document registry 的 22 项假阳性 warning,使门禁重新具备信噪比。

P2 / 维护与精简

  • 风险型覆盖阈值、服务端 audit 可用性、patch/minor 依赖维护。
  • 本地 ignored artifacts 清理命令和证据保留期限。
  • 按触达修复可访问性、导航元数据、错误恢复等开放项。
  • 真实性能数据证明需要后,再优化扫码 chunk、字体和 PWA precache。