# 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  
- [ ] 文档包含：改动文件列表 + 验证步骤 + 回滚方式  

---

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