foodie-server/CLAUDE.md

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 时必须注意：

1. 先确认 key 所属的对象层级。 语言文件中有多层嵌套对象（如 foots:{}、cuxiao:{}、fenlei:{} 等），使用 $t('foots.XXX') 的 key 必须添加到 foots 对象内部，不能加到文件顶部或其它对象里。
2. 找到该对象的最后一个属性（通过 grep 或阅读文件定位），在其后追加新 key，确保逗号正确（中间属性末尾要有逗号，最后一个属性无逗号）。
3. 四个语言文件（zh.js、tw.js、en.js、vi.js）都要添加，缺一不可。
4. 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() 或行号操作来修改文件内容，避免换行符匹配问题。

数据库变更管理

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

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

全栈字段添加清单

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

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

商家类型与订单查询逻辑

InfoUser.userType 区分不同商家角色，查询订单时必须按类型使用不同字段过滤：

userType	角色	订单过滤条件
1	普通商家	PosOrder.shId = userId
3	夜市商家	PosOrder.shId = userId
其他	摊位商家	PosOrder.mdId = InfoUser.storeId（从用户表查关联的摊位门店ID）

关键字段：

• InfoUser.userType：0=普通用户, 1=商家, 2=骑手, 3=夜市
• InfoUser.storeId：摊位商家关联的摊位门店ID
• PosOrder.shId：商家ID（普通/夜市商家直接等于userId）
• PosOrder.mdId：门店ID（摊位商家用 InfoUser.storeId 匹配）

范围控制

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

对于简单的格式化或显示变更（如截断小数、重命名 key、单文件修改），不要创建任务计划或启动 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.

For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan