后端 Java 接口 → 前端 TypeScript 接口生成

工作流程

1. 解析输入：识别接口名称、地址、请求方式、请求参数（区分 Header/Body/Query/Path）、响应结构
2. 过滤参数：排除 Header 注入参数（LoginUser、userId、token 等网关/拦截器注入字段）
3. 类型转换：按类型映射表将 Java 类型转为 TypeScript 类型
4. 递归展开：嵌套 BO/VO/DTO 对象递归生成独立 interface
5. 组装输出：按固定格式输出接口概览 + TypeScript 代码块
6. 标注疑问：信息不完整或有歧义时，在末尾以 > ⚠️ 注意： 列出

类型映射

泛型包装处理

分页响应模板：

interface XxxPageResultBO {
  /** 总记录数 */
  total: number;
  /** 数据列表 */
  result: XxxItemBO[];
}

参数处理

响应处理：

• 外层统一使用 ApiResponse（项目已有），不逐个生成
• result 实际类型单独定义为 interface

命名规范

注释规范

• 每个字段使用 JSDoc /* ... /，内容来源于后端文档参数说明
• 可选字段用 ? 标记，必填字段不加
• 枚举值完整列出：/* 奖励类型: BASIC_RETURN / DOUBLE_RETURN /
• 日期格式标注：/* 过期时间，格式: yyyy-MM-dd HH:mm:ss /

输出格式

输出为一个 .md 文件，包含所有接口的完整定义。多个接口之间用 --- 分隔。

文件命名规则： {飞书文档标题}-接口类型.md，文档标题从飞书文档中提取。

单个接口结构模板

**接口名称**

- **接口地址：** `/xxx/xxx`
- **请求方式：** `POST`
- **接口描述：** 一句话概括接口功能
- **请求参数：**

（TypeScript 代码块：请求相关类型）

- **响应结果：**

（TypeScript 代码块：响应相关类型）

规则说明

1. 标题使用 接口名称 加粗文本，不使用 # 标题
2. 接口地址、请求方式、接口描述为列表项
3. 请求参数 和 响应结果 各自独立一个 TypeScript 代码块
4. 请求参数代码块包含：嵌套子对象（请求侧） + 请求类型
5. 响应结果代码块包含：嵌套子对象（响应侧） + 响应结果类型
6. 无请求参数时，省略「请求参数」及其代码块
7. 每个 interface 之间空一行
8. 所有接口输出到同一个 .md 文件中，文件名由用户指定或根据模块名自动生成

禁止包含：装饰性分隔注释、ApiResponse 定义。

项目中已有的通用类型：

interface ApiResponse<T> {
  code: number;
  message: string;
  result: T;
}

质量要求

1. 不遗漏后端文档中的任何字段
2. 字段名与后端完全一致，不擅自重命名
3. 枚举值必须在注释中完整列出
4. 日期/金额等格式化字段必须在注释中标注格式
5. 接口描述总结为一句话，简明扼要
6. 输出不得包含表格，所有信息使用列表或代码块
7. 信息不完整或有歧义时，在末尾以 > ⚠️ 注意： 列出疑问点

边界情况处理

完整示例

详见 examples.md