Added some more documentation to ETL scripts

stm_etl/FTP/wf_assignments.py

@@ -1,14 +1,72 @@
 '''
+Wells Fargo Invoice Assignment Generator
+
 Created on Jan 7, 2016
-
-Generate assignment of invoices to be sent to Wells Fargo in csv format.
-This is mainly called from the send_wf.py cgi script running on the Apache instance on our test server.
-
-'WF' in comments = Wells Fargo
-
-@todo: Properly truncate invoice amount value to fit WF's decimal(12,2) field size. TOTAL and DETAIL records!
-
 @author: Wes
+
+PURPOSE:
+    Generates CSV assignment files containing invoice and credit memo data for
+    transmission to Wells Fargo (WF) via SFTP. WF acts as the factoring company —
+    invoices are "assigned" to them so they can collect payment from customers on
+    our behalf.
+
+    Primarily invoked from the send_wf.py CGI script on the test server's Apache
+    instance, but can also be run standalone from the command line.
+
+USAGE:
+    python wf_assignments.py <yyyymmdd>       # non-interactive, generates + sends
+    python wf_assignments.py                  # interactive, prompts for date and confirmation
+
+KEY CONCEPTS:
+    - Trade Style: A Wells Fargo grouping code. Valid styles are 00, 03, 05, 09,
+      mapped to Jomar factor account numbers (888888, 88888803, 88888805, 88888809).
+      Each trade style gets its own assignment file.
+    - Assignment: A single CSV file containing all invoices OR all credits for one
+      trade style on a given date. Invoices have positive dollar amounts; credits
+      have negative dollar amounts.
+    - Backout: An invoice that was created and reversed on the same day. Both the
+      original and the reversing invoice are excluded from transmission.
+    - Client Code: Our identifier with WF (4143, changed from 5867 on 10/02/2017).
+
+PROCESSING LOGIC:
+    1. Load terms codes from Jomar (TXMYTX00) into a lookup dictionary.
+
+    2. Query Invoice_Backouts table for the target date. If an invoice was created
+       and backed out on the same day, both the original and backout invoice numbers
+       are excluded from all subsequent queries.
+
+    3. For each valid trade style, generate two assignments:
+        a. Invoices (RWTF > 0)
+        b. Credits  (RWTF < 0)
+
+    4. Each assignment CSV contains:
+        - TRL (trailer/summary) row: client code, trade style, assignment number,
+          date, invoice count, type (I/C), and total dollar amount.
+        - DTL (detail) rows, one per invoice: invoice number, date, amount, terms,
+          bill-to customer info (name, address, city, state, country, zip, phone),
+          and customer PO number.
+
+       Customer data is looked up from the Customer Master table (TXUYKD00).
+       Field lengths are truncated to WF's maximum widths (e.g. name max 40 chars).
+       Phone numbers must be exactly 10 digits or are omitted.
+
+    5. If sendNow=True:
+        - CSV files are uploaded via SFTP to sftp.spscommerce.net (port 10022).
+          TEST_MODE uploads to /testin/ instead of /in/.
+        - Transmitted invoices are flagged as processed in Jomar (RFIL = 'X').
+        - AS400_Invoice_Interface.py is called as a subprocess to sync the
+          same invoices to the AS400.
+
+    6. If email=True, the generated CSVs and log output are emailed to AR.
+
+OUTPUT:
+    - CSV files in D:\FTP\SEND_WF\ named {clientCode}{tradeStyle}_INV_{date}_{seq}.csv
+    - Log file at D:\FTP\logs\wf_assignment_build.log
+    - Email alert with CSVs attached (optional)
+
+NOTE:
+    The sendFiles() function is currently stubbed out (returns immediately).
+    SFTP upload logic is preserved in comments within the function body.
 '''
 import paramiko, csv, sys, logging, re, time, os, smtplib, sqlite3, StringIO, subprocess
 from datetime import datetime