在本文中，我们将完整记录一次和 AI 深度协作构建后管系统的全过程。从一个小小的“协议签署记录”需求出发，逐步扩展到协议版本管理、激活用户状态控制、提示词与敏感词联动控制、CRUD 接口设计、模型解耦、逻辑封装、注释规范乃至干净的 API 响应格式，最终形成了一个真正具备“落地能力”的系统模块。

01｜起点：不是代码，是需求的本质

我提出的第一个需求是：

协议文档需要保存富文本，还要能记录多个版本，因为用户签署的是“某一版本”。

这个需求听起来是数据库结构，但实质上是版本控制问题。我的出发点是：

• 每个协议文档有唯一标识（code）

• 每次新增/更新协议时生成一个版本记录（version_code、snapshot_link、hash）

• 签署记录关联的是具体的版本 ID，而不是文档 ID

• 每个文档只能有一个当前激活版本（is_active = true）

AI 很快响应并设计出三张表结构：

• ai_agreement_documents

• ai_agreement_versions

• ai_disclaimer_records

每张表结构清晰，字段命名也标准，基本没有修改就直接定稿。

02｜数据结构之上：模型方法的责任边界

我特别强调了两个原则：

• 控制器只做调度，业务逻辑全部下沉模型层

• 创建协议文档时要自动生成一个版本，更新协议时也要创建新版本

于是我们设计了：

AiAgreementDocuments::createWithVersion()
AiAgreementDocuments::updateWithNewVersion()
AiAgreementDocuments::deleteWithVersions()

这三个方法完全隐藏了复杂的业务逻辑，调用者只需传入数据，即可完成整套流程。

此外，我要求删除文档时不真正删除版本，而是保留历史。AI 根据这一要求，将 deleteWithVersions() 改写为只标记文档为逻辑删除，并取消所有版本的激活状态。

03｜注释规范和响应封装：让接口更像产品

我给出了标准接口注释模板，并强调所有非分页接口必须使用统一封装格式：

return $this->errorParam->paramValidity('失败信息', 0);
return $this->errorParam->paramValidity('', 1);

分页接口统一返回：

[
  'items' => [...],
  '_meta' => [...]
]

这让整个后管接口调用体验非常一致，不会有“有的返回结构复杂、有的返回值随意”的割裂感。

我还指出，客户端接口和后管接口的注释风格要区别，后管只关注 manager（企业ID）、Authorization 和分页参数。

04｜联想词 & 敏感词管理模块：信息控制的核心

当系统基础构建完成后，我又提出：

我希望联想词（提示词）能支持双向扩展，避免用户输入关键词不一致导致命中失败。 同时敏感词要能配置是否拦截，是否替换。

于是又设计了两个表：

• ai_suggested_keywords：存储 keyword1 和 keyword2 的互联关系

• ai_sensitive_words：维护违禁词，支持是否拦截/是否替换配置

然后我进一步要求：

• 所有接口必须支持：分页、增、删、改

• 所有逻辑必须在模型中实现

• 控制器只调用模型方法，并统一包装响应

• verbs() 必须完整列出每个接口的方法

AI 响应极快，并按我给的接口风格写出了整套接口，模型方法设计也非常工整：

AiSuggestedKeywords::getPagedList()
AiSuggestedKeywords::createOrUpdate()
AiSuggestedKeywords::deleteById()
AiSensitiveWords::... // 同结构

模型方法不仅封装了业务逻辑，还自动处理新建/更新操作人的 ID，避免遗漏。

05｜隐藏的重点：思想和结构的整合

整个协作过程，重点不是生成了多少代码，而是我持续强调的三个核心原则：

1. 业务逻辑必须集中在模型层，保持控制器简洁

2. 接口风格必须统一，注释、返回值、状态标识全部规范化

3. 系统结构必须支持演进：富文本、版本、激活状态、双向词汇、拦截配置，这些都是演进能力

通过这一次协作，我获得了的不仅是系统，更是：

• 一套落地执行力极强的协作规范

• 一组业务模块可复用的建模经验

• 一种让 AI 成为“开发搭子”的高效工作方式

结语：什么是干货？就是能直接落地的思想

这不是一篇“AI 真厉害”的文章，而是一次“把需求交给 AI 协作落地”的真实过程。

代码只是表象，思路才是底层结构。我们不是做功能，而是在构建一套可拓展、可复制、可协作的系统思维框架。

by 楠哥 红尘炼心，知行一体。