# hongkun **Repository Path**: code_87/hongkun ## Basic Information - **Project Name**: hongkun - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-22 - **Last Updated**: 2026-10-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 电子发票管理系统 Hongkun 面向医疗机构的电子票据管理系统，围绕医疗收费票据的基础资料、票据库存、开具与冲红、交付、归档、核销和统计建设。系统采用 Go 后端与 Vue Vben Admin 管理后台，默认使用 SQLite，并预留 MySQL 切换能力。 ## 项目范围 项目功能以 [`docs/01-项目资料/项目功能范围及验收基准.csv`](docs/01-项目资料/项目功能范围及验收基准.csv) 为主要范围清单，并结合 `docs/` 中的票据接口对接、医疗电子票据评估和 WAR 重构核查资料逐步实施。规划中的业务模块包括： - **基础资料**：单位与科室、收费项目、票种、开票点、业务类型、交款人、收费员及相关编码映射。 - **票据业务**：电子票开具、批量开票、红字冲销、转纸票与状态变更、作废及票据信息查询。 - **库存管理**：票据申领、入库与分发、退回或作废、票号段管理和库存预警。 - **交付与归档**：票据通知与文件获取、交付结果跟踪、财务归档和差异核对。 - **查询与运营**：开票明细、票据汇总、收费员统计、失败任务跟踪和监管上报结果查询。 - **平台管理**：用户、角色与权限、组织范围、系统配置及操作审计。 文档中出现的遗留 WAR 模块用于梳理业务和接口线索，不自动代表全部纳入本项目验收。HIS、监管票据平台等外部接口的地址、字段、签名和回执规则，需按接口资料并经双方联调确认。 ### 范围边界 项目资料明确不包含身份证信息采集、读取或核验，也不包含身份证/医保卡读卡器、小程序、专用自助终端及其他可选外设。常规浏览器打印不等于静默打印、专用纸型或打印驱动控制；统一身份、支付和区块链新增对接也不在当前边界内。H5、模板和档案等功能按功能范围清单及最终确认的合同范围实施。 ## 当前代码状态 本地编码支持业务前缀、北京时间日期和持久化流水。历史自动长码可按明确来源清单离线迁移，工具同步本地关联和摘要、保留手填主编码，并在执行前备份；不按前缀自动改数据。操作与限制见[历史自动长编码迁移与关联验收](docs/04-开发验收/历史自动长编码迁移与关联验收.md)。 当前本地后台已覆盖基础资料与业务规则、组织权限、库存领用与开票草稿、冲红申请、核销与销毁、交付任务、归档差异、报表、单位同步本地包和操作审计；各模块的验收边界以[后台功能完成状态与验收索引](docs/04-开发验收/后台功能完成状态与验收索引.md)为准。本地业务流转不等于监管出票或外部发送成功，外部上下行由后续接口方负责。H5 不在当前工作范围，导航已隐藏。 库存与开票已增加本地工作流：期初/入库草稿确认、申领审核、分发接收、未用票申退回补，以及开票草稿、精确金额校验、单位流水幂等和票号预占。各操作均有独立按钮权限与后端范围校验。开票提交目前停留在“待外部平台处理”，正式监管开具、回执及外部红冲、外部归档仍待后续对接（本地冲红申请和本地归档已完成），不能作为已正式出票。详见[票据库存领用与开票开发验收](docs/04-开发验收/票据库存领用与开票开发验收.md)。 单据模板、界面开具模板和票据模板已提供专用管理页，支持字段配置、版本标签、独立启停/默认和JSON导入导出。票据PNG/PDF附件通过私有接口预览下载，JSON不包含附件；界面模板只在新建开票草稿时显式应用。现已补齐历史记录、字段差异比较及恢复为新记录，恢复保留当前标识和发布状态并重验权限、业务引用与文件。旧模板从首次变更前的已知状态开始留痕，不补造过去历史；本地模板不代表监管正式制票。升级需关注009、010及024迁移，历史查看沿用读取权限，恢复沿用编辑及相关文件/默认权限，不自动授予新权限。详见[模板管理开发验收](docs/04-开发验收/模板管理开发验收.md)及[历史专项验收](docs/04-开发验收/三类模板历史版本比较与恢复验收.md)。 ## 技术栈 库存结余表与库存预警已接入真实逐号库存，支持筛选汇总、导出、普通浏览器打印及规则维护。单位有效日期、开票点类型和树形展示、开票点导入导出、用户安全批量导入与归属调整已补齐。预警目前为页面实时计算，未接入外部通知；报表为当前时点统计。接口、权限、升级和验证说明见[库存结余预警与管理补齐验收](docs/04-开发验收/库存结余预警与管理补齐验收.md)。 - **后端**：Go、Gin、GORM；SQLite 使用纯 Go 驱动，无需 CGO；可配置 MySQL。 - **管理后台**：Vue 3、Vben Admin 5、Ant Design Vue、Vite、pnpm。 - **文件存储**：本地存储或 MinIO。 - **部署**：前端构建产物由 Go `embed` 打入服务二进制。 ## 本地运行 ### 后端 默认配置位于 `config.yaml`，HTTP 端口为 `8811`。默认使用本地 SQLite（`data/hongkun.db`）和本地文件存储，无需连接 MySQL 或 MinIO。运行前需安装 Go 1.26 或以上版本。 ```sh go run . ``` 首次启动后，使用一次性初始化接口创建管理员： ```sh curl -X POST http://localhost:8811/api/v1/admin/init \ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"replace-with-a-long-password"}' ``` ### 管理后台开发 需安装 Node.js 22.18 或以上版本，并启用 Corepack；项目锁定 pnpm 11.16.0： ```sh cd web corepack pnpm install --frozen-lockfile corepack pnpm dev ``` Vite 将 `/api` 请求代理到 `http://localhost:8811`。文件上传和访问均走 API 路径。 后端开发模式不要求提前生成前端资源，使用 Vite 的 http://localhost:5173 访问管理后台。首次访问登录页会引导创建管理员，密码至少 6 个字符。前端公共配置位于 `web/apps/web-antd/.env`，本地覆盖写入被忽略的 `.env.local`。API 地址为 `/api`，兼容开发代理和生产同源部署。 后端未找到前端产物时，访问 8811 首页会显示构建提示；API 仍可正常使用。运行 `corepack pnpm --dir web build` 后，也可以通过 http://localhost:8811 访问构建后的页面。 ### 构建 仓库根目录的构建脚本会安装前端依赖、构建管理后台，再编译 Go 服务： ```sh # Windows build.bat # Linux / macOS sh build.sh ``` 默认构建当前操作系统的可执行文件：Windows 为 `app.exe`，Linux/macOS 为 `app`。需要 Linux amd64 产物时使用 `build.bat linux` 或 `sh build.sh linux`。构建脚本先安装锁定依赖、构建前端，再通过 `go build -tags production` 将 `web/apps/web-antd/dist/` 嵌入二进制。 在项目根目录执行 `.\app.exe`（Windows）或 `./app`（Linux/macOS），访问 http://localhost:8811。部署时保留配置文件，并确保数据库和上传目录可写；生产二进制不依赖源码目录中的前端文件。 开发模式读取磁盘上的前端资源；生产模式强制嵌入资源，缺少前端产物会在编译时失败。生成的资源、依赖、日志和数据库均由 Git 忽略。 ## 配置概要 编辑 `config.yaml` 或通过 `HONGKUN_CONFIG` 指定配置文件。数据库使用 `database.driver` 选择 `sqlite` 或 `mysql`；文件存储使用 `upload.driver` 选择 `local` 或 `minio`。切换数据库只会切换连接目标，不会自动迁移另一数据库中的既有数据。 生产部署应使用独立配置或密钥管理注入 JWT、MySQL、MinIO 凭据，并限制 CORS 来源；不要将生产密钥提交到仓库。 ## 已提供的基础 API - `GET /api/health`、`GET /api/v1/health` - `GET /api/v1/admin/check`、`POST /api/v1/admin/init` - `POST /api/v1/auth/login` - `GET /api/v1/user/profile`、`PUT /api/v1/user/password` - `GET/POST /api/v1/admin/users`、`PUT/DELETE /api/v1/admin/users/{id}` - `GET /api/v1/user/access`、`GET /api/v1/user/access-options` - `GET/POST /api/v1/admin/access/{kind}`、`PUT/DELETE /api/v1/admin/access/{kind}/{id}` - `GET/POST /api/v1/admin/catalog/{kind}` - `PUT/DELETE /api/v1/admin/catalog/{kind}/{id}` - `POST /api/v1/upload`、`GET /api/v1/files/{key}` 组织权限 API 的 kind 支持 `organizations`、`departments`、`points`、`roles` 和 `menus`；这些资料不再通过通用 catalog 接口维护。组织权限页面支持自定义角色和勾选功能树，查询、新增、编辑、删除、启停及用户授权、密码重设、角色授权分别校验按钮权限。数据结构、授权范围、专用操作接口和旧数据升级说明见 [数据库结构与权限设计](docs/02-设计与接口/数据库结构与权限设计.md)。 其他基础资料 API 支持 `revenue-items`、`invoice-types`、`business-types`、`code-mappings`、`payers`、`cashiers` 和 `archive-differences`。三类模板使用 `/api/v1/admin/templates/{kind}` 专用接口，库存预警使用 `/api/v1/admin/stock-warnings`。管理接口使用 Bearer Token；列表支持分页、搜索及相关筛选。 医疗票据明细、开具汇总及收费员票据使用情况表使用 `/api/v1/admin/invoice-reports/{kind}` 专用接口。明细与汇总查询真实本地开票记录，区分草稿、待外部平台处理及已取消，支持业务日期或创建日期、日/月/开票点/票种汇总；金额以分单位字符串传输。收费员表按开票点及票种展示当前库存，不代表个人领用或历史日期结存。票据销毁申请使用 `/api/v1/admin/stock-destructions`，支持草稿、提交锁票、审批本地销毁及驳回/取消释放库存；不代表监管核销成功。新操作权限须显式授予，手工迁移环境需执行对应的011脚本。详见 [三张报表与销毁申请开发验收](docs/04-开发验收/三张报表与销毁申请开发验收.md)。 票据核销数据上报与冲红票据使用 `/api/v1/admin/stock-writeoffs`、`/api/v1/admin/red-invoices` 专用接口。核销按真实批次、最新终态流水和截止日期归集已使用/已销毁票号，提交生成快照并防重复占用，取消释放占用且保留历史；不变更库存终态。冲红支持原票关联草稿、精确全额负数金额、Excel 预览原子导入和原子批量提交，提交须原票已正式出票且库存为已使用。两个模块均只进入本地待外部处理，不请求上下行接口、不回补库存、不退款、不生成正式红票；新增权限须显式授予，手工迁移环境需执行对应的 012、013 脚本。详见 [核销上报与冲红后台开发验收](docs/04-开发验收/核销上报与冲红后台开发验收.md)。 补发监制与通知明细查询／票据交付使用 `/api/v1/admin/supervision-tasks`、`/api/v1/admin/delivery-tasks` 专用接口，支持真实原票关联、草稿编辑回读、筛选导出、历史和本地任务状态流转。待外部处理原票仅能排队状态回查，可预先保存交付草稿；补发监制或交付排队须原票已正式开具且库存使用关系一致。交付另有最多200条的原子批量排队及受权限控制的失败重试配额重置，手机号邮箱在列表、导出中脱敏。当前没有传输通道、实际发送或公开取件链接；本地排队次数与实际请求次数分开，不修改库存。手工迁移需依数据库类型执行014、015脚本，新增按钮不自动授权。详见 [补发监制与通知交付后台开发验收](docs/04-开发验收/补发监制与通知交付后台开发验收.md)。 电子票据归档检索与归档差异处理已替换为专用本地后台：真实正式原票关联、一票一档快照、私有PNG/PDF补传与完整性校验、本地归档、历史差异核对、失败重试、信息及次数重置、原子批量归档、查询导出和处理历史。仅已正式出票且库存关系一致的原票可归档，不修改原票和库存，不接外部档案系统。手工迁移执行所选数据库的016脚本，新操作按钮需显式授权；旧通用JSON不转换为正式档案。详见[电子票据归档与差异处理开发验收](docs/04-开发验收/电子票据归档与差异处理开发验收.md)。 票据补录明细查询已使用独立本地明细表和专用只读页面，支持原业务日期／北京时间补录日期、单位、开票点、票种及代码号码等筛选、详情、精确全量合计、导出和普通浏览器打印。校验码仅授权详情可见；普通开票及旧通用JSON不自动视为补录。本轮不提供补录录入、导入或外部数据接入，没有真实补录数据时显示为空。手工迁移执行所选数据库017脚本，导出／打印需显式授权。详见[票据补录明细查询开发验收](docs/04-开发验收/票据补录明细查询开发验收.md)。 单位同步管理已提供数据更新／数据上报两个专用本地页签，支持单位组织资料包的全量与增量、独立版本游标、依赖校验、幂等任务、故障回滚、失败重试、镜像查看和包／日志下载。数据更新只写独立暂存镜像，上报只生成本地包，不覆盖现有组织授权、不请求外部平台。当前包范围为单位、部门和开票点，正式同步目标、协议及其他数据范围仍待确认。手工迁移执行所选数据库018脚本，执行和下载等新按钮需显式授权。详见[单位同步管理本地后台开发验收](docs/04-开发验收/单位同步管理本地后台开发验收.md)。 业务类别已补齐单位内唯一默认类别、默认渠道、渠道必填、默认收费项目及数量；开票可显式应用默认值，保留已录入内容，并在保存及提交时执行引用、票种和渠道校验。默认规则与启用模板冲突、资料变更导致规则失效时会拒绝操作。配置复用现有资料字段，无新增迁移或权限，不接外部接口。详见[基础信息业务规则开发验收](docs/04-开发验收/基础信息业务规则开发验收.md)。 后台修改冲突现提供保留输入、只读查看最新记录及确认放弃后重新加载；状态操作不自动重放。库存结余和预警导出、打印取查询与输出权限范围交集。各本地模块过期版本统一返回409，前后端需同步更新并刷新浏览器。详见[冲突与角色流程验收](docs/04-开发验收/角色菜单可用性与库存版本确认验收.md)。 后台编辑及导入预览现增加未保存内容离开保护，取消离开保留输入；首页增加按模块查询权限统计的本地待办与库存摘要，并可进入对应筛选列表。统计不代表正式出票或外部处理结果。无新增迁移，需同步更新前后端并刷新页面。详见[完成状态与本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 ## 数据库迁移 角色菜单按各模块读接口能力支持部门及开票点范围，单位专属功能保持限制；库存确认、审批及接收新增所见版本校验，过期操作不改变库存，当前版本重复处理保持幂等。无新迁移或权限，更新前后端后须刷新页面。详见[角色菜单可用性与库存版本确认验收](docs/04-开发验收/角色菜单可用性与库存版本确认验收.md)。 基础资料与组织权限维护已统一增加过期修改保护，开票提交和取消也需确认用户看到的草稿版本；批量用户调整逐条检查版本并整体回滚。无新增迁移，升级须同时更新前后端并刷新页面。详见[统一过期修改保护与开票版本确认验收](docs/04-开发验收/统一过期修改保护与开票版本确认验收.md)。 基础信息对照增加本地批量编码解析与版本校验；菜单管理增加缺失项初始化、移动排序和受引用保护的原子批量删除；新建开票可查询常用交款人并填入空白名称。沿用现有权限，无新迁移，不对接外部上下行接口。详见[基础对照菜单与开票联动开发验收](docs/04-开发验收/基础对照菜单与开票联动开发验收.md)。 后台操作审计查询位于“用户与权限”，支持单位、操作人、模块、日期及结果筛选，独立授权的详情与CSV导出。新操作保存单位和账号快照，历史不明确归属仅平台管理员可见；失败写请求只记录安全路由模板和状态码。页面及接口只读，不接外部日志平台；手工升级需执行所选数据库020迁移并显式授权。详见[后台操作审计查询开发验收](docs/04-开发验收/后台操作审计查询开发验收.md)。 医疗票据开具明细、开具汇总和收费员使用情况表已补齐本地交易渠道及现金/转账/其他收款分项，支持部门、渠道和操作账号汇总，以及收费员操作账号业务追溯。旧记录的缺失分项单列为“未登记”，当前库存与账号业务统计分开，已使用票据金额仅计算一致的正式原票关联。报表、全量导出和打印沿用独立权限与范围交集，不接支付/HIS或监管接口。手工升级需执行所选数据库019迁移；详见[医疗票据三张报表本地功能补齐验收](docs/04-开发验收/医疗票据三张报表本地功能补齐验收.md)。 默认启用 GORM 自动迁移。若设置 `auto_migrate: false`，请按所选数据库执行 `migrations/` 中对应的 SQLite 或 MySQL SQL 脚本。SQLite 默认文件为 `data/hongkun.db`；本地上传文件默认保存在 `uploads/`。 ## 项目资料 - [后台操作说明](docs/03-操作指南/后台操作说明.md)：按角色说明资料准备、库存开票、财务任务、权限及本地状态、失败处理。 - [后台接口交接文档](docs/02-设计与接口/后台接口交接文档.md)：当前管理接口和代码入口、状态/库存约束、后续外部接入要求及待确认清单。 - `docs/01-项目资料/项目功能范围及验收基准.csv`：功能范围与验收场景。 - `docs/02-设计与接口/票据服务接口开发对接文档.html`：本平台与监管票据服务的接口线索及对接约定。 - `docs/01-项目资料/医疗电子票据功能评估报告(2).html`：业务复杂度、实施建议和待确认事项。 - `docs/01-项目资料/WAR包全量重构范围核查.html`、`docs/01-项目资料/WAR重构功能补充核对.csv`：遗留系统功能覆盖差异与范围边界。 基础资料和冲红导入已补齐本地只读业务预检、逐行错误提示及错误CSV清单下载。正式确认在事务内重新校验，任一行失败整批不写入；冲红只生成本地草稿。无新增迁移，外部接口和部署工作不在本轮范围。详见[导入专项验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 用户、开票点和期初库存导入现支持本地只读业务预检、逐行错误提示和错误CSV下载，正式导入重检并整批回滚。用户仅创建停用未授权账号，期初新增仅建草稿；同号同内容重试不重复入库。无新增迁移。详见[本轮专项验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 医疗报表、补录、库存结余/预警、审计及模板查询现区分失败与成功空结果并提供重试；三类模板配置导入支持只读业务预检、逐项错误清单及事务重检回滚。无新增迁移。完成后的本地后台后续计划见[验收索引及计划](docs/04-开发验收/后台功能完成状态与验收索引.md)。 冲红批量提交、批量归档现支持只读逐项预检、失败定位与错误清单，版本变化需明确核对后重试，正式操作继续整批回滚。交付/补发监制及归档列表补齐读取失败提示与重试。无新增迁移，外部接口和部署不在本轮范围。详见[本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 冲红、核销、销毁页面已补齐读取失败提示与原地重试，失败或条件变化后禁止旧结果操作；新增三条隔离本地API跨模块验收，覆盖规则库存开票、合成原票后续归档、销毁核销及角色范围。外部接口和部署不在范围内。详见[验收记录](docs/04-开发验收/后台功能完成状态与验收索引.md)。 库存工作流、开票及六类基础资料维护现补齐读取失败提示与原地重试，关联读取整体成功后才开放旧结果操作，编辑重试保留草稿；常用交款人及对照校验同样支持失败重试。无后端规则或迁移变更。详见[本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 单位同步本地管理与模板维护剩余读取入口已补齐失败提示及原地重试，覆盖编辑依赖、镜像、配置/文件预览与下载；重试保留草稿，保存后回读失败只重读确认，避免重复保存。无新增迁移，不对接外部接口、不安排部署。详见[本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 组织与权限维护已补齐列表、编辑依赖、开票点导出与单位打印的读取失败提示及重试，本地业务追溯支持当前目标失败恢复；关闭或离开后旧响应失效。无后端规则或迁移变更，外部接口和部署不在范围内。详见[本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 库存预警规则编辑已补齐详情/选项失败重试、草稿保护及保存后只读确认；首页与审计页面缓存离开使旧请求失效，重新进入重读权限和数据，详情及导出同样受保护。无新增迁移，外部接口和部署不在范围内。详见[本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 医疗报表、补录查询、库存结余与库存预警列表已补齐缓存恢复和导出打印请求隔离，重新进入重读权限及选项，保留合法筛选；旧响应和旧加载结束处理不影响新请求，离开关闭未准备好的打印窗口。无新增迁移，外部接口和部署不在范围内。详见[本轮验收](docs/04-开发验收/后台功能完成状态与验收索引.md)。 单位同步补齐首次加载中离开后的缓存恢复；模板配置和单位日志导出支持忙碌提示与重复点击保护，列表重查取消旧输出。第一批隔离浏览器流程已完成，覆盖基础资料、未保存保护、模板与同步日志实际下载、本地同步处理、页面返回及审计核对；后续角色及库存开票归档流程仍分批验收。详见[验收记录](docs/04-开发验收/后台功能完成状态与验收索引.md)。 第二批隔离浏览器验收已覆盖单位/部门/开票点只读范围、期初申领分发接收、开票本地预占待处理，以及合成原票的缺文件失败恢复、文件补传和本地归档。修复追溯记录时间统一北京时间，132项前端回归及后端检查通过；不代表外部出票或全部授权组合验收。详见[验收记录](docs/04-开发验收/后台功能完成状态与验收索引.md)。 第三批独立浏览器验收已覆盖申退拒绝及回总库、销毁驳回重提批准、核销快照与取消、冲红和交付本地提交及取消、关联追溯和冲红断线重试。修复交付任务及核销明细的时间显示，统一北京时间；134项前端回归及后端检查通过。未操作现有业务数据，不涉及外部接口和部署。详见[验收记录](docs/04-开发验收/后台功能完成状态与验收索引.md)。 第四批独立浏览器验收覆盖基础资料、期初库存、冲红、用户、开票点与单据模板导入及错误CSV实际下载，并验证导入并发冲突整批拒绝、冲红批量版本恢复和归档批量缺文件/版本恢复。修复基础资料错误响应混淆数据项序号与文件行号；普通打印入口及数据读取已核对，库存打印预览由用户辅助确认正常，未验收实际出纸或驱动。详见[验收记录](docs/04-开发验收/后台功能完成状态与验收索引.md)。 第五批隔离浏览器验收已覆盖业务人员申领、单位审核员审批分发、开票点接收及开票草稿/本地提交，验证提交撤权、点范围收缩、账号停用与归档文件/导出撤权。修复归档及模板正常PDF预览空白，改为本地打包PDF.js逐页渲染，PNG及PDF/PNG实际下载一致性通过。无新增迁移或权限；151项前端回归及后端检查通过，需更新前端产物并刷新页面。详见[第五批验收记录](docs/04-开发验收/后台功能完成状态与验收索引.md)。