feat: add commercial order activation flow

2026-05-18 22:27:42 +08:00
parent c6aa566495
commit 34412b26c0
10 changed files with 1460 additions and 29 deletions
@@ -2138,6 +2138,74 @@
 - 本轮开发无 required 阻塞项。
 - 下一步如果继续商业化主线，建议进入“管理员套餐调整 + 支付前订单/购买意向记录”，然后再接真实支付。

+## 2026-05-18 商业化 Phase2 支付前订单、收款生效与套餐调整闭环
+### 本轮完成项
+- 已把上轮剩余的“订单、套餐调整、赠送额度/人工调整”推进为支付前闭环。
+- 新增商业订单真相源：
+  - 数据表：`commercial_orders`
+  - 模型：`backend/app/models/commercial_order.py`
+  - 迁移：`backend/migrations/versions/20260518_0025_create_commercial_orders.py`
+  - 订单可记录套餐、金额、计费周期、发票状态、联系人、备注、额度快照和生效时间。
+- 新增后端接口：
+  - `GET /api/v1/tenant-settings/billing/orders`
+  - `POST /api/v1/tenant-settings/billing/orders`
+  - `POST /api/v1/tenant-settings/billing/orders/{order_id}/activate`
+  - `PUT /api/v1/tenant-settings/billing/plan`
+- 新增后台能力：
+  - 管理员可创建购买意向/商业订单。
+  - 管理员可确认线下收款并让订单生效。
+  - 订单生效后会把租户套餐、计费状态和额度同步到 `tenants` 真相源。
+  - 管理员可直接调整当前租户套餐、计费状态、审查额度、生成额度、知识库额度、存储额度和用户上限。
+- 前端 `/billing` 已从“用量看板”升级为商业运营台账：
+  - 保留用量统计、试用状态、超额预警。
+  - 新增购买意向/订单创建表单。
+  - 新增商业订单台账。
+  - 新增“确认收款并生效”操作。
+  - 新增管理员套餐/额度调整表单。
+
+### 本轮验证
+- gstack 检查：
+  - `GSTACK_OK`
+- Python 编译检查：
+  - `backend\.venv\Scripts\python.exe -m py_compile backend\app\models\commercial_order.py backend\app\models\__init__.py backend\app\services\tenant_service.py backend\app\api\tenant_settings.py backend\migrations\versions\20260518_0025_create_commercial_orders.py`
+  - 结果：通过。
+- 后端聚焦测试：
+  - `backend\.venv\Scripts\python.exe -m pytest backend\tests\test_tenant_settings_api.py backend\tests\test_permission_metadata.py`
+  - 结果：`16 passed`。
+- 前端聚焦 lint：
+  - `npm --prefix frontend run lint -- src/app/billing/page.tsx src/services/tenant-settings.ts src/types/api.ts`
+  - 结果：通过。
+- 前端生产构建：
+  - `npm --prefix frontend run build`
+  - 结果：通过，`/billing` 已进入构建路由。
+- `git diff --check`
+  - 结果：通过，仅有 Git CRLF 工作区提示。
+
+### 当前状态
+- 商业化 Phase2 已具备支付前经营闭环：
+  - 可统计用量。
+  - 可在到期或超额时硬拦截。
+  - 可创建订单。
+  - 可记录发票需求。
+  - 可确认线下收款。
+  - 可让套餐和额度自动同步生效。
+- 这里的“自动升级”是指订单被管理员确认收款后，系统自动把租户升级到订单套餐；还不是第三方支付回调后的全自动升级。
+
+### 未完成项
+- 真实在线支付仍未接入：
+  - 微信支付或支付宝商户号配置。
+  - 支付二维码/收银台。
+  - 支付回调验签。
+  - 回调后自动生效。
+- 发票当前只是订单级状态记录，尚未做发票抬头、税号、开票文件和发票流转管理。
+- 销售线索跟进面板仍未做；当前只完成订单台账，不是完整 CRM。
+- 本轮未执行远程 Docker 部署，也未对远程 PostgreSQL 执行迁移。
+
+### 阻塞项
+- 本轮开发无 required 阻塞项。
+- 若要进入真实在线支付，需要先确定支付通道：微信支付、支付宝，或先只做银行转账/线下收款。
+- 若要在开发测试服务器验证本轮功能，需要部署后端和前端，并在远程 PostgreSQL 执行 Alembic 到 `20260518_0025`。
+
 ## 2026-05-16 Phase14 第二批法条全文扩容与告警 dry-run 收口
 ### 本轮完成项
 - 已新增第二批合同高频法条清单：