From a4b6e31a407ddfeb1e7cbe52f3cf9adf28d68c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=AF=92=E5=AF=92?= <2596194220@qq.com> Date: Mon, 13 Apr 2026 01:02:38 +0800 Subject: [PATCH] docs: add README.md and update AGENTS.md --- AGENTS.md | 70 +++++++++++++++++++++++++-- README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 185 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4777948..8ac5698 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,11 +1,71 @@ # 所有回答请使用中文 -# 当前开发环境 -系统:windows -shell:PowerShell +# 项目信息 + +- **项目名称**: 食谱翻译工具 +- **类型**: Next.js 16 Web 应用 +- **系统**: Windows / Linux / macOS +- **Shell**: PowerShell / Bash + +# 技术栈 + +- Next.js 16 (App Router) +- TypeScript +- Tailwind CSS + shadcn/ui +- MySQL 8.0 +- AI (OpenAI / GLM) + +# 开发规范 + +## 代码规范 + +- 使用 TypeScript，严格类型检查 +- 组件使用 "use client" 指令 +- 样式优先使用 Tailwind CSS +- 配置文件存储在 `config.json` + +## Git 提交规范 + +``` +feat: 新功能 +fix: 修复bug +docs: 文档更新 +refactor: 重构 +chore: 构建/工具 +``` + +## 配置管理 + +- **config.json**: 应用配置（数据库、AI、导出设置） +- **环境变量**: 仅首次启动时初始化 config.json +- **API**: `/api/config` 用于前端读写配置 + +## 目录结构 + +``` +app/ +├── api/ # API 路由（后端逻辑） +├── settings/ # 设置页面 +└── page.tsx # 首页 + +lib/ +├── config.ts # 配置读写 +├── database.ts # MySQL 连接 +└── ai-translate.ts # AI 翻译 + +config/ # 配置文件 +data/ # 上传文件 +``` + +## 关键约束 + +1. **配置分离**: 数据库配置、AI配置、导出设置分离存储 +2. **API 优先**: 导出时先调用 API 获取最新配置 +3. **防抖**: 搜索等高频操作需添加防抖 +4. **Docker**: 应用容器化，数据库使用外部服务 -# This is NOT the Next.js you know +# Next.js 16 注意事项 -This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. +本项目使用 Next.js 16，部分 API 可能有破坏性变更。编写代码前查阅 `node_modules/next/dist/docs/` 中的文档。 diff --git a/README.md b/README.md index e215bc4..ce2bca8 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,134 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# 食谱翻译工具 -## Getting Started +一款基于 AI 的食谱文档翻译工具，支持解析 Word 文档、智能翻译、批量导出。 -First, run the development server: +## 功能特性 -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev +- **Word 文档解析** - 解析 `.docx` 格式的食谱文档，提取菜品信息 +- **AI 智能翻译** - 支持 OpenAI / GLM 等大模型 API，批量翻译菜品名称 +- **翻译词库管理** - 管理常用词组翻译对照表 +- **多格式导出** - 导出双语对照的 Word 文档 +- **导出设置** - 自定义未翻译文本颜色、页面方向、第二页表头等 + +## 技术栈 + +- **框架**: Next.js 16 (App Router) +- **语言**: TypeScript +- **样式**: Tailwind CSS + shadcn/ui +- **文档**: docx (Word 生成) +- **数据库**: MySQL 8.0 +- **AI**: OpenAI API / 智谱 GLM + +## 项目结构 + +``` +├── app/ # Next.js App Router +│ ├── api/ # API 路由 +│ │ ├── ai/ # AI 翻译接口 +│ │ ├── config/ # 配置管理接口 +│ │ ├── recipe/ # 食谱解析接口 +│ │ ├── translate/ # 翻译接口 +│ │ └── words/ # 词库管理接口 +│ ├── settings/ # 设置页面 +│ │ ├── ai/ # AI 配置 +│ │ ├── database/ # 数据库配置 +│ │ ├── export/ # 导出设置 +│ │ └── translation/ # 翻译词库 +│ └── page.tsx # 首页 +├── components/ # React 组件 +├── lib/ # 工具函数 +│ ├── config.ts # 配置管理 +│ ├── database.ts # 数据库连接 +│ └── ai-translate.ts # AI 翻译 +├── config.json # 配置文件 +├── Dockerfile # Docker 构建 +└── docker-compose.yml # Docker 编排 ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +## 快速开始 -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +### 环境要求 -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +- Node.js 20+ +- MySQL 8.0 +- pnpm -## Learn More +### 本地开发 -To learn more about Next.js, take a look at the following resources: +```bash +# 1. 安装依赖 +pnpm install -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +# 2. 配置环境变量 +cp .env.docker .env +# 编辑 .env 填入数据库和 AI API 配置 -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +# 3. 启动开发服务器 +pnpm dev +``` -## Deploy on Vercel +访问 http://localhost:3000 -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +### Docker 部署 -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +```bash +# 1. 配置环境变量 +cp .env.docker .env +# 编辑 .env 填入配置 + +# 2. 构建并启动 +docker-compose up -d + +# 3. 查看日志 +docker-compose logs -f app +``` + +## 配置说明 + +### 配置文件 + +所有配置存储在 `config.json` 中，可通过设置页面修改： + +| 配置项 | 说明 | +|--------|------| +| `db` | 数据库连接配置 | +| `ai` | AI 翻译 API 配置 | +| `export` | 导出文档格式配置 | + +### 环境变量 + +首次启动时，环境变量会初始化 `config.json`。之后配置以 `config.json` 为准。 + +| 变量名 | 说明 | 默认值 | +|--------|------|--------| +| `DB_HOST` | 数据库地址 | 127.0.0.1 | +| `DB_PORT` | 数据库端口 | 3306 | +| `DB_USER` | 数据库用户名 | root | +| `DB_PASSWORD` | 数据库密码 | - | +| `DB_NAME` | 数据库名 | recipe_tools | +| `AI_API_KEY` | AI API Key | - | +| `AI_BASE_URL` | API 地址 | https://api.openai.com/v1 | +| `AI_MODEL` | 模型名称 | gpt-3.5-turbo | + +## API 接口 + +| 接口 | 方法 | 说明 | +|------|------|------| +| `/api/config` | GET/POST | 获取/保存配置 | +| `/api/recipe` | POST | 解析食谱文档 | +| `/api/translate` | POST | 批量翻译 | +| `/api/ai/translate` | GET | 单词翻译测试 | +| `/api/words` | GET/POST | 词库列表/添加 | +| `/api/words/[id]` | PATCH/DELETE | 编辑/删除词条 | + +## 导出设置 + +| 选项 | 说明 | +|------|------| +| 未翻译文本颜色 | 未翻译菜品在文档中的显示颜色 | +| 页面方向 | 横向/纵向 | +| 第二页表头 | 多页时后续页显示表头行 | + +## License + +MIT