rtu_v5/.planning/phases/02-data-persistence-file-management/02-01-PLAN.md

---
phase: 02-data-persistence-file-management
plan: "01"
type: execute
wave: 1
depends_on: []
files_modified:
  - src/app.py
  - src/templates/files.html
autonomous: true
requirements:
  - FILE-01
  - FILE-02
  - FILE-04
  - BACK-04

must_haves:
  truths:
    - "User can view list of CSV files stored in flash memory"
    - "User can view contents of selected CSV files"
    - "User can delete unwanted CSV files from flash memory"
  artifacts:
    - path: "src/app.py"
      provides: "File management API endpoints"
      exports: ["GET /api/files", "GET /api/files/<filename>", "DELETE /api/files/<filename>"]
    - path: "src/templates/files.html"
      provides: "File management UI page"
      routes: ["/files"]
  key_links:
    - from: "src/templates/files.html"
      to: "/api/files"
      via: "fetch in useEffect"
      pattern: "fetch.*api/files"
---

<objective>
Create file management API endpoints and basic UI for listing/viewing/deleting CSV files.
</objective>

<context>
@./.planning/phases/02-data-persistence-file-management/02-CONTEXT.md
@./.planning/phases/02-data-persistence-file-management/02-RESEARCH.md
@./.planning/ROADMAP.md
@./.planning/REQUIREMENTS.md
@./src/app.py
</context>

<tasks>

<task type="auto">
  <name>task 1: Add file management API endpoints to Flask backend</name>
  <files>src/app.py</files>
  <action>
Add the following API endpoints to src/app.py:

1. GET /api/files - List all CSV files in the logger directory
   - Returns JSON: {files: [{name, size, created}], total: count}
   - Storage path: /myvscada/logger (configurable, default to src/data/logger)
   - Handle missing directory gracefully

2. GET /api/files/&lt;filename&gt; - Get file contents
   - Returns JSON: {name, content: "full file text", lines: count}
   - Limit preview to first 100 lines for large files

3. DELETE /api/files/&lt;filename&gt; - Delete a file
   - Returns JSON: {success: true/false}
   - Confirm file exists before delete
   - Handle errors gracefully

Use the existing Flask patterns from src/app.py:
- Use jsonify for responses
- Use request.get_json() for POST data
- Add error handling with try/except
- Follow existing route structure
  </action>
  <verify>
<automated>curl -s http://localhost:8080/api/files | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if 'files' in d else 'FAIL')"</automated>
  </verify>
  <done>API endpoints return valid JSON, file list shows files, delete removes files</done>
</task>

<task type="auto">
  <name>task 2: Create files.html template</name>
  <files>src/templates/files.html</files>
  <action>
Create src/templates/files.html with:

1. Main navigation menu (reuse from other templates)
2. Page title: "Flash Memory Files"
3. File list display:
   - Table or card layout showing: filename, size, date
   - "View" button for each file (opens modal)
   - "Delete" button with confirmation
4. Modal for viewing file contents:
   - File name header
   - Scrollable content area (pre/code block)
   - Close button
5. JavaScript:
   - Fetch file list on page load
   - Handle view button click -> fetch file content
   - Handle delete button click -> confirm -> delete -> refresh list
   - Use Bootstrap 5.3 + Bootstrap Icons (like existing templates)
   - Touch-optimized 48px+ buttons

Base on the existing templates (settings.html, calibration.html) for:
- Bootstrap 5.3 structure
- Navigation menu
- CSS variables and touch targets
- Socket.IO integration (optional)
  </action>
  <verify>
<automated>curl -s http://localhost:8080/files | grep -q "Flash Memory" && echo "OK" || echo "FAIL"</automated>
  </verify>
  <done>Files page loads, shows file list, view modal works, delete works</done>
</task>

<task type="auto">
  <name>task 3: Add /files route to Flask app</name>
  <files>src/app.py</files>
  <action>
Add the route for the files page in src/app.py:

```python
@app.route('/files')
def files():
    """File management page"""
    return render_template('files.html',
                           page='files',
                           version=SOFTWARE_VERSION,
                           build_date=BUILD_DATE)
```

Add this route near the other page routes (index, settings, calibration).
  </action>
  <verify>
<automated>curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/files</automated>
  </verify>
  <done>Route returns 200 OK</done>
</task>

<task type="auto">
  <name>task 4: Add Files menu item to navigation</name>
  <files>src/templates/dashboard.html, src/templates/settings.html, src/templates/calibration.html</files>
  <action>
Add "Files" navigation button to main menu in:
- dashboard.html
- settings.html  
- calibration.html

The navigation should link to /files route. Follow the existing nav structure with nav-btn class.

Example (add after calibration button):
```html
<a href="/files" class="nav-btn btn btn-outline-primary">
    <i class="bi bi-folder"></i> Files
</a>
```
  </action>
  <verify>
<automated>grep -l "Files" src/templates/*.html | wc -l</automated>
  </verify>
  <done>All pages have Files link in navigation</done>
</task>

</tasks>

<verification>
- API endpoints return valid JSON
- Files page loads with file list
- View modal shows file contents
- Delete removes files from storage
- Navigation works across all pages
</verification>

<success_criteria>
User can view list of CSV files, view file contents, and delete files from flash memory via web UI
</success_criteria>

<output>
After completion, create `.planning/phases/02-data-persistence-file-management/02-01-SUMMARY.md`
</output>