# 工程项目管理用户指南

## 适用对象

- 项目管理员、业务负责人：维护工程主数据及参建关系。
- 委托岗：需要选择正确项目与见证人信息时查阅项目资料。

## 前置条件

- 权限：`project:list`（列表与详情）；创建/编辑若后端有单独权限需管理员配置（当前路由列表与详情共用 `project:list`）。
- 建议在录入委托前完成项目立项，保证 `code` 唯一、信息完整。

## 页面入口

| 功能 | 路由 | 侧栏 |
|------|------|------|
| 项目列表 | `/project` | 业务管理 → 工程项目 |
| 项目详情 | `/project/:id` | 从列表点击某行进入 |

## 字段说明

对应后端 `Project` 及关联 `Organization`、`SubProject`、`Contract`、`Witness` 等（以界面展示为准）。

### 项目（Project）

| 字段 | 含义 |
|------|------|
| `name` | 工程名称 |
| `code` | 项目编号，**全库唯一** |
| `address` | 工程地点 |
| `project_type` | 工程类型：房建/市政/交通/水利/机场/其他 |
| `status` | 项目状态：进行中/已竣工/已暂停 |
| `start_date` / `end_date` | 开工日期、计划竣工日期 |
| `description` | 备注 |

### 参建单位（Organization）

| 字段 | 含义 |
|------|------|
| `name` | 单位名称 |
| `role` | 建设/施工/监理/设计/检测等单位角色 |
| `contact_person` / `contact_phone` | 联系人、电话 |

### 分部分项（SubProject）

| 字段 | 含义 |
|------|------|
| `name` | 分部分项工程名称 |
| `code` | 编号（可选） |
| `parent` | 上级工程（树形） |

### 合同（Contract）

| 字段 | 含义 |
|------|------|
| `contract_no` | 合同编号（唯一） |
| `title` | 合同名称 |
| `amount` | 合同金额 |
| `sign_date` / `start_date` / `end_date` | 签订与履约周期 |
| `scope` | 检测范围 |
| `attachment` | 合同附件 |

### 见证人（Witness）

| 字段 | 含义 |
|------|------|
| `name` | 见证人姓名 |
| `id_type` / `id_number` | 证件类型与号码 |
| `organization` | 所属单位（关联参建单位） |
| `certificate_no` | 见证员证书号 |
| `is_active` | 是否在岗 |

## 标准操作步骤（SOP）

### 新建项目（若界面提供入口；否则通过 API/管理后台）

1. 进入 **`/project`**。
2. 使用页面「新建」或等价入口（以实际 UI 为准），填写 **项目编号**、**工程名称**、**工程类型**、地点与日期。
3. 保存后在列表中确认 **`code` 唯一**、状态正确。

### 维护参建单位与见证人

1. 打开 **`/project/:id`**。
2. 在详情页维护参建单位、见证人列表，供后续 **委托单** 选择 `witness` 等引用。

### 分部分项与合同

1. 在详情中维护分部分项树，便于委托单选择 `sub_project`。
2. 录入合同编号、金额与检测范围，支撑合同评审业务。

## 常见错误

| 现象 | 原因 | 处理 |
|------|------|------|
| 项目编号保存失败 | `code` 与已有项目重复 | 更换编号 |
| 委托中看不到见证人 | 见证人未挂本项目或 `is_active=false` | 在项目详情中补录或启用 |
| 详情页数据不全 | 权限仅列表或网络错误 | 确认权限与接口返回 |

## 数据核对清单

- [ ] `code` 与合同、对外文件中的项目编号一致。
- [ ] 委托单 `project_id` 指向正确项目。
- [ ] 见证人、分部分项与现场实际情况一致，避免委托单信息错误。

## 与上下游模块关系

- **上游**：无（项目为业务主数据起点之一）。
- **下游**：
  - **委托管理** `Commission.project` 必选本项目。
  - **样品** 通过委托间接关联项目。
  - **检测任务、报告** 通过委托链关联同一项目。
- **统计**：首页与统计服务可按 `project_id` 聚合委托量与任务量。

相关路由：**`/project`**、**`/project/:id`**；下游衔接 **`/entrustment`**、**`/sample`**。