# 宠小它 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 或本地文件路径写成生产方案。