leaudit-platform-backend/docs/superpowers/plans/2026-05-23-qichacha-migration.md

Qichacha Migration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Migrate the legacy Qichacha company verification module into the current LeAudit backend and keep the existing frontend company-info modal working.

Architecture: Add a [QICHACHA] TOML settings section, a new qcc_company_info active-record model, DTO/VO objects, a service interface plus implementation, and a small HTTP client wrapper for Qichacha signing and API parsing. Controllers expose /api/v2/qichacha/* using unified Result[...]; the frontend wrapper unwraps both the new Result response and the old raw legacy shape.

Tech Stack: FastAPI, SQLAlchemy async ORM, Pydantic v2, httpx, pytest, Next.js TypeScript.

---

Task 1: Configuration And Response Contract

Files:

• Modify: app.toml

• Modify: fastapi_admin/config/_settings.py

• Modify: fastapi_admin/config/__init__.py

• Create: tests/test_qichacha_config_client.py

• Write failing tests proving QICHACHA_* settings are exported and the client generates the expected MD5 token.

• Add QichachaSettings and [QICHACHA] placeholders.

• Implement QichachaClient with signing, retry-friendly GET calls, and response validation.

• Run pytest tests/test_qichacha_config_client.py -q.

Task 2: Backend Domain And Cache Service

Files:

• Create: fastapi_common/fastapi_common_web/exception/QichachaException.py

• Create: fastapi_modules/fastapi_leaudit/domian/Dto/qichachaDto.py

• Create: fastapi_modules/fastapi_leaudit/domian/vo/qichachaVo.py

• Create: fastapi_modules/fastapi_leaudit/models/qichachaCompanyInfo.py

• Create: fastapi_modules/fastapi_leaudit/services/qichachaService.py

• Create: fastapi_modules/fastapi_leaudit/services/impl/qichachaServiceImpl.py

• Modify: fastapi_modules/fastapi_leaudit/models/__init__.py

• Modify: fastapi_modules/fastapi_leaudit/services/__init__.py

• Create: tests/test_qichacha_service.py

• Write failing tests for cache hit, stale refresh, force refresh, and dishonesty count mapping.

• Implement model classmethods for keyword lookup and upsert.

• Implement service interface and implementation returning VO objects.

• Run pytest tests/test_qichacha_service.py -q.

Task 3: API Routes, Permissions, SQL

Files:

• Create: fastapi_modules/fastapi_leaudit/controllers/qichachaController.py

• Modify: fastapi_modules/fastapi_leaudit/services/impl/rbacAdminServiceImpl.py

• Modify: scripts/创建sql/user_rbac_seed.sql

• Create: scripts/创建sql/schema_qichacha_company_info.sql

• Add authenticated routes for /v2/qichacha/company, /enterprise, /dishonesty, /batch, /status.

• Add action permissions qichacha:company:query and qichacha:status:read without creating a route/menu entry.

• Add SQL schema for qcc_company_info.

• Run backend import and focused pytest checks.

Task 4: Frontend Compatibility

Files:

• Modify: legal-platform-frontend/lib/api/legacy/corporate-information/qichacha.ts

• Add a local unwrap helper that returns response.data.data for new Result responses and raw response.data for legacy responses.

• Use it in queryCompanyInfo, queryEnterpriseInfo, and queryDishonestyInfo.

• Run TypeScript or lint check for the changed file scope.

Task 5: Verification

• Run focused backend tests: pytest tests/test_qichacha_config_client.py tests/test_qichacha_service.py -q.
• Run Python compile/import checks for new backend files.
• Run frontend lint/type verification if available.
• Review git diff to ensure no unrelated dirty files were reverted.