HaniBlindBox/.kiro/specs/frontend-api-refactor/requirements.md

Requirements Document

Introduction

本需求文档描述前端 API 接口调用重构工作。目标是将分散在页面和组件中的接口调用统一收敛到 common/server/ 模块，实现接口集中管理，并在改造过程中记录所有 API 地址，用于核对 C# 后端迁移完整性。

Glossary

• Server_Module: honey_box/common/server/ 目录下的 API 接口封装模块
• RequestManager: 现有的网络请求工具类 (honey_box/common/request.js)
• Page: honey_box/pages/ 目录下的页面文件
• Component: honey_box/components/ 目录下的组件文件
• API_Registry: 接口清单文档，记录所有前端使用的 API 地址及迁移状态

Requirements

Requirement 1: 修改请求格式

User Story: As a 开发者, I want POST 请求使用 JSON 格式, so that 与 C# 后端兼容。

Acceptance Criteria

1. WHEN 发送 POST 请求 THEN RequestManager SHALL 使用 application/json 作为 Content-Type
2. WHEN 发送请求 THEN RequestManager SHALL 保持现有签名机制不变
3. WHEN 请求完成 THEN RequestManager SHALL 返回与 PHP 版本一致的响应格式

Requirement 2: 创建 Server 模块

User Story: As a 开发者, I want 按业务域划分 API 模块, so that 接口集中管理便于维护。

Acceptance Criteria

1. THE Server_Module SHALL 按业务域划分为独立文件（auth、user、goods、order、warehouse、coupon、welfare、collection、address、config、rank、invitation、redeem、pay）
2. WHEN 定义接口函数 THEN Server_Module SHALL 使用语义化的函数名（如 getUserInfo、getGoodsList）
3. WHEN 接口调用失败 THEN Server_Module SHALL 统一处理错误并返回标准格式
4. THE Server_Module SHALL 不使用 index.js 统一导出，各模块独立导入

Requirement 3: 重构页面接口调用

User Story: As a 开发者, I want 页面通过 Server 模块调用接口, so that 接口路径不再硬编码在页面中。

Acceptance Criteria

1. WHEN 页面需要调用接口 THEN Page SHALL 从对应 Server_Module 导入函数
2. WHEN 页面调用接口 THEN Page SHALL 使用 await 方式调用导入的函数
3. THE Page SHALL 不再直接使用 this.req()、RequestManager.post() 等方式硬编码 URL
4. WHEN 重构页面 THEN 开发者 SHALL 记录该页面使用的所有 API 地址到 API_Registry

Requirement 4: 重构组件接口调用

User Story: As a 开发者, I want 组件通过 Server 模块调用接口, so that 组件中的接口也能集中管理。

Acceptance Criteria

1. WHEN 组件需要调用接口 THEN Component SHALL 从对应 Server_Module 导入函数
2. WHEN 组件调用接口 THEN Component SHALL 使用 await 方式调用导入的函数
3. THE Component SHALL 不再直接使用 this.req()、RequestManager.post() 等方式硬编码 URL
4. WHEN 重构组件 THEN 开发者 SHALL 记录该组件使用的所有 API 地址到 API_Registry

Requirement 5: 生成接口清单

User Story: As a 开发者, I want 记录所有前端使用的 API 地址, so that 能核对 C# 后端是否遗漏接口。

Acceptance Criteria

1. THE API_Registry SHALL 记录每个接口的 URL 路径
2. THE API_Registry SHALL 记录每个接口所属的 Server_Module
3. THE API_Registry SHALL 记录每个接口的请求方式（GET/POST）
4. THE API_Registry SHALL 标注每个接口在 C# 后端的迁移状态（已迁移/未迁移/待确认）
5. THE API_Registry SHALL 记录每个接口被哪些页面/组件使用

Requirement 6: 保持功能兼容

User Story: As a 用户, I want 重构后功能正常, so that 不影响正常使用。

Acceptance Criteria

1. WHEN 重构完成 THEN 所有现有功能 SHALL 正常工作
2. WHEN 接口返回错误 THEN 系统 SHALL 正确显示错误提示
3. WHEN 用户未登录 THEN 系统 SHALL 正确跳转到登录页
4. WHEN 需要绑定手机号 THEN 系统 SHALL 正确跳转到绑定页面