docs: Critical gaps in behaviors.md documentation and test coverage

[evan-zhang11]

Daily Documentation Review (2026-02-19)

This issue documents findings from the daily documentation review of docs/dev/behaviors.md.

🔴 Critical Issues

1. Missing API-011: Custom CRS Update Endpoint

Problem: The custom CRS support feature was added in PR #57 but is not documented in behaviors.md.

Implementation exists:

• Endpoint: PUT /api/files/:id/crs
• Handler: update_crs in backend/src/handlers.rs
• Request body: {"crs": string | null}
• Response: {"id", "crs", "crsType"}
• Status codes: 200, 400, 401, 404, 409
• Requirement: File must be in ready status

Impact: Users cannot discover this feature through documentation.

Recommendation: Add API-011 entry to behaviors.md:

| API-011 | 更新CRS | PUT /api/files/:id/crs 需要认证，仅 ready 状态可更新。请求体：{"crs": string|null}，响应：{"id", "crs", "crsType"} | 200 + JSON / 400（crs 缺失） / 401 / 404 / 409（非 ready） | `cargo test test_update_crs_*` | Integration | P1 |

---

2. Missing Tests for Custom CRS Feature

Problem: The custom CRS feature has test data but no automated tests.

Evidence:

• Test data exists: testdata/custom-crs/ (4 GeoJSON files with documentation)
• No test files reference custom CRS: grep -r "custom-crs" backend/tests/ frontend/tests/ returns nothing
• No integration tests for API-011

Impact:

• Feature correctness is not verified
• Regression risks are high
• CRS normalization logic is untested

Recommendation: Add integration tests:

#[tokio::test]
async fn test_update_crs_with_custom_projection() { ... }

#[tokio::test]  
async fn test_update_crs_requires_ready_status() { ... }

#[tokio::test]
async fn test_custom_crs_file_upload_sets_crs_type() { ... }

---

⚠️ High Priority Issues

3. Non-existent Test Commands Referenced in Documentation

Problem: Documentation references test commands that don't exist in the repository.

Behavior ID	Documented Command	Status
STORE-001	cargo test test_storage_*	❌ No matching tests found
STORE-002	pytest test_db_schema	❌ No Python tests in repo
STORE-003	pytest test_state_machine	❌ No Python tests in repo

Impact:

• P0 behaviors claim test coverage that doesn't exist
• CI cannot verify storage behavior contracts
• Documentation misleads contributors

Recommendation:

1. Either implement the missing tests (Rust, not Python)
2. Or update documentation to reflect actual test coverage
3. Consider if these are P0 if they have no tests

---

ℹ️ Minor Issues

4. Priority Classification Inconsistency

Observation: API-014 (health check) is marked as P2 but has test coverage (test_health_check exists).

Question: Should health check be P2 if it's tested? Or should untested P0s (STORE-*) be demoted?

---

📊 Test Coverage Summary

Category	Documented	Implemented	Gap
API behaviors	14	~13	API-011 missing docs
Auth behaviors	4	✅ E2E tests exist	OK
Storage behaviors	3	0	❌ Critical gap
UI behaviors	10	✅ E2E tests exist	OK
Custom CRS	1 (impl)	0	❌ No tests

---

🎯 Recommended Actions

Priority 1 (Critical):

1. Document API-011 (custom CRS endpoint)
2. Add integration tests for custom CRS feature

Priority 2 (High):
3. Resolve STORE-001/002/003 test gaps:

• Either implement tests OR
• Remove from behaviors.md OR
• Mark as "manual verification required"

Priority 3 (Medium):
4. Review all P0 behaviors without tests
5. Standardize test naming conventions

---

📝 Additional Context

Recent Changes:

• Custom CRS feature: PR feat(backend): add custom CRS support for non-EPSG coordinate systems #57 (merged 2026-02-18)
• PMTiles support: Well documented and tested ✅
• UUID upload IDs: Documented ✅

Test Data Available:

• testdata/custom-crs/ has 4 test files ready for use
• Documentation in testdata/custom-crs/README.md is excellent

---

Next Review: 2026-02-20 05:00 Asia/Shanghai