合同对账系统

kuaishenghu · 发表于 2026-5-23 18:01:13

本帖最后由 kuaishenghu 于 2026-5-25 09:38 编辑

一、运行环境与支持平台

操作系统：支持 Windows 和 Linux（包括 CentOS、Ubuntu、Debian、宝塔面板等），系统自动识别系统类型并设置默认数据库路径。
Web 服务器：Nginx 1.20+ / Apache 2.4+，推荐 Nginx。
PHP 版本：7.0 ~ 8.x，已兼容 PHP 7.0 语法。
数据库：支持 SQLite 3 和 MySQL 5.7+，可在系统设置中随时切换，切换时自动创建表结构。
浏览器：Chrome、Edge、Firefox 等现代浏览器。
PHP 扩展：必须开启 pdo_sqlite 或 pdo_mysql（根据实际数据库）、mbstring、json、fileinfo。如需导入 Excel，需安装 PhpSpreadsheet 库（Composer 安装）。

二、文件结构与作用

index.php：系统入口，包含登录检查、侧边栏菜单、页面路由、通用 JavaScript 函数（合同详情弹窗、空闲超时、菜单高亮等）。
config.php：配置文件，设置时区、Session 生命周期、路径常量（备份目录、日志目录）、数据库配置读写、IP 访问控制函数等。
DB.php：数据库操作类，实现 SQLite/MySQL 双驱动，首次运行时自动创建所有表及初始数据（admin 用户、备份设置等），并提供汇总更新方法。
api.php：后端 API 接口，处理所有 AJAX 请求（登录、合同增删改查、开票/收款/审定记录管理、统计、导入导出、备份恢复、用户管理等）。
upload_handler.php：合同批量导入处理脚本，负责解析上传的 CSV/Excel 文件，实现合同覆盖更新、开票/收款追加、审定覆盖等逻辑。
config_handler.php：处理数据库切换、测试连接、清空数据库等系统设置操作。
login_page.php：登录页面，包含用户名密码表单和登录逻辑。
template_download.php：下载合同导入模板。
db_config.json：数据库配置持久化文件，保存当前使用的数据库类型及连接参数。
assets/：静态资源目录，包含 CSS（Bootstrap、DataTables、Font Awesome）和 JS（jQuery、Bootstrap、DataTables、Chart.js、Bootbox、SheetJS）。
pages/：各功能页面目录，包含：统计仪表 dashboard.php、合同总表 contracts.php、项目状态status.php、用户工程 user_project.php、双清表 settlement.php、审定管理 approval.php、上传文件 upload.php、系统设置 settings.php、收款表 income.php、开票汇总 invoice.php、下发项目 dept_issue.php、开票提醒 reminder.php、收款提醒 income_reminder.php 等。
logs/：存放登录访问日志（按日分割，保留30天）。
backups/：存放数据库备份文件。

三、合同管理

合同主表字段：包含合同名称、财务平台编码、合同编号、合同金额、审定金额、帐外债权、甲方单位、签订日期、开工/竣工时间、合同状态、审定状态、合同来源、分类、业务类型、电压等级、框架金额、下浮率、送审金额、预计审定金额、付款摘录、是否需要下发项目部、是否已下发、税率、联系人、备注等。
唯一性约束：合同名称唯一，不可重复；财务平台编码若填写则也需唯一，留空则视为无编码；合同编号用于关联子表。
新增/编辑合同：在“合同总表”页面操作，支持所有字段录入和修改，合同编号为必填项。
合同关闭规则：当审定状态为“已审定”或“固定总价无需审计”，且审定金额 = 已开票总额 = 已收款总额时，系统自动标记为“已关闭”；管理员也可手动切换。
合同删除：仅管理员可删除，删除时级联删除该合同下的所有开票、收款、审定记录。

四、核心金额计算逻辑（自动实时更新）

已开票总额 = 该合同所有开票记录的开票金额之和。
已收款总额 = 该合同所有收款记录的收款金额之和。
应开票基准金额 = 审定状态为“已审定”且审定金额>0时取审定金额，否则取合同金额。
待开票金额 = 应开票基准金额 - 已开票总额（最小为0）。
待收款金额 = 已开票总额 - 已收款总额（最小为0）。
帐外债权 = 审定金额 + 预计审定金额 - 已收款总额（最小为0），也可手动修改。
每次增删改开票、收款、审定记录后自动调用汇总更新函数，并判断是否自动关闭合同。

五、导入功能详解重要区分： 不同页面的导入行为不同，请仔细阅读。
5.1 “上传文件”页面（合同总表导入）

合同主表：采用覆盖模式，优先通过合同编号匹配已有合同（若文件中存在合同编号列），匹配则覆盖所有合同字段；其次通过合同名称匹配；若无匹配则新增合同。
开票记录：采用追加模式，若文件中提供了已开票金额，则插入新的开票记录（携带合同编号），不删除原有开票记录。
收款记录：采用追加模式，逻辑同开票。
审定记录：采用覆盖模式，每个合同仅保留一条审定记录，先删除再插入文件中的数据（若文件中提供了审定金额）。
文件内重复检查：上传前检测文件中是否有重复的合同编号，若有则中止导入并提示。

5.2 “开票汇总”、“收款表”、“审定管理”各自的独立导入

共同点：采用覆盖模式，导入前删除该合同对应的所有子表记录，再插入文件中的新记录，多次导入不会重复。
合同识别：优先通过“合同编号”列匹配，其次通过“合同名称”匹配，均失败则该行失败并记录原因。
不影响主表：仅操作子表和合同的汇总金额字段，不修改合同主表其他字段。
文件格式：支持 CSV UTF-8（自动识别分隔符）和 Excel（依赖 PhpSpreadsheet 库），表头需包含固定列名，列顺序可任意。

5.3 “开票提醒”导入

导入独立于合同的提醒记录，使用动态列名匹配（合同名称、需开票金额、应开票截止日期），支持跳过空行。

六、仪表板与统计

顶部汇总卡片：实时显示合同总数、合同金额（万元）、审定金额、已开票、待开票、已收款、待收款、帐外债权，可按签订日期范围筛选。卡片标题含单位（万元），悬停显示元级实际金额。
月度趋势图：展示最近12个月的合同金额、审定金额、已开票、已收款趋势，线条颜色鲜明。
年度统计图：近五年系统内项目（主业）与系统外项目（用户/代建）的承揽金额占比（柱状图）与总金额趋势（折线图）。
最近10条合同：按签订日期倒序，可查看详情。

七、表间关联与自动更新

开票、收款、审定记录通过“合同ID”关联主表，删除合同时子表级联删除。
任何子表增删改操作触发主表汇总字段自动重算，并判断自动关闭合同。
添加审定记录时同步更新主表的审定金额、送审金额、审定状态为“已审定”。
合同总表导入的审定金额也会写入主表。

八、用户与权限管理

角色：管理员（admin）拥有全部权限；普通用户（user）仅可查看合同、开票、收款等业务数据，无法进入系统设置。
登录锁定：同一IP+用户名连续失败3次锁定5分钟，5次锁定30分钟。
登录日志：成功登录记录于 logs/access_日期.log，保留30天，包含用户名、IP、网络类型。
访问控制：支持三种模式——“允许所有IP”、“仅局域网IP”、“自定义IP段（CIDR）”。设置错误可通过数据库命令紧急恢复。

九、数据库管理

切换数据库：可在 SQLite 与 MySQL 之间切换，配置永久保存于 db_config.json，切换时自动创建表结构。
备份与恢复：手动备份数据库为文件，支持从备份文件恢复（覆盖当前数据库），保留数量可配置。
清空数据：可清空 SQLite 或 MySQL 的全部业务数据而保留表结构，需输入确认文字。

十、开票提醒与收款提醒

开票提醒：独立于合同，可添加多条提醒。系统根据“应开票截止日期”判断紧迫度，左侧菜单图标变色（红：已过期，橙：7天内，蓝：30天内，绿：30天后）。支持日期筛选、导入/导出。
收款提醒：自动检测已开票未收齐的合同，按开票日期计算逾期天数，默认显示所有未收齐合同（最早未收齐在前）。提供7天/15天/30天筛选，行颜色区分逾期程度，可导出 CSV。左侧菜单图标同步变色。

十一、项目部下发管理

合同主表包含“是否需要下发项目部”和“是否已经下发项目部”字段。
“需要下发项目部的项目”页面默认显示所有未下发（dept_issued != '是'）的合同，点击“已下发”则仅显示已下发且需要下发的合同。
可在合同编辑中标记“已下发”，合同即从“未下发”列表转移至“已下发”列表。

十二、搜索与排序

所有列表页（合同总表、开票汇总、收款表、审定管理、双清表等）均有搜索框，支持模糊搜索合同名称、甲方单位等字段，后端模糊匹配，分页展示。
列头支持点击排序，服务器端处理，保证大数据量下响应迅速。

十三、其他重要说明

字符兼容：系统全面输出 UTF-8，对历史数据中可能存在的特殊字符（如全角括号、控制字符）有容错处理，避免 JSON 编码失败。
分页与性能：所有列表采用服务器端分页（DataTables），数据库字段建立索引，确保大数据量下流畅。
导出：导出 CSV 文件均以 UTF-8 BOM 开头，可直接用 Excel 打开，中文不乱码。
自动超时处理：30分钟无操作通过心跳检测验证会话，操作中不会误退出。
前端资源本地化：所有 CSS 和 JS 文件均存放于 assets/ 目录，不依赖外网 CDN，内网部署无忧。
合同详情弹窗：宽度可自适应，包含基本信息、开票记录、收款记录、审定记录，合同名称突出显示。
重复检测：可检测合同名称相似度≥90%的合同以及重复的合同编号，支持忽略和取消忽略。
年度汇总卡片：合同总表顶部以十年分组展现每年的合同数量、金额汇总，按审定状态区分待开票计算。

十四、部署与权限设置

将整个项目目录上传至服务器 Web 目录（例如 /www/wwwroot/hetong）。
确保 项目根目录（存放 contract.db 的那一级）对 PHP 进程用户（如 www-data）具有读写权限：
sudo chmod -R 755 /www/wwwroot/hetong
sudo chown -R www-data:www-data /www/wwwroot/hetong
若使用宝塔面板，可在“文件”管理中将目录权限设为 755，所有者为 www。
首次运行时，系统会自动创建 contract.db 空文件并初始化表结构。
如果之前有绝对路径残留，请删除 db_config.json 文件后刷新页面，系统会以相对路径重新生成配置