Appearance
金刚系统技术模块目录
本页按 storeui 和 storeapi 的真实目录整理金刚系统模块。接手时先按业务域定位，再查对应页面、API、controller、service 和表组。
如果要按角色阅读完整小程序能力，先看：
模块总览
当前代码规模按 2026-07-19 本地扫描记录：
| 项目 | 规模 | 接手意义 |
|---|---|---|
| 小程序页面路由 | storeui/src/pages.json 共 181 个页面路由，含 7 个主包页面和 4 个底部 tab；门店端开发单位于首页补充分包，pages/dispatch/index 仅保留为历史普通页和内部回退路径。 | 先按分包定位业务域，不要在全局搜索里直接改同名页面。 |
| 小程序 API 封装 | storeui/src/api 覆盖门店、员工、合同、保险、钱包、积分、易宝、素材、培训等接口域。 | 前端页面通常不直接写完整 URL，先查对应 API 封装。 |
| 后端注册路由 | storeapi/server.py 当前注册 115 个 router。 | 后端 controller 数量大，优先按 tag/前缀定位，再追 service。 |
| 核心生产数据 | 公司 662、门店 487、门店账号 739、服务人员 2925、订单 1515、客户 2198、合同 1434、保险记录 1652。 | 门店、员工、合同、保险是已经有生产沉淀的链路，修复前必须只读核验影响范围。 |
| 新标准单沉淀 | staff_service_capability 41 条、staff_platform_product 219643 条、standard_staff_service_region 97 条、standard_staff_score_account 41 条；staff_wallet_account、standard_staff_dispatch_attempt、standard_order_settlement_task、通知 outbox 当前为 0 条。 | 员工能力和产品绑定已有数据，真实派发、通知、结算和员工钱包流水尚未形成生产沉淀，放量时要重点看任务和配置。 |
| 业务域 | 小程序入口 | API 封装 | 后端 controller | 主要 service | 主要表组 |
|---|---|---|---|---|---|
| 登录与身份 | pages/login、pages-login-aux、pages-staff/home | auth.js、staff-auth.js、user.js | auth_controller.py、service_staff_login_controller.py、internal_login_controller.py | auth_service.py、service_staff_login_service.py、internal_user_login_service.py | internal_user、service_staff、internal_login_record |
| 首页与角色切换 | pages/home、pages/my、components/role-switcher | common.js、dashboard.js、announcement.js | common_controller.py、data_dashboard_controller.py、announcement_controller.py | common_service.py、data_dashboard_service.py、announcement_service.py | sys_config、content_banner、store_notice |
| 订单履约 | pages-dispatch、pages-staff/service/record.vue、pages-common/select-server-person | order.js、staff-order.js、payment.js | order_controller.py、staff_order_controller.py、payment_controller.py、order_evaluation_controller.py | order_service.py、staff_order_service.py、payment_service.py、order_evaluation_service.py | order、order_details、order_logs、order_waiter |
| 全国标准单 | pages-staff/home/index.vue、pages-staff/availability、pages-staff/capability、pages-staff/wallet | staff-availability.js、staff-capability.js、staff-wallet.js、staff-order.js | internal_standard_order_ops_controller.py、staff_availability_controller.py、staff_capability_controller.py、staff_wallet_controller.py | standard_staff_dispatch_service.py、standard_order_operation_service.py、standard_order_settlement_service.py、standard_order_notification_service.py | standard_staff_*、standard_order_*、staff_wallet_* |
| 员工管理 | pages/staff、pages-staff/edit.vue、pages-staff/apprentice、pages-staff/station-contact | staff.js、staff-apprentice.js、staff-station-contact.js | staff_controller.py、staff_apprentice_controller.py、staff_station_contact_controller.py | staff_service.py、staff_management_service.py、staff_apprentice_service.py、staff_station_contact_service.py | service_staff、service_staff_ext、staff_mentor_* |
| 员工服务能力 | pages-staff/capability/index.vue、pages-staff/availability/index.vue | staff-capability.js、staff-availability.js | staff_capability_controller.py、staff_availability_controller.py | staff_capability_service.py、staff_availability_service.py、standard_staff_schedule_service.py | staff_service_capability、standard_staff_service_region、staff_rest_date |
| 员工钱包与提现 | pages-staff/wallet/index.vue、pages-staff/select-account.vue、pages-staff/yeepay-innet | staff-wallet.js、withdrawal-account.js、yeepay-innet.js | staff_wallet_controller.py、withdrawal_account_controller.py、yeepay_innet_controller.py | staff_wallet_service.py、staff_withdrawal_payout_service.py、withdrawal_account_service.py、yeepay_innet_service.py | staff_wallet_account、staff_wallet_ledger、staff_withdrawal_application、yeepay_innet_record |
| 门店与公司 | pages-set/storeManagement、pages-set/staffManagement | store.js、staff.js | store_controller.py、company_controller.py、internal_user_controller.py | store_service.py、company_service.py、internal_user_service.py | store、store_info、company、internal_user |
| 门店积分 | pages-home/sign-in、pages-capital-flow 部分入口 | lead-dispatch-config.js、common.js | store_score_controller.py、lead_pricing_controller.py、lead_dispatch_appeal_controller.py | store_score_service.py、jiejie_alliance_lead_dispatch_service.py、lead_pricing_service.py | store_score_*、store_lead_dispatch_* |
| 门店钱包与收款 | pages-capital-flow、pages-other/yeepay-innet | payment.js、withdrawal-account.js、yeepay-innet.js | store_payment_controller.py、payment_controller.py、yeepay_plate_controller.py、yeepay_divide_controller.py | store_payment_service.py、payment_service.py、store_wallet_service.py、yeepay_split_service.py | store_wallet_*、store_payment_order、company_transaction、yeepay_* |
| 合同 | pages-agreement、pages-set/contractSetting、pages-sister-business/contract-templates | sister-business.js、payment.js、common.js | contract_controller.py、contract_supply_controller.py、contract_resign_controller.py、agreement_signature_controller.py | contract_service.py、contract_supply_service.py、contract_word_export_service.py、agreement_signature_service.py | contract、contract_supply、contract_payment、contract_signature |
| 保险 | pages-home/insurance、pages-insurance、pages-staff/insurance-purchase.vue | insurance.js | insurance_controller.py、insurance_payment_controller.py、picc_insurance_controller.py、insurance_surrender_document_controller.py | insurance_service.py、insurance_payment_service.py、picc_insurance_service.py、insurance_surrender_document_service.py | insurance_*、contract_insurance、alipay_anxin_* |
| 产品与工种 | pages-set/serviceProjects、pages-home/product-list.vue | product.js、skill.js | product_controller.py、skill_controller.py | product_service.py、platform_product_service.py、staff_skill_service.py | product、product_sku、service_skill、platform_product |
| 简历与阿姨资料 | pages-aunt-resume、pages-staff/resume*、pages-staff/ai-aunt-chat.vue | aunt.js、aunt-resume.js、ai-register.js | aunt_controller.py、platform_aunt_controller.py、resume_share_controller.py、public_ai_aunt_controller.py | aunt_service.py、aunt_resume_service.py、resume_share_service.py、public_ai_aunt_match_service.py | aunt、aunt_detail、aunt_certificate、resume_share_validity |
| 培训与内容 | pages-home/train-online.vue、pages-home/announcement | training.js、announcement.js | training_controller.py、public_training_controller.py、announcement_controller.py | training_service.py、announcement_service.py | training_*、college_*、content_banner |
| 素材、海报和分享 | pages-staff/development-poster、pages-other/haibao、pages-share | store-material.js、platform-share.js、store-channel.js | store_material_controller.py、store_recruit_controller.py、store_share_controller.py、platform_share_controller.py | store_material_service.py、store_recruit_service.py、store_share_application_service.py、platform_share_service.py | store_material_*、store_recruit_*、platform_share_membership |
| 数据看板与工具 | pages/data-dashboard、pages-home/assessment-result.vue | dashboard.js、customer-insight.js | data_dashboard_controller.py、customer_insight_controller.py、public_customer_insight_controller.py | data_dashboard_service.py、customer_insight_service.py | customer_insight、daily_points_grant_record |
后端启动和路由注册
storeapi/server.py 是金刚后端主入口。它负责：
- 初始化数据库、Redis、异常处理、CORS 和静态资源。
- 注册
module_admin/controller下的 controller。 - 初始化系统调度器。
- 在云函数环境中承接小程序、内部任务、第三方回调和公开接口。
所有新增业务接口都应遵循现有结构：
| 层级 | 规范 |
|---|---|
| controller | 只负责鉴权、参数接收、调用 service、返回统一响应。 |
| service | 负责事务、业务规则、第三方调用、状态变更和日志。 |
| dao/entity/vo | 有现成模型时复用，没有必要时可用 SQLAlchemy text 查询，但必须保持事务边界清楚。 |
| scripts/module_task | 需要后台补偿、批处理、日结、超时处理时放到任务入口，不依赖请求结束后的后台线程。 |
小程序页面边界
| 分区 | 说明 |
|---|---|
主包 pages/* | home 首页、staff 服务人员、data-dashboard 数据大盘、dispatch 历史标准单普通页面、sister-business 三嫂业务、my 我的。 |
pages-staff | 员工端核心分包，包含服务首页、我的、接单、服务记录、能力、档期、钱包、签名、入驻、入网、发展海报和队员管理。 |
pages-set | 门店设置、门店管理、员工管理、服务项目、合同设置、资质、公章和个人设置。 |
pages-capital-flow | 余额、充值、对公充值、提现、提现账户、易宝入网、收款码、积分商城相关页面。 |
pages-dispatch | 门店到家订单详情、编辑、新建预约、派工、收服务费、自动化设置、补价和保险入口。 |
pages-agreement | 合同列表、新增、编辑、搜索、合同组件。 |
pages-sister-business | 三嫂客户、线索、合同、保险、家务清单等旧业务页面；保单入口仍从首页复用，但小羽佳订单协同旧链路不在本次交接展开。 |
pages-insurance | 理赔、报案、退保材料。 |
pages-aunt-resume | 阿姨简历资料、AI 录入、预览、分享封面。 |
pages-home / pages-home-sub | 公告、家政人广场、体检、线上培训、全部功能、开发单统计、派发配置、素材。 |
身份和入口判定
同一个 storeui 小程序里同时承载门店端和员工端，不是两个独立应用。
| 判定点 | 门店端 | 员工端 |
|---|---|---|
| token | token | staffToken |
| 当前角色 | currentRole = store | currentRole = staff |
| 登录主表 | internal_user | service_staff |
| 登录校验接口 | /api/v1/internal-login/getInfo | /api/v1/staff-login/getinfo |
| 切换接口 | /api/v1/staff-login/switch-to-store | /api/v1/staff-login/switch-account |
| 入口页面 | 主包 pages/home/index.vue、pages/my/index.vue | 分包 pages-staff/home/index.vue、pages-staff/home/my.vue |
排查登录和入口错乱时，先看 tokenManager.getCurrentRole() 和本地是否同时有门店 token、员工 token。角色切换由 roleManager 调用后端换 token，再清理当前角色缓存；不要只改页面跳转。
核心链路定位
订单履约
- 小程序从订单列表、员工服务首页或服务记录页进入。
storeui/src/api/order.js、staff-order.js调用后端。order_controller.py、staff_order_controller.py进入order_service.py、staff_order_service.py。- 主状态在
order，过程日志在order_logs，员工关系看order_waiter或订单员工字段。 - 支付相关同时查
order_payments、store_payment_order、ccuser_transaction。
全国标准单自动交付
- 平台标准产品在云平台配置，金刚后端按平台产品、员工能力、区域、档期和积分计算候选。
- 待派发订单由
standard_staff_dispatch_pending任务处理。 - 员工确认超时由
standard_staff_dispatch_timeout任务处理。 - 服务完成后由
standard_order_settlement_process生成服务奖金结算。 - 通知由
standard_order_notification_process消费 outbox。
关键常量和规则：
| 项 | 值或规则 |
|---|---|
| 平台标准单虚拟门店 | PLATFORM_STANDARD_STORE_UUID = pQrS6tUvwx，名称“金刚到家”。 |
| 平台标准单业务模式 | business_mode = PLATFORM_STANDARD_SOURCE。 |
| 历史门店订单业务模式 | business_mode = LEGACY。 |
| 城市口径 | ALLOWED_CITY_CODES 控制自动派发城市范围，当前为 ["*"]；配置为全国时厦门也进入候选。代码中有厦门判断函数，但当前派发主流程没有内置厦门排除分支。 |
| 候选范围 | 普通全国派发按区县、城市、省、全国兜底；金刚下单端内部派发只按区县和城市，不自动扩大到省/全国。 |
| 候选排序 | SCORE_WAITING、SCORE_ONLY、RANK_ONLY 三种，默认积分加等待天数。 |
门店订单和员工履约状态口径
历史订单和标准单状态都落在 order.order_status，但页面和老 DAO 中存在兼容口径。接手时按业务模式判断，不要混用。
| 状态码 | 标准单/员工端含义 | 备注 |
|---|---|---|
10 | 已接单 | 生产库中仍有历史数据。 |
20 | 派单待确认 | 员工可接单或拒单。 |
30 | 拒绝接单 | 标准单拒单后会触发候选顺延。 |
40 | 已派单 | 员工确认后进入待服务。 |
50 | 执行中 | 员工前往或执行准备中。 |
60 | 开始服务 | 已上传服务前凭证并开始。 |
70 | 服务结束 | 兼容旧流程，后续可到完成。 |
80 | 已完成 | 会触发档期释放、结算任务、开发奖金任务等后续动作。 |
90 | 已评价/历史完成态 | 生产库中状态名多为“已完成”。 |
99 | 已取消 | 取消时还要同步支付、需求广场、档期/库存和第三方通知。 |
真实库里存在少量“状态码和状态名不一致”的历史记录，例如 20/已派单、80/服务结束。排查时以状态码和日志为主，状态名只作展示参考。
合同保险
- 合同购买、续费、换人、补充协议都先看
contract_*。 - 支付通过
payment_service.py或合同支付回调处理。 - 保险投保记录看
insurance_record，合同和保险关联看contract_insurance。 - 退保材料生成看
insurance_surrender_document和退保操作日志。
钱包和分账
- 门店钱包看
store_wallet_*，员工钱包看staff_wallet_*。 - 易宝入网看
yeepay_innet_record，收款码看yeepay_plate_qrcode。 - 分账、余额和回调失败要查
yeepay_notification_log和业务流水。
不写入主线的旧模块
仓库中仍存在 xyj_migration_controller.py、旧外部订单协同、colleague_order_*、xyj_order_* 相关代码和表。本次交接不展开这些细节，避免接手人误以为这是未来维护主线。