# 宠小它 Fixed Agent Team Operating Model

本文件定义宠小它固定 agent 编制、持续队列和产品研发流程规范。目标是让 agent 按固定角色从 Ready 队列持续拉活，而不是每次临时重拆边界。

## 执行槽位

固定队形描述的是角色和责任，不等同于工具层可同时运行的子 agent 数量。实际执行采用“固定角色 + 动态并行 + 及时关闭”：

- 主控 PM 不占子 agent 槽位，负责拆任务、review、集成、提交、发布协调和阻塞归因。
- agent 完成、阻塞、取消或仅用于探测后，必须及时关闭会话，释放队列资源。
- 优先并行互不冲突的写入边界，例如 `docs` + `frontend` + `backend`；同一 `Service Lock` 同时只允许一个 owner 修改。
- 如果创建新 agent 返回 thread limit，先清理已完成或已阻塞 agent，再按优先级重试。

## 固定队形

| Group | Owner Agent | Role 字段 | 常驻职责 | 主写入边界 | Paired QA |
|---|---|---|---|---|---|
| 门店端前端 | Store Miniapp FE | `Store Miniapp Frontend` | 老板/员工小程序页面、预约列表、开始服务、报告填写、我的、员工/服务类型管理 | `frontend/src/pages/home`、`appointment`、`report`、`mine`、门店端共享组件 | Core Flow QA / Report Share QA |
| 门店 Web 后台 | Store Admin FE | `Store Admin Frontend` | 门店 Web 管理后台（工作台/预约/报告/线索/客户/排班/设置） | `admin/**`（建成后） | Core Flow QA / Report Share QA |
| 宠主体验前端 | Customer Experience FE | `Customer Experience Frontend` | 宠主预约、报告 H5、分享落地、视频播放、留资、宠物档案和公开体验 | `frontend/src/pages/report-view`、`video-player`、宠主预约页、公开体验 utils/components | Core Flow QA / Report Share QA |
| 核心后端 | Backend Core | `Backend Core` | 预约状态机、门店、用户、宠物、日程、服务类型、微信/短信基础能力 | `backend/src/main/java/com/petstore/controller` 和 `service` 中核心域文件 | Core Flow QA |
| 报告媒体后端 | Report Media Backend | `Report Media Backend` | 服务报告、报告图片/视频、成片任务、公开报告数据、留资、评价 | `Report*`、`FileController`、`ReportHighlightVideoService` 等报告媒体域 | Report Share QA |
| 核心链路 QA | Core Flow QA | `Core Flow QA` | 老板/员工/宠主预约主链路、状态机、门店数据范围验收 | `docs/qa-reports`、必要 smoke 脚本 | Store Miniapp FE / Customer Experience FE / Backend Core |
| 报告分享 QA | Report Share QA | `Report Share QA` | 报告填写、分享页、H5、成片三态、隐私提示、埋点验收 | `docs/qa-reports`、必要 smoke 脚本 | Report Media Backend / Customer Experience FE |
| 后端运维 | Backend Ops | `Backend Ops` | 后端 jar、数据库配置、Nginx API、启动、回滚、API smoke | `backend/deploy`、运维报告；不改业务逻辑 | 关联业务 QA |
| 前端发布运维 | Frontend Release Ops | `Frontend Release Ops` | 微信小程序体验版、H5 构建、项目配置、前端 smoke | `frontend/project*.json`、构建/发布配置、运维报告；不改业务逻辑 | 关联业务 QA |
| PM 助手 | PM Assistant | `PM Assistant` | 任务源维护、RC 管家、依赖跟踪、验收证据归档、阻塞归因、进展同步 | `docs`；不改产品代码 | 主控 PM |
| 架构治理 | System Architect | `System Architect` | 跨模块边界、接口契约、状态机、数据一致性、owner 拆分 | `docs`；不改业务代码 | 关联业务 QA / Docs |

专项支持 agent：

| Agent | Role 字段 | 职责 | 写入边界 |
|---|---|---|---|
| Data Model | `Data Model` | JPA entity、表结构、索引、软删除、状态字段、幂等和迁移顺序 | `docs`、必要时 backend entity/repository review；默认不持锁 |
| Product Design | `Product Design` | 产品说明、用户流程、IA、文案、验收标准 | `docs` |
| Docs | `Docs` | 知识库、架构文档、实施计划、状态同步 | `docs` |
| Progress Digest | `Progress Digest` | 实现度看板、日报素材、阶段摘要 | `docs` |

## 队列字段

每个 Owner Agent 维护一个持续队列。队列项必须具备以下字段，缺一不可：

| 字段 | 说明 |
|---|---|
| `Task Name` | 以业务结果命名，不以角色前缀命名 |
| `Role` | 使用上表 Role 字段之一 |
| `Owner Agent` | 固定 agent 名称，例如 `Backend Core` |
| `Paired QA` | 对应 QA，例如 `Core Flow QA` |
| `Workstream` | `Core Booking Flow`、`Report Sharing`、`Release`、`PM`、`Architecture` |
| `Track` | `Product`、`Coding`、`QA`、`Ops`、`Hotfix`、`Planning`、`Review` |
| `Status` | `Backlog`、`Ready`、`Doing / In Progress`、`Review`、`QA`、`Deploying`、`Blocked`、`Ready for Release`、`Released`、`Done` |
| `Priority` | `P0`、`P1`、`P2` |
| `Repo/Path` | 主要写入路径 |
| `Service Lock` | 后端 domain、前端 page group、docs 或发布资源锁 |
| `Depends On` | 依赖任务或接口 |
| `Acceptance` | QA 可执行的验收节点 |
| `RC Included` | 是否进入当前 Release Candidate |
| `Due Date` | 目标完成日期；没有明确日期时写 `TBD` |
| `Output Link` | commit、报告、发布记录、截图或其他证据链接 |
| `Blocker Owner` | 阻塞责任 owner；未阻塞时写 `None` |
| `Commit / RC` | 相关提交号、RC id 或 `Not Frozen` |
| `Architecture Review Required` | 是否需要 System Architect 在开发前评审 |
| `Data Model Review Required` | 是否涉及 entity、表结构、索引、状态字段、幂等、软删除或数据迁移 |
| `Access / Privacy Review Required` | 是否涉及登录、门店数据范围、手机号、报告 token、媒体 URL、公开页或隐私提示 |

## 拉活策略

- 固定 agent 完成当前任务后，从自己 `Role + Owner Agent + Status = Ready` 的队列中取最高优先级任务。
- QA agent 不等发布后才工作。开发阶段先写验收清单和 smoke 草案，RC 固定后再做发布后验证。
- Ops agent 不等所有开发结束才工作。后端/前端完成可部署单元后，Ops 提前准备发布脚本、回滚点和 smoke 命令。
- PM Assistant 每轮负责把 agent 输出转换为固定任务源状态、依赖、阻塞和下一步任务。
- System Architect 只在跨模块边界、状态机、公开链接、媒体异步任务、数据一致性或服务拆分争议出现时拉活。

## 运行门禁

### 产品门禁

- 产品说明类任务默认只写 `docs/`；只有负责人明确要求“改代码 / 实现功能”时才进入编码类任务。
- 编码前必须确认需求来源：产品说明、P0 落地清单、bug 复现、QA 报告或用户直接指令。
- 不确定的功能状态必须标记为“假设 / 待确认 / 未实现”，不得写成已完成。

### API 契约门禁

- 任一任务触碰后端 controller/service/entity/repository 或 `frontend/src/api`，必须读取 [rules/api-contract-boundary.md](rules/api-contract-boundary.md)。
- API 变更必须同时说明：请求参数、响应 shape、错误码/业务码、前端调用点、回归页面。
- 公开报告页和宠主入口必须明确是否允许匿名访问、token 口径和隐私提示。

### Data / Model 门禁

- 涉及 JPA entity、表结构、索引、软删除、状态字段、幂等、report token、手机号、媒体 URL 或异步任务状态时，`Data Model Review Required` 必须为 `Yes`。
- 预约状态只允许 `new`、`doing`、`done`、`cancel`；新增状态必须先过 System Architect 和 Product Design。
- 成片任务必须保留 processing / failed / success 状态，以及失败原因的用户可读映射。

### Access / Privacy 门禁

- 涉及登录、门店数据范围、boss/staff 权限、宠主公开页、手机号、报告 token、媒体 URL 或留资时，`Access / Privacy Review Required` 必须为 `Yes`。
- 报告公开访问 token 视为敏感公开链接；日志、报告和截图中不要暴露真实 token 全量值。
- 在真实权限未生产化前，报告必须明确标记 demo identity、mock login 或 pending，不得写成生产权限能力已完成。

### Release Candidate 门禁

- PM Assistant 兼任 RC Steward，负责维护 RC manifest、前后端提交号、纳入/排除范围、dirty diff 分类、发布状态和 QA 结论。
- Backend Ops 和 Frontend Release Ops 只部署 RC Steward 冻结的提交号或明确归档的构建产物。
- QA 只验收当前 RC；发现阻塞问题时由 PM Assistant 建 Hotfix 任务并关联原 RC。
- 任一仓库存在未提交改动时，RC manifest 必须说明是否纳入、排除或等待 owner confirmation。

## 写入锁规则

- 同一时间只允许一个后端 owner 修改同一个 domain/service 组合。
- `frontend/src/api/index.js` 是共享契约入口，改动必须通知受影响的 FE owner 和后端 owner。
- 共享 report 组件、report share utils、public URL utils 同时影响门店端和宠主端，必须声明实际 owner 和 paired reviewer。
- QA 不改业务代码；Ops 不改业务逻辑；PM Assistant 不改产品代码。
- System Architect 不改业务代码，不持有前后端写入锁；架构结论需要落地时，由对应 owner agent 持锁执行。

## 三条业务主线

### Core Booking Flow

目标：门店端和宠主端预约主链路稳定，状态机不产生脏数据。

常驻 owner：
- Store Miniapp FE
- Customer Experience FE
- Backend Core
- Core Flow QA

### Report Sharing

目标：服务报告、公开 H5、分享卡片、成片三态、留资和隐私提示形成闭环。

常驻 owner：
- Store Miniapp FE
- Customer Experience FE
- Report Media Backend
- Report Share QA

### Release / Operations

目标：后端 jar、API、微信小程序、H5 构建和回滚路径可重复。

常驻 owner：
- Backend Ops
- Frontend Release Ops
- PM Assistant
- 关联业务 QA

## 状态同步节奏

- 每个 agent 输出必须包含：状态、修改文件、验证命令、结果、风险、需要主控 review 的问题。
- PM Assistant 每次同步时更新：任务状态、阻塞原因、依赖 owner、下一动作。
- Progress Digest 在用户要求或自动化任务触发时，基于固定任务源、git 状态、QA/Ops 报告和实现度看板生成摘要。
- System Architect 负责提出架构结论、拆解 owner 任务和标记缺口；主控 PM 负责跨域冲突、优先级、RC 冻结和最终边界决策。