================================================================================
                     产地证数据 AI 回填工具 V5.0 使用说明书
================================================================================

  智能提取报关/产地证数据 → 自动回填 Excel 模板
  支持 DeepSeek AI 大模型智能提取 + 格式学习
  支持多工作表（INV/PKL/CO）联合导入
  支持 .xls / .xlsx / .docx / .pdf 等多种格式
  提取记录自动同步微信小程序云数据库

================================================================================
                               目    录
================================================================================

  1. 系统概述
  2. 安装与运行
  3. 快速入门
  4. AI 导入模式
  5. 常规导入模式
  6. 格式学习（新功能）
  7. 文件管理
  8. 提取记录云同步
  9. 云存储导入
  10. 系统设置与注册
  11. 常见问题
  12. 支持的文件格式
  附录 A：快捷键
  附录 B：Excel 列头命名建议

================================================================================
第1章  系统概述
================================================================================

  产地证数据 AI 回填工具是一款专业的报关辅助工具，主要功能：

  ◆ 核心功能

  ▪ AI 智能提取：自动识别发票/装箱单/合同/产地证文件中的商品信息
  ▪ 自动回填：提取的数据自动填入 Excel 模板（格式标准.xlsm）
  ▪ 格式学习（V5.0 新增）：AI 学会的格式自动记忆，下次同格式无需 AI
  ▪ 英译中：自动翻译英文品名为中文
  ▪ HS 编码提取：从 INV/CO 工作表自动提取 HS 编码
  ▪ 多工作表联合：智能识别 INV/PKL/CO 等多个工作表并合并数据
  ▪ 云同步（V5.0 新增）：提取记录自动同步到微信小程序云数据库
  ▪ 云存储导入：从微信小程序云存储下载文件并处理

================================================================================
第2章  安装与运行
================================================================================

  ◆ 系统要求

  - 操作系统：Windows 10/11
  - 磁盘空间：约 500MB
  - 网络：需要互联网连接（AI 功能和云同步）
  - Python 3.8+（如使用源码运行）

  ◆ 方式一：一键安装包

  1. 解压 产地证工具_v1.0_安装包.zip 到任意目录
  2. 双击运行 安装向导.bat
  3. 选择安装路径（默认 D:\产地证工具）
  4. 自动创建桌面快捷方式
  5. 双击桌面「产地证工具」运行

  ◆ 方式二：便携运行

  1. 解压安装包到 U 盘或任意目录
  2. 直接进入目录双击 产地证工具.exe
  3. 首次启动自动安装依赖（需要联网）

  ◆ 方式三：源码运行

  需要安装 Python 3.8+，然后：
  pip install openpyxl pandas python-docx pdfplumber pypdf olefile xlrd
  python "to co.py"

  ◆ 卸载

  直接删除安装目录和桌面快捷方式即可。

================================================================================
第3章  快速入门
================================================================================

  ◆ 标准操作流程

  1. 启动程序
  2. 点击「选择文件并开始」按钮
  3. 选择要处理的文件（支持多选）
     - 产地证文件（Form E / CO）
     - 商业发票（INVOICE）
     - 装箱单（PACKING LIST）
     - 销售合同（SALES CONTRACT）
  4. 选择导入模式（AI导入 / 常规导入）
  5. 等待处理完成
  6. 数据自动填入 Excel 模板并保存
  7. 在「生成文件管理」列表中查看历史记录

  ◆ 界面布局

  ┌────────────────────────────────────────────────────┐
  │  选择文件  [选择文件并开始]  [云存储导入]  负责人   │  ← 工具栏
  ├──────────────────────────────┬─────────────────────┤
  │  运行日志                    │  生成文件管理        │
  │  ✓ 已选择 2 个文件          │  ┌───────────────┐  │
  │  ✓ 提取到 13 条商品        │  │发票号│商品数│…│  │
  │  ✓ 已保存到: ...           │  │BG2306│ 13  │  │  │
  │                            │  └───────────────┘  │
  │                            │  商品明细列表        │
  │                            │  ┌───────────────┐  │
  │                            │  │HS│品名│数量│… │  │
  │                            │  │850110│Motor│25│  │
  │                            │  └───────────────┘  │
  └──────────────────────────────┴─────────────────────┘

  ◆ 右击文件管理列表 → 打开文件（打开生成的 Excel）

  ◆ 双击文件管理列表：
    - 左半边（发票号~备注）→ 显示商品明细
    - 右半边（源文件~提成）→ 打开 Excel 文件

================================================================================
第4章  AI 导入模式
================================================================================

  ◆ 适用场景

  - 文件格式不规范，常规导入无法识别
  - 需要英译中翻译
  - 首次遇到的新格式（让 AI 学习）

  ◆ 流程

  1. 选择文件 → 点击「选择文件并开始」
  2. 选择「AI导入」模式
  3. 程序自动尝试常规解析（CO / 结构化Excel）
  4. 无法解析的部分调用 AI（DeepSeek）提取
  5. AI 提取 + 常规解析结果合并
  6. 数据清洗、单位转换、英译中
  7. 填入 Excel 模板并保存

  ◆ 内置 AI 账号

  - 系统内置 DeepSeek API 账号，限 50 次调用
  - 剩余 30 次时每次操作提示剩余次数
  - 用完后在「帐号设置」中输入自己的 API Key

  ◆ AI 模型

  默认使用 DeepSeek 模型，可在 ai_settings.json 中配置。

================================================================================
第5章  常规导入模式
================================================================================

  ◆ 适用场景

  - 格式规范的 Excel 文件（有标准列头）
  - Form E 原产地证书（.docx 表格型）
  - 不需要 AI 翻译

  ◆ 支持的解析方式

  ■ Form E 直解（parse_co_document）
    自动识别 .docx 格式的 Form E 原产地证书
    支持：表格型 Form E（含 Exporter/Consignee 等表头）

  ■ 结构化 Excel 导入（import_structured_excel）
    自动检测含 QTY+PRICE 列的工作表作为主表
    支持多工作表联合：INV（主表）+ PKL（毛重/净重）+ CO（HS编码）
    列头关键词自动匹配，支持中/英/越文

  ■ 格式配置解析（V5.0 新增）
    使用之前 AI 学到的格式配置直接解析，无需 AI

================================================================================
第6章  格式学习（新功能）
================================================================================

  ◆ 什么是格式学习？

  当 AI 成功导入一个格式后，系统会自动分析该文件的结构特征
  （工作表名、列头、列顺序），保存为「格式配置」。
  下次遇到相同格式的文件 → 直接用配置解析 → 无需调用 AI。

  ◆ 工作流程

  第1次 → 格式A.xlsx
    ├─ 常规解析 → 失败
    ├─ AI 提取 → 成功
    └─ 学习格式 → 保存配置

  第2次 → 相同格式A.xlsx
    ├─ 常规解析 → 失败
    ├─ ★ 格式匹配命中! 100% → 按配置解析 → 成功（免AI）
    └─ 跳过 AI

  ◆ 管理格式

  菜单「工具 → 恢复原始提取参数」
  - 清除所有已学习的格式配置
  - 恢复到原始状态
  - 配置保存在 codata/format_profiles/ 目录

================================================================================
第7章  文件管理
================================================================================

  ◆ 生成文件管理列表

  每次成功生成 Excel 后，记录自动出现在列表中：

  列名        说明
  ─────────────────────────────────────────
  发票号      文件对应的发票号码
  出口商      出口商/卖方名称
  进口商      进口商/买方名称
  商品项数    商品明细数量
  负责人      当前处理人（可切换）
  备注        自定义备注
  源文件      生成的 Excel 文件路径
  生成日期    文件生成时间
  文件地址    完整文件路径
  提成        提成金额

  ◆ 操作

  右键行 → 打开文件（打开生成的 Excel）
  双击行 → 左半边显示明细，右半边打开文件
  工具栏 → 填写负责人/备注/提成

  ◆ 右键菜单

  在文件管理列表任意位置右键 → 弹出菜单 → 打开文件

================================================================================
第8章  提取记录云同步
================================================================================

  ◆ 功能

  每次生成的 Excel 记录自动同步到微信小程序云数据库

  同步字段：
  - output_file    生成的Excel文件名
  - invoice_no     发票号
  - item_count     商品项数
  - exporter       出口商/卖方
  - consignee      买方/收货人
  - responsible    负责人
  - generate_date  生成日期
  - amount         提取金额（汇总FOB）

  ◆ 查看方式

  微信小程序 → 我的 → 产地证管理 → 产地证提取记录
  （仅 level 1 系统管理员可见）

  ◆ 数据导出

  在小程序提取记录页点击「导出」按钮 → 生成 CSV → 复制下载链接

  ◆ 配置（无需手动设置）

  自动使用 vinhua 项目的云环境：
  AppID: wx4766e6a19fcf456c
  环境: cloud1-2gb1y24raf20f3e0

================================================================================
第9章  云存储导入
================================================================================

  ◆ 功能

  从微信小程序云存储下载客户上传的文件，处理后将结果上传回云。

  ◆ 操作

  1. 点击「☁️ 云存储导入」按钮
  2. 选择要处理的记录
  3. 自动下载文件到临时目录
  4. 调用流水线处理
  5. 结果上传回云存储

  ◆ 前置条件

  - 微信小程序已部署云函数
  - getCoFilesForImport（查询待处理记录）
  - uploadFileProxy（上传文件到云存储）
  - updateCoRecord（更新记录状态）

================================================================================
第10章  系统设置与注册
================================================================================

  ◆ 菜单

  ■ 负责人切换
    菜单「负责人: XXX」切换当前处理人

  ■ 帐号设置
    菜单「帮助 → 帐号设置」
    配置自己的 DeepSeek API Key 和百度翻译账号

  ■ 软件注册
    菜单「帮助 → 软件注册」
    试用期 180 天，过期需注册

  ◆ 试用与注册

  - 新安装后有 180 天免费试用期
  - 试用期内全部功能正常使用
  - 系统内置 AI 账号可用 50 次
  - 注册联系：冯兰雄 13877107717

  ◆ 使用说明书

  菜单「帮助 → 使用说明书」打开本文档

================================================================================
第11章  常见问题
================================================================================

  Q: AI 提取不准确怎么办？
  A: 1. 确保文件清晰，表格列头命名规范
     2. 尝试先更新到格式能常规导入后再用AI
     3. 给 AI 提供更多上下文（多选几个关联文件）

  Q: 格式学习学到的配置在哪里？
  A: 保存在 codata/format_profiles/ 目录中，可删除恢复原始状态

  Q: 恢复原始提取参数会怎样？
  A: 清除所有 AI 学到的格式配置，回到原始状态。
     下次同格式文件会重新用 AI 学习。

  Q: 支持 .xls 文件吗？
  A: 支持！V5.0 已加入 .xls 旧格式兼容。

  Q: 提取记录同步到云失败？
  A: 1. 检查 saveCoExtractionLog 云函数是否已部署
     2. 检查网络连接
     3. 查看运行日志中的错误信息

  Q: 内置 AI 次数用完了？
  A: 在「帐号设置」中输入自己的 DeepSeek API Key

  Q: 文件管理列表为空？
  A: 需要先选择文件并成功生成 Excel 才会有记录

  Q: 双击源文件打不开 Excel？
  A: 检查文件是否存在，或右键使用「打开文件」

================================================================================
第12章  支持的文件格式
================================================================================

  导入格式：

  格式        扩展名              说明
  ─────────────────────────────────────────────────────────
  Excel       .xlsx / .xlsm       标准 Excel 格式（推荐）
  旧版 Excel  .xls                V5.0 新增兼容
  Word        .docx               表格型 Form E 证书
  旧版 Word   .doc                通过 win32com/olefile 读取
  PDF         .pdf                文本型 PDF

  导出格式：

  格式        扩展名              说明
  ─────────────────────────────────────────────────────────
  Excel       .xlsm               带宏的 Excel 模板

================================================================================
附录 A：快捷键
================================================================================

  操作                  说明
  ─────────────────────────────────────────
  Ctrl+S                保存当前编辑
  Delete                删除选中商品
  双击商品              编辑商品详情
  双击记录              显示明细/打开文件
  右键                  弹出菜单

================================================================================
附录 B：Excel 列头命名建议
================================================================================

  为确保 AI 导入准确率，建议列头使用以下命名：

  内容          推荐列头名称
  ────────────────────────────────────────────────
  序号          NO / 序号 / No.
  商品名称      DESCRIPTION / 品名 / COMMODITY
  HS 编码       HS / H.S.CODE / HS CODE / 海关编码
  数量          QUANTITY / QTY / 数量
  单价          UNIT PRICE / UNIT PRICE(USD) / 单价
  金额          AMOUNT / AMOUNT(USD) / 金额
  件数          件数 / CARTON / CTNS
  件数单位      件数单位 / PACKING / 包装
  单位          UNIT / UOM / 单位
  原产地        ORIGIN / 产地
  毛重          GROSS WEIGHT / KGM / 毛重
  净重          NET WEIGHT / N.W / 净重

  提示：COMMODITY / PRODUCT NAME 也支持（V5.0 新增）

================================================================================

  版本：V5.0
  更新日期：2026-07-08
  技术支持：冯兰雄  13877107717
