云平台源码与业务导航

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

1. 文档用途

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

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

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

2. 五分钟理解系统

2.1 系统职责

项目	技术栈	主要职责	关键目录
`yunui`	Vue 2、Vue Router、Vuex、Element UI、Axios	云平台运营后台、查询、审核、配置、统计、导出和人工兜底	`src/views`、`src/api`、`src/router`、`src/store`
`yunapi`	FastAPI、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.js`	Axios 基础地址、Bearer Token、GET 参数转换、1 秒重复提交保护、业务码和 401 处理。
`yunui/src/directive/permission/hasPermi.js`	`v-hasPermi` 按按钮权限码控制操作入口。

登录后的关键顺序是：

text

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

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

src/views 中存在组件代码。
sys_menu 中存在启用的菜单或按钮权限。
当前角色通过 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/403	`login_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.js`	`dashboard_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.js`	`requirement_review_controller.py` 的公共路由
固定表单 `/fixed-form/:formKey`	免登录填写指定表单，最多上传 6 张图片	`views/fixedForm/public/index.vue`、`api/fixedForm/index.js`	`fixed_form_controller.py` 的公共路由
个人中心 `/user/profile`	修改资料、头像和密码	`views/system/user/profile/*`、`api/system/user.js`	`user_controller.py`；登录用户

4.2 商户与服务人员

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

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

4.3 产品、订单与线索

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

4.4 财务、合同与保险

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

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

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

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 / Service	DAO 或核心表	外部依赖与边界
登录权限 `/login`、`/getInfo`、`/getRouters`	`login_controller.py`、`login_service.py`、`menu_service.py`	`sys_user`、`sys_role`、`sys_menu`、`sys_user_role`、`sys_role_menu`	JWT 和 Redis 会话
商户入驻 `/merchant/experienceTable`	`experience_table_controller.py`、`experience_table_service.py`	`experience_table`、`follow_up_record`、`company`、`store`、`store_info`、`internal_user`、`yeepay_innet_record`	审核短信；这里只查询易宝入网结果，不负责真实入网提交
公司 `/merchant/company`	`company_controller.py`、`company_service.py`、`company_dao.py`	`company`、`store`、公司版本、业务有效期、`company_transaction`	API 凭据生成、充值和提现联动
门店 `/merchant/store`	`store_controller.py`、`store_service.py`、`store_dao.py`	`store`、`store_info`、`pay_type`、`yeepay_innet_record`	门店经营资料和入网查询
客户 `/merchant/ccuser`	`ccuser_controller.py`、`ccuser_service.py`、`ccuser_dao.py`	`ccuser`	本地业务库
内部员工 `/merchant/internal-user`	`internal_user_controller.py`、`internal_user_service.py`、`internal_user_dao.py`	`internal_user`、`internal_user_permission`、公司门店关联	门店端账号和权限
家政员 `/merchant/aunt`	`aunt_controller.py`、`aunt_service.py`、`aunt_dao.py`	`aunt` 及家庭、图片、证书、技能、培训、保险、关注、操作日志子表	本地聚合档案
服务人员 `/merchant/serviceStaff`	`service_staff_controller.py`、`service_staff_service.py`、`service_staff_dao.py`	`service_staff`、证书、培训、保险、合同、评价、订单关联	只读聚合为主
人员鉴定 `/merchant/staff-appraisal`	`staff_appraisal_controller.py`、`staff_appraisal_admin_service.py`	鉴定、站长和地区配置相关表	受保护桥接调用 `storeapi`，写操作不在 `yunapi` 本地实现
全国标准单 `/merchant/standard-staff`	`standard_staff_controller.py`、`standard_staff_service.py`	`standard_staff_`、`staff_platform_product`、`platform_product`、派发/奖金/提现/通知相关表	本地预检查询；审批、冻结、重排、提现、通知重试等调用 `storeapi`
平台产品 `/merchant/platformProduct`	`platform_product_controller.py`、`platform_product_service.py`、`platform_product_dao.py`	`platform_product`、`platform_product_sku`、`platform_product_mapping`、区域价格表	标准单产品与来源映射
产品同步 `/merchant/productSync`	`product_sync_controller.py`、`product_sync_service.py`	`product`、`product_sku`、`service_product`、映射表	`xyj_standard_order_client.py` 调用外部标准单能力
积分商城 `/product/points-goods`、`/product/points-orders`	`points_goods/order_controller.py`、对应 Service	`sys_goods*`、积分订单表	发货属于写操作
订单 `/order`	`order_controller.py`、`order_service.py`、`order_dao.py`	`order`、`order_waiter`、`order_logs`、支付与门店员工关联	普通取消只改本地订单，不调用第三方取消
家政广场 `/demand-square`	`demand_square_controller.py`、`demand_square_service.py`、`demand_square_dao.py`	`demand_square`、`demand_channel_data`、`order`、`xyj_order_link`	支付宝安心取消接口；其他渠道不会进入该取消逻辑
门店积分 `/merchant/store-score`	`store_score_controller.py`、`store_score_service.py`	`store_score_*`、派发配置/记录/游标、钱包和渠道映射表	日结、线索派发、账户、排行、钱包兼容逻辑集中于超大 Service
线索跟踪 `/lead/tracking`	`lead_tracking_controller.py`、`lead_tracking_service.py`、`lead_tracking_dao.py`	`jiejie_alliance_lead`、门店派发记录、轨迹和候选数据	查询统计和完整派发上下文
派发申诉 `/lead/dispatch-appeal`	`lead_dispatch_appeal_controller.py`、`lead_dispatch_appeal_service.py`	申诉、派发记录、钱包流水	已扣费取消应走申诉/退款，不直接删除线索
资金流水 `/finance/transaction`	`company_transaction_controller.py`、`company_transaction_service.py`	`company_transaction`	旧公司余额体系
充值 `/finance/recharge`	`recharge_management_controller.py`、`recharge_management_service.py`	充值记录、`company_transaction`、`store_wallet_transaction`	按钱包灰度模式决定写旧账、新钱包或双写
提现 `/finance/withdrawal`	`company_withdrawal_controller.py`、`company_withdrawal_service.py`	`company_withdrawal` 及相关资金流水	审核、处理和取消分阶段执行
钱包灰度 `/finance/store-wallet-feature`	`store_wallet_feature_controller.py`、`store_wallet_feature_service.py`	`store_wallet_feature_config`、`store_wallet_account`	`LEGACY`、`DUAL`、`STORE_WALLET` 读写模式
月度品牌费 `/finance/monthly-brand-fee`	`monthly_brand_fee_controller.py`、`monthly_brand_fee_service.py`	公司和门店钱包流水、`store_score_account`	云平台负责预演和触发，实际扣款调用 `storeapi` 内部任务
其他财务 `/finance/*`	软件收入、平台收入、平台统计、渠道收入、灵工分账、门店流水 Controller/Service	订单、支付、分账、易宝和钱包相关表的聚合	每个页面统计口径不同，必须以对应 Service 为准
合同 `/contract/management`、`/contract/revenue`	`contract_management/revenue_controller.py`、对应 Service	`contract`、`contract_payment`、`contract_supply`、签名、换人和导出任务表	换人、重签、签署入口和保险重同步调用 `storeapi`
保险 `/insurance/*`	对账、退款文档、退保审核 Controller/Service	保险记录、订单日志、`insurance_surrender_document`	中路保障任务调用 `storeapi`；文档生成涉及模板、临时文件和电子章
培训 `/training/categories`、`/training/courses`	对应 Controller/Service/DAO	`training_categories`、`training_courses`	本地内容管理
素材 `/training/materials`	`store_material_controller.py`、`store_material_service.py`、`material_ai_service.py`	`store_material*`、`store_material_ai_image_task`	百炼文案、NewAPI 生图、华为 OBS
需求 `/requirement-review`	`requirement_review_controller.py`、`requirement_review_service.py`	`requirement_review`	`/public/requirement-review` 免登录提交
固定表单 `/fixed-form`	`fixed_form_controller.py`、`fixed_form_service.py`	`fixed_form`、`fixed_form_submission`	`/public/fixed-form` 免登录提交
系统与监控 `/system/`、`/monitor/`	用户、角色、菜单、字典、参数、任务、日志、在线、缓存和服务 Controller/Service	`sys_*`、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 组装订单、支付、门店、服务人员和渠道信息。

普通取消：

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

人工派单：

校验目标订单和员工。
Upsert order_waiter，同步订单员工字段、工资和预计服务时间。
订单状态为 10 或 30 时推进到 20“派单待确认”。
状态已经更靠后时只换员工，不回退订单状态。
将操作人、原因和变更说明写入 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'：

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

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

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

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

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

取消与退款边界：

未扣费线索可按业务动作取消，并释放冻结金额、更新派发记录和占用。
已扣费线索不能通过删除主表回退，必须走申诉和退款，保留反向流水及审核记录。
直接删除 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_target`	`sys_job`、`sys_job_log`、云平台“定时任务”
门店积分日结	`module_task/store_score_settlement_task.py`	`store_score_settlement_batch`、积分流水、任务日志
宝塔积分任务	`scripts/cron/yun_store_score_daily_settlement_bt.sh`	脚本日志、HTTP 响应、退出码、结算批次
标准单结算包装任务	`module_task/standard_order_settlement_task.py`	`sys_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 配置、通知日志和群机器人状态
百炼 / NewAPI	AI 文案与图片	模型配置、任务 ID、状态轮询、错误信息
华为 OBS	素材图片和文档文件	上传结果、对象路径、访问权限；文档中禁止记录 AccessKey

8. 标准排障方法

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

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

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

8.2 页面“没有返回数据”

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

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

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

8.4 财务和积分问题

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

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 的推荐阅读顺序

新会话处理云平台问题时，依次读取：

本页，建立源码、页面和业务全局地图。
云平台技术模块目录，快速定位模块文件。
云平台数据与配置模型，了解关键表、配置和状态。
与问题对应的产品或运维专题文档。
目标 yunui 页面和 API 文件。
目标 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 归属或主表变化。
新增第三方依赖、跨系统调用或后台任务。
订单、积分、钱包、合同、保险等关键状态规则变化。
发现新的生产菜单与代码漂移。

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

云平台源码与业务导航 ​

1. 文档用途 ​

2. 五分钟理解系统 ​

2.1 系统职责 ​

2.2 请求链路 ​

2.3 前端启动与权限 ​

2.4 后端启动与响应 ​

3. 遇到问题先查哪里 ​

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

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

4.2 商户与服务人员 ​

4.3 产品、订单与线索 ​

4.4 财务、合同与保险 ​

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

4.6 菜单与代码漂移 ​

5. 后端业务域矩阵 ​

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

6.1 商户入驻审核 ​

6.2 平台产品与标准单 ​

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

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

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

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

6.7 合同与保险 ​

6.8 素材 AI ​

6.9 需求评审与固定表单 ​

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

7.1 核心数据组 ​

7.2 任务入口 ​

7.3 外部依赖 ​

8. 标准排障方法 ​

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

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

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

8.4 财务和积分问题 ​

8.5 只读菜单 SQL 模板 ​

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

10. 代码变更后的验证 ​

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

12. 文档维护清单 ​

云平台源码与业务导航

1. 文档用途

2. 五分钟理解系统

2.1 系统职责

2.2 请求链路

2.3 前端启动与权限

2.4 后端启动与响应

3. 遇到问题先查哪里

4. 前端页面与功能矩阵

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

4.2 商户与服务人员

4.3 产品、订单与线索

4.4 财务、合同与保险

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

4.6 菜单与代码漂移

5. 后端业务域矩阵

6. 关键端到端业务逻辑

6.1 商户入驻审核

6.2 平台产品与标准单

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

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

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

6.6 钱包迁移与月度品牌费

6.7 合同与保险

6.8 素材 AI

6.9 需求评审与固定表单

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

7.1 核心数据组

7.2 任务入口

7.3 外部依赖

8. 标准排障方法

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

8.2 页面“没有返回数据”

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

8.4 财务和积分问题

8.5 只读菜单 SQL 模板

9. 已知风险与维护规则

10. 代码变更后的验证

11. 给 AI 的推荐阅读顺序

12. 文档维护清单