zfc/guzhi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
guzhi/.trae/documents/初始化交易记录数据并在后台可见的实施方案.md
邹方成 f536178428 feat: 新增交易记录管理功能与统一上传接口 
feat(交易记录): 新增交易记录管理页面与API接口
feat(上传): 添加统一上传接口支持自动识别文件类型
feat(用户管理): 为用户模型添加备注字段并更新相关接口
feat(邮件): 实现SMTP邮件发送功能并添加测试脚本
feat(短信): 增强短信服务配置灵活性与日志记录

fix(发票): 修复发票列表时间筛选功能
fix(nginx): 调整上传大小限制与超时配置

docs: 添加多个功能模块的说明文档
docs(估值): 补充估值计算流程与API提交数据说明

chore: 更新依赖与Docker镜像版本
2025-11-20 20:53:09 +08:00

4.0 KiB
Raw Blame History

目标

  • 创建若干“交易记录”（对公转账付款凭证）测试数据，并确保后台管理可以正常查看、筛选与分页。
  • 全流程可回滚，严格隔离开发与生产数据。

关键假设

  • 交易记录以 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）前端“交易记录”后台页（或在发票页增加凭证列的最小改动）。

备注

  • 编码时为新增函数与接口补充函数级注释（功能、参数、返回值说明），遵循现有代码风格与安全规范。