Appearance
金刚员工端完整模块与逻辑
本页只写金刚小程序员工端。员工端是服务履约入口，重点是登录、接单、服务记录、能力区域、档期、钱包、入驻、保险、简历和队员管理。
员工端入口
| 模块 | 页面 | API | 后端 | 主要数据 |
|---|---|---|---|---|
| 登录和账号 | pages-staff/home/*、pages/login、pages-login-aux | staff-auth.js | service_staff_login_controller.py、service_staff_login_service.py | service_staff、internal_user、openid 绑定 |
| 服务首页 | pages-staff/home/index.vue | staff-order.js | staff_order_controller.py、staff_order_service.py | order、order_logs、order_waiter、standard_staff_dispatch_* |
| 服务记录 | pages-staff/service/record.vue | staff-order.js | staff_order_controller.py | file_*、order_logs、订单服务记录字段 |
| 我的 | pages-staff/home/my.vue | staff-wallet.js、staff-auth.js、insurance.js、employee-relation.js | 多个员工端 controller | 员工钱包、保险、公众号绑定、用工关系 |
| 设置 | pages-staff/home/settings.vue | staff-auth.js | service_staff_login_controller.py | 员工登录态、默认公司 |
| 能力申请 | pages-staff/capability/index.vue | staff-capability.js | staff_capability_controller.py、staff_capability_service.py | staff_service_capability、staff_service_capability_audit、staff_platform_product |
| 服务区域 | pages-staff/capability/index.vue | staff-capability.js | staff_capability_controller.py | standard_staff_service_region、staff_service_region_application |
| 档期休息 | pages-staff/availability/index.vue | staff-availability.js | staff_availability_controller.py、staff_availability_service.py | staff_rest_date、standard_staff_schedule_lock、order |
| 员工钱包 | pages-staff/wallet/index.vue | staff-wallet.js | staff_wallet_controller.py、staff_wallet_service.py | staff_wallet_account、staff_wallet_ledger、staff_withdrawal_application |
| 入网开户 | pages-staff/yeepay-innet/*、pages-staff/select-account.vue | yeepay-innet.js、staff-account-application.js | yeepay_innet_controller.py、staff_account_application_controller.py | yeepay_innet_record、staff_withdrawal_application |
| 队员管理 | pages-staff/apprentice/index.vue、pages-staff/station-contact/index.vue | staff-apprentice.js、staff-station-contact.js | staff_apprentice_controller.py、staff_station_contact_controller.py | service_staff.mentor_staff_id、staff_mentor_province_binding |
| 简历和阿姨资料 | pages-staff/resume*、pages-aunt-resume | staff.js、aunt-resume.js、aunt.js、ai-register.js | staff_controller.py、aunt_controller.py、resume_share_controller.py | aunt、aunt_detail、aunt_certificate、service_staff |
| 保险购买 | pages-staff/insurance-purchase.vue | insurance.js | insurance_controller.py | insurance_record、contract_insurance |
| 信用核验 | pages-staff/credit-check.vue | aunt.js、payment.js | aunt_*_service.py、payment_service.py | credit_query_record、核验结果表 |
| 招聘和发展 | pages-staff/development-poster、pages-staff/recruit-poster.vue | staff-development-channel.js、staff.js | staff_development_channel_controller.py、store_recruit_controller.py | development_channel_scan_log、store_recruit_code |
登录和身份逻辑
员工端支持密码、短信、微信、手机号快速授权和公众号绑定。后端统一从员工 token 解析当前员工，再决定员工可访问的门店或公司。
| 能力 | 逻辑 |
|---|---|
| 密码登录 | 手机号和密码校验后返回员工身份、门店、token。 |
| 短信登录 | 先发验证码，再用手机号和验证码换 token。 |
| 微信登录 | 根据 openid 找员工；没有绑定时要求手机号绑定。 |
| 多公司访问 | validateCompanyAccess 校验员工是否能进入目标公司，setDefaultCompany 保存默认公司。 |
| 员工和门店账号切换 | switchToStaffAccount、switchToStoreAccount 在员工身份和管理端身份之间切换。 |
| 公众号绑定 | 生成带参二维码，扫码后统一绑定员工微信公众号 openid，用于服务通知和测试推送。 |
排查登录失败时先查员工是否有效，再查 openid 和手机号绑定，不要只看小程序缓存。
员工主数据和身份字段
| 字段组 | 数据来源 | 影响 |
|---|---|---|
| 基础身份 | 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，标准单会继续顺延候选或进入人工处理。
完成服务后会继续触发：
StandardStaffScheduleService.complete_schedule释放或完成档期锁。StandardOrderSettlementService.enqueue_order_completion创建服务奖金结算任务。DevelopmentBonusService.enqueue_order_completion创建客户开发奖金任务。- 尝试通知云平台和渠道方订单已完成。旧小羽佳直连接口已废弃，不作为交接主线。
补价和支付
员工端可以对订单创建补价、查询补价记录、处理现金支付、客户余额支付和线上支付。
| 场景 | 逻辑 |
|---|---|
| 创建补价 | 员工填写补价金额、原因、说明，后端写 order_additional_payments。 |
| 现金支付 | 员工确认已收现金后，后端标记补价成功并写日志。 |
| 客户余额支付 | 后端校验客户余额，扣减后更新补价状态。 |
| 线上支付 | 创建支付订单后轮询状态，支付回调成功后更新补价。 |
| 查询状态 | 员工端刷新补价记录，避免重复收款。 |
补价问题排查要同时看补价表、支付订单、订单日志和员工端轮询状态。
员工端补价必须先校验当前员工对订单有权限。支持的 payment_type：
| 类型 | 处理方式 |
|---|---|
cash | 员工确认已收现金，补价记录直接标记已支付。 |
balance | 扣客户余额后更新补价支付状态。 |
scan_pay | 创建支付订单，客户扫码支付。 |
yeepay | 创建易宝支付订单或二维码，回调后更新状态。 |
补价记录的支付状态不要由前端本地判断，必须以后端查询结果和支付回调为准。
服务记录
pages-staff/service/record.vue 是员工结束服务时的关键页面，主要处理：
- 上传服务前或服务后图片。
- 上传客户签名或服务确认凭证。
- 填写服务说明。
- 调用结束服务接口。
- 回到服务首页刷新订单状态。
服务记录页不能绕过订单状态。后端会校验当前订单是否允许开始或结束服务，避免已取消、已完成或不属于当前员工的订单被重复处理。
服务记录页上传逻辑：
| 内容 | 要求 |
|---|---|
| 服务前照片 | startService 必填；uploadServiceBeforeImages 可后续补传。 |
| 服务后照片 | endService 可选，存在时写文件组。 |
| 客户签名 | endService 可选，存在时写电子签名文件组。 |
| 服务说明 | 可选文本，随结束服务写入。 |
图片和签名通过文件服务创建文件组，再把文件组 ID 写回订单。排查图片丢失时先查文件组和订单字段，不要只看页面缓存。
能力、区域和档期
服务能力
员工能力由工种、产品和审核状态共同决定。
| 数据 | 说明 |
|---|---|
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 会同时读取固定休息日、具体休息日和订单档期锁：
- 固定休息日来自
service_staff_ext.rest_days。 - 具体休息日来自
staff_rest_date。 - 已有订单来自
standard_staff_schedule_lock和order。 - 设置休息日时如果当天已有进行中订单，会拒绝设置。
- 取消休息日也会检查冲突，避免影响已锁定服务。
档期接口默认查从今天起未来 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 | 提现申请、审核、处理中、完成、失败。 |
钱包总览会拆分：
| 字段 | 含义 |
|---|---|
| 可提现 | 已解冻且可发起提现的收入。 |
| 冻结中 | 未入网、人工冻结或开发奖金冻结期；历史保险冻结只按遗留状态排查，新标准单结算不因保险缺失冻结。 |
| 处理中 | 结算或提现正在处理。 |
| 已到账 | 已分账或已打款完成。 |
| 历史只读 | 老订单的历史收入，只展示不参与新钱包计算。 |
提现时后端会校验最低提现金额、是否已有处理中提现、可用余额是否足够，并写幂等流水。
员工钱包展示不是只读 staff_wallet_account。当前真实库中员工钱包账户为空，但页面仍会聚合以下数据：
| 数据来源 | 展示位置 |
|---|---|
standard_order_settlement_task | 服务奖金冻结、处理中、已到账、总额。 |
development_bonus_task | 开发奖金可用、冻结、提现中、已支付。 |
staff_wallet_ledger | 开发奖金、提现、失败/驳回等流水。 |
order_waiter + order | 历史服务收入，只读展示，不计入可提现。 |
yeepay_innet_record | 入网状态，决定是否可提现。 |
提现申请规则：
- 金额必须大于 0，且不低于
standard_order_rule_config.MIN_WITHDRAWAL_AMOUNT；未配置时按服务默认值。 - 易宝个人入网必须完成，否则不能提现开发奖金。
- 必须存在员工钱包账户，且可提现余额足够。
- 同一员工已有
PENDING、APPROVED、PROCESSING提现时禁止再申请。 - 申请后可用余额减少、冻结余额增加，写
staff_withdrawal_application和staff_wallet_ledger，幂等键为提现单号。
队员和站长
队员管理以 service_staff.mentor_staff_id 快照和省级师傅绑定为准，不再依赖旧师傅名单池。
| 能力 | 说明 |
|---|---|
| 队员列表 | 省级负责人查看直属队员、工种、状态、接单情况、入网状态。 |
| 接单开关 | 负责人可以更新队员是否参与派发。 |
| 员工积分 | 负责人可调整队员员工积分，并记录原因。 |
| 能力审批 | 站长审批直属队员工种和产品能力。 |
| 区域审批 | 站长审批直属队员服务区域。 |
| 站长联系方式 | 员工维护对队员展示的微信号和二维码。 |
员工“我的”页只有满足省级负责人条件才展示“我的队员”和“站长微信”。队员管理接口要求当前员工是直属负责人，否则不能查看或审批别人的能力/区域。
我的页入口总表
pages-staff/home/my.vue 是员工端二级能力入口，排查员工说“找不到功能”时先看这里。
| 入口 | 页面/接口 | 逻辑 |
|---|---|---|
| 我的钱包 | /pages-staff/wallet/index、staff-wallet.js | 展示可提现、冻结、处理中、已到账和入网状态。 |
| 代客预约 | /pages-home/sub-po?from=staff | 员工帮助客户预约服务，仍要走订单校验。 |
| 可服务产品 | /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.vue | AI 对话生成或补全阿姨资料，可复制平台阿姨到门店。 |
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、订单状态、员工服务区域和能力。 |
| 接单失败 | 当前订单状态、员工权限、是否超时、是否已被其他人处理。 |
| 开始服务失败 | 是否已接单、服务前图片、订单是否取消。 |
| 完成服务失败 | 当前状态是否服务中、图片/签名是否上传、结算任务是否创建。 |
| 休息日设置失败 | 当天是否已有订单或档期锁。 |
| 钱包金额不对 | 服务奖金任务、开发奖金流水、提现申请、历史只读收入。 |
| 提现失败 | 可提现余额、最低金额、处理中提现、入网和打款状态。 |
| 能力区域不生效 | 申请是否审批通过，员工池是否刷新。 |
| 保险状态不对 | 本地保单、第三方回调、待支付清理、保险起止日期。 |