Skip to content

云平台源码与业务导航 ​

代码快照:2026-08-20。范围为 yunui 与 yunapi 当前工作区;生产菜单同时通过 sys_menu 只读查询核对。实际线上能力仍以已发布代码、sys_menu、sys_role_menu 和运行时配置为准。

合同家访追踪(2026-10-10) ​

前端页面为 yunui/src/views/contract/home-visit-tracking/index.vue,API 包装为 src/api/contract/home-visit-tracking.js。后端由 contract_management_controller.py 的 /contract/management/home-visits 列表和详情接口接入 ContractHomeVisitTrackingService,权限为 contract:home-visit:list。

14次家访提示维护使用 contract_home_visit_instruction_template 配置表,主键为合同类别和家访次数;旧 contract_home_visit_instruction 保留作为通用兼容兜底。合同类别为 CHILDCARE(育儿嫂)、ELDERCARE(老人照护)或 GENERAL(通用),由合同类型名称、服务类型和服务内容自动识别。云平台 home-visit-instructions?category=... 查询和保存,员工端合同家访接口在每次计划中返回对应 instruction。迁移脚本为 yunapi/sql/20261013_contract_home_visit_instruction_template.sql,员工端兼容脚本为 storeapi/migrations/20261013_contract_home_visit_instruction_template.sql。

服务距离使用 contract_home_visit_setting 单行配置,云平台通过 home-visit-settings 查询和保存;员工端计划返回 radius_meters,服务端提交时再次按该距离校验。

家访完成后的内容补填使用员工端 home-visits/remark 接口,仅更新已完成记录的 remark,不重新校验或覆盖照片、定位、签字证据。

开始证据写入家访计划的 start_* 字段;结束证据和签字时间写入家访记录的 end_*、signature_at 字段。2026-10-13 新增员工端 POST /api/v1/contract/{contract_uuid}/home-visits/auto-location,按合同地址识别定位,拒绝行政区级模糊结果和错误城市;已开始或完成家访的坐标不自动覆盖。旧版手动定位接口保留兼容。腾讯地图账号通过 TENCENT_API_KEY 环境配置覆盖,复用原有地图账号默认值;识别失败不写目标坐标,地图额度不足单独提示。本次不涉及数据库结构迁移。

家访追踪的省市门店筛选读取 store_region_profile 已核对的门店地区,最细到市级;筛选项接口为 /contract/management/home-visit-filter-options。/contract/management/home-visits/export 按与列表相同的筛选条件导出合同及逐次家访明细,不使用分页参数限制结果。

查询共享库 contract_home_visit_plan 与 contract_home_visit_record,从适用合同左联计划,因此未生成计划的合同也可追踪。菜单迁移为 yunapi/sql/20261010_contract_home_visit_tracking_menu.sql,幂等新增入口并同步合同明细角色授权。接口只读,未生成计划不会在查询时自动写入。

临时测试定位使用 sys_config 键 contract.home_visit.test_location.{contract_uuid},值为 JSON:enabled 必须为布尔真、expires_at 必须含时区且未到期,original_address 必须对应合同原地址,address、latitude、longitude 必须逐条匹配家访计划中的测试地址和坐标。不存在、到期、停用、坐标不符均拒绝;仅服务端管理员配置,无员工端开启入口。识别、开始和提交均检查,原有合同权限和距离校验不变。无需建表;关闭时停用或删除该配置,恢复备份的计划地址和坐标,清理测试证据须另行确认并备份。

1. 文档用途 ​

这是一份面向开发、运维和 AI 接手的源码总索引,用来回答四类问题:

  1. 某个业务规则在哪里实现,数据最终写到哪里。
  2. 某个前端功能是否存在,页面入口、按钮权限和代码文件在哪里。
  3. 页面数据异常时,如何从 Vue 页面追到 API、Controller、Service、DAO 和数据表。
  4. 新会话如何用最少阅读量建立云平台上下文。

本页记录源码事实和排障入口。面向运营的操作步骤继续以云平台业务流程与运营手册为准,具体专题以对应产品或运维文档为准。

2. 五分钟理解系统 ​

2.1 系统职责 ​

项目技术栈主要职责关键目录
yunuiVue 2、Vue Router、Vuex、Element UI、Axios云平台运营后台、查询、审核、配置、统计、导出和人工兜底src/views、src/api、src/router、src/store
yunapiFastAPI、SQLAlchemy Async、MySQL、Redis、APScheduler登录权限、业务查询和写入、任务调度、文件生成、第三方与 storeapi 桥接module_admin/controller、service、dao、entity、module_task

云平台不是完整的一线履约系统。订单履约、人员鉴定、全国标准单部分写操作、合同重签、保险任务和月度品牌费等能力会读取共用业务库,或通过内部凭证调用 storeapi。排障时不能默认所有业务都只发生在 yunapi。

2.2 请求链路 ​

text
浏览器页面
  -> yunui/src/views/**/*.vue
  -> yunui/src/api/**/*.js
  -> yunui/src/utils/request.js
  -> yunapi/module_admin/controller/*_controller.py
  -> yunapi/module_admin/service/*_service.py
  -> yunapi/module_admin/dao/*_dao.py 或服务内参数化 SQL
  -> MySQL / Redis / storeapi / 支付保险接口 / AI 服务 / OBS

查问题时按这条链路逐层确认,不要只看页面,也不要跳过 Service 直接按表名猜业务规则。

2.3 前端启动与权限 ​

位置作用
yunui/src/main.js注册 Element UI、全局组件、字典、下载工具、Vuex 和路由。
yunui/src/router/index.js登录、首页、个人中心、公开表单、大屏和少量隐藏路由。业务菜单不在这里写死。
yunui/src/permission.js登录拦截、白名单判断、首次加载用户信息和动态路由。
yunui/src/store/modules/permission.js将后端 /getRouters 返回的菜单转换成 Vue 路由并加载页面组件。
yunui/src/utils/request.jsAxios 基础地址、Bearer Token、GET 参数转换、1 秒重复提交保护、业务码和 401 处理。
yunui/src/directive/permission/hasPermi.jsv-hasPermi 按按钮权限码控制操作入口。

登录后的关键顺序是:

text
POST /login
  -> 保存 Token
  -> GET /getInfo,取得 user、roles、permissions
  -> GET /getRouters,取得角色菜单树
  -> 动态加载 src/views 下的组件

页面是否可用由三层共同决定:

  1. src/views 中存在组件代码。
  2. sys_menu 中存在启用的菜单或按钮权限。
  3. 当前角色通过 sys_role_menu 获得对应权限。

超级接口权限为 *:*:*。后端通过 CheckUserInterfaceAuth 校验接口权限,前端按钮隐藏不能替代后端授权。

2.4 后端启动与响应 ​

位置作用
yunapi/app.py使用 Uvicorn 启动 server:app。
yunapi/server.py创建 FastAPI、挂载静态目录和子应用、注册中间件、异常处理与全部 Controller。
yunapi/config/get_db.py创建异步数据库会话,启动时验证数据库并创建已声明表。
yunapi/config/get_redis.py连接 Redis,并将系统字典和参数载入缓存。
yunapi/config/get_scheduler.py从 sys_job 恢复 APScheduler 任务,记录 sys_job_log。
yunapi/utils/response_util.py统一输出 code、msg、success、time,列表常附带 rows 和 total。

server.py 生命周期的启动顺序是:数据库 -> Redis -> 字典与配置缓存 -> 调度器 -> 恢复未完成素材 AI 任务。设置 APP_DISABLE_BACKGROUND_TASKS=true 时,调度器和 AI 恢复任务都会关闭,适用于不应执行后台任务的临时实例或测试环境。

3. 遇到问题先查哪里 ​

现象第一入口下一步
不确定前端有没有某功能本页“前端页面与功能矩阵”搜索页面文件中的按钮文案、v-hasPermi 和 API import。
菜单看不到sys_menu、sys_role_menu查菜单状态、组件路径、角色授权,再查前端是否已发布。
页面 404 或空白sys_menu.component 对应的 src/views 文件查浏览器控制台、静态资源版本和菜单代码漂移。
按钮不显示页面 v-hasPermi对照 /getInfo 的 permissions 和后端 CheckUserInterfaceAuth。
页面有请求但没有数据浏览器 Network 中的 URL 和参数按 API -> Controller -> Service -> DAO/SQL 检查过滤条件和数据范围。
接口返回 401/403login_service.py、interface_auth.py查 Token、Redis 会话、角色权限码。
操作显示成功但业务没变化对应 Service 的事务和跨系统调用查 sys_oper_log、业务日志表、storeapi 或第三方响应。
订单或家政广场异常order_service.py、demand_square_service.py查 order、order_waiter、order_logs、demand_square、demand_channel_data。
线索重复派发或名额不对store_score_service.py、lead_tracking_service.py查派发记录、轮派游标、接收人、余额、进行中线索和取消/申诉记录。
积分没有增加store_score_service.py 和任务日志查业务命中条件、source_key、结算批次、来源同步是否早于日结。
财务金额不一致具体财务页面对应 Service先确认 LEGACY、DUAL、STORE_WALLET 模式,再核对两套流水。
定时任务没跑云平台“系统监控 -> 定时任务”查 sys_job、sys_job_log、APScheduler 状态;宝塔任务另查脚本日志和批次表。
第三方状态不同步对应 Service 的 HTTP 调用查请求标识、第三方响应、回调记录和本地事务是否提交。

4. 前端页面与功能矩阵 ​

4.1 首页、公开页和隐藏路由 ​

页面/URL主要功能Vue 与 API后端与权限
首页 /index订单、收入、门店等经营指标和趋势图;进入数据大屏views/dashboard/index.vue、api/dashboard.jsdashboard_controller.py;dashboard:statistics
平台数据大屏 /platform-screen全屏展示平台经营数据views/dashboard/PlatformScreen.vue、api/dashboard.js静态隐藏路由;接口仍校验 dashboard:statistics
日度数据大屏 /daily-screen展示日度业绩、趋势和排名views/dashboard/DailyScreen.vue、api/dashboard.js静态隐藏路由;接口仍校验 dashboard:statistics
需求提交 /requirement-submit免登录提交需求及附件views/requirement/submit/index.vue、api/requirement/review.jsrequirement_review_controller.py 的公共路由
固定表单 /fixed-form/:formKey免登录填写指定表单,最多上传 6 张图片views/fixedForm/public/index.vue、api/fixedForm/index.jsfixed_form_controller.py 的公共路由
个人中心 /user/profile修改资料、头像和密码views/system/user/profile/*、api/system/user.jsuser_controller.py;登录用户

4.2 商户与服务人员 ​

以下入口来自生产 sys_menu 的启用菜单快照。

菜单与 URL页面功能Vue / API后端入口页面权限
商户管理 -> 商户入驻 /merchant/storeRegister入驻申请查询、详情、跟进记录、商户审核、小羽佳员工审核、入网资料查询views/merchant/storeRegister/index.vue / api/merchant/storeRegister.jsexperience_table_controller.py、experience_table_service.pymerchant:experienceTable:list
商户管理 -> 公司管理 /merchant/company公司增删改查、门店明细、版本开通与续费、批量续费撤销、业务服务续期、费率、充值、提现、API 密钥管理views/merchant/company/index.vue / api/merchant/company.jscompany_controller.py、company_service.pymerchant:company:list
商户管理 -> 门店管理 /merchant/store门店查询、增删改、公司归属和易宝入网详情views/merchant/store/index.vue / api/merchant/store.jsstore_controller.py、store_service.pymerchant:store:list
商户管理 -> 客户管理 /merchant/ccuser客户查询、增删改和门店筛选views/merchant/ccuser/index.vue / api/merchant/ccuser.jsccuser_controller.py、ccuser_service.pymerchant:ccuser:list
商户管理 -> 内部员工管理 /merchant/internalUser内部员工查询、创建、修改、删除、公司门店和权限维护views/merchant/internalUser/index.vue / api/merchant/internalUser.jsinternal_user_controller.py、internal_user_service.pymerchant:internalUser:list
商户管理 -> 全国标准单员工池 /merchant/standardStaff员工池预检、资料异常、省级负责人、派发、结算、招工与产品、运营中心views/merchant/standardStaff/index.vue、components/OperationsCenter.vue / api/merchant/standardStaff.jsstandard_staff_controller.py、standard_staff_service.pymerchant:standardStaff:list
商户管理 -> 积分机制 /merchant/storeScore积分账户、派发区域、运营数据、排行、城市池看板、积分规则、结算运维、积分流水、线索追踪、渠道门店绑定views/merchant/storeScore/index.vue / api/merchant/storeScore.jsstore_score_controller.py、store_score_service.pymerchant:storeScore:list
商户管理 -> 招工观察榜 /merchant/storeRecruitRanking招工排名柱状图、区域筛选和明细views/merchant/storeRecruitRanking/index.vue / api/merchant/storeScore.jsstore_score_controller.pymerchant:storeScore:list
商户管理 -> 招工海报配置 /merchant/storeRecruitPoster海报模板、二维码和门店招工配置views/marketing/storeRecruitPoster/index.vue / api/storeRecruitPoster.jsstore_recruit_poster_controller.pymerchant:storeRecruitPoster:list
商户管理 -> 手机号关联门店 /merchant/storeSwitchAccount查询手机号可切换门店并保存账号关联views/merchant/storeSwitchAccount/index.vue / api/merchant/storeSwitchAccount.jsstore_switch_account_controller.pymerchant:storeSwitch:list
服务人员管理 -> 服务人员 /serviceStaffManagement/serviceStaff服务人员列表、详情、证书、培训、保险、合同、评价和服务历史views/merchant/serviceStaff/index.vue / api/merchant/serviceStaff.jsservice_staff_controller.py、service_staff_service.pymerchant:serviceStaff:list
服务人员管理 -> 家政员档案 /serviceStaffManagement/aunt家政员档案、家庭、技能证书、工作与培训经历、图片、保险、关注和操作记录views/merchant/aunt/index.vue / api/merchant/aunt.jsaunt_controller.py、aunt_service.pymerchant:aunt:list
已下线:服务人员管理 -> 人员鉴定管理2026-08-21 停用菜单;已审核员工池、人员异常和省级负责人统一进入全国标准单员工池,旧接口仅保留历史兼容views/merchant/staffAppraisal/index.vue / api/merchant/staffAppraisal.jsstaff_appraisal_controller.py、staff_appraisal_admin_service.py菜单权限已停用

4.3 产品、订单与线索 ​

菜单与 URL页面功能Vue / API后端入口页面权限
产品管理 -> 平台统一产品库 /product/platformProduct平台产品、SKU、工种、状态、区域价格和来源映射维护views/merchant/platformProduct/index.vue / api/merchant/platformProduct.jsplatform_product_controller.py、platform_product_service.pymerchant:platformProduct:list
产品管理 -> 产品同步 /product/productSync查看历史产品、同步状态、差异、映射和手动同步views/merchant/productSync/index.vue / api/merchant/productSync.jsproduct_sync_controller.py、product_sync_service.pymerchant:productSync:list
产品管理 -> 积分产品 /product/pointsGoods积分商品增删改查、上下架和库存信息views/product/pointsGoods/index.vue / api/product/pointsGoods.jspoints_goods_controller.py、points_goods_service.pyproduct:pointsGoods:list
产品管理 -> 积分订单 /product/pointsOrder兑换订单查询、详情和发货views/product/pointsOrder/index.vue / api/product/pointsOrder.jspoints_order_controller.py、points_order_service.pyproduct:pointsOrder:list
订单管理 -> 订单列表 /order/list多条件查询、详情、备注、取消、编辑、导出、可派员工、手动派单和派单日志;识别支付宝安心渠道views/order/index.vue / api/order/order.jsorder_controller.py、order_service.pyorder:list
订单管理 -> 家政广场 /order/demandSquare需求查询、详情、导出、候选员工、人工派单、支付宝安心预约取消views/order/demandSquare/index.vue / api/order/demandSquare.jsdemand_square_controller.py、demand_square_service.pyorder:demandSquare:list
线索管理 -> 线索跟踪统计 /lead/tracking统计、线索列表、门店线索详情、完整派发轨迹和候选过程views/lead/tracking/index.vue / api/lead/tracking.jslead_tracking_controller.py、lead_tracking_service.pylead:tracking:list
线索管理 -> 派发配置 /lead/dispatch-config查询积分账户、配置公司或门店接收人views/lead/dispatchConfig/index.vue / api/merchant/storeScore.jsstore_score_controller.pymerchant:leadAssignee:list
线索管理 -> 派发申诉审核 /lead/dispatch-appeal查询申诉、查看派发和门店上下文、审核退款或驳回views/lead/dispatchAppeal/index.vue / api/lead/dispatchAppeal.jslead_dispatch_appeal_controller.py、lead_dispatch_appeal_service.pylead:dispatchAppeal:list

4.4 财务、合同与保险 ​

菜单与 URL页面功能Vue / API后端入口页面权限
财务管理 -> 平台资金流水 /finance/platform-flow公司/门店流水查询、详情、统计和筛选views/finance/platform-flow/index.vue / api/finance/transaction.jscompany_transaction_controller.pyfinance:transaction:list
财务管理 -> 充值管理 /finance/recharge-management充值记录、详情、统计、公司和门店筛选views/finance/recharge-management/index.vue / api/finance/recharge.jsrecharge_management_controller.pyfinance:recharge:list
财务管理 -> 对公充值 /finance/public-transfer-recharge对公充值申请查询、详情和审核入账views/finance/public-transfer-recharge/index.vue / api/finance/recharge.jsrecharge_management_controller.pyfinance:publicTransferRecharge:list
财务管理 -> 提现管理 /finance/withdrawal-management提现查询、详情、审核、处理、取消和关联流水views/finance/withdrawal-management/index.vue / api/finance/withdrawal.jscompany_withdrawal_controller.pyfinance:withdrawal:list
财务管理 -> 软件收入 /finance/software-income软件相关收入流水、详情、统计views/finance/software-income/index.vue / api/finance/software-income.jssoftware_income_controller.pyfinance:transaction:list
财务管理 -> 平台收入 /finance/platform-income平台收入流水、详情和统计views/finance/platform-income/index.vue / api/finance/platform-income.jsplatform_income_controller.pyfinance:transaction:list
财务管理 -> 灵工分帐 /finance/freelancer-settlement分账记录和结算状态查询views/finance/freelancer-settlement/index.vue / api/finance/freelancer-settlement.jsorder_split_record_controller.pyfinance:freelancer:list
财务管理 -> 平台收入统计 /finance/platform-revenue-stats平台收入聚合、明细和导出views/finance/platform-revenue-stats/index.vue / api/finance/platformRevenue.jsplatform_revenue_controller.pyfinance:platform-revenue:list
财务管理 -> 渠道收入 /finance/channel-revenue渠道收入列表、统计和导出views/finance/channel-revenue/index.vue / api/finance/channel-revenue.jschannel_revenue_controller.pyfinance:channel-revenue:list
财务管理 -> 月度品牌费 /finance/monthly-brand-fee目标门店预演、执行、按月查看公司/门店钱包双流水和派发状态views/finance/monthly-brand-fee/index.vue / api/finance/monthlyBrandFee.jsmonthly_brand_fee_controller.py、monthly_brand_fee_service.pyfinance:monthlyBrandFee:list
财务管理 -> 门店流水 /finance/store-revenue按门店和时间查询收入流水并导出views/finance/store-revenue/index.vue / api/finance/storeRevenue.jsstore_revenue_controller.pyfinance:storeRevenue:list
合同管理 -> 门店营收统计 /contract/revenue合同营收列表、详情、统计、门店排名和导出views/contract/revenue/index.vue / api/contract/revenue.jscontract_revenue_controller.pycontract:revenue:list
合同管理 -> 合同明细管理 /contract/management合同查询、详情、统计、导出、费用维护、换人、补充协议现服务地址、保险同步、主合同/补充协议重签和签署入口views/contract/management/index.vue / api/contract/management.jscontract_management_controller.py、contract_management_service.pycontract:management:list
合同管理 -> 旧数据导出 /contract/legacy-export创建历史数据导出任务、查看进度和下载结果views/contract/legacy-export/index.vue / api/contract/management.jscontract_management_controller.py、legacy_data_export_service.pycontract:management:export
保险管理 -> 保险对账 /insurance/reconciliation保险对账、统计、导出和中路保障任务views/insurance/reconciliation/index.vue、components/ZhongluTaskPanel.vue / api/insurance/reconciliation.jsinsurance_reconciliation_controller.pyinsurance:reconciliation:list
保险管理 -> 保单退款生成 /insurance/policy-refund保单筛选、退款文档生成、付款截图、电子章或手工盖章和下载views/insurance/policy-refund/index.vue / api/insurance/policyRefund.jspolicy_refund_document_controller.pyinsurance:policyRefund:list
保险管理 -> 保单退保审核 /insurance/surrender-review退保申请查询、材料查看、审核通过或驳回views/insurance/surrender-review/index.vue / api/insurance/surrenderReview.jsinsurance_surrender_review_controller.pyinsurance:surrenderReview:list

4.5 培训、需求、权限和监控 ​

菜单与 URL页面功能Vue / API后端入口页面权限
培训中心 -> 课程管理 /training/courses课程分类和课程增删改查、上下架、内容与封面维护views/training/courses/index.vue / api/training/courses.js、categories.jstraining_courses_controller.py、training_categories_controller.pytraining:courses:list
培训中心 -> 素材管理 /training/materials素材分类、上传、增删改查、使用统计、AI 文案、AI 生图、参考图和任务重试发布views/training/materials/index.vue / api/training/materials.jsstore_material_controller.py、store_material_service.py、material_ai_service.pytraining:materials:list
需求评审 -> 需求列表 /requirement/review需求查询、详情、状态、优先级、排期、附件、编辑、删除和导出views/requirement/review/index.vue / api/requirement/review.jsrequirement_review_controller.pyrequirement:review:list
需求评审 -> 开发日历 /requirement/calendar按计划日期查看需求并调整排期views/requirement/review/calendar.vue / api/requirement/review.jsrequirement_review_controller.pyrequirement:review:schedule
需求评审 -> 表格列表 /requirement/fixedForm固定表单定义和提交记录查询、详情及导出views/fixedForm/list/index.vue / api/fixedForm/index.jsfixed_form_controller.pyfixedForm:form:list
支持员工 -> 门店角色 /internal/role门店端内部角色、菜单权限、状态和用户授权views/internal/role/* / api/system/internalRole.jsinternal_role_controller.pysystem:internal:role:list
支持员工 -> 双端菜单管理 /internal/menu门店端和员工端菜单树增删改查views/internal/menu/index.vue / api/system/internalMenu.jsinternal_menu_controller.py菜单级控制
系统管理用户、角色、菜单、部门、岗位、字典、参数、公告、企微群公告views/system/* / api/system/*对应 *_controller.py 和 *_service.pysystem:*
系统监控在线用户、定时任务、任务日志、登录/操作日志、服务和缓存views/monitor/* / api/monitor/*online、job、log、server、cache Controllermonitor:*
系统工具表单构建、代码生成、Swaggerviews/tool/* / api/tool/gen.jsmodule_generator、/docstool:*

4.6 菜单与代码漂移 ​

类型当前情况影响
菜单有、组件缺失merchant/staffMentorRoster/index“队长师傅名单”菜单启用,但当前 yunui 无对应文件,点击可能组件加载失败。
菜单有、组件缺失merchant/colleagueOrderLoop/index“外部订单协同”菜单启用,但当前 yunui 无对应文件。
历史菜单停用merchant/xyjOrderTrace/index菜单已隐藏停用,当前代码也不存在,不应继续基于旧入口扩展。
代码有、活动菜单无finance/store-wallet-feature/index.vue门店钱包灰度配置页面和接口存在,但生产没有活动菜单;只能在明确授权和路由配置后使用。
辅助页无独立菜单training/materialSubCategories/index.vue二级分类主要由素材页调用,生产没有独立活动菜单。
公开或隐藏路由需求提交、固定表单、两个数据大屏不显示在普通左侧菜单,不能据此判断功能不存在。

5. 后端业务域矩阵 ​

后端通常按 Controller -> Service -> DAO/SQLAlchemy 分层;少量复杂聚合和跨系统逻辑直接在 Service 中使用参数化 SQL。新增接口后必须在 server.py 的 controller_list 注册。

业务域与路由前缀Controller / ServiceDAO 或核心表外部依赖与边界
登录权限 /login、/getInfo、/getRouterslogin_controller.py、login_service.py、menu_service.pysys_user、sys_role、sys_menu、sys_user_role、sys_role_menuJWT 和 Redis 会话
商户入驻 /merchant/experienceTableexperience_table_controller.py、experience_table_service.pyexperience_table、follow_up_record、company、store、store_info、internal_user、yeepay_innet_record审核短信;这里只查询易宝入网结果,不负责真实入网提交
公司 /merchant/companycompany_controller.py、company_service.py、company_dao.pycompany、store、公司版本、业务有效期、company_transactionAPI 凭据生成、充值和提现联动
门店 /merchant/storestore_controller.py、store_service.py、store_dao.pystore、store_info、pay_type、yeepay_innet_record门店经营资料和入网查询
客户 /merchant/ccuserccuser_controller.py、ccuser_service.py、ccuser_dao.pyccuser本地业务库
内部员工 /merchant/internal-userinternal_user_controller.py、internal_user_service.py、internal_user_dao.pyinternal_user、internal_user_permission、公司门店关联门店端账号和权限
家政员 /merchant/auntaunt_controller.py、aunt_service.py、aunt_dao.pyaunt 及家庭、图片、证书、技能、培训、保险、关注、操作日志子表本地聚合档案
服务人员 /merchant/serviceStaffservice_staff_controller.py、service_staff_service.py、service_staff_dao.pyservice_staff、证书、培训、保险、合同、评价、订单关联只读聚合为主
人员鉴定 /merchant/staff-appraisalstaff_appraisal_controller.py、staff_appraisal_admin_service.py鉴定、站长和地区配置相关表受保护桥接调用 storeapi,写操作不在 yunapi 本地实现
全国标准单 /merchant/standard-staffstandard_staff_controller.py、standard_staff_service.pystandard_staff_*、staff_platform_product、platform_product*、派发/奖金/提现/通知相关表本地预检查询;审批、冻结、重排、提现、通知重试等调用 storeapi
平台产品 /merchant/platformProductplatform_product_controller.py、platform_product_service.py、platform_product_dao.pyplatform_product、platform_product_sku、platform_product_mapping、区域价格表标准单产品与来源映射
产品同步 /merchant/productSyncproduct_sync_controller.py、product_sync_service.pyproduct、product_sku、service_product、映射表xyj_standard_order_client.py 调用外部标准单能力
积分商城 /product/points-goods、/product/points-orderspoints_goods/order_controller.py、对应 Servicesys_goods*、积分订单表发货属于写操作
订单 /orderorder_controller.py、order_service.py、order_dao.pyorder、order_waiter、order_logs、支付与门店员工关联普通取消只改本地订单,不调用第三方取消
家政广场 /demand-squaredemand_square_controller.py、demand_square_service.py、demand_square_dao.pydemand_square、demand_channel_data、order、xyj_order_link支付宝安心取消接口;其他渠道不会进入该取消逻辑
门店积分 /merchant/store-scorestore_score_controller.py、store_score_service.pystore_score_*、派发配置/记录/游标、钱包和渠道映射表日结、线索派发、账户、排行、钱包兼容逻辑集中于超大 Service
线索跟踪 /lead/trackinglead_tracking_controller.py、lead_tracking_service.py、lead_tracking_dao.pyjiejie_alliance_lead、门店派发记录、轨迹和候选数据查询统计和完整派发上下文
派发申诉 /lead/dispatch-appeallead_dispatch_appeal_controller.py、lead_dispatch_appeal_service.py申诉、派发记录、钱包流水已扣费取消应走申诉/退款,不直接删除线索
资金流水 /finance/transactioncompany_transaction_controller.py、company_transaction_service.pycompany_transaction旧公司余额体系
充值 /finance/rechargerecharge_management_controller.py、recharge_management_service.py充值记录、company_transaction、store_wallet_transaction按钱包灰度模式决定写旧账、新钱包或双写
提现 /finance/withdrawalcompany_withdrawal_controller.py、company_withdrawal_service.pycompany_withdrawal 及相关资金流水审核、处理和取消分阶段执行
钱包灰度 /finance/store-wallet-featurestore_wallet_feature_controller.py、store_wallet_feature_service.pystore_wallet_feature_config、store_wallet_accountLEGACY、DUAL、STORE_WALLET 读写模式
月度品牌费 /finance/monthly-brand-feemonthly_brand_fee_controller.py、monthly_brand_fee_service.py公司和门店钱包流水、store_score_account云平台负责预演和触发,实际扣款调用 storeapi 内部任务
其他财务 /finance/*软件收入、平台收入、平台统计、渠道收入、灵工分账、门店流水 Controller/Service订单、支付、分账、易宝和钱包相关表的聚合每个页面统计口径不同,必须以对应 Service 为准
合同 /contract/management、/contract/revenuecontract_management/revenue_controller.py、对应 Servicecontract、contract_payment、contract_supply、签名、换人和导出任务表换人、重签、签署入口和保险重同步调用 storeapi
保险 /insurance/*对账、退款文档、退保审核 Controller/Service保险记录、订单日志、insurance_surrender_document中路保障任务调用 storeapi;文档生成涉及模板、临时文件和电子章
培训 /training/categories、/training/courses对应 Controller/Service/DAOtraining_categories、training_courses本地内容管理
素材 /training/materialsstore_material_controller.py、store_material_service.py、material_ai_service.pystore_material*、store_material_ai_image_task百炼文案、NewAPI 生图、华为 OBS
需求 /requirement-reviewrequirement_review_controller.py、requirement_review_service.pyrequirement_review/public/requirement-review 免登录提交
固定表单 /fixed-formfixed_form_controller.py、fixed_form_service.pyfixed_form、fixed_form_submission/public/fixed-form 免登录提交
系统与监控 /system/*、/monitor/*用户、角色、菜单、字典、参数、任务、日志、在线、缓存和服务 Controller/Servicesys_*、Redis、服务器运行指标调度任务直接影响后台业务,运行前确认幂等和参数

6. 关键端到端业务逻辑 ​

6.1 商户入驻审核 ​

text
商户入驻页面
  -> /merchant/experienceTable
  -> experience_table_service.py
  -> 审核申请资料
  -> 创建/绑定 company、store、store_info
  -> 创建业务有效期、支付类型和内部用户
  -> 发送审核结果短信
  • 普通审核通过会创建公司和门店等基础数据。
  • “小羽佳员工审核”会创建门店并绑定统一公司。
  • 平台产品已经统一,新公司不再复制旧公司的产品数据。
  • 页面看到的易宝入网状态来自 store_info 和 yeepay_innet_record;实际易宝入网提交不在本模块。

6.2 平台产品与标准单 ​

text
platform_product
  -> platform_product_sku
  -> platform_product_mapping
  -> staff_platform_product
  -> standard_staff_service_region
  -> standard_staff_dispatch_pool
  -> 派发尝试/日志
  -> order
  • 产品上架需要有效工种、SKU 和必要的区域/来源映射。
  • 标准单总开关 NATIONAL_STANDARD_ORDER_ENABLED 默认关闭。
  • 默认允许来源为 CLIENT、STORE_QR,默认城市为全部,默认确认时限 15 分钟,路程缓冲 60 分钟。
  • 开启前必须校验收款商户号、服务奖金比例和派发准备状态。
  • 员工候选依赖资料、入网、产品能力、服务区域、状态和时间可用性。
  • 运营中心的审批、人工重排、冻结、奖金、提现和通知重试经内部 Token 调用 storeapi,不能只查 yunapi 日志。

6.3 订单查询、取消和人工派单 ​

订单列表由 order_service.py 组装订单、支付、门店、服务人员和渠道信息。

普通取消:

  1. 已取消、已完成、已评价订单不允许再次取消。
  2. 允许取消时把 order.order_status 改为 99、状态名改为“已取消”。
  3. 该入口不调用第三方支付或渠道取消接口;渠道订单必须按渠道规则处理。

人工派单:

  1. 校验目标订单和员工。
  2. Upsert order_waiter,同步订单员工字段、工资和预计服务时间。
  3. 订单状态为 10 或 30 时推进到 20“派单待确认”。
  4. 状态已经更靠后时只换员工,不回退订单状态。
  5. 将操作人、原因和变更说明写入 order_logs。

6.4 支付宝安心家政广场取消 ​

安心订单通过以下关联识别:

text
demand_square.created_order_number
  -> order.order_number
demand_square.uuid
  -> demand_channel_data.demand_uuid
     且 channel_code = 'anxin_life'

取消入口为 POST /demand-square/anxin-life/cancel/{uuid},仅允许 channel_code='anxin_life':

  1. 渠道已经取消,或需求已过期/已取消时拒绝重复处理。
  2. 有 deduction_order_id 表示已核销,调用核销取消接口。
  3. 没有 deduction_order_id 时调用未核销预约取消接口。
  4. 两条外部接口二选一,不需要先核销取消再执行未核销取消。
  5. 外部成功后把 demand_channel_data.order_status 更新为 cancelled。
  6. 待抢需求改为取消;已抢需求还会清空抢单人和本地订单关联。
  7. 已创建的本地订单仅在未完成、未评价、未取消且不存在 xyj_order_link 时同步取消,否则保留并标记跳过。
  8. 页面优先按安心渠道取消状态显示“已取消”,不会把其他渠道统一套用这套规则。

6.5 门店积分、线索轮派与日结 ​

门店是否能接收自动线索至少取决于:

  • 积分账户已启用,派发状态正常。
  • 公司和门店派发开关开启。
  • 有有效服务区域和已绑定接收人。
  • 钱包余额满足要求,自动接收开关开启。
  • 当前进行中线索、每日规则和其他业务限制允许。

派发不是简单地把所有线索连续给积分第一名。系统先按区域/城市池和积分排行得到基础候选,再结合每日轮派游标、接收开关、余额和占用情况选择。新线索与自动流转共用游标,云平台看板读取同一进度。

夜间策略于2026年10月16日发布调整为仅暂停自动流转,首次派发、通知和成功派发后的游标推进继续。开启时,超时起点取本次派发与最近适用恢复时刻中较晚者,跨夜未查看记录获得完整时限;轮发日以北京时间恢复时刻为边界,不能直接以凌晨日期切换游标。看板与派发服务必须使用相同边界。关闭策略时,沿用本次派发时间连续计时及自然日游标。保留历史配置、派发记录和每条线索已尝试门店;详细验收见线索夜间派发与次日流转规则。

取消与退款边界:

  • 未扣费线索可按业务动作取消,并释放冻结金额、更新派发记录和占用。
  • 已扣费线索不能通过删除主表回退,必须走申诉和退款,保留反向流水及审核记录。
  • 直接删除 jiejie_alliance_lead 不会自动回退门店名额、游标、派发记录或钱包状态。

日结:

  • 使用 MySQL 日期锁和 store_score_settlement_batch 防止同一天并发结算。
  • store_score_transaction.source_key 用于来源幂等,补跑不得绕过。
  • 结算来源包括三嫂业绩、满佣、续约、换人、一次性合同、员工上架和小羽佳开发标准单等。
  • 来源同步任务必须早于日结;补跑按日期从早到晚执行并核对批次。

6.6 钱包迁移与月度品牌费 ​

钱包支持三种读写模式:

模式含义
LEGACY使用历史公司余额和 company_transaction。
DUAL迁移期同时写旧流水与门店钱包,查询按服务层规则合并。
STORE_WALLET以 store_wallet_account 和 store_wallet_transaction 为主。

对公充值、线索扣费和财务查询都可能受模式影响。发现余额或流水不一致时,先查 store_wallet_feature_config,再核对两套流水和幂等键。

月度品牌费页面只负责预演和触发,实际扣款通过内部接口调用 storeapi。当前 monthly_brand_fee_service.py 的目标门店是代码内维护的固定名单,新增或移除门店必须同时评估代码、历史流水和派发暂停/恢复状态。

6.7 合同与保险 ​

  • 合同列表、详情、收款、签名、换人历史和保险记录主要从本地库聚合。
  • 换人、主合同或补签协议重签、生成签署入口、保险重新同步由 contract_management_service.py 调用 storeapi。
  • PDF、Word、Excel 和历史导出任务在 yunapi 生成。
  • 保险对账是本地聚合;中路保障任务写操作通过内部接口调用 storeapi。
  • 退款文档生成包含临时文件锁、电子章主体校验、图片限制、一次性临时 Token 和 Word 生成,失败时应同时查文档状态、文件日志和上传结果。

6.8 素材 AI ​

text
素材页面提交
  -> 百炼生成营销文案
  -> NewAPI 生成或编辑图片
  -> store_material_ai_image_task
  -> pending / processing / completed / failed
  -> 成功图片上传华为 OBS
  -> 发布为 store_material

应用启动时会恢复 pending 和 processing 任务;设置 APP_DISABLE_BACKGROUND_TASKS=true 后不会恢复。排查“任务一直处理中”时要确认 AI 服务响应、任务轮询、应用是否重启、OBS 上传和发布步骤,而不只看页面状态。

6.9 需求评审与固定表单 ​

  • 公开需求提交写入 requirement_review,初始状态为 pending_review。
  • 固定表单提交写入 fixed_form_submission,最多 6 张图片。
  • employee_experience_feedback 固定表单会额外同步一条需求评审记录。
  • 公开接口不要求后台登录,但后端仍记录必要的提交来源信息并执行字段校验。

7. 数据、任务和外部依赖 ​

7.1 核心数据组 ​

数据组代表表主要用途
权限sys_user、sys_role、sys_menu、sys_user_role、sys_role_menu登录用户、菜单、按钮和角色授权
调度与审计sys_job、sys_job_log、sys_oper_log、sys_logininfor任务配置、执行结果、操作与登录证据
商户company、store、store_info、internal_user公司、门店、经营和内部账号
服务人员service_staff、aunt 及其子表服务人员和家政员完整档案
产品与标准单platform_product*、platform_product_mapping、staff_platform_product、standard_staff_*产品、能力、区域、候选和派发
订单与渠道order、order_waiter、order_logs、demand_square、demand_channel_data下单、派单、渠道需求和取消
积分与线索store_score_*、门店派发记录/配置、jiejie_alliance_lead排名、日结、线索派发、申诉和追踪
财务company_transaction、store_wallet_*、company_withdrawal、支付和分账表充值、扣费、提现、收入和钱包迁移
合同保险contract*、保险记录、insurance_surrender_document合同生命周期、收款、保险和退保资料
内容需求training_*、store_material*、requirement_review、fixed_form*培训、素材 AI、需求和反馈表单

7.2 任务入口 ​

任务类型代码入口状态证据
APScheduler 动态任务config/get_scheduler.py、sys_job.invoke_targetsys_job、sys_job_log、云平台“定时任务”
门店积分日结module_task/store_score_settlement_task.pystore_score_settlement_batch、积分流水、任务日志
宝塔积分任务scripts/cron/yun_store_score_daily_settlement_bt.sh脚本日志、HTTP 响应、退出码、结算批次
标准单结算包装任务module_task/standard_order_settlement_task.pysys_job_log 和 storeapi 侧业务记录
简历分享过期module_task/resume_share_expire_task.py任务日志和分享有效期数据
素材 AI 恢复server.py -> MaterialAiService.resume_unfinished_image_tasks()AI 任务表和应用日志

详细参数和补跑要求见云平台计划任务。

7.3 外部依赖 ​

依赖云平台用途失败时查什么
storeapi标准单运营、人员鉴定、合同维护、中路保障、月度品牌费yunapi HTTP 错误、内部凭证配置、storeapi 日志和业务表
支付宝安心接口未核销预约取消、核销取消渠道订单号、核销扣款单号、响应体、demand_channel_data
易宝入网状态、支付、分账和收入数据入网记录、支付/分账记录、第三方状态;入网提交不在商户审核模块
短信服务入驻审核结果等通知模板、接收号码脱敏信息、供应商响应和应用日志
企业微信群机器人任务和运营通知Webhook 配置、通知日志和群机器人状态
百炼 / NewAPIAI 文案与图片模型配置、任务 ID、状态轮询、错误信息
华为 OBS素材图片和文档文件上传结果、对象路径、访问权限;文档中禁止记录 AccessKey

8. 标准排障方法 ​

8.1 判断“前端是否有这个功能” ​

  1. 在本页功能矩阵按业务名称搜索。
  2. 在 yunui/src/views 搜索页面文案或按钮文字。
  3. 看页面 import 的 src/api 文件,确认请求 URL 和 HTTP 方法。
  4. 查 sys_menu 是否有启用菜单,按钮查 menu_type='F' 和权限码。
  5. 查当前角色 sys_role_menu,最后确认线上前端静态资源是否包含该版本。

代码存在不代表生产可见;生产有菜单也不代表当前代码有组件;当前角色无权限时按钮仍会消失。

8.2 页面“没有返回数据” ​

  1. 浏览器 Network 记录 URL、方法、查询参数、响应 code/msg/rows/total。
  2. 在 src/api 找请求函数,在页面找调用时传入的筛选条件。
  3. 在 Controller 找参数别名、默认值和权限依赖。
  4. 在 Service 找状态、公司、门店、时间和删除标记等业务过滤。
  5. 在 DAO 或参数化 SQL 查 JOIN 是否把主记录过滤掉。
  6. 用同样条件执行只读 SQL,禁止先改数据验证猜测。
  7. 如后端有数据而页面没有,再查字段命名、空数组/null、分页和前端状态映射。

8.3 操作成功但其他系统未变化 ​

  1. 确认接口是本地写入还是调用 storeapi/第三方。
  2. 查本地事务是否提交,业务日志或 sys_oper_log 是否存在。
  3. 查远程 HTTP 状态、业务响应和超时;HTTP 200 不一定代表业务成功。
  4. 查远端日志、回调表、outbox 或补偿任务。
  5. 确认另一端读取的是同一字段、同一门店/员工标识,并排除缓存和旧版本前端。

8.4 财务和积分问题 ​

  1. 确认金额单位、业务时间字段、订单状态和退款是否纳入口径。
  2. 查钱包模式,确认旧流水、新钱包或双写。
  3. 查唯一 source_key、请求号或其他幂等键,避免把“未命中”和“重复跳过”混为一谈。
  4. 查任务批次、锁和执行日期;页面最后执行时间、宝塔日志时间和业务归属日期是不同概念。
  5. 修复应走补偿或反向流水,不直接改最终余额。

8.5 只读菜单 SQL 模板 ​

查询当前启用页面和组件:

sql
SELECT
    parent.menu_name AS parent_name,
    menu.menu_name,
    menu.path,
    menu.component,
    menu.perms,
    menu.visible,
    menu.status
FROM sys_menu AS menu
LEFT JOIN sys_menu AS parent
    ON parent.menu_id = menu.parent_id
WHERE menu.menu_type IN ('M', 'C')
  AND menu.status = :enabled_status
ORDER BY menu.parent_id, menu.order_num, menu.menu_id;

查询指定用户通过角色获得的菜单权限:

sql
SELECT DISTINCT
    menu.menu_id,
    menu.menu_name,
    menu.component,
    menu.perms,
    menu.menu_type,
    menu.visible,
    menu.status
FROM sys_user_role AS user_role
INNER JOIN sys_role_menu AS role_menu
    ON role_menu.role_id = user_role.role_id
INNER JOIN sys_menu AS menu
    ON menu.menu_id = role_menu.menu_id
WHERE user_role.user_id = :user_id
ORDER BY menu.parent_id, menu.order_num, menu.menu_id;

执行前先用 DESCRIBE 核对目标环境字段;只读查询使用参数,不在文档或聊天中保存真实账号和客户数据。

9. 已知风险与维护规则 ​

风险当前结论维护要求
菜单和组件漂移有两个启用菜单对应组件缺失上线前自动或人工核对 sys_menu.component 与 src/views。
跨系统写操作多个云平台按钮实际调用 storeapi变更时同时核对两边接口契约、权限、日志和回滚。
钱包双轨公司旧余额和门店钱包处于兼容期所有充值、扣费、退款、品牌费改动先确认读写模式。
月度品牌费固定名单目标门店写在 Service 代码中调整名单必须走代码评审,不能只改页面或数据库。
超大积分 Service派发、钱包、日结、映射集中在一个文件修改前先定位具体方法和调用者,运行对应测试并抽样真实数据。
渠道取消差异普通订单取消与安心渠道取消不是同一动作根据渠道走专用接口,禁止用本地状态覆盖第三方事实。
任务多入口APScheduler、宝塔脚本、启动恢复任务并存先识别执行器和锁,再补跑,避免重复执行。
配置文件安全部署配置中可能存在明文敏感值不复制到文档;应迁移到受控环境变量并轮换已暴露凭据。

10. 代码变更后的验证 ​

变更类型最低验证
yunui 页面npm run lint 或目标测试、npm run build:prod、目标角色实测菜单和按钮
yunapi 查询接口目标测试、真实参数只读联调、分页和空数组/null 形态检查
写接口成功、拒绝、重复提交、事务回滚、操作日志和权限用例
菜单组件文件存在、菜单 SQL、角色授权、刷新 /getRouters 后实测
定时任务dry-run、锁、幂等、业务日期、任务日志、批次和失败重试
财务金额精度、双轨模式、幂等键、流水证据和反向补偿方案
跨系统yunapi 与 storeapi 契约、内部凭证、超时、错误透传和两边日志

11. 给 AI 的推荐阅读顺序 ​

新会话处理云平台问题时,依次读取:

  1. 本页,建立源码、页面和业务全局地图。
  2. 云平台技术模块目录,快速定位模块文件。
  3. 云平台数据与配置模型,了解关键表、配置和状态。
  4. 与问题对应的产品或运维专题文档。
  5. 目标 yunui 页面和 API 文件。
  6. 目标 yunapi Controller、Service、DAO,再按需只读查库和查日志。

推荐给 AI 的任务上下文:

text
先阅读 yun/technical/source-code-business-guide.md。
按“页面 -> 前端 API -> 后端 Controller -> Service -> DAO/SQL -> 数据表/外部系统”链路定位。
先只读查询和日志核实,不凭字段名猜业务,不直接修改生产数据。
涉及钱包、积分、渠道取消、合同、保险或 storeapi 时,必须核对跨系统边界、幂等和回滚。

12. 文档维护清单 ​

发生以下变化时同步更新本页:

  • 新增、删除或重命名 src/views 页面。
  • sys_menu 菜单、组件路径或权限码变化。
  • Controller 路由前缀、Service 归属或主表变化。
  • 新增第三方依赖、跨系统调用或后台任务。
  • 订单、积分、钱包、合同、保险等关键状态规则变化。
  • 发现新的生产菜单与代码漂移。

专题细节更新到对应文档,本页只保留稳定的架构、入口、主链路和风险索引,避免成为无法维护的代码逐行复述。

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