# foodie_server Development Guidelines

Auto-generated from all feature plans. Last updated: 2026-05-15

Tech Stack

后端: Java (Spring Boot, MyBatis with XML mappers)
前端: Vue.js (Element UI)
支持语言: Vietnamese (vi), Simplified Chinese (zh), Traditional Chinese (tw), English (en)
数据库: MySQL
开发环境: Windows

Project Structure

平台管理前端代码路径：E:\QtwCode\foodie\foodie-admin-vue
商家端管理前端代码路径：E:\QtwCode\foodie\foodie-store

前端多语言(i18n)添加规范

所有前端新功能必须实现多语言，不例外。 平台管理端(foodie-admin-vue)和商家端(foodie-store) 新增的任何面向用户的文字都必须使用 $t() 而非硬编码中文。

商家端(foodie-store)使用 vue-i18n，语言文件在 src/lang/ 下（zh.js、tw.js、en.js、vi.js）。

添加多语言 key 时必须注意：

先确认 key 所属的对象层级。 语言文件中有多层嵌套对象（如 foots:{}、cuxiao:{}、fenlei:{} 等），使用 $t('foots.XXX') 的 key 必须添加到 foots 对象内部，不能加到文件顶部或其它对象里。
找到该对象的最后一个属性（通过 grep 或阅读文件定位），在其后追加新 key，确保逗号正确（中间属性末尾要有逗号，最后一个属性无逗号）。
四个语言文件（zh.js、tw.js、en.js、vi.js）都要添加，缺一不可。
key 必须使用有意义的英文单词（驼峰命名），禁止使用 text1、text2、text55 等无意义序号。例如：按钮用 orderBtn，标题用 orderDialogTitle，状态用 diningStatus。四个语言文件的 key 名称必须完全一致。

曾经犯的错误： 把 AddCategoryFirst 加到了文件第 141 行的公共区域，而 $t('foots.AddCategoryFirst') 是在 foots 对象（第 190+ 行）下查找，导致页面显示原始 key 而非翻译文本。

前端文件编辑注意事项

前端项目（foodie-store、foodie-admin-vue）的文件使用 CRLF 换行符（Windows 风格 \r\n）。使用编辑工具进行字符串替换时，由于换行符不匹配会导致 "String to replace not found" 错误。

正确做法： 编辑前端文件时，使用 Python 脚本（python << 'PYEOF'）通过 content.replace() 或行号操作来修改文件内容，避免换行符匹配问题。

越南盾(VND)货币格式化

所有展示给越南用户的货币/金额必须使用整数格式（无小数位），因为越南盾不使用分。Java 计算使用 .setScale(0, RoundingMode.HALF_UP)，JS 格式化使用 Math.floor() 或 parseInt()。

数据库变更管理

所有数据库变更（ALTER TABLE、数据迁移等）不直接执行，必须写入 updatesql/sql.md 文件。由开发者统一到数据库手动执行。SQL 语句需标注日期和用途注释，例如：

-- 2026-05-15 订单状态四字段分离
ALTER TABLE pos_order ADD COLUMN delivery_status BIGINT DEFAULT NULL COMMENT '配送状态';

全栈字段添加清单

添加新字段到实体时，必须按顺序更新以下所有层级：

Java 实体类（Entity）
MyBatis XML mapper（resultMap + 相关的 select/insert/update 语句）
DTO 类（如适用）
Service 层业务逻辑
Controller 层接口
前端 Vue 组件
四个 i18n 语言文件（vi.js、zh.js、tw.js、en.js）
SQL 迁移脚本

范围控制

当用户说"只改 X"时，就只改 X——不要广泛探索、创建任务或为简单的定向修改启动 Agent。从用户提到的具体文件或区域开始，做最小的必要修改。

CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

State your assumptions explicitly. If uncertain, ask.
If multiple interpretations exist, present them - don't pick silently.
If a simpler approach exists, say so. Push back when warranted.
If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

No features beyond what was asked.
No abstractions for single-use code.
No "flexibility" or "configurability" that wasn't requested.
No error handling for impossible scenarios.
If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

Don't "improve" adjacent code, comments, or formatting.
Don't refactor things that aren't broken.
Match existing style, even if you'd do it differently.
If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

Remove imports/variables/functions that YOUR changes made unused.
Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

"Add validation" → "Write tests for invalid inputs, then make them pass"
"Fix the bug" → "Write a test that reproduces it, then make it pass"
"Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

CLAUDE.md 6.0 KB تاريخچه خام