From 5e782ac8ccaeade89595f141e9b222044277bb14 Mon Sep 17 00:00:00 2001
From: zhangjf <zhangjf@example.com>
Date: Mon, 23 Feb 2026 11:26:18 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E5=89=8D=E7=AB=AFAPI?=
 =?UTF-8?q?=E9=9B=86=E4=B8=AD=E7=AE=A1=E7=90=86=E8=AE=BE=E8=AE=A1=E8=A7=84?=
 =?UTF-8?q?=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. 架构设计文档 v1.7 -> v1.8
   新增 6.1.5 API集中管理规范：
   - 目录结构示例：api/index.ts + api/request.ts + api/modules/
   - api/index.ts 代码示例
   - Vue组件调用示例（正确vs错误对比）
   - 规范要求：禁止硬编码、统一入口、路径简化、便于维护

2. Agents.md v1.2 -> v1.3
   新增 5.6 前端API集中管理规范：
   - 目录结构说明
   - 规范要求表格
   - 正确/错误代码示例对比

规范要点：
- 采用独立目录或文件集中管理后台API请求
- Vue组件中禁止直接使用 request.get('/xxx/xxx') 硬编码URL
- 所有API函数从 @/api 统一导出，按模块分组
- API路径变更时只需修改 api/index.ts 一处
---
 Agents.md                                     | 48 ++++++++++++-
 doc/资金服务平台 FundPlatform 架构设计文档.md | 69 ++++++++++++++++++-
 2 files changed, 115 insertions(+), 2 deletions(-)

diff --git a/Agents.md b/Agents.md
index e292cfa..76e84c0 100644
--- a/Agents.md
+++ b/Agents.md
@@ -1,6 +1,6 @@
 # 资金服务平台 (FundPlatform) - 开发规范
 
-> **文档版本**: v1.2  
+> **文档版本**: v1.3  
 > **创建日期**: 2026-02-20  
 > **更新日期**: 2026-02-23  
 > **适用范围**: 本项目所有开发人员
@@ -264,6 +264,52 @@ GET    /cust/api/v1/customer/page       # 分页查询
 | 404 | 资源不存在 |
 | 500 | 服务器内部错误 |
 
+### 5.6 前端API集中管理规范
+
+前端项目必须采用**独立目录或文件集中管理**对后台API的请求，便于调整和优化。
+
+**目录结构**：
+
+```
+fund-admin/src/api/    或    fund-mobile/src/api/
+├── index.ts          # API集中定义入口，统一导出
+├── request.ts        # Axios实例配置、拦截器
+└── modules/          # 按业务模块拆分（可选）
+    ├── auth.ts       # 用户认证API
+    ├── customer.ts   # 客户管理API
+    └── expense.ts    # 支出管理API
+```
+
+**规范要求**：
+
+| 要求 | 说明 |
+|------|------|
+| 禁止硬编码 | Vue组件中禁止直接使用 `request.get('/xxx/xxx')` 形式 |
+| 统一入口 | 所有API函数从 `@/api` 统一导出，按模块分组 |
+| 路径简化 | API函数内部使用简化路径，由 baseURL 统一添加前缀 |
+| 便于维护 | 后端接口变更时，只需修改 api/index.ts 一处 |
+
+**正确示例**：
+
+```typescript
+// api/index.ts - 集中定义
+export function getReceivableList(params: { pageNum: number; pageSize: number }) {
+  return request.get('/receipt/receivable/page', { params })
+}
+
+// Vue组件 - 使用集中定义
+import { getReceivableList } from '@/api'
+const res = await getReceivableList({ pageNum: 1, pageSize: 10 })
+```
+
+**错误示例**：
+
+```typescript
+// Vue组件 - 硬编码URL（禁止）
+import request from '@/api/request'
+const res = await request.get('/receipt/api/v1/receipt/receivable/page')
+```
+
 ---
 
 ## 六、多租户规范
diff --git a/doc/资金服务平台 FundPlatform 架构设计文档.md b/doc/资金服务平台 FundPlatform 架构设计文档.md
index d400e89..e6f2c68 100644
--- a/doc/资金服务平台 FundPlatform 架构设计文档.md	
+++ b/doc/资金服务平台 FundPlatform 架构设计文档.md	
@@ -1,6 +1,6 @@
 # 资金服务平台 (FundPlatform) - 架构设计文档
 
-> **文档版本**: v1.7  
+> **文档版本**: v1.8  
 > **创建日期**: 2026-02-13  
 > **更新日期**: 2026-02-23  
 > **项目名称**: 资金服务平台  
@@ -3551,6 +3551,72 @@ const router = createRouter({
 /fund/receipt/receivable ->      /api/v1/receipt/receivable -> fund-receipt
 ```
 
+#### 6.1.5 API集中管理规范
+
+前端项目必须采用**独立目录或文件集中管理**对后台API的请求，便于调整和优化。
+
+**目录结构示例**：
+
+```
+fund-mobile/src/
+└── api/
+    ├── index.ts          # API集中定义入口，统一导出
+    ├── request.ts        # Axios实例配置、拦截器
+    └── modules/          # 按业务模块拆分（可选）
+        ├── auth.ts       # 用户认证API
+        ├── customer.ts   # 客户管理API
+        └── expense.ts    # 支出管理API
+```
+
+**api/index.ts 示例**：
+
+```typescript
+import request from './request'
+
+// ===================== 用户认证 =====================
+export function login(data: { username: string; password: string }) {
+  return request.post('/auth/login', data)
+}
+
+export function getUserInfo() {
+  return request.get('/auth/info')
+}
+
+// ===================== 支出管理 =====================
+export function createExpense(data: any) {
+  return request.post('/exp/expense', data)
+}
+
+export function getExpenseTypeTree() {
+  return request.get('/exp/expense-type/tree')
+}
+
+// ===================== 应收款管理 =====================
+export function getReceivableList(params: { pageNum: number; pageSize: number }) {
+  return request.get('/receipt/receivable/page', { params })
+}
+```
+
+**Vue组件调用示例**：
+
+```typescript
+// 正确：使用集中定义的API函数
+import { getReceivableList, createExpense } from '@/api'
+
+const res = await getReceivableList({ pageNum: 1, pageSize: 10 })
+
+// 错误：直接在组件中硬编码URL
+import request from '@/api/request'
+const res = await request.get('/receipt/api/v1/receipt/receivable/page')
+```
+
+**规范要求**：
+
+1. **禁止硬编码**：Vue组件中禁止直接使用 `request.get('/xxx/xxx')` 形式调用API
+2. **统一入口**：所有API函数从 `@/api` 统一导出，按模块分组
+3. **路径简化**：API函数内部使用简化路径（如 `/auth/login`），由 request.ts 的 baseURL 统一添加前缀
+4. **便于维护**：后端接口变更时，只需修改 api/index.ts 一处即可
+
 ### 6.3 生产环境部署
 
 ```
@@ -4070,6 +4136,7 @@ public class GlobalExceptionHandler {
 | v1.5 | 2026-02-13 | 补充模块通信与 OpenFeign 参数对象管理策略、分层架构职责说明、MyBatis-Plus 使用规范、Controller 与参数校验规范、事务与测试规范及开发规则总览 | zhangjf |
 | v1.6 | 2026-02-13 | 补充单机部署配置：配置文件分离架构（env.properties+service.properties）、打包目录结构、多租户部署配置、日志配置集中化、脚本加载逻辑 | zhangjf |
 | v1.7 | 2026-02-23 | 新增6.1前端部署路径设计：Nginx子路径部署、部署路径规划、Nginx配置示例、前端构建配置、API请求路径规范 | zhangjf |
+| v1.8 | 2026-02-23 | 新增6.1.5 API集中管理规范：独立目录管理、禁止硬编码、统一入口、路径简化、便于维护 | zhangjf |
 
 ---