企业官网建设流程全解析

搭建一个基于 Vue3 的后台管理系统，主要包含商户库存、周期询价、实时查价、供应商 Top10 等业务模块。项目本身并不复杂到需要特别强调业务，但它非常适合作为 Codex 的实践案例，因为它具备典型后台项目的特点：页面多、字段多、接口多、需求变化频繁、交互细节不断调整。开发过程中，Codex 参与了代码 Review、架构统一、接口接入、页面重构、状态轮询、跨模块跳转、供应商详情复用和构建校验等工作。

通过这个项目，可以比较清楚地看到：Codex 的价值并不只是生成一段代码，而是能够围绕一个真实工程持续推进任务。

1. Codex 更适合“工程任务”，而不只是代码片段生成

很多人第一次使用 AI 编程工具时，习惯把它当成一个代码问答助手。比如问它“这个函数怎么写”“这个组件怎么封装”“这个报错是什么意思”。这些当然可以，但不是 Codex 最有价值的地方。

在真实项目里，一个需求通常不是写一个函数就结束。例如“接入实时查价模块”这个需求，背后包含很多步骤：

• 阅读接口文档
• 理解接口路径、参数和响应字段
• 查看项目中已有 API 封装风格
• 新增 TypeScript 类型
• 新增接口请求函数
• 修改 Vue 页面
• 删除 mock 数据
• 增加 loading 和 error 状态
• 增加筛选条件
• 增加分页
• 增加批次展开
• 增加任务列表
• 增加供应商详情跳转
• 运行类型检查和构建
• 根据报错继续修正

如果只是普通代码生成工具，可能只能完成其中一小段。但 Codex 更像是在执行一个完整工程任务。它会先查项目结构，再看已有代码，再决定在哪里新增文件、在哪里修改组件、在哪里改路由。这个过程更接近一个开发者接手需求后的工作方式。

所以，使用 Codex 时，建议不要只把问题拆成很碎的代码片段，而是可以直接给它一个工程目标。例如：

按照接口文档接入实时查价模块，保持和现有 Vue3 架构一致。

这样的指令比“帮我写一个请求函数”更能发挥 Codex 的能力。

2. 让 Codex 顺着项目架构工作

在这个 Vue3 项目中，代码结构相对清晰：

• 页面组件放在src/components
• API 请求封装放在src/api
• 路由集中在src/router/index.ts
• 通用 HTTP 请求在src/api/http.ts
• 样式主要使用 Tailwind CSS

当接入新模块时，比较好的方式不是让 Codex 直接在页面里写fetch，而是让它先观察现有结构。比如项目中已经有：

src/api/inventory.ts src/api/periodic.ts

那么接入实时查价时，Codex 就会新增：

src/api/realtime.ts

并在其中封装实时查价相关接口，例如：

getRealtimeBatches()addRealtimeBatch()getRealtimeBatchTasks()getRealtimeSuppliers()

页面组件只负责调用这些 API，而不是把请求逻辑散落在模板组件中。

这一点很重要。AI 写代码最大的风险之一，是生成的代码“能跑但不融入项目”。如果每次需求都生成一套自己的结构，项目很快会变得难维护。Codex 的优势是可以阅读现有代码，并按已有风格继续扩展。

所以在实际使用中，给 Codex 的指令可以强调：

按现有 API 封装风格实现。
保持和现有页面组件结构一致。
不要新增重复页面，优先复用已有组件。

这些约束会让 Codex 更像团队成员，而不是外部代码生成器。

3. 接口文档驱动开发非常适合 Codex

这个项目中有一份接口文档frog-bid-api.md，里面定义了商户库存、周期询价、实时查价等接口。Codex 非常适合处理这种“接口文档到前端代码”的转换。

以实时查价模块为例，接口包括：

• 获取实时查价门店列表
• 获取实时查价车型名称列表
• 获取实时查价车型配置明细列表
• 获取实时查价起租日期列表
• 新增实时查价批次
• 获取实时查价批次列表
• 获取批次下任务列表
• 获取实时查价供应商 Top10

这些接口如果人工逐个接入，需要不断复制字段、写类型、写请求函数、写页面逻辑。Codex 可以根据文档中的路径、参数和响应字段，快速补齐 TypeScript 类型和请求方法。

例如它会为批次、任务、供应商等定义类型：

exportinterfaceRealtimeBatch{...}exportinterfaceRealtimeTask{...}exportinterfaceRealtimeSupplier{...}

然后在组件中使用这些类型，减少字段拼写错误和结构不清晰的问题。

不过，接口文档驱动开发有一个前提：文档要准确。如果后端更新了字段，就需要明确告诉 Codex：

实时查价接口已更新至frog-bid-api.md，按最新文档调整。

Codex 可以高效执行“文档到代码”的工作，但它不能自动知道后端刚刚改了什么。因此，接口文档的及时同步仍然是人的责任。

4. TypeScript 校验让 Codex 更可靠

Codex 写代码很快，但真正让它适合工程实践的关键，是修改后的校验闭环。

这个项目中，每次主要修改后都会运行：

npm.cmd run check

这个命令包含：

vue-tsc--noEmitvite build

也就是说，不只是看代码表面是否合理，还要让 TypeScript 和构建工具实际检查一遍。

这个过程发现过不少问题，例如：

• 类型字段缺失
• 字段加到了错误的接口类型上
• 模板引用了不存在的变量
• import 未使用
• 函数定义后没有被调用
• 路由名称或参数不匹配

比如实时查价任务列表增加“结束日期”时，逻辑需要支持endDate。一开始类型补充到了批次类型中，而不是任务类型中，vue-tsc就直接报错。Codex 根据错误再修正，把endDate?: string补到了RealtimeTask上。

这说明 Codex 的正确使用方式不是“相信它一次生成的代码”，而是让它完成：

修改代码 → 运行检查 → 读取错误 → 修复错误 → 再次检查

这个闭环非常关键。没有校验的 AI 代码只是草稿，有校验闭环后才更接近可交付代码。

5. Vue3 单文件组件的改造能力

这个项目的大部分开发都发生在.vue单文件组件中。Vue3 的script setup写法让逻辑相对集中，但实际修改时仍然要同时处理：

• TypeScript 类型
• 响应式状态
• computed
• watch
• 生命周期
• 模板结构
• 表格字段
• 按钮事件
• 弹窗状态
• 路由跳转

Codex 在这类组件改造中比较实用，因为它能同时处理脚本区和模板区。

例如需求：

周期询价详情里，数据采集状态放在采集时间后面。

看起来只是换两列顺序，但正确修改需要：

• 调整表头顺序
• 调整对应数据单元格顺序
• 确认空状态和 loading 状态的colspan
• 确认表格最小宽度是否需要调整

再比如：

实时查价任务表格，车型、车牌不需要，前面补充开始日期和结束日期。

这个需求需要：

• 删除任务表中的车型列
• 删除车牌列
• 增加开始日期列
• 增加结束日期列
• 如果接口没有endDate，根据startDate + duration计算
• 补充RealtimeTask.endDate?: string
• 确认构建通过

这些都是典型的前端后台表格需求。人工做并不难，但容易遗漏同步修改。Codex 的优势是可以快速定位相关模板和逻辑，并在修改后运行校验。

6. 后台表格类需求非常适合 Codex

后台系统开发中，表格字段调整是高频工作。比如这个项目中出现过很多类似需求：

• 表格后面加一列
• 某一列移动位置
• 某个字段不显示
• 某个字段改名
• 某些操作按钮互斥
• 某些按钮根据状态禁用
• 任务统计卡片默认收起
• 筛选项增加清除按钮
• 批次号隐藏
• 操作列增加复制按钮

这些需求单个看都很小，但数量多了非常耗时间。更麻烦的是，它们往往需要保持一致性：表头、表体、空状态、宽度、按钮样式都要同步。

Codex 对这种“细碎但有规律”的工作非常擅长。它能快速找到表格区域，修改模板，补充逻辑，并运行构建。人更多负责判断业务规则，而不是花时间在模板中来回查找。

7. 状态流转和轮询逻辑

采集类业务通常有状态变化，例如：

• 待采集
• 采集中
• 采集成功
• 采集失败

如果页面不自动刷新，用户就需要手动刷新或重新查询。这个项目中，实时查价和周期询价都加入了轮询机制。

实时查价的轮询规则是：

• 新建任务成功后，立即刷新批次列表
• 批次列表每 5 秒刷新一次
• 持续 2 分钟后停止
• 当前展开的任务列表每 5 秒刷新一次
• 当任务全部不再是待采集或采集中时停止
• 收起批次或离开页面时停止

周期询价的轮询规则是：

• 任务统计中runningCount > 0或pendingCount > 0
• 每 5 秒刷新任务统计和任务列表
• 当两个值都为 0 时停止
• 查询、重置、翻页、切换批次、离开页面时停止旧轮询

这里 Codex 的实现不只是简单写一个setInterval。真正重要的是边界处理：

• 静默刷新，避免页面每 5 秒闪 loading
• 避免重复开启多个 interval
• 状态结束后自动停止
• 组件卸载时清理定时器
• 查询条件变化时停止旧轮询
• 翻页后按新页面数据重新判断

这些细节对长期运行的后台页面很重要。否则很容易出现重复请求、内存泄漏或页面状态错乱。

8. 路由跳转和页面预填

项目中有一个比较典型的跨模块流程：

在周期询价详情中点击“实时查价”，跳转到实时查价模块，并自动打开新建实时查价弹窗。

这个功能涉及多个技术点：

• 周期询价详情新增按钮
• 只有采集成功时按钮可点击
• 点击后跳转/realtime
• 使用 query 携带城市、门店、渠道、车型、开始日期、取还车时间、租期等字段
• 实时查价页面读取 query
• 自动打开新建弹窗
• 根据渠道和城市门店加载车型配置
• 尽量自动匹配车型配置
• 匹配不到时保留弹窗，让用户手动选择

这个需求如果手写，需要跨多个文件处理状态。Codex 可以同时修改周期询价详情组件和实时查价组件，把跳转、参数解析、弹窗状态和异步加载逻辑串起来。

这种能力在真实后台系统中很有价值。很多业务不是单页面完成，而是从一个模块跳到另一个模块，并带入上下文。Codex 能处理这种跨页面协作逻辑。

9. 组件复用：供应商 Top10 详情

供应商 Top10 详情页最开始用于周期询价，后来实时查价也需要同样的页面展示。如果人工开发，可能会很自然地复制一个新页面。但复制页面会带来维护成本：样式改两遍，字段改两遍，bug 也可能改两遍。

Codex 的处理方式是复用已有SupplierDetail.vue。新增实时查价供应商路由：

/realtime/supplier/:supplierId

然后在供应商详情页中判断来源：

• 如果路径来自/periodic，调用周期询价供应商接口
• 如果路径来自/realtime，调用实时查价供应商接口

这样页面结构、返回逻辑、表格展示都可以复用。

这个例子说明，Codex 不只是会“生成新代码”，也可以帮助做更合理的工程复用。前提是指令要明确，例如：

点击效果和周期询价详情里的“查看供应商价格”保持一致，不要弹窗，跳转新页面。

Codex 就会倾向于复用现有详情页，而不是继续保留弹窗。

10. 新建、复制和预填表单

实时查价模块中有一个很实用的功能：复制已有批次，新建一条类似任务。

实现上需要：

• 在批次表“备注”后增加“操作”列
• 操作列放一个 Copy 风格按钮
• 点击后打开新建实时查价弹窗
• 将当前批次的渠道、城市、车型配置、开始日期、取还车时间、租期、备注带入
• 保存时仍然调用新增接口

这个需求体现了 Codex 对表单状态管理的处理能力。它不仅要打开弹窗，还要处理异步加载车型配置的问题。因为车型配置列表依赖渠道和城市门店，不能简单把vehicleCfgId塞进表单就结束。需要先设置渠道和门店，再加载车型配置，最后回填车型配置 ID。

Codex 在这里加入了临时抑制 watch 的逻辑，避免自动加载过程把已回填字段清掉。这类细节如果人工实现，也需要认真考虑。

11. 使用 Codex 时如何写需求

通过这个项目可以明显感受到，Codex 的输出质量和需求描述的清晰度高度相关。

不太好的指令是：

优化一下页面。

这种说法太宽泛，Codex 也能做，但很可能和实际预期有偏差。

更好的指令是：

实时查价任务表格去掉车型和车牌，在前面补充开始日期和结束日期。结束日期优先用接口返回的 endDate，没有则用 startDate + duration 计算。

或者：

周期询价详情中，当任务统计里的采集中或待采集数量任意一个不为 0 时，每 5 秒刷新任务统计和任务列表；当两个值都为 0 时停止轮询。

这种需求具备几个特点：

• 改哪个模块
• 改什么字段
• 保留什么行为
• 触发条件是什么
• 停止条件是什么

Codex 对这种明确需求执行得非常好。

12. Codex 的边界和注意事项

Codex 很适合工程实现，但它不是业务负责人。使用时需要注意几个边界。

第一，业务规则必须由人明确。
例如状态为2才能点击操作，状态为0可以停用，状态为-1可以启用，这些规则不能依赖 Codex 猜。

第二，接口字段必须以最新文档为准。
如果后端更新了接口，最好明确告诉 Codex 使用最新接口文档。否则它可能沿用之前的字段。

第三，生成结果必须经过 Review。
类型检查只能证明代码可以构建，不代表业务一定正确。比如结束日期如何计算、轮询时长是否合理、复制任务是否复制备注，都需要业务确认。

第四，项目历史质量会影响效率。
这个项目中部分中文在终端输出时出现乱码，导致 Codex 做文本补丁时偶尔匹配失败。虽然最后可以通过更小范围的结构性修改解决，但如果项目编码统一、文案干净，效率会更高。

第五，不要让 Codex 无限扩大范围。
如果需求是改一个字段，就让它改一个字段。除非明确要求重构，否则不要让它顺手改太多。工程协作中，控制修改范围很重要。

13. 更推荐的协作模式

结合这次实践，我认为比较理想的 Codex 协作模式是：

1. 人提出明确目标
   比如“把实时查价 TOP10 从弹窗改成跳转详情页”。

2. Codex 阅读代码和定位文件
   它会查路由、组件、API 封装。

3. Codex 修改代码
   包括脚本逻辑、模板、类型、路由等。

4. Codex 运行校验
   通过npm.cmd run check检查类型和构建。

5. 人验收业务效果
   判断是否符合真实使用习惯。

6. 根据反馈继续迭代
   比如字段顺序、按钮样式、轮询规则继续调整。

这种协作方式下，人和 Codex 的分工比较清楚：

• 人负责业务判断、接口确认、交互取舍
• Codex 负责代码定位、实现、类型补齐、构建校验

14. 总结

这次 Vue3 后台项目实践说明，Codex 最适合的不是一次性代码生成，而是持续工程协作。

它擅长：

• 理解项目结构
• 按现有风格扩展代码
• 根据接口文档生成 API 和类型
• 修改 Vue3 单文件组件
• 调整后台表格字段
• 实现弹窗、筛选、分页和按钮状态
• 处理路由跳转和跨页面预填
• 实现状态轮询
• 复用已有详情页
• 运行类型检查和构建

而人的重点应该放在：

• 明确业务规则
• 确认接口语义
• 控制需求范围
• Review 结果
• 做最终验收

如果只是把 Codex 当成“帮我写一段代码”的工具，它的价值会被低估。更好的方式是把它当成一个可以持续协作的工程助手。特别是在后台管理系统这类页面多、字段多、接口多、需求变化快的项目中，Codex 可以明显降低重复劳动，提高开发节奏。

简单来说，Codex 适合承担“实现和验证”，人负责“判断和决策”。这两者结合起来，才是目前 AI 编程工具在真实工程里最有效的使用方式。