# 运营后台接口（/ops/v1）

运营后台的接口不在用户端契约 `openapi.yaml` 里：它们只挂在 `bid-doctor ops` 进程上（决策 M6-2），前端 `apps/admin` 是唯一的调用方，类型在 `apps/admin/src/api.ts` 里手写。实现见 `server/src/bid_doctor/ops/`（`console_api.py` 路由、`console.py` 查询、`auth.py` 登录）。

## 安全

| 方面 | 做法 |
|---|---|
| 进程 | 和 api、worker 同一镜像的第三种进程，单独端口（开发 8019）；部署时只对内网开放 |
| 来源地址 | `BD_OPS_ALLOWED_IPS`（CIDR 列表）以外的请求一律 403 `ops_ip_denied`；生产环境不配或放开全部地址拒绝启动 |
| 登录 | 用户名 + 密码（scrypt）+ TOTP 6 位动态码（身份验证器 App）；同一用户名 15 分钟最多试 5 次；账号只能用 `bid-doctor ops-admin create` 建 |
| 会话 | cookie `bd_ops_session`（HttpOnly、SameSite=Strict，8 小时）+ 写操作带 `X-CSRF-Token`（等于 cookie `bd_ops_csrf`） |
| 数据库 | 跨企业查询用 `bd_ops`（绕过行级安全策略，业务表只读，运营账号和会话表可写，审计可写）；对某个企业的修改走 `bd_app` + 那个企业的租户事务。`bd_app` 读不到运营账号表 |
| 留痕 | 每个操作都写审计（`actor_kind = ops`，记运营账号），查看企业详情也记一条 `ops.tenant.view` |
| 内容 | 不显示项目名称、招标 / 投标原文、审计的修改前后（决策 M6-7、红线 10） |

## 角色和权限点（只留结构，决策 M6-10）

以后会有管理员、运营、销售、运维等不同权限的运营人员。现在只建结构：

- `ops_admin.role`（迁移 0012，不加 CHECK）；
- 权限点 `OpsPermission`（`ops/auth.py`）：`tenant.view`、`quota.adjust`、`activation.manage`、`invoice.manage`、`feedback.view`、`jobs.view`、`audit.view`；
- 「角色 → 权限点」对应表 `ROLE_PERMISSIONS`：现在只有 `admin`（全部权限）。表里有、对应表里没有的角色什么权限都没有；
- 每个接口开头都调 `auth.require(op, 权限点)`，没有权限返回 403 `forbidden`；`/me` 返回角色和权限点，前端菜单按权限点过滤（`apps/admin/src/nav.ts`），一组都看不到时整组不显示。

加角色时只改 `ROLE_PERMISSIONS`、`ROLE_LABEL` 和 `ops-admin create --role` 的说明；要不要有「运营账号管理」页面、谁能建账号，到时再定。

## 菜单（决策 M6-9）

左侧菜单由 `apps/admin/src/nav.ts` 一处配置：分组（客户、质量、安全）→ 菜单项（图标、路由、要的权限点、待办数）。分组可以展开收起，记在本机；跳到收起分组里的页面时自动展开。待办数来自 `GET /summary`（待处理的开通申请、近 7 天失败任务、近 7 天反馈），做完操作和每分钟刷新一次。

## 接口

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/auth/login` | `{username, password, totp}`；失败 401 `ops_login_failed` |
| POST | `/auth/logout` | |
| GET | `/me` | 当前运营账号：角色、权限点、运行环境（非生产环境时菜单顶部提示） |
| GET | `/summary` | 菜单上的待办数；没有权限的那一项给 0 |
| GET | `/tenants?q=` | 企业名称（模糊）、手机号（精确，按 HMAC 查）、申请单号；不带条件列最近注册的 50 个 |
| GET | `/tenants/{id}` | 成员（手机号脱敏）、套餐历史、最近 30 条额度流水（不带项目名称）、任务按状态计数 |
| POST | `/tenants/{id}/quota-adjustments` | `{unit: parse, amount, reason}`；原因必填，不能扣成负数（G6） |
| GET | `/activation-requests?status=` | 待处理（等待转账、已到账）在前 |
| POST | `/activation-requests/{id}/paid` | 标记到账（只限等待转账） |
| POST | `/activation-requests/{id}/activate` | `{months = 12}`；免费版 / 已过期马上开始新一期，专业版没到期时新一期排队（续费） |
| POST | `/activation-requests/{id}/reject` | `{note}`，用户在额度页看得到原因 |
| POST | `/activation-requests/{id}/invoice` | `{invoice_no}`，开通以后才能登记 |
| GET | `/feedback?kind=` | 误报 / 漏报：标题、级别、理由、规则编号、规则集和提示词版本、页码 |
| GET | `/failed-jobs` | 解析、检查、报告失败的任务：错误类别、错误码、阶段、耗时、模型调用次数 |
| GET | `/audit-events?tenant_id=&action=` | 动作、对象、操作人、时间；`action` 按前缀筛选 |

## 本地跑起来

```
cd server && ../.venv/bin/bid-doctor ops            # :8019
../.venv/bin/bid-doctor ops-admin create --username dev --display-name 开发运营   # 打印 otpauth:// 地址，用身份验证器 App 添加
pnpm dev:admin                                      # :5174，/ops 代理到 :8019
```

已有的数据卷是在加 `bd_ops` 之前初始化的，要手工建一次角色（新数据卷由 `deploy/compose/postgres/init-roles.sh` 建）：

```
docker exec -e PGPASSWORD=dev-owner bid-doctor-postgres-1 psql -U bd_owner -d bid_doctor \
  -c "CREATE ROLE bd_ops LOGIN BYPASSRLS PASSWORD 'dev-ops'" -c "GRANT CONNECT ON DATABASE bid_doctor TO bd_ops"
```