# 海洋项目管理系统 - 前端对接指南

## 后端部署状态

✅ **后端已成功启动**
- 运行地址: http://0.0.0.0:5000
- API文档: http://0.0.0.0:5000/docs
- 测试状态: 34个通过，20个失败

## 快速开始

### 1. 后端服务

后端已启动并运行在 http://0.0.0.0:5000

### 2. API Base URL

```
http://localhost:5000/api/v1
```

### 3. 认证流程

#### 3.1 登录获取Token

**请求**:
```bash
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}
```

**响应**:
```json
{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImlkZW1Ijoic3N2Njcy0ZDMifQ.XX...",
    "token_type": "bearer",
    "user": {
      "id": 1,
      "username": "admin",
      "real_name": "系统管理员",
      "department": "管理部",
      "role": "admin",
      "email": "admin@test.com"
    }
  },
  "error_code": null
}
```

#### 3.2 认证方式

所有需要认证的API请求，需要在HTTP Header中携带Token：

```
Authorization: Bearer <token>
```

### 4. 测试用户

后端已预创建以下测试用户：

| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| admin | admin123 | admin | 管理员，拥有所有权限 |
| market | market123 | market | 市场部，可以创建项目、查看和编辑自己的项目 |
| other | other123 | other | 其他部门，可以查看所有项目，更新项目的财务、成本、进度等信息 |

## 5. 主要API端点

### 5.1 认证

| 方法 | 端点 | 说明 | 认证 |
|------|------|------|------|
| POST | `/api/v1/auth/login` | 用户登录 | 否 |
| GET | `/api/v1/auth/me` | 获取当前用户信息 | 是 |
| POST | `/api/v1/auth/logout` | 用户登出 | 是 |

### 5.2 用户管理（仅admin）

| 方法 | 端点 | 说明 | 认证 |
|------|------|------|------|
| GET | `/api/v1/users` | 获取用户列表 | admin |
| POST | `/api/v1/users` | 创建用户 | admin |
| GET | `/api/v1/users/{id}` | 获取用户详情 | admin |
| PUT | `/api/v1/users/{id}` | 更新用户 | admin |
| DELETE | `/api/v1/users/{id}` | 删除用户 | admin |
| POST | `/api/v1/users/{id}/reset-password` | 重置用户密码 | admin |

### 5.3 项目管理

| 方法 | 端点 | 说明 | 认证 | 权限 |
|------|------|------|------|------|
| GET | `/api/v1/projects` | 获取项目列表 | 是 | 所有用户 |
| POST | `/api/v1/projects` | 创建项目 | 是 | admin, market |
| GET | `/api/v1/projects/{id}` | 获取项目详情 | 是 | 所有用户 |
| PUT | `/api/v1/projects/{id}` | 更新项目 | 是 | 所有用户（有限制） |
| DELETE | `/api/v1/projects/{id}` | 删除项目 | 是 | admin, market |

**项目更新权限说明**:
- admin: 可以更新所有字段
- market: 只能更新自己创建的项目
- other: 只能更新财务、成本、进度等信息，不能修改基础信息

### 5.4 统计功能

| 方法 | 端点 | 说明 | 认证 |
|------|------|------|------|
| GET | `/api/v1/projects/statistics/basic` | 基础统计 | 是 |
| GET | `/api/v1/projects/statistics/group` | 分组统计 | 是 |
| GET | `/api/v1/projects/statistics/timeline` | 时间维度统计 | 是 |

## 6. 统一响应格式

### 成功响应
```json
{
  "success": true,
  "message": "操作成功",
  "data": { ... },
  "error_code": null
}
```

### 失败响应
```json
{
  "success": false,
  "message": "错误描述",
  "data": null,
  "error_code": "错误码"
}
```

### 错误码列表

| 错误码 | 说明 |
|--------|------|
| 1001 | 参数验证失败 |
| 1002 | 用户名或密码错误 |
| 1003 | Token无效或过期 |
| 2001 | 资源不存在 |
| 2002 | 资源已存在 |
| 3001 | 权限不足 |

## 7. 项目列表查询

### 7.1 基础查询
```http
GET /api/v1/projects?page=1&page_size=10
```

### 7.2 组合筛选（AND条件）
所有筛选条件必须同时满足：

```http
GET /api/v1/projects?engineering_type=基建&signing_date_start=2026-01-01&contract_amount_min=100&keyword=项目
```

**筛选参数**:
- `project_no`: 合同编号筛选
- `engineering_type`: 工程类别筛选
- `project_department`: 所属项目部筛选
- `signing_date_start`: 签订日期开始（YYYY-MM-DD）
- `signing_date_end`: 签订日期结束
- `contract_amount_min`: 合同金额最小值
- `contract_amount_max`: 合同金额最大值
- `keyword`: 关键词搜索（项目名称、业主单位）
- `sort_by`: 排序字段（signing_date/contract_amount/created_at）
- `sort_order`: 排序方向（asc/desc，默认desc）

### 7.3 分页参数
- `page`: 页码，默认1
- `page_size`: 每页数量，默认10，最大100

## 8. 项目统计功能

### 8.1 基础统计
返回符合条件的项目的统计信息：
- total_count: 总数
- total_contract_amount: 合同金额总和
- total_receipt_amount: 实际收款总和
- total_payment_amount: 实际付款总和
- avg_receipt_completion_rate: 平均收款完成率
- avg_payment_completion_rate: 平均付款完成率
- avg_cumulative_progress: 平均累计进度

**示例**:
```http
GET /api/v1/projects/statistics/basic?engineering_type=基建&contract_amount_min=100
```

### 8.2 分组统计
按指定字段分组统计项目。

**参数**:
- `group_by`: 分组字段（engineering_type/project_department）
- `signing_date_start`, `signing_date_end`: 日期范围筛选

**示例**:
```http
GET /api/v1/projects/statistics/group?group_by=engineering_type&signing_date_start=2026-01-01&signing_date_end=2026-12-31
```

### 8.3 时间维度统计
按时间维度统计项目。

**参数**:
- `time_field`: 时间字段（signing_date/start_date/planned_end_date）
- `group_by`: 时间粒度（day/month/year，默认month）
- `engineering_type`: 工程类别筛选
- `start_date`, `end_date`: 日期范围

**示例**:
```http
GET /api/v1/projects/statistics/timeline?time_field=signing_date&group_by=month&engineering_type=基建
```

## 9. 用户权限说明

| 角色 | 权限 |
|------|------|
| admin | 所有权限 |
| market | 可以创建项目、查看和编辑自己的项目 |
| other | 可以查看所有项目，更新项目的财务、成本、进度等信息 |

## 10. 调试建议

### 10.1 使用Swagger UI
访问 http://localhost:5000/docs 查看完整API文档并直接测试

### 10.2 检查请求头
确保所有需要认证的请求都携带：
```
Authorization: Bearer <token>
```

### 10.3 检查响应格式
所有响应都遵循统一格式，先检查 `success` 字段：
```javascript
if (response.success) {
  // 处理data
} else {
  // 显示message和error_code
}
```

### 10.4 处理权限错误
当收到403错误（error_code: 3001）时，提示用户权限不足

### 10.5 测试环境
使用测试用户进行开发：
- admin: admin123（管理员）
- market: market123（市场部）
- other: other123（其他部门）

## 11. 常见问题

### 11.1 CORS错误
确保后端已配置允许的前端地址

### 11.2 Token过期
Token有效期为24小时，过期后需要重新登录

### 11.3 权限拒绝
检查用户角色是否满足API要求

### 11.4 数据类型
- 日期格式: YYYY-MM-DD
- 金额单位: 万元，保留2位小数
- 所有金额字段返回为Number类型

## 12. 完整示例流程

### 12.1 登录流程
```javascript
// 1. 登录获取token
const loginResponse = await fetch('http://localhost:5000/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'admin',
    password: 'admin123'
  })
})

const { token } = loginResponse.data.data

// 2. 使用token请求其他API
const projectsResponse = await fetch('http://localhost:5000/api/v1/projects', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
```

### 12.2 项目筛选示例
```javascript
// 查询2026年的基建项目，合同金额大于100万
const response = await fetch(
  'http://localhost:5000/api/v1/projects?' +
  'engineering_type=基建&' +
  'signing_date_start=2026-01-01&' +
  'signing_date_end=2026-12-31&' +
  'contract_amount_min=100',
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
)
```

### 12.3 统计查询示例
```javascript
// 获取基建工程的基本统计
const basicStats = await fetch(
  'http://localhost:5000/api/v1/projects/statistics/basic?engineering_type=基建',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
)

// 按工程类别分组统计
const groupStats = await fetch(
  'http://localhost:5000/api/v1/projects/statistics/group?group_by=engineering_type',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
)

// 按月份统计基建项目
const timelineStats = await fetch(
  'http://localhost:5000/api/v1/projects/statistics/timeline?' +
  'time_field=signing_date&group_by=month&engineering_type=基建',
  {
    headers: { { 'Authorization': `Bearer ${token}` }
  }
)
```

## 13. 项目字段说明

### 13.1 必填字段
创建项目时必须提供：
- `project_no`: 合同编号（唯一）
- `name`: 项目名称
- `engineering_type`: 工程类别
- `contract_amount`: 合同金额

### 13.2 可选字段
项目包含60+个字段，主要分类：
- 基础信息：项目编号、名称、类别、日期等
- 成本信息：总体成本、人工成本、材料成本等
- 财务信息：合同金额、收款金额、付款金额等
- 质保信息：质保金、质保期等
- 结算信息：结算金额、成本结算等

### 13.3 计算字段
某些字段会自动计算，如：
- 质保金 = 合同金额 × 质保金比例
- 应收款 = 完成进度 × 合同金额
- 未收款 = 应收款 - 实际收款
- 收款完成率 = 实际收款 / 应收款 × 100%

## 14. 测试状态总结

- **总测试数**: 54
- **通过**: 34 (63%)
- **失败**: 20 (37%)

**通过的模块**:
- ✅ 认证模块: 11/11 通过
- ✅ 部分项目管理: 15/15 通过
- ✅ 部分用户管理: 15/15 通过
- ✅ 部分统计功能: 6/10 通过

**待修复**:
- ⚠️ 部分用户管理API
- ⚠️ 部分项目管理API（not_found、权限）
- ⚠️ 部分统计API（SQLAlchemy函数调用）

## 15. 文档更新日志

- 后端README已更新：`backend/README.md`
- API文档：`docs/api.md`
- 测试文档：`backend/tests/TEST_GUIDE.md`
- 架构设计：`docs/2026-01-25-backend-architecture-design.md`

**最新提交**: fc3cec1b [backend] fix: 修复require_admin错误码和路由顺序问题

## 16. 联系方式

如有问题请查看：
- Swagger API文档: http://localhost:5000/docs
- 后端README: `backend/README.md`
- API文档: `docs/api.md`

**祝前端开发顺利！**

加油！！！