W20D01：接口文档要写输入、输出、错误和审计字段

第二十周进入端到端作品集项目。今天的主题是API 列表。从这一周开始，练习不再只是单个能力点，而是把制度问答、合同审查、权限控制、审计日志、评估报告和部署说明串成一个可讲、可演示、可追问的项目。

今天要完成的产物是 portfolio/api_design.md。这份材料不是给自己留备忘录，而是给未来的面试官、业务评审者和协作同事看的项目入口。它要让别人迅速判断：你解决了什么问题，系统边界在哪里，哪些能力已经做成闭环，哪些限制仍然诚实保留。

1. 1. 为什么作品集必须先讲清业务问题

接口文档让作品集从概念进入工程契约。一个端到端项目如果没有接口设计，前端、后端、测试、审计和演示脚本就很难对齐。

很多 AI 项目在作品集里失败，不是因为技术点太少，而是因为读者看不出它为什么存在。API 列表的作用，就是把一个抽象的“大模型应用”放进具体组织场景：谁在什么时刻遇到什么问题，系统如何减少搜索、核对、整理、追责和复盘成本。

国企制度和合同场景尤其适合训练这种表达。制度问答要求引用来源和权限边界，合同审查要求结构化抽取和风险提示，审计日志要求过程可追溯，评估报告要求结果可比较。把这些能力串起来，作品集就不只是功能截图，而是一套企业 AI 应用的交付逻辑。

读者在做自己的项目时，可以先问一个朴素问题：如果没有这个系统，业务人员今天会怎么完成同一件事。答案可能是到处找制度、反复问同事、手工比对合同条款、把风险记录在聊天里。只要这个人工流程讲清楚，AI 系统的价值才有落点。

2. 2. 先固定这份材料的关键字段

今天的关键字段可以先固定为：路径、方法、输入、输出、错误码、审计字段、权限要求。字段不是装饰，而是作品集的骨架。每个字段都要能支撑一次追问：为什么需要它，从哪里拿数据，系统怎么处理，最后怎样展示给业务或评审者。

写字段时要同时照顾业务语言和技术语言。业务语言回答使用者的收益，例如少翻制度、少漏字段、少走错审批；技术语言回答系统的机制，例如检索前权限过滤、引用片段、结构化输出、风险规则、日志事件和评估样例。两种语言缺一边，作品集都会显得偏。

一个稳妥写法，是先把字段分成四类。第一类描述对象，比如制度文档、合同、用户和角色；第二类描述动作，比如提问、抽取、审查、反馈和复核；第三类描述证据，比如引用、风险项、日志和评估结果；第四类描述边界，比如权限、拒答、人工确认和降级。这样后面的架构、接口和演示脚本都能沿用同一套词表。

3. 3. 常见误区要提前避开

这类作品集常见误区包括：只列接口名；没有错误码；不写审计字段；权限要求靠口头说明。这些误区会让项目看起来有页面、有接口、有模型调用，但读者无法判断它是不是一个企业场景能采用的系统。

最危险的误区，是把作品集写成技术清单。比如只说用了向量库、用了工作流、用了模型网关，却没有说明它们如何服务业务流程。技术栈当然重要，但它必须回到问题本身：权限为什么放在检索前，引用为什么要展示，合同风险为什么要转人工，日志为什么要记录请求和角色。

另一个误区，是只准备成功路径。真实项目一定会遇到无权限、依据不足、合同字段缺失、工具失败、模型输出不稳定、日志追溯不完整等情况。作品集如果只展示顺利回答，会让人怀疑系统没有边界意识。相反，把拒答、降级和复核讲清楚，反而更像真实工程。

4. 4. 可以按这个流程推进

推荐流程是：按业务流程排序、写请求字段、写响应字段、写错误码、写审计字段、连接测试样例。这套流程的重点，是先让项目结构稳定，再逐步填充细节。不要一开始就陷入页面颜色或模型参数，而要先确认业务对象、核心流程、数据关系、接口边界、测试样例和演示顺序。

接口可以覆盖文档上传、制度问答、合同抽取、合同风险审查、反馈提交和审计日志查询。每个接口至少写清输入、输出、错误码、权限要求和审计字段。这样即使暂时没有完整实现，读者也能判断系统边界是否完整。

推进过程中，可以把每一天的产物都当成下一天的输入。一句话定位会影响用户故事，用户故事会影响架构，架构会影响数据模型，数据模型会影响接口，接口会影响演示脚本和测试样例。这样做出的作品集会有连续性，不像十二份互相无关的文档。

如果短时间内无法完成真实后端，也可以先把文档写到可实现的粒度。比如接口里写清请求字段、返回字段、错误码和审计字段；测试样例里写清输入、身份、期望结果和验证点；部署说明里写清环境变量、启动顺序和降级方式。这些材料本身就能展示工程判断。

5. 5. 放到国企制度与合同项目里怎么判断

这个作品集的核心项目，可以设定为“国企制度与合同智能审查平台”。它不是泛泛的聊天机器人，而是围绕制度查询和合同审查两个高频流程展开：制度侧强调带引用回答、权限拒答和依据不足拒答；合同侧强调字段抽取、风险提示、人工复核和审计追溯。

判断这套项目是否成立，可以看它能不能回答五类问题。第一，业务问题是否具体，比如制度找不到、合同字段靠人工核对、风险意见分散在聊天里。第二，系统边界是否明确，比如不替代法务最终意见，不绕过组织权限，不在依据不足时强行回答。第三，数据关系是否完整，比如用户、文档、切片、合同、抽取结果、风险项、问答日志和反馈能否串起来。

第四，演示是否按业务流程展开，而不是按技术模块跳来跳去。一个好的演示应该让观众看到从上传制度、提问、引用、合同上传、字段抽取、风险提示、越权拒答到日志追溯的一条线。第五，评估是否能说明系统可改进，比如命中率、引用正确率、拒答准确性、抽取字段准确率和风险召回情况。

6. 6. 怎样写进作品集更有说服力

讲 API 设计时，可以说自己不是只写成功返回，而是把无权限、依据不足、格式错误、工具失败和模型超时都写进错误码，并把请求编号、用户、角色、资源、结果和耗时写入审计字段。

作品集里不要只放 portfolio/api_design.md 这个文件名，还要写清它在项目里承担什么角色。它是入口说明、需求依据、架构蓝图、数据骨架、接口契约、演示脚本、测试资产，还是部署手册。角色越清楚，读者越容易沿着材料理解你的工程能力。

更有说服力的表达方式，是把结论写成因果链：因为业务人员需要可信制度依据，所以问答必须带引用；因为不同角色可见范围不同，所以检索前要做权限过滤；因为合同风险会影响责任归属，所以模型只给提示并转人工复核；因为上线后要复盘问题，所以请求、身份、引用、风险和处理结果都要进入审计日志。

当你能用这种方式讲项目，别人会更容易相信你不是只会调模型接口，而是在设计一个能被企业流程接住的 AI 应用。第十九周和第二十周的目标，就是把这种能力沉淀成一套完整作品集。

7. 参考输出

7.1 API 列表参考输出

• 文档上传接口接收文件、文档类型、权限标签和版本信息。
• 问答接口接收问题、用户身份和会话信息，返回回答、引用、拒答原因和请求编号。
• 合同抽取和风险审查接口返回字段、置信度、风险等级、依据和复核状态。
• 反馈和审计日志接口记录用户、角色、资源、动作、结果、耗时和错误原因。