ai-contract-platform/project-docs/V2-phase3-legal-fulltext-versioning-2026-07-02.md

V2 Phase 3 Legal Fulltext Versioning

Date: 2026-07-02

Status

This slice closes the first implementation step for selected legal fulltext versioning.

Completed:

1. Added Alembic migration 20260702_0027_add_legal_fulltext_versions.py.
2. Added ORM model LegalFulltextVersionModel.
3. Added LegalFulltextVersionRepository.
4. Added runtime schema-check coverage for legal_fulltext_versions.
5. Switched /api/v1/legal-articles list/detail to repository-backed reads.
6. Switched legal change impact scan article resolution to repository-backed reads.
7. Kept static SELECTED_LEGAL_ARTICLES as compatibility fallback.
8. Added demo/dev seed of current selected legal articles into legal_fulltext_versions as v1.

Not changed in this slice:

1. No bulk import tool for the full V1 legal corpus yet.
2. No frontend legal-fulltext edit/version management UI yet.
3. No remote smoke deployment for migration 20260702_0027 yet.

Runtime Behavior

Legal article read order is now:

1. Read the latest non-deleted article version from legal_fulltext_versions.
2. If no version rows exist for the environment, fall back to the existing static selected legal articles.

Legal change impact scanning now resolves article_id and source_id through the repository first, so scans can target DB-only legal articles that do not exist in the static fixture.

The existing API contract remains unchanged:

• GET /api/v1/legal-articles
• GET /api/v1/legal-articles/{article_id}
• POST /api/v1/legal-change-impacts/scan

Schema

New table:

legal_fulltext_versions

Key fields:

• tenant_id
• article_id
• version
• source_id
• source_aliases
• source_title
• article_no
• title
• article_text
• summary
• keywords
• tags
• status
• effective_date
• published_at
• governance fields: created_by, updated_by, deleted_at

Schema-check now treats the table as a Contract API core table and validates governance columns.

Validation

Local validation passed:

python -m py_compile `
  yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/legal_fulltext.py `
  yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/persistence/legal_fulltext.py `
  yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/persistence/models.py `
  yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/sqlalchemy_contract_repository.py `
  yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/sqlalchemy_repository_wiring.py `
  yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/schema_check.py `
  yuqei-contract-platform/services/contract-api/migrations/versions/20260702_0027_add_legal_fulltext_versions.py

python -m pytest yuqei-contract-platform/services/contract-api/tests/test_contract_workflow.py -q
python -m pytest yuqei-contract-platform/services/contract-api/tests/test_health.py -q

Added/updated tests:

• selected legal articles remain queryable
• DB-only legal article versions are listable, fetchable, and usable by impact scan
• latest legal fulltext version wins over the static fixture
• schema-check reports legal_fulltext_versions as a missing core/governance table on stale schemas

Remaining Items From The User's Closure List

Done:

• Phase 3 Slice 3.6 published snapshots
• Selected legal fulltext versioning first implementation slice

Still pending:

• Remote smoke deployment and verification of migration 20260702_0027
• Full V1 legal corpus import/backfill tooling
• AI Platform tenant/Trace governance
• Provider/OCR secret ref compatibility
• pgvector extension/dimension/index schema-check
• Delivery quality gates rerun: Docker smoke, schema-check, interface benchmark, security scan, CI quality gate
• Deployment docs update after remote smoke and remaining quality gates

Recommended Next Step

Deploy this Contract API slice to 192.168.3.90 smoke, run Alembic to 20260702_0027, then verify:

1. /api/v1/runtime/schema-check
2. GET /api/v1/legal-articles?keyword=违约金
3. GET /api/v1/legal-articles/LEGAL-CIVIL-0585
4. POST /api/v1/legal-change-impacts/scan

After smoke passes, continue with AI Platform tenant/Trace governance.