# 宁夏赛睿医疗 CRM 项目交接文档

| 项目 | 宁夏赛睿医疗 CRM 与学术活动管理系统 |
| --- | --- |
| 交接日期 | 2026-10-10 |
| 当前代码目录 | `D:\Java_AI\sairui` |
| 当前阶段 | 初版功能已搭建完成，待客户线上确认、移动端体验复核及后续真实业务能力接入 |
| 交接人 | 鲜明阳 |
| 接收人 | 罗庆宇 |
| 客户/业务负责人 | 肖恺 |

> 本文依据当前工程源码、配置及模块文档整理。账号、密码、AppKey、客户联系人、生产地址和文件存储凭证不写入本文，应通过公司认可的密码管理工具或安全渠道单独交接。

## 1. 项目目标与交付范围

项目面向医疗销售协同场景，目标是让业务人员通过 PC 和手机浏览器管理医院、科室、医生档案，并完成拜访、学术活动、付款和管理统计等工作。

当前已开发并可本地联调的模块如下：

| 模块 | 当前功能状态 | 主要入口 |
| --- | --- | --- |
| 市场维护 | 已完成初版 | `/market` |
| 拜访管理 | 已完成初版 | `/visits` |
| 学术活动 | 已完成初版 | `/activities` |
| 活动扫码签到 | 已完成初版 | `/activity-check-in/:token` |
| 付款流程 | 已完成初版 | `/payments` |
| 管理报表 | 已完成初版 | `/reports` |
| 项目台账 | 仅保留页面入口，未开发业务功能 | `/ledger` |
| 钉钉真实免登、组织同步、真实审批 | 仅预留接入边界，未完成 | 无 |

## 2. 工程结构

```text
D:\Java_AI\sairui
├─ sairui-server/                 Spring Boot 后端
│  ├─ src/main/java/com/sairui/
│  │  ├─ common/                  统一响应、异常处理
│  │  ├─ config/                  Web、MyBatis-Plus 配置
│  │  ├─ integration/dingtalk/    钉钉用户上下文预留
│  │  ├─ module/                  市场、拜访、活动、付款、报表模块
│  │  └─ system/                  健康检查接口
│  └─ src/main/resources/db/schema/  数据库建表脚本 V1-V5
├─ sairui-web/                    Vue 3 前端
│  └─ src/
│     ├─ api/                     Axios 请求封装及模块接口
│     ├─ components/              AppShell 全局布局
│     ├─ router/                  路由
│     ├─ styles/                  全局样式
│     └─ views/                   各业务页面
├─ modules/                       各模块 README 和用户操作手册
└─ docs/                          需求、架构、周报、技术复盘、交接文档
```

## 3. 技术栈与运行地址

| 类别 | 技术/版本 |
| --- | --- |
| 后端 | JDK 1.8、Spring Boot 2.7.18、Spring MVC、MyBatis-Plus 3.5.5、Maven |
| 数据库 | MySQL 8、InnoDB、utf8mb4 |
| 前端 | Vue 3、TypeScript、Vite、Vue Router、Axios、Pinia |
| 二维码 | `qrcode` 前端库，用于活动签到二维码 |
| 默认后端端口 | `8086` |
| 默认前端端口 | `5173`，端口占用时 Vite 可能自动使用 `5174` |
| 本地前端入口 | `http://127.0.0.1:5173/` 或终端实际输出地址 |
| 后端健康检查 | `http://localhost:8086/api/v1/system/health` |

前端使用 Vite 代理将 `/api` 转发至 `http://localhost:8086`。后端本地 CORS 已覆盖 `localhost`、`127.0.0.1` 的 5173/5174 端口，以及常用局域网网段的开发访问地址。

## 4. 本地启动与验证

### 4.1 前置软件

- JDK 8。
- Maven 3.8+。
- MySQL 8。
- Node.js 18+ 与 npm。

### 4.2 数据库初始化

1. 创建数据库 `sairui`，字符集使用 `utf8mb4`。
2. 按顺序执行以下脚本：

```text
sairui-server/src/main/resources/db/schema/V1__base_schema.sql
sairui-server/src/main/resources/db/schema/V2__market_maintenance.sql
sairui-server/src/main/resources/db/schema/V3__academic_activities.sql
sairui-server/src/main/resources/db/schema/V4__visit_management.sql
sairui-server/src/main/resources/db/schema/V5__payment_process.sql
```

3. 不要重复执行已执行过的脚本；当前项目没有接入 Flyway/Liquibase 自动迁移，数据库版本需人工登记和管理。
4. 数据库连接优先通过环境变量设置：`SAIRUI_DB_HOST`、`SAIRUI_DB_PORT`、`SAIRUI_DB_NAME`、`SAIRUI_DB_USERNAME`、`SAIRUI_DB_PASSWORD`。

### 4.3 启动后端

在 `D:\Java_AI\sairui\sairui-server` 目录执行：

```powershell
mvn "-Dspring-boot.run.profiles=local" spring-boot:run
```

启动后访问：

```text
GET http://localhost:8086/api/v1/system/health
```

预期返回 `code: 0` 且 `data.status: UP`。

如需构建验证：

```powershell
mvn clean package
```

### 4.4 启动前端

首次启动或依赖变化后，在 `D:\Java_AI\sairui\sairui-web` 执行：

```powershell
npm install
npm run dev
```

终端会输出实际浏览器地址。若 `5173` 已被占用，会使用其他端口；此时后端 `application-local.yml` 的 CORS 白名单需要包含实际端口。

前端构建验证：

```powershell
npm run build
```

### 4.5 推荐联调顺序

1. 先确认后端健康检查正常。
2. 打开前端首页，确认不会出现 403 或网络错误。
3. 在市场维护新增医院、科室、医生。
4. 创建一条拜访，完成签到和拜访记录。
5. 创建一条学术活动，完成审批与扫码签到。
6. 创建一笔付款，按流程完成审批、协议、付款凭证、发票归档。
7. 打开管理报表，检查统计是否能展示上述数据。
8. 使用手机浏览器重新验证市场维护、拜访签到、活动签到和付款附件预览。

## 5. 已实现模块说明

### 5.1 市场维护

**前端页面：** `sairui-web/src/views/MarketView.vue`

**后端包：** `com.sairui.module.market`

**数据表：** `market_hospital`、`market_department`、`market_doctor`

**已实现功能：**

- 医院、科室、医生三级档案新增、编辑、详情查看、关键字检索和分页。
- 档案录入与全部数据分视图展示，避免数据量增加后表单与列表混杂。
- 删除操作位于列表中，删除前会二次确认。
- 后端删除保护：医院关联科室、拜访或学术活动时不可删除；科室关联医生、拜访或活动时不可删除；医生关联拜访时不可删除。
- 数据表操作区的“详情”和“删除”按钮已统一尺寸、圆角和间距，详情为浅蓝色，删除为浅红色。

**关键接口：**

| 方法 | 地址 | 说明 |
| --- | --- | --- |
| GET | `/api/v1/market/hospitals?keyword=` | 医院查询 |
| POST | `/api/v1/market/hospitals` | 新增医院 |
| PUT | `/api/v1/market/hospitals/{id}` | 编辑医院 |
| DELETE | `/api/v1/market/hospitals/{id}` | 删除医院 |
| GET/POST | `/api/v1/market/departments` | 科室查询/新增 |
| PUT/DELETE | `/api/v1/market/departments/{id}` | 科室编辑/删除 |
| GET/POST | `/api/v1/market/doctors` | 医生查询/新增 |
| PUT/DELETE | `/api/v1/market/doctors/{id}` | 医生编辑/删除 |

**注意：** 当前是物理删除。若客户需要审计追溯，应改为逻辑删除并保留操作人、删除时间和原因。

### 5.2 拜访管理

**前端页面：** `sairui-web/src/views/VisitManagementView.vue`

**后端包：** `com.sairui.module.visit`

**数据表：** `visit_record`

**已实现功能：**

- 关联医院、科室、医生创建拜访计划。
- 查询、分页、详情、计划编辑。
- 浏览器定位签到；设备无法定位时有本地开发兼容处理。
- 手机拍照或选择图片、图片预览；前端单文件限制为 2MB。
- 签到后填写沟通结果、后续计划、下次拜访日期及风险等级。
- 状态流转：`PLANNED -> CHECKED_IN -> COMPLETED`。

**注意：** 当前定位和拍照由浏览器能力实现，未接入钉钉 JS API；照片数据不是生产级文件存储方案。

### 5.3 学术活动与扫码签到

**前端页面：** `AcademicActivityView.vue`、`ActivityCheckInView.vue`

**后端包：** `com.sairui.module.activity`

**数据表：** `academic_activity`、`academic_activity_agenda`、`academic_activity_expense`、`academic_activity_check_in`

**已实现功能：**

- 创建活动主档、议程明细和费用明细。
- 按关键字、活动类型、流程状态查询活动。
- 三方审批：总经理、市场、合规；角色值为 `GENERAL_MANAGER`、`MARKETING`、`COMPLIANCE`。
- 活动创建时生成唯一签到令牌；详情页生成二维码，扫码进入独立签到页面。
- 已通过审批的活动可签到；签到后更新实际签到人数。

**状态重点：** 草稿提交后进入待审批；三方均通过才成为已通过；任一方驳回即为已驳回。

**注意：** 真实审批、电子签章、活动附件、个人信息脱敏和会务协同尚未接入。活动、议程和费用更新涉及多表写入，建议后续在 Service 方法上补充事务及回滚测试。

### 5.4 付款流程

**前端页面：** `sairui-web/src/views/PaymentProcessView.vue`

**后端包：** `com.sairui.module.payment`

**数据表：** `payment_request`

**已实现功能：**

- 付款申请创建、草稿编辑、查询、分页、详情。
- 总经理审批、协议/合同上传、财务付款与凭证上传、发票上传、自动归档。
- 上传的协议、付款凭证和发票支持前端预览与下载。
- 本地附件以 Base64 数据保存，单文件前端限制为 8MB。

**状态流转：**

```text
DRAFT -> PENDING_APPROVAL -> AGREEMENT_PENDING
      -> FINANCE_PROCESSING -> INVOICE_PENDING -> ARCHIVED
                            \-> REJECTED
```

**注意：** 当前由页面模拟总经理和财务操作，未接真实钉钉审批、电子签章、银行支付、发票验真或对象存储。大附件 Base64 入库会快速增大数据库，不适合生产环境。

### 5.5 管理报表

**前端页面：** `sairui-web/src/views/ReportView.vue`

**后端包：** `com.sairui.module.report`

**接口：** `GET /api/v1/reports/overview?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd`

**已实现功能：**

- 默认最近 30 天，可按日期范围查看。
- 市场维护覆盖统计、医院/科室/医生数量。
- 拜访总数、完成数、风险提醒、医院拜访排行。
- 学术活动数量与待处理统计。
- 付款申请数量、金额、待处理/已归档统计。
- 每日趋势和各流程状态分布；统计卡片支持跳转至对应模块查看明细。
- 已适配 PC 与手机浏览器。

**注意：** 当前报表先读取业务列表后在 Java 内存中用 Stream 聚合。数据量大后应改为 SQL 聚合、后端物理分页、缓存或汇总表。

## 6. 后端架构与关键约定

### 6.1 分层约定

每个业务模块通常按 `controller`、`service`、`mapper`、`entity`、`dto` 分层：

- Controller：接收 HTTP 请求、参数校验、调用 Service。
- Service：业务规则、状态转换、关联校验。
- Mapper：MyBatis-Plus 数据访问。
- Entity：数据库表映射。
- DTO：请求入参及 Bean Validation 规则。

### 6.2 统一接口规范

所有 API 返回统一结构：

```json
{
  "code": 0,
  "message": "成功",
  "data": {}
}
```

相关代码：

- `common/api/ApiResponse.java`
- `common/api/ApiCode.java`
- `common/exception/GlobalExceptionHandler.java`

前端的 `src/api/http.ts` 会同时判断 HTTP 状态和业务 `code`。新增接口时应保持这一约定。

### 6.3 全局异常与校验

- `BusinessException`：可预期的业务限制，例如状态不允许流转、有关联数据不能删除。
- `MethodArgumentNotValidException`：DTO 的 `@Valid` 参数校验失败。
- 其他异常：统一返回系统错误，详细堆栈只在服务端日志中查看。

### 6.4 MyBatis-Plus

- 通过 `BaseMapper` 获取基础 CRUD。
- 条件查询使用 `LambdaQueryWrapper`，避免硬编码列名。
- 已配置 MySQL 分页插件 `PaginationInnerInterceptor`。
- 现有多数列表仍为全量查询后由前端分页，后续应优先改造为后端分页，避免大数据量性能问题。

### 6.5 钉钉接入现状

`DingTalkUserInterceptor` 会从请求 Header 读取 `X-DingTalk-User-Id`、`X-DingTalk-User-Name` 写入 `ThreadLocal`，请求结束后清理。

此能力仅用于本地联调预留，**不能作为生产身份认证**。生产接入应完成钉钉免登、服务端签名校验、角色权限、数据权限、审计日志及异常处理。

## 7. 数据库交接要点

### 7.1 主要表关系

```text
market_hospital
  └─ market_department
       └─ market_doctor

visit_record -> hospital_id / department_id / doctor_id
academic_activity -> hospital_id / department_id 等业务关联字段
academic_activity -> agenda / expense / check_in 子表
payment_request 独立维护付款及附件信息
```

### 7.2 数据管理建议

- 在执行脚本、升级字段或删除数据前先备份数据库，并在测试库验证。
- 客户正式数据导入前，确认医院、科室、医生去重规则和历史数据映射规则。
- 金额字段使用 MySQL `DECIMAL` 与 Java `BigDecimal`，不得改用浮点型。
- 生产环境应建立备份、恢复演练和最小权限数据库账号。
- 数据库脚本以 V1-V5 命名但目前不由迁移框架自动执行；后续新增脚本必须记录执行时间、执行人、环境和回滚方案。

## 8. 常见问题排查

| 现象 | 优先排查 |
| --- | --- |
| 前端无法访问系统 | 是否已执行 `npm run dev`，并以终端输出的实际端口访问。 |
| 访问后端失败 | 后端是否已启动，`/api/v1/system/health` 是否返回 UP，端口是否为 8086。 |
| 接口 403 | 前端来源端口是否已在后端 CORS `allowed-origins` 中；确认 Vite 代理目标是否为 8086；检查是否使用了未允许的 IP/端口。 |
| 保存无数据 | 浏览器 Network 检查方法、URL、请求体；再检查 Controller 路径、DTO 校验、后端日志及数据库表。 |
| 科室或医生被覆盖 | 新增应调用 POST，编辑才调用 PUT `/{id}`；先检查前端当前编辑 ID 是否被错误保留。 |
| 删除提示失败 | 检查是否有关联科室、医生、拜访或活动；当前设计会阻止删除有关联的数据。 |
| 手机不能定位/拍照 | 浏览器必须授权定位和相机；HTTP 页面或设备权限限制会导致失败；当前有开发兼容逻辑，但生产应接钉钉能力。 |
| 前端构建失败且提示 tsbuildinfo 权限错误 | 关闭占用文件的编辑器/终端后重试，确认 `node_modules/.tmp` 可写；必要时重新安装前端依赖。 |
| 附件无法预览或下载 | 检查 Base64 数据、文件名和浏览器支持类型；超过前端限制的文件不会被提交。 |

## 9. 当前风险与后续优先级

### P0：交接时必须补齐

1. **代码版本管理缺失。** 当前 `D:\Java_AI\sairui` 不是 Git 仓库，无法依据现有目录追溯提交历史、发布版本或责任人。应立即在公司 Git 平台建立私有仓库，提交当前可运行快照，并设置分支保护与发布标签。
2. **敏感配置治理。** 本地配置文件曾用于开发数据库连接，不应将任何真实密码、钉钉密钥或客户凭证继续保存在源码目录。请交接前轮换已暴露的开发凭证，将秘密迁移到环境变量、密钥管理服务或部署平台配置。
3. **客户环境信息缺失。** 需由负责人另行交接客户部署地址、域名、服务器、数据库、钉钉应用、对象存储、证书、联系人、访问权限及账号所有权；本文不包含这些敏感信息。
4. **上线前验收缺失。** 当前为初版，需组织客户线上演示，确认字段、流程节点、审批角色、权限范围、历史数据迁移与手机端关键路径。

### P1：上线前应完成

1. 接入真实钉钉免登、组织架构、审批和移动端 JS API；不得信任前端自定义 Header。
2. 建立用户、角色、数据权限和操作审计体系。
3. 把付款、活动及附件由本地模拟能力替换为真实审批、对象存储和受控下载。
4. 为活动保存等多表操作补充 `@Transactional`，并补充流程、删除保护、金额和日期边界的自动化测试。
5. 后端实现物理分页和条件检索，报表改为 SQL 聚合或预计算，避免数据规模提升后全量加载。
6. 明确备份、监控、日志留存、错误告警、发布回滚和数据迁移流程。

### P2：持续优化

1. 完成项目台账模块。
2. 根据客户反馈优化手机端信息密度、操作路径和附件体验。
3. 丰富报表口径、导出、权限范围和风险提醒。
4. 评估升级至较新的 JDK/Spring Boot 版本，并建立 CI/CD。

## 10. 接收人建议的首日检查清单

- [ ] 获取公司 Git 仓库、服务器、数据库、钉钉应用、域名/证书及部署平台的合法访问权限。
- [ ] 确认所有共享凭证已通过安全渠道交接并完成所有权转移；不要通过即时聊天工具发送密码。
- [ ] 用新的本地开发数据库按 V1-V5 脚本完成初始化。
- [ ] 分别执行后端启动、前端启动、后端健康检查与前端构建。
- [ ] 完整跑通市场维护、拜访、学术活动、付款、报表五条业务路径。
- [ ] 用手机浏览器复核定位、拍照、附件预览和表单布局。
- [ ] 与客户确认尚未落地的审批、权限、附件、数据导入及台账需求。
- [ ] 建立问题清单、发布记录、数据库变更登记和验收记录。

## 11. 现有文档索引

| 文档 | 用途 |
| --- | --- |
| `README.md` | 项目总体目标、范围和技术约束 |
| `docs/需求基线.md` | 当前需求边界 |
| `docs/架构设计.md` | 前后端架构与接口约定 |
| `docs/周报_20260914-20260918.md` | 前期周报 |
| `docs/周报_20260921-20260924.md` | 后续周报 |
| `docs/Java面试技术复盘与AI-Coding实践.md` | 代码技术点及已知改进方向 |
| `modules/基础工程/` | 基础工程说明与操作手册 |
| `modules/市场维护/` | 市场维护 README 与操作手册 |
| `modules/学术活动/` | 学术活动 README 与操作手册 |
| `modules/拜访管理/` | 拜访管理 README 与操作手册 |
| `modules/付款流程/` | 付款流程 README 与操作手册 |
| `modules/管理报表/` | 管理报表 README 与操作手册 |