bid-doctor/docs/architecture/m6-plan.md

M6 剩下的 P0：额度流水、套餐开通、数据删除、运营后台（实现计划 v0.1）

依据：FR-M6-03 / 05 / 06 / 07 / 09（docs/analysis/03-functional-requirements.md），J4、J5（02-user-journeys.md），G6、G8、G10，决策 Q9、Q13、P1、DM4；表结构已在基线迁移里（data-model.md §4、§6），用户端接口已在 openapi.yaml 里定义；运营后台的接口和选型「做到时再定」（架构 §3.11、§4.3）。

0. 现状

方面	已有	还没有
额度	注册发放、预扣 / 结算 / 退回 / 免扣、GET /quota、顶栏额度（≥ 80% 赭色）	流水接口和额度页、80% / 100% 提醒、人工调整、过期
套餐	免费版注册即开通、GET /plans、专业版套餐（解析 500，D2 待定）	开通 / 续费申请、运营开通、到期处理
删除	资质删除（QL6）	删除项目、注销账号
通知	解析、检查、报告完成写通知；事件流	前端通知入口、标为已读
运营后台	表：ops_admin、ops_session；角色 bd_ops（文档里有，部署脚本里还没建）；反馈写入	进程、登录、接口、前端，全部没有

另外发现一处冲突：原型 project.html 的删除写「30 天内可以在回收站恢复」，而 G10、DM4（已确认）是删除时销毁项目数据密钥、彻底删除。按决策优先，见 M6-1。

1. 用户端

1.1 额度页（FR-M6-03，原型 quota.html）

• 侧栏账户区（头像、套餐标签）点开进「额度与套餐」页；顶栏额度改成链接，也进这个页。
• 页面：本期额度卡（剩余 / 已用 / 退回，期间起止）→ 扣点规则表（原型原样）→ 按功能分布（读标招标文件、补遗和澄清、查标、免扣次数）→ 本期流水。
• 流水：GET /quota/entries，按单位筛选、按时间倒序分页；每行写时间、类型（发放 / 预扣 / 结算 / 退回 / 免扣 / 过期 / 调整）、数量（+ / −，墨色，Q1）、余额、关联项目 · 任务（「招标文件」「第 2 次检查」；项目删了写「已删除的项目」和任务编号，G10）、说明（调整原因、失败原因、「距上次扣额度的检查不到 24 小时」）。导出 CSV 在前端生成。
• 提醒：预扣后余额跨过 80%、100%（按本期发放算）时写站内通知，quota_alert 保证每期每档只提醒一次。

1.2 开通与续费（FR-M6-05，G8）

• 免费版：额度页和顶栏「额度用完」提示里有「开通专业版」；专业版：到期前 30 天起显示「续费」。
• 申请对话框（原型）：企业名称（注册时的，只读）、发票类型（普票 / 专票）、纳税人识别号、联系人、手机号；专票再加地址电话、开户行账号。POST /activation-requests，不扣额度、不用先付款。
• 提交后页面顶部显示申请单号、状态（等待对公转账 / 已到账 / 已开通 / 已退回）、收款信息（收款单位、开户行、账号，从配置读 BD_PAYEE_*）和「转账备注写申请单号」。
• 运营确认到账并开通：建专业版订阅、发放额度（流水「发放」，说明写申请单号），发站内通知；之后填发票号。
• 续费：当前专业版还没到期时，新一期从旧一期结束时开始；旧一期剩下的额度到期清零（「本期没用完的不结转」，原型）。

1.3 到期（FR-M6-05）

• worker 每天跑一次定时任务（Procrastinate 周期任务）：到期的订阅改「已过期」、记「过期」流水把余额清零；排队的下一期到点发放。
• 提前 30 天、7 天、到期当天各发一次站内通知。
• 过期后：数据保留，只读（M6-5）。

1.4 删除项目（J4、G10、data-model §6.1）

• 入口：项目头「更多」菜单（和归档放一起），已递交、已归档的也能删。
• 确认框：写明删掉什么、保留什么（额度流水、不含业务内容的审计），输入项目名称确认（原型）。
• DELETE /projects/{id}：同一事务里写审计、抹掉这个项目审计的内容、删项目行（级联）、销毁数据密钥；提交后后台任务删对象存储前缀。正在解析 / 检查的项目先取消任务再删（预扣退回）。

1.5 账号页与注销（J4、data-model §6.2）

• 「额度与套餐」页旁边一个「账号」页：企业名称、手机号（脱敏）、显示名、套餐；最下面「注销账号」。
• 注销：确认框写明后果（全部项目、资质库删除；开通申请和发票记录按财务要求保留；剩余额度作废、不退款），输入企业名称 + 短信验证码。POST /tenant/close：立即吊销会话、企业标「已注销」，项目按 §1.4 由后台任务逐个删。

1.6 通知入口

• 顶栏加铃铛（原型有），有未读时带圆点；点开是浮层列表（最近 30 条：解析 / 检查 / 报告完成、额度提醒、开通结果、到期提醒），点一条跳到相关页面并标为已读，「全部标为已读」。POST /notifications/read。

2. 运营后台（FR-M6-09）

2.1 形态

• 后端：同一个 Python 包的第三种进程 bid-doctor ops（和 api、worker 一样的镜像），单独端口、路径前缀 /ops/v1，用 bd_ops 数据库角色（绕过行级安全策略）；用户端 api 进程里不挂任何运营接口。部署时运营端口只对内网 / 白名单开放。
• 登录：用户名 + 密码 + TOTP 二次验证；IP 白名单（BD_OPS_ALLOWED_IPS，空着时拒绝启动于生产环境）；会话 8 小时；账号用命令行建（bid-doctor ops-admin create），没有自助注册。
• 前端：apps/admin，Vue 3 + Vite，复用 tokens.css 和组件样式，不引入带样式的框架（M6-3）；单独构建、单独部署，私有化不交付。
• 审计：每个运营操作（包括查询企业详情）都写审计事件，操作人记运营账号。

2.2 页面和接口（最小版）

页面	做什么	接口（/ops/v1）
企业	按企业名称、手机号（用 HMAC 查）、申请单号搜；详情：成员（手机号脱敏）、套餐和到期日、各单位余额、项目数、最近任务；不显示项目名称和任何业务内容	GET /tenants、GET /tenants/{id}
开通申请	待处理在前；标记「已到账」→「开通」（选套餐和周期，默认专业版 1 年），或「退回」写原因；开通后填发票号	GET /activation-requests、POST .../{id}/activate、/reject、/invoice
额度调整	在企业详情里：单位、±数量、原因（必填）	POST /tenants/{id}/quota-adjustments
反馈	误报 / 漏报列表：类型、用户写的理由、问题标题和级别、规则编号、提示词版本、出处页码，不显示招标 / 投标文件原文（M6-7）	GET /feedback
失败任务	解析、检查、报告失败的：错误类别、错误码、阶段、耗时、模型调用次数，不含文档内容	GET /failed-jobs
审计	按企业 / 对象 / 时间查审计事件（项目删除后只剩类型和时间）	GET /audit-events

3. 步骤

1. 用户端后端：流水、提醒、开通申请、到期任务、删除项目、注销、通知已读，各配集成测试（额度对账：任何失败任务都没有净扣点；删除后对象不可解密）。
2. 用户端前端：额度与套餐页、账号页、通知入口、删除项目。
3. 运营后台后端：ops 进程、bd_ops 角色（部署脚本）、登录和 TOTP、上表接口、审计。
4. 运营后台前端：apps/admin 六个页面。
5. 浏览器走查：注册 → 用完免费额度 → 申请开通 → 运营开通 → 流水核对 → 到期（改时钟）→ 删除项目 → 注销。

4. 待确认（建议见每条）

#	问题	建议
M6-1	删除项目要不要「30 天回收站」（原型这么写）	不要，立即彻底删除：按已确认的 G10、DM4 销毁数据密钥；回收站要软删除，和「彻底删除」冲突（同 QL6）。确认框要求输入项目名称，写明不能恢复。原型文案改掉
M6-2	运营接口放在哪	单独的第三种进程 bid-doctor ops（同一镜像、单独端口、bd_ops 角色）；用户端 api 进程里没有运营接口，绕过行级安全策略的代码不会被公网请求触到
M6-3	运营后台前端选型	Vue 3 + 复用 tokens.css / 组件样式，不引入带样式框架：页面只有六个、以表格和表单为主；和用户端同一套组件，维护成本低。另一种做法是引入 Element Plus 之类加快开发，但多一套视觉和依赖
M6-4	运营登录	用户名 + 密码 + TOTP + IP 白名单，账号命令行创建（架构 §3.11 已写独立登录、白名单、二次验证）
M6-5	套餐到期后怎么办	不自动降为免费版；项目只读（能看、能下载已导出的报告、能删除；不能新建项目、解析、检查、改清单）；额度清零；提前 30 天、7 天、当天提醒。续费到账后恢复
M6-6	开通申请页写不写价格、收款信息从哪来	页面不写价格（D2 额度数字和定价都还没定），写「运营会联系你确认金额」；收款单位 / 开户行 / 账号从配置读，没配时显示「（待定）」，生产环境没配拒绝启动
M6-7	运营看反馈时能不能看原文	不看原文：只看标题、理由、规则编号、提示词版本、页码（红线 10：数据敏感、按租户隔离）。要复盘原文时请用户导出报告发过来，或以后做「用户授权查看」
M6-8	注销账号的确认方式	输入企业名称 + 短信验证码；有没到期的专业版时写明剩余额度作废、不退款

5. 落地记录（2026-11-05）

M6-1–M6-8 全部按建议确认后实现。和上文不一样、或计划里没写到的：

• 迁移 0010：订阅加「排队中」（scheduled），续费到账时当前一期还没到期就排队，到点由定时任务生效发放；开通申请加申请单号 request_no（KT- 加 6 位）；通知加「已到期」「申请被退回」；billing_due(now) 是 bd_auth 所有的 SECURITY DEFINER 函数，定时任务（worker 每小时 billing_tick）用它跨企业找到期、该生效、该提醒的订阅，只拿编号，处理时回到各企业自己的租户事务。到期时还有没了结的预扣就等下一次再清零，避免退回的 1 次漏在余额里。
• 迁移 0011：bd_ops 的权限（跨企业只读、运营账号和会话表可写、审计可写），bd_app 收回运营账号表的权限。角色本身由部署脚本建（init-roles.sh，CI 同一个脚本）。
• 只读的落点：到期后写操作在鉴权依赖里统一拦（identity/deps.py 的 READ_ONLY_ALLOWED），退出、续费申请、删除项目、注销、通知已读、反馈、管理登录设备照常放行；不用逐个接口去改。
• 额度单位：只发放现在用得上的「解析」；专业版套餐里的 generate（M4 标书生成）等功能上线再发，免得顶栏出现用不了的额度。
• 删除项目：正在解析、检查、生成报告时返回 409 job_already_running，先取消（预扣退回）再删；data_key 销毁以后不再建新密钥，还在跑的任务写不回文件。审计的 before / after 改为 Python 的 None 存成 SQL NULL（以前是 JSON 的 null）。
• 注销账号：验证码改为登录后 POST /me/sms-codes 发到自己的号码（前端不知道完整号码）；同步部分完成后手机号就能重新注册，删项目、资质库、抹审计内容、销毁密钥、清对象存储由后台任务 close_tenant 做，可以重复执行。
• uuid7 单调：同一进程内严格递增（RFC 9562 方法 2），额度流水按编号排序算逐条余额。
• 顺手修的：取消解析、取消检查的接口在刷新以前转 API 会触发懒加载报错（MissingGreenlet），取消按钮会 500。
• 运营后台：接口说明见 ops-api.md；前端 apps/admin（pnpm dev:admin，:5174）六个页面：登录、开通申请、企业（含调额度）、误报 / 漏报、失败任务、审计。

测试：后端 156 个（新增 test_billing_flow.py 4 个、test_ops_console.py 3 个，覆盖流水对账、提醒只发一次、开通 / 续费 / 到期只读、删除后不可解密、注销后可重新注册、运营登录和 IP 白名单、bd_app 读不到运营表、bd_ops 改不了业务表）。浏览器走查：注册 → 申请开通 → 运营标记到账、开通、登记发票 → 流水核对 → 调额度 → 到期只读 → 删除项目 → 注销账号。

没做的：运营后台没有「撤回申请」「延长订阅」这类操作（需要时用退回 + 重新申请、调额度代替）；收款信息和发票是线下流程，系统只登记发票号。

运营后台第二版（2026-11-05，决策 M6-9、M6-10）：菜单改到左侧（墨色渐变底，标准横版 logo 反白，非生产环境挂赭色环境标签），分组可以展开收起、每项带图标和待办数（GET /summary），底部是当前运营人员（姓名、角色）和退出；登录页加 logo。运营人员的角色只留结构：迁移 0012 加 ops_admin.role，权限点和「角色 → 权限点」对应表、每个接口的检查点、按权限点过滤的菜单都已就位，现在只有管理员。见 ops-api.md。