API 第一版定型

docs/交互文档.md

@@ -0,0 +1,137 @@
+# 交互文档（前端）
+
+**依据**：《产品文档》  
+**读者**：前端工程师  
+**目标**：明确页面数量、每个页面的功能与用户交互，便于实现与联调。
+
+---
+
+## 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 节。
+
+---
+
+### 页面 4：操作日志
+
+- **功能**：展示某一项目的修改记录（操作人、时间、修改摘要等），仅查看，无编辑。
+- **承载形式**：可为详情页右侧**抽屉**，或**独立页面**；与产品/前端约定一致即可。
+- **用户交互**：
+
+| 用户操作 | 系统反馈 |
+|----------|----------|
+| 打开操作日志（从详情页入口） | 请求该项目下的操作日志；请求中显示 Loading；成功则展示记录列表；无记录时展示空状态文案。 |
+| 关闭抽屉 / 返回 | 关闭抽屉或返回详情页/列表页。 |
+
+- **列表内容**：操作人、操作时间、修改内容摘要（如「合同信息」「成本控制」等），具体字段与后端接口一致。
+
+---
+
+## 4. 全局状态与异常
+
+| 场景 | 交互反馈 |
+|------|----------|
+| 列表/详情/日志请求中 | 明确 Loading 态（整页或局部）。 |
+| 保存提交中 | 保存按钮 Loading，禁止再次点击。 |
+| 保存成功 | 统一成功提示（如 Toast）。 |
+| 保存或接口失败 | 页内或 Toast 提示错误信息，不关闭当前页。 |
+| 无权限（如 403） | 提示无权限，可引导返回列表。 |
+| 列表无数据 / 无搜索结果 | 空状态文案，无表格内容。 |
+| 操作日志无记录 | 空状态文案。 |
+
+---
+
+## 5. 项目信息字段（5 个 Tab）
+
+详情/编辑页按 5 个 Tab 组织，字段与《产品文档》一致；单位、校验、是否必填与后端对齐。
+
+- **合同信息**：序号、合同编号、供电局项目合同编号、项目名称、子项个数、子项编码、项目总投资、中标合同金额、质保金比例、结算金额、总成本测算、工程电压等级、工程类别、业主单位、业主联系人及电话、中标形式、签订日期、开工日期、计划竣工日期、实际竣工日期、质保金、质保期截止日、实际退质保金日期、所属项目部、项目负责人及电话、工程款拨付方式。
+- **成本控制**：总体成本、是否调整（是/否）、农民工工资（按进度计划/实付）、乙供材料费（控制）、应付材料费（按收款比例）、实际发生/支付材料费、其他费用（控制）、应付其他费、实际其他费用、税金、利润/实际利润、成本结算金额。
+- **应收款**：应收款（完成进度款）、开票金额、实际收款金额、实际收款完成率。
+- **应付款**：应付款金额、实际付款金额、未收款、实际付款完成率、民工工资清欠金额。
+- **其他**：结算后成本测算金额、结算人工费/材料费/其他费、到期应结算项目个数、到期未完成结算个数、存在的问题、建议措施、累计进度、备注。
+
+---
+
+## 6. 小结（给前端）
+
+- **页面数**：4 个（登录、项目列表、项目详情/编辑、操作日志；操作日志可为抽屉）。
+- **权限**：仅市场部展示「新建项目」；所有角色可查看、编辑、保存；保存由后端记日志，前端仅提供「查看操作日志」入口与展示。
+- **搜索**：项目名称、项目编号；触发方式与后端约定（如回车/点击搜索）。
+- **筛选**：项目进度、项目费用；选项与列表接口参数一致。
+- **详情页**：5 个 Tab 对应 5 类字段，保存时防重复提交、成功/失败有明确反馈。
+
+---
+
+**文档版本**：v2  
+**依据**：产品文档

docs/产品文档.md

@@ -0,0 +1,30 @@
+# 产品文档
+
+## 1. 概述
+
+项目管理系统，多部门协作维护项目信息，支持按名称/编号/进度/费用检索与筛选。
+
+## 2. 用户与权限
+
+**角色**：管理员、市场部、工程部、技经部、财务部、物贸部。
+
+- **创建项目**：仅市场部。
+- **查看与修改**：所有角色（含市场部）均可查看和修改项目信息。
+- **修改日志**：对项目信息的修改需记录操作日志。
+
+## 3. 项目信息（5 个分类）
+
+**合同信息**：序号、合同编号、供电局项目合同编号、项目名称、子项个数、子项编码、项目总投资、中标合同金额、质保金比例、结算金额、总成本测算、工程电压等级、工程类别、业主单位、业主联系人及电话、中标形式、签订/开工/计划竣工/实际竣工日期、质保金、质保期截止日、实际退质保金日期、所属项目部、项目负责人及电话、工程款拨付方式。
+
+**成本控制**：总体成本、是否调整（是/否）、农民工工资（按进度计划/实付）、乙供材料费（控制）、应付材料费（按收款比例）、实际发生/支付材料费、其他费用（控制）、应付其他费、实际其他费用、税金、利润/实际利润、成本结算金额。
+
+**应收款**：应收款（完成进度款）、开票金额、实际收款金额、实际收款完成率。
+
+**应付款**：应付款金额、实际付款金额、未收款、实际付款完成率、民工工资清欠金额。
+
+**其他**：结算后成本测算金额、结算人工费/材料费/其他费、到期应结算项目个数、到期未完成结算个数、存在的问题、建议措施、累计进度、备注。
+
+## 4. 项目统计
+
+- **搜索**：按项目名称、项目编号。
+- **筛选**：按项目进度、按项目费用。

docs/初始需求.md

@@ -0,0 +1,89 @@
+- 用户系统
+每个用归属于这些
+    管理员
+    市场部
+    工程部
+    技经部
+    财务部
+    物贸部
+只有市场部门能创建项目信息，其他用户可以查看和修改项目信息(修改项目信息需要记录日志)。
+
+- 项目信息
+    有"合同信息"，"成本控制", "应收款", "应付款", "其他" 这5个分类。
+"合同信息" 这个分类有以下这些字段
+序号
+合同编号
+供电局项目合同编号
+项目名称
+子项个数
+子项编码
+项目总投资（万元）	
+中标合同金额（万元）
+质保金比例	
+结算金额（万元）
+总成本测算	
+工程电压等级
+工程类别
+业主单位
+业主联系人及电话
+中标形式
+签订日期
+开工日期
+计划竣工日期
+实际竣工日期
+质保金（万元）
+质保期截止日
+实际退质保金日期
+所属项目部	 
+项目负责人及电话 	
+工程款拨付方式
+
+"成本控制"这个分类有以下这些字段
+总体成本
+是否调整（是/否）
+农民工工资（按进度计划）
+农民工工资（实付）
+乙供材料费（控制）
+应付材料费（按收款比例）
+实际发生材料费	
+实际支付材料费	
+其他费用（控制）
+应付其他费	
+实际其他费用	
+税金
+利润（万元）
+实际利润（万元）
+成本结算金额（万元）
+
+"应收款"这个分类有以下这些字段
+应收款（完成进度款）
+开票金额（万元）
+实际收款金额（万元）
+实际收款完成率	
+
+"应付款"这个分类有以下这些字段
+应付款金额（万元）
+实际付款金额（万元）
+未收款（万元）
+实际付款完成率	
+民工工资清欠金额（万元）
+
+"其他"这个分类有以下这些字段
+结算后成本测算金额	
+结算人工费	
+结算材料费	
+结算其他费	
+到期应结算项目个数	
+到期未完成结算个数	
+存在的问题	
+建议措施	
+累计进度
+备注
+
+- 项目统计
+可以根据，项目名称和项目编号搜索项目
+可以根据，项目精度筛选项目
+可以根据，项目费用筛选项目
+
+
+