邹方成
f536178428
feat(交易记录): 新增交易记录管理页面与API接口 feat(上传): 添加统一上传接口支持自动识别文件类型 feat(用户管理): 为用户模型添加备注字段并更新相关接口 feat(邮件): 实现SMTP邮件发送功能并添加测试脚本 feat(短信): 增强短信服务配置灵活性与日志记录 fix(发票): 修复发票列表时间筛选功能 fix(nginx): 调整上传大小限制与超时配置 docs: 添加多个功能模块的说明文档 docs(估值): 补充估值计算流程与API提交数据说明 chore: 更新依赖与Docker镜像版本
60 lines
4.0 KiB
Markdown
60 lines
4.0 KiB
Markdown
## 目标
|
||
- 创建若干“交易记录”（对公转账付款凭证）测试数据，并确保后台管理可以正常查看、筛选与分页。
|
||
- 全流程可回滚，严格隔离开发与生产数据。
|
||
|
||
## 关键假设
|
||
- 交易记录以 `PaymentReceipt`（关联 `Invoice`）为核心：后端模型位于 `app/models/invoice.py`。
|
||
- 后端已提供发票与凭证相关 API：
|
||
- 发票：`GET/POST /api/v1/invoice/*`（`app/api/v1/invoice/invoice.py`）
|
||
- 凭证：`POST /api/v1/invoice/{id}/receipt`、列表 `GET /api/v1/transactions/receipts`（`app/api/v1/transactions/transactions.py`）。
|
||
- 现有后台页已覆盖发票列表 `web/src/views/transaction/invoice/index.vue`，尚无“凭证专属列表”页面。
|
||
|
||
## 数据建模与来源
|
||
- `Invoice`：发票记录（开票状态、类型、抬头信息、公司税号、银行账户等）。
|
||
- `PaymentReceipt`：对公转账付款凭证（字段含 `invoice_id`、`url`、`note`、`verified`、`created_at`）。
|
||
- 为保证后台可见，需同时插入可查询的 `Invoice` 与其关联的 `PaymentReceipt`。
|
||
|
||
## 实施路径
|
||
### 方案 A：通过现有 API 批量生成（零代码改动，首选）
|
||
- 步骤：
|
||
- 调用 `POST /api/v1/invoice/create` 批量创建 5–10 条覆盖不同类型/状态的发票（含公司名、税号、银行账户等）。
|
||
- 对每条发票调用 `POST /api/v1/invoice/{id}/receipt` 上传/登记 1–2 条付款凭证（`file_url` 或 `url`、`note`、`verified`）。
|
||
- 可选：通过 `POST /api/v1/transactions/send-email` 生成邮件日志，验证通知链路。
|
||
- 优势：不改动代码，快速、低风险；与现有权限和审计链路一致。
|
||
|
||
### 方案 B：后端种子脚本（仅开发环境，便于重复初始化）
|
||
- 在 `app/core/init_app.py` 新增 `init_demo_transactions()`：
|
||
- 仅在开发环境执行（如 `ENV=dev`）；避免污染生产。
|
||
- 批量创建 `Invoice` 测试数据，再为每条 `Invoice` 创建若干 `PaymentReceipt`。
|
||
- 为可识别性，在 `note` 中加入 `DEMO` 标签或新增布尔字段（若允许）。
|
||
- 将该方法纳入现有 `init_data()` 的“开发模式”分支；保留一键清理逻辑（删除 `DEMO` 标记数据）。
|
||
|
||
## 前端后台展示
|
||
- 新增后台页“交易记录”：`web/src/views/transaction/receipts/index.vue`（Naive UI）：
|
||
- 数据源：`GET /api/v1/transactions/receipts`；支持分页与筛选（手机号、公司名、税号、状态、类型等）。
|
||
- 列：凭证时间、公司名称、税号、转账备注（`note`）、审核状态（`verified`）、关联发票 ID/类型，查看详情。
|
||
- 行为：查看详情（`GET /api/v1/transactions/receipts/{id}`），跳转到发票详情。
|
||
- 菜单与权限：
|
||
- 在后端 `init_menus()` 增加“交易记录”菜单，并为管理员角色在 `init_roles()` 授权；在 `init_apis()` 注册 `receipts` 相关 API。
|
||
- 备选轻改：在 `invoice/index.vue` 增加“凭证数/链接”列与详情入口，先实现可见性，后续再拆分独立列表页。
|
||
|
||
## 验证步骤
|
||
- 数据验证：
|
||
- 通过 API 查询：`GET /api/v1/invoice/list` 与 `GET /api/v1/transactions/receipts`，确认条数、筛选与分页正确。
|
||
- 随机抽样验证 `PaymentReceipt` 与对应 `Invoice` 关联完整、字段齐备。
|
||
- 前端验证：
|
||
- 后台页加载正常、列渲染与筛选可用；详情跳转与状态标签正确。
|
||
- 安全验证：
|
||
- 在生产环境禁用种子逻辑；标记测试数据，提供清理。
|
||
|
||
## 回滚与清理
|
||
- 提供清理脚本/接口：按 `DEMO` 标记或 ID 范围批量删除测试发票与凭证。
|
||
- 菜单与权限变更可回退至原状态（移除菜单、撤销授权）。
|
||
|
||
## 交付物
|
||
- （A）一组 API 请求示例（可直接运行）生成测试交易与凭证。
|
||
- （B）可选：开发环境种子函数与清理脚本。
|
||
- （C）前端“交易记录”后台页（或在发票页增加凭证列的最小改动）。
|
||
|
||
## 备注
|
||
- 编码时为新增函数与接口补充函数级注释（功能、参数、返回值说明），遵循现有代码风格与安全规范。 |