petstore-docs/.agents/common-context.md

宠小它 Agent Common Context

项目路径

名称	路径
工作区	/Users/apple/_src/petstore
知识库	/Users/apple/_src/petstore/docs
后端工程	/Users/apple/_src/petstore/backend
前端工程	/Users/apple/_src/petstore/frontend

业务边界

• 当前产品是“宠小它”宠物门店服务 SaaS。
• v1 核心用户：宠物店老板、员工、宠主。
• v1 核心闭环：预约创建 -> 待开始 -> 开始服务 -> 填写报告 -> 发送报告 -> 宠主查看/分享。
• 本期重点以现有文档为准：预约状态机、服务报告、短视频成片、报告分享、宠主预约、留资和最小埋点。
• 不把会员卡、储值、复杂排班、复杂数据看板、支付结算、技师分成等 P1/P2 能力写成 P0 已完成。
• 不把 demo、mock、临时 H5 或 dev-only 配置描述成生产能力。

术语规则

术语	含义	使用规则
宠小它	当前产品品牌	对外文档和页面统一使用
Store / 门店	宠物店主体	后端数据范围以 store_id / storeId 为核心
boss	老板角色	可管理员工、服务类型、店铺设置等
staff	员工角色	可处理预约、开始服务、填写/发送报告
customer / 宠主	报告查看者和预约发起者	公开页和预约页不得泄漏无关门店/员工数据
Appointment	预约	状态仅使用 new、doing、done、cancel
Report	服务报告	一约一份报告，提交后默认锁死
report_token	报告公开访问令牌	视为敏感公开链接，不打印、不随意暴露到日志
Highlight Video / 成片	服务过程短视频自动成片	必须有 processing / failed / success 三态和可理解错误文案
Lead / 留资	宠主手机号等转化线索	需要去重、隐私提示和数据范围控制

技术基线

• 后端：Java 17、Spring Boot 3.2.3、Spring Data JPA、MySQL、Lombok。
• 前端：uni-app、Vue 3、Vite，支持微信小程序和 H5。
• 本地 H5 开发代理：frontend/vite.config.js 将 /api 转发到 http://localhost:8080。
• 前端 API 入口优先通过 frontend/src/api/index.js 和业务 utils 统一封装。
• 后端 controller 只做入口和响应映射；领域规则必须落在 service 层。

知识本体（Ontology）

项目领域知识以本体论框架建模为 SSOT，位于 docs/ontology/：

• objects.md — 实体（store_customer、business_event 已落为 JPA；admin_console/workbench 为后台读模型；P1/P2 gap 占位见 membership 等）
• actions.md — 动作（controller 接口 + 客户端埋点 + admin_ 后台动作 documented*）
• events.md — 事件（含 workbench_viewed gap）
• rules.md — 规则（含 rule:BR-ADMIN-001…004 后台门禁与范围闸门）
• relations.md — ER 关系 + 动作-事件 + 规则-动作适用
• graph/ontology.jsonl — 机器可读知识图谱
• graph/validate_ontology.py — 引用完整性校验
• graph/audit_drift.py — 本体—代码漂移审计（端点 + 实体类对齐）
• coverage/ontology-coverage-audit.md — 覆盖度审计（与 jsonl 同步刷新）
• 产品对标：docs/门店管理后台升级方案-对标宠老板.md
• Phase A 页面 PRD：docs/门店管理后台-PhaseA-页面清单PRD.md
• Phase A 交付目标：docs/门店管理后台-PhaseA-交付目标.md
• Phase A 冒烟：docs/qa-reports/门店后台-PhaseA-冒烟清单.md
• Phase A 线框：docs/门店管理后台-PhaseA-线框说明.md
• 技术选型（Q5）：docs/门店管理后台-技术选型草案.md
• 编码任务 brief：docs/门店管理后台-PhaseA-编码任务brief.md

协作约定：

• 改动 controller/service/entity 时，同步更新对应本体条目（docs/ontology/ + graph/ontology.jsonl）。
• 任务 brief 可在 ontologyRefs 字段引用本体 ID（如 [entity:report, rule:BR-RPT-002]），让接手 agent 直接定位上下文。
• 冲突时以本体为准；本体与代码漂移由 audit_drift.py 守护。
• 校验：python3 docs/graph/validate_ontology.py docs && python3 docs/graph/audit_drift.py

协作规则

• 开工前说明读哪些文件、写哪些文件。
• 写代码前确认写入范围，避免多个 agent 修改同一组文件。
• 固定团队任务先读 .agents/fixed-team-operating-model.md，确认 Owner Agent、Paired QA、Workstream、Service Lock、Data Model Review Required、Access / Privacy Review Required。
• 固定 agent 只领取字段完整且 Status = Ready 的任务；不要从长文档、聊天上下文或历史 prompt 自行扩大范围。
• 任务名称不加角色前缀；角色归属写入任务字段。
• 不要回滚、删除或格式化职责范围外的文件。
• 发现未提交或未跟踪文件时，默认认为是他人工作成果。
• 输出必须包含修改文件、验证命令、验证结果、风险点。
• 没有运行验证命令时，不得声称“已验证通过”。

固定团队写入锁

• frontend/src/pages/home、frontend/src/pages/appointment、frontend/src/pages/report、frontend/src/pages/mine 的门店端体验归 Store Miniapp FE。
• admin/**（建成后）门店 Web 后台归 Store Admin FE。
• frontend/src/pages/report-view、frontend/src/views/ReportView.vue、frontend/src/pages/video-player、宠主预约、分享落地和留资体验归 Customer Experience FE。
• 共享组件、frontend/src/api、frontend/src/utils 需要声明具体 Service Lock，并让相关 FE owner review。
• 预约、门店、用户、宠物、日程、服务类型后端能力归 Backend Core。
• 报告、媒体、成片、报告公开页、留资、评价后端能力归 Report Media Backend。
• JPA entity、索引、表结构、状态字段和迁移顺序需要 Data Model 复核。
• QA 不改业务代码；Ops 不改业务逻辑；PM Assistant 不改产品代码。
• System Architect 不改业务代码，不持有前后端业务写入锁；架构结论需要落地时，必须拆给对应 owner agent 执行。

禁止事项

• 不要把未实现的容量模型写成“排队/不排队”能力。
• 不要让公开报告页暴露内部 user id、store id 以外的敏感明细、手机号或调试字段。
• 不要绕过预约状态机直接赋值状态。
• 不要绕过报告提交流程制造 done 终态。
• 不要在业务页面继续扩散硬编码品牌主色；优先使用全局 token。
• 不要把 mock 支付、测试域名、临时 token 或本地文件路径写成生产方案。