Skip to content

金刚员工端完整模块与逻辑 ​

本页只写金刚小程序员工端。员工端是服务履约入口,重点是登录、接单、服务记录、能力区域、档期、钱包、入驻、保险、简历和队员管理。

流程总览见:员工端业务流程总览;系统边界和数据流见:员工端系统架构与数据流。

员工端入口 ​

模块页面API后端主要数据
登录和账号pages-staff/home/*、pages/login、pages-login-auxstaff-auth.jsservice_staff_login_controller.py、service_staff_login_service.pyservice_staff、internal_user、openid 绑定
服务首页pages-staff/home/index.vuestaff-order.jsstaff_order_controller.py、staff_order_service.pyorder、order_logs、order_waiter、standard_staff_dispatch_*
服务记录pages-staff/service/record.vuestaff-order.jsstaff_order_controller.pyfile_*、order_logs、订单服务记录字段
我的pages-staff/home/my.vuestaff-wallet.js、staff-auth.js、insurance.js、employee-relation.js多个员工端 controller员工钱包、保险、公众号绑定、用工关系
设置pages-staff/home/settings.vuestaff-auth.jsservice_staff_login_controller.py员工登录态、默认公司
能力申请pages-staff/capability/index.vuestaff-capability.jsstaff_capability_controller.py、staff_capability_service.pystaff_service_capability、staff_service_capability_audit、staff_platform_product
服务区域pages-staff/capability/index.vuestaff-capability.jsstaff_capability_controller.pystandard_staff_service_region、staff_service_region_application
档期休息pages-staff/availability/index.vuestaff-availability.jsstaff_availability_controller.py、staff_availability_service.pystaff_rest_date、standard_staff_schedule_lock、order
员工钱包pages-staff/wallet/index.vuestaff-wallet.jsstaff_wallet_controller.py、staff_wallet_service.pystaff_wallet_account、staff_wallet_ledger、staff_withdrawal_application
入网开户pages-staff/yeepay-innet/*、pages-staff/select-account.vueyeepay-innet.js、staff-account-application.jsyeepay_innet_controller.py、staff_account_application_controller.pyyeepay_innet_record、staff_withdrawal_application
队员管理pages-staff/apprentice/index.vue、pages-staff/station-contact/index.vuestaff-apprentice.js、staff-station-contact.jsstaff_apprentice_controller.py、staff_station_contact_controller.pyservice_staff.mentor_staff_id、staff_mentor_province_binding
简历和阿姨资料pages-staff/resume*、pages-aunt-resumestaff.js、aunt-resume.js、aunt.js、ai-register.jsstaff_controller.py、aunt_controller.py、resume_share_controller.pyaunt、aunt_detail、aunt_certificate、service_staff
保险购买pages-staff/insurance-purchase.vueinsurance.jsinsurance_controller.pyinsurance_record、contract_insurance
信用核验pages-staff/credit-check.vueaunt.js、payment.jsaunt_*_service.py、payment_service.pycredit_query_record、核验结果表
招聘和发展pages-staff/development-poster、pages-staff/recruit-poster.vuestaff-development-channel.js、staff.jsstaff_development_channel_controller.py、store_recruit_controller.pydevelopment_channel_scan_log、store_recruit_code

登录和身份逻辑 ​

员工端支持密码、短信、微信、手机号快速授权和公众号绑定。后端统一从员工 token 解析当前员工,再决定员工可访问的门店或公司。

能力逻辑
密码登录手机号和密码校验后返回员工身份、门店、token。
短信登录先发验证码,再用手机号和验证码换 token。
微信登录根据 openid 找员工;没有绑定时要求手机号绑定。
多公司访问validateCompanyAccess 校验员工是否能进入目标公司,setDefaultCompany 保存默认公司。
员工和门店账号切换switchToStaffAccount、switchToStoreAccount 在员工身份和管理端身份之间切换。
公众号绑定生成带参二维码,扫码后统一绑定员工微信公众号 openid,用于服务通知和测试推送。

排查登录失败时先查员工是否有效,再查 openid 和手机号绑定,不要只看小程序缓存。

退出与身份切换的请求时序 ​

退出成功后清空员工资料,会触发仍挂载页面的状态监听。staff-tabbar 在未登录时必须停止查询站长角色,并清空角色展示;getStationRole 在没有员工 token 时直接停止请求,“我的”页退出后也停止刷新。已发出的角色请求返回时,还需核对是否仍属于当前登录身份,旧身份结果不得恢复已清除的角色或覆盖新身份。

请求层处理认证失败时,应比较请求发出时与当前的认证凭证。getStaffInfo 和 tokenManager 的凭证校验还须记录起始 token 与 role,在成功及认证失败返回后均核对是否仍为同一会话。旧请求迟到返回成功,不得重新写入缓存员工资料;退出或切换身份前的旧认证失败,不再弹出 Not authenticated 等提示,也不得影响退出收尾或清除当前新身份。当前登录身份真正返回认证失败时,仍按原登录失效流程处理,不能全局忽略认证错误。

设置页退出流程在清理本地登录资料后,应独立完成返回登录页,提示展示失败不能中断退出收尾。退出接口本身返回认证失败时仍完成本地退出,避免已失效凭证阻止用户离开。验收覆盖正常退出、凭证已失效退出、退出时仍有员工资料请求、旧角色及资料请求迟到成功或返回401、切换后旧认证失败、退出后重新登录,以及当前会话真实401。本地H5验证前完整刷新并重新打开页面,避免旧页面实例干扰判断;本次只修改前端,小程序由用户自行发布,不以接口退出成功代替页面完整验收。

员工主数据和身份字段 ​

字段组数据来源影响
基础身份service_staff.id、uuid、mobile、real_name、company_id、store_id、store_uuid登录、订单权限、跨门店订单查询。
微信身份wx_openid、wx_unionid、wx_bind_time小程序微信登录和绑定。
公众号身份wx_official_openid、wx_official_bind_time、昵称头像订单通知、服务提醒、测试推送。
账号状态status、is_delete、is_bind_wx、is_default_company是否可登录、是否可用默认公司。
接单资格is_allow_rob、work_type、job_type、is_part_time_job、保险起止时间是否进入可接单/派发范围。
归属和师傅mentor_staff_id、own_user_id、copy_source_*队员管理、入驻来源、复制来源排查。
用工消息employee_relation_status、employee_bind_time、employee_unbind_time员工端“用工消息通知”绑定状态。

同一手机号可能在多个门店有员工身份。员工订单列表支持跨门店查询,后端会先按手机号找到可访问员工身份,再按订单关系验证权限。

服务首页和接单 ​

员工端服务首页围绕订单列表、统计、接单、拒单、开始服务、完成服务、补价支付展开。

操作前端方法后端接口核心逻辑
查询订单getStaffOrderList、getStaffOrderStatistics/api/v1/staff-order/getOrderList、getOrderStatistics按员工身份、订单状态和时间筛选待处理、进行中、已完成。
接单acceptStaffOrder/acceptOrder校验员工对订单有权限,更新订单或派发 attempt 状态,写订单日志。
拒单rejectStaffOrder/rejectOrder写拒绝原因;标准单触发候选顺延或转人工。
状态更新updateStaffOrderStatus/updateOrderStatus按业务状态推进,禁止非法跳转。
开始服务startService/startService上传服务前凭证,订单进入服务中,必要时同步安心生活或渠道方。
上传服务前图片uploadServiceBeforeImages/uploadServiceBeforeImages只补充服务前凭证,不直接完成订单。
完成服务endService/endService校验当前状态,保存服务后图片、签名和说明,释放档期锁,触发结算任务和开发奖金。
订单详情页面内详情弹层和接口/getOrderDetail回显客户、地址、服务、补价、凭证和当前操作按钮。

关键状态:

状态员工端含义
待确认员工需要接单或拒单。
待服务已确认,等待到服务时间。
服务中已开始服务,允许上传服务后凭证并结束。
已完成员工已完成服务,后续进入结算或评价。
已取消不可再服务,需看取消来源和退款/释放逻辑。

后端状态机 ​

员工端状态更新由 StaffOrderStatusManager 限制:

当前状态允许下一步
20 派单待确认30 已拒绝、40 已派单
40 已派单50 执行中
50 执行中60 开始服务
60 开始服务80 已完成
70 服务结束80 已完成,兼容旧流程

acceptOrder 会先调用标准单派发服务标记 attempt 已接收;如果 attempt 已超时或已被处理,会提示刷新。rejectOrder 会先写拒绝,再调用 reject_and_reassign,标准单会继续顺延候选或进入人工处理。

完成服务后会继续触发:

  1. StandardStaffScheduleService.complete_schedule 释放或完成档期锁。
  2. StandardOrderSettlementService.enqueue_order_completion 创建服务奖金结算任务。
  3. DevelopmentBonusService.enqueue_order_completion 创建客户开发奖金任务。
  4. 尝试通知云平台和渠道方订单已完成。旧小羽佳直连接口已废弃,不作为交接主线。

补价和支付 ​

员工端可以对订单创建补价、查询补价记录、处理现金支付、客户余额支付和线上支付。

场景逻辑
创建补价员工填写补价金额、原因、说明,后端写 order_additional_payments。
现金支付员工确认已收现金后,后端标记补价成功并写日志。
客户余额支付后端校验客户余额,扣减后更新补价状态。
线上支付创建支付订单后轮询状态,支付回调成功后更新补价。
查询状态员工端刷新补价记录,避免重复收款。

补价问题排查要同时看补价表、支付订单、订单日志和员工端轮询状态。

员工端补价必须先校验当前员工对订单有权限。支持的 payment_type:

类型处理方式
cash员工确认已收现金,补价记录直接标记已支付。
balance扣客户余额后更新补价支付状态。
scan_pay创建支付订单,客户扫码支付。
yeepay创建易宝支付订单或二维码,回调后更新状态。

补价记录的支付状态不要由前端本地判断,必须以后端查询结果和支付回调为准。

服务记录 ​

pages-staff/service/record.vue 是员工结束服务时的关键页面,主要处理:

  1. 至少上传一张服务后照片,可补传服务前图片。
  2. 上传客户电子签名。
  3. 按需填写服务说明。
  4. 调用结束服务接口。
  5. 回到服务首页刷新订单状态。

服务记录页不能绕过订单状态。后端会校验当前订单是否允许开始或结束服务,避免已取消、已完成或不属于当前员工的订单被重复处理。

服务记录页上传逻辑:

内容要求
服务前照片startService 必填;uploadServiceBeforeImages 可后续补传。
服务后照片endService 必填,至少一张有效上传文件,写服务后照片文件组。
客户签名endService 必填,至少一份有效上传签名,写电子签名文件组。
服务说明可选文本,随结束服务写入。

图片和签名通过文件服务创建文件组,再把文件组 ID 写回订单。排查图片丢失时先查文件组和订单字段,不要只看页面缓存。

前端提交前检查两项凭证,后端在完工副作用前再次校验,拒绝空列表或空文件地址。缺失时不推进订单状态、不释放本次档期、不触发完工结算及通知。员工不能通过通用状态更新接口直接完成订单;状态为 60 或旧流程 70 的订单统一通过服务记录页提交凭证后完成。已完成历史记录不批量补写。配套发布时应先确认新版小程序可提交两项凭证;旧版即使未显示必填提示,也必须提交完整凭证才能通过后端校验。

能力、区域和档期 ​

服务能力 ​

员工能力由工种、产品和审核状态共同决定。

数据说明
staff_service_capability员工已经生效或申请中的工种能力。
staff_service_capability_audit能力审批记录。
staff_platform_product员工可承接的平台标准产品。
platform_product可申请产品来源。

员工提交能力申请后,不一定立即具备新订单承接资格。需要站长或运营审批;标准单由门店负责人在家政广场抢单后派给本店有效员工,员工端不能直接抢单。

能力接口约束:

接口约束
/staff-capability/products按 work_type 查询可申请平台产品。
/staff-capability/applications一次最多提交 100 个产品。
/staff-capability/regions查看已生效区域和待审批申请。
/staff-capability/region-applications一次提交 1-50 个区域;扫码员工直接替换生效,非扫码员工生成待审批申请。

服务区域 ​

服务区域用于判断员工是否覆盖订单地址。系统通过招工扫码记录识别扫码员工:扫码员工提交后直接同步两套生效区域并写入审计;非扫码员工生成区域变更申请,由直属站长或运营审批后生效。

休息日和档期 ​

staff_availability_service.py 读取具体休息日和订单档期锁:

  1. 具体休息日来自 staff_rest_date。
  2. 已有订单来自 standard_staff_schedule_lock 和 order。
  3. 设置休息日时如果当天已有进行中订单,会拒绝设置。
  4. 取消休息日也会检查冲突,避免影响已锁定服务。

历史 service_staff_ext.rest_days 只保留原始资料,不再返回给员工端,也不参与候选、抢单、派单或档期锁校验。

档期接口默认查从今天起未来 90 天,一次保存休息日最多 62 天。冲突检查先看 standard_staff_schedule_lock 的 ACTIVE 锁,再看 order_waiter + order 中 20/40/50/60/70 等未完成订单。

钱包和提现 ​

员工钱包汇总两类收入:标准单服务奖金和开发奖金。

数据说明
standard_order_settlement_task服务奖金结算任务,可能处于处理中、冻结、成功、失败。
staff_wallet_account员工钱包账户余额。
staff_wallet_ledger开发奖金、提现、历史只读收入、服务奖金等流水。
staff_withdrawal_application提现申请、审核、处理中、完成、失败。

钱包总览会拆分:

字段含义
可提现已解冻且可发起提现的收入。
冻结中未入网、人工冻结或开发奖金配置冻结期;默认完成后冻结 2 小时。不含已提交的钱包提现申请。历史保险冻结只按遗留状态排查,新标准单结算不因保险缺失冻结。
处理中易宝分账处理中的服务奖金、提现中的开发奖金,以及已提交审核/打款的钱包提现申请。
累计已提现仅统计已完成提现的实际到账金额,首页和钱包页统一使用 withdrawn_amount;驳回、失败及处理中的申请不计入。
历史只读老订单的历史收入,只展示不参与新钱包计算。

员工端接口 GET /api/v1/staff-wallet/summary 字段对应关系:

返回字段展示项
available_balance钱包可提现余额
frozen_balance冻结金额 =(钱包账户冻结余额 − withdrawing_amount,小于 0 按 0)+ 服务奖金冻结 + 开发奖金冻结
withdrawing_amount处理中提现金额 = staff_withdrawal_application 中 PENDING、APPROVED、PROCESSING 的 apply_amount 合计
withdrawn_amount累计已提现 = staff_withdrawal_application 中仅 COMPLETED 的 COALESCE(actual_amount, apply_amount) 合计,历史记录无实际金额时回退申请金额;首页与钱包页统一使用,排除驳回、失败及 PENDING、APPROVED、PROCESSING 等未完成记录
processing_balance分账/提现中 = 易宝分账中 + 开发奖金提现中 + withdrawing_amount
arrived_amount兼容旧客户端保留:service_arrived + development_paid + account.available_balance,即成功分账的服务奖金 + 已支付开发奖金 + 钱包账户实际可用余额;不使用 total_income 减提现金额推算,避免把冻结收入算为已到账
total_income累计收入

首页 pages-staff/home/my.vue 与钱包页 pages-staff/wallet/index 的“累计已提现”均读取 withdrawn_amount。旧 arrived_amount 仅保留兼容,不作为新版累计已提现数据源。后端修正兼容字段中的冻结误计;UI 代码交由用户自行发布小程序,本次不修改账户余额、入账或提现流水。

提现时后端会校验云平台配置的最低提现金额、是否已有处理中提现、可用余额是否足够,并写幂等流水。

员工钱包展示不是只读 staff_wallet_account。当前真实库中员工钱包账户为空,但页面仍会聚合以下数据:

数据来源展示位置
standard_order_settlement_task服务奖金冻结、处理中、已到账、总额。
development_bonus_task开发奖金可用、冻结、提现中、已支付。
staff_wallet_ledger开发奖金、提现、失败/驳回等流水。
order_waiter + order历史服务收入,只读展示,不计入可提现。
yeepay_innet_record入网状态,决定是否可提现。

提现申请规则:

  1. 金额必须大于 0,且不低于 standard_order_rule_config.MIN_WITHDRAWAL_AMOUNT;未配置时按服务默认值。
  2. 单笔提现金额不得超过 1000 元;按订单勾选时以本次勾选奖金合计计算。
  3. 易宝个人入网必须完成,否则不能提现开发奖金。
  4. 必须存在员工钱包账户,且可提现余额足够。
  5. 同一员工已有 PENDING、APPROVED、PROCESSING 提现时禁止再申请。
  6. 申请后可用余额减少、钱包冻结余额增加,写 staff_withdrawal_application 和 staff_wallet_ledger,幂等键为提现单号;员工端展示为"分账/提现中"。

队员和站长 ​

队员管理以 service_staff.mentor_staff_id 快照和省级师傅绑定为准,不再依赖旧师傅名单池。

能力说明
队员列表省级负责人查看直属队员、工种、状态、接单情况、入网状态。
接单开关负责人可以更新队员是否参与派发。
员工积分负责人可调整队员员工积分,并记录原因。
能力审批站长审批直属队员工种和产品能力。
区域审批站长审批直属队员服务区域。
站长联系方式员工维护对队员展示的微信号和二维码。

员工“我的”页只有满足省级负责人条件才展示“我的队员”和“站长微信”。队员管理接口要求当前员工是直属负责人,否则不能查看或审批别人的能力/区域。

我的页入口总表 ​

pages-staff/home/my.vue 是员工端二级能力入口,排查员工说“找不到功能”时先看这里。

入口页面/接口逻辑
我的钱包/pages-staff/wallet/index、staff-wallet.js展示可提现、冻结、处理中、累计已提现和入网状态;累计已提现与首页统一读取 withdrawn_amount。
代客下单/pages-home/sub-po?from=staff员工帮助客户创建全国标准单。提交后可选择本人微信支付或生成客户扫码二维码;订单金额以服务端平台 SKU 价格为准。
可服务产品/pages-staff/capability/index申请工种、产品和服务区域。
休息日/pages-staff/availability/index维护临时休息和可接单日期。
客户开发海报/pages-staff/development-poster/index生成专属下单二维码,后续用于开发奖金归因。
邀请入驻shareStaffInvitation邀请员工入驻。
我的队员/pages-staff/apprentice/index省级负责人查看和管理直属队员。
站长微信/pages-staff/station-contact/index维护队员可见联系方式。
联系店长getStoreContact获取当前门店联系方式。
个人入网/pages-staff/yeepay-innet/*个人结算入网和状态查看。
保险服务insurance.js查看保单、下载或购买保险。
用工消息通知employee-relation.js绑定/解绑用工消息,绑定后可测试推送。
公众号绑定staff-auth.js生成二维码、轮询绑定状态、测试推送、解绑。
设置/pages-staff/home/settings默认公司、退出、密码等设置。

入驻、简历和资料 ​

员工资料链路覆盖注册、AI 录入、简历、证件、照片、技能、工作经历、家庭信息、封面和分享。

页面逻辑
resume-add.vue员工或阿姨快速录入,支持邀请码、微信手机号、身份证 OCR、AI 解析。
resume.vue查看和维护员工简历,支持复制到阿姨库或标准员工删除。
resume-template-list.vue门店简历模板设置。
ai-aunt-chat.vueAI 对话生成或补全阿姨资料,可复制平台阿姨到门店。
sync-aunt.vue搜索外部或平台阿姨,并同步到门店。
credit-check.vue身份比对、涉诉、特殊名单、信用查询,可能涉及余额或积分扣费。

这些模块会涉及个人敏感资料,文档只写流程和表归属,不沉淀明细。

保险购买 ​

员工端保险购买主要用于服务人员保障。标准单结算不以保险作为前置条件,后续如接入服务时投保接口,再按履约链路校验。

操作逻辑
查询保险状态getStaffInsuranceStatus 判断员工当前是否有有效保险。
购买保险调用大地或人保接口,写本地保险记录和第三方订单。
查询支付状态轮询或回调更新保单状态。
取消待支付对超时或错误待支付记录进行取消,避免卡住后续购买。

历史数据中如出现保险冻结状态,只按遗留状态排查;新标准单结算不因保险缺失冻结。

招聘和发展海报 ​

员工可以生成招聘码、发展渠道和海报,用于带来新员工或订单归因。

数据说明
store_recruit_code门店招聘码。
store_recruit_poster_template*海报模板和二维码。
development_channel_scan_log发展渠道扫码记录。
staff_wallet_ledger后续开发奖金流水。

排障清单 ​

问题先查
员工登录失败service_staff 状态、手机号、openid、token。
员工看不到订单员工订单关系、标准单 attempt、订单状态、员工服务区域和能力。
接单失败当前订单状态、员工权限、是否超时、是否已被其他人处理。
开始服务失败是否已接单、服务前图片、订单是否取消。
完成服务失败当前状态是否服务中、图片/签名是否上传、结算任务是否创建。
休息日设置失败当天是否已有订单或档期锁。
钱包金额不对服务奖金任务、开发奖金流水、提现申请、历史只读收入。
提现失败可提现余额、最低金额、处理中提现、入网和打款状态。
能力区域不生效申请是否审批通过,员工池是否刷新。
保险状态不对本地保单、第三方回调、待支付清理、保险起止日期。

用于金刚项目内部协作、运营培训和客户说明。