Appearance
金刚门店端完整模块与逻辑
本页只写金刚小程序门店端和管理端能力。门店端用于门店管理人员处理员工、客户、合同、保险、服务项目、资金、入网、线索、素材和系统设置。
门店端入口
| 模块 | 页面 | API | 后端 | 主要数据 |
|---|---|---|---|---|
| 首页和设置 | pages/home/index.vue、pages-set/index.vue | common.js、auth.js、staff.js | common_controller.py、auth_controller.py | company、store、internal_user |
| 门店管理 | pages-set/storeManagement/* | 直接调用 /api/v1/store/* | store_controller.py、store_service.py | store、store_info、store_qualification |
| 员工管理 | pages-set/staffManagement/*、pages-home/attendantManage* | staff.js、ai-register.js | staff_controller.py、product_controller.py | service_staff、service_staff_ext、internal_user |
| 服务项目 | pages-set/serviceProjects/*、pages-home/product-list.vue | product.js、skill.js、ai-image.js | product_controller.py、product_service.py | product、product_sku、service_skill、platform_product |
| 订单和代下单 | pages-home/sub-po.vue、pages-dispatch | order.js、client.js、sister-business.js | order_controller.py、order_service.py | order、order_details、customer |
| 需求广场和线索 | pages-home/demand-square.vue | demand-square.js、platform-share.js | demand_square_controller.py、lead_* | demand_square、store_score_*、store_lead_dispatch_* |
| 合同管理 | pages-agreement/*、pages-set/contractSetting/* | sister-business.js | contract_controller.py、contract_supply_controller.py | contract、contract_payment、contract_supply、contract_signature |
| 保险 | pages-home/insurance/*、pages-insurance/* | insurance.js | insurance_controller.py、insurance_surrender_document_controller.py | insurance_record、insurance_claim、insurance_surrender_document |
| 资金余额 | pages-capital-flow/balance-manage.vue、recharge.vue、toUp-Public.vue | payment.js | payment_controller.py、store_payment_controller.py | company_transaction、store_wallet_*、store_payment_order |
| 提现账户 | pages-capital-flow/withdrawal* | payment.js、withdrawal-account.js | payment_controller.py、withdrawal_account_controller.py | withdrawal_account、withdrawal、company_withdrawal |
| 易宝入网和收款码 | pages-capital-flow/store-innet.vue、innet-status.vue、plate-qrcode.vue | yeepay-innet.js | yeepay_innet_controller.py、store_payment_controller.py | yeepay_innet_record、yeepay_plate_qrcode |
| 积分商城 | pages-capital-flow/coins-mall/* | coins-mall.js、payment.js | coins_mall_controller.py、store_score_service.py | sys_goods*、store_score_* |
| 公章和印章 | pages-set/seal-generator、pages-set/seal-management | seal.js | store_seal_controller.py、company_seal_controller.py | store_seal、company_seal、文件表 |
| 渠道二维码 | components/store-channel-modal、store-channel.js | store-channel.js | store_channel_controller.py | store_channel、promotion_code_visit |
| 培训公告素材 | pages-home/train-online.vue、announcement/*、素材页面 | training.js、announcement.js、store-material.js | training_controller.py、announcement_controller.py、store_material_controller.py | training_*、store_material_* |
首页和全部功能真实入口
门店端首页不是完整菜单，只放高频入口和经营概览。更多功能在 pages-home-sub/home/all-functions.vue。
| 入口区域 | 功能 | 跳转/逻辑 | 限制 |
|---|---|---|---|
| 顶部切换 | 切换到接单端 | 调用角色切换，进入员工端 token 和页面 | 需要手机号能匹配员工账号。 |
| 顶部客服 | 联系客服 | 跳转在线客服或联系客服逻辑 | 无特殊业务写入。 |
| 账户余额 | 余额管理 | /pages-capital-flow/balance-manage | 合同维护员不可用。 |
| 门店二维码 | 渠道二维码弹窗 | store-channel 接口拉渠道并生成二维码 | 合同维护员不可生成。 |
| 快捷入口 | 线索、保单、开发单、全部 | 线索和保单进入三嫂业务对应 tab；开发单进入门店码开发订单统计页；全部进入全部功能页 | 合同维护员只保留少量入口。 |
| 家政人广场 | 到家/到店线索统计 | 按版本选择 business_type=1/2 拉需求广场统计 | 合同维护模式不可进入。 |
| 业务概览 | 服务人员、客户、订单 | 客户和订单统计可进入开发单页查看门店码开发订单和开发奖金 | 客户和订单受合同维护模式限制。 |
全部功能页分 4 组：
| 分组 | 功能 |
|---|---|
| 经营常用 | 开发单、服务人员。 |
| 线索与增长 | 家政人广场、到店线索、派发配置、通知公告。 |
| 营销服务 | 商家培训、家政保险、历史保单、产品价格表、简历模板、素材。 |
| 财务与设置 | 余额管理、积分兑换、充值、入网管理、系统设置。 |
派发配置 只对公司管理员展示。合同维护模式下仅允许“服务人员”和“历史保单”，其他入口会被过滤。
门店首页和账号
门店端首页展示门店核心入口和常用统计。账号逻辑和员工端不同：门店端以 internal_user、公司和门店权限为主，员工端以 service_staff 为主。
| 场景 | 逻辑 |
|---|---|
| 门店进入首页 | 读取当前公司、门店、角色和版本能力，展示对应入口。 |
| 角色切换 | 门店账号可以切换到员工账号，员工也可以切回门店管理端，但必须验证权限。 |
| 公众号绑定 | 门店端可以生成二维码绑定公众号，用于接收运营消息。 |
| 子账号 | 员工管理里可以维护内部用户和角色，限制可编辑目标。 |
排查入口缺失时，先看账号角色、公司版本、菜单入口和后端权限，不要只看前端按钮。
公司和门店主数据
| 主体 | 关键字段/含义 | 影响功能 |
|---|---|---|
company | balance、frozen_amount、withdrawal_fee_rate、split_fee_rate、unified_expire_time、store_service_expire_time、contract_maintenance_mode、印章字段 | 首页余额、版本到期、提现/分账费率、合同维护员模式、公章。 |
store | store_uuid、company_id、status、store_status、mini_qr_url、score、coins_balance、settle_to_staff、square_split_mode、contract_party_name_source | 门店归属、二维码、积分/金币、广场分账、合同主体来源、是否结算到员工。 |
internal_user | company_id、store_uuid、role_id、权限扩展 | 门店账号可见范围和操作能力。 |
门店端大多数接口不是只看 store_uuid。公司负责人可看公司范围，门店负责人看门店范围，部分店员回退到门店范围；订单 DAO 里个人级过滤曾因数据不完整被放宽，后续若补齐 sale_user_uuid 再收紧。
门店管理
门店管理包括门店列表、详情、资料、资质和统计。
| 页面 | 功能 |
|---|---|
storeList.vue | 查询门店列表和门店数量。 |
storeInfo.vue | 查看和更新门店基本信息。 |
storeDetail.vue | 查看门店扩展资料。 |
storeZizhi.vue | 维护门店资质材料。 |
addStore.vue | 新增门店。 |
主要后端接口是 /api/v1/store/list、/detail、/update、/count。更新门店时必须保留公司和门店归属，不允许越权改其他门店。
员工和服务人员管理
门店端有两类人员：
| 类型 | 说明 |
|---|---|
| 服务人员 | service_staff，实际承接服务、接单、保险、钱包和能力。 |
| 内部账号 | internal_user，用于门店后台管理、合同、财务、员工管理等。 |
主要能力：
- 添加服务人员，支持 AI 录入、身份证 OCR、手机号校验、邀请码。
- 查询服务人员列表、上下架、复制到阿姨库、删除标准员工。
- 查看服务人员详情、服务产品、简历和资料。
- 维护内部账号、角色、权限和资料。
- 员工和阿姨资料可能互相复制，但必须注意数据来源和隐私。
服务项目和价格
服务项目模块负责门店产品、SKU、图片、工种和门店价格。
| 操作 | 逻辑 |
|---|---|
| 新增产品 | 选择工种、填写服务信息、上传图片，可用 AI 图片生成。 |
| 编辑产品 | 更新产品信息、图片、SKU、价格和上下架状态。 |
| 查看详情 | 回显产品、套餐、SKU、服务说明和门店支持情况。 |
| 门店管理 | 查看门店可售产品，维护门店 SKU 价格。 |
| 标准员工产品 | 员工端能力申请也会读取平台标准产品。 |
新增或编辑服务项目时要同步考虑员工能力、下单端展示、价格口径和合同或订单引用。
订单和代下单
门店端可创建或处理订单，代下单页面会整合客户地址、服务项目、服务时间、客户信息和支付信息。
| 环节 | 说明 |
|---|---|
| 客户选择 | 查询客户或创建客户，读取客户地址。 |
| 服务选择 | 读取可购买产品和服务项目。 |
| 地址定位 | 调用地理编码能力，保存服务地址。 |
| 提交订单 | /api/v1/order/proxy-create 创建订单。 |
| 门店信息 | /api/v1/order/storeInfo 获取当前门店和公司上下文。 |
| 订单状态 | 创建后进入订单履约或员工派单链路。 |
订单问题要查 order、order_details、order_logs，支付问题再查支付订单和流水。
到家派单和订单处理矩阵
底部“到家”tab 不再展示。首页和全部功能中的“开发单”进入门店码开发订单统计页，只展示通过门店码归因的订单名称、开发奖金、已入余额和冻结汇总。原 pages/dispatch/index.vue 保留为历史普通页面和内部回退路径，不作为门店端开发单入口。门店端订单接口主要集中在 /api/v1/order：
| 场景 | 接口/服务 | 关键逻辑 |
|---|---|---|
| 订单列表 | findOrderList、dispatchOrderList | 关联最新 order_payments、客户地址、需求广场佣金、渠道颜色；按公司/门店数据范围过滤。 |
| 订单详情 | findServeOrderDetail、getOrderDetail | 关联客户、地址、服务人员 order_waiter、支付、渠道和操作提示。 |
| 代客下单 | proxy-create | 前端入口和历史创单逻辑仍在，但 OrderService.create_order_service 与 create_proxy_order_service 当前开头直接抛 1048 暂停异常，提示“代客下单正在升级为小羽佳协同下单闭环”。不要按正常可新建订单链路交接。 |
| 派单 | getDispatchableStaff、assignStaff | 读取订单当前控制门店，查询可派员工，写订单服务人员关系和状态。 |
| 改价/改时 | updateOrderAmount、updateOrderTime | 校验订单号、金额、时间格式，禁止非法金额和非法时间格式。 |
| 取消订单 | cancelOrder | 锁定订单后置为 99，更新支付状态、需求广场状态，释放服务人员库存/档期，必要时通知安心生活或渠道方。 |
| 支付 | manual-balance-payment、cash-payment、balance-payment、qrcode-payment、miniapp-payment | 先做订单支付权限校验，再进入余额、现金、扫码或小程序支付服务。 |
| 结算/分账 | settle、split、demand-split | 校验订单权限，走易宝结算或需求广场分账，回调需要幂等。 |
| 补价统计 | additional-payments/statistics、additional-payments/{order_number} | 门店端查看订单补价记录和统计，不直接处理员工现场收款。 |
历史订单默认 business_mode = LEGACY。只有页面显式传 order_source=store_standard 时才查平台标准单，并且平台标准单使用虚拟门店 pQrS6tUvwx。如果门店说“订单不见了”，先确认是否查错业务模式。
需求广场和线索
需求广场用于门店购买、抢单、选择服务人员、提交协议签署和查看会员状态。
| 操作 | 逻辑 |
|---|---|
| 获取需求列表 | 按城市、类型、状态和门店资格筛选。 |
| 抢单 | 校验门店余额、积分、接收状态和是否已被处理。 |
| 购买线索 | 可能扣余额或积分，写线索记录和流水。 |
| 选择服务人员 | 关联门店服务人员。 |
| 协议签署 | 提交签署并查询签署状态。 |
| 平台会员 | 查询、购买或续费平台共享会员。 |
线索派发与门店积分相关，排查时要看 store_score_account、store_score_transaction、store_lead_dispatch_record 和事件日志。
合同管理
合同模块是门店端高风险模块，涉及客户、阿姨、服务期、金额、签名、公章、补充协议、换人和终止。
| 操作 | API | 逻辑 |
|---|---|---|
| 合同列表 | getContractList | 按门店、客户、状态、时间筛选。 |
| 创建合同 | createContract | 保存合同主数据、服务人员、客户、费用和条款。 |
| 更新合同 | updateContract | 修改未锁定字段，受权限和签署状态限制。 |
| 合同收款 | addContractFinanceRecord、createContractPaymentQrcode | 现金记录或二维码支付，成功后写支付状态。 |
| 签名 | uploadContractSignature、updateContractSignStatus | 客户和门店签署，签署状态影响导出。 |
| 公章 | getContractCompanySealPublic | 导出和签署时读取公司或门店公章。 |
| 导出 | exportContract、exportSupplyContract | 生成合同或补充协议 PDF/Word。 |
| 换人 | changeContractPerson | 记录换人历史，必要时同步保险。 |
| 补充协议 | getSupplyContractList、updateSupplyTerms、resignSupplySignature | 补充协议签署、重签、条款和报酬修正。 |
| 终止 | terminateContract | 终止合同并记录原因。 |
合同排查必须看 contract、contract_payment、contract_signature、contract_supply、contract_change_record，不要只按页面状态判断。
保险模块
门店端保险能力覆盖购买、批改、换人、理赔、退保和退保材料。
| 场景 | 逻辑 |
|---|---|
| 购买保险 | 根据门店主体、员工、保期和产品调用保险接口，写 insurance_record。 |
| 查询支付状态 | 轮询或回调更新保险支付订单。 |
| 批改 | 修改保单人员或日期，写操作记录。 |
| 光伏换人 | 特定场景下替换人员并同步第三方。 |
| 理赔 | 提交理赔申请、查询详情和列表。 |
| 退保材料 | 填写退保字段、上传付款截图、生成 Word、提交保险公司。 |
保险与合同关联时，还要看 contract_insurance，尤其是换人和待支付异常。
资金、充值、提现和钱包
门店资金模块同时存在历史余额和新门店钱包能力，排查时必须先分清资金口径。
| 功能 | 主要数据 | 说明 |
|---|---|---|
| 余额总览 | company_transaction、store_wallet_account | 页面可能兼容历史余额和新钱包。 |
| 余额流水 | company_transaction、store_wallet_transaction | 充值、扣费、品牌费、线索购买等。 |
| 微信/易宝充值 | store_payment_order | 创建支付订单，回调后更新余额或钱包。 |
| 对公转账充值 | 对公充值申请记录 | 运营审核后入账。 |
| 提现 | withdrawal、company_withdrawal、提现账户 | 校验可提现流水、账户、状态。 |
| 可提现流水 | getAvailableTransactionsForWithdrawal | 只能选择符合提现条件的资金流水。 |
| 积分商城 | store_score_*、sys_goods* | 用积分兑换商品，不能和钱包余额混用。 |
资金类修复不要直接改余额，优先通过补偿流水或反向流水处理。
门店钱包读写口径
| 口径 | 读取/写入 | 说明 |
|---|---|---|
| 历史余额 | company.balance、company.frozen_amount、company_transaction | 钱包未接管或兼容期使用。 |
| 新钱包 | store_wallet_account、store_wallet_transaction | 钱包功能开关接管后使用。真实库当前有 479 个门店钱包账户。 |
| 功能开关 | store_wallet_feature_config、StoreWalletFeatureService | 决定读流水时走历史还是钱包。 |
| 异常资金 | store_wallet_suspense | 悬挂或无法自动归属的资金。 |
门店钱包写入动作只有 5 类：收入、支出、冻结、解冻、确认冻结扣费。所有写入都必须带 idempotency_key，服务会先查已有流水，命中则直接返回原流水，避免重复扣款或重复入账。
钱包流水类型：
| 类型值 | 含义 |
|---|---|
1 | 收入 |
2 | 支出 |
3 | 冻结 |
4 | 解冻 |
5 | 确认扣费 |
易宝入网和收款码
易宝模块负责商户入网、资料上传、状态查询、整改、短验重发、行业/银行编码和收款码。
| 场景 | 逻辑 |
|---|---|
| 企业入网 | 填主体、法人、结算、资质，调用官方入网接口。 |
| 小微入网 | 员工或个人结算接收方入网。 |
| 状态查询 | 自动同步易宝状态，更新 yeepay_innet_record。 |
| 资料上传 | 通过官方上传文件接口获得文件标识。 |
| 整改查询 | 查询易宝整改协查结果。 |
| 通知重发 | 重发短验、邮件或电子签章通知。 |
| 收款码 | 查询或生成门店收款码。 |
入网问题先查本地入网记录，再查易宝官方状态，不要只看页面按钮状态。
印章、渠道、素材和公告
| 模块 | 逻辑 |
|---|---|
| 印章生成 | 根据公司或门店名称生成印章预览并保存。 |
| 印章管理 | 上传、删除、读取合同导出使用的印章。 |
| 渠道二维码 | 创建门店渠道、颜色、二维码和访问统计。 |
| 招聘海报 | 管理海报模板、二维码、扫码和提交统计。 |
| 素材 | 门店素材列表、AI 图片任务、使用记录。 |
| 公告 | 公告列表和详情。 |
| 培训 | 课程、分类、观看记录。 |
标准单招工码
门店服务人员页的“标准单招工”面板来自 store_recruit_controller.py 和 store_recruit_service.py。门店只负责推荐入驻，新入驻人员写入平台标准单兼容门店，后续派单、能力、区域和结算由平台员工池治理。
| 能力 | 逻辑 |
|---|---|
| 获取招工码 | 每个有效门店获取或创建一个激活招工码，短码 8 位大写字母数字。 |
| 生成小程序码 | 场景值形如 sr=招工码，可附带海报模板追踪码；目标页是 pages-home/attendantManage-add。 |
| 刷新招工码 | 旧码失效后重新生成，防止旧海报继续流入。 |
| 招工统计 | 统计扫码、提交资料、已提交、重复或存量人员。 |
| 公开注册 | 根据招工码展示门店推荐信息，提交员工入驻资料；10 分钟内限 3 次，重复入驻返回冲突。 |
| 工种识别 | 支持保洁、维修、搬家关键词识别，最终仍要走员工能力/产品配置。 |
排查招工问题时先看 store_recruit_code、staff_recruit_record、海报模板统计和员工是否写入平台标准单门店，不要只看门店自己的员工列表。
版本续费和系统设置
pages-set/systemRenewal/systemList.vue 处理门店版本续费、套餐预览和执行，涉及公司到期时间、版本关系和支付。排查时查公司版本字段、续费订单和支付结果。
设置页还包含修改密码、个人资料、地址、客服预约和反馈。此类功能通常低风险，但涉及账号权限时仍要看 internal_user。
数据大盘、客户和经营辅助
门店端还有一组经营辅助入口，不直接改变履约状态，但会影响门店日常判断、客户跟进和经营复盘。
| 模块 | 页面/API | 逻辑 |
|---|---|---|
| 数据大盘 | pages/data-dashboard/index.vue、dashboard.js | 查询收入、到家订单、到店订单、合同到期/续签、员工招聘等 KPI，支持按日期范围导出。 |
| 客户管理 | pages-client/client/*、client.js、sister-business.js | 查询客户列表、客户搜索、客户设置、合同跳转和客户跟进；客户问题要同时查客户、合同、订单和跟进记录。 |
| 考勤管理 | pages-home-sub/home/attendance-manage.vue | 当前页面侧重月度考勤展示和本地日期切换，接入接口前不要当作正式薪资结算依据。 |
| 素材中心 | pages-home-sub/home/materials.vue、store-material.js | 拉取门店素材，支持图片/视频预览、下载和使用记录埋点。 |
| 课程培训 | pages-large/*、training.js | 培训列表、课程详情、心理测评和课程配置，排查展示先查课程状态和分类。 |
这些入口通常由首页快捷入口或“全部功能”进入。运营反馈“页面没有数据”时，先确认账号角色、门店范围和筛选条件，再查具体业务表。
排障清单
| 问题 | 先查 |
|---|---|
| 门店端入口缺失 | 当前账号角色、公司版本、前端入口、后端权限。 |
| 门店资料无法保存 | store 权限、必填字段、资质文件、公司归属。 |
| 员工列表不准 | service_staff 状态、门店 uuid、是否标准员工、是否删除。 |
| 产品不展示 | 产品状态、SKU、门店支持、工种、下单端映射。 |
| 订单创建失败 | 客户、地址、产品、服务时间、门店上下文和订单日志。 |
| 合同导出失败 | 合同状态、签名、公章、模板字段、远程文档服务。 |
| 保险购买失败 | 主体信息、员工信息、保期、产品、支付状态、第三方返回。 |
| 余额或钱包不准 | 先分清历史余额和门店钱包，再查对应流水。 |
| 提现失败 | 提现账户、可提现流水、余额、审核状态。 |
| 入网失败 | 本地入网记录、资料完整性、易宝官方状态、整改通知。 |
| 线索派发异常 | 门店积分账户、派发状态、线索记录、事件日志。 |