Skip to content

TECH_STACK.md

Latest commit

 

History

History
101 lines (91 loc) · 6.77 KB

TECH_STACK.md

File metadata and controls

101 lines (91 loc) · 6.77 KB

CaseAI 技术栈与实现细节

总览

  • 前端：React 18（ESM 直引）、单页应用（Hash 路由）、原生 SVG 思维导图、CSS 变量主题
  • 后端：Node.js + Express（TypeScript）、Zod 校验、错误中间件、静态资源托管
  • 数据层：MySQL（mysql2/promise 连接池）、迁移脚本与启动初始化、版本与审计日志
  • 生成能力：文件解析（PDF、DOCX、纯文本）、规则生成 + LLM 生成（OpenAI/DeepSeek/OpenRouter/Ollama）
  • 导出能力：Excel/CSV（xlsx）、PNG（SVG → Canvas）
  • 回退机制：数据库失败时的内存存储回退（任务与用例），确保功能可用

前端实现

  • 入口与路由
    • 单文件 SPA：backend/public/app.html
    • Hash 路由与导航：backend/public/app.html:44–48, backend/public/app.html:270–279
    • 页面组件：Upload、History、Task、Profile、Mindmap、Detail (所有组件均集成在app.html中)
  • 思维导图（SVG）
    • 渲染与交互：backend/public/app.html:878–1173
    • 颜色取自 CSS 变量，支持主题切换：backend/public/app.html:896–917
    • 节点 hover/拖拽/缩放：backend/public/app.html:1141–1168
    • 节点附带 title 与 data-id（显示用例ID）：backend/public/app.html:1111–1112
  • 详情面板（用例编辑/新建/删除）
    • 显示并复制用例ID：backend/public/app.html:1187–1193
    • 保存/新建/删除的回调接入 API 并进行函数式状态更新：
      • Upload 页：backend/public/app.html:700–717
      • Task 页：backend/public/app.html:901
  • 历史记录
    • 筛选与本地回退逻辑：backend/public/app.html:732–757
    • 复选与批量导出：backend/public/app.html:760–777, 选择列 backend/public/app.html:794–799
  • 导出
    • Excel/CSV：backend/public/app.html:650–667, backend/public/app.html:760–777
    • PNG：backend/public/app.html:656–663, backend/public/app.html:898–903
  • 主题与样式
    • 设计令牌与组件样式：backend/public/app.html:7–143, backend/public/app.html:144–465

后端实现

  • 应用初始化与路由挂载
    • backend/src/server.ts:22–27 挂载各模块路由
    • 静态资源与错误处理：backend/src/server.ts:16, backend/src/server.ts:29
  • 用例集 API（模块 backend/src/web/testcases.ts）
    • 生成用例：POST /api/testcases/generate（文件/文本，LLM 优先，失败回退规则）backend/src/web/testcases.ts:19–51
    • 历史列表：GET /api/testcases/tasks backend/src/web/testcases.ts:59–62
    • 历史筛选：GET /api/testcases/tasks/filter（支持关键词/时间/用例数；合并内存与库）backend/src/web/testcases.ts:115–126
    • 任务详情：GET /api/testcases/tasks/:id backend/src/web/testcases.ts:53–67
    • 用例更新：PATCH /api/testcases/:id（Zod 校验；库失败回内存）backend/src/web/testcases.ts:69–82
    • 新建用例：POST /api/testcases/tasks/:id/testcases（库失败回内存）backend/src/web/testcases.ts:84–94
    • 删除用例：DELETE /api/testcases/:id（事务 + affectedRows；失败回内存并明确 message）backend/src/web/testcases.ts:96–103
    • 版本与审计：GET /api/testcases/:id/versions、GET /api/testcases/:id/audits backend/src/web/testcases.ts:105–113
  • 数据访问层（模块 backend/src/repo/tasks.ts）
    • 任务入库（修正列/占位符、写入用例数）：backend/src/repo/tasks.ts:12–24
    • 用例 ID 标准化（生成阶段补全缺失ID）：backend/src/repo/tasks.ts:27–36
    • 任务详情聚合（返回 sourceType 与 summary）：backend/src/repo/tasks.ts:31–45
    • 历史与筛选（SQL + 合并内存，关键词/时间/用例数）：backend/src/repo/tasks.ts:61–100, 103–112
    • 用例更新（版本快照 + 审计日志）：backend/src/repo/tasks.ts:110–128
    • 新建用例（库失败回内存）：backend/src/repo/tasks.ts:109–122
    • 删除用例（事务 + affectedRows，失败回内存）：backend/src/repo/tasks.ts:124–131
    • 用例存在性检查（明确错误原因）：backend/src/repo/tasks.ts:132–140
  • 内存存储（模块 backend/src/store/cases.ts）
    • 任务/用例 Map 与列表统计：backend/src/store/cases.ts:22–26
    • 删除任务：backend/src/store/cases.ts:28–31
    • 就地更新用例：backend/src/store/cases.ts:33–52
    • 新增/删除用例（库失败时回退）：backend/src/store/cases.ts:53–67

数据库与迁移

  • 连接池与环境变量：backend/src/db/pool.ts:3–12
    • DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME
  • 启动初始化：backend/src/setup/dbInit.ts:5–21
    • 执行 db/migrations/001_init.sql
    • 追加表：test_case_versions 与 audit_logs，含索引与外键（CASCADE）
    • 兼容迁移：generation_tasks.template_id 改为可空，避免插入失败 backend/src/setup/dbInit.ts:21
  • 主要表结构（摘要）
    • generation_tasks(id,user_id,parameters,status,test_case_count,created_at,completed_at)
    • test_cases(id,task_id,content,metadata,category,created_at)
    • test_case_versions(id,case_id,version,content,metadata,category,created_at)
    • audit_logs(id,user_id,case_id,action,payload,created_at)

生成与解析

  • 文档解析：backend/src/services/fileText.ts 使用 pdf-parse 与 mammoth（DOCX）提取文本
  • 规则引擎：generateTestCasesFromDoc 对文本做标题/段落/关键字分析生成初始用例
  • LLM 生成：generateCasesWithLLM 多供应商适配，强制 JSON 输出，失败回退规则引擎

导出实现

  • PNG 导出：序列化 SVG → Image → Canvas → toDataURL('image/png') 下载
  • Excel/CSV 导出：XLSX.utils.json_to_sheet + XLSX.writeFile，支持批量导出并包含任务摘要与来源类型

错误处理与健壮性

  • Zod 校验所有写入参数（生成、更新、新建）
  • 删除用例：数据库事务 + affectedRows 检查；失败时内存回退并在响应 message 告知原因
  • 前端：所有写操作均检查 response.ok 并有 console.error 与用户提示；失败时保持视图一致（本地移除）

主题与可访问性

  • 设计令牌、焦点环（2px 外描边）、按钮与表格 hover/active 明确，深浅色主题对比度 ≥ 4.5:1

开发与运行

  • 启动：npm run dev（后端）、浏览器打开 http://localhost:3000/app.html
  • 预览适配：只读接口开放以避免预览环境无令牌时无法浏览

学习建议

  • SVG 布局：查看 Mindmap 中的环形分布、曲线连接、交互层（缩放/拖拽）
  • 状态管理：函数式 setState 更新避免闭包旧值；对并发更新有更强健性
  • 事务与回退：从 deleteCaseById 的事务实现入手理解“失败时仍保持用户可用”的设计
  • 筛选策略：后端 SQL + 前端回退混合，实现“空结果不清空”的用户体验