petstore-docs/.agents/fixed-team-operating-model.md

宠小它 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。
• 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 冻结和最终边界决策。