disclosure backend static

การเปิดเผยแบ็กเอนด์แบบคงที่

repo disclosure-backend-static คือแบ็กเอนด์ที่ขับเคลื่อน Open Disclosure California

มันถูกสร้างขึ้นอย่างเร่งรีบจนถึงการเลือกตั้งปี 2559 และได้รับการออกแบบตามปรัชญา "ลงมือทำ" ในเวลานั้น เราได้ออกแบบ API และสร้างส่วนหน้า (ส่วนใหญ่) แล้ว repo นี้ถูกสร้างขึ้นเพื่อดำเนินการเหล่านั้นโดยเร็วที่สุด

โปรเจ็กต์นี้ใช้ไปป์ไลน์ ETL พื้นฐานเพื่อดาวน์โหลดข้อมูล Netfile ของ Oakland ดาวน์โหลดข้อมูลที่ดูแลจัดการโดยมนุษย์ในรูปแบบ CSV สำหรับ Oakland และรวมทั้งสองเข้าด้วยกัน เอาต์พุตคือไดเร็กทอรีของไฟล์ JSON ซึ่งเลียนแบบโครงสร้าง API ที่มีอยู่ ดังนั้นจึงไม่จำเป็นต้องเปลี่ยนแปลงโค้ดไคลเอ็นต์

ข้อกำหนดเบื้องต้น

• Ruby 3.3.4 (ดูเวอร์ชันใน .ruby-version )

การติดตั้ง

หมายเหตุ: คุณไม่จำเป็นต้องเรียกใช้คำสั่งเหล่านี้เพื่อพัฒนาบนส่วนหน้า สิ่งที่คุณต้องทำคือโคลนพื้นที่เก็บข้อมูลที่อยู่ติดกับ repo ส่วนหน้า

หากคุณวางแผนที่จะแก้ไขโค้ดแบ็กเอนด์ ให้ทำตามขั้นตอนเหล่านี้เพื่อตั้งค่าการพึ่งพาการพัฒนาที่จำเป็นทั้งหมด รวมถึงฐานข้อมูล PostgreSQL และ Python 3 ใหม่:

1. ตรวจสอบให้แน่ใจว่า Homebrew เป็นเวอร์ชันล่าสุดโดยเรียกใช้:

    brew update && brew upgrade
   

2. ติดตั้ง PostgreSQL เวอร์ชัน 16 ด้วย Homebrew:

    brew install postgresql@16
   

   • หากต้องการเริ่มฐานข้อมูลโดยอัตโนมัติเมื่อเข้าสู่ระบบ ให้ใช้:

      brew services start postgresql@16
     

3. ตรวจสอบว่าติดตั้ง Python 3 บนระบบของคุณแล้ว ถ้าไม่เช่นนั้น ให้ดาวน์โหลดจาก python.org
   • macOS รัน Python 2 โดยกำเนิด ดังนั้นให้ใช้ python3 -m pip แทน pip เพื่อให้แน่ใจว่ามีการใช้ Python 3:

      python3 -m pip install ...
     

   • หรือหาก pip ของระบบของคุณชี้ไปที่ Python 3 คุณสามารถใช้ pip ได้โดยตรง:

      pip install ...
     

4. วิ่ง

    sudo -H python -m pip install -r requirements.txt
   gem install pg bundler
   bundle install
   

โค๊ดสเปซ

พื้นที่เก็บข้อมูลนี้ได้รับการตั้งค่าให้ทำงานในคอนเทนเนอร์ภายใต้ Codespaces กล่าวอีกนัยหนึ่ง คุณสามารถเริ่มต้นสภาพแวดล้อมที่ตั้งค่าไว้แล้วโดยไม่ต้องทำตามขั้นตอนการติดตั้งใดๆ ที่จำเป็นในการตั้งค่าสภาพแวดล้อมภายในเครื่อง ซึ่งสามารถใช้เป็นวิธีการแก้ไขปัญหาโค้ดก่อนที่จะส่งไปยังไปป์ไลน์การผลิต ข้อมูลต่อไปนี้อาจเป็นประโยชน์ในการเริ่มต้นใช้งาน Codespaces:

1. ไปที่หน้าที่แสดงรหัสที่เก็บ: https://github.com/caciviclab/disclosure-backend-static
2. เปลี่ยนสาขาเป็นสาขาที่คุณสนใจดำเนินการและแก้ไข
3. คลิกที่ปุ่ม Code แล้วคลิกแท็บ Codespaces ในเมนูแบบเลื่อนลง
4. คลิกที่ปุ่มเพื่อเริ่มโค้ดสเปซใหม่
5. รอให้ตั้งค่าคอนเทนเนอร์และเทอร์มินัลพร้อมท์ที่ /workspace จะถูกนำเสนอในหน้าเว็บ ซึ่งจะดูคุ้นเคยหากคุณเคยทำงานกับ VS Code มาก่อน
6. ในเทอร์มินัล คุณสามารถเริ่มรันคำสั่งได้จากส่วนถัดไป เช่น make download
7. จะมีฐานข้อมูล Postgres ที่ทำงานอยู่เริ่มต้นบน localhost และคุณสามารถพิมพ์ psql ในเทอร์มินัลเพื่อเชื่อมต่อกับเซิร์ฟเวอร์
8. คำสั่ง make import จะเติมฐานข้อมูล Postgres
9. คลิกที่ไอคอนรูปทรงกระบอกทางด้านซ้ายเพื่อเข้าถึงส่วนขยายเครื่องมือ SQL ซึ่งจะช่วยให้คุณสามารถเชื่อมต่อกับ Postgres และดูสคีมาของมันรวมทั้งสืบค้นข้อมูลที่คุณนำเข้า
10. คอนเทนเนอร์มี Python 3.9 และ Ruby เวอร์ชันปัจจุบันติดตั้งอยู่ พร้อมด้วยแพ็คเกจที่จำเป็นทั้งหมด
11. เราจะพยายามรับคอนเทนเนอร์ให้ตรงกับสภาพแวดล้อมสำหรับ Travis CI รวมถึงการพยายามติดตั้ง Ruby เวอร์ชันเดียวกันด้วย
12. การตั้งค่าเดียวกันนี้ทำให้ทุกคนสามารถเรียกใช้คอนเทนเนอร์เดียวกันบนเครื่องของตนใน VS Code โดยใช้ส่วนขยาย Dev Containers แต่เรามุ่งเน้นไปที่การเปิดใช้งาน Codespaces เป็นหลักในขณะนี้ และตรวจสอบให้แน่ใจว่าเราสามารถเสริมความแข็งแกร่งให้กับการตั้งค่าสำหรับ Codespaces ได้ก่อน (เราจะเพิ่มคำแนะนำสำหรับ Dev Containers เมื่อสิ่งนี้สมบูรณ์แล้ว)
13. หากคุณทำการเปลี่ยนแปลงในสภาพแวดล้อม Codespaces อย่าลืมผลักดันมันหลังจากยืนยันด้วย Git มันก็เหมือนกับเครื่องอื่น ดังนั้นมันจะไม่ไปจบลงที่ GitHub repository ถ้าไม่ทำการ git push

นักเทียบท่า

พื้นที่เก็บข้อมูลนี้ได้รับการกำหนดค่าให้ทำงานภายในคอนเทนเนอร์ Docker ด้วย สิ่งนี้คล้ายกับ Codespaces ยกเว้นว่าคุณสามารถใช้ IDE และการตั้งค่าในเครื่องใดก็ได้ที่คุณต้องการ ต่อไปนี้เป็นวิธีเริ่มต้นใช้งาน Docker กับ VSCode:

1. ดาวน์โหลด Docker และเปิด Docker Desktop
   • เวอร์ชัน 4.32.0 (157355) ได้รับการตรวจสอบแล้วว่าทำงานกับที่เก็บนี้ได้
2. ติดตั้งส่วนขยาย VSCode Dev Containers
   • เวอร์ชัน v0.375.1 ได้รับการยืนยันว่าเข้ากันได้กับพื้นที่เก็บข้อมูลนี้
   • หมายเหตุ: VSCode อาจแนะนำให้ติดตั้งส่วนขยาย Docker เช่นกัน แต่คุณต้องใช้ส่วนขยาย Dev Containers เท่านั้นสำหรับการตั้งค่านี้
3. ใน VSCode ให้ไปที่ .devcontainer/Dockerfile หรือรีสตาร์ท VSCode ส่วนขยาย Dev Containers ควรแจ้งให้คุณเปิดพื้นที่เก็บข้อมูลในคอนเทนเนอร์อีกครั้ง ดำเนินการต่อด้วยตัวเลือกนี้
4. เมื่อโหลดสภาพแวดล้อมคอนเทนเนอร์แล้ว ให้ตั้งค่าให้เสร็จสิ้นโดยทำตามคำสั่งด้านล่าง

วิ่ง

ดาวน์โหลดไฟล์ข้อมูลดิบ คุณจะต้องดำเนินการนี้เป็นครั้งคราวเพื่อรับข้อมูลล่าสุด

 $ make download

นำเข้าข้อมูลเข้าสู่ฐานข้อมูลเพื่อการประมวลผลที่ง่ายขึ้น คุณจะต้องเรียกใช้สิ่งนี้หลังจากที่คุณดาวน์โหลดข้อมูลใหม่แล้วเท่านั้น

 $ make import

เรียกใช้เครื่องคิดเลข ทุกอย่างจะถูกส่งออกไปยังโฟลเดอร์ "build"

 $ make process

ทางเลือก จัดทำดัชนีเอาต์พุตบิลด์ใหม่ลงใน Algolia (การจัดทำดัชนีใหม่ต้องใช้ตัวแปรสภาพแวดล้อม ALGOLIASEARCH_APPLICATION_ID และ ALGOLIASEARCH_API_KEY)

 $ make reindex

หากคุณต้องการให้บริการไฟล์ JSON แบบคงที่ผ่านเว็บเซิร์ฟเวอร์ในเครื่อง ให้ทำดังนี้

 $ make run

กำลังพัฒนา

การดูแลรักษาสคีมาฐานข้อมูล

เมื่อรัน make import ตาราง postgres จำนวนหนึ่งจะถูกสร้างขึ้นเพื่อนำเข้าข้อมูลที่ดาวน์โหลด สคีมาของตารางเหล่านี้ถูกกำหนดไว้อย่างชัดเจนในไดเร็กทอรี dbschema และอาจต้องได้รับการอัปเดตในอนาคตเพื่อรองรับข้อมูลในอนาคต คอลัมน์ที่เก็บข้อมูลสตริงอาจมีขนาดไม่ใหญ่พอสำหรับข้อมูลในอนาคต ตัวอย่างเช่น หากคอลัมน์ชื่อยอมรับชื่อที่มีความยาวไม่เกิน 20 อักขระ และในอนาคต เรามีข้อมูลที่ชื่อมีความยาว 21 อักขระ การนำเข้าข้อมูลจะล้มเหลว เมื่อสิ่งนี้เกิดขึ้น เราจะต้องอัปเดตไฟล์สคีมาที่เกี่ยวข้องใน dbschema เพื่อรองรับอักขระเพิ่มเติม เพียงทำการเปลี่ยนแปลงและเรียกใช้ make import อีกครั้งเพื่อตรวจสอบว่าสำเร็จหรือไม่

ตรวจสอบการเปลี่ยนแปลงข้อมูลเอาท์พุต

พื้นที่เก็บข้อมูลนี้ใช้เพื่อสร้างไฟล์ข้อมูลที่เว็บไซต์ใช้ หลังจากรัน make process แล้ว ไดเร็กทอรี build จะถูกสร้างขึ้นโดยมีไฟล์ข้อมูล ไดเร็กทอรีนี้ถูกเช็คอินในพื้นที่เก็บข้อมูล และเช็คเอาท์ในภายหลังเมื่อสร้างเว็บไซต์ หลังจากทำการเปลี่ยนแปลงโค้ด สิ่งสำคัญคือต้องเปรียบเทียบไดเร็กทอรี build ที่สร้างขึ้นกับไดเร็กทอรี build ที่สร้างขึ้นก่อนการเปลี่ยนแปลงโค้ด และตรวจสอบว่าการเปลี่ยนแปลงจากการเปลี่ยนแปลงโค้ดเป็นไปตามที่คาดไว้

เนื่องจากการเปรียบเทียบเนื้อหาทั้งหมดของไดเร็กทอรี build อย่างเข้มงวดจะรวมการเปลี่ยนแปลงที่เกิดขึ้นโดยไม่ขึ้นกับการเปลี่ยนแปลงโค้ดใดๆ เสมอ นักพัฒนาทุกคนจึงต้องทราบเกี่ยวกับการเปลี่ยนแปลงที่คาดหวังเหล่านี้เพื่อดำเนินการตรวจสอบนี้ หากต้องการลบความจำเป็นนี้ ไฟล์เฉพาะ bin/create-digests.py จะสร้างไดเจสต์สำหรับข้อมูล JSON ในไดเร็กทอรี build หลังจากยกเว้นการเปลี่ยนแปลงที่คาดไว้เหล่านี้ หากต้องการค้นหาการเปลี่ยนแปลงที่ไม่รวมการเปลี่ยนแปลงที่คาดหวังเหล่านี้ เพียงมองหาการเปลี่ยนแปลงในไฟล์ build/digests.json

ในปัจจุบัน การเปลี่ยนแปลงที่คาดหวังเหล่านี้เกิดขึ้นโดยไม่ขึ้นกับการเปลี่ยนแปลงรหัสใดๆ:

• การประทับเวลาเปลี่ยนแปลงสำหรับการวิ่งแต่ละครั้ง
• รายชื่อผู้สนับสนุนอันดับต้นๆ มีการเรียงลำดับที่ไม่ได้กำหนดไว้ของผู้สนับสนุนที่มีการสนับสนุนเหมือนกัน
• รายการผู้ใช้จ่ายสูงสุดมีการเรียงลำดับผู้ใช้จ่ายที่ไม่ได้กำหนดซึ่งมีการใช้จ่ายเท่ากัน
• การปัดเศษความแตกต่างสำหรับการลอยตัว

การเปลี่ยนแปลงที่คาดไว้จะถูกแยกออกก่อนที่จะสร้างไดเจสต์สำหรับข้อมูลในไดเร็กทอรี build ตรรกะสำหรับสิ่งนี้สามารถพบได้ในฟังก์ชัน clean_data ที่พบในไฟล์ bin/create-digests.py หลังจากที่โค้ดได้รับการแก้ไขจนไม่มีการเปลี่ยนแปลงที่คาดหวังอีกต่อไปแล้ว การแยกการเปลี่ยนแปลงนั้นสามารถลบออกจาก clean_data ได้ ตัวอย่างเช่น การปัดเศษของการลอยไม่เหมือนกันในแต่ละครั้งที่รัน make process เนื่องจากความแตกต่างในสภาพแวดล้อม เมื่อโค้ดได้รับการแก้ไขเพื่อให้การปัดเศษของ float เท่ากันตราบใดที่ข้อมูลไม่มีการเปลี่ยนแปลง การเรียก round_float ใน clean_data ก็สามารถลบออกได้

มีการสร้างสคริปต์เพิ่มเติมเพื่อสร้างรายงานที่ช่วยให้สามารถเปรียบเทียบผลรวมของผู้สมัครได้ สคริปต์คือ bin/report-candidates.py และสร้าง build/candidates.csv และ build/candidates.xlsx รายงานประกอบด้วยรายชื่อผู้สมัครทั้งหมดและผลรวมที่คำนวณได้หลายวิธีที่ควรรวมกันเป็นตัวเลขเดียวกัน

เพื่อให้แน่ใจว่าการเปลี่ยนแปลงสคีมาฐานข้อมูลสามารถมองเห็นได้ในคำขอดึง สคีมา postgres ที่สมบูรณ์จะถูกบันทึกลงในไฟล์ schema.sql ในไดเร็กทอรี build ด้วย เนื่องจากไดเร็กทอรี build ถูกสร้างขึ้นใหม่โดยอัตโนมัติสำหรับแต่ละสาขาใน PR และคอมมิตกับพื้นที่เก็บข้อมูล การเปลี่ยนแปลงใดๆ ในสคีมาที่เกิดจากการเปลี่ยนแปลงโค้ดจะแสดงความแตกต่างในไฟล์ schema.sql เมื่อตรวจสอบ PR

การเพิ่มเครื่องคิดเลข

แต่ละตัวชี้วัดเกี่ยวกับผู้สมัครจะได้รับการคำนวณอย่างแยกจากกัน ตัวชี้วัดอาจเป็น "เงินสนับสนุนทั้งหมดที่ได้รับ" หรืออะไรที่ซับซ้อนกว่านั้น เช่น "เปอร์เซ็นต์ของเงินสนับสนุนที่น้อยกว่า 100 ดอลลาร์"

เมื่อเพิ่มการคำนวณใหม่ จุดเริ่มต้นที่ดีคือแบบฟอร์ม 460 อย่างเป็นทางการ คุณกำลังมองหาข้อมูลที่ถูกรายงานในแบบฟอร์มนั้นหรือไม่ หากเป็นเช่นนั้น คุณจะพบข้อมูลดังกล่าวในฐานข้อมูลของคุณหลังจากขั้นตอนการนำเข้า นอกจากนี้ยังมีแบบฟอร์มอื่นๆ อีกสองสามรูปแบบที่เรานำเข้า เช่น แบบฟอร์ม 496 (นี่คือชื่อของไฟล์ในไดเร็กทอรี input ตรวจสอบสิ่งเหล่านั้น)

แต่ละกำหนดการของแต่ละแบบฟอร์มจะถูกนำเข้าไปยังตาราง postgres ที่แยกจากกัน ตัวอย่างเช่น ตาราง A ของแบบฟอร์ม 460 จะถูกนำเข้าไปยังตาราง A-Contributions

เมื่อคุณมีวิธีในการสืบค้นข้อมูลแล้ว คุณควรสร้างแบบสอบถาม SQL ที่คำนวณค่าที่คุณกำลังพยายามรับ เมื่อคุณแสดงการคำนวณเป็น SQL แล้ว ให้ใส่ไว้ในไฟล์เครื่องคิดเลขดังนี้:

1. สร้างไฟล์ใหม่ชื่อ calculators/[your_thing]_calculator.rb
2. นี่คือตัวอย่างบางส่วนสำหรับไฟล์นั้น:

 # the name of this class _must_ match the filename of this file, i.e. end
# with "Calculator" if the file ends with "_calculator.rb"
class YourThingCalculator
  def initialize ( candidates : [ ] , ballot_measures : [ ] , committees : [ ] )
    @candidates = candidates
    @candidates_by_filer_id = @candidates . where ( '"FPPC" IS NOT NULL' )
      . index_by { | candidate | candidate [ 'FPPC' ] }
  end

  def fetch
    @results = ActiveRecord :: Base . connection . execute ( <<-SQL )
      -- your sql query here
    SQL

    @results . each do | row |
      # make sure Filer_ID is returned as a column by your query!
      candidate = @candidates_by_filer_id [ row [ 'Filer_ID' ] . to_i ]

      # change this!
      candidate . save_calculation ( :your_thing , row [ column_with_your_desired_data ] )
    end
  end
end

3. คุณจะต้องกรอกแบบสอบถาม SQL และตรวจสอบให้แน่ใจว่าแบบสอบถามเลือกคอลัมน์ Filer_ID
4. ตรวจสอบให้แน่ใจว่าได้อัปเดตการเรียกเป็น candidate.save_calculation วิธีการนั้นจะทำให้อาร์กิวเมนต์ที่สองเป็นอนุกรมเป็น JSON เพื่อให้สามารถจัดเก็บข้อมูลประเภทใดก็ได้
5. การคำนวณของคุณสามารถดึงข้อมูลได้ด้วย candidate.calculation(:your_thing) คุณจะต้องเพิ่มสิ่งนี้ลงในการตอบกลับ API ในไฟล์ process.rb

การไหลของข้อมูล

นี่คือวิธีที่ข้อมูลไหลผ่านส่วนหลัง ข้อมูลทางการเงินถูกดึงมาจาก Netfile ซึ่งเสริมด้วยรหัสไฟล์ของไฟล์การแมป Google ชีตกับข้อมูลบัตรลงคะแนน เช่น ชื่อผู้สมัคร สำนักงาน มาตรการลงคะแนนเสียง ฯลฯ เมื่อกรอง รวบรวม และแปลงข้อมูลแล้ว ส่วนหน้าจะใช้ข้อมูลดังกล่าวและสร้าง HTML แบบคงที่ ส่วนหน้า

ข้อผิดพลาดทั่วไป

ระหว่างการติดตั้ง Bundle

 error: use of undeclared identifier 'LZMA_OK'

พยายาม:

 brew unlink xz
bundle install
brew link xz

ระหว่าง make download

 wget: command not found

วิ่ง brew install wget

ระหว่าง make import

ดูเหมือนว่ามีปัญหากับระบบ Macintosh ที่ใช้ชิป Apple

 ImportError: You don't appear to have the necessary database backend installed for connection string you're trying to use. Available backends include:

PostgreSQL:	pip install psycopg2

ลองดังต่อไปนี้:

 pip uninstall psycopg2-binary
pip install psycopg2-binary --no-cache-dir