“神秘电影五条代码”目前不能仅凭这几个字确定是正式电影名称、影片中的五条暗号，还是用户对五组线索的简称。开发时最稳妥的做法，不是直接编出五条代码或虚构影片资料，而是把原始短语作为待解析输入，先判断词义，再根据已有片库或用户补充内容返回结果。
如果没有可核验的电影数据库，接口至少应返回标准化词组、候选含义、识别状态和缺少的信息；如果接入了真实片库，则可以进一步返回电影信息、线索列表或剧情解释。下面给出一套可以自行实现和测试的接口契约示例。接口名称、字段和路径均为开发示例，不代表存在一个名为“神秘电影五条代码”的官方接口。
先要解决的问题：它究竟是电影名、暗号，还是五条线索？
这句话存在三个容易混淆的部分。“神秘电影”可能是作品名称，也可能只是对悬疑电影的描述；“五条”通常表示数量，但也可能属于片名的一部分；“代码”既可以指程序编码，也可以指影片里的密码、暗号或解谜线索。
因此，解析器不能把空格或汉字机械拆成五个代码，也不能因为出现“电影”二字就断言存在同名作品。应先保留完整原词，再生成有限的候选解释：
- movie_title：用户可能在查一部名为“神秘电影五条代码”的作品。
- code_phrase：用户可能在查一部神秘电影中的代码或暗号。
- clue_collection：用户可能需要整理五条剧情线索。
- unknown：现有上下文不足，暂时不能可靠判断。
候选解释不等于事实结论。只有当片库中存在完全匹配或足够明确的资料时，接口才应把某个候选标记为已确认；否则返回 ambiguous，并要求调用方补充电影年份、导演、演员、代码原文或剧情上下文。
确定了词义后，接口应该怎样定义，才不会把五条代码编出来？
可以设计一个只负责解析和检索的接口，例如 POST /v1/mystery-film/parse。这是内部服务的示例路径，重点在于输入和输出的边界清楚，而不是路径本身。
| 字段 | 类型 | 要求 | 作用 |
|---|---|---|---|
| query | 字符串 | 必填，长度限制在合理范围内 | 接收“神秘电影五条代码”等原始词组 |
| context | 字符串 | 可选 | 补充“查结局”“找五条暗号”等用户意图 |
| filmId | 字符串 | 可选 | 已有片库中的唯一作品编号 |
| codes | 数组 | 可选 | 用户已经提供的代码或线索列表 |
| locale | 字符串 | 可选 | 控制语言和本地化输出 |
最小请求可以只有一个 query 字段：
如果用户已经给出五项内容，则应把它们放进 codes，而不是让服务根据标题自行猜测：
返回结果要包含什么，才能区分已确认和待核验内容？
返回结构应把原始输入、标准化结果、识别状态和证据来源分开。不要只返回一段看似确定的剧情文字，否则前端无法判断哪些内容来自数据库，哪些内容只是模型或规则推测。
| 字段 | 说明 |
|---|---|
| status | matched、ambiguous、unmatched 或 invalid |
| normalizedQuery | 去除多余空格、统一标点后的原始词组 |
| interpretations | 候选含义及其依据 |
| film | 已匹配片库时返回作品信息，没有匹配时返回 null |
| items | 已确认的代码或线索列表，没有资料时返回空数组 |
| expectedCount | 从“五条”识别出的期望数量，可返回 5 |
| actualCount | 当前实际获得的条目数量 |
| evidence | 说明结果来自片库、用户输入还是规则解析 |
| nextAction | 提示调用方需要补充什么信息 |
对于只有原始词组、没有片库命中的请求，合理响应应类似下面的结构：
这里的 expectedCount 只表示词组中出现了“五条”这一数量信号，不代表系统已经找到了五条真实内容。只有当片库或用户输入提供了条目，actualCount 才能增加。
怎样把这条输入做成可测试的处理链？
- 规范化文本。对 query 进行去首尾空格、统一全角半角标点、合并连续空格处理，但不删除“神秘”“电影”“五条”“代码”等可能影响判断的词。
- 识别数量表达。将“五条”映射为 expectedCount=5，同时保留原词。若输入中明确给出数字“5”，也可以归一化为同一数量值。
- 判断候选类型。根据片库完全匹配、上下文关键词和用户提供的 codes 生成候选。没有证据时只能返回候选，不能升级为 confirmed。
- 查询可信数据源。若 filmId 存在，优先按唯一编号查询；若只有文本，则先做精确匹配，再做经过审核的别名匹配。模糊匹配应标记为候选。
- 校验条目数量。当接口声称已找到五条代码时，必须检查 items 的长度和每条内容的来源。长度不足时返回 incomplete 或 ambiguous，不用占位文字补齐。
- 生成下一步动作。缺少年份时提示年份，缺少代码原文时提示原文，不能用泛化的剧情描述代替缺失字段。
在规则实现上，可以把判断优先级写成明确的分支，而不是让一个模糊的文本生成函数直接产出结论：
如果暂时没有电影资料库，接口还能返回什么？
可以返回“解析结果”，但不能返回未经证实的电影事实。没有片库时，服务仍然能够完成文本规范化、数量识别、候选意图分类和参数校验。例如，输入“神秘电影五条代码，帮我找结局”可以识别出用户可能关注剧情内容，但这并不等于服务知道影片结局。
此时最有用的返回是缺口信息：是否需要片名、年份、导演、代码原文、截图转写或剧情片段。前端可以据此展示补充表单；后端也可以在资料补齐后重新调用同一接口，而不用改变响应结构。
如果接入片库，建议给每条线索保存 sourceId、sourceType、content、order 和 verified 字段。sourceType 可以区分官方资料、编辑录入、用户提交和自动抽取。自动抽取的内容即使结构完整，也不应默认标记为 verified。
怎样验收“神秘电影五条代码”的实现是否正确？
- 输入只有关键词时，返回 ambiguous 或 unmatched，不返回虚构电影名称。
- 输入带有明确 filmId 时，只查询对应作品，不因文本相似而切换到其他影片。
- 输入五个 codes 时，actualCount 返回 5，并保留原始顺序。
- 输入三个 codes 时，返回 actualCount=3，同时保留 expectedCount=5，不能自动补成五项。
- 输入空字符串、超长文本或错误类型时，返回 invalid，并说明字段问题。
- 片库没有匹配记录时，film 为 null，evidence 不得写成官方资料。
- 同一请求重复提交时，标准化结果和状态应保持一致，便于缓存与回归测试。
这样实现后，“神秘电影五条代码”不再被当成一个无法验证的固定答案，而会成为一条有明确输入、判断边界和返回状态的解析请求。开发重点是区分电影名称、剧情暗号和五条线索，并让每个结论都能追溯到用户输入或实际数据源。
saspun76guogtrgv0gfwnhaoqu6d
