# Feature Spec: 运营系统（Ops-E）

> Status: `Active` · Map: `§7 Phase E` · Phase: `Ops-E` · ECR: `ECR-010`  
> 规范：[../feature-design.md](../feature-design.md)  
> 上游：Ops-A～D（ECR-006～009）

---

## 1. 功能定义

| 字段 | 内容 |
|---|---|
| Name | 运营系统 Ops-E |
| Purpose | 两角色 RBAC、C 端用户封禁、推送任务占位，支撑安全运维 |
| Business Goal | 限制写权限；可处置违规账号；预留推送运营入口（不下发） |

| In | Out |
|---|---|
| `admin_accounts.role`：`super` \| `ops` | 细粒度权限矩阵 / 动态权限表 |
| 用户封禁 / 解封（`users.status` active↔banned） | 设备级 / IP 封禁 |
| `push_jobs` 草稿 CRUD（draft / cancelled） | 真推送通道 · Worker · 站内信 |
| Admin API 动作级 403 + admin-h5 导航裁剪 | UGC · 真支付 |

---

## 2. 用户价值

1. **为何需要：** 全员等同 Admin 风险高；无封禁只能改库。  
2. **完成后获得：** ops 可查可封可建推送草稿；写会员/定价/内容仅 super。  
3. **为何付费：** N/A（内部工具）。

---

## 3. 用户角色

| Actor | 能力 |
|---|---|
| Admin `super` | 全部读写；Admin 账号列表与改角色 |
| Admin `ops` | 读全模块；封禁/解封；推送草稿；**不可**授予会员、改价、内容写、管 Admin |
| C 端 User `banned` | DeviceAuth / 会话拒绝（40310） |
| Guest | 无后台入口 |

---

## 4. 用户流程

```text
Admin 登录 → Me 含 role
  ↓
ops：导航隐藏「定价写 / 内容写入口仍可见只读？按表：内容写否」
  → 用户详情 → 封禁 → C 端下次请求 40310
  → 推送页 → 新建 draft → 可 cancelled
super：另开「管理员」改 role
失败：无权限 403；未登录 401
```

---

## 5. 页面设计

| 路由 | 页面 | 说明 |
|---|---|---|
| `/users/:id` | UserDetailPage | 封禁 / 解封按钮 |
| `/push` | PushJobsPage | 列表 + 新建草稿 |
| `/admins` | AdminsPage | 仅 super：列表改角色 |

```text
AdminShell Nav += 推送 | 管理员(super)
```

---

## 6. 状态

| 态 | 要求 |
|---|---|
| Loading | 列表/详情请求中 |
| Empty | 无推送任务 / 无管理员（不应发生） |
| Error | 403 提示无权限；封禁失败可感知 |
| Normal | 状态与角色展示正确 |

---

## 7. 业务规则

1. Bootstrap / 存量 admin 默认 `super`。  
2. `ops` 调用 grant / PUT plan-prices / 内容写 → HTTP 403。  
3. 封禁写 `users.status='banned'` + audit `user.ban`；解封 `active` + `user.unban`。  
4. 被封用户：Bearer 会话与 DeviceAuth 解析后均拒绝（40310）；可撤销 sessions。  
5. 推送仅 `draft`/`cancelled`；创建不下发。  
6. 仅 `super` 可 `PATCH` admin role；**禁止**降级最后一个 `super`（HTTP 409 / code 40901）。
7. 推送标题非空且 ≤128 字符（rune），否则 400。

---

## 8. 数据

- `admin_accounts.role` varchar CHECK (`super`,`ops`) DEFAULT `super`  
- `users.status` CHECK (`active`,`banned`)（存量补齐）  
- `push_jobs(id, title, body, audience, status, created_by, created_at, updated_at)`

---

## 9. API

| Method | Path | 说明 |
|---|---|---|
| GET | `/api/v1/admin/me` | 响应含 `role` |
| POST | `/api/v1/admin/users/{id}/ban` | super+ops |
| POST | `/api/v1/admin/users/{id}/unban` | super+ops |
| GET | `/api/v1/admin/admins` | super |
| PATCH | `/api/v1/admin/admins/{id}` | super · body `{role}` |
| GET | `/api/v1/admin/push-jobs` | super+ops |
| POST | `/api/v1/admin/push-jobs` | super+ops · draft |
| PATCH | `/api/v1/admin/push-jobs/{id}` | 改文案或 cancelled |

既有写接口对 `ops` 返回 403。

---

## 10. 埋点

N/A（内部）；审计日志覆盖封禁与角色变更。

---

## 11. 事件

| Audit action | 何时 |
|---|---|
| `user.ban` / `user.unban` | 封禁变更 |
| `admin.role_update` | 改角色 |
| `push_job.create` / `push_job.update` | 推送占位 |

---

## 12. 验收

**Given** ops 账号  
**When** PUT plan-prices 或 grant membership  
**Then** 403  

**Given** 用户被 ban  
**When** C 端带该 user 的 DeviceAuth 请求  
**Then** 40310  

**Given** 唯一 super  
**When** PATCH role=ops  
**Then** 40901，角色不变  

**Given** push title 超 128 字  
**When** POST push-jobs  
**Then** 40055  

---

## 13. AI 开发前检查

- [x] Spec §4/7/9/12  
- [x] ECR-010 · BD-2026-010  

---

## 14. Implementation Notes

| 项 | 内容 |
|---|---|
| Packages | `middleware` · `service/admin` · `AdminRepo` · admin-h5 |
| Migration | `000016_ops_system` |
| Label | Feature Complete（Ops-E MVP） |