接口设计

请审查或完善 Python模块 的类型契约。输入：模块代码、公开接口清单、最低Python版本、依赖与检查配置、调用示例、兼容约束。

以真实调用契约为准完善类型标注，并用项目现有工具验证。检查 Paddle 公开 API 时核对对应接口要求；普通 Python 工程按自身兼容范围选择类型语法，不直接套用框架专属约定。

1. 先区分公开接口、内部辅助函数和动态扩展入口，记录真实调用方依赖的参数与返回值。优先完善公开边界，不为了追求覆盖率给所有局部变量堆叠注解，更不能通过修改业务签名制造表面上的类型统一。
2. 将函数签名、类公开属性和说明文档逐项对照，检查可为空、默认值、集合元素和返回分支。对字典结构尽量描述明确字段，对返回结果写出调用方实际拿到的具体类型，避免用 Any 掩盖已知契约。
3. 检查参数是否需要接受更通用的集合协议，以及实现是否真的支持这些输入。保留必要的运行时校验，类型提示不能替代用户输入验证；如果使用枚举、字面量或重载，说明它们与真实运行行为的对应关系。
4. 核对最低解释器和静态工具支持的语法，区分注解上下文与运行时类型别名。仅为类型服务的导入可以评估放入 TYPE_CHECKING，但需要运行时反射或解析注解的代码必须另外验证，不能盲目移动导入。
5. 检查文档示例、外部调用和异常分支是否同时符合新类型，识别循环导入、可变容器与泛型参数缺失。只在有明确契约的地方收紧类型，并列出可能影响调用方的变化及迁移办法。
6. 使用项目现有静态检查和相关运行测试验证，在最低支持环境做导入与关键调用检查。对每个无法准确标注的动态入口说明原因和收敛方案，禁止大量忽略错误后宣称类型已经完整可靠。

输出：公开接口契约表、类型与文档差异、必要代码修改、兼容性说明及检查结果。缺少调用方或版本信息时记录假设和待确认项；没有执行条件就提供验证命令与预期检查目标，不虚报静态检查已通过。

官方来源（2026-09-08 核验）：
- [百度飞桨《Python 类型提示标注规范》](https://www.paddlepaddle.org.cn/documentation/docs/zh/dev_guides/style_guide_and_references/type_annotations_specification_cn.html)

请评审 Java 接口契约与 DTO 字段。根据提供的项目资料给出具体结论、处理方案和验证方法。

适用范围：常规Java后端的HTTP或RPC接口；先核对JDK与框架版本，不将传统JavaBean约定直接套用于record或特殊序列化模型。

输入资料：业务需求、接口定义或代码、DTO与VO、调用方约束、JDK与框架版本、接口样例。

资料不足时，先列出最多3个影响结论的关键问题；可以继续的部分标明假设，无法确定的内容写“待核实”。不得编造文件、行号、调用链、性能数据或已完成的验证。

让接口说明覆盖输入、返回及异常，使用能准确表达含义的名称。

检查步骤：
1. 从业务需求列出操作对象、发起角色、前置条件、成功状态和失败状态，逐项对应到接口；不能用接口返回成功替代业务实际完成，异步任务要明确状态查询入口。
2. 建立请求与响应字段字典，逐个核对名称、类型、长度、单位、必填条件、空值含义、枚举和脱敏要求；遇到金额、时区、状态码等缺少定义时指出具体缺口。
3. 追踪DTO到业务方法再到响应对象的转换，检查重命名、漏传、默认值和字段覆盖；对布尔属性核对实际序列化结果，并用现有客户端样例验证兼容性。
4. 检查路径、查询参数与请求体是否承担清晰职责，列出重复提交、分页、排序、越权对象访问等边界；只在项目确有多租户时核对租户字段的可信来源。
5. 补齐接口注释需要表达的业务规则，给出一组有效请求和至少三组边界请求，响应需包含可处理的业务信息；不要向用户暴露堆栈或内部连接信息。
6. 将需求、接口、字段和验收用例逐条关联，区分新增接口与兼容改动；评估旧客户端在字段缺失、增加或枚举扩展时的行为，并给出分阶段联调顺序。

输出要求：依次给出接口清单、字段字典、问题表、最小修改示例和联调用例。问题表使用“位置｜触发条件｜实际影响｜修正建议｜验证方式”，用例写明请求、期望业务状态及期望响应。 只报告有证据支持的问题；区分“已验证”“推测”和“待验证”，涉及变更时给出受影响文件或对象、最小修改和复核方法。代码与操作示例使用占位符，不写入真实密码。

来源（核验日期：2026-09-08）：
[阿里巴巴《P3C-PMD 官方公开规则》](https://github.com/alibaba/p3c/blob/master/p3c-pmd/README.md)

整理范围：仅依据上述公开文档的相关建议，业务场景、变量、检查流程与验收格式均为独立改写，不代表相关企业完整内部规范。