103 lines
6.5 KiB
Markdown
103 lines
6.5 KiB
Markdown
# 宠小它 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` 已落为 JPA `StoreCustomer`；`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 或本地文件路径写成生产方案。
|