AI 应用后端工程化：从原型到可交付系统 · 第 20 篇 · 第五章 · 产品化接口
从读取草稿配置到复制、删除、分页和内置模板，解释产品能力如何沉淀为可管理的数据。
当应用只是数据库中的一行名字，创建、修改和删除非常直接。随着它包含模型、Prompt、工具、知识库和工作流，管理操作就会触及版本、复制语义、默认配置与模板来源。配置驱动的目标不是把所有逻辑塞进 JSON，而是让稳定能力可以被组合和复用。
管理对象与运行配置分层
flowchart TD
App[应用基本信息] --> Draft[草稿配置]
Draft --> Model[模型选择]
Draft --> Tools[工具引用]
Draft --> Dataset[知识引用]
Draft --> Workflow[工作流]
Template[内置模板] --> Clone[实例化]
Clone --> App
Draft --> Runtime[运行时配置转换]
应用实体保存名称、图标、所有者和状态，草稿配置保存可编辑能力，运行时转换器把配置引用解析为实际模型和工具。Handler 不应自己拼运行对象，否则调试聊天、公开 API 和后台任务会产生三套不同规则。
复制到底复制什么
复制应用通常复制基本信息和草稿快照，但不复制所有者、API Key、用户会话和发布历史。知识库与工具可以选择引用原资源，也可以深复制；产品必须明确，否则用户删除原资源后副本可能失效。
{
"copy": {
"metadata": "duplicate",
"draft_config": "snapshot",
"datasets": "reference",
"credentials": "exclude",
"conversations": "exclude",
"release_history": "exclude"
}
}
复制过程使用事务并生成新 ID。若需复制外部资源，改为异步任务和 copying 状态。重复请求携带幂等键，避免网络超时后产生多个副本。
分页与排序也是产品语义
应用列表应按更新时间稳定排序，并用 ID 解决同一时间并列。搜索名称时限制长度与特殊字符，过滤条件始终包含当前所有者。列表返回摘要，不加载完整草稿、历史和会话关系，避免 N+1 查询。
时间字段命名需要一致。update_at、updated_time 和 updated_at 混用会让排序与序列化出错。看似微小的字段修正，实际是在稳定外部契约。
内置模板是只读来源
旅行助手、产品经理等模板可以帮助用户快速开始，但不应直接作为共享可编辑应用。用户选择模板时创建自己的实例，记录模板 ID 与版本；之后用户修改不影响模板，模板升级也不强制覆盖用户内容。
模板配置需要与普通草稿走同一校验和运行转换，否则“内置模板能运行、用户配置不能运行”或相反。模板文件可以放代码仓库接受评审，也可以进入数据库由内容团队维护，选择取决于发布频率。
配置转换是反腐层
持久配置为了可编辑，会保存 ID、选项和展示信息；模型 SDK 需要客户端对象与工具实例。AppConfigService 一类转换层负责加载引用、验证所有权、应用默认值并生成不可变运行快照。
转换失败应指出具体路径，例如 tools[2] 已停用，而不是返回“配置错误”。发布前和运行时都可以调用同一验证逻辑，避免两套规则漂移。
删除需要引用检查
应用可能拥有公开 API Key、发布版本和会话。删除前先撤销新调用，再异步清理或按保留策略归档。直接级联物理删除会破坏审计与用量记录。
软删除数据仍要处理唯一名称约束和列表过滤。恢复功能若存在，要验证关联工具和知识库仍可用，不能简单把 deleted_at 置空。
观察字段变化背后的契约意识
提交中连续出现配置字段与更新时间字段重命名，说明实体、Schema 和 API 正在对齐。早期系统允许调整，但每次改名都应同步迁移、序列化、文档和测试。进入公开版本后，则需要兼容期或版本化 API。
迁移到 SaaS 模板系统
报表模板、营销自动化和 CI 流水线都用配置驱动实例。练习：定义一次应用复制矩阵，逐项决定深复制、引用或排除；再从内置模板创建实例，修改实例后验证模板内容不变。最后统计列表查询次数，确认没有随应用数量线性增长。
七次提交让管理能力成形
bfc4fec：引入配置服务，把草稿转换为工具等运行能力。b74a3d9：统一草稿配置字段语义。0a0e57d：增加更新、复制与删除。53dda1e：加入分页列表。c3e7084：补充时间戳与唯一标识，并修正推理字段语义。6a7f571：统一更新时间字段为updated_at。e5eb938：建立内置应用管理器和模板实体。
这些变化从运行配置扩展到完整生命周期，展示了配置产品常见的成长路径：能运行之后，紧接着就是能复制、能查找、能解释和能复用。