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

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

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

1. 项目目标与交付范围

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

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

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

2. 工程结构

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 数据库初始化

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

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

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

4.3 启动后端

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

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

启动后访问：

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

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

如需构建验证：

mvn clean package

4.4 启动前端

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

npm install
npm run dev

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

前端构建验证：

npm run build

4.5 推荐联调顺序

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

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。

状态流转：

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 返回统一结构：

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

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 主要表关系

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：交接时必须补齐

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

P1：上线前应完成

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

P2：持续优化

完成项目台账模块。
根据客户反馈优化手机端信息密度、操作路径和附件体验。
丰富报表口径、导出、权限范围和风险提醒。
评估升级至较新的 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 与操作手册

项目交接文档_20261010.md 18 KB History Raw

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

1. 项目目标与交付范围

2. 工程结构

3. 技术栈与运行地址

4. 本地启动与验证

4.1 前置软件

4.2 数据库初始化

4.3 启动后端

4.4 启动前端

4.5 推荐联调顺序

5. 已实现模块说明

5.1 市场维护

5.2 拜访管理

5.3 学术活动与扫码签到

5.4 付款流程

5.5 管理报表

6. 后端架构与关键约定

6.1 分层约定

6.2 统一接口规范

6.3 全局异常与校验

6.4 MyBatis-Plus

6.5 钉钉接入现状

7. 数据库交接要点

7.1 主要表关系

7.2 数据管理建议

8. 常见问题排查

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

P0：交接时必须补齐

P1：上线前应完成

P2：持续优化

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

11. 现有文档索引

项目交接文档_20261010.md 18 KB

History Raw