Skip to content

AGENTS.md

Latest commit

 

History

History
209 lines (161 loc) · 10.4 KB

AGENTS.md

File metadata and controls

209 lines (161 loc) · 10.4 KB
Raw

AGENTS.md

本文件给后续维护者和自动化 Agent 使用。动代码前先读这里，优先保持项目现有结构、业务口径和工具型 UI 风格。

项目定位

  • 项目名：data-analysis-workbench
  • 产品名：数据研判工具箱
  • 技术栈：Next.js App Router、TypeScript、Tailwind CSS。
  • 核心依赖：next、react、exceljs、lucide-react。
  • 这是一个面向 Excel/CSV 的本地数据研判工具台，不是营销页。第一屏应直接呈现可操作工具。
  • 项目 icon 位于 public/icon.svg，同时作为 favicon 使用。
  • 推荐终端：C:\Program Files\Git\bin\bash.exe。当前 Codex Windows PowerShell 沙箱偶尔会启动失败，必要时使用受控提权执行本地命令。

当前工具

顶部导航由 app/config/tools.ts 的 TOOL_DEFINITIONS 自动渲染。当前包括：

  • 多表碰撞：多张表按字段碰撞，支持补全基准表或只取交集。
  • 多表合并：以基准表字段为准，合并多张参与表的所有 sheet。
  • 智能提取：从源列按模板或自定义正则提取结构化字段。
  • 模糊去重：按相似度算法发现重复行，支持完全一致字段约束。
  • 差异对比：对比两张表，识别新增、删除、修改和一致。
  • 跨表检索：跨多个 Excel/CSV 和多工作表全字段检索，按命中 sheet 展示原表切片。
  • 取最新行：按基准字段和时间字段保留最新一条。

代码结构

  • app/page.tsx：页面壳、全局导航、跨模块状态编排、通用导出入口。不要在这里堆大块 UI 或算法。
  • app/config/tools.ts：工具注册信息，包括导航标题、页面标题、导出文件名和默认 sheet 名。
  • app/types.ts：共享类型。
  • app/lib/workbook.ts：Excel/CSV 解析、字段工具、Excel 导出。
  • app/lib/collision.ts：多表碰撞业务计算。
  • app/lib/merge.ts：多表合并业务计算。
  • app/lib/extract.ts：智能提取业务计算。
  • app/lib/dedup.ts：模糊去重业务计算。
  • app/lib/diff.ts：差异对比业务计算。
  • app/lib/search.ts：跨表检索业务计算和多 sheet 导出。
  • app/lib/latest.ts：取最新行业务计算。
  • app/components：通用 UI 组件。
  • app/modules/<module>：各工具模块 UI。复杂模块可以在模块目录内放自有 hook，例如 app/modules/search/useSearchWorkbench.ts。

新增模块时：

  1. 在 app/config/tools.ts 注册工具。
  2. 在 app/types.ts 增加必要共享类型。
  3. 在 app/lib/<module>.ts 放业务计算。
  4. 在 app/modules/<module> 放模块 UI 和模块私有 hook。
  5. 在 app/page.tsx 只做状态接入和模块挂载。

业务约定

多表碰撞

  • 默认展示 2 张 Excel/CSV 表，可继续添加第 3、第 4 张表。
  • 第 1 张表叫 基准表，后续参与表使用 参与表 A、参与表 B、参与表 C。
  • 模式文案只使用业务名称：
    • 补全基准表：等价于以基准表为主的 left join，保留基准表全部记录，未命中显示 未命中。
    • 只取交集：等价于多表 inner join，只保留所有参与表都命中的记录。
  • 界面不要出现 Left Join、Inner Join、待补全 等旧文案。
  • 默认不区分大小写；顶部可勾选 区分大小写。
  • 前端结果表格必须保留 基准表.、参与表 A. 等列名前缀，用于区分同名字段。
  • Excel 导出时去掉表名前缀，但要允许重复表头。导出逻辑必须按二维数组列位置写入，不要用对象 key 方式生成 sheet，否则同名字段会互相覆盖。
  • 结果行需要按整行去重，类似 SQL 的 DISTINCT *，但界面不要展示 DISTINCT * 英文说明。

多表合并

  • 1 张 基准表 + 多张 参与表；参与表支持单个导入，也支持 批量添加表（Ctrl/Cmd 多选文件）。
  • 字段映射先按字段名自动匹配（normalizeKey），未匹配字段可手动映射到基准字段。
  • 合并范围是参与表的所有 sheet，全部合并到结果中。
  • 输出列 = 基准表字段 + 来源表名。
  • 整行去重 开关默认开启，需显示去重移除数量。

智能提取

  • 单表导入，支持多选源列；每个源列独立匹配，不要把多列直接拼接，避免跨列误匹配。
  • 模板按钮支持多选。
  • 当前模板包括：手机号、身份证号、银行卡号、邮箱、财付通、支付宝、自定义正则。
  • 金额 模板已移除，不要恢复。
  • 若同一行同一模板命中多个值，输出字段按 手机号1、手机号2 这类序号扩展。
  • 财付通邮箱不要被邮箱模板重复命中；支付宝账号不要被银行卡模板重复命中。
  • 身份证号应校验日期和校验位；明显出生日期不合法的数字串不能当身份证。
  • 银行卡号应排除合法身份证、支付宝号，并做基础长度与 Luhn 校验。
  • 结果说明使用 提取身份证号 X 行、提取邮箱 X 行 这种分模板口径。

模糊去重

  • 单表导入，选择 匹配字段，可额外选择 完全一致字段。
  • 完全一致字段 表示该字段内容必须完全相同，才允许被归到同一重复组。
  • 默认不区分大小写；顶部可勾选 区分大小写。
  • 相似度算法包括 编辑距离 和 二元组。
  • 分块粒度包括 首字分块 和 首2字分块。
  • 工作表、匹配字段、完全一致字段 在数据表卡片内并排展示；工作表列宽应明显小于字段列。
  • 推荐导出应只导出去重后的推荐保留行和独立行；全量导出保留重复组标记。

差异对比

  • 固定两张表：旧表 和 新表。
  • 模式包括：
    • 按内容比对：无可靠主键时使用，优先匹配完全一致行，再把高度相似的剩余行配成修改。
    • 按字段对齐：用户选择 1 个或多个字段作为对齐字段。
  • 默认不区分大小写；顶部可勾选 区分大小写。
  • 按字段对齐时，重复 key 不要丢弃后续行，应按出现顺序配对，并在 note 里提示 对齐字段存在重复，已按出现顺序配对。
  • 修改行的 变更字段 列使用 字段名: 旧值 → 新值，多个字段用 ； 分隔。
  • 修改行展示新表数据；删除行展示旧表数据；新增行展示新表数据。

跨表检索

  • 输入为多张 Excel/CSV 表。每张表可以多选工作表，导入后默认选中全部工作表。
  • 搜索要素放在上传表区域下方，符合先选数据源、再输入线索的动线。
  • 支持 精确、包含、模糊 三种检索方式。
  • 默认不区分大小写；顶部可勾选 区分大小写。
  • 检索范围是选中工作表的全字段搜索，不需要用户选择字段。
  • 结果不要展示 来源表 / 字段 / 命中值 明细表。结果应按命中的 sheet 分块展示，每块保持该 sheet 的原始列结构，只展示命中行。
  • 结果中只高亮命中的要素本身，不要整行高亮。
  • 导出为 .xlsx，每个命中 sheet 一个 Excel sheet，sheet 名就是命中工作表名；sheet 内只保留命中行，表头保持原样。
  • 如果多个来源有同名 sheet，导出时自动给后续 sheet 加后缀，避免 Excel sheet 名冲突。
  • 搜索模块状态较多，优先放在 app/modules/search/useSearchWorkbench.ts，不要继续把 page.tsx 撑大。

取最新行

  • 单表导入，选择 基准字段 和 时间字段。
  • 结果等价于：
ROW_NUMBER() OVER (PARTITION BY 基准字段 ORDER BY 时间字段 DESC) = 1
  • 每个基准字段只保留时间最新的一条记录。
  • 空基准字段要忽略，并在结果指标里展示忽略数量。
  • 时间解析当前使用 Date.parse，并兼容基础 Excel 序列日期数字。
  • 未导入数据时不要让右侧出现大片空白；配置卡片和上传卡片应保持视觉平衡。

UI 约定

  • 顶部导航是标准全宽 header，左侧显示 icon 和 数据研判工具箱，工具切换放中间或偏左。
  • 工具切换由 TOOL_DEFINITIONS 自动渲染；新增工具时注意导航在窄屏是否会拥挤。
  • 文件导入后，不再显示大面积导入框，只保留标题右侧的 更换 小按钮。
  • 多表类工具的表卡片横向单行排列，超出后左右滑动；添加表 按钮跟在同一横向列表最后。
  • 添加表 按钮宽度应明显小于普通表卡片；高度要与同一行表卡片统一，不要被内容撑成巨型卡片。
  • 统计信息应收在结果标题旁边，不要做成大面积指标卡。
  • 页面风格偏工具型、清晰、低噪音。优先让用户看到上传、字段选择、结果表格和导出。
  • 使用 Tailwind CSS 写样式，不要回退到大量手写 CSS。
  • 不要在工具型界面放大段说明文字。必要说明用短标签、note 或导出按钮文案承载。
  • 不要使用营销页式 hero、装饰性大图、渐变插画或大面积空白。

本地开发与验证

常用命令：

npm install
npm run dev
npx tsc --noEmit

默认开发地址：

http://localhost:3000

注意：

  • 改功能后优先运行 npx tsc --noEmit。
  • 用户明确说不需要启动时，不要启动 dev server。
  • 当 npm run dev 正在运行时，尽量不要同时跑 next build，避免 .next 缓存互相影响。
  • 若页面样式突然丢失，优先检查 _next/static/css/app/layout.css 是否返回 500；必要时停止 dev server，删除 .next 后重启。
  • 本机 PowerShell 沙箱偶尔启动失败，必要时使用受控提权执行本地命令。

Docker 离线部署

项目支持打包成离线 Docker 部署包，目标服务器无需 npm、无需联网。

相关文件：

  • Dockerfile
  • docker-compose.yml
  • deploy.sh
  • .dockerignore

常用命令：

sh deploy.sh pack
sh deploy.sh start
sh deploy.sh stop

约定：

  • Compose 文件使用 version: "2"，兼容老版本 docker-compose。
  • Next.js 使用 standalone 输出，Docker 镜像必须包含 public/，否则 /icon.svg 等静态资源会 404。
  • 默认端口为宿主机 3000 到容器 3000，可通过 DATA_ANALYSIS_WORKBENCH_PORT=8080 sh deploy.sh start 覆盖。
  • 离线包名形如 dist/data-analysis-workbench-offline-*.tar.gz。

忽略与提交

不要提交以下内容：

  • node_modules
  • .next
  • dist
  • .deploy-pack
  • dev-server.log
  • tsconfig.tsbuildinfo
  • 本地环境变量和包管理器 debug 日志

提交前检查工作区，避免把离线部署包、构建缓存、依赖目录提交进仓库。