规划设计院合同管理系统 (Contract Management System)

📌 项目简介

本项目专为规划设计院（及类似轻资产、重人工、按节点确权收费的工程咨询机构）定制的 全生命周期合同与业财联动管理系统。 系统旨在打破“业务线（合同立项与履约）”与“财务线（收据实收与发票开出）”的信息壁垒，实现从项目立项、合同起草、收款计划拆解、到实际资金进账与发票开具的无缝闭环管理。

🚀 当前版本定位

MVP 内部测试版 (v0.1.0-alpha)

当前版本为核心功能的最简可行产品（MVP），主要用于验证“确权—>拆解—>进账—>开票”骨干业务链路的数据连通性及业财数据的防爆雷预警逻辑。此阶段为轻量化、全原生的结构形态，暂不包含复杂的 OA 审批工作流流转及外部单点登录（SSO）集成。

✨ 核心功能

• 权限与组织架构隔离 (RBAC)：支持基于角色的数据权限控制逻辑（目前提供超管、部门负责人、项目经理三个层级视角），确保业财数据横向与纵向安全。
• 客户与项目前置档案：标准化的客户库与项目立项管理，为后续长期的合同起草提供基础锚点与业务源头。
• 合同台账核心流：支持总包合同的防呆录入与全貌台账查询，打通多级信息维系。
• 收付款与发票台账 (金三角聚口)：
  • 收款计划：将大额合同按里程碑拆解，通过总额防呆拦截避免计划超额。
  • 实收款管理：记录真实的物理资金入账事实。
  • 发票档案：登记销项合规与自动税额测算。
• 防呆预警大屏 (Dashboard)：自动计算全院总量及每个单合同维度的“已票未收（垫税黑洞预警）”与“已收未票（违约风险预警）”，以及违约逾期期数。
• 轻量审计与留痕：提供隐秘的后台全局高危增删改操作拦截与动作追溯引擎。

🛠 技术栈

• 前端基建：Next.js (App Router, React 18)
• 项目语言：TypeScript
• 界面样式：Tailwind CSS (核心采用纯原生类组合，避免多余沉重的通用 UI 组件库包袱)
• 后端 & 接口引擎：Next.js Route Handlers (Serverless API 方案)
• 数据库中间件：Prisma (强类型 ORM 联表支持)
• 底层存储：SQLite (当前开发与 MVP 演示阶段使用，方便零配置拉起，后期支持平滑转 MySQL/PostgreSQL)
• 外设拓展：SheetJS (按需动态加载的轻量 Excel 客户端导出引擎)

📂 项目结构简介

├── docs/                   # 业务蓝图、迭代轨迹及内部测试操作文档
├── prisma/                 # 数据库模型定义 (schema.prisma) 与 变更建表痕迹 (migrations)
├── src/
│   ├── app/                # Next.js App Router (承载所有页面组件与 API 接口路由)
│   ├── components/         # 跨级复用的泛用组件库 (通用表格、过滤栏、模态框等)
│   └── lib/                # 核心业务脱离服务 (鉴权 Auth、数据库实例生成、审计 Logger)
└── public/                 # 静态资源与临时开发环境的文件附件上传存放区

💻 本地运行方式

环境要求：Node.js 18.17+

1. 克隆项目并安装依赖

   git clone <当前仓库地址>
   cd <项目名称>
   npm install

2. 初始化数据库环境 本项目开发阶段采用轻量级 SQLite，请执行以下命令来同步最新的 Schema 并准备初始库文件：

   npx prisma generate
   npx prisma migrate dev

3. 启动本地开发服务器

   npm run dev

   终端就绪后，打开浏览器访问 http://localhost:3000 即可进入系统门户。

4. 体验账号门禁准备 当前初级验证版本内置了硬编码拦截的模拟账号，专门用以演示数据权限墙与视图隔离：

   • 超管全域特权：账号 admin / 密码 123456
   • 部门管辖特权：账号 manager / 密码 123456
   • 基层起草特权：账号 pm / 密码 123456

📖 文档说明

对于即将参与本次 MVP 内部试用和系统走查的业务人员、法务财务代表、测试人员，请【务必】优先阅读本仓库下方的内部操作手册： 👉 《MVP内部体验与测试指南》 (docs/MVP内部体验与测试指南.md)

该指南会详细指导您的测试视角、标准连招操作路径演练、以及极其关键的内部统一问题反馈模版。

⚠️ 已知限制与技术债 (Roadmap)

• 审批流转暂缺：当前系统的履约阶段状态流转（草拟 -> 审批 -> 生效）暂依赖相关定性人员的手动干预确认，尚未纳入重量级的 BPMN 工作流引擎引擎。
• 单机版附件基建：目前为保证首发可用性，合同扫描归档件暂存服务器本地（不会提交至代码仓库），后期演进规划为转移至专线 OSS 对象存储。
• 身份网关脱钩：MVP 验证期未接通正式的企微 / 钉钉 等外部企业级真实单点登录组织架构。
• 补充协议受限：系统当下强认定合同主基调一次性落锤为准，无法对主金额提供类似《X号补充修改协议》带来的子卷宗浮动修正空间。