DOPJAVA/docs/qms/codex-dev-playbook.md

Codex 提示词（WSL + VS Code + 芋道/Yudao）前后端开发与自校验规范

用途：把本文件放入项目（建议 docs/codex-dev-playbook.md 或根目录 CODEX_DEV_PROMPT.md），用于驱动 Codex 自行开发 + 自行校验。
目标：在当前系统（WSL2 + VS Code Remote-WSL + 多模块 Maven + pnpm 前端）下，快速、稳定地完成“需求→代码→联调→验收”。

---

0. 你的角色与输出要求（给 Codex 的总指令）

你是项目的“全栈工程助手”，需要在不遗漏工程化细节的前提下完成开发任务。每次改动必须满足：

• 最小可跑通：后端接口可启动可调用；前端页面可访问可返回列表/详情。
• 工程一致性：遵循芋道项目分层与命名规范；模块边界清晰。
• 自校验：每次交付都包含 *如何验证*（命令/URL/返回示例/截图点位）。
• 不走捷径：不要用临时 hardcode 绕开权限/租户/路由，除非明确写在“临时方案”并给出回滚方式。

输出格式固定为：

1) 你要做什么（任务拆解清单）
2) 你改了哪些文件（文件路径列表 + 关键 diff）
3) 你如何验证（命令 + 预期结果）
4) 风险与回滚（潜在影响 + 如何撤销）

---

1. 环境与工具链硬约束（避免踩坑）

1.1 WSL 下运行后端：禁止“单文件运行”

• 禁止使用 VS Code Code Runner 的 *Run Code*（它只会 javac 单文件，会导致 org.springframework.boot 等依赖找不到）。
• 必须使用 Maven/IDEA/Java 扩展的 Run Java 或 Maven 命令启动。

1.2 多模块 Maven：在哪个目录执行很关键

• 聚合根目录不一定声明 spring-boot 插件，根目录直接 mvn spring-boot:run 可能失败。
• 推荐命令（任选其一）：
  • cd yudao-server && mvn -DskipTests spring-boot:run
  • 或：mvn -pl yudao-server -am -DskipTests org.springframework.boot:spring-boot-maven-plugin:run

1.3 新增模块后：必须 install 一次

• 新增 yudao-module-xxx 或改依赖后：
  • mvn -pl yudao-module-xxx -am -DskipTests install
• 否则 VS Code / Maven 会提示本地仓库缺 jar（~/.m2 不存在）。

1.4 前端 baseURL：必须指向后端，不要请求打到 5173

• .env.local 必须配置（示例）：
  • VITE_BASE_URL='http://127.0.0.1:48080'
  • VITE_API_URL=/admin-api
• 如验证码接口 404（打到 5173），优先检查 baseURL 与代理。

---

2. 项目开发总流程（强制遵循的“从 0 到 1”）

当你接到一个业务模块（如 IQC 申请列表）需求时，按以下顺序执行：

2.1 先定“接口契约”（VO），再定“数据映射”（DO）

1) 明确前端需要的字段与含义（含显示名/枚举中文/时间格式）。
2) 先创建 VO：*RespVO / *PageReqVO 等。
3) 之后再考虑 DO / entity / 表字段映射（如果需要）。

2.2 模块边界：优先拆独立模块

• 建议将业务放入独立模块，例如：
  • yudao-module-qms（质量相关）
• 目的：隔离依赖、便于发布、避免污染 system 等核心模块。

2.3 后端开发顺序（固定）

1) Controller：定义路由与入参（分页、筛选）。
2) Service：定义业务接口与实现（先跑通空分页也行）。
3) Mapper + XML：落地 SQL（再逐步补齐 join/聚合）。
4) 权限/租户：对齐项目现有注解与过滤器，不要私自绕过。
5) Swagger/Knife4j：确保接口可在文档里调通。

2.4 前端开发顺序（固定）

1) API 封装：src/api/... 定义请求与返回类型。
2) 页面与路由：保证 list/detail/edit 等页面可访问。
3) 菜单/权限：如走动态路由，确保后端菜单配置可生成路由。
4) 联调：Network 检查 URL 是否正确（不是 5173）。

---

3. 动态路由 / 菜单（最常见 404 的根因与规则）

3.1 菜单 path 规则（硬规则）

• 子菜单 path 不要以 “/” 开头，并且必须相对父菜单。
• 否则最终路由拼接会错，导致“返回列表 404”。

3.2 动态路由缓存

• 前端通常缓存 roleRouters（或类似字段）。
• 菜单/路由改动后必须清缓存（localStorage/sessionStorage）并刷新，否则仍旧 404。

3.3 “返回列表 404”的诊断 checklist

当你发现“新增/编辑/查看后返回列表 404”： 1) 打开控制台打印当前注册 routes，确认是否存在 /xxx/list。
2) 若只有 new/edit/view，而没有 list，则：

• 要么 list 页面没注册路由
  
• 要么动态路由菜单没下发 list
  3) 修复后清缓存再验证。

---

4. IQC 申请列表的字段口径与 SQL 聚合规范（可复用模板）

4.1 列表主键与显示

• 返回给前端的 id 用 FBILLNO（或按需求指定的业务单号），而非数据库自增 id（除非前端明确要求）。

4.2 申请人字段

• FAPPLYUSER 存用户 id，列表显示需要 join system_users.id -> system_users.username。

4.3 状态聚合（示例规则）

• 主表状态由子表汇总得出（示例优先级）： 1) 若任一子表为“检验中” → 主表“检验中” 2) 否则若所有子表“检验完成” → 主表“检验完成” 3) 否则 → 主表“待检验”
• 需要同时返回：子表总数、完成数、检验中数（便于前端展示与筛选）。

注意：状态中文化建议由后端返回中文（避免前端二次映射出错），除非项目规范要求前端映射。

---

5. 交付时必须包含的自校验（不写=未完成）

5.1 后端自检命令（必须给出）

• 编译：
  • mvn -pl yudao-server -am -DskipTests package
• 新模块依赖安装（如新增模块）：
  • mvn -pl yudao-module-qms -am -DskipTests install
• 启动：
  • cd yudao-server && mvn -DskipTests spring-boot:run

5.2 接口自检（必须给出）

• 以 Swagger/Knife4j 或 curl 方式，提供：
  • URL
  • Header（token、tenant-id）
  • 请求参数示例
  • 返回 JSON 示例（至少包含关键字段）

5.3 前端自检（必须给出）

• 启动：
  • pnpm i
  • pnpm dev
• 检查点： 1) Network 请求 baseURL 是否指向后端端口 2) 列表页能否加载 3) 新增/编辑/查看返回列表是否 404 4) 清缓存后动态路由是否生效

---

6. Codex 开发提示词模板（复制即用）

你可以直接把下面这一段当作每次给 Codex 的 Prompt 开头。

6.1 通用开发 Prompt

• 任务：在当前项目（WSL + VS Code Remote-WSL + 多模块 Maven + pnpm 前端）下，实现【填业务功能】。
• 约束： 1) 禁止单文件运行 Spring Boot；必须通过 Maven 启动与编译校验。 2) 若新增模块或依赖，必须执行 mvn -pl <module> -am -DskipTests install。 3) 前端 baseURL 必须指向 http://127.0.0.1:48080（或项目实际端口）。 4) 动态路由：子菜单 path 不能以 / 开头；改菜单后清缓存验证。
• 输出要求（必须逐项给出）： 1) 任务拆解清单 2) 修改文件路径列表 + 关键 diff 3) 自校验命令与预期结果（后端/前端/接口） 4) 风险与回滚方案

6.2 IQC 申请列表 Prompt（示例）

• 任务：实现 IQC 来料检验“申请列表”接口与前端页面联调，要求：
  • 列表主键返回 FBILLNO（作为 id）。
  • FAPPLYUSER 关联 system_users 显示申请人 username。
  • 状态从子表聚合得到，并返回中文：待检验/检验中/检验完成。
  • 返回分页字段符合芋道分页规范。
• 交付：接口可在 Swagger 调通，前端列表可加载且“返回列表”不 404。

---

7. 快速故障定位（遇到问题先按这里排）

7.1 后端启动类报错

• package org.springframework.boot does not exist：
  • 你用错了运行方式（单文件 javac），改用 Maven 启动。
• No plugin found for prefix 'spring-boot'：
  • 你在聚合根目录运行了，cd 到 yudao-server 或用插件全坐标。
• “缺 jar / m2 不存在”：
  • 新增模块未 install：mvn -pl <module> -am -DskipTests install

7.2 前端接口 404

• 请求打到 5173：
  • baseURL 未配置或 env 没生效，检查 .env.local，重启 dev。

7.3 页面返回列表 404

• routes 没有 list：
  • 路由未注册或动态菜单未下发 list。
• 改菜单没生效：
  • 清 roleRouters 等缓存，硬刷新。

---

8. 你必须遵循的“完成定义”（Definition of Done）

只有同时满足以下条件才算完成：

---

9. 今日问题记录（IPQC 任务 / 2026-01-22~23）

9.1 后端 500：多租户自动拼接 tenant_id

• 现象：/admin-api/qms/ipqc-task/page 报 500，日志里出现 Unknown column 'tenant_id'。
• 根因：多租户拦截器自动追加 tenant_id，但 WorkOrdMaster / ItemMaster / mes_morder / qms_gcjyd 无该字段。
• 处理：在 yudao-server/src/main/resources/application.yaml 的 yudao.tenant.ignore-tables 增加这四张表，避免注入。

9.2 后端 404：接口未注册

• 现象：请求命中 127.0.0.1:48080 仍返回 {"code":404,"msg":"请求地址不存在:admin-api/qms/ipqc-task/page"}。
• 根因：本地运行的 yudao-module-qms jar 不是最新，IpqcTaskController 未被打包进运行时。
• 处理： 1) 先执行 mvn -pl yudao-module-qms -am -DskipTests install
  2) 再重启 yudao-server 3) 可用 jar tf ~/.m2/repository/.../yudao-module-qms-*.jar | rg IpqcTaskController 验证

9.3 后端启动失败：端口占用

• 现象：启动时报 Port 48080 was already in use。
• 处理：停止旧进程（ss -ltnp | rg :48080 找 PID，再 kill <pid>），再启动。

9.4 VS Code JMX 刷新失败提示

• 现象：Failed to refresh live data from process service:jmx...
• 结论：仅 VS Code Spring Boot Dashboard 监控失败，不影响接口功能，可忽略或重连监控。

9.5 验证方法（最小闭环）

• 后端直连验证：
  curl "http://127.0.0.1:48080/admin-api/qms/ipqc-task/page?pageNo=1&pageSize=20&status=pending"

• 预期返回：
  未登录返回 401；登录后应返回 code=0 且有分页结构。

• [ ] 后端 mvn -pl yudao-server -am -DskipTests package 通过

• [ ] 后端启动后接口可访问（Swagger/curl）

• [ ] 前端启动后列表页可打开、可加载数据

• [ ] 新增/编辑/查看后返回列表不 404

• [ ] 文档包含：改动文件列表 + 验证步骤 + 回滚方式

---

维护建议：每做完一个模块，把“字段口径/状态规则/路由菜单坑点”沉淀在本文件的对应章节，逐步形成团队的工程手册。