【4】前后端交付标准：50 条自检与验收清单

## 为什么需要「交付标准」

AI 写代码很快，但默认：

- 只实现 happy path  

- 用 HTTP 状态判断业务成败  

- 把后端字段原样展示  

- 单文件堆满逻辑  

**交付标准** 的作用：给 AI 和人类同一套 **可检查的清单**。仓库 `ai-native` 中完整版位于 `.cursor/skills/fullstack-dev-standards/SKILL.md`，Agent 可直接引用。

本文摘录博客读者最该记住的 **20%**。

---

## 统一 HTTP 响应契约（前后端共同）

```text

HTTP Status: 200（请求到达并走通网关/服务时）

Body: { code, data, message }

```

| body.code | 含义 |

|:---:|:---|

| 200 | 成功，`data` 为载荷 |

| 400 | 参数或业务可修正错误 |

| 401 | 未登录 / 登录过期 |

| 403 | 无权限 |

| 500 | 服务器内部错误 |

### 前端必须遵守

- 在 `utils/request.ts`（或等价封装）**统一解析** body。  

- **禁止**：HTTP 2xx 就 toast「操作成功」。  

- 业务成败看 **`body.code`**，不是 HTTP 状态码。

### 后端必须遵守

- 业务错误返回 **稳定业务码 + 可读 message**（message 可直接展示）。  

- **禁止**：用 HTTP 4xx/5xx 表达业务失败（与上述公司约定冲突时以团队规范为准）。

---

## 前端十条铁律

1. **不只写成功流** —— 失败可重试，空态有引导。  

2. **状态闭环** —— loading / error / empty / success / submitting。  

3. **交付信息，不是字段** —— `status: 2` →「订舱中」。  

4. **分层** —— Page → Component → Composable → Service → Types。  

5. **防御式** —— 空值、枚举、日期兜底。  

6. **最小变更** —— 改文案不顺手重构。  

7. **可观测** —— 错误含页面、接口、code、traceId。  

8. **权限体验** —— 前端隐藏/置灰；**后端仍校验**。  

9. **性能边界** —— 分页、防抖、取消旧请求；禁止一次拉全量。  

10. **人工验收** —— AI 产出必须过清单，不能「能跑就算完」。

### 推荐目录（Vue 3 + TS）

```text

views/          # 页面组装

components/     # 展示组件

composables/    # 状态与逻辑

services/       # HTTP（禁止写在 .vue 里）

types/          # DTO / ViewModel

constants/      # 枚举映射

```

### 列表页必做

| 场景 | 要求 |

|------|------|

| 首屏加载 | loading |

| 接口失败 | error + 重试 |

| 无数据 | empty |

| 筛选变更 | `pageNo` 重置为 1 |

| 删除 | 二次确认 |

---

## 后端十条铁律

1. **不只 CRUD 成功路径** —— 异常、权限、并发、脏数据都要设计。  

2. **统一 Result** —— `{ code, data, message }`。  

3. **业务成败看 body.code**。  

4. **分层不跨层** —— Controller → Service → Mapper。  

5. **DTO / VO / Entity 分离** —— Entity 不直出 API。  

6. **写操作可追踪** —— traceId、操作人、脱敏。  

7. **幂等与防重** —— 提交类接口必须防重复。  

8. **权限服务端强制** —— 前端隐藏按钮 ≠ 安全。  

9. **性能** —— 分页、禁 N+1、禁 `select *`。  

10. **人审后上线** —— 接口能通 ≠ 可交付。

### 推荐分层

```text

controller/     # 校验、鉴权、返回封装

service/        # 业务、事务

mapper/         # 数据访问

dto/ / vo/      # 入参 / 出参

entity/         # 持久化模型

common/         # Result、异常、错误码

```

### 写操作清单

- [ ] `@Valid` 或等价校验  

- [ ] `@Transactional(rollbackFor = Exception.class)`  

- [ ] 幂等策略（令牌 / 唯一键 / 状态机）  

- [ ] 权限注解 + 数据权限  

---

## 合并验收清单（打印贴显示器旁）

### 前端

- [ ] loading / error / empty 完整  

- [ ] 分页 total 正确；筛选后回第一页  

- [ ] 无权限按钮隐藏或置灰 + 原因  

- [ ] 防重复提交；删除二次确认  

- [ ] 状态展示业务文案；错误非「系统异常」  

- [ ] 保存失败：弹窗不关、保留输入  

### 后端

- [ ] 入参校验完整  

- [ ] 统一 Result 与业务错误码  

- [ ] 权限校验（含数据权限）  

- [ ] 写操作事务 + 幂等  

- [ ] 列表分页，禁止一次返回全量  

- [ ] 日志含 traceId；无敏感明文  

---

## Demo vs 可交付

| Demo 特征 | 可交付特征 |

|-----------|------------|

| 写死数据 | 真实接口 + 类型 |

| 无 loading/error | 状态闭环完整 |

| 无权限/分页 | 权限 + 分页 + 校验 |

| 字段原样展示 | ViewModel 映射 |

| 单文件 900 行 | 分层清晰 |

| 无事务/幂等 | 写操作可追踪、可防重 |

---

## 给 AI 的修复指令模板

### 前端

```text

请基于 [页面/模块] 重构，要求：

1. 接口请求抽到 services/xxxService.ts

2. 新增 types/xxx.ts，禁止 any

3. 表格拆成 components/xxx/XxxTable.vue

4. 状态逻辑放 composables/useXxx.ts

5. 完整处理 loading/error/empty

6. status 走统一枚举映射

7. 支持分页；筛选变更重置 pageNo

8. 保持现有功能，不引入不必要依赖

```

### 后端

```text

请实现/重构 [模块] 接口，要求：

1. 分层：Controller / Service / Mapper / DTO / VO

2. 入参 @Valid；统一 Result<code,data,message>

3. @Transactional(rollbackFor = Exception.class)

4. 幂等：重复提交返回明确业务错误

5. 权限注解 + 数据权限

6. 日志含 traceId；敏感字段脱敏

7. 禁止 select *、禁止循环查库

8. 不改动无关模块

```

在 Cursor 中发送上述模板时，加上：**「遵守 fullstack-dev-standards skill。」**

---

## 人不能全交给 AI 的决定

以下必须由人拍板，再让 AI 在边界内实现：

- 页面信息层级与用户主路径  

- 组件/模块拆分边界  

- 权限展示策略（隐藏 vs 置灰）  

- 危险操作交互  

- DTO→ViewModel / Entity→VO 规则  

- 是否引入新依赖  

- **页面/接口是否可以上线**

---

## 本篇小结

- 统一 `{ code, data, message }`，前端看 body.code。  

- 前端重 **状态闭环与分层**；后端重 **分层、幂等、权限**。  

- 用验收清单挡在合并前，而不是上线后。  

- 完整 50 题见仓库 `fullstack-dev-standards` Skill。

---

## 系列导航

| 篇目 | 标题 |

|:---:|------|

| 1 | [AI-Native 是什么？](01-AI-Native是什么.md) |

| 2 | [工具链入门](02-工具链入门.md) |

| 3 | [第一条工作流](03-第一条工作流.md) |

| **4** | **前后端交付标准：50 条自检与验收清单**（本文） |

| 5 | [7 天上手计划与 FAQ](05-七天上手与FAQ.md) |

 

 

---

name: fullstack-dev-standards

description: >-

  Enterprise fullstack development standards for Codex/AI-assisted delivery.

  Covers frontend page state closure, layering, DTO mapping, and backend API

  contracts, layering, idempotency, and observability. Use when implementing

  or reviewing Vue/TypeScript frontend or backend APIs, when generating pages

  or services with Codex, or when the user mentions 前后端规范、交付标准、50题.

disable-model-invocation: true

---

# 前后端开发规范（企业级交付）

用于 **Codex/AI 辅助开发** 与 **人工验收**。核心目标：代码可上线，不是 Demo。

## 何时启用

- 新建/重构页面、接口、列表、表单、弹窗

- 用 Codex 生成或修改前后端代码

- Code Review、验收测试、修复指令编写

- 用户提到：交付标准、happy path、状态闭环、接口契约

## 快速决策

| 场景 | 必做 |

|------|------|

| 列表页 | loading + error + empty + 分页；筛选变更重置 pageNo=1 |

| 表单/弹窗 | 校验、submitting 防重复；失败保留输入、不关弹窗 |

| 危险操作 | 二次确认；后端权限校验；前端隐藏/置灰无权限按钮 |

| 接口消费 | DTO→ViewModel 映射；状态枚举文案；空值/单位/时间格式化 |

| 写接口 | 参数校验、业务码、幂等/防重、事务边界、结构化日志 |

| 大数据 | 后端分页/异步任务；禁止前端一次拉全量或浏览器生成 Excel |

## 前端必守原则

1. **不只写成功流**：成功流决定能不能显示，失败流决定能不能上线。

2. **状态闭环**：loading / error / empty / success / submitting 不可省略。

3. **前端交付信息，不是字段显示器**：枚举转文案、带单位、格式化时间。

4. **分层**：Page 组装 → Component 展示 → Composable 状态 → Service 请求 → Types 类型。

5. **防御式编程**：空值、枚举、日期兜底；不信接口永远完美。

6. **最小变更**：改文案不顺手重构；明确告诉 AI 不要动无关代码。

7. **可观测**：错误须含页面、操作、接口、参数、业务码、traceId/requestId。

8. **权限体验**：后端是安全边界，前端是体验边界（隐藏/置灰+原因）。

9. **性能边界**：分页、防抖、取消旧请求、虚拟滚动、延迟加载附件/邮件。

10. **人工验收**：Codex 产出必须过验收清单，不能「能跑就算完成」。

## 后端必守原则

1. **不只写 CRUD 成功路径**：异常、边界、权限、并发、脏数据都要设计。

2. **统一响应契约**：HTTP 200 + body `{ code, data, message }`（见下方公司约定）。

3. **业务成功 ≠ HTTP 成功**：业务结果看 body.code；业务错误用稳定业务码+可读 message。

4. **分层不跨层**：Controller 入参校验 → Service 业务 → Repository/Mapper 数据；禁止 Controller 直写 SQL。

5. **DTO/VO/Entity 分离**：Entity 不直出 API；字段变更在 DTO/Mapper 层吸收。

6. **写操作可追踪**：日志含 traceId、操作人、关键业务 ID；敏感字段脱敏。

7. **幂等与防重**：提交/支付/同步类接口必须防重复提交（令牌、唯一键、状态机）。

8. **权限服务端强制**：前端隐藏按钮不能替代鉴权。

9. **性能与数据量**：分页查询、禁止 N+1、禁止 select *、大数据导出走异步任务。

10. **Codex 产出须人审**：接口能通 ≠ 可上线。

## 公司 HTTP 响应约定（前后端共同遵守）

```

HTTP Status: 200（请求到达且走通网关/服务时）

Body: { code, data, message }

```

| body.code | 含义 |

|-----------|------|

| 200 | 成功，data 为载荷 |

| 400 | 参数/可修正的业务错误 |

| 401 | 未登录或登录过期 |

| 403 | 无权限 |

| 500 | 服务器内部错误 |

前端：`utils/request.ts` 统一解析，业务代码判断 `result.success` 或 body.code，**禁止** HTTP 2xx 即 toast「成功」。

## 推荐目录结构

**前端（Vue 3 + TS）**

```

views/          # 页面组装

components/     # 展示组件（表格/表单/弹窗）

composables/    # 可复用状态与逻辑

services/       # HTTP 请求（禁止写在 .vue 里）

types/          # DTO / ViewModel / Query 类型

constants/      # 枚举、状态映射

```

**后端（分层）**

```

controller/     # 入参校验、鉴权注解、返回封装

service/        # 业务编排、事务

repository|mapper/  # 数据访问

entity|model/   # 持久化模型

dto/            # 入参

vo/             # 出参

common/         # 统一 Result、异常、错误码

```

## 前端规范明细

### A. 工程思想（1–10）

| # | 要点 | 规范 |

|---|------|------|

| 1 | 不能只写成功流 | 加载中/失败/空/无权限均需处理；失败提供重试 |

| 2 | 状态闭环 | loading、error、empty、success、submitting、disabled、result feedback |

| 3 | 不是字段展示器 | status=2 →「订舱中」；带业务语义、单位、层级 |

| 4 | Vue 文件不能写到底 | Page / Filter / Table / Dialog / composable / service / types |

| 5 | 防御式编程 | 空值、枚举、日期、数组默认 []；不展示 null/undefined |

| 6 | 最小变更 | 小需求小改动；无关重构单独任务 |

| 7 | 可观测性 | 页面、操作、接口、参数、错误码、traceId |

| 8 | 权限与安全 | 无权限隐藏或置灰+原因；后端仍校验 |

| 9 | 性能边界 | 分页、虚拟滚动、后端筛选；10 万条不能一次渲染 |

| 10 | 人工验收 | 检查 happy path、状态、权限、防重、分层、any |

### B. 页面状态与交互闭环（11–20）

| # | 要点 | 规范 |

|---|------|------|

| 11 | 列表为空 | Empty State + 下一步指引（无权限时换文案） |

| 12 | 加载慢 | loading/skeleton；禁用重复查询；超时提示；可重试 |

| 13 | 接口失败 | 位置+原因+用户可做什么+重试/联系管理员 |

| 14 | 保存失败不关弹窗 | 保留输入；展示原因；高亮字段；成功后再关 |

| 15 | 防重复点击 | submitting；按钮 disabled；文案「提交中」 |

| 16 | 删除二次确认 | 明确对象、是否可恢复、删除中 loading |

| 17 | 操作成功更新状态 | 提示成功；更新按钮/状态/时间；必要时刷新 |

| 18 | 批量部分成功 | 成功数/失败数/失败清单/原因/可重试失败项 |

| 19 | 权限不足 | 高风险隐藏；主流程置灰+「暂无权限，请联系管理员」 |

| 20 | 长耗时任务 | 提交任务→「识别中」→轮询/订阅→结果或失败+重试 |

### C. 接口数据消费与展示（21–30）

| # | 要点 | 规范 |

|---|------|------|

| 21 | 状态值不直接展示 | 集中 `StatusTextMap` 维护 |

| 22 | DTO 不直接用于页面 | `mapDTOToViewModel()`；页面只用 ViewModel |

| 23 | 时间格式化 | 按业务场景与时区规则展示 |

| 24 | 空字段兜底 | `-` / `待确认` / 关键字段缺失提示 |

| 25 | 数量带单位 | `12,000 KG`、`58 CBM`、`USD 3,500` |

| 26 | HTTP 成功 ≠ 业务成功 | 判断 body.code / result.success |

| 27 | 业务错误码 | 展示业务 message，勿统一「系统异常」 |

| 28 | 查询参数校验 | 空订舱号不请求；前端 trim |

| 29 | 分页筛选排序联动 | 筛选变→pageNo=1；请求带全参数 |

| 30 | 字段变更降影响 | DTO 类型 + mapper；页面不直绑后端字段 |

### D. 组件结构与可维护性（31–40）

| # | 要点 | 规范 |

|---|------|------|

| 31 | API 不在组件里 | 放 `services/` |

| 32 | 表格职责 | 渲染+事件；不请求接口、不控弹窗 |

| 33 | composable | list/loading/error/分页/fetch 放 `useXxx.ts` |

| 34 | Pinia 不是垃圾桶 | 仅跨页共享：用户、权限、字典 |

| 35 | 重复表格抽组件 | 三次以上+结构稳定可抽象 BaseTable |

| 36 | 枚举集中管理 | 禁止多页面复制 if/status 文案 |

| 37 | 业务语义命名 | `bookingList` 非 `data`/`flag` |

| 38 | 避免 any | 定义 `BookingItem` 等接口 |

| 39 | 大列表不一次加载 | 后端分页；必要时虚拟滚动 |

| 40 | 搜索防抖 | 300ms 防抖；取消旧请求；重置分页 |

### E. 可靠性、性能与边界（41–44）

| # | 要点 | 规范 |

|---|------|------|

| 41 | 请求竞态 | 取消旧请求 / 请求序号 / 只采纳最后一次 |

| 42 | 附件邮件延迟加载 | 首屏核心信息；原文折叠；点击预览 |

| 43 | 页面慢定位 | Network vs Performance；接口 vs 渲染分开看 |

| 44 | 大数据导出 | 提交任务→异步生成→状态轮询→下载链接 |

### F. Codex 协作与交付（45–50）

| # | 要点 | 规范 |

|---|------|------|

| 45 | 生成前上下文 | 技术栈、目录、request、权限、验收标准 |

| 46 | Demo vs 交付 | 见下方对照表 |

| 47 | 验收测试 | 正常/空/失败/分页/校验/权限/防重/业务文案 |

| 48 | 不能全交 AI | 信息层级、主路径、拆分、权限策略、性能 |

| 49 | 修复指令 | 明确改什么、放哪里、不要改什么 |

| 50 | 开发者必须清楚 | 业务问题、主流程、状态、接口、权限、风险、测试覆盖 |

**前端推荐模式**

```typescript

const result = await bookingService.submit(form)

if (result.success) {

  message.success('提交成功')

  await refreshDetail()

} else {

  message.error(result.message || '提交失败')

}

// useBookingList.ts — list, loading, errorMessage, pageNo, pageSize, total, fetchList

// BookingPage.vue — 组装 Filter + Table + Dialog

// bookingService.ts — getBookingList(query)

```

## 后端规范明细

### A. 工程思想（1–10）

| # | 要点 | 规范 |

|---|------|------|

| 1 | 不能只写 CRUD 成功路径 | 校验失败、业务冲突、无权限、下游超时均需明确响应 |

| 2 | 接口状态闭环 | 同步结果 / 异步任务状态 / 失败可重试 均需可查询 |

| 3 | 不是数据库字段直出 | VO 带业务语义；敏感字段脱敏或不返回 |

| 4 | 单类不能写到底 | Controller / Service / Mapper / DTO / VO 拆分 |

| 5 | 防御式编程 | 外部系统、历史脏数据、空字段；不假设输入永远合法 |

| 6 | 最小变更 | 改一个接口字段不顺手重构全模块 |

| 7 | 可观测性 | traceId、操作人、bizId、耗时；错误可定位到 SQL/下游 |

| 8 | 权限与安全 | 鉴权在服务端；数据权限按租户/组织过滤 |

| 9 | 性能与数据边界 | 分页上限、导出异步、禁止一次返回 10 万行 |

| 10 | 人工验收 | 能调通 ≠ 可上线 |

### B. 接口设计与事务闭环（11–20）

| # | 要点 | 规范 |

|---|------|------|

| 11 | 空列表语义 | 返回 `[]` + total=0；与「查询异常」区分 |

| 12 | 慢查询 | 超时配置；>3s 考虑异步任务+进度查询 |

| 13 | 失败响应 | code + message + 可选 details；前端能展示「下一步」 |

| 14 | 写失败不丢上下文 | 业务错误返回具体字段；支持幂等重试 |

| 15 | 防重复提交 | 幂等键 / 状态机 / 唯一约束；重复返回明确业务码 |

| 16 | 删除/高危操作 | 软删或审计日志；批量删除返回明细 |

| 17 | 写成功返回最新状态 | 返回更新后 VO（状态、时间、操作人） |

| 18 | 批量部分成功 | `{ successCount, failCount, failures[] }` |

| 19 | 权限不足 | 403 + 明确 message；不返回 500 掩盖 |

| 20 | 长耗时任务 | 创建任务→返回 taskId→查询进度/结果接口 |

### C. 数据模型与契约（21–30）

| # | 要点 | 规范 |

|---|------|------|

| 21 | 状态存 code 非文案 | DB/API 用枚举值；文案由映射表维护 |

| 22 | Entity ≠ API 模型 | Entity 内部；DTO 入参；VO 出参 |

| 23 | 时间字段 | 存储 UTC/统一时区；API 文档注明格式 |

| 24 | 空值约定 | null 语义明确；Optional 字段文档化 |

| 25 | 数值带单位 | amount+currency、weight+unit 等约定 |

| 26 | HTTP 200 + 业务 code | 统一 `{ code, data, message }` |

| 27 | 稳定业务错误码 | 如 `BOOKING_ALREADY_SUBMITTED` |

| 28 | 入参校验 | `@Valid`；非法参数 400 + 字段级提示 |

| 29 | 分页排序筛选 | 统一 PageQuery；筛选变更由前端重置页码 |

| 30 | 字段演进 | 新增字段向后兼容；废弃字段保留过渡期 |

### D. 分层架构与可维护性（31–40）

| # | 要点 | 规范 |

|---|------|------|

| 31 | Controller 薄 | 校验、鉴权、调用 Service、封装 Result |

| 32 | Service 职责 | 业务编排、事务、领域规则；不拼 SQL |

| 33 | Mapper/Repository | 数据访问；禁止循环内单条查询（N+1） |

| 34 | 常量与枚举集中 | ErrorCodes、PermissionCodes、LockKeys |

| 35 | 重复 CRUD 模式 | 代码生成或基类；不复制粘贴五层 |

| 36 | 枚举统一管理 | 禁止魔法数字散落 Service |

| 37 | 业务语义命名 | `submitBooking` 非 `handle`/`doProcess` |

| 38 | 避免 Map 裸传 | 强类型 DTO/VO |

| 39 | 列表必须分页 | 默认 pageSize 上限（如 50/100） |

| 40 | 查询优化 | 索引、避免 select *、必要字段投影 |

### E. 可靠性、性能与安全（41–50）

| # | 要点 | 规范 |

|---|------|------|

| 41 | 并发与竞态 | 分布式锁 / 乐观锁 / 唯一约束 |

| 42 | 大字段分离 | 邮件原文、附件元数据分接口或延迟加载 |

| 43 | 慢接口定位 | 日志耗时、SQL explain、下游调用链 |

| 44 | 大数据导出 | 异步任务 + 文件存储 + 下载 URL + 过期时间 |

| 45 | Codex 上下文 | 技术栈版本、包结构、Result 封装、禁止项 |

| 46 | Demo vs 交付 | 无校验、无权限、无事务、无测试 = Demo |

| 47 | 接口验收 | 正常/边界/无权限/重复提交/分页/业务冲突 |

| 48 | 人必须决策 | 事务边界、幂等策略、缓存、是否引入中间件 |

| 49 | 修复指令 | 明确分层落点、不改无关模块 |

| 50 | 开发者须清楚 | 业务规则、状态机、依赖下游、回滚方案 |

**后端 Anti-patterns**

| 禁止 | 应做 |

|------|------|

| Entity 直出 API | 转 VO |

| select * | 明确字段 |

| 循环内查库 | join / batch / in 查询 |

| 裸 throw RuntimeException | 业务异常 + 错误码 |

| 魔法字符串 | 常量类 / 枚举 |

| 无 rollbackFor 的事务 | `@Transactional(rollbackFor = Exception.class)` |

| 前端防重代替后端 | 前后端双重防护 |

**与前端协作契约**

- 列表：返回 `{ list, total, pageNo, pageSize }` 或公司统一分页结构

- 提交：body.code=200 且 data 含最新状态；失败 message 可直接展示

- 长任务：返回 taskId；提供 `GET /tasks/{id}` 查询

- 导出：`POST /export` 创建任务；`GET /export/{id}` 查状态与 downloadUrl

- 字段命名：团队统一 snake_case 或 camelCase；变更只改 mapper 层

## 实施工作流

### 开发前（给 Codex 的上下文）

至少提供：技术栈与版本、目录规范、请求封装、权限方式、表格/表单规范、状态处理规范、枚举位置、**允许改哪些文件 / 禁止改哪些**、验收标准。

### 实现中

- 先定 **状态闭环** 与 **组件/模块边界**，再让 AI 填实现

- 页面禁止：`any`、直绑后端字段、900 行单文件、API 写在组件内

- 接口禁止：Entity 直出、循环查库、裸抛 Exception、魔法字符串

### 验收清单

**前端**

- [ ] loading / error / empty 完整

- [ ] 筛选后回第一页；分页 total 正确

- [ ] 无权限按钮隐藏或置灰+说明

- [ ] 防重复提交；删除二次确认

- [ ] 状态展示业务文案；业务错误非「系统异常」

- [ ] 保存失败弹窗不关、保留输入

**后端**

- [ ] 参数 @Valid / 手动校验

- [ ] 统一 Result 与业务错误码

- [ ] 权限注解或等价校验

- [ ] 写操作事务 `rollbackFor = Exception.class`

- [ ] 幂等/防重（提交类）

- [ ] 分页接口带 total；列表不一次返回全量

- [ ] 日志含 traceId；无敏感信息明文

### 修复指令模板

**前端**

```

请基于 [页面/模块] 重构，要求：

1. 接口请求抽到 services/xxxService.ts

2. 新增 types/xxx.ts，禁止 any

3. 表格拆成 components/xxx/XxxTable.vue

4. 状态逻辑放 composables/useXxx.ts

5. 完整处理 loading/error/empty

6. status 走统一枚举映射

7. 支持分页；筛选变更重置 pageNo

8. 保持现有功能，不引入不必要依赖

9. 输出文件结构与关键代码

```

**后端**

```

请实现/重构 [模块] 接口，要求：

1. 分层：Controller / Service / Mapper / DTO / VO，禁止 Controller 直调 Mapper

2. 入参 @Valid；统一 Result<code,data,message>

3. 业务错误码可读；message 可直接展示

4. @Transactional(rollbackFor = Exception.class)

5. 幂等：重复提交返回明确业务错误，不重复写库

6. 权限注解 + 数据权限过滤

7. 日志含 traceId、bizId；敏感字段脱敏

8. 禁止 select *、禁止循环查库

9. 保持现有 API 兼容，不改动无关模块

10. 输出接口说明、关键类、必要单元测试

```

## Demo vs 可交付

| Demo 特征 | 可交付特征 |

|-----------|------------|

| 写死数据 | 真实接口 + 类型 |

| 无 loading/error | 状态闭环完整 |

| 无权限/分页 | 权限+分页+校验 |

| 字段原样展示 | ViewModel + 映射 |

| 单文件堆逻辑 | 分层清晰 |

## 人不能全交给 Codex 的决定

- 页面信息层级与用户主路径

- 组件/模块拆分边界

- 权限展示策略（隐藏 vs 置灰）

- 危险操作交互

- DTO→ViewModel / Entity→VO 规则

- 是否引入新依赖、是否改原有交互

- **页面/接口是否可以上线**