# 合同风控与合规审查系统-大四实训

**Repository Path**: ggg-bingkun/smartHT

## Basic Information

- **Project Name**: 合同风控与合规审查系统-大四实训
- **Description**: 大四实训项目，构建智能合同风控与合规审查系统，基于AI技术自动识别合同风险点，提升法律合规效率。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LexPact

LexPact 是合同全生命周期管理平台的初始化工程。当前提交只建立可持续开发的工程骨架、基础设施和开发约定，不包含业务用例、领域模型、数据库表迁移或真实认证逻辑。

## 1. 工程结构

```text
.
├── backend/                      # 完整后端 Maven 工程
│   ├── pom.xml                   # 后端唯一聚合入口
│   ├── apps/                     # 六个可部署后端服务
│   └── libs/                     # 可复用技术库，不放业务规则
├── frontend/                      # Vue 3 + TypeScript + Vite SPA
├── deploy/                        # 仅基础设施的 Docker Compose
├── docs/                          # 产品、架构、数据和 API 文档
├── AGENTS.md                      # 全局协作与代码规范
└── README.md                     # 项目入口和配置说明
```

设计与开发统一从 [`docs/README.md`](docs/README.md) 开始；当前闭环状态和未解决项以 [`docs/12-management/10-system-design-closure-report.md`](docs/12-management/10-system-design-closure-report.md) 为准。接口开发再进入 [`docs/07-api/README.md`](docs/07-api/README.md)：路由与字段目录见 [`01-api-catalog.md`](docs/07-api/01-api-catalog.md)，机器可读契约见 [`02-openapi.yaml`](docs/07-api/02-openapi.yaml)，错误码和页面覆盖矩阵分别见 [`03-error-codes.md`](docs/07-api/03-error-codes.md) 与 [`04-api-coverage-matrix.md`](docs/07-api/04-api-coverage-matrix.md)。

后端采用 `interfaces → application → domain ← infrastructure` 分层。服务之间只能通过 HTTP/RPC 或消息通信，不能直接访问其他服务的数据库。MySQL 是事实来源，Redis 只用于缓存、幂等、锁和短期状态；跨服务异步流程采用 RabbitMQ、Outbox 和幂等消费。

## 2. 需要使用的服务

| 服务 | 用途 | 本地入口 |
| --- | --- | --- |
| MySQL 8.4 | 五个服务数据库：`system_db`、`contract_db`、`review_db`、`lifecycle_db`、`audit_db` | `localhost:3306` |
| Redis 7.4 | 缓存、幂等键、分布式锁和短期任务状态 | `localhost:6379` |
| RabbitMQ 4.0 | 领域事件、异步任务和重试/DLQ | `localhost:5672`，管理台 `15672` |
| MinIO | 合同原文件、解析产物和导出文件 | API `localhost:9000`，控制台 `9001` |
| Nacos 2.4 | 服务发现和后续集中配置 | `localhost:8848` |

生产环境还需要在基础设施层补充 Nginx/TLS、日志采集、监控告警、备份和密钥管理；这些内容不作为本次应用初始化的一部分。`deploy/docker-compose.yml` 有意只编排上表基础设施，不编排前后端容器。

## 3. 环境要求

- JDK 17+
- Maven 3.9+
- Node.js 20+
- npm 10+
- Docker Desktop 24+

## 4. 配置文件规则

每个后端服务都包含：

- `src/main/resources/application.yml`：提交到仓库的公共配置入口，只引用 profile 配置中的值。
- `src/main/resources/application-dev.yml`：本机开发配置，包含密码和本机地址，已被 `.gitignore` 忽略。
- `src/main/resources/application-example.yml`：可提交的配置模板，使用占位符或容器服务名，不包含真实密钥。

`application.yml` 默认激活 `dev`，并通过 `spring.config.import` 预留外部 `config/application-dev.yml` 的覆盖入口；Spring Boot 同时会自动合并 classpath 下的 `application-dev.yml`。部署时可用 `SPRING_PROFILES_ACTIVE` 切换 profile，并通过环境变量覆盖端口、数据库和基础设施地址。

首次拉取后，在 PowerShell 执行：

```powershell
$services = @('gateway-service', 'system-service', 'contract-service', 'review-service', 'lifecycle-service', 'audit-service')
foreach ($service in $services) {
    Copy-Item "backend/apps/$service/src/main/resources/application-example.yml" `
    "backend/apps/$service/src/main/resources/application-dev.yml"
}
Copy-Item deploy/.env.example deploy/.env
```

然后编辑各服务的 `application-dev.yml` 和 `deploy/.env`，替换所有 `change-me`、`replace-me`。不要把真实的 `application-dev.yml`、`.env`、生产密钥或备份文件提交到 Git。

当前 Nacos 配置客户端默认关闭（`NACOS_ENABLED=false`），便于只启动本地服务骨架。Nacos 数据准备完成后，将它改为 `true`，再逐步迁移非敏感配置到 Nacos；密钥仍应放在密钥管理系统或运行环境变量中。

## 5. 启动基础设施

本次初始化只写入 Docker Compose 配置、环境变量示例和 MySQL 初始化脚本，不执行容器启动、数据卷创建或 Docker 环境配置。以下命令供后续环境负责人使用。

```powershell
docker compose --env-file deploy/.env.example -f deploy/docker-compose.yml config
docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d
docker compose --env-file deploy/.env -f deploy/docker-compose.yml ps
```

初始化脚本只创建五个业务数据库和对应的最小本地开发账号。MySQL 初始化脚本只会在空数据卷第一次启动时执行；如果已经有旧数据卷，新增数据库需要手动执行脚本或使用迁移方案。RabbitMQ 管理台地址为 `http://localhost:15672`，MinIO 控制台地址为 `http://localhost:9001`。

## 6. 启动后端

先按第 4 节生成开发配置，再从项目根目录执行：

```powershell
mvn -f backend/pom.xml -DskipTests compile
mvn -f backend/pom.xml -pl apps/system-service spring-boot:run
```

各服务默认端口如下：

| 服务 | 端口 | 基础检查 |
| --- | ---: | --- |
| gateway-service | 8080 | `GET /actuator/health` |
| system-service | 8081 | `GET /internal/health` |
| contract-service | 8082 | `GET /internal/health` |
| review-service | 8083 | `GET /internal/health` |
| lifecycle-service | 8084 | `GET /internal/health` |
| audit-service | 8085 | `GET /internal/health` |

本阶段 Flyway 默认关闭，避免在尚无业务迁移脚本时连接数据库失败。开始实现某个服务的表结构后，为该服务补 `db/migration` 并将 `FLYWAY_ENABLED=true` 纳入该环境配置。

## 7. 启动前端

```powershell
cd frontend
npm install
npm run dev
```

默认地址为 `http://localhost:5173`。Vite 将 `/api/v1` 代理到 `http://localhost:8080`，可通过 `VITE_API_TARGET` 指向其他 Gateway 地址。前端已实现完整业务页面（覆盖原型 108 个入口）、路由守卫、Pinia、统一 Axios、Element Plus、ECharts 与加载/空态/错误/403/404 状态；登录页已接入 `POST /api/v1/auth/login`，需要后端 `system-service` 实现后才能完成真实登录。

开发期可访问组件预览页 `http://localhost:5173/dev/components` 查看全部共享组件与状态（该路由由 `import.meta.env.DEV` 守卫，生产构建中不存在）。

### 无后端走查（DEV Mock）

开发环境下 Mock 默认开启（仅服务于页面走查，生产构建不包含）：页面通过同一个 Axios 实例请求，但由 `src/mocks/**` 的 adapter 返回 canonical envelope 形状的假数据，左下角固定显示 `DEV MOCK · 页面数据为前端假数据`。

- 登录：用户名/密码任意非空即可；用户名含 `legal` 登录为 LEGAL 角色，含 `business` 登录为 BUSINESS 角色，其它（如 `admin`）为 ADMIN。
- Mock 数据随操作在内存中变化，刷新页面后重置；会话在 sessionStorage 中暂存（仅 Mock 模式），刷新页面无需重复登录。
- 关闭 Mock、回到真实 `/api/v1`：在 `frontend/.env.local` 写入 `VITE_USE_MOCK=false`，或临时启动前执行 `$env:VITE_USE_MOCK="false"; npm run dev`。
- Mock 只替换 Axios adapter，`src/api/**`、`src/modules/**/api/*.api.ts` 的接口边界与真实后端完全一致，因此后端就绪后无需改业务代码。

### 静态页面与组件原型

全量高保真静态原型位于 [`frontend/public/prototype.html`](frontend/public/prototype.html)，启动 Vite 后访问 `http://localhost:5173/prototype.html`。原型包含 108 个页面入口、46 个组件/状态展示、差异化的看板/卡片/登记册/矩阵/日历/收件箱布局、CreateDialog、固定 Sidebar/Topbar、Drawer、Dialog、Toast、表单步骤条和页面级 API 标签。覆盖明细与接口对照记录见 [`docs/08-frontend/11-static-prototype-coverage.md`](docs/08-frontend/11-static-prototype-coverage.md)。

## 8. 开发规范和验证

开始编码前先阅读根目录及对应子目录的 `AGENTS.md`。完整的按文档驱动开发流程、阶段任务、门禁和拓扑图见 [`docs/12-management/09-development-process-and-topology.md`](docs/12-management/09-development-process-and-topology.md)。新增业务功能时，必须先标注所属阶段，再同步考虑接口契约、权限、审计、事务边界、幂等、重试、消息版本和测试。Review Service 是唯一允许调用外部 LLM 的服务，其他服务只能调用其内部接口或消费其事件。

推荐提交前执行：

```powershell
mvn -f backend/pom.xml test
cd frontend
npm run typecheck
npm run lint
npm run test -- --run
npm run build
```

原始领域 API 文档仍保留在 `docs/07-api-and-integration/` 供追溯；实现业务接口时以 `docs/07-api/` 的规范契约为准。数据字典等尚未纳入的文档仍需在实现前确认来源和版本，不要根据缺失文件自行臆造字段或表结构。