147 lines
10 KiB
Markdown
147 lines
10 KiB
Markdown
# 交互文档（前端）
|
||
|
||
**依据**：《产品文档》
|
||
**读者**：前端工程师
|
||
**目标**：明确页面数量、每个页面的功能与用户交互，便于实现与联调。
|
||
|
||
---
|
||
|
||
## 1. 页面总览
|
||
|
||
| 序号 | 页面名称 | 说明 |
|
||
|------|--------------|------|
|
||
| 1 | 登录页 | 用户登录入口（若与现有系统统一，可复用现有登录页） |
|
||
| 2 | 项目列表页 | 项目列表的入口页，支持搜索、筛选、进入详情、新建项目 |
|
||
| 3 | 项目详情/编辑页 | 查看/编辑单个项目信息，含 5 个 Tab；新建项目时也为本页（空表单） |
|
||
| 4 | 操作日志 | 查看某项目的修改记录，可为抽屉或独立页 |
|
||
|
||
**合计：4 个页面（或 3 个主页面 + 操作日志以抽屉形式承载）。**
|
||
|
||
---
|
||
|
||
## 2. 角色与权限（影响各页显隐）
|
||
|
||
| 角色 | 新建项目 | 查看/编辑项目 |
|
||
|------|----------|----------------|
|
||
| 市场部 | ✓ | ✓ |
|
||
| 管理员、工程部、技经部、财务部、物贸部 | ✗ | ✓ |
|
||
|
||
- **新建项目**：仅市场部展示入口；其他角色不展示或入口不可用。
|
||
- **查看/编辑**：所有角色均可进入项目列表、项目详情，并可编辑、保存；每次保存由后端记录一条操作日志。
|
||
- 前端需按当前用户角色控制按钮/入口的**显隐与禁用**。
|
||
|
||
---
|
||
|
||
## 3. 各页面功能与用户交互
|
||
|
||
### 页面 1：登录页
|
||
|
||
- **功能**：用户登录，进入系统。若项目与现有账号体系统一，则复用现有登录页；否则需单独实现登录页。
|
||
- **用户交互**：
|
||
- 用户输入账号、密码（等必填项），点击「登录」。
|
||
- 成功：跳转至**项目列表页**。
|
||
- 失败：页内提示错误信息，不跳转。
|
||
|
||
---
|
||
|
||
### 页面 2：项目列表页
|
||
|
||
- **功能**：展示项目列表，支持按名称/编号搜索、按进度/费用筛选、**按各日期筛选**、**按「日期异常」筛选**；进入项目详情或新建项目。
|
||
- **用户交互**：
|
||
|
||
| 用户操作 | 系统反馈 |
|
||
|----------|----------|
|
||
| 进入页面 | 请求列表数据；请求中显示 Loading；成功则展示表格；无数据时展示空状态文案。 |
|
||
| 选择搜索维度（项目名称 / 项目编号），输入关键词，点击「搜索」或回车 | 按当前维度和关键词请求列表；请求中可保留原列表或局部 Loading；结果替换列表；无结果时展示空状态。 |
|
||
| 选择「项目进度」筛选 | 按所选进度请求列表并刷新表格；无结果时展示空状态。 |
|
||
| 选择「项目费用」筛选 | 按所选费用请求列表并刷新表格；无结果时展示空状态。 |
|
||
| **选择按日期筛选**（签订日期 / 开工日期 / 计划竣工日期 / 实际竣工日期） | 按所选日期类型及条件（如区间、单日等，与后端约定）请求列表并刷新表格；无结果时展示空状态。 |
|
||
| **选择「日期异常」筛选** | 仅展示存在“日期异常”的项目（任一日期的值非「日期正常」）；与后端接口参数一致；无结果时展示空状态。 |
|
||
| 点击某一行的「查看」或「编辑」 | 跳转至**项目详情/编辑页**，并传入该项目 ID；详情加载中显示 Loading。 |
|
||
| 点击「新建项目」（仅市场部可见） | 跳转至**项目详情/编辑页**，不传项目 ID（新建模式）；页面展示 5 个 Tab 的空表单。 |
|
||
| 分页操作（若有） | 请求对应页数据并刷新列表。 |
|
||
|
||
- **列表展示**：至少包含项目名称、合同编号、进度、费用等关键信息列，以及操作列（查看/编辑）。具体列与后端接口字段一致。
|
||
- **筛选说明**：除项目进度、项目费用外，列表需支持**按签订日期、开工日期、计划竣工日期、实际竣工日期**的筛选（日期类型与条件与后端约定），以及**「日期异常」**筛选项（筛选至少有一个日期字段非「日期正常」的项目）。
|
||
|
||
---
|
||
|
||
### 页面 3：项目详情/编辑页
|
||
|
||
- **功能**：查看或编辑单个项目的全部信息（5 个分类）；新建时为本页空表单。所有有权限角色均可编辑并保存，保存由后端记操作日志。
|
||
- **用户交互**：
|
||
|
||
| 用户操作 | 系统反馈 |
|
||
|----------|----------|
|
||
| 进入页面（带项目 ID） | 请求该项目详情；请求中显示 Loading；成功后在当前页展示 5 个 Tab 及表单内容。 |
|
||
| 进入页面（新建，无项目 ID） | 直接展示 5 个 Tab 的空表单，无 Loading。 |
|
||
| 切换 Tab（合同信息 / 成本控制 / 应收款 / 应付款 / 其他） | 切换当前展示的 Tab 内容，无请求。 |
|
||
| 填写或修改表单字段 | 仅前端状态变化；可做前端校验（与后端约定）。 |
|
||
| 点击「保存」 | 提交中：保存按钮 Loading，禁止再次点击；成功：提示「保存成功」（如 Toast），新建时可选跳转至该详情或列表；失败：提示接口返回错误信息，不关闭当前页。 |
|
||
| 点击「返回」或等价入口 | 返回**项目列表页**；是否保留列表页上次的搜索/筛选状态与产品约定。 |
|
||
| 点击「查看操作日志」 | 打开**操作日志**（抽屉或新页），展示当前项目的修改记录。 |
|
||
|
||
- **5 个 Tab**：合同信息、成本控制、应收款、应付款、其他。每个 Tab 内为该分类下的表单字段，字段与《产品文档》一致，单位与校验与后端对齐。字段清单见本文第 5 节。
|
||
|
||
- **日期字段逻辑（签订日期、开工日期、计划竣工日期、实际竣工日期）**
|
||
以上四个字段在后端为**字符串**，既可表示日期，也可表示说明文字；前端需同时支持**显示日期**或**显示字符串**。
|
||
- **后端存储（导入）**：导入数据时，若该字段有有效日期数据，则存为固定字符串「日期正常」；若无日期数据，则存入导入的原始字符串（如「未签订」「待定」等）。
|
||
- **API 返回**：接口返回时，若该字段值为「日期正常」，则返回实际日期（格式与后端约定）；否则返回该字符串。
|
||
- **前端展示**：根据接口返回值判断——若为日期格式则按日期展示（如日期选择器或格式化日期文本）；若为字符串则直接展示该字符串。编辑时，用户可选择/输入日期或输入文字，提交格式与后端接口约定一致。
|
||
|
||
---
|
||
|
||
### 页面 4：操作日志
|
||
|
||
- **功能**：展示某一项目的修改记录（操作人、时间、修改摘要等），仅查看，无编辑。
|
||
- **承载形式**：可为详情页右侧**抽屉**，或**独立页面**；与产品/前端约定一致即可。
|
||
- **用户交互**：
|
||
|
||
| 用户操作 | 系统反馈 |
|
||
|----------|----------|
|
||
| 打开操作日志（从详情页入口） | 请求该项目下的操作日志；请求中显示 Loading；成功则展示记录列表；无记录时展示空状态文案。 |
|
||
| 关闭抽屉 / 返回 | 关闭抽屉或返回详情页/列表页。 |
|
||
|
||
- **列表内容**：操作人、操作时间、修改内容摘要（如「合同信息」「成本控制」等），具体字段与后端接口一致。
|
||
|
||
---
|
||
|
||
## 4. 全局状态与异常
|
||
|
||
| 场景 | 交互反馈 |
|
||
|------|----------|
|
||
| 列表/详情/日志请求中 | 明确 Loading 态（整页或局部）。 |
|
||
| 保存提交中 | 保存按钮 Loading，禁止再次点击。 |
|
||
| 保存成功 | 统一成功提示（如 Toast）。 |
|
||
| 保存或接口失败 | 页内或 Toast 提示错误信息，不关闭当前页。 |
|
||
| 无权限（如 403） | 提示无权限，可引导返回列表。 |
|
||
| 列表无数据 / 无搜索结果 | 空状态文案，无表格内容。 |
|
||
| 操作日志无记录 | 空状态文案。 |
|
||
|
||
---
|
||
|
||
## 5. 项目信息字段（5 个 Tab）
|
||
|
||
详情/编辑页按 5 个 Tab 组织，字段与《产品文档》一致；单位、校验、是否必填与后端对齐。
|
||
|
||
- **合同信息**：序号、合同编号、供电局项目合同编号、项目名称、子项个数、子项编码、项目总投资、中标合同金额、质保金比例、结算金额、总成本测算、工程电压等级、工程类别、业主单位、业主联系人及电话、中标形式、**签订日期、开工日期、计划竣工日期、实际竣工日期**（以上四字段可显示日期或字符串，逻辑见页面 3「日期字段逻辑」）、质保金、质保期截止日、实际退质保金日期、所属项目部、项目负责人及电话、工程款拨付方式。
|
||
- **成本控制**：总体成本、是否调整（是/否）、农民工工资（按进度计划/实付）、乙供材料费（控制）、应付材料费（按收款比例）、实际发生/支付材料费、其他费用（控制）、应付其他费、实际其他费用、税金、利润/实际利润、成本结算金额。
|
||
- **应收款**：应收款（完成进度款）、开票金额、实际收款金额、实际收款完成率。
|
||
- **应付款**：应付款金额、实际付款金额、未收款、实际付款完成率、民工工资清欠金额。
|
||
- **其他**：结算后成本测算金额、结算人工费/材料费/其他费、到期应结算项目个数、到期未完成结算个数、存在的问题、建议措施、累计进度、备注。
|
||
|
||
---
|
||
|
||
## 6. 小结（给前端）
|
||
|
||
- **页面数**：4 个（登录、项目列表、项目详情/编辑、操作日志；操作日志可为抽屉）。
|
||
- **权限**：仅市场部展示「新建项目」；所有角色可查看、编辑、保存；保存由后端记日志，前端仅提供「查看操作日志」入口与展示。
|
||
- **搜索**：项目名称、项目编号；触发方式与后端约定（如回车/点击搜索）。
|
||
- **筛选**：项目进度、项目费用；**按签订日期、开工日期、计划竣工日期、实际竣工日期**（日期条件与后端约定）；**「日期异常」**（筛选存在非「日期正常」日期字段的项目）；选项与列表接口参数一致。
|
||
- **详情页**：5 个 Tab 对应 5 类字段；**签订日期、开工日期、计划竣工日期、实际竣工日期** 四个字段：API 若返回日期则按日期展示，若返回字符串则原样展示；保存时防重复提交、成功/失败有明确反馈。
|
||
|
||
---
|
||
|
||
**文档版本**：v2.1
|
||
**依据**：产品文档、后端日期字段与列表筛选约定
|