|
|
@@ -0,0 +1,95 @@
|
|
|
+# 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`，确认没有无关文件、整文件格式化、编码或换行变化。
|
|
|
+- 如果受环境或外部服务限制无法完成验证，明确说明未验证项和原因，不把推测描述为已验证结果。
|
qmj