petstore-docs/门店管理后台-PhaseA-编码任务brief.md

# 门店 Web 后台 · Phase A 编码任务 Brief

> 状态：任务源草案  
> 日期：2026-07-10  
> **编码启动门禁**：须用户明确说「改代码 / 实现后台」后，各 Coding 任务才可从 Ready 拉活开工。  
> 上游：PRD、线框、技术选型草案、本体 `BR-ADMIN-*`

Workstream 建议名：`Store Admin Console`

---

## 任务总览

| # | Task Name | Owner | Priority | Status | Depends On |
|---|-----------|-------|----------|--------|------------|
| T0 | 登记 Store Admin FE 角色与写入锁 | PM Assistant / Docs | P0 | Done（本文+角色文件） | — |
| T1 | 脚手架 admin（Vue3+Vite+Element Plus） | Store Admin FE | P0 | **Done** | — |
| T2 | 实现 service-customers 聚合 API | Backend Core | P0 | **Done** | — |
| T3 | 壳层登录 + 工作台 + 预约中心 | Store Admin FE | P0 | **Done（MVP）** | T1 |
| T4 | 报告中心 + 回访线索 | Store Admin FE | P0 | **Done（MVP）** | T1 |
| T5 | 客户列表对接新 API + 排班 + 设置 | Store Admin FE | P0 | **Done** | T1、T2 |
| T6 | Phase A 端到端 QA 清单与冒烟 | Core Flow QA + Report Share QA | P0 | Ready（清单已出） | T3–T5 |

\*Ready = 字段完整，可排队；**未授权编码前不得改 `admin/` / `backend` 业务代码**。

---

## T1 · 脚手架 admin

| 字段 | 内容 |
|------|------|
| Task Name | 初始化门店 Web 后台工程 |
| Role | `Store Admin Frontend` |
| Owner Agent | Store Admin FE |
| Paired QA | Core Flow QA |
| Workstream | Store Admin Console |
| Track | Coding |
| Status | Done（工作台事件漏斗已接入） |
| Repo/Path | `admin/**` |
| Service Lock | `admin-scaffold` |
| Depends On | 用户授权编码；选型确认 Vue3+Element Plus |
| Due Date | TBD |
| RC Included | TBD |
| Output Link | TBD |
| Blocker Owner | None |
| Commit / RC | Not Frozen |
| Architecture Review Required | No（选型文档已评） |
| Data Model Review Required | No |
| Access / Privacy Review Required | Yes（token 存储） |

**写入范围**：仅 `admin/` 新建；只读 `docs`、现网 API。  
**验收**：`npm run build` 通过；空壳可配 proxy 到 `localhost:8080`；侧栏 IA 与 PRD §0.4 一致且无禁入模块。  
**验证**：

```bash
cd /Users/apple/_src/petstore/admin && npm run build
```

---

## T2 · service-customers API

| 字段 | 内容 |
|------|------|
| Task Name | 建立 StoreCustomer 主档与服务客户聚合列表 |
| Role | `Backend Core` |
| Owner Agent | Backend Core |
| Paired QA | Core Flow QA |
| Workstream | Store Admin Console |
| Track | Coding |
| Status | Done（2026-08-01） |
| Repo/Path | `backend/.../entity|mapper|controller|service`（admin 客户域） |
| Service Lock | `admin-service-customers` |
| Depends On | 用户授权编码；PRD §7.6 |
| ontologyRefs | `[entity:store_customer, action:admin_list_service_customers, rule:BR-SC-001, rule:BR-ADMIN-001, rule:BR-ADMIN-002, rule:BR-ADMIN-003, rule:BR-ADMIN-004]` |
| Architecture Review Required | Yes（新 `/api/admin/**` 前缀） |
| Data Model Review Required | Yes（`t_store_customer` 唯一约束与历史迁移） |
| Access / Privacy Review Required | Yes（手机号脱敏、本店） |

**验收**：boss/staff 本店 200；customer 403；跨店不可见；返回稳定 `storeCustomerId` 且手机脱敏；无余额/次卡字段；搜索含宠物名；本体与代码无漂移。
**验证**：

```bash
cd /Users/apple/_src/petstore/backend && mvn -q test
python3 /Users/apple/_src/petstore/docs/graph/validate_ontology.py docs
python3 /Users/apple/_src/petstore/docs/graph/audit_drift.py
```

---

## T3 · A.1 壳层 + 工作台 + 预约

| 字段 | 内容 |
|------|------|
| Task Name | 后台登录落点与预约中心 |
| Role | `Store Admin Frontend` |
| Owner Agent | Store Admin FE |
| Paired QA | Core Flow QA |
| Workstream | Store Admin Console |
| Track | Coding |
| Status | Ready（待授权） |
| Repo/Path | `admin/src/**`（shell/workbench/appointments） |
| Service Lock | `admin-a1-pages` |
| Depends On | T1；`entity:business_event` |
| ontologyRefs | `[entity:admin_console, entity:workbench, entity:business_event, action:view_workbench, action:start_service, rule:BR-ADMIN-001, rule:BR-APPT-001, rule:BR-BE-001]` |
| Access / Privacy Review Required | Yes |

**验收**：对齐 PRD §1–3 与线框 A0–A2；staff/boss 可开始服务；customer 进不去；待办下钻参数正确；报告提交/打开/留资来自本店 BusinessEvent 汇总，未跟踪的转预约显示未知。
**验证**：`AdminBusinessEventControllerTest` + `AdminBusinessEventServiceTest` + admin 构建；发布后按 PRD §3.6 / §2.6 手工冒烟。

---

## T4 · A.2 报告 + 线索

| 字段 | 内容 |
|------|------|
| Task Name | 报告中心与回访线索页 |
| Role | `Store Admin Frontend` |
| Owner Agent | Store Admin FE |
| Paired QA | Report Share QA |
| Workstream | Store Admin Console |
| Track | Coding |
| Status | Ready（待授权） |
| Repo/Path | `admin/src/**`（reports/leads） |
| Service Lock | `admin-a2-pages` |
| Depends On | T1 |
| ontologyRefs | `[entity:report, entity:highlight_video, entity:report_lead, rule:BR-HL-001, rule:BR-LEAD-002, rule:BR-ADMIN-003]` |
| Access / Privacy Review Required | Yes（report_token、openid 脱敏） |

**验收**：成片三态与失败文案；复制链接；`processing`>30min 可标异常；线索无完整 openid。  
**验证**：PRD §5.5 / §6.5 + Report Share QA 清单。

---

## T5 · A.3 客户 + 排班 + 设置

| 字段 | 内容 |
|------|------|
| Task Name | 客户列表排班与门店设置 |
| Role | `Store Admin Frontend` |
| Owner Agent | Store Admin FE |
| Paired QA | Core Flow QA |
| Workstream | Store Admin Console |
| Track | Coding |
| Status | Ready（待授权） |
| Repo/Path | `admin/src/**`（customers/schedule/settings） |
| Service Lock | `admin-a3-pages` |
| Depends On | T1、T2 |
| ontologyRefs | `[entity:store_customer, action:admin_list_service_customers, action:admin_manage_schedule, action:admin_update_settings, rule:BR-USER-001, rule:BR-ST-001]` |
| Access / Privacy Review Required | Yes |

**验收**：客户页无余额列；排班与小程序一致；设置改时段生效；删员工仅 boss。  
**验证**：PRD §4.3 / §7.7 / §8.4。

---

## T6 · QA 冒烟

| 字段 | 内容 |
|------|------|
| Task Name | Phase A 后台端到端验收 |
| Role | `Core Flow QA` / `Report Share QA` |
| Owner Agent | Core Flow QA（主）+ Report Share QA（报告段） |
| Paired QA | — |
| Workstream | Store Admin Console |
| Track | QA |
| Status | Ready（待授权后随开发并行写清单） |
| Repo/Path | `docs/qa-reports/**` |
| Service Lock | `docs-qa-admin-phase-a` |
| Depends On | T3–T5 可测增量 |
| Access / Privacy Review Required | Yes |

**验收**：执行 PRD §11 剧本；输出证据链接。

---

## 修订记录

| 日期 | 说明 |
|------|------|
| 2026-07-10 | 首版：T0–T6；编码待用户授权 |