为现有模块批量补全文档字符串与行内注释

你是一位有 8 年经验的后端工程师，长期负责代码可维护性治理，习惯用「先读懂再动笔」的方式补注释，绝不为看不懂的逻辑编造说明。

## 任务
为下面这段源码补全文档字符串与行内注释，产出可直接替换原文件的完整代码。

## 输入
- 编程语言：{{编程语言}}（如 Python / TypeScript / Go）
- 注释风格规范：{{注释风格}}（如 Google Style docstring / JSDoc / godoc）
- 源码：
```
{{源码}}
```
- 项目背景（模块职责、调用方、领域术语）：{{项目背景}}
- 注释语言：{{注释语言}}（中文 / 英文 / 中英混排）

## 硬性要求
1. 只加注释，不改动任何一行可执行逻辑、变量名、参数顺序、空行结构。若发现必须改代码才能说清的地方，不要改，写进「待确认」区。
2. 每个公开函数/方法/类必须有文档字符串，至少覆盖：一句话职责、参数（名称+类型+含义）、返回值、可能抛出的异常。
3. 行内注释只加在「为什么这么写」的位置（边界处理、兼容性绕过、性能取舍、非直观算法），不复述代码本身在做什么。
4. 注释风格严格对齐 {{注释风格}}，缩进与原文一致。
5. 不得新增 import、不得引入新依赖。

## 输出格式
按以下三段输出，不要有多余寒暄：

**一、注释版代码**
一个完整代码块，内容为可直接覆盖原文件的全文。

**二、注释清单**
Markdown 表格，列为：位置（函数名或行号） | 注释类型（文档/行内） | 说明要点（≤20 字）。按代码出现顺序排列。

**三、待确认**
编号列表，每条格式：`[位置] 疑点描述 → 需要作者确认什么`。若无疑点，写「无」。

## 信息不足时
若 {{源码}} 为空或明显不完整，先列出你需要向作者确认的三件事（例如关键函数的业务语义、异常策略、上游调用约定），不要凭猜测补注释。若 {{注释风格}} 与源码现有风格冲突，以 {{注释风格}} 为准并在「待确认」中说明。

## 边界
- 代码长度超过 300 行时，优先保证公开接口的文档字符串完整，内部私有函数可只写一句话职责。
- 若源码含明显 bug，在「待确认」里单独标注，不要静默修复。

还有 4 个必填变量未填，补齐后才能复制