金刚员工端系统架构与数据流

一、系统定位

员工端由 storeui 小程序和 storeapi 后端组成，是金刚体系的一线履约承接侧。它不负责客户选购，也不承担云平台的全量运营配置；它把已支付订单变成员工可执行的任务，并把服务结果、凭证和结算任务回写到平台。

二、系统边界

客户
  ↓ 选产品、地址、时间、支付
clientui / clientapi
  ↓ 共享订单主数据和支付结果
storeapi
  ├─ 标准员工池：能力、区域、档期、轮派、通知
  ├─ 员工履约：接单、前往、开始、完成、服务记录
  ├─ 资金：补价、服务奖金、开发奖金、钱包、提现
  ├─ 资料：员工、简历、能力、保险、入网、队员
  └─ 任务：超时顺延、通知、结算、回调和补偿
  ↓
storeui 员工端小程序
  ↓ 服务状态、图片、签名、说明、支付确认
yunui / yunapi
  └─ 产品/权限配置、人工派单、审核、财务、统计和兜底

三、前端分层

层级	目录/页面组	作用
主包入口	pages/staff、pages/home、pages/my	员工身份进入、服务首页、我的和角色切换
员工核心分包	pages-staff/home、service、capability、availability、wallet	接单、履约、能力、区域、档期和钱包
资料分包	pages-staff/resume*、pages-aunt-resume	简历、证件、技能、AI 录入、分享和资料同步
资金/入网	pages-staff/yeepay-innet、select-account、pages-capital-flow	个人入网、账户、提现、余额和支付
保险	pages-staff/insurance-purchase、pages-insurance、pages-home/insurance	员工保障、报案、理赔、退保材料
发展与队伍	development-poster、recruit-poster、apprentice、station-contact	开发归因、招聘、队员和站长联系

页面通常只负责展示、参数收集和调用 API；订单、资金、权限和状态判断必须由后端完成。

四、后端分层

FastAPI app/server
  ↓ controller（鉴权、入参、统一响应）
service（事务、状态、第三方、幂等和业务规则）
  ↓
DAO/entity/VO（订单、员工、任务、文件和流水）
  ↓
MySQL + Redis + 文件服务 + 支付/保险/通知渠道

核心 controller/service 组：

业务域	Controller	Service
员工登录	service_staff_login_controller.py	service_staff_login_service.py
员工订单	staff_order_controller.py	staff_order_service.py
标准派发	internal_standard_order_ops_controller.py	standard_staff_dispatch_service.py、standard_order_operation_service.py
能力区域	staff_capability_controller.py、staff_availability_controller.py	staff_capability_service.py、staff_region_service.py、standard_staff_schedule_service.py
结算钱包	staff_wallet_controller.py、order_settlement_controller.py	staff_wallet_service.py、standard_order_settlement_service.py
提现入网	staff_account_application_controller.py、yeepay_innet_controller.py	staff_withdrawal_payout_service.py、yeepay_innet_service.py
保险	insurance_controller.py、picc_insurance_controller.py	insurance_service.py、picc_insurance_service.py
资料队伍	staff_controller.py、staff_apprentice_controller.py	staff_management_service.py、staff_apprentice_service.py

五、身份和权限模型

同一小程序同时承载门店端和员工端，两套身份必须分开处理：

项目	门店端	员工端
token	门店/内部用户 token	staffToken
主身份	internal_user	service_staff
入口	pages/home、pages/my	pages-staff/home、pages-staff/home/my
访问范围	公司/门店数据权限	员工本人、所属门店和授权队伍关系

角色切换由后端生成目标身份 token，并清理前端当前角色缓存。不能只通过前端跳转页面模拟切换，否则会出现“页面到了但接口无权限”的假登录。

六、核心数据流

6.1 订单履约

order（订单主状态）
 ├─ order_waiter / dispatch attempt（员工关系和派发尝试）
 ├─ order_logs（接单、拒单、状态和异常日志）
 ├─ file_*（服务前后图片、签名和文件组）
 ├─ order_additional_payments（补价和支付状态）
 └─ order_evaluation（评价和奖励）

标准单在支付成功后进入待派发；后端按能力、区域、档期和派发规则生成尝试，员工操作只通过状态机推进订单。完成服务后，档期锁关闭，结算和开发奖金任务入队。

6.2 能力、区域和档期

platform_product
   ↓ 员工申请/平台绑定
staff_service_capability → staff_service_capability_audit
standard_staff_service_region → staff_service_region_application
staff_rest_date
   ↓ 冲突检查
standard_staff_schedule_lock + 未完成订单
   ↓
是否进入标准员工池候选

提交申请只是产生待审核记录；只有生效状态才参与派发。档期锁同时防止并发订单和休息日设置冲突。

6.3 钱包和结算

订单完成
  ↓
standard_order_settlement_task
  ├─ 服务奖金：等待/处理中/冻结/成功/失败
  ├─ development_bonus_task：开发归因、解冻和冲减
  └─ staff_wallet_ledger：流水留痕
          ↓
staff_wallet_account → 提现申请 → 打款/到账确认

钱包页面不能只读一个账户余额。展示需要聚合结算任务、开发奖金、提现申请、流水以及历史只读收入；对账时按收入来源拆分。

七、后台任务和第三方边界

类别	典型任务/渠道	作用
派发任务	待派发、拒绝/超时顺延、通知 outbox	找下一候选并发送员工通知
履约任务	结算、奖金、完成通知	把完成结果转成资金和运营结果
支付渠道	易宝、微信/支付宝、余额	订单支付、补价和入网
保险渠道	大地、人保、安心生活等	投保、支付、保单、理赔和退保材料
通知渠道	公众号、短信、企微	订单提醒、审批提醒和运营通知
文件服务	文件组、图片、签名、导出	保存履约凭证并提供查看/下载

云函数请求结束后的隐式后台线程不作为可靠任务机制。结算、超时、通知、回调补偿等必须有明确任务入口、幂等锁和可查询日志。

八、状态一致性原则

1. 订单状态以 storeapi 后端状态机为准，前端按钮只反映当前允许动作。
2. 支付、补价、提现和保险状态以渠道回调与本地记录共同确认，不能以轮询页面结果单独确认成功。
3. 文件上传成功不等于服务完成；服务完成必须通过订单状态校验并创建后续任务。
4. 员工拒单或超时只结束当前派发尝试，不等于客户订单取消。
5. 历史订单、旧外部协同链路和新标准单必须按业务模式区分，不用产品名称猜业务来源。

九、技术排查路径

现象	排查顺序
登录成功但看不到员工入口	token/角色 → service_staff 状态 → 默认公司 → 页面权限
没有待接单订单	订单支付状态 → 标准业务模式 → 员工能力/区域 → 档期/接单开关 → 派发尝试
接单失败	当前状态 → attempt 是否超时/处理 → 员工订单权限 → 档期锁 → 订单日志
开始/完成失败	当前状态 → 员工关系 → 图片/签名文件组 → 服务记录 → 状态日志
钱包金额异常	结算任务 → 开发奖金 → 流水 → 提现申请 → 入网状态
保险状态异常	本地保单 → 支付回调 → 第三方查询 → 待支付清理 → 操作日志

十、发布和兼容

• storeui 是微信小程序，前端改动需要构建、真机验证、上传和审核，不能按普通静态网站直接覆盖。
• storeapi 是云函数，后端上线前必须兼容线上旧小程序包，尤其是订单状态、支付回调、保险和钱包接口。
• 前后端同步改造要安排兼容窗口；后端新字段和新状态应允许旧包继续读取或忽略。
• 生产发布前后重点验证登录、待接单、接单、开始/完成、补价、钱包和第三方回调。