You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5.2 KiB
5.2 KiB
天天护工平台：项目理解（基于仓库源码）
1. 项目定位
- 这是一个医院陪护业务管理系统，核心是围绕“订单-护工-床位-结算”闭环运行。
- 系统支持多角色协同：后台管理员（Admin）、客户端用户（Customer）、项目管理端（Manager）、护工端（Worker）。
- 业务目标不是单纯下单，而是包含排班指派、每日子订单、自动扣款、退款、统计分析等运营链路。
2. 技术架构理解
- 后端：Laravel 7 + PHP 7.2.5+（
composer.json）。 - 认证：
admin使用 session guard。customer/manager/worker使用 JWT guard（config/auth.php）。
- 权限：
- 管理后台使用
authorize:admin+rbac:admin。 - RBAC 规则按 URL 前缀匹配权限（
app/Http/Middleware/Rbac.php）。
- 管理后台使用
- 前端形态（仓库内可见）：
- 管理后台模板资源：
public/hyper。 - 客户端 H5 静态资源：
public/h5、public/h5_test。 - 数据看板页面：
public/dashboard。
- 管理后台模板资源：
- 前端构建：Laravel Mix + Vue2 + Bootstrap4（
package.json）。
3. 路由与端划分
路由主要集中在 routes/web.php，按前缀拆分：
/admin/*：后台管理，包含权限/角色/项目/产品/护工/经理/订单/统计/支付账户管理。/customer/*：用户端，下单、患者管理、可用护工查询、充值、评价等。/manager/*：项目管理端，订单处理、派单、改价、结算、充值退款、统计等。/worker/*：护工端，登录、个人信息、订单列表/详情。/swagger/*：接口文档相关入口。
备注：routes/api.php 仅保留 Laravel 默认示例接口，业务 API 基本走 web.php。
4. 核心业务对象
从模型层看，业务主干是：
- 订单主表：
Orders（状态机、总价、关联患者/客户/护工/床位/产品）。 - 订单日明细：
OrderItems（按服务日生成、用于日扣款与工资结算）。 - 资源对象：
Project/Building/Area/Room/Bed（医院空间层级）。 - 人员对象：
Paramedic（护工）、Manager（项目管理人员）、Customer（下单用户）。 - 交易对象：
Balance/Recharge/Refund。 - 配置对象：
Product/ProductItems/ProductParamedicLevel/Factor/FactorItems（服务项和计价因子）。
5. 我理解的关键业务流程
5.1 下单与执行
- 客户端按项目获取产品、病区床位、可用护工。
- 创建订单后，订单在状态流转中推进：
待确认(0)->待指派(10)->进行中(20)->已完成(100)（app/Models/Orders.php）。
- 管理端在进行中订单上执行派单、改价、变更等操作。
5.2 每日子订单与扣款
- 定时任务每分钟执行
order-items:create-daily，为服务日生成order_items。 - 下午 14:00-23:59 每分钟执行自动扣款（
OrderItems::autoCheckout()），并记录日志。 - 子订单
paid_at决定是否已扣款及工资归属月份（OrderItems::getPaidStatusAttribute()）。
5.3 退款链路
- 每分钟执行自动退款逻辑（
Refund::autoRefund()），同时支持管理端按订单手工充值/退款。
5.4 审计与追踪
Orders在更新时会对变更字段写入order_audit（批次+操作人），用于追踪关键字段修改历史。
6. 数据隔离与权限边界
Orders等模型挂了AdminProjectScope全局作用域：当 admin 账号配置了project_ids，查询会自动按项目过滤。- 管理后台权限为“角色 -> 权限 URL 前缀”模型，核心在
spatie/laravel-permission之上实现。 - 另有导出权限的角色检测逻辑（
CommonModel::checkExport()）。
7. 事件与可扩展点
当前事件总线已有：
FactorSaved、ManagerSaved、AdminSaved、ProjectSaved、ProductSaved、RechargeSucceed、OrderAssigned。
这说明项目采用了“核心流程 + 事件监听补充动作”的演进模式，便于后续插入通知、同步、统计等旁路能力。
8. 对当前代码状态的判断
- 这是一个长期维护中的业务系统，不是新脚手架；有较完整的运营功能（统计、导出、日志、自动任务）。
- 代码里存在历史兼容痕迹（例如大量
whereRaw、web.php承担 API、注释中有 TODO），但主线流程清晰可维护。 - 仓库内已有多个“说明文档”文件，建议后续统一维护一份“权威架构文档”，减少信息分散。
9. 待确认事项（建议下一步澄清）
- 多端前端代码是否全部在本仓库（当前可见主要是编译产物，源工程边界需要确认）。
- 支付参数与回调验签的生产部署策略（当前看账户数据在库内配置+代码调用）。
- 子订单自动扣款规模上限与失败重试策略是否满足当前业务量。
routes/web.php中 API 与后台页面耦合是否要逐步拆分。
10. 建议的文档化落地
建议后续把文档分为三层：
01-业务流程.md：从下单到结算的时序图和状态机。02-技术架构.md：鉴权、权限、任务调度、事件机制。03-运维手册.md：定时任务、支付回调排障、日志定位路径。
本文档依据当前仓库源码整理，重点描述“已在代码中可验证”的理解，供后续开发与沟通对齐。