docs: add README.md and update AGENTS.md

2026-04-13 01:02:38 +08:00
parent 12282ae4b3
commit a4b6e31a40
2 changed files with 185 additions and 27 deletions
@@ -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**: 应用容器化，数据库使用外部服务

 <!-- BEGIN:nextjs-agent-rules -->
-# 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/` 中的文档。
 <!-- END:nextjs-agent-rules -->
@@ -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