# 海洋项目管理系统 - 后端API文档

## 1. API基础信息

### 1.1 基础规范
- **Base URL**: `http://localhost:5000/api/v1`
- **Content-Type**: `application/json`
- **认证方式**: JWT Token
  - Header: `Authorization: Bearer <token>`
- **API文档地址**: `http://localhost:5000/docs` (Swagger UI)

### 1.2 统一响应格式

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

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

### 1.3 错误码列表

| 错误码 | 说明 | HTTP状态码 |
|--------|------|-----------|
| 1001 | 参数验证失败 | 400 |
| 1002 | 用户名或密码错误 | 401 |
| 1003 | Token无效或过期 | 401 |
| 2001 | 资源不存在 | 404 |
| 2002 | 资源已存在 | 409 |
| 3001 | 权限不足 | 403 |
| 5000 | 服务器内部错误 | 500 |

### 1.4 分页参数
所有列表接口都支持分页：
- `page`: 页码，默认1
- `page_size`: 每页数量，默认10，最大100

## 2. 认证相关API

### 2.1 用户登录

**接口**: `POST /auth/login`

**请求体**:
```json
{
  "username": "admin",
  "password": "password123"
}
```

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

**错误示例**:
```json
{
  "success": false,
  "message": "用户名或密码错误",
  "data": null,
  "error_code": "1002"
}
```

### 2.2 获取当前用户信息

**接口**: `GET /auth/me`

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "real_name": "系统管理员",
    "department": "管理部",
    "role": "admin",
    "email": "admin@example.com",
    "phone": "13800000000",
    "is_active": true
  },
  "error_code": null
}
```

### 2.3 登出

**接口**: `POST /auth/logout`

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "success": true,
  "message": "登出成功",
  "data": null,
  "error_code": null
}
```

## 3. 用户管理API

### 3.1 获取用户列表

**接口**: `GET /users`

**权限**: 仅管理员 (admin)

**请求头**:
```
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认10 |
| department | string | 否 | 部门筛选 |
| role | string | 否 | 角色筛选 |
| keyword | string | 否 | 关键词搜索（用户名、真实姓名、邮箱） |

**响应**:
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "admin",
        "real_name": "系统管理员",
        "department": "管理部",
        "role": "admin",
        "email": "admin@example.com",
        "phone": "13800000000",
        "is_active": true,
        "created_at": "2026-01-25T10:00:00",
        "updated_at": "2026-01-25T10:00:00"
      },
      {
        "id": 2,
        "username": "zhangsan",
        "real_name": "张三",
        "department": "市场部",
        "role": "market",
        "email": "zhangsan@example.com",
        "phone": "13900139000",
        "is_active": true,
        "created_at": "2026-01-25T11:00:00",
        "updated_at": "2026-01-25T11:00:00"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 10
  },
  "error_code": null
}
```

### 3.2 创建用户

**接口**: `POST /users`

**权限**: 仅管理员 (admin)

**请求头**:
```
Authorization: Bearer <token>
```

**请求体**:
```json
{
  "username": "lisi",
  "password": "password123",
  "real_name": "李四",
  "department": "技术部",
  "role": "other",
  "email": "lisi@example.com",
  "phone": "13700137000"
}
```

**字段说明**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名，唯一 |
| password | string | 是 | 密码，最少6位 |
| real_name | string | 是 | 真实姓名 |
| department | string | 是 | 部门 |
| role | string | 是 | 角色：admin/market/other |
| email | string | 否 | 邮箱，唯一 |
| phone | string | 否 | 电话 |

**响应**:
```json
{
  "success": true,
  "message": "用户创建成功",
  "data": {
    "id": 3,
    "username": "lisi",
    "real_name": "李四",
    "department": "技术部",
    "role": "other"
  },
  "error_code": null
}
```

### 3.3 获取用户详情

**接口**: `GET /users/{id}`

**权限**: 仅管理员 (admin)

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 用户ID |

**响应**:
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 2,
    "username": "zhangsan",
    "real_name": "张三",
    "department": "市场部",
    "role": "market",
    "email": "zhangsan@example.com",
    "phone": "13900139000",
    "is_active": true,
    "created_at": "2026-01-25T11:00:00",
    "updated_at": "2026-01-25T11:00:00"
  },
  "error_code": null
}
```

### 3.4 更新用户

**接口**: `PUT /users/{id}`

**权限**: 仅管理员 (admin)

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 用户ID |

**请求体**:
```json
{
  "real_name": "张三三",
  "email": "zhangsan_new@example.com",
  "phone": "13900139001",
  "is_active": false
}
```

**字段说明**: 所有字段都是可选的，至少提供一个字段

**响应**:
```json
{
  "success": true,
  "message": "用户更新成功",
  "data": {
    "id": 2,
    "username": "zhangsan",
    "real_name": "张三三",
    "department": "市场部",
    "role": "market",
    "email": "zhangsan_new@example.com",
    "phone": "13900139001",
    "is_active": false
  },
  "error_code": null
}
```

### 3.5 删除用户

**接口**: `DELETE /users/{id}`

**权限**: 仅管理员 (admin)

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 用户ID |

**响应**:
```json
{
  "success": true,
  "message": "用户删除成功",
  "data": null,
  "error_code": null
}
```

### 3.6 重置用户密码

**接口**: `POST /users/{id}/reset-password`

**权限**: 仅管理员 (admin)

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 用户ID |

**请求体**:
```json
{
  "new_password": "newpassword123"
}
```

**响应**:
```json
{
  "success": true,
  "message": "密码重置成功",
  "data": null,
  "error_code": null
}
```

## 4. 项目管理API

### 4.1 获取项目列表

**接口**: `GET /projects`

**权限**: 所有用户

**请求头**:
```
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认10，最大100 |
| project_no | string | 否 | 合同编号筛选 |
| engineering_type | string | 否 | 工程类别筛选 |
| project_department | string | 否 | 所属项目部筛选 |
| signing_date_start | string | 否 | 签订日期开始（YYYY-MM-DD） |
| signing_date_end | string | 否 | 签订日期结束（YYYY-MM-DD） |
| contract_amount_min | decimal | 否 | 合同金额最小值（万元） |
| contract_amount_max | decimal | 否 | 合同金额最大值（万元） |
| keyword | string | 否 | 关键词搜索（项目名称、业主单位） |
| sort_by | string | 否 | 排序字段：signing_date/contract_amount/created_at |
| sort_order | string | 否 | 排序方向：asc/desc，默认desc |

**注意**：所有筛选条件都是AND关系，必须同时满足。

**响应**:
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "project_no": "PRJ2026001",
        "power_contract_no": "GD2026001",
        "name": "某电力基建工程项目",
        "subitem_count": 5,
        "subitem_code": "SUB001",
        "total_investment": 1000.00,
        "contract_amount": 950.00,
        "warranty_ratio": 5.00,
        "settlement_amount": null,
        "total_cost_estimated": 800.00,
        "voltage_level": "110kV",
        "engineering_type": "基建",
        "owner_unit": "XX电力公司",
        "owner_contact": "张三 13800000001",
        "bidding_type": "公开招标",
        "signing_date": "2026-01-01",
        "start_date": "2026-01-15",
        "planned_end_date": "2026-12-31",
        "actual_end_date": null,
        "warranty_amount": 47.50,
        "warranty_expiry_date": "2028-12-31",
        "actual_warranty_refund_date": null,
        "project_department": "项目部一",
        "project_leader": "李四 13900000001",
        "payment_method": "按进度付款",
        "total_cost_control": 800.00,
        "is_adjusted": "否",
        "labor_cost_control": 300.00,
        "labor_cost_planned": 280.00,
        "labor_cost_paid": 200.00,
        "material_cost_control": 400.00,
        "material_cost_payable": 320.00,
        "material_cost_actual": 310.00,
        "material_cost_paid": 280.00,
        "other_cost_control": 100.00,
        "other_cost_payable": 80.00,
        "other_cost_actual": 75.00,
        "tax_amount": 95.00,
        "profit": 55.00,
        "actual_profit": null,
        "cost_settlement_amount": null,
        "cumulative_progress": 60.00,
        "receivable_amount": 570.00,
        "invoice_amount": 570.00,
        "actual_receipt_amount": 475.00,
        "receipt_completion_rate": 50.00,
        "payable_amount": 480.00,
        "actual_payment_amount": 390.00,
        "unpaid_amount": 95.00,
        "payment_completion_rate": 81.25,
        "labor_debt_amount": 80.00,
        "settlement_cost_amount": null,
        "settlement_labor_cost": null,
        "settlement_material_cost": null,
        "settlement_other_cost": null,
        "due_settlement_count": 0,
        "unsettlement_count": 0,
        "problems": null,
        "suggestions": null,
        "remarks": "备注信息",
        "created_by": 2,
        "created_by_name": "张三",
        "created_at": "2026-01-25T10:00:00",
        "updated_at": "2026-01-25T12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10
  },
  "error_code": null
}
```

### 4.2 获取项目详情

**接口**: `GET /projects/{id}`

**权限**: 所有用户

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 项目ID |

**响应**:
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "project_no": "PRJ2026001",
    "name": "某电力基建工程项目",
    "engineering_type": "基建",
    "contract_amount": 950.00,
    "created_by": 2,
    "created_by_name": "张三",
    "created_at": "2026-01-25T10:00:00",
    "updated_at": "2026-01-25T12:00:00"
    // ... 完整项目信息（60+字段）
  },
  "error_code": null
}
```

### 4.3 创建项目

**接口**: `POST /projects`

**权限**: admin, market

**请求头**:
```
Authorization: Bearer <token>
```

**请求体**:
```json
{
  "project_no": "PRJ2026002",
  "power_contract_no": "GD2026002",
  "name": "新电力工程项目",
  "engineering_type": "业扩",
  "owner_unit": "XX供电局",
  "contract_amount": 500.00,
  "signing_date": "2026-01-25",
  "start_date": "2026-02-01",
  "planned_end_date": "2026-12-31",
  "project_department": "项目部二",
  "project_leader": "王五 13800000002",
  "payment_method": "按进度付款",
  "total_cost_control": 400.00,
  "labor_cost_control": 150.00,
  "material_cost_control": 200.00,
  "other_cost_control": 50.00
}
```

**必填字段**:
- project_no: 合同编号（唯一）
- name: 项目名称
- engineering_type: 工程类别
- contract_amount: 合同金额

**响应**:
```json
{
  "success": true,
  "message": "项目创建成功",
  "data": {
    "id": 2,
    "project_no": "PRJ2026002",
    "name": "新电力工程项目",
    "engineering_type": "业扩"
  },
  "error_code": null
}
```

### 4.4 更新项目

**接口**: `PUT /projects/{id}`

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

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 项目ID |

**请求体**:
```json
{
  "name": "更新后的项目名称",
  "contract_amount": 600.00,
  "actual_receipt_amount": 300.00,
  "actual_payment_amount": 250.00,
  "cumulative_progress": 50.00,
  "remarks": "更新备注"
}
```

**字段说明**: 所有字段都是可选的，至少提供一个字段

**响应**:
```json
{
  "success": true,
  "message": "项目更新成功",
  "data": {
    "id": 1,
    "project_no": "PRJ2026001",
    "name": "更新后的项目名称"
  },
  "error_code": null
}
```

### 4.5 删除项目

**接口**: `DELETE /projects/{id}`

**权限**: admin, market
- admin: 可删除所有项目
- market: 只能删除自己创建的项目

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | int | 项目ID |

**响应**:
```json
{
  "success": true,
  "message": "项目删除成功",
  "data": null,
  "error_code": null
}
```

### 4.6 项目统计API

#### 4.6.1 基础统计

**接口**: `GET /projects/statistics`

**权限**: 所有用户

**请求头**:
```
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| engineering_type | string | 否 | 工程类别筛选 |
| signing_date_start | string | 否 | 签订日期开始 |
| signing_date_end | string | 否 | 签订日期结束 |
| contract_amount_min | decimal | 否 | 合同金额最小值 |
| contract_amount_max | decimal | 否 | 合同金额最大值 |

**说明**: 筛选参数与列表查询相同，支持AND组合筛选

**响应**:
```json
{
  "success": true,
  "message": "统计成功",
  "data": {
    "total_count": 100,
    "total_investment": 50000.00,
    "total_contract_amount": 48000.00,
    "total_settlement_amount": 45000.00,
    "total_receipt_amount": 42000.00,
    "total_payment_amount": 40000.00,
    "avg_receipt_completion_rate": 87.50,
    "avg_payment_completion_rate": 83.33,
    "avg_cumulative_progress": 75.00
  },
  "error_code": null
}
```

#### 4.6.2 分组统计

**接口**: `GET /projects/statistics/group`

**权限**: 所有用户

**请求头**:
```
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| group_by | string | 是 | 分组字段：engineering_type/project_department |
| signing_date_start | string | 否 | 签订日期开始 |
| signing_date_end | string | 否 | 签订日期结束 |

**响应**:
```json
{
  "success": true,
  "message": "统计成功",
  "data": [
    {
      "engineering_type": "基建",
      "count": 50,
      "total_contract_amount": 30000.00,
      "total_receipt_amount": 28000.00,
      "total_payment_amount": 26000.00
    },
    {
      "engineering_type": "业扩",
      "count": 30,
      "total_contract_amount": 12000.00,
      "total_receipt_amount": 10000.00,
      "total_payment_amount": 9500.00
    },
    {
      "engineering_type": "客户",
      "count": 20,
      "total_contract_amount": 6000.00,
      "total_receipt_amount": 4000.00,
      "total_payment_amount": 4500.00
    }
  ],
  "error_code": null
}
```

#### 4.6.3 时间维度统计

**接口**: `GET /projects/statistics/timeline`

**权限**: 所有用户

**请求头**:
```
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| time_field | string | 是 | 时间字段：signing_date/start_date/planned_end_date |
| group_by | string | 否 | 时间粒度：day/month/year，默认month |
| engineering_type | string | 否 | 工程类别筛选 |
| start_date | string | 否 | 开始日期 |
| end_date | string | 否 | 结束日期 |

**响应**:
```json
{
  "success": true,
  "message": "统计成功",
  "data": [
    {
      "month": "2026-01",
      "count": 20,
      "total_contract_amount": 8000.00
    },
    {
      "month": "2026-02",
      "count": 15,
      "total_contract_amount": 6000.00
    },
    {
      "month": "2026-03",
      "count": 25,
      "total_contract_amount": 10000.00
    }
  ],
  "error_code": null
}
```

## 5. 数据模型说明

### 5.1 用户角色 (role)
- `admin`: 管理员，拥有所有权限
- `market`: 市场部，可以创建项目、查看和编辑自己的项目
- `other`: 其他部门，可以查看所有项目，更新项目的财务、成本、进度等信息

### 5.2 工程类别 (engineering_type)
- `基建`: 基建工程
- `业扩`: 业扩工程
- `客户`: 客户工程
- `营销`: 营销工程
- `检修`: 检修、技改、应急抢修项目

### 5.3 项目字段说明
项目表包含60+个字段，分为以下几类：
- **基础信息**: project_no, name, engineering_type, signing_date等
- **成本信息**: total_cost_control, labor_cost_control, material_cost_control等
- **财务信息**: contract_amount, actual_receipt_amount, actual_payment_amount等
- **质保信息**: warranty_amount, warranty_expiry_date等
- **结算信息**: settlement_amount, cost_settlement_amount等

注意：项目不使用status字段，数据本身反映了项目的真实状态。

## 6. 常见问题

### 6.1 Token过期怎么办？
Token有效期24小时，过期后需要重新登录获取新Token。

### 6.2 如何处理筛选结果过多？
建议使用分页参数`page`和`page_size`，每页最多返回100条记录。

### 6.3 日期格式是什么？
所有日期字段使用`YYYY-MM-DD`格式，例如：`2026-01-25`

### 6.4 金额单位是什么？
所有金额字段单位为**万元**，保留两位小数。

### 6.5 如何获取完整的API文档？
访问`http://localhost:5000/docs`查看Swagger UI自动生成的API文档。

---

**文档维护**: 后端程序员
**更新时间**: 2026-01-25
**API文档地址**: `http://localhost:5000/docs`