foodie_server Codex 项目规范

本文件是 Codex 在仓库根目录直接加载的项目指令。遵循用户最新要求，并按以下规则进行分析、修改和验证。CLAUDE.md 保留更完整的背景说明；本文件已包含日常开发必须遵守的关键约束。

工作原则

动手前确认目标、影响范围和验收方式；存在会实质改变结果的歧义时，先明确说明。
只实现用户要求的内容，不增加推测性功能，不为一次性逻辑引入抽象或配置。
只修改完成任务必需的代码；不顺手重构、格式化或清理无关代码。
匹配现有代码风格。只移除本次修改造成的无用 import、变量或方法。
修复缺陷时优先用可复现检查或测试证明问题，再验证修复结果；多步骤任务给出简短、可验证的执行计划。
当用户说“只改 X”时，只改 X。简单的格式、显示或单文件修改不要创建任务计划，也不要启动 Agent。

技术栈和相关项目

后端：Java、Spring Boot、MyBatis XML Mapper、MySQL。
前端：Vue.js、Element UI。
支持语言：越南语 vi、简体中文 zh、繁体中文 tw、英文 en。
平台管理前端：E:\QtwCode\foodie\foodie-admin-vue。
商家管理前端：E:\QtwCode\foodie\foodie-store。
开发环境以 Windows 为准；编辑时保留文件原有编码和 CRLF/LF 换行风格，不因小改动重写整个文件。

订单和支付代码边界

以下代码仍在仓库中但已经废弃，不要参考其业务逻辑，也不要在其上做增量修改：

ZaloPayController.java：整体废弃，ZaloPay 已下线。
PayController.java：VNPay 回调和多数方法废弃。仅 sendAcceptRiderPush(...) 仍被 PosOrderController 的货到付款路径及尚未启用的 NewebpayPayController 引用；等接入新支付时再迁移。
TestTask.java：其中定时任务全部废弃，包括退款处理、抽成返还、自动开店和超时退款。
OrderAppealController.java：取消/申诉逻辑已失效，仅剩 parseLocale 可用。

当前有效的订单操作入口：

PosOrderShOprateController：商家出餐和取消。
PosOrderQsOprateController：骑手接单、取餐、送达，使用 deliveryStatus 1/2/3。
UserOrderController：用户下单和取消。
NewebpayPayController：蓝新金流代码已就绪但尚未启用。
PosOrderController：仅 /addorder、/setorderuzt 和 list 查询仍在使用，主要订单状态流转已经迁出。

推送以当前真实通道为准：PayPush 没有 Android FCM；本项目仅有 iOS uni 云函数 msduser、msdrider、msdstore，以及 PushEvent -> push_message 入库。cidType 当前没有实际区分作用。相关状态见 specs/012-im-user-integration/code-status.md。

Spring Controller 规范

需要登录 token 的接口直接声明 @RequestHeader String token。不要为了读取 token 注入或使用 HttpServletRequest。
POST 业务参数使用明确 DTO，并显式标注 @RequestBody；禁止未标注注解的隐式绑定。
GET 查询参数逐个显式标注 @RequestParam；token 使用 @RequestHeader，路径参数使用 @PathVariable。
禁止用任何 Map 作为 Controller 请求方法入参。
第三方 form-urlencoded 回调也用 DTO（如 @ModelAttribute）接收。签名 SDK 必须用 Map 时，只能在 Controller 边界之后由 DTO 转换，不能把 Map 暴露为接口入参。
DTO 仅承载请求数据，不在 DTO 字段上使用 Bean Validation 注解，也不依赖 @Valid / @Validated 返回业务校验错误。
业务校验放在 Controller 或 Service，并通过 MessageUtils.message(...) 等项目国际化机制返回错误，禁止硬编码单一语言错误信息。

后端构建和模块边界

Maven 编译目标为 JDK 21。本机使用 C:\Users\qmj\.jdks\graalvm-jdk-21.0.7；只在当前命令环境临时设置 JAVA_HOME 和 PATH，不要修改用户全局 Java 配置。
模块依赖方向必须保持 ruoyi-admin -> ruoyi-system。禁止 ruoyi-system 反向依赖或导入 com.ruoyi.app.*。
同时依赖外部 HTTP（httpclient4 + fastjson2）和应用层 Service 的集成代码放在 ruoyi-admin，不要放入 ruoyi-system。
Java 块注释或 Javadoc 正文中禁止出现额外的 */。描述 ATM_*、CVS_* 等通配值时，写成“ATM 系列”“CVS 系列”，避免提前关闭注释。

数据库和全栈字段变更

不直接执行任何数据库结构或数据迁移操作。所有 ALTER TABLE、数据迁移等 SQL 写入 updatesql/sql.md，标注日期和用途，由开发者统一手动执行。
添加新字段时按顺序检查并更新：Java Entity、MyBatis XML 的 resultMap 和相关 select/insert/update、DTO、Service、Controller、Vue 组件、四个 i18n 文件、SQL 迁移脚本。

前端和 i18n

平台端和商家端所有新增用户可见文本都必须使用 $t()，不得硬编码中文。
商家端语言文件位于 src/lang/zh.js、tw.js、en.js、vi.js；新增 key 必须四个文件同时添加，名称完全一致。
i18n key 使用有意义的英文驼峰命名，禁止 text1、text2 等无意义编号。
key 必须放进调用路径对应的嵌套对象。例如 $t('foots.AddCategoryFirst') 对应的 key 必须位于 foots 对象内部。
编辑 foodie-store 和 foodie-admin-vue 时保留 CRLF。先确认原始换行风格，避免字符串替换失败或造成整文件换行变化。

商家和订单查询规则

InfoUser.userType = 1（普通商家）：使用 PosOrder.shId = userId。
InfoUser.userType = 3（夜市商家）：使用 PosOrder.shId = userId。
其他摊位商家：先读取 InfoUser.storeId，再使用 PosOrder.mdId = InfoUser.storeId。
字段含义：InfoUser.userType 为 0 用户、1 商家、2 骑手、3 夜市；PosOrder.shId 是商家 ID，PosOrder.mdId 是门店 ID。

spec-kit 和规格文件

用户提到 spec kit、spec-kit 或 speckit 时，指 GitHub github/spec-kit；项目配置在 .specify/，规格在 specs/。
新功能默认遵循 specify -> plan -> tasks -> implement。
已有功能追加或变更时，更新现有 spec.md、plan.md、tasks.md 并顺延任务；除非用户明确要求，不重新启动完整流程。
OMG 支付相关工作开始前阅读 specs/016-omg-payment/plan.md。

特定业务约束

餐桌码必须覆盖普通商家，不能只按夜市摊主或夜市管理员设计权限；普通商家也能查看自己门店的餐桌码及关联订单。
涉及支付、退款、配送和订单状态时，以当前有效入口和最新规格为准；不要把仅修改数据库状态等同于真实支付、退款或配送流程。

验证要求

根据改动风险运行最小且充分的检查；优先运行受影响模块的编译、单元测试或定向测试。
交付前检查 git diff，确认没有无关文件、整文件格式化、编码或换行变化。
如果受环境或外部服务限制无法完成验证，明确说明未验证项和原因，不把推测描述为已验证结果。

AGENTS.md 7.1 KB تاريخچه خام