# Rules（规则 / 不变量） > 业务约束、决策条件、权限边界。每条规则标注适用动作、落地代码、测试。 ## 鉴权 ### rule:BR-AUTH-001 **HMAC session token 鉴权**：protected `/api/**` 要求 `Authorization: Bearer `；token 格式 `base64url(payload).base64url(sig)`，HMAC-SHA256，默认 7 天有效期；public allowlist 见 `AuthInterceptor.PUBLIC_PATTERNS`。 - **适用动作**：所有 protected 接口 - **代码**：`backend/src/main/java/com/petstore/auth/AuthInterceptor.java`、`SessionTokenService.java`、`CurrentUserContext.java` - **测试**：`SessionTokenServiceTest` - **证据**：`anchored` ### rule:BR-AUTH-002 **生产登录策略**：生产只走微信授权（`/api/user/wx-phone-login`）；SMS 验证码登录 dev-only（`universalSmsCode` 为空 = 生产禁用）；`SmsController#send` 生产返回 403 `SMS_LOGIN_DISABLED`。 - **适用动作**：`action:login`、`action:wx_phone_login` - **代码**：`backend/src/main/java/com/petstore/service/UserService.java#login`、`SmsController.java` - **测试**：`UserServiceLoginStrategyTest` - **证据**：`anchored` ## Store ### rule:BR-STORE-001 **店铺更新/删除仅 boss + 同店**：`update`/`delete` 仅 `isBoss() && current.storeId != null`；`store.id` 必须等于 `current.storeId`。 - **适用动作**：`action:update_store`、`action:delete_store` - **代码**：`backend/src/main/java/com/petstore/controller/StoreController.java#update`/`#delete` - **测试**：`StoreControllerTest` - **证据**：`anchored` ### rule:BR-STORE-002 **邀请码查询仅 boss/staff + 同店**：按 code 查到的 store.id 必须等于 `current.storeId`；新员工注册预览走公开 `/api/user/register-staff`（请求体含 inviteCode）。 - **适用动作**：`action:get_store_by_invite_code` - **代码**：`backend/src/main/java/com/petstore/controller/StoreController.java#getByInviteCode` - **测试**：`StoreControllerTest#inviteCodeCrossStoreForbidden` - **证据**：`anchored` ### rule:BR-STORE-003 **公开门店字段裁剪**：公开接口 `GET /api/store/get`、`GET /api/store/list` 仅返回预约/展示所需字段（id/name/address/坐标/phone/logo/intro/营业时段），**不得**返回 `ownerId`、`inviteCode`、`deleted` 等内部字段（与 `rule:BR-RPT-006` 对称）。 - **适用动作**：`action:get_store`、`action:list_stores` - **代码**：`backend/src/main/java/com/petstore/controller/StoreController.java#toPublicStoreView` - **测试**：`StoreControllerTest#publicGetHidesOwnerIdAndInviteCode`、`#publicListHidesOwnerIdAndInviteCode` - **证据**：`anchored` ## Appointment ### rule:BR-APPT-001 **预约状态机**：仅允许 `new→doing`（`startService`）、`new→cancel`、`doing→done`（报告提交触发）、`doing→cancel`（若产品允许）；`done`/`cancel` 为终态不可回退；`→doing` 必须走 `/appointment/start`；非法迁移返回 `INVALID_STATUS` / `CANCEL_NOT_ALLOWED` / `USE_START_ENDPOINT`。 - **适用动作**：`action:start_service`、`action:transition_appointment_status`、`action:submit_report` - **代码**：`backend/src/main/java/com/petstore/service/AppointmentService.java#startService`/`#transitionStatus` - **测试**：`AppointmentServiceTest` - **证据**：`anchored` ### rule:BR-APPT-002 **预约跨店 403**：boss/staff 操作预约（list/start/status/detail/delete）仅限本店 `storeId == current.storeId`，跨店返回 `FORBIDDEN`。 - **适用动作**：`action:list_appointments`、`action:start_service`、`action:transition_appointment_status`、`action:get_appointment_detail`、`delete` - **代码**：`backend/src/main/java/com/petstore/controller/AppointmentController.java` - **测试**：`AppointmentControllerDetailTest` - **证据**：`anchored` ### rule:BR-APPT-003 **预约客户归属与跨用户 403**：customer 仅可查看/取消自己的预约（`customerUserId == current.userId`；未回填旧数据可回退 legacy `userId`），不可操作他人预约。customer 自约时客户与创建人均从上下文派生；boss/staff 代客预约必须解析真实 customer，禁止把操作员工写成客户。`petId` 存在时必须属于该客户。 - **适用动作**：`action:create_appointment`、`action:get_appointment_detail`、`action:transition_appointment_status`（仅 cancel） - **代码**：`backend/src/main/java/com/petstore/controller/AppointmentController.java#detail`/`#updateStatus` - **测试**：`AppointmentControllerIdentityTest`、`AppointmentControllerDetailTest#customerCannotViewOthersAppointment` - **证据**：`anchored` ### rule:BR-APPT-004 **真实预约容量校验**：开始时间按半小时对齐；服务必须在 `booking_day_start` 到末容量桶结束时刻内完成。预约保存服务时长快照，并检查覆盖的每个半小时容量桶；有效预约与 `walk_in` 各消耗一个 `booking_capacity`，`blocked` 关闭覆盖范围内全部容量。创建预约/占用时悲观锁定门店行，避免并发超卖；取消预约不占容量。 - **适用动作**：`action:create_appointment`、`action:get_available_slots`、`action:create_schedule_block` - **代码**：`backend/src/main/java/com/petstore/service/AppointmentService.java#createBooking`、`BookingCapacityService`、`ScheduleService#createBlock` - **测试**：`BookingCapacityServiceTest`、`AppointmentServiceTest`、`BookingCapacityMigrationTest` - **文档**：`docs/产品设计文档.md §5.2` - **证据**：`anchored` ## Report ### rule:BR-RPT-001 **报告必须绑定预约**：`appointmentId` 为空返回 `APPOINTMENT_REQUIRED`；无预约报告不作为 P0 主路径。 - **适用动作**：`action:submit_report` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#create`、`ReportService.java#create` - **测试**：`ReportControllerTest#createMissingAppointmentIdReturnsBizCode`、`ReportServiceTest#createWithNullAppointmentIdThrows` - **证据**：`anchored` ### rule:BR-RPT-002 **一约一份报告**：`Report.appointment_id` 唯一约束 `uk_report_appointment`；服务层 `existsByAppointmentIdAndDeletedFalse` 重复提交抛 `IllegalStateException`，Controller 转 409 `REPORT_ALREADY_EXISTS`。 - **适用动作**：`action:submit_report` - **代码**：`backend/src/main/java/com/petstore/entity/Report.java`、`mapper/ReportMapper.java`、`service/ReportService.java#create`、`controller/ReportController.java#create` - **测试**：`ReportServiceTest#createDuplicateReportThrows`、`ReportControllerTest#createDuplicateReportReturnsAlreadyExists` - **证据**：`anchored`（上线前需清理历史重复数据，见 `backend/README.md` 数据库迁移） ### rule:BR-RPT-003 **报告前后照片必填**：服务前/服务后至少各 1 张有效照片（`mediaType` 非 video）；缺 before 返回 `BEFORE_PHOTO_REQUIRED`，缺 after 返回 `AFTER_PHOTO_REQUIRED`；服务过程中素材可选。 - **适用动作**：`action:submit_report` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#hasPhotoType`、`frontend/src/pages/report/Report.vue#submitReport` - **测试**：`ReportControllerTest#createMissingBeforePhotoReturnsBizCode`/`createMissingAfterPhotoReturnsBizCode` - **文档**：`docs/产品设计文档.md §5.3 报告提交必填项` - **证据**：`anchored`（前后端双校验） ### rule:BR-RPT-004 **报告仅 doing 预约可提交**：关联预约状态非 `doing` 返回 `INVALID_STATUS`「请先开始服务后再提交报告」；提交后 `doing→done`。 - **适用动作**：`action:submit_report` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#create`、`service/ReportService.java#create` - **测试**：`ReportServiceTest#createDoingAppointmentMarksDone` - **证据**：`anchored` ### rule:BR-RPT-005 **报告跨店 403**：仅 boss/staff 可创建/删除报告；报告所属门店必须等于 `current.storeId`，跨店返回 `FORBIDDEN`。 - **适用动作**：`action:submit_report`、`action:delete_report` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#create`/`#delete` - **测试**：`ReportControllerTest#createCrossStoreReturnsForbidden`、`createNonStaffReturnsForbidden` - **证据**：`anchored` ### rule:BR-RPT-006 **公开报告字段裁剪**：`GET /api/report/get?token=`（publicTokenRequest）不返回 top-level `userId`/`storeId`/`reportToken`；`store` 对象内可返回 `id`（用于预约跳转）+ `name`/`logo`/`phone`/`address`，不返回 `latitude`/`longitude`；非 public（appointmentId 查询）保留全部字段供门店端使用。 - **适用动作**：`action:get_report_by_token` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#getByAppointmentId` - **测试**：`ReportControllerTest#publicTokenQueryHidesInternalFields` - **前端**：`frontend/src/pages/report-view/reportView.vue`（`reminderToken` 只读路由 token，`bookingStoreId` 只读 `store.id`） - **证据**：`anchored` ### rule:BR-RPT-007 **token hash 日志**：报告打开埋点日志只记 `tokenHash`（SHA-256 前 8 位 hex），不输出 token 前缀。 - **适用动作**：`action:track_report_open` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#shortTokenHash`/`#trackReportOpen` - **证据**：`anchored` ## ReportLead ### rule:BR-LEAD-001 **留资去重**：同一 `report_token` + 同一手机号二次提交幂等更新，不重复插库，返回 `repeatSubmit=true`。 - **适用动作**：`action:submit_lead` - **代码**：`backend/src/main/java/com/petstore/service/ReportLeadService.java#submit` - **证据**：`documented`（逻辑已实现，未补测试用例） ### rule:BR-LEAD-002 **留资标识脱敏**：`/api/report/leads` 不返回完整 `wechatOpenid`/`wechatUnionid`，只返回 `wechatBound`（boolean）+ `wechatOpenidMasked` + `wechatUnionidMasked`（首4+****+末4，过短返回 `****`）。 - **适用动作**：`action:list_leads` - **代码**：`backend/src/main/java/com/petstore/controller/ReportLeadController.java#maskIdentifier`/`#leads` - **前端**：`frontend/src/pages/mine/Leads.vue`（只渲染 `wechatBound`/`wechatOpenidMasked`） - **证据**：`anchored` ### rule:BR-LEAD-003 **回访池跨店 403**：`/api/report/leads` 仅 boss/staff，`storeId` 从 `CurrentUserContext` 派生，忽略 query `storeId`。 - **适用动作**：`action:list_leads` - **代码**：`backend/src/main/java/com/petstore/controller/ReportLeadController.java#leads` - **证据**：`anchored` --- ## Batch 2 录入规则 ## Upload ### rule:BR-UPLOAD-001 **上传路径归一化**：`FileController` 用 `Paths.get(uploadPath).toAbsolutePath().normalize()`；`resolveSafePath` 反斜杠统一、去前导斜杠、`normalize` 后校验 `target.startsWith(root)`，逃逸返回 400。 - **适用动作**：`action:upload_image`、`action:get_upload_image`、`getLegacyImage` - **代码**：`backend/src/main/java/com/petstore/controller/FileController.java#resolveSafePath`/`#uploadRoot` - **证据**：`anchored` ### rule:BR-UPLOAD-002 **上传扩展名/MIME 校验**：原文件有扩展名必须在图片/视频白名单内，否则拒绝；无扩展名时 MIME 必须是 `image/*`/`video/*`/`application/octet-stream`/空（小程序兼容），否则拒绝。 - **适用动作**：`action:upload_image` - **代码**：`backend/src/main/java/com/petstore/controller/FileController.java#isAllowedMediaType`/`#hasMediaExtension` - **证据**：`anchored` ## Highlight Video ### rule:BR-HL-001 **成片仅 boss/staff 可触发**：`operatorUserId`/`role` 从 `CurrentUserContext` 派生，不信任请求体；customer 触发返回 403。 - **适用动作**：`action:generate_highlight` - **代码**：`backend/src/main/java/com/petstore/controller/ReportController.java#startHighlight` - **证据**：`anchored` ### rule:BR-HL-002 **成片三态 + composeMode**：`highlight_video_status` 枚举 `processing`/`done`/`failed`；`composeMode` 枚举 `preset`/`interleave`；失败原因归类 `material`/`service`/`network`/`unknown`（对宠主展示归类中文，不暴露堆栈）；时长随素材变化（配置级上限 `HIGHLIGHT_MAX_DURATION_SEC`）。 - **适用动作**：`action:generate_highlight` - **代码**：`backend/src/main/java/com/petstore/entity/Report.java`（`highlight_*` 字段）、`service/ReportHighlightVideoService.java` - **文档**：`docs/洗美报告短视频成片方案.md`、`docs/API-报告成片字段契约.md` - **证据**：`anchored`（字段与状态已实现；FFmpeg 集成测试 `gap`） ## Schedule ### rule:BR-SCH-001 **排班仅 boss/staff + 跨店 403**：`day`/`block`(create/delete) 仅 `isStoreUser()`；`storeId=current.storeId`（忽略请求体）；`deleteBlock` 经 service `operatorStoreId` 校验同店。 - **适用动作**：`action:day_agenda`、`action:create_schedule_block`、`action:delete_schedule_block` - **代码**：`backend/src/main/java/com/petstore/controller/ScheduleController.java`、`service/ScheduleService.java#deleteBlock` - **测试**：`ScheduleControllerTest` - **证据**：`anchored` ### rule:BR-SCH-002 **手动占用容量语义**：`durationMinutes` 为 30～480 的 30 分钟倍数；`walk_in` 在覆盖的每个容量桶消耗一个并发名额，`blocked` 仅允许创建在没有预约或其他占用的范围，并关闭全部号源。 - **适用动作**：`action:day_agenda`、`action:create_schedule_block` - **代码**：`backend/src/main/java/com/petstore/service/ScheduleService.java`、`BookingCapacityService.java` - **测试**：`BookingCapacityServiceTest`、`ScheduleControllerTest` - **证据**：`anchored` ## ServiceType ### rule:BR-ST-001 **服务类型仅 boss + 同店 + 系统默认不可改删**：`create`/`update`/`delete` 仅 `isBoss()`；`storeId=current.storeId`；`update`/`delete` 时 `existing.storeId` 必须非空且等于 `current.storeId`（系统默认 `storeId=null` 不可改删，他店不可改删）；预计时长须为 30～480 的 30 分钟倍数；`init` 仅 boss/staff。 - **适用动作**：`action:create_service_type`、`action:update_service_type`、`action:delete_service_type`、`action:init_service_types` - **代码**：`backend/src/main/java/com/petstore/controller/ServiceTypeController.java` - **测试**：`ServiceTypeControllerTest` - **证据**：`anchored` ## Pet ### rule:BR-PET-001 **宠物跨用户/跨店**：customer `list`/`create` 强制 `ownerUserId=current.userId`；boss/staff `list` 查本店服务过的宠物（`storeId=current.storeId`）；`update`/`delete`/`history` 的 `operatorUserId`/`role` 从上下文派生。 - **适用动作**：`action:list_pets`、`action:create_pet`、`action:update_pet`、`action:delete_pet`、`action:get_pet_history` - **代码**：`backend/src/main/java/com/petstore/controller/PetController.java` - **测试**：`PetControllerTest` - **证据**：`anchored` ## User 管理 ### rule:BR-USER-001 **员工管理仅 boss + 同店**：`create_staff`/`list_staff`/`delete_staff` 仅 `isBoss()`；`storeId=current.storeId`；`delete_staff` 校验目标员工属于本店。 - **适用动作**：`action:create_staff`、`action:list_staff`、`action:delete_staff` - **代码**：`backend/src/main/java/com/petstore/controller/UserController.java` - **证据**：`anchored` ### rule:BR-USER-002 **用户更新仅本人**：`update_user` 的 `id=current.userId`（覆盖请求体）；手机号变更需 SMS 验证码（生产 `rule:BR-AUTH-002` 禁用）。 - **适用动作**：`action:update_user`、`action:get_user_info` - **代码**：`backend/src/main/java/com/petstore/controller/UserController.java#updateUser`/`#info` - **证据**：`anchored` ### rule:BR-USER-003 **User 敏感字段不序列化**：`password`、`wechatOpenid`、`wechatUnionid` 必须 `@JsonIgnore`，禁止随 API JSON 返回。 - **适用动作**：`action:login`、`action:wx_phone_login`、`action:get_user_info`、`action:update_user`、`action:register_boss`、`action:register_staff`、`action:list_staff` - **代码**：`backend/src/main/java/com/petstore/entity/User.java` - **测试**：`UserJsonIgnoreTest` - **证据**：`anchored` ## Config ### rule:BR-CONFIG-001 **生产配置环境变量**：`application.yml` 的 `datasource.url/username/password`、`wechat.appid/appsecret`、`auth.session-secret`、`upload.path` 等敏感项全部改为 `${ENV_VAR:默认}`；不在源码写真实密钥。 - **适用动作**：—（全局约束） - **代码**：`backend/src/main/resources/application.yml`、`application-example.yml` - **文档**：`backend/README.md 环境变量表` - **证据**：`anchored`（已暴露凭据需运维轮换） ### rule:BR-CONFIG-002 **production profile**：`--spring.profiles.active=production` 时 `ddl-auto=validate`（不改表）、`show-sql=false`、`SMS_UNIVERSAL_CODE` 默认空（关闭万能验证码 `rule:BR-AUTH-002`）。 - **适用动作**：—（全局约束） - **代码**：`backend/src/main/resources/application.yml`（multi-document production profile） - **文档**：`backend/README.md production profile` - **证据**：`anchored`（配置已加；production 实测启动 `gap`） ## 寄语 / 退订 / 建议周期 ### rule:BR-TST-001 **一报告一寄语**：同一 `report_id` 仅保留一条寄语；重复提交更新 `content`/`is_public`/`update_time`，不新增行。 - **适用动作**：`action:submit_testimonial` - **代码**：`backend/src/main/java/com/petstore/service/ReportTestimonialService.java` - **测试**：`ReportTestimonialServiceTest` - **证据**：`anchored` ### rule:BR-UNSUB-001 **凭 unsubscribeToken 一键退订**：公开接口，令牌无效返回明确错误；成功后 `remind_status=unsubscribed`。 - **适用动作**：`action:unsubscribe` - **代码**：`backend/src/main/java/com/petstore/controller/ReportLeadController.java#unsubscribe` - **测试**：`ReportLeadControllerTest` - **证据**：`anchored` ### rule:BR-INT-001 **服务建议周期推算**：公开 `suggestion` 按报告服务类型 + 宠物类型读取 `entity:service_interval`（门店覆盖优先于系统默认）推算下次建议日期。 - **适用动作**：`action:get_report_suggestion` - **代码**：`backend/src/main/java/com/petstore/service/ReportLeadService.java#suggestNext` - **测试**：`ReportLeadControllerTest` - **证据**：`anchored` ## 门店 Web 后台（Phase A） ### rule:BR-ADMIN-001 **门店后台角色门禁**：`entity:admin_console` 仅 `boss` / `staff` 可进且 **均可编辑本店数据**；`customer` 禁止。删店、创建/删除员工等仍遵循既有仅 boss 规则（`rule:BR-STORE-001`、`rule:BR-USER-001`）。 - **适用动作**：`action:view_workbench`、`action:admin_list_*`、`action:admin_update_settings`、`action:admin_manage_schedule` - **产品决策**：2026-07-10（staff 可编辑，非只读） - **文档**：`docs/门店管理后台-PhaseA-页面清单PRD.md` - **证据**：`documented` ### rule:BR-ADMIN-002 **后台数据仅本店**：所有后台查询/写强制 `current.storeId`；忽略跨店参数；连锁规则同步不在 Phase A。 - **适用动作**：同上 - **证据**：`documented` ### rule:BR-ADMIN-003 **后台可看内部字段**：经鉴权后可返回公开 API 裁剪掉的字段（如 inviteCode、报告内部字段）；与 `rule:BR-STORE-003` / `rule:BR-RPT-006` 对称。手机号默认仍脱敏，明文权限预留。 - **适用动作**：`action:admin_list_reports`、`action:admin_update_settings`、`action:admin_list_service_customers` - **证据**：`documented` ### rule:BR-ADMIN-004 **Phase A 后台范围闸门**：禁止将 `membership` / 储值 / 次卡套餐 / 收银 / 库存 / 寄养 / 押金 / 点餐 / 支付宝渠道 写入 Phase A 后台范围或设计稿；上述保持 `evidence=gap`。 - **适用**：`entity:admin_console`、`entity:workbench` 及一切 admin Phase A 动作 - **文档**：`docs/门店管理后台升级方案-对标宠老板.md` - **证据**：`documented` ### rule:BR-SC-001 **门店客户主档唯一性与合并**：同一门店内，`customer_user_id` 和手机号分别只能对应一条有效 StoreCustomer。留资可先按手机号建档；后续预约/登录识别到 customer 后绑定或合并。不得将 boss/staff 绑定为客户主档。 - **适用动作**：`action:create_appointment`、`action:submit_lead`、`action:admin_list_service_customers` - **代码**：`backend/src/main/java/com/petstore/service/StoreCustomerService.java` - **测试**：`StoreCustomerServiceTest`、`ReportLeadServiceStoreCustomerTest`、`IdentityOwnershipQueryTest` - **证据**：`anchored` ### rule:BR-BE-001 **业务事件不可变、幂等与低敏**：BusinessEvent 只追加，不更新/软删；稳定业务结果使用 idempotencyKey 去重。metadata 只允许服务端白名单标量，不得保存手机号、报告 token/hash、媒体 URL、IP、openid/unionid、备注、内容全文、密码、密钥或原始请求体。管理端仅返回当前门店聚合，不开放通用事件明细。 - **适用动作**：`action:create_appointment`、`action:start_service`、`action:transition_appointment_status`、`action:submit_report`、`action:track_report_open`、`action:submit_lead`、`action:view_workbench` - **代码**：`backend/src/main/java/com/petstore/service/BusinessEventService.java`、`AdminBusinessEventService.java` - **测试**：`BusinessEventServiceTest`、`BusinessEventMigrationTest`、`AdminBusinessEventControllerTest` - **证据**：`anchored`