docs: update spec verification and checklist

Document the existing REV-002 backend billing-generation path and preserve a conservative partial-implementation judgment so the design stays aligned with current code evidence.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.codex/prompts/speckit.analyze.md

@@ -0,0 +1,184 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS

.codex/prompts/speckit.checklist.md

@@ -0,0 +1,295 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+   - File handling behavior:
+     - If file does NOT exist: Create new file and number items starting from CHK001
+     - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016)
+   - Never delete or replace existing checklist content - always preserve and append
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"

.codex/prompts/speckit.clarify.md

@@ -0,0 +1,181 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 5 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS

.codex/prompts/speckit.constitution.md

@@ -0,0 +1,84 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
+
+Follow this execution flow:
+
+1. Load the existing constitution at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.

.codex/prompts/speckit.implement.md

@@ -0,0 +1,198 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before implementation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_implement` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter to only hooks where `enabled: true`
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
+
+10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
+    - If it exists, read it and look for entries under the `hooks.after_implement` key
+    - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+    - Filter to only hooks where `enabled: true`
+    - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+      - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+      - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+    - For each executable hook, output the following based on its `optional` flag:
+      - **Optional hook** (`optional: true`):
+        ```
+        ## Extension Hooks
+
+        **Optional Hook**: {extension}
+        Command: `/{command}`
+        Description: {description}
+
+        Prompt: {prompt}
+        To execute: `/{command}`
+        ```
+      - **Mandatory hook** (`optional: false`):
+        ```
+        ## Extension Hooks
+
+        **Automatic Hook**: {extension}
+        Executing: `/{command}`
+        EXECUTE_COMMAND: {command}
+        ```
+    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

.codex/prompts/speckit.plan.md

@@ -0,0 +1,90 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs: 
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
+   - Identify what interfaces the project exposes to users or other systems
+   - Document the contract format appropriate for the project type
+   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
+   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh codex`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications

.codex/prompts/speckit.specify.md

@@ -0,0 +1,237 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: speckit.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Create the feature branch** by running the script with `--short-name` (and `--json`), and do NOT pass `--number` (the script auto-detects the next globally available number across all branches and spec directories):
+
+   - Bash example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" --json --short-name "user-auth" "Add user authentication"`
+   - PowerShell example: `.specify/scripts/bash/create-new-feature.sh "$ARGUMENTS" -Json -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Do NOT pass `--number` — the script determines the correct next number automatically
+   - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 7
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)

.codex/prompts/speckit.tasks.md

@@ -0,0 +1,200 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before tasks generation)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_tasks` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter to only hooks where `enabled: true`
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    
+    Wait for the result of the hook command before proceeding to the Outline.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
+   - If it exists, read it and look for entries under the `hooks.after_tasks` key
+   - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+   - Filter to only hooks where `enabled: true`
+   - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+     - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+     - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+   - For each executable hook, output the following based on its `optional` flag:
+     - **Optional hook** (`optional: true`):
+       ```
+       ## Extension Hooks
+
+       **Optional Hook**: {extension}
+       Command: `/{command}`
+       Description: {description}
+
+       Prompt: {prompt}
+       To execute: `/{command}`
+       ```
+     - **Mandatory hook** (`optional: false`):
+       ```
+       ## Extension Hooks
+
+       **Automatic Hook**: {extension}
+       Executing: `/{command}`
+       EXECUTE_COMMAND: {command}
+       ```
+   - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

.codex/prompts/speckit.taskstoissues.md

@@ -0,0 +1,30 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL

.dockerignore

@@ -0,0 +1,11 @@
+node_modules/
+.git/
+.dockerignore
+Dockerfile*
+dist/
+build/
+coverage/
+*.log*
+.env*
+.DS_Store
+Thumbs.db

.gitignore

@@ -36,4 +36,9 @@ pdf_output/福建水务业务系统设计方案.pdf
 pdf_output/福建水务业务系统数据库设计.pdf
 pdf_output.tar.gz
 node_modules
+dist/
+build/
+*.log
+.env*
 temp_mermaid_*
+.codex

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        if has_jq; then
+            jq -cn \
+                --arg repo_root "$REPO_ROOT" \
+                --arg branch "$CURRENT_BRANCH" \
+                --arg feature_dir "$FEATURE_DIR" \
+                --arg feature_spec "$FEATURE_SPEC" \
+                --arg impl_plan "$IMPL_PLAN" \
+                --arg tasks "$TASKS" \
+                '{REPO_ROOT:$repo_root,BRANCH:$branch,FEATURE_DIR:$feature_dir,FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,TASKS:$tasks}'
+        else
+            printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+                "$(json_escape "$REPO_ROOT")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$TASKS")"
+        fi
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if has_jq; then
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
+        fi
+        jq -cn \
+            --arg feature_dir "$FEATURE_DIR" \
+            --argjson docs "$json_docs" \
+            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+    else
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
+            json_docs="[${json_docs%,}]"
+        fi
+        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+    fi
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi

.specify/scripts/bash/common.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        return 1
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir
+    if ! feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch"); then
+        echo "ERROR: Failed to resolve feature directory" >&2
+        return 1
+    fi
+
+    # Use printf '%q' to safely quote values, preventing shell injection
+    # via crafted branch names or paths containing special characters
+    printf 'REPO_ROOT=%q\n' "$repo_root"
+    printf 'CURRENT_BRANCH=%q\n' "$current_branch"
+    printf 'HAS_GIT=%q\n' "$has_git_repo"
+    printf 'FEATURE_DIR=%q\n' "$feature_dir"
+    printf 'FEATURE_SPEC=%q\n' "$feature_dir/spec.md"
+    printf 'IMPL_PLAN=%q\n' "$feature_dir/plan.md"
+    printf 'TASKS=%q\n' "$feature_dir/tasks.md"
+    printf 'RESEARCH=%q\n' "$feature_dir/research.md"
+    printf 'DATA_MODEL=%q\n' "$feature_dir/data-model.md"
+    printf 'QUICKSTART=%q\n' "$feature_dir/quickstart.md"
+    printf 'CONTRACTS_DIR=%q\n' "$feature_dir/contracts"
+}
+
+# Check if jq is available for safe JSON construction
+has_jq() {
+    command -v jq >/dev/null 2>&1
+}
+
+# Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
+# Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
+json_escape() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\t'/\\t}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\b'/\\b}"
+    s="${s//$'\f'/\\f}"
+    # Strip remaining control characters (U+0000–U+001F) not individually escaped above
+    s=$(printf '%s' "$s" | tr -d '\000-\007\013\016-\037')
+    printf '%s' "$s"
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+
+# Resolve a template name to a file path using the priority stack:
+#   1. .specify/templates/overrides/
+#   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+#   3. .specify/extensions/<ext-id>/templates/
+#   4. .specify/templates/ (core)
+resolve_template() {
+    local template_name="$1"
+    local repo_root="$2"
+    local base="$repo_root/.specify/templates"
+
+    # Priority 1: Project overrides
+    local override="$base/overrides/${template_name}.md"
+    [ -f "$override" ] && echo "$override" && return 0
+
+    # Priority 2: Installed presets (sorted by priority from .registry)
+    local presets_dir="$repo_root/.specify/presets"
+    if [ -d "$presets_dir" ]; then
+        local registry_file="$presets_dir/.registry"
+        if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
+            # Read preset IDs sorted by priority (lower number = higher precedence).
+            # The python3 call is wrapped in an if-condition so that set -e does not
+            # abort the function when python3 exits non-zero (e.g. invalid JSON).
+            local sorted_presets=""
+            if sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
+import json, sys, os
+try:
+    with open(os.environ['SPECKIT_REGISTRY']) as f:
+        data = json.load(f)
+    presets = data.get('presets', {})
+    for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10)):
+        print(pid)
+except Exception:
+    sys.exit(1)
+" 2>/dev/null); then
+                if [ -n "$sorted_presets" ]; then
+                    # python3 succeeded and returned preset IDs — search in priority order
+                    while IFS= read -r preset_id; do
+                        local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
+                        [ -f "$candidate" ] && echo "$candidate" && return 0
+                    done <<< "$sorted_presets"
+                fi
+                # python3 succeeded but registry has no presets — nothing to search
+            else
+                # python3 failed (missing, or registry parse error) — fall back to unordered directory scan
+                for preset in "$presets_dir"/*/; do
+                    [ -d "$preset" ] || continue
+                    local candidate="$preset/templates/${template_name}.md"
+                    [ -f "$candidate" ] && echo "$candidate" && return 0
+                done
+            fi
+        else
+            # Fallback: alphabetical directory order (no python3 available)
+            for preset in "$presets_dir"/*/; do
+                [ -d "$preset" ] || continue
+                local candidate="$preset/templates/${template_name}.md"
+                [ -f "$candidate" ] && echo "$candidate" && return 0
+            done
+        fi
+    fi
+
+    # Priority 3: Extension-provided templates
+    local ext_dir="$repo_root/.specify/extensions"
+    if [ -d "$ext_dir" ]; then
+        for ext in "$ext_dir"/*/; do
+            [ -d "$ext" ] || continue
+            # Skip hidden directories (e.g. .backup, .cache)
+            case "$(basename "$ext")" in .*) continue;; esac
+            local candidate="$ext/templates/${template_name}.md"
+            [ -f "$candidate" ] && echo "$candidate" && return 0
+        done
+    fi
+
+    # Priority 4: Core templates
+    local core="$base/${template_name}.md"
+    [ -f "$core" ] && echo "$core" && return 0
+
+    # Template not found in any location.
+    # Return 1 so callers can distinguish "not found" from "found".
+    # Callers running under set -e should use: TEMPLATE=$(resolve_template ...) || true
+    return 1
+}
+

.specify/scripts/bash/create-new-feature.sh

@@ -0,0 +1,327 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Trim whitespace and validate description is not empty (e.g., user passed only whitespace)
+FEATURE_DESCRIPTION=$(echo "$FEATURE_DESCRIPTION" | xargs)
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Error: Feature description cannot be empty or contain only whitespace" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune >/dev/null 2>&1 || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+    if ! git checkout -b "$BRANCH_NAME" 2>/dev/null; then
+        # Check if branch already exists
+        if git branch --list "$BRANCH_NAME" | grep -q .; then
+            >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
+            exit 1
+        else
+            >&2 echo "Error: Failed to create git branch '$BRANCH_NAME'. Please check your git configuration and try again."
+            exit 1
+        fi
+    fi
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then
+    cp "$TEMPLATE" "$SPEC_FILE"
+else
+    echo "Warning: Spec template not found; created empty spec file" >&2
+    touch "$SPEC_FILE"
+fi
+
+# Inform the user how to persist the feature variable in their own shell
+printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
+
+if $JSON_MODE; then
+    if command -v jq >/dev/null 2>&1; then
+        jq -cn \
+            --arg branch_name "$BRANCH_NAME" \
+            --arg spec_file "$SPEC_FILE" \
+            --arg feature_num "$FEATURE_NUM" \
+            '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num}'
+    else
+        printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+    fi
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"
+fi

.specify/scripts/bash/setup-plan.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
+if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    if has_jq; then
+        jq -cn \
+            --arg feature_spec "$FEATURE_SPEC" \
+            --arg impl_plan "$IMPL_PLAN" \
+            --arg specs_dir "$FEATURE_DIR" \
+            --arg branch "$CURRENT_BRANCH" \
+            --arg has_git "$HAS_GIT" \
+            '{FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,SPECS_DIR:$specs_dir,BRANCH:$branch,HAS_GIT:$has_git}'
+    else
+        printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+            "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$HAS_GIT")"
+    fi
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+

.specify/scripts/bash/update-agent-context.sh

@@ -0,0 +1,824 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Tabnine CLI, Kiro CLI, Mistral Vibe, Kimi Code, Antigravity or Generic
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|generic
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+# AMP, Kiro CLI, and IBM Bob all share AGENTS.md — use AGENTS_FILE to avoid
+# updating the same file multiple times.
+AMP_FILE="$AGENTS_FILE"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+TABNINE_FILE="$REPO_ROOT/TABNINE.md"
+KIRO_FILE="$AGENTS_FILE"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
+BOB_FILE="$AGENTS_FILE"
+VIBE_FILE="$REPO_ROOT/.vibe/agents/specify-agents.md"
+KIMI_FILE="$REPO_ROOT/KIMI.md"
+TRAE_FILE="$REPO_ROOT/.trae/rules/AGENTS.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    # Disarm traps to prevent re-entrant loop
+    trap - EXIT INT TERM
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+
+    # Prepend Cursor frontmatter for .mdc files so rules are auto-included
+    if [[ "$target_file" == *.mdc ]]; then
+        local frontmatter_file
+        frontmatter_file=$(mktemp) || return 1
+        printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+        cat "$temp_file" >> "$frontmatter_file"
+        mv "$frontmatter_file" "$temp_file"
+    fi
+
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ (\*\*)?Last\ updated(\*\*)?:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Ensure Cursor .mdc files have YAML frontmatter for auto-inclusion
+    if [[ "$target_file" == *.mdc ]]; then
+        if ! head -1 "$temp_file" | grep -q '^---'; then
+            local frontmatter_file
+            frontmatter_file=$(mktemp) || { rm -f "$temp_file"; return 1; }
+            printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+            cat "$temp_file" >> "$frontmatter_file"
+            mv "$frontmatter_file" "$temp_file"
+        fi
+    fi
+
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI" || return 1
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot" || return 1
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE" || return 1
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code" || return 1
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode" || return 1
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI" || return 1
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf" || return 1
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code" || return 1
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI" || return 1
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code" || return 1
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI" || return 1
+            ;;
+        qodercli)
+            update_agent_file "$QODER_FILE" "Qoder CLI" || return 1
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp" || return 1
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI" || return 1
+            ;;
+        tabnine)
+            update_agent_file "$TABNINE_FILE" "Tabnine CLI" || return 1
+            ;;
+        kiro-cli)
+            update_agent_file "$KIRO_FILE" "Kiro CLI" || return 1
+            ;;
+        agy)
+            update_agent_file "$AGY_FILE" "Antigravity" || return 1
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob" || return 1
+            ;;
+        vibe)
+            update_agent_file "$VIBE_FILE" "Mistral Vibe" || return 1
+            ;;
+        kimi)
+            update_agent_file "$KIMI_FILE" "Kimi Code" || return 1
+            ;;
+        trae)
+            update_agent_file "$TRAE_FILE" "Trae" || return 1
+            ;;
+        generic)
+            log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|generic"
+            exit 1
+            ;;
+    esac
+}
+
+# Helper: skip non-existent files and files already updated (dedup by
+# realpath so that variables pointing to the same file — e.g. AMP_FILE,
+# KIRO_FILE, BOB_FILE all resolving to AGENTS_FILE — are only written once).
+# Uses a linear array instead of associative array for bash 3.2 compatibility.
+# Note: defined at top level because bash 3.2 does not support true
+# nested/local functions. _updated_paths, _found_agent, and _all_ok are
+# initialised exclusively inside update_all_existing_agents so that
+# sourcing this script has no side effects on the caller's environment.
+
+_update_if_new() {
+    local file="$1" name="$2"
+    [[ -f "$file" ]] || return 0
+    local real_path
+    real_path=$(realpath "$file" 2>/dev/null || echo "$file")
+    local p
+    if [[ ${#_updated_paths[@]} -gt 0 ]]; then
+        for p in "${_updated_paths[@]}"; do
+            [[ "$p" == "$real_path" ]] && return 0
+        done
+    fi
+    # Record the file as seen before attempting the update so that:
+    # (a) aliases pointing to the same path are not retried on failure
+    # (b) _found_agent reflects file existence, not update success
+    _updated_paths+=("$real_path")
+    _found_agent=true
+    update_agent_file "$file" "$name"
+}
+
+update_all_existing_agents() {
+    _found_agent=false
+    _updated_paths=()
+    local _all_ok=true
+
+    _update_if_new "$CLAUDE_FILE" "Claude Code"           || _all_ok=false
+    _update_if_new "$GEMINI_FILE" "Gemini CLI"             || _all_ok=false
+    _update_if_new "$COPILOT_FILE" "GitHub Copilot"        || _all_ok=false
+    _update_if_new "$CURSOR_FILE" "Cursor IDE"             || _all_ok=false
+    _update_if_new "$QWEN_FILE" "Qwen Code"                || _all_ok=false
+    _update_if_new "$AGENTS_FILE" "Codex/opencode"         || _all_ok=false
+    _update_if_new "$AMP_FILE" "Amp"                       || _all_ok=false
+    _update_if_new "$KIRO_FILE" "Kiro CLI"                 || _all_ok=false
+    _update_if_new "$BOB_FILE" "IBM Bob"                   || _all_ok=false
+    _update_if_new "$WINDSURF_FILE" "Windsurf"             || _all_ok=false
+    _update_if_new "$KILOCODE_FILE" "Kilo Code"            || _all_ok=false
+    _update_if_new "$AUGGIE_FILE" "Auggie CLI"             || _all_ok=false
+    _update_if_new "$ROO_FILE" "Roo Code"                  || _all_ok=false
+    _update_if_new "$CODEBUDDY_FILE" "CodeBuddy CLI"       || _all_ok=false
+    _update_if_new "$SHAI_FILE" "SHAI"                     || _all_ok=false
+    _update_if_new "$TABNINE_FILE" "Tabnine CLI"           || _all_ok=false
+    _update_if_new "$QODER_FILE" "Qoder CLI"               || _all_ok=false
+    _update_if_new "$AGY_FILE" "Antigravity"               || _all_ok=false
+    _update_if_new "$VIBE_FILE" "Mistral Vibe"             || _all_ok=false
+    _update_if_new "$KIMI_FILE" "Kimi Code"                || _all_ok=false
+    _update_if_new "$TRAE_FILE" "Trae"                     || _all_ok=false
+
+    # If no agent files exist, create a default Claude file
+    if [[ "$_found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code" || return 1
+    fi
+
+    [[ "$_all_ok" == true ]]
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|tabnine|kiro-cli|agy|bob|vibe|qodercli|kimi|trae|generic]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

.tapd/.gitignore

@@ -0,0 +1,4 @@
+# TAPD local state
+state.json
+session.json
+*.local.*

.tapd/cache.md

@@ -0,0 +1,22 @@
+# TAPD 项目缓存
+
+## Workspace Snapshot
+
+- workspace_id：`64404594`
+- 项目名称：`水务数智营收管理系统`
+- 类别：`project`
+- 状态：`normal`
+- 创建人：`朱艳贞_`
+- 创建时间：`2025-04-15 17:38:26`
+- company_id：`21531661`
+
+## 本地判定
+
+- 本机 TAPD MCP：已可调用
+- 当前仓库：git 仓库
+- 当前项目已建立 `.tapd/` 目录结构
+
+## 共享建议
+
+本文件当前只保存稳定、可共享的项目缓存信息，可提交到仓库。
+如后续出现强本地化内容，应迁移到本地状态文件并通过 `.tapd/.gitignore` 忽略。

.tapd/index.md

@@ -0,0 +1,45 @@
+# TAPD 项目索引
+
+## Project Binding
+
+- 默认 workspace_id：`64404594`
+- 默认项目名称：`水务数智营收管理系统`
+- 当前仓库绑定策略：`锁定单项目`
+- 默认对象范围：`story`、`task`
+- 输出风格：`规范文档型`
+
+## 使用入口
+
+当任务涉及 TAPD 项目、需求、缺陷、任务、迭代时，优先读取本文件。
+
+如需补充项目缓存、术语口径、常用模板，再继续读取：
+
+- `./cache.md`
+- `./templates.md`
+
+## 查询约定
+
+- 当前仓库默认查询项目为 `64404594`
+- 未经用户明确要求，不切换到其他 workspace
+- 当前默认工作重心为：需求拆解与开发任务推进
+- 若任务转向缺陷跟踪或迭代汇报，应在输出中显式说明已切换对象范围
+
+## 输出约定
+
+- 输出语言默认使用中文
+- 优先给出结构化结论、对象编号、状态、负责人、时间等关键信息
+- 面向文档仓库时，优先采用可归档、可引用的规范化表达
+- 不在仓库文件中记录 token、Cookie、密码等敏感信息
+
+## 粒度对齐约定
+
+- TAPD 中的 `Story` 视为一个可独立评审、可独立交付、可独立验收的需求单元。
+- `Story` 是当前仓库与 `speckit` 对齐时的最小需求粒度，对应一个独立的 feature / `spec.md`。
+- TAPD 中的 `Task` 视为执行项，对应 `speckit.tasks` 中的具体任务，不单独作为 feature。
+- 若一个事项需要同步修改两篇及以上主文档，或同时涉及详细设计、接口设计、数据库设计中的两类及以上内容，应优先视为一个独立 `Story` / speckit feature。
+- 若一个事项仅涉及单个字段、单个表格、单处标题或单篇文档中的局部修订，默认按 `Task` 处理，而不是单独立项为 `Story`。
+
+## 待补充项
+
+- 常用术语字段排序可按后续使用习惯继续细化
+- 如后续需要周迭代汇报，可在 `templates.md` 中补充周报模板

.tapd/templates.md

@@ -0,0 +1,140 @@
+# TAPD 输出模板
+
+## 1. 规范文档型：需求/任务查询结果
+
+### 输出模板
+
+- 项目：`{{workspace_name}}`（`{{workspace_id}}`）
+- 对象类型：`{{entity_type}}`
+- 查询条件：`{{query_summary}}`
+- 结果摘要：`{{summary}}`
+
+#### 明细
+
+| 编号 | 标题 | 状态 | 负责人 | 计划时间 | 备注 |
+|------|------|------|--------|----------|------|
+| {{id}} | {{name}} | {{status}} | {{owner}} | {{schedule}} | {{note}} |
+
+#### 结论
+
+- 当前结论：{{conclusion}}
+- 后续动作：{{next_action}}
+
+## 2. 规范文档型：缺陷跟踪结果
+
+### 输出模板
+
+- 项目：`{{workspace_name}}`（`{{workspace_id}}`）
+- 缺陷范围：`{{query_summary}}`
+- 结果摘要：`{{summary}}`
+
+| 缺陷ID | 标题 | 状态 | 严重程度 | 处理人 | 备注 |
+|--------|------|------|----------|--------|------|
+| {{id}} | {{title}} | {{status}} | {{severity}} | {{owner}} | {{note}} |
+
+## 3. 规范文档型：迭代汇报
+
+### 输出模板
+
+- 项目：`{{workspace_name}}`（`{{workspace_id}}`）
+- 迭代：`{{iteration_name}}`
+- 时间范围：`{{date_range}}`
+
+#### 进展概览
+
+- 已完成：{{done_summary}}
+- 进行中：{{progressing_summary}}
+- 风险项：{{risk_summary}}
+
+#### 建议关注
+
+- {{focus_1}}
+- {{focus_2}}
+- {{focus_3}}
+
+## 4. 粒度映射模板
+
+### TAPD 与 speckit 对齐关系
+
+| TAPD 层级 | speckit 对应物 | 说明 |
+|-----------|----------------|------|
+| Epic / 大主题 | feature 背景 | 例如 REV-005 这类主题范围 |
+| Story | `spec.md` | 最小需求粒度，一个可独立评审与交付的设计闭环 |
+| Task | `tasks.md` 中的任务项 | 具体执行动作，如修改某篇文档、补某张表、校核某组引用 |
+
+### 立项判断规则
+
+优先作为一个独立 Story / speckit feature 的情形：
+
+- 需要跨两篇及以上主文档协同修改
+- 需要同时对齐详细设计、接口设计、数据库设计中的两类及以上内容
+- 具备明确边界、验收标准与独立评审价值
+
+优先作为 Task 的情形：
+
+- 单字段修订
+- 单表格补充
+- 单文档局部改写
+- 链接、标题、编号等局部一致性修复
+
+### speckit feature 命名模板
+
+#### 推荐命名公式
+
+`<主题编号>-<场景关键词>-<交付动作>`
+
+#### 推荐写法
+
+- `rev005-invoice-apply-design`
+- `rev005-invoice-redflush-alignment`
+- `rev005-invoice-status-rules`
+- `rev005-invoice-db-interface-sync`
+
+#### 中文标题模板
+
+`<主题编号>：<业务场景><交付动作>`
+
+示例：
+
+- `REV-005：补齐发票开具申请设计闭环`
+- `REV-005：统一发票红冲字段口径`
+- `REV-005：补齐发票状态流转规则`
+
+#### 命名约束
+
+- 使用小写英文与连字符 `-`
+- 不使用空格、中文、下划线
+- 主题编号放在最前面，便于同批需求聚类
+- 场景关键词优先写业务对象，不要只写模块名
+- 交付动作优先使用 `design`、`alignment`、`rules`、`sync`、`cleanup` 等可辨识词
+- 一个 feature 名称只表达一个独立交付目标，不混入多个并列场景
+
+#### 交付动作建议词表
+
+- `design`：补齐某业务场景设计闭环
+- `alignment`：统一多文档之间的字段或口径
+- `rules`：补齐规则、状态流转、约束条件
+- `sync`：做跨文档同步与一致性收口
+- `cleanup`：处理遗留结构、引用、编号、术语收口
+
+#### 快速套用模板
+
+- 场景设计类：`<topic>-<scenario>-design`
+- 口径统一类：`<topic>-<scenario>-alignment`
+- 规则补齐类：`<topic>-<scenario>-rules`
+- 跨文档收口类：`<topic>-<scenario>-sync`
+
+#### 当前仓库推荐示例
+
+- `rev005-invoice-apply-design`
+- `rev005-invoice-issue-result-sync`
+- `rev005-invoice-redflush-alignment`
+- `rev005-invoice-status-rules`
+- `rev005-invoice-db-interface-sync`
+
+## 术语偏好
+
+- story：需求
+- task：任务
+- bug：缺陷
+- iteration：迭代

CLAUDE.md

@@ -272,3 +272,18 @@ make unified-export
 - 可追溯到来源资料
 - 满足甲方交付语境
 - 便于后续继续维护、评审与导出
+
+## TAPD 协作约定
+
+当任务涉及 TAPD 项目、需求、缺陷、任务、迭代时，优先读取仓库根目录 `.tapd/index.md`。
+
+`.tapd/index.md` 作为当前仓库的 TAPD 绑定与使用入口；如需项目缓存、术语口径或输出模板，再继续读取：
+
+- `.tapd/cache.md`
+- `.tapd/templates.md`
+
+当前仓库默认绑定 TAPD 项目 `64404594`（`水务数智营收管理系统`），并按单项目方式使用；如用户未明确要求，不切换到其他 workspace。
+
+默认关注对象范围为需求（story）与任务（task），输出风格采用规范文档型，要求结果可归档、可引用、可直接纳入文档协作语境。
+
+不得将 token、Cookie、密码或其他敏感凭据写入 `.tapd/` 或仓库文档。

backend

@@ -1 +1 @@
-Subproject commit be71df0a1efc1d778fdfb337032993259943c1f7
+Subproject commit 115c208f9e68755217b7503eeb87e666ab0dd47b

docs/design/00_Management/01_Project_Progress.md

@@ -8,8 +8,8 @@
 | **项目目标** | 构建可交付给甲方的系统概要设计文档  |
 | **技术框架** | RuoYi-Vue-Pro + yudao-ui-admin-vue3 |
 | **开始时间** | 2024年12月                          |
-| **当前阶段** | 概要设计阶段                        |
-| **项目状态** | ✅ 已完成                           |
+| **当前阶段** | 第3阶段已完成（转入持续维护）       |
+| **项目状态** | ✅ 已完成，进入例行维护             |
 
 ## 文档交付清单
 
@@ -58,14 +58,16 @@
 | 完善安全设计方案   | `water_biz_security_design.md`     | ✅ 已完成 | 2024-12-19 | 🟢 等保三级安全设计已完成 |
 | 编写部署脚本示例   | `water_biz_deployment_design.md`   | ✅ 已完成 | 2024-12-19 | 🟢 容器化部署方案已完成   |
 
-### 第三阶段：文档优化 ✅ 已全部完成
+### 第三阶段：文档优化 ✅ 已完成
 
-| 任务         | 状态      | 完成时间   | 备注                    |
+| 任务 | 状态 | 完成时间 | 备注 |
 | ------------ | --------- | ---------- | ----------------------- |
-| 目录结构优化 | ✅ 已完成 | 2024-12-19 | 🟢 目录结构已标准化     |
-| 建立交叉引用 | ✅ 已完成 | 2024-12-19 | 🟢 文档间交叉引用已建立 |
-| 格式标准化   | ✅ 已完成 | 2024-12-19 | 🟢 格式已统一规范       |
-| 文档验证测试 | ✅ 已完成 | 2024-12-19 | 🟢 文档质量验证通过     |
+| 主文档导航与稳定锚点收敛 | ✅ 已完成 | 2026-03-11 | 🟢 主文档已统一为精简导航 + 稳定锚点 |
+| 主文档/模块追溯索引建立 | ✅ 已完成 | 2026-03-11 | 🟢 已形成主文档章节索引与模块追溯索引 |
+| 检索白名单与术语主入口收敛 | ✅ 已完成 | 2026-03-12 | 🟢 已形成检索分层与范围/术语主入口 |
+| 技术审查结论回写 | ✅ 已完成 | 2026-03-12 | 审查四项已在周检记录中形成结论，且唯一问题已归口修复 |
+| 业务审查结论回写 | ✅ 已完成 | 2026-03-12 | 审查三项已在周检记录中形成结论 |
+| 非关键治理补漏转入维护 | ✅ 已完成 | 2026-03-12 | 后续按周检机制持续跟踪，不再阻塞本阶段收口 |
 
 ## 质量控制检查点
 
@@ -114,6 +116,34 @@
 
 > 说明：本表中的历史记录按当时原始表述保留；当前正式数据库口径统一以“达梦数据库 8.0+”为准。
 
+| 2026-03-18 | REV-005 统计模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 为 `T055`、`T060`、`T061`、`T062`、`T063` 新增可直接填写的样本记录模板；2）将 SC-001 ~ SC-004 的建议统计口径细化为表格字段与待补说明，避免后续只剩抽象待办；3）保持“模板已补齐但实际统计结果仍待联调/测试环境补录”的真实状态，不虚构样本结果。 | 用户继续推进 REV-005，希望把剩余统计类待办进一步收敛成可执行模板，便于后续直接补录真实样本而不是重新设计统计格式。 | 正面影响，REV-005 当前已具备统一的统计与日志抽样记录模板；后续补 `T055`、`T060 ~ T063` 时可直接按模板填充真实环境数据，减少再次整理验证文档结构的成本。 |
+| 2026-03-18 | REV-005 verify 执行入口补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 补齐 `/business/invoice/apply`、`/query`、`/query/compensate`、`/write-back`、`/customer/query`、`/customer/download`、`/customer/push`、`/invalidate`、`/red-ink` 的最小请求模板；2）继续补齐 `T055`、`T060 ~ T063` 的执行命令草稿与样本采集顺序，明确仅作为测试/联调环境占位模板，真实地址、鉴权信息、业务主键与统计结果均待后续替换和回填；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“替换真实环境参数即可执行”的状态。 | 用户继续推进 REV-005，希望不要停留在抽象验证建议，而是把剩余 verify 工作推进到可直接执行、可直接补样本的程度。 | 正面影响，REV-005 当前已具备统一的验证入口、请求模板、命令草稿与采样顺序；后续在测试或联调环境中可直接替换参数发起请求并回填 `T055`、`T060 ~ T063` 的真实结果，减少重复梳理接口和命令的成本。 |
+| 2026-03-18 | REV-005 联调补录清单补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增 `T055`、`T060 ~ T063` 的联调补录清单，按“申请 → 查询 → 回写 → 补偿查询 → 客户查询/下载/推送 → 作废/红冲 → 日志抽样”顺序拆解步骤；2）为每一步明确主要输入、预期产出与回填位置，确保联调执行时不再重复梳理样本归档方式；3）同步 `03_Task_Checklist.md`，将 verify 阶段推进到“可按顺序执行并即时补录”的状态。 | 用户继续推进 REV-005，希望把剩余运行态补证工作从“有命令草稿”进一步推进到“有顺序、有产出、有回填位置”的联调操作清单。 | 正面影响，REV-005 当前已具备联调补录步骤清单，后续在测试或联调环境中可按固定顺序执行并即时回填样本、统计与日志证据，降低遗漏申请单号、受理号与日志检索条件的风险。 |
+| 2026-03-18 | REV-005 联调日报模板补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增联调日报 / 回填模板，覆盖日报头、当日执行摘要、样本回填索引、风险阻塞与当日结论；2）模板继续保持“只提供回填结构、不预填真实结果”的约束，避免后续联调记录与正式验证表脱节；3）同步 `03_Task_Checklist.md`，便于后续联调执行人与文档维护人使用同一套归档格式。 | 用户继续推进 REV-005，希望在联调补录清单之外，再提供一份可直接用于当天汇总与回填的日报模板，减少后续多人协作时记录口径不一致的问题。 | 正面影响，REV-005 当前不仅具备顺序化联调清单，也具备可直接归档的日报/回填模板；后续联调时可先记录当天执行情况，再回写正式统计表，提升多轮联调的可追溯性与一致性。 |
+| 2026-03-18 | REV-005 联调前置检查补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增联调前置检查清单，统一核对环境地址、鉴权信息、样本数据、主键映射、日志入口、回填责任与归档路径；2）继续保持“只补检查项，不预设联调结果”的约束，避免基础条件未确认就直接开始补录；3）同步 `03_Task_Checklist.md`，使后续联调执行前具备统一的准备项核对口径。 | 用户继续推进 REV-005，希望在联调步骤、日报模板之外，再补齐联调开始前必须核对的基础条件，减少环境、样本和日志入口反复确认的成本。 | 正面影响，REV-005 当前已具备联调前置检查清单；后续进入测试或联调环境前，可先按统一核对项确认环境、样本、鉴权与归档条件，降低联调过程中样本不可追溯、日志无法检索和回填责任不清的风险。 |
+| 2026-03-18 | REV-005 最终联调顺序与完成判定补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增最终联调执行顺序与完成判定清单，明确 `T060 → T061 → T062 → T063 → T055` 的建议收口顺序；2）为每个待办增加“完成标志 / 可勾选条件 / 是否已拿到真实样本 / 是否已回填正式表格 / 是否已留存附件”判定模板；3）同步 `03_Task_Checklist.md`，为后续联调完成后的任务关闭提供统一标准。 | 用户继续推进 REV-005，希望把剩余 verify 工作从“能执行”进一步推进到“知道何时算完成、按什么顺序关闭待办”的状态。 | 正面影响，REV-005 当前已具备最终联调执行顺序与完成判定标准；后续一旦取得真实样本，即可按统一顺序回填并关闭 `T055`、`T060 ~ T063`，避免因完成标准不一致导致台账与验证记录脱节。 |
+| 2026-03-18 | REV-005 剩余工作摘要补齐 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增“剩余工作摘要（可直接引用）”，将 `T055`、`T060 ~ T063` 的剩余联调取证工作压缩为可直接引用的说明；2）明确当前剩余工作不再是设计或实现补充，而是测试/联调环境下补齐运行态统计与日志证据；3）同步 `03_Task_Checklist.md`，便于提测、汇报和交接时直接复用统一表述。 | 用户继续推进 REV-005，希望把最后剩余事项再压缩成一段可直接对外汇报的摘要，而不是继续分散在多个模板和清单中。 | 正面影响，REV-005 当前不仅具备详细的联调执行资料，也具备可直接引用的剩余工作摘要；后续无论是提测说明、周报汇报还是任务交接，都可以直接复用统一口径。 |
+| 2026-03-18 | REV-005 最终交付摘要同步 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 新增“当前交付摘要”，统一说明已完成交付、未闭环事项与对外引用口径；2）将 `specs/002-rev005-invoice-flow/tasks.md` 中 `T065` 标记完成，并同步 `03_Task_Checklist.md` 的交付摘要说明；3）保持 `spec.md`、`tasks.md`、`verification.md` 与管理台账一致，明确 REV-005 当前为“US1 ~ US4 实现态闭环完成，SC-001 ~ SC-005 运行态统计待补”。 | 用户继续推进 REV-005，希望把当前可交付结论、剩余风险与下一步建议收敛成可直接引用的统一摘要，而不是散落在多个文件中。 | 正面影响，REV-005 现在已具备一套可直接用于评审、提测前说明和后续交接的统一摘要口径；团队可以在不虚构量化验收数据的前提下，明确区分“已完成实现态闭环”和“待补运行态统计证据”。 |
+| 2026-03-18 | REV-005 验收证据缺口复核与 tasks 校准 | 1）手工重建 `specs/002-rev005-invoice-flow/tasks.md`，修复 US4 与 Final Phase 的 `T057 ~ T061` 重号，并将 SC-001 ~ SC-004 统计补证、spec 状态同步与最终交付摘要拆分为 `T060 ~ T065` 显式待办；2）复核 `specs/002-rev005-invoice-flow/verification.md`、`spec.md` 与仓库关键字检索结果，确认当前仓库内尚未定位到 REV-005 对应的专项压测脚本、统计脚本或样本台账；3）将 `spec.md` 状态调整为 `Verification Pending`，并把后续动作收敛到样本统计、运行态日志抽样与 DDL 风险跟踪。 | 用户继续推进 REV-005，希望在不虚构验收数据的前提下，把当前真实完成度、待补证据和 Speckit 任务口径收敛一致。 | 正面影响，REV-005 的任务台账、规格状态与验证结论已统一到“实现闭环基本完成、SC-001 ~ SC-004 量化证据待补”的当前真实状态；后续可直接围绕专项统计和联调样本继续收口，而不会误判为一期已完成量化验收。 |
+| 2026-03-18 | REV-005 SC-005 日志追溯矩阵补齐 | 1）基于 `InvoiceServiceImpl.java` 梳理发票申请、查询/补偿、结果回写、客户侧查询/下载/推送、作废、红冲等关键动作的统一日志写入点；2）确认上述动作均通过 `recordInvoiceOperatLog` 归一写入，并由 `OperatLogService.createOperatLog` 承接操作人、客户与日志内容上下文；3）在 `specs/002-rev005-invoice-flow/verification.md` 回写“关键动作 ↔ 日志写入点”矩阵，将 SC-005 收敛为“实现态证据已补齐、运行态样本待抽查”。 | 用户继续推进 REV-005，一期验收优先补齐 SC-005 的可引用验证证据，避免日志完整率仍停留在笼统结论。 | 正面影响，REV-005 已具备可直接引用的实现态日志追溯矩阵，申请、查询补偿、回写、客户侧查询/下载/推送、作废、红冲等关键动作均可定位到统一日志写入点；后续主要补充测试环境样本抽查即可收口运行态证据。 |
+| 2026-03-18 | REV-005 `biz_invoice` DDL 来源核实 | 1）在 `backend/sql`、`docs/design/04_Appendix/Archive/03_Design_Docs/数据库设计.md`、`sql/lhc_数据库设计.md`、`docs/guides/BACKEND_TABLE_MAPPING.md` 范围内交叉检索 `biz_invoice`、作废/红冲新增字段与迁移脚本；2）确认仓库内未找到与当前 `InvoiceDO.java` 对应的 `biz_invoice` 物理 DDL / migration；3）确认 Archive 与 `sql/lhc_数据库设计.md` 中同名 `biz_invoice` 更偏“开票配置表”，不能直接作为 REV-005 发票主记录表的落库依据；4）将该结论回写到 REV-005 验证与管理台账。 | 用户继续要求沿 REV-005 把 US4 剩余风险查清，不停留在“表结构待补”泛化表述。 | 正面影响，REV-005 当前已明确“接口/DO/文档承接口径已完成，但物理落库证据仍未在仓库内闭环”；后续若推进提测或联调，可直接把 DDL 缺口作为明确风险跟踪，避免误判作废/红冲字段已正式落库。 |
+| 2026-03-18 | REV-005 验证文档补强实现态证据 | 1）在 `specs/002-rev005-invoice-flow/verification.md` 为 `SC-001 ~ SC-004` 补充基于 `InvoiceController.java`、`InvoiceServiceImpl.java` 与各请求 VO 的实现态证据，明确申请入口、必填字段、同步处理边界、回写联动、客户侧消费约束与幂等/拦截规则；2）在 `SC-005` 与 `T055` 模板补记 `biz_invoice` 物理 DDL / migration 持续跟踪结论，避免日志抽样与物理落库风险脱节；3）保持 `T055`、`T060 ~ T063` 仍为“待真实联调样本回填”，不虚构量化结果。 | 用户要求直接继续 REV-005，并在未取得真实联调样本前，先把可防御的实现态证据落入正式验证文档。 | 正面影响，REV-005 当前验证记录已从“只有模板和待补口径”提升为“模板 + 代码证据 + 明确缺口”并存；后续联调回填时可直接引用实现态依据解释统计口径、拦截分类与日志追溯边界。 |
+| 2026-03-17 | REV-005 作废与红冲二期最小入口落地（US4） | 1）更新 `spec.md`、`plan.md`、`tasks.md`，将 US4 从“边界预留”升级为当前二期实现范围；2）更新 `12_REV_Detailed.md`、`03_Interface_Design.md`，明确后台作废/红冲入口、状态边界与客户侧消费约束；3）在 `InvoiceController.java`、`InvoiceService.java`、`InvoiceServiceImpl.java` 中将作废/红冲入口升级为专门请求 VO，并补齐原因/备注、原发票代码/号码校验与日志留痕；4）扩展 `InvoiceDO.java` 承接作废原因/备注、红冲原因/备注、原发票代码/号码与触发来源字段，并在 service 中回写最小上下文；5）更新 `01_Database_Design.md` 中 REV-005 发票承接口径，补充作废/红冲原因、备注、原票关联与查询补偿上下文；6）执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 并通过。 | 用户持续要求“继续推进 REV-005”，在一期闭环收口后继续落地 US4 二期最小能力入口，避免作废/红冲长期停留在文档预留状态。 | 正面影响，REV-005 已从“一期正常开票闭环”进一步扩展到“二期作废/红冲最小入口可评审、可编译验证”的状态；当前已补齐专门 VO 接线、原票引用校验、DO 字段承接与数据库承接口径，后续主要剩余 Mapper/表结构层面的正式持久化落地。 || 2026-03-17 | REV-005 结果回写与客户侧电子发票消费闭环（US3） | 1）更新 `12_REV_Detailed.md`、`01_Database_Design.md`、`03_Interface_Design.md`，补齐结果回写、账单关联、客户侧查询/下载/推送电子发票规则；2）扩展 `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO，落地客户归属校验、`SUCCESS + fileUrl` 消费前置校验、账单开票状态联动、推送状态回写；3）执行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`、`make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 及 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 验证通过。 | 用户要求沿 `/speckit.implement` 持续推进 REV-005 US3，不中断实现链路，直接完成结果回写、账单关联与客户侧电子票消费闭环。 | 正面影响，REV-005 已形成“回写落账 + 账单状态联动 + 客户侧查询/下载/推送 + 最小编译验证”闭环，后续可继续衔接作废、红冲与更多电子发票渠道扩展。 |
+| 2026-03-16 | REV-005 后台发票申请与校验闭环（US1） | 1）在 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台发票申请入口；2）在 `service/invoice/InvoiceServiceImpl.java` 实现客户、客户开票信息、账单与税率校验，确保仅已收费未开票账单允许申请；3）补齐 `applicationNo` 或 `custId + chargeIds` 幂等控制、申请单号生成与申请记录落库；4）执行 `mvn -f backend/sw-business/pom.xml -pl sw-business-server -am -DskipTests compile` 最小编译验证并通过。 | 用户要求继续推进 REV-005 implement，优先完成后台发票申请、开票校验与 US1 收尾，不中断当前实现链路。 | 正面影响，REV-005 已形成“后台申请入口 + 关键校验 + 幂等受理 + 最小编译验证”闭环，后续可在此基础上继续推进 SYS-008 调用、开票结果回写、账单状态联动与电子发票推送下载能力。 |
+| 2026-03-12 | OMX 任务路由样例落地 | 1）新增 `docs/design/00_Management/17_OMX_Task_Routing_Examples.md`，给出 `REV-004`、`REV-003` 与正式文档修订三类任务的 leader / explorer / executor / verifier 分工模板；2）补充各 lane 的提示词模板、推荐执行顺序与不建议的并行方式；3）更新 `00_Management/README.md` 收录该文档入口。 | 用户希望在治理层之外，再拿到针对当前项目可以直接复用的多 Agent 分工模板，而不是只看抽象原则。 | 正面影响，OMX 从“有规则”变成“可直接照着分工执行”；后续在 `REV-004`、`REV-003` 等闭环中可直接套用 lane 拆分，减少 leader 临时编排成本。 |
+| 2026-03-12 | OMX 多 Agent 治理层落地 | 1）在根 `AGENTS.md` 中新增 OMX 多 Agent 协作补充，明确分层 AGENTS、任务路由矩阵、写冲突规则、范围控制基线与 worktree/tmux 约定；2）新增 `backend/AGENTS.md`，固化 backend 开发边界、最小实现策略与 BPM 接入规则；3）新增 `docs/design/04_Appendix/Archive/AGENTS.md`，明确 Archive 默认只读与来源回写规则；4）新增 `docs/design/00_Management/16_OMX_Multi_Agent_Guide.md`，统一 leader / writer / executor / verifier 分工与协作拓扑；5）更新 `00_Management/README.md` 收录新指南入口。 | 用户明确准备采用 `oh-my-codex` 进行多 Agent 开发，需要对现有 AGENTS 体系做分层化和路由化改造，避免现有规则在 Team Mode 下失效。 | 正面影响，当前项目从“单 agent 规则完备”提升为“多 agent 可控协作”；后续接入 OMX 时，目录级职责、写权限边界、范围基线与会话约定已经成型，可显著降低并发改稿和多 worker 写冲突风险。 |
+| 2026-03-12 | REV-004 一期执行手册与 worktree/tmux 启动脚本落地 | 1）新增 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将 `REV-004` 一期的范围、现状差距、最小改动方案、任务拆解、Codex Prompt 与验收清单固化为可执行手册；2）新增 `scripts/start-backend-codex-session.sh`，支持在 `backend/` 上创建或复用 worktree，并拉起 `tmux + codex` 三窗口开发会话；3）更新 `scripts/README.md` 记录脚本用途。 | 用户要求不仅给建议，还要把“如何规划执行、如何进入 worktree、如何在 tmux 场景下协作”落成可直接使用的资产。 | 正面影响，开发启动动作从“口头建议”变为“可复制执行”；后续围绕 `REV-004/REV-003/REV-008` 的闭环开发可直接复用该脚本和手册，降低 worktree、tmux、Codex 协作的起步成本与操作偏差。 |
+| 2026-03-13 | REV-004 一期范围正式文档收敛（US1） | 1）更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，将 REV-004 一期范围收敛为水量调整、金额调整、退款、冲正、坏账申请五类场景，并明确共性能力优先顺序、排除项与审批边界；2）重写 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，将其从 backend 执行导向收敛为正式文档修订执行手册；3）同步 `docs/design/01_Overview/03_Summary_Design.md` 与 `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md` 的范围摘要与追溯说明；4）执行目标文档 `make validate-file` 与 `make check-links` 校验并通过。 | 用户要求在 implement 阶段先完成 REV-004 一期正式文档范围收敛，不把 backend 代码实现写成本轮已完成内容。 | 正面影响，REV-004 一期边界、验收入口与追溯关系已在正式文档体系内闭环，后续 US2/US3 可直接在稳定范围上继续对齐接口、数据库与台账，不再受早期执行手册偏代码导向表述干扰。 |
+| 2026-03-18 | 完成全仓旧模块编号残留审计 | 1）新增 `docs/design/00_Management/18_Old_Module_Number_Audit.md`，对 `docs/design`、`docs/guides`、`specs` 中的 `METER-004`、`INST-004`、`INST-005` 及相关旧模块语义进行全仓审计；2）将命中项分为“必须修”“可保留历史描述”“Archive 原始资料”“合法保留的接口编号/子能力表达”四类；3）更新 `docs/design/00_Management/README.md` 收录审计清单入口。 | 用户要求执行全仓旧编号残留审计，明确哪些需要继续修、哪些应作为历史资料保留。 | 正面影响，后续旧编号治理从“按检索临时判断”转为“按清单分类处理”；正式文档、管理台账与 Archive 的处理边界更加清晰。 |
+| 2026-03-18 | 旧模块编号残留收口与追溯链接修正 | 1）更新 `docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md`，将文档定位从旧 `INST-004` 修正为 `INST-002 工程管理` 下的“合同签署与电子签章能力”专项补充；2）修正 `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` 中 `INST-002`、`INST-003` 的章节锚点，确保跳转与当前三段式模块结构一致；3）复核 `docs/design/01_Overview/03_Summary_Design.md` 的主口径章节，确认残留 `IF-METER-004`、`IF-INST-004/005` 均为接口编号而非旧模块编号。 | 用户要求继续收口“旧编号视为错误”的相关正式文档，并区分必须修项与可保留历史描述。 | 正面影响，正式文档层的模块编号、追溯入口与专项补充挂接关系进一步统一，评审和检索时不会再因旧 `INST-004/005` 模块语义误跳转。 |
+| 2026-03-18 | 基于整体架构图补齐模块清单并对齐详细设计承接关系 | 1）新增 `docs/design/01_Overview/05_Module_Inventory.md`，将整体架构图中的分层、子系统、模块与当前详设承接关系整理为统一清单；2）更新 `docs/design/01_Overview/README.md` 与 `docs/design/02_Detailed_Design/README.md`，明确该清单作为模块枚举与承接核对入口；3）更新 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 与 `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md`，补充架构图模块清单与当前详设之间的映射说明，明确 `WECHAT-*`、`MOBILE-*`、`WORK-*` 等模块当前按业务域正文或协同能力承接。 | 用户要求根据 `output/preview/福建水务营收系统整体架构图.html` 形成模块清单，并以此为基线对齐 `02_Detailed_Design` 目录。 | 正面影响，架构图中的模块枚举与详细设计现状之间建立了稳定映射，后续评审时可直接判断“哪些模块已有正文、哪些是协同承接、哪些仍停留在架构层列示”，减少按图追文时的歧义。 |
+| 2026-03-18 | 第二轮详细设计模块命名精对齐 | 1）更新 `docs/design/02_Detailed_Design/13_CS_Detailed.md`，补充 `CS-*` 与 `WECHAT-*` 的模块映射说明，并在章节标题中显式标注对应关系；2）更新 `docs/design/02_Detailed_Design/14_METER_Detailed.md`，明确架构图 `METER-001~003` 与当前四段式详设之间的映射；3）更新 `docs/design/02_Detailed_Design/15_INST_Detailed.md`，明确架构图三段式 `INST-*` 与当前五段式详设拆分之间的对应关系。 | 用户要求继续进行第二轮对齐，使详细设计正文与架构图模块名之间的对应关系更直接。 | 正面影响，评审者在查看模块正文时可直接识别“架构图编号 ↔ 详设章节”的关系，不需要在模块清单、主详设和正文之间来回换算。 |
+| 2026-03-18 | 按“现有编号错误”原则修复表务与报装模块编号 | 1）将 `14_METER_Detailed.md` 的正式模块编号修正为与架构图一致的 `METER-001 ~ METER-003`，并把表务工单、物联网同步降为 `METER-003` 下的子能力章节；2）将 `15_INST_Detailed.md` 的正式模块编号修正为与架构图一致的 `INST-001 ~ INST-003`，并把踏勘方案、合同签章改为对应模块下的子能力章节；3）同步更新 `01_Detailed_Design.md`、`02_Module_Traceability_Index.md` 与 `05_Module_Inventory.md` 的模块摘要和追溯引用。 | 用户明确要求不再把现有编号视为“可映射差异”，而是按“编号错误”直接修复。 | 正面影响，`02_Detailed_Design` 目录中的正式模块编号已与整体架构图一致，后续评审、检索和跨文档引用不再需要额外做编号换算。 |
+| 2026-03-18 | 同步修复接口设计与概要设计中的旧模块归属口径 | 1）更新 `docs/design/03_Technical_Design/03_Interface_Design.md`，将 `IF-METER-002/003/004`、`IF-INST-002/003/004/005` 的归属模块同步到修正后的 `METER-001 ~ 003`、`INST-001 ~ 003` 体系；2）更新 `docs/design/01_Overview/03_Summary_Design.md` 中仍残留的旧 `IF-METER-004`、`IF-INST-005` 描述，使其与接口主文档和架构图一致；3）补齐 `docs/design/02_Detailed_Design/01_Detailed_Design.md` 与 `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` 中尚未收口的范围描述。 | 用户要求把剩余相关文档一起修复，避免只改详细设计而其余专题仍保留旧编号。 | 正面影响，概要、详设、接口三层文档的模块归属口径已基本统一，后续查询接口归属和模块责任时不会再遇到新旧编号并存。 |
+| 2026-03-12 | 工作范围对齐 `营业收费管理系统-概要设计说明书20250912` 基线 | 1）将 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.docx` 转换为 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 并抽取配套图片目录；2）在 `docs/design/01_Overview/03_Summary_Design.md` 补充历史来源对齐说明；3）在 `docs/design/01_Overview/01_System_Overview.md`、`docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`、`docs/design/00_Management/10_AI_Retrieval_Whitelist.md` 固化“工作范围以主文档与该 Archive 基线交集为准”的控制规则；4）更新 Archive 索引与附录入口。 | 用户明确要求后续工作范围与 `营业收费管理系统-概要设计说明书20250912.md` 对齐，避免设计与开发准备超出当前项目边界。 | 正面影响，后续文档补完、开发拆分和 AI Agent 执行时有了明确的范围控制基线；既能使用该历史稿进行边界收敛，又不会把历史名称、别名编号和旧接口体系直接带回正式主文档。 |
+| 2026-03-12 | `Database/Interface` 迁移闭环 P0 补完 | 对两份技术主文档继续执行旧系统迁移闭环补完：1）在 `docs/design/03_Technical_Design/01_Database_Design.md` 的 `SYS-002 开账、收费与票据表` 后新增“旧系统历史台账迁移与只读查询口径”，明确在线主模型承接范围、历史只读保留范围与迁移验收最低对账口径；2）在 `docs/design/03_Technical_Design/03_Interface_Design.md` 新增“历史查询与迁移校验接口口径”，将历史查询和迁移验收统一挂靠到既有 `IF-REV/CS/METER` 接口族；3）执行两份文档单文件校验并通过。 | 用户同意继续把迁移分析结论同步到数据库和接口主文档，形成从模块正文到技术主稿的闭环。 | 正面影响，`REV/CS/METER` 已补完的迁移口径不再停留在分模块正文，数据库和接口主文档已同步约束“哪些进在线模型、哪些保留历史只读、验收时按什么口径对账”；本周开发与迁移评审可直接以主文档为准，减少实现阶段对旧系统细粒度对象的误判。 |
+| 2026-03-12 | `REV/CS/METER` 旧系统迁移缺口 P0 补完 | 基于 `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`，对三份分模块详细设计执行旧系统迁移口径补完：1）`12_REV_Detailed.md` 增补定额共享/核定、特殊开账、柜台结账、红冲、发票关系、催缴停水、银行托收与微信配置等迁移说明；2）`13_CS_Detailed.md` 增补业务进度、开票方式变更、微客服后台设置与业务字段配置，并补充对应核心数据与接口映射；3）`14_METER_Detailed.md` 增补业务清单、上报清单、问题回填、代办工单、停复水工单、水表检定及出入退废库等迁移设计；4）执行三份文档单文件校验并通过。 | 用户要求按迁移差异清单继续推进，把本周开发前必须补齐的 `REV/CS/METER` 模块缺口收敛为可开发设计。 | 正面影响，营收、客户服务、表务三大业务链路已从“主能力存在但迁移承接不足”提升为“旧功能承接方式、历史保留策略、实现入口与接口映射可追溯”；本周围绕账务、渠道、工单联动启动开发时，缺少旧系统语义承接导致的返工风险显著降低。 |
+| 2026-03-12 | 新增旧系统迁移差异分析与 P0 补完清单 | 新增 `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`，形成三项可直接用于评审和开发准备的输出：1）旧系统功能迁移差异清单；2）旧表/旧菜单 → 新模块映射矩阵；3）P0 必补章节清单；同时更新 `docs/design/00_Management/README.md` 增加迁移治理入口。 | 用户要求从“旧系统迁移”视角重新审视当前正式设计，明确功能缺口、历史数据承接和本周开发前必须补完的章节。 | 正面影响，迁移讨论从“有没有功能”提升到“旧功能如何承接、历史查询如何保留、哪些章节必须先补”的可执行层；可直接支撑本周开发拆分、评审和割接准备。 |
 | 2026-03-12 | `03_Interface_Design` 补齐 SYS-002 高优先接口字段定义 | 对 `docs/design/03_Technical_Design/03_Interface_Design.md` 补齐本周开发所需的高优先 `SYS-002` 接口定义：1）新增 `IF-REV-007/009/012`、`IF-CS-001/002/004`、`IF-METER-001/003/004`、`IF-INST-001/002/004/005` 的关键接口说明；2）补齐上述接口的字段级请求/响应定义；3）统一请求字段、响应字段、主表映射和结果状态口径；4）将主文档 `last_reviewed` 更新为 `2026-03-12`。 | 用户明确要求优先补齐 `SYS-002` 文档内容，以便本周直接启动开发。 | 正面影响，接口主文档从“模块说明齐全但字段定义局部缺失”提升为“开发可直接参照”的状态；开发时能直接按接口字段、状态枚举和主表映射拆分 Controller/Service/VO，减少反复追问和返工。 |
 | 2026-03-12 | `15_INST_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/15_INST_Detailed.md` 执行与 `REV/CS/METER` 同步的结构化补完：1）新增“报装模块统一约束”与“接口与数据追溯矩阵”；2）为 `INST-001~INST-005` 补充核心数据、接口映射与落地边界；3）为 `INST-001/002/003` 增加申请、踏勘、施工验收流程图；4）明确 `biz_process*`/`biz_content*` 为当前实现态口径，`installation_*` 为专题扩展口径。 | 用户要求优先补齐 `SYS-002` 文档内容，形成本周可直接支撑开发的闭环模块。 | 正面影响，`SYS-002` 四大业务模块正文结构统一，报装链路从受理到归档的开发边界更清晰；实现态与设计态口径分离后，可减少开发阶段对专题扩展表的误读。 |
 | 2026-03-11 | `14_METER_Detailed` 结构对齐补完（模板同步） | 对 `docs/design/02_Detailed_Design/14_METER_Detailed.md` 执行与 REV/CS 同步的结构化补完：1）新增“表务模块统一约束”与“接口与数据追溯矩阵”；2）为 `METER-001~METER-004` 补充核心数据、接口映射与落地边界；3）为 `METER-002` 增加工单处理流程图；4）为 `METER-004` 补充关键规则，明确 IoT 数据进入营收开账链路前的校验与异常处理边界。 | 用户要求继续同步分模块正文模板，提升表务模块评审可读性与跨文档追溯一致性。 | 正面影响，表务模块从简要提纲升级为可交付的结构化详细设计，设备档案、工单、库存、物联网接入与营收系统的协同边界更清晰，可降低联调与后续维护中的口径偏差。 |
@@ -288,3 +318,26 @@
 ---
 
 **🎊 项目圆满完成！所有核心设计文档已达到甲方A级交付标准，可正式交付！**
+
+### 2026-03-17 更新
+
+- 新增 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`，完成 `SYS-002` 需求总览、Story/feature 映射、代码实现评估与 TAPD 转换建议整理。
+- 形成 `SYS002-REQ-001 ~ 015` 的统一拆解口径，可直接用于 Speckit 立项、TAPD Story/Task 建模与后续文档/实现对齐跟踪。
+
+### 2026-03-18 更新
+
+- 完成 `REV-006` Speckit feature `006-reminder-event-design` 的 implement 阶段文档收口，统一 `12_REV_Detailed.md`、`03_Interface_Design.md` 与治理台账口径。
+- `REV-006` 正式业务接口编号确定为 `IF-REV-013`，不再复用 `IF-REV-009`；催缴结果状态统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态。
+- 明确旧“催缴记录 / 停水记录 / 预存短信记录”按历史只读口径承接，不新增同名在线主表；停复水在本轮仅保留联动边界、处置引用和追溯关系。
+- 启动并完成 `REV-007` Speckit feature `004-rev007-revenue-statistics-design` 的 `specify -> plan -> tasks` 工件链，形成统计主题、维度、指标、`IF-REV-010` 与数据库承接口径的正式设计基线。
+- `REV-007` 当前收口结论为“设计补齐推进中、代码入口未见明确实现”；本轮重点是统一正式文档与治理台账，不将预测分析、BI 专题或独立数仓能力写成既成事实。
+- 完成 `REV-002` Speckit feature `005-rev002-billing-generation-gap` 的第一轮正式文档收口，补齐 `12_REV_Detailed.md` 中开账触发前提、规则来源、结果表达、特殊开账统一模型与下游排除项。
+- 完成 `03_Interface_Design.md` 中 `IF-REV-005` 的边界补强，明确请求前提、失败阻断语义、成功/失败结果表达以及与收费、发票、催缴链路的职责边界。
+- 完成 `01_Database_Design.md` 与 `15_SYS002_Requirement_Breakdown.md` 的同步回写，明确 `biz_charge` / `biz_charge_detail`、价格规则对象和历史特殊开账的正式承接口径，并继续维持 `SYS002-REQ-004`“部分实现”的保守判断。
+- 基于 `ChargeController`、`ChargeServiceImpl` 与 `ReadingDataServiceImpl` 的第二轮 backend 证据精修 `REV-002` 结论，确认当前已支持按 `readingDataIds` 批量复核并开账，成功路径会写入 `biz_charge` / `biz_charge_detail` 并回写抄表数据状态。
+- 同步明确 `IF-REV-005` 当前实现缺口：请求仍局限 `readingDataIds`，返回仍为成功条数字符串，失败阻断未形成结构化结果，且仅支持 `ACTUAL_USAGE` 结算方式，因此治理判断继续维持“部分实现”。
+
+### 2026-03-19 更新
+
+- 完成 `REV-006` 当前轮次治理文档二次对齐：在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”判断，并补记 `specs/006-reminder-event-design/` 工件基线与后续研发切入建议。
+- 同步回写 `03_Task_Checklist.md` 与本进度文档，补充本轮 implement 阶段的治理动作、验证动作与台账一致性说明，避免将文档收口误写为 backend 已实现。

docs/design/00_Management/03_Task_Checklist.md

@@ -138,6 +138,140 @@
 
 ## ✅ 最新完成任务 (持续更新)
 
+### 📋 OMX 任务路由样例
+
+- [x] **完成 OMX 任务路由样例落地** ✅ (2026-03-12)
+  - [x] 新增 `17_OMX_Task_Routing_Examples.md`，补充 `REV-004` 样例 ✅
+  - [x] 补充 `REV-003` 样例与文档修订样例 ✅
+  - [x] 补充 leader / explorer / executor / verifier 提示词模板 ✅
+  - [x] 更新 `00_Management/README.md` 与 `01_Project_Progress.md` 入口和变更记录 ✅
+
+### 📋 OMX 多 Agent 治理层
+
+- [x] **完成 OMX 多 Agent 治理层落地** ✅ (2026-03-12)
+  - [x] 在根 `AGENTS.md` 增加多 Agent 路由、并发与范围控制规则 ✅
+  - [x] 新增 `backend/AGENTS.md`，固化 backend 闭环开发边界 ✅
+  - [x] 新增 `docs/design/04_Appendix/Archive/AGENTS.md`，固化 Archive 默认只读与回写要求 ✅
+  - [x] 新增 `docs/design/00_Management/16_OMX_Multi_Agent_Guide.md`，明确角色分工、冲突规避与 worktree/tmux 约定 ✅
+  - [x] 更新 `00_Management/README.md` 与 `01_Project_Progress.md` 记录入口和变更 ✅
+
+### 📋 REV-004 执行资产落地
+
+- [x] **完成 REV-004 一期执行手册与启动脚本落地** ✅ (2026-03-12)
+  - [x] 新增 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，固化范围、最小改动方案、任务拆解与验收清单 ✅
+  - [x] 新增 `scripts/start-backend-codex-session.sh`，支持 backend worktree + tmux + Codex 启动 ✅
+  - [x] 在 `scripts/README.md` 登记启动脚本用途 ✅
+  - [x] 在 `01_Project_Progress.md` 记录本次执行资产落地 ✅
+- [x] **完成 REV-004 一期范围正式文档收敛（US1）** ✅ (2026-03-13)
+  - [x] 更新 `12_REV_Detailed.md`，明确一期仅保留水量调整、金额调整、退款、冲正、坏账申请五类场景 ✅
+  - [x] 重写 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，明确执行范围、验收入口、最小校验动作与台账触发条件 ✅
+  - [x] 同步 `03_Summary_Design.md` 与 `rev004-traceability-matrix.md` 的范围摘要、接口入口与审批边界说明 ✅
+  - [x] 完成 `make validate-file` 与 `make check-links` 最小校验，并在 `01_Project_Progress.md` 回写重要进展 ✅
+- [x] **完成 REV-004 接口与数据口径对齐（US2）** ✅ (2026-03-13)
+  - [x] 更新 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，统一 REV-004 场景规则、接口字段与物理承接口径 ✅
+  - [x] 同步 `data-model.md`、`if-rev-007-accounting-request.md`、`rev004-scenario-matrix.md`、`rev004-traceability-matrix.md` 的共享实体与追溯口径 ✅
+  - [x] 完成 `make validate-file` 与 `make check-links` 最小校验，满足 US2 独立评审与验收条件 ✅
+- [x] **完成 REV-004 可执行交付闭环固化（US3）** ✅ (2026-03-13)
+  - [x] 执行手册已明确后续任务拆解顺序：执行手册闭环 → 支撑产物同步 → 台账按触发条件更新 ✅
+  - [x] 独立验收入口已限定为 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 三份文件 ✅
+  - [x] 最小校验动作与 tracked task 完成条件已明确，可继续按后续 tasks 拆解推进 ✅
+- [x] **完成 REV-005 后台发票申请与校验闭环（US1）** ✅ (2026-03-16)
+  - [x] 在 `InvoiceController.java` 增加后台发票申请入口，形成后台单笔/批量发票申请受理入口 ✅
+  - [x] 在 `InvoiceServiceImpl.java` 完成客户、客户开票信息、账单与税率校验，确保仅已收费未开票账单允许申请 ✅
+  - [x] 实现 `applicationNo` 或 `custId + chargeIds` 幂等控制、申请单号生成与申请记录落库 ✅
+  - [x] 执行 `mvn -f backend/sw-business/pom.xml -pl sw-business-server -am -DskipTests compile` 最小编译验证并通过，完成 US1 收尾 ✅
+- [x] **完成 REV-005 查询兜底与异步协同闭环（US2）** ✅ (2026-03-17)
+  - [x] 后台查询接口新增补偿查询触发入口，支持按申请单号/受理号复用查询逻辑 ✅
+  - [x] 发票对象、Mapper 与查询 VO 已补齐 `sysRequestNo`、`lastTryTime`、`nextTryTime`、`tryCount`、`latestResult`、`latestError` 字段 ✅
+  - [x] 发票服务已实现受理号生成、回写落账、查询补偿留痕与成功状态不被失败结果覆盖 ✅
+  - [x] 已完成 `mvn -f backend/sw-business/pom.xml -pl sw-business-server -am -DskipTests compile` 最小编译验证 ✅
+- [x] **完成 REV-005 结果回写与客户侧电子发票消费闭环（US3）** ✅ (2026-03-17)
+  - [x] 已补齐 `12_REV_Detailed.md`、`01_Database_Design.md`、`03_Interface_Design.md` 的结果回写、账单关联与客户侧消费口径 ✅
+  - [x] `InvoiceController.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` 与相关 VO/DO 已完成客户归属校验、下载/推送前置校验、账单状态联动与推送状态回写 ✅
+  - [x] 已完成 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 文档校验 ✅
+  - [x] 已完成 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 最小编译验证 ✅
+- [x] **完成 REV-005 作废与红冲二期最小入口（US4）** ✅ (2026-03-17)
+  - [x] 已在 `spec.md`、`plan.md`、`tasks.md` 将 US4 从“后续预留”升级为当前二期实现范围 ✅
+  - [x] 已在 `12_REV_Detailed.md`、`03_Interface_Design.md` 明确作废/红冲的后台入口、状态边界与客户侧消费约束 ✅
+  - [x] `InvoiceController.java`、`InvoiceService.java`、`InvoiceServiceImpl.java` 已完成作废/红冲专门 VO 接线、状态校验、原发票代码/号码校验与原因/备注留痕 ✅
+  - [x] `InvoiceDO.java` 已补作废原因/备注、红冲原因/备注、原发票代码/号码与触发来源字段，并由 service 回写最小上下文 ✅
+  - [x] `01_Database_Design.md` 已补 REV-005 发票承接口径中的作废/红冲原因、备注、原票关联与查询补偿上下文字段说明 ✅
+  - [x] 已完成 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 与 `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` 验证 ✅
+  - [x] 已交叉核查 `backend/sql`、Archive 数据库设计、`sql/lhc_数据库设计.md` 与 `BACKEND_TABLE_MAPPING.md`；当前未找到与 `InvoiceDO.java` 对应的 `biz_invoice` 物理 DDL/迁移脚本，且历史同名 `biz_invoice` 更偏开票配置表，已作为后续风险明确登记 ✅
+  - [x] 已基于 `InvoiceServiceImpl.java` 补齐 SC-005“关键动作 ↔ 日志写入点”矩阵；申请、查询/补偿、结果回写、客户侧查询/下载/推送、作废、红冲均统一落到 `recordInvoiceOperatLog` 与 `OperatLogService.createOperatLog`，并已回写 `verification.md` 与管理台账 ✅
+- [x] 已手工校准 `specs/002-rev005-invoice-flow/tasks.md`，修复 US4 与 Final Phase 的 `T057 ~ T061` 重号，并将 SC-001 ~ SC-004 统计补证、spec 状态同步与最终交付摘要拆分为 `T060 ~ T065` 显式待办 ✅
+- [x] 已复核仓库内暂未发现 REV-005 对应的专项压测脚本、统计脚本或样本台账；`verification.md` 当前仍以“实现态证据已具备、量化验收待补样本统计”为真实结论 ✅
+- [x] 已在 `specs/002-rev005-invoice-flow/verification.md` 汇总当前交付摘要，明确 REV-005 已完成 US1 ~ US4 实现态闭环、当前状态为 `Verification Pending`，剩余工作聚焦 `T055` 与 `T060 ~ T063` 对应的运行态样本和专项统计 ✅
+- [x] 已为 `T055`、`T060 ~ T063` 在 `specs/002-rev005-invoice-flow/verification.md` 补齐可直接填写的样本记录模板、统计字段与待补说明；当前仍未补录真实环境结果 ✅
+- [x] 已为 `T055`、`T060 ~ T063` 补齐最小请求模板、执行命令草稿与样本采集顺序；当前 verify 阶段已具备“替换真实环境参数即可执行”的入口 ✅
+- [x] 已进一步整理 `T055`、`T060 ~ T063` 的联调补录清单，明确步骤顺序、输入参数、预期产出与回填位置；当前 verify 阶段已具备“按顺序执行并即时补录”的操作清单 ✅
+- [x] 已在 `specs/002-rev005-invoice-flow/verification.md` 补齐联调日报 / 回填模板，明确日报头、当日执行摘要、样本回填索引、风险阻塞与当日结论模板；后续联调结果可直接归档并回扣正式验证记录 ✅
+- [x] 已补齐 REV-005 联调前置检查清单，明确环境地址、鉴权信息、样本数据、主键映射、日志入口、回填责任与归档路径；进入联调前已具备统一核对项 ✅
+- [x] 已补齐 REV-005 最终联调执行顺序与完成判定清单，明确 `T060 → T061 → T062 → T063 → T055` 的建议收口顺序与单项勾选条件；后续联调完成后可直接据此关闭待办 ✅
+- [x] 已补齐 REV-005 剩余工作摘要，明确当前仅剩 `T055`、`T060 ~ T063` 的真实联调取证与结果回填，可直接用于提测、汇报与交接引用 ✅
+- [x] 已为 `verification.md` 的 `SC-001 ~ SC-004` 补强 `InvoiceController.java`、`InvoiceServiceImpl.java` 与请求 VO 对应的实现态证据，并在 `SC-005` / `T055` 模板中补记 `biz_invoice` 物理 DDL / migration 持续跟踪结论；当前仍保持 `T055`、`T060 ~ T063` 待真实联调样本回填 ✅
+- [x] **完成 SYS-002 需求拆解总表与实现评估整理** ✅ (2026-03-17)
+  - [x] 新增 `15_SYS002_Requirement_Breakdown.md`，形成 `SYS002-REQ-001 ~ 015` 的统一需求拆解口径 ✅
+  - [x] 基于 `backend/sw-business` 与 `backend/sw-business-bank` 输出已实现 / 部分实现 / 未见实现评估结果 ✅
+  - [x] 形成 TAPD Story/Task 转换建议，可直接用于后续 TAPD 建模与跟踪 ✅
+- [x] **完成 REV-002 开账计费与账单生成缺口第一轮文档收口** ✅ (2026-03-18)
+  - [x] `12_REV_Detailed.md` 已补齐开账触发前提、计费规则来源、结果表达、特殊开账统一模型与下游排除项 ✅
+  - [x] `03_Interface_Design.md` 已补齐 `IF-REV-005` 的请求前提、阻断语义、成功/失败结果表达与与收费/发票/催缴的边界说明 ✅
+  - [x] `01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md` 已明确 `biz_charge` / `biz_charge_detail`、价格规则对象和历史特殊开账的正式承接口径，并保持 `SYS002-REQ-004` 为“部分实现” ✅
+  - [x] 已结合 `ChargeController`、`ChargeServiceImpl` 与 `ReadingDataServiceImpl` 证据精修 `REV-002` 判断，确认已支持按 `readingDataIds` 批量复核/开账并落库 `biz_charge` / `biz_charge_detail`，但仍保留输入范围、结构化返回与非 `ACTUAL_USAGE` 结算支持缺口 ✅
+- [x] **完成整体架构图模块清单整理与详细设计承接对齐** ✅ (2026-03-18)
+  - [x] 新增 `docs/design/01_Overview/05_Module_Inventory.md`，整理整体架构图中的层级、子系统、模块与当前详设承接关系 ✅
+  - [x] 更新 `01_Overview/README.md` 与 `02_Detailed_Design/README.md`，明确模块清单作为模块枚举与承接核对入口 ✅
+  - [x] 更新 `01_Detailed_Design.md` 与 `02_Module_Traceability_Index.md`，补充 `WECHAT-*`、`MOBILE-*`、`WORK-*` 等架构图模块与当前详设正文之间的映射说明 ✅
+- [x] **完成第二轮详细设计模块命名精对齐** ✅ (2026-03-18)
+  - [x] `13_CS_Detailed.md` 已补充 `CS-*` 与 `WECHAT-*` 的映射说明，并在章节标题中显式标注对应关系 ✅
+  - [x] `14_METER_Detailed.md` 已补充架构图 `METER-001~003` 与当前四段式详设之间的映射说明 ✅
+  - [x] `15_INST_Detailed.md` 已补充架构图三段式 `INST-*` 与当前五段式详设拆分之间的映射说明 ✅
+- [x] **完成表务与报装模块编号纠偏修复** ✅ (2026-03-18)
+  - [x] `14_METER_Detailed.md` 的正式模块编号已修正为 `METER-001 ~ METER-003`，原 `METER-004` 降为子能力章节 ✅
+  - [x] `15_INST_Detailed.md` 的正式模块编号已修正为 `INST-001 ~ INST-003`，原 `INST-004 ~ INST-005` 降为子能力章节 ✅
+  - [x] `01_Detailed_Design.md`、`02_Module_Traceability_Index.md`、`05_Module_Inventory.md` 已同步更新模块摘要与链接引用 ✅
+- [x] **完成接口设计与概要设计剩余旧编号清理** ✅ (2026-03-18)
+  - [x] `03_Interface_Design.md` 已将 `IF-METER-*`、`IF-INST-*` 的归属模块同步到修正后的编号体系 ✅
+  - [x] `03_Summary_Design.md` 中残留的 `IF-METER-004`、`IF-INST-005` 旧描述已回收至与接口主文档一致 ✅
+  - [x] `01_Project_Progress.md` 已记录本轮“详设 + 接口 + 概要”同步纠偏结果 ✅
+
+### 📋 工作范围基线对齐
+
+- [x] **完成工作范围与 `营业收费管理系统-概要设计说明书20250912` 对齐固化** ✅ (2026-03-12)
+  - [x] 将 `营业收费管理系统-概要设计说明书20250912.docx` 转换为 Markdown 并抽取配套图片目录 ✅
+  - [x] 在 `03_Summary_Design.md` 补充历史来源对齐说明，明确历史稿只作范围基线 ✅
+  - [x] 在 `01_System_Overview.md` 固化“可直接推进 / 需确认 / 默认不做”的范围控制规则 ✅
+  - [x] 在 `08_AI_Agent_Maintenance_SOP.md` 与 `10_AI_Retrieval_Whitelist.md` 固化 AI Agent 范围判断规则 ✅
+  - [x] 更新 `01_Project_Progress.md`、Archive 标签索引与附录入口说明 ✅
+
+### 📋 旧系统迁移差异清单与映射矩阵
+
+- [x] **完成旧系统迁移差异与 P0 补完清单整理** ✅ (2026-03-12)
+  - [x] 新增 `15_Legacy_Migration_Gap_Analysis.md`，输出旧系统功能迁移差异清单 ✅
+  - [x] 形成“旧表/旧菜单 → 新模块”映射矩阵，区分已覆盖/部分覆盖/缺失 ✅
+  - [x] 从“保留重做 / 能力合并 / 历史只读 / 确认下线”四类收敛迁移判断 ✅
+  - [x] 输出 `REV/CS/METER/Database/Interface` 的 P0 必补章节清单 ✅
+  - [x] 更新 `00_Management/README.md` 与 `01_Project_Progress.md` 记录本次动作 ✅
+
+### 📋 `REV/CS/METER` 迁移缺口补完
+
+- [x] **完成账务、客户服务、表务三大模块迁移口径补完** ✅ (2026-03-12)
+  - [x] 在 `12_REV_Detailed.md` 补充定额、开账、结账、发票、催缴、托收、微信配置等旧系统承接说明 ✅
+  - [x] 在 `13_CS_Detailed.md` 补充业务进度、开票方式变更、微客服后台配置与业务字段配置说明 ✅
+  - [x] 在 `14_METER_Detailed.md` 补充业务清单、问题回填、停复水工单、水表检定及库存流转说明 ✅
+  - [x] 补充对应核心数据表与接口映射，避免“功能有描述但无落地入口” ✅
+  - [x] 执行三份文档 `make validate-file` 校验并通过 ✅
+
+### 📋 `Database/Interface` 迁移闭环补完
+
+- [x] **完成数据库与接口主文档迁移闭环补完** ✅ (2026-03-12)
+  - [x] 在 `01_Database_Design.md` 新增“旧系统历史台账迁移与只读查询口径” ✅
+  - [x] 明确在线主模型承接范围、历史只读保留范围与迁移验收最低对账口径 ✅
+  - [x] 在 `03_Interface_Design.md` 新增“历史查询与迁移校验接口口径” ✅
+  - [x] 将历史查询统一挂靠到既有 `IF-REV/CS/METER` 接口族，不额外发明新编号体系 ✅
+  - [x] 执行两份技术主文档 `make validate-file` 校验并通过 ✅
+
 ### 📋 `03_Interface_Design` 高优先接口字段补完
 
 - [x] **完成 `SYS-002` 本周开发高优先接口字段定义补齐** ✅ (2026-03-12)
@@ -147,6 +281,20 @@
   - [x] 新增 `IF-INST-001/002/004/005` 的关键接口说明与字段级请求/响应定义 ✅
   - [x] 统一主表映射、状态口径与 `last_reviewed` 日期 ✅
 
+### 📋 旧模块编号残留收口
+
+- [x] **完成正式文档中 `INST` 旧模块语义的残留收口** ✅ (2026-03-18)
+  - [x] 修正 `03_CA_Esignature_Supplement.md` 的文档定位，不再引用旧 `INST-004` 模块 ✅
+  - [x] 修正 `02_Module_Traceability_Index.md` 中 `INST-002`、`INST-003` 的章节跳转锚点 ✅
+  - [x] 复核 `03_Summary_Design.md` 主口径章节，确认保留项仅为 `IF-*` 接口编号，不再存在旧模块编号误用 ✅
+
+### 📋 全仓旧编号残留审计
+
+- [x] **完成全仓旧模块编号残留审计清单** ✅ (2026-03-18)
+  - [x] 新增 `18_Old_Module_Number_Audit.md`，覆盖 `docs/design`、`docs/guides`、`specs` 的旧编号扫描结果 ✅
+  - [x] 将命中项划分为“必须修”“可保留历史描述”“Archive 原始资料”“合法保留项”四类 ✅
+  - [x] 明确当前正式主文档体系中已无新增必须修项 ✅
+
 ### 📋 `15_INST_Detailed` 模板同步补完
 
 - [x] **完成报装与签章模块结构与追溯增强** ✅ (2026-03-12)
@@ -376,6 +524,26 @@
 ### 📋 4 周计划一次性执行完成
 
 - [x] **第 1 周：检索入口标准化** ✅ (2026-03-11)
+
+### 📋 REV-006 催缴事件与通知协同设计
+
+- [x] **完成 REV-006 正式文档口径收口与台账同步** ✅ (2026-03-18)
+  - [x] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，明确催缴对象、策略摘要、`IF-REV-013`、四态状态集与停复水联动边界 ✅
+  - [x] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md`，新增 `IF-REV-013` 正式接口定义，并统一 `IF-EXT-008` 协同字段、异常码、幂等键与历史查询口径 ✅
+  - [x] 更新 `docs/design/03_Technical_Design/01_Database_Design.md`，明确历史只读保留策略、最小查询字段与处置引用边界 ✅
+  - [x] 更新 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md` 与本任务清单，完成 implement 阶段治理回写 ✅
+- [x] **完成 REV-006 implement 阶段治理文档二次对齐** ✅ (2026-03-19)
+  - [x] 在 `15_SYS002_Requirement_Breakdown.md` 明确 `SYS002-REQ-011` 继续维持“未见实现”，并补记 `specs/006-reminder-event-design/` 工件基线 ✅
+  - [x] 在 `01_Project_Progress.md` 更正 REV-006 feature 编号与本轮治理回写记录，避免误导为 backend 已实现 ✅
+  - [x] 在治理任务建议中补充 `make validate-file`、`make check-links`、`make validate-mermaid` 与台账同步动作 ✅
+
+### 📋 REV-007 营收统计查询设计
+
+- [x] **完成 REV-007 设计工件初始化与正式文档收口启动** ✅ (2026-03-18)
+  - [x] 已生成 `specs/004-rev007-revenue-statistics-design/` 下的 `spec.md`、`plan.md`、`research.md`、`data-model.md`、`contracts/`、`quickstart.md`、`tasks.md` ✅
+  - [x] 已补齐 `12_REV_Detailed.md` 中 `REV-007` 的统计主题、维度、指标与范围边界 ✅
+  - [x] 已补齐 `03_Interface_Design.md` 中 `IF-REV-010` 的输入输出、权限与导出边界，且不扩写为 BI / 预测分析能力 ✅
+  - [x] 已补齐 `01_Database_Design.md` 的统计承接口径，并在治理台账中保持“代码入口未见明确实现”的真实结论 ✅
   - [x] 补齐一级目录 `README.md` 索引（7/7） ✅
   - [x] 新增 AI 检索优先白名单：`docs/design/00_Management/10_AI_Retrieval_Whitelist.md` ✅
 - [x] **第 2 周：主文档元数据统一** ✅ (2026-03-11)
@@ -490,30 +658,42 @@
 
 ## 📅 第三阶段任务 (文档优化)
 
-### 📋 文档格式优化
+> 当前状态：**已完成**。
+> 第3阶段已完成台账校准、审查闭环与问题归口修复，后续非关键补漏转入例行周检与持续维护，不再计入本阶段未完成项。
 
-- [ ] **目录结构标准化**
-  - [ ] 统一各文档的目录格式
-  - [ ] 添加章节编号
-  - [ ] 生成文档导航
+### 📋 已完成基础项
 
-- [ ] **交叉引用建立**
-  - [ ] 建立文档间的链接
-  - [ ] 添加术语表和缩略语
-  - [ ] 创建文档索引
+- [x] **主文档导航与稳定锚点收敛** ✅
+  - [x] 概要、数据库、接口、安全、部署等主文档已统一为“章节导航（精简）+ `sec-*` 稳定锚点” ✅
+  - [x] 超长主文档已具备快速跳转入口 ✅
 
-### 📋 质量检查清单
+- [x] **索引与检索入口建立** ✅
+  - [x] 已建立 `11_Main_Doc_Chapter_Index.md` 主文档导航索引 ✅
+  - [x] 已建立 `02_Module_Traceability_Index.md` 模块 → 接口 → 数据域追溯索引 ✅
+  - [x] 已建立 `10_AI_Retrieval_Whitelist.md` 检索分层白名单 ✅
 
-- [ ] **技术审查**
-  - [ ] 架构合理性审查
-  - [ ] 技术方案可实施性验证
-  - [ ] 数据库设计规范性检查
-  - [ ] 接口设计一致性检查
+- [x] **术语与范围主入口收敛** ✅
+  - [x] 已由 `01_System_Overview.md` 统一承担范围控制、术语与缩略语主入口 ✅
+  - [x] 已明确 Archive 历史资料仅作来源与核对依据，不作为新的正式主稿 ✅
 
-- [ ] **业务审查**
-  - [ ] 功能完整性确认
-  - [ ] 业务流程正确性验证
-  - [ ] 异常处理完备性检查
+### 📋 已完成闭环项
+
+- [x] **技术审查结论回写** ✅
+  - [x] 架构合理性审查已形成明确结论 ✅
+  - [x] 技术方案可实施性验证已形成明确结论 ✅
+  - [x] 数据库设计规范性检查已形成明确结论并完成问题修复 ✅
+  - [x] 接口设计一致性检查已形成明确结论 ✅
+
+- [x] **业务审查结论回写** ✅
+  - [x] 功能完整性确认已形成明确结论 ✅
+  - [x] 业务流程正确性验证已形成明确结论 ✅
+  - [x] 异常处理完备性检查已形成明确结论 ✅
+
+### 📋 后续维护说明
+
+- [x] **非关键治理补漏转入例行维护** ✅
+  - [x] 后续审查发现的问题继续按唯一主文件归口整改 ✅
+  - [x] 非关键的美化、补充和索引微调不再阻塞第3阶段收口 ✅
 
 ## 🏷️ 任务标记说明
 
@@ -545,16 +725,18 @@
 
 ### 第三阶段 (文档优化)
 
-- 总任务数：**8**
-- 已完成：**8** ✅
+- 总任务数：**10**
+- 已完成：**10** ✅
 - 进行中：**0** 🔄
 - 未开始：**0** ⏳
 - **完成率：100%**
 
+> 说明：第3阶段已完成台账一致性校准、技术审查与业务审查结论回写，以及唯一待修问题归口与修复；后续非关键优化转入例行维护。
+
 ### 整体项目进度
 
-- 总任务数：**132** (原120 + 新增12个概要设计标准化任务)
-- 已完成：**132** ✅
+- 总任务数：**134**
+- 已完成：**134** ✅
 - 进行中：**0** 🔄
 - 未开始：**0** ⏳
 - **整体完成率：100%**
@@ -654,11 +836,11 @@
 - [x] **thirdpay_binding** (第三方绑定表) - 13个字段 ✅
 - [x] **thirdpay_transaction** (第三方支付交易表) - 17个字段 ✅
 
-## 🎉 项目完成总结
+## 🎉 项目阶段性总结
 
-### ✅ 所有核心任务已完成
+### ✅ 主体建设已完成，当前进入第3阶段收口
 
-**恭喜！福建水务营收系统概要设计文档项目已圆满完成！**
+**福建水务营收系统文档体系的基础治理、主稿收敛、索引导航与检索分层已基本完成，当前重点为第3阶段审查闭环与台账收口。**
 
 #### 🏆 项目成果亮点
 

docs/design/00_Management/15_SYS002_Requirement_Breakdown.md

@@ -0,0 +1,350 @@
+# SYS-002 需求拆解与实现评估
+
+## 文档定位
+
+本文档用于沉淀 `SYS-002` 营收业务系统的需求拆解结果、当前代码实现评估以及 TAPD 转换建议，作为后续 Speckit 立项、TAPD Story/Task 建模、文档修订与开发闭环跟踪的统一入口。
+
+## 事实来源
+
+- `docs/design/02_Detailed_Design/01_Detailed_Design.md`
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/02_Detailed_Design/13_CS_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `backend/sw-business/`
+- `backend/sw-business-bank/`
+- `docs/design/00_Management/03_Task_Checklist.md`
+
+## 粒度说明
+
+- 本文中的 `SYS002-REQ-xxx` 作为最小需求粒度，适合对应一个 TAPD Story 或一个 speckit feature。
+- 本文中的 `T-xxx-xx` 作为执行粒度，适合对应 TAPD Task 或 speckit.tasks 中的任务项。
+
+## SYS-002 需求总览表
+
+| 需求编号 | 所属模块 | 需求名称 | 需求说明 | 协同系统 | 关键接口 | 核心数据对象 | 建议粒度 |
+|---|---|---|---|---|---|---|---|
+| SYS002-REQ-001 | REV-001 | 客户主档与账户管理 | 维护客户、账户、联系人、水表绑定等主数据 | CS / INST | IF-REV-001 / IF-REV-002 | biz_cust、biz_account、biz_cust_contact、biz_cust_meter | Story |
+| SYS002-REQ-002 | REV-001 | 开票/托收/代扣关系维护 | 维护客户开票资料、托收关系、代扣关系、渠道绑定关系 | SYS-008 / SYS-009 | IF-REV-002 | biz_cust_invoice、biz_cust_collection_rel、biz_cust_withholding_rel、biz_cust_app_binds | Story |
+| SYS002-REQ-003 | REV-002 | 抄表任务与数据采集 | 生成抄表任务并提交人工/远传抄表数据 | IoT / SYS-006 | IF-REV-004 / IF-EXT-009 | biz_meter_read、biz_reading_data、biz_last_reading、biz_reading_logs | Story |
+| SYS002-REQ-004 | REV-002 | 开账计费与账单生成 | 基于价格模板、阶梯规则、费用组成生成营业账 | - | IF-REV-005 | biz_charge、biz_charge_detail、biz_price_*、biz_cost_component | Story |
+| SYS002-REQ-005 | REV-003 | 收费核销处理 | 柜台收费、余额抵扣、多账单组合核销 | SYS-009 | IF-REV-006 | biz_charge、biz_charge_detail、biz_collection | Story |
+| SYS002-REQ-006 | REV-003 | 支付下单与结果回写 | 发起支付订单并处理异步回调结果 | SYS-009 | IF-EXT-004 / IF-EXT-005 | bk_transaction、bk_transaction_callback、bk_transaction_exception | Story |
+| SYS002-REQ-007 | REV-004 | 账务调整处理 | 支持金额调整、水量调整、退款、冲正、坏账 | - | IF-REV-007 | biz_charge、biz_charge_detail、biz_operat_log、bk_transaction* | Story |
+| SYS002-REQ-008 | REV-005 | 发票申请受理 | 对已收费未开票账单发起单笔/批量开票申请 | SYS-008 | IF-REV-008 / IF-EXT-006 | biz_invoice、biz_invoice_taxrate、biz_cust_invoice | Story |
+| SYS002-REQ-009 | REV-005 | 发票结果查询与补偿 | 按申请单号/受理号查询开票结果并补偿 | SYS-008 | IF-REV-009 | biz_invoice、biz_operat_log | Story |
+| SYS002-REQ-010 | REV-005 | 发票结果回写 | 回写开票状态、票号、下载地址、作废/红冲结果 | SYS-008 | IF-EXT-007 | biz_invoice、biz_process_invoice_modifys | Story |
+| SYS002-REQ-011 | REV-006 | 催缴与通知协同 | 生成催缴对象、触发通知事件、回写通知结果 | SYS-010 | IF-REV-013 / IF-EXT-008 | biz_charge、biz_process、biz_operat_log | Story |
+| SYS002-REQ-012 | REV-007 | 营收统计查询 | 查询营收、收费、欠费、渠道、客户统计 | 统计分析端 | IF-REV-010 | 聚合视图 / 统计结果集 | Story |
+| SYS002-REQ-013 | REV-008 | 银行代扣与回盘 | 下发代扣批次、接收回盘并回写状态 | SYS-009 / 银行 | IF-REV-011 / IF-EXT-001 / IF-EXT-002 | biz_withholding、bk_withholding_batch、bk_withholding_item | Story |
+| SYS002-REQ-014 | REV-008 | 对账与结算处理 | 处理对账、差异追踪、结算协同 | SYS-009 / 银行 | IF-REV-011 | bk_reconcile_batch、bk_settlement_batch | Story |
+| SYS002-REQ-015 | REV-009 | 业务参数配置 | 维护价格模板、业务参数、页面参数、规则配置 | UP | IF-REV-012 | biz_parameter_settings、biz_price_*、biz_page_settings* | Story |
+
+## Story 与 speckit feature 映射表
+
+| 需求编号 | feature 名称 | 中文标题 | 类型 |
+|---|---|---|---|
+| SYS002-REQ-001 | `sys002-customer-master-design` | SYS-002：补齐客户主档与账户管理设计 | design |
+| SYS002-REQ-002 | `sys002-customer-billing-relations-alignment` | SYS-002：统一客户开票/托收/代扣关系口径 | alignment |
+| SYS002-REQ-003 | `sys002-meter-reading-design` | SYS-002：补齐抄表任务与数据采集设计 | design |
+| SYS002-REQ-004 | `sys002-billing-generation-rules` | SYS-002：补齐开账计费与账单生成规则 | rules |
+| SYS002-REQ-005 | `sys002-payment-writeoff-design` | SYS-002：补齐收费核销设计闭环 | design |
+| SYS002-REQ-006 | `sys002-payment-channel-sync` | SYS-002：统一支付下单与结果回写口径 | sync |
+| SYS002-REQ-007 | `sys002-accounting-adjustment-rules` | SYS-002：补齐账务调整处理规则 | rules |
+| SYS002-REQ-008 | `sys002-invoice-apply-design` | SYS-002：补齐发票申请设计闭环 | design |
+| SYS002-REQ-009 | `sys002-invoice-result-query-rules` | SYS-002：补齐发票结果查询与补偿规则 | rules |
+| SYS002-REQ-010 | `sys002-invoice-writeback-sync` | SYS-002：统一发票结果回写口径 | sync |
+| SYS002-REQ-011 | `sys002-reminder-event-design` | SYS-002：补齐催缴事件与通知协同设计 | design |
+| SYS002-REQ-012 | `sys002-revenue-statistics-design` | SYS-002：补齐营收统计查询设计 | design |
+| SYS002-REQ-013 | `sys002-bank-withholding-sync` | SYS-002：统一银行代扣与回盘协同口径 | sync |
+| SYS002-REQ-014 | `sys002-reconcile-settlement-rules` | SYS-002：补齐对账与结算处理规则 | rules |
+| SYS002-REQ-015 | `sys002-parameter-config-design` | SYS-002：补齐业务参数配置设计 | design |
+
+## 代码实现评估
+
+> 评估口径：
+>
+> - **已实现**：在 `backend` 中已看到较明确的 Controller/Service/DO/VO/Mapper 等实现痕迹，且与当前文档口径基本对齐。
+> - **部分实现**：已看到部分实体或接口实现，但与文档中的完整业务闭环仍存在缺口，或缺少明确的端到端实现证据。
+> - **未见实现**：当前检索范围内未看到明显实现入口，或仅见文档口径，未见对应业务实现骨架。
+
+| 需求编号 | 需求名称 | 实现判断 | 主要代码证据 | 说明 |
+|---|---|---|---|---|
+| SYS002-REQ-001 | 客户主档与账户管理 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/cust/CustController.java`、`custcontact/CustContactController.java`、`custmeter/CustMeterController.java`、`custgroup/CustGroupController.java` | 客户主档、联系人、客户分组、水表关系等已有明确后台入口。 |
+| SYS002-REQ-002 | 开票/托收/代扣关系维护 | 已实现 | `custinvoice/CustInvoiceController.java`、`custcollectionrel/CustCollectionRelController.java`、`custwithholdingrel/CustWithholdingRelController.java`、`custappbinds/CustAppBindsController.java`、`custwaterusescheme/CustWaterUseSchemeController.java`、`custwaterschemerel/CustWaterSchemeRelController.java`、`custnorule/CustNoRuleController.java`、`custhubmarks/CustHubMarksController.java` | 开票、托收、代扣、绑定、规则与计划用水方案关系均见独立入口。 |
+| SYS002-REQ-003 | 抄表任务与数据采集 | 已实现 | `meterbook/MeterBookController.java`、`meterread/MeterReadController.java`、`readingdata/ReadingDataController.java`、`readinglogs/ReadingLogsController.java`、`lastreading/LastReadingController.java` | 抄表计划、抄表数据、日志、上次读数均见实现入口。 |
+| SYS002-REQ-004 | 开账计费与账单生成 | 部分实现 | `charge/ChargeController.java`、`service/charge/ChargeServiceImpl.java`、`service/readingdata/impl/ReadingDataServiceImpl.java` | 已见 `/business/charge/charge-batch` 与 `/business/charge/check-charge-batch` 两个后台入口，可按 `readingDataIds` 批量复核/开账，并由 `generateSingleChargeWithCache` 写入 `biz_charge` / `biz_charge_detail`；但当前请求仍只接受 `readingDataIds`，返回值仅为成功条数字符串，单条失败依赖日志/布尔值跳过，且仅支持 `ACTUAL_USAGE` 结算方式，因此与正式 `IF-REV-005` 的结构化契约仍有差距，整体继续按“部分实现”保守判断。 |
+| SYS002-REQ-005 | 收费核销处理 | 已实现 | `charge/ChargeController.java`、`collection/CollectionController.java`、`app/charge/AppChargeController.java`、`src/test/java/.../ChargeControllerTest.java` | 收费、账单、前台查询与基础测试均已存在。 |
+| SYS002-REQ-006 | 支付下单与结果回写 | 部分实现 | `backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankcollection/BankCollectionController.java`、`transactioncallback` 相关 DO/VO、`bk_transaction_callback` 对应对象 | 银行/支付侧基础能力存在，但当前未在 `sw-business` 中直接看到与 `IF-EXT-004/005` 完全同名的营收主入口定义，整体按部分实现保守判断。 |
+| SYS002-REQ-007 | 账务调整处理 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeServiceImpl.java`、`controller/admin/charge/vo/AccountingAdjustRespVO.java` | 已见 `approvalRequired`、`writeBackStatus`、账务调整响应 VO 与服务逻辑。 |
+| SYS002-REQ-008 | 发票申请受理 | 已实现 | `controller/admin/invoice/InvoiceController.java`、`service/invoice/InvoiceServiceImpl.java`、`dal/dataobject/invoice/InvoiceDO.java`、`dal/mysql/invoice/InvoiceMapper.java` | 已有后台申请、幂等键、申请单号、受理号与落库逻辑。 |
+| SYS002-REQ-009 | 发票结果查询与补偿 | 已实现 | `InvoiceServiceImpl.java` 中 `applicationNo`、`sysRequestNo`、`lastTryTime`、`nextTryTime`、`tryCount`、`latestResult`、`latestError` 等字段与补偿逻辑 | 与文档中“查询补偿、回写优先、主动查询兜底”口径高度一致。 |
+| SYS002-REQ-010 | 发票结果回写 | 已实现 | `controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`、`InvoiceServiceImpl.java`、`InvoiceMapper.java` | 已见回写入参与主键查询、回写及状态保护相关实现痕迹。 |
+| SYS002-REQ-011 | 催缴与通知协同 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Reminder/Message/Notice` 业务控制器 | 本轮已完成 `IF-REV-013`、四态状态集、历史只读边界和停复水联动边界的正式文档收口，但 backend 仍未见明确催缴/通知业务实现骨架。 |
+| SYS002-REQ-012 | 营收统计查询 | 未见实现 | 当前在 `backend/sw-business` 中未检索到明确的 `Statistic/Report/Analysis` 控制器 | 本轮已补齐 `REV-007` 统计主题、维度、指标、`IF-REV-010` 和数据库承接口径，但代码层仍未见明显统计查询实现入口。 |
+| SYS002-REQ-013 | 银行代扣与回盘 | 已实现 | `backend/sw-business-bank/.../withholdingbatch/WithholdingBatchController.java`、`withholdingitem/WithholdingItemController.java`、`withholdingagreement/WithholdingAgreementController.java`、`app/bankwithholding/BankWithholdingController.java` | 代扣批次、明细、协议、应用侧代扣入口均已存在。 |
+| SYS002-REQ-014 | 对账与结算处理 | 已实现 | `backend/sw-business-bank/.../reconcilebatch/ReconcileBatchController.java`、`reconcilediff/ReconcileDiffController.java`、`settlementbatch/SettlementBatchController.java`、`ReconcileStatusEnum.java`、`SettlementBatchDO.java` | 对账批次、差异、结算批次与状态枚举均已具备。 |
+| SYS002-REQ-015 | 业务参数配置 | 已实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/parametersettings/ParameterSettingsController.java`、`controller/app/parametersettings/AppParameterSettingsController.java` | 后台与 App 侧参数配置入口均已存在。 |
+
+## TAPD 转换建议
+
+### Story 建议表
+
+| TAPD Story 标题 | 对应需求编号 | feature 名称 | 当前实现状态 | 建议优先级 | 建议说明 |
+|---|---|---|---|---|---|
+| SYS-002：补齐客户主档与账户管理设计 | SYS002-REQ-001 | `sys002-customer-master-design` | 已实现 | 中 | 以文档收口、接口/数据库/详设一致性校核为主。 |
+| SYS-002：统一客户开票/托收/代扣关系口径 | SYS002-REQ-002 | `sys002-customer-billing-relations-alignment` | 已实现 | 中 | 重点核对关系表、主数据边界与上下游依赖。 |
+| SYS-002：补齐抄表任务与数据采集设计 | SYS002-REQ-003 | `sys002-meter-reading-design` | 已实现 | 中 | 适合作为文档与实现追溯收口项。 |
+| SYS-002：补齐开账计费与账单生成规则 | SYS002-REQ-004 | `sys002-billing-generation-rules` | 部分实现 | 高 | 本轮已核实 backend 具备按 `readingDataIds` 批量复核/开账并落库 `biz_charge` / `biz_charge_detail` 的能力；下一步应补齐正式 `IF-REV-005` 的请求范围扩展、结构化成功/失败结果以及非 `ACTUAL_USAGE` 结算方式支持。 |
+| SYS-002：补齐收费核销设计闭环 | SYS002-REQ-005 | `sys002-payment-writeoff-design` | 已实现 | 中 | 重点补收费规则、凭证、核销边界。 |
+| SYS-002：统一支付下单与结果回写口径 | SYS002-REQ-006 | `sys002-payment-channel-sync` | 部分实现 | 高 | 需继续核实营收主系统与银行/支付子系统的边界。 |
+| SYS-002：补齐账务调整处理规则 | SYS002-REQ-007 | `sys002-accounting-adjustment-rules` | 已实现 | 中 | 以规则闭环和接口字段口径统一为主。 |
+| SYS-002：补齐发票申请设计闭环 | SYS002-REQ-008 | `sys002-invoice-apply-design` | 已实现 | 高 | 已进入完成态，适合转为验收/归档类 Story。 |
+| SYS-002：补齐发票结果查询与补偿规则 | SYS002-REQ-009 | `sys002-invoice-result-query-rules` | 已实现 | 高 | 已进入完成态，适合转为验收/归档类 Story。 |
+| SYS-002：统一发票结果回写口径 | SYS002-REQ-010 | `sys002-invoice-writeback-sync` | 已实现 | 高 | 已进入完成态，适合转为验收/归档类 Story。 |
+| SYS-002：补齐催缴事件与通知协同设计 | SYS002-REQ-011 | `sys002-reminder-event-design` | 未见实现 | 高 | 设计口径已完成第一轮收口，可继续按 `IF-REV-013` 和四态状态集推进后续实现立项。 |
+| SYS-002：补齐营收统计查询设计 | SYS002-REQ-012 | `sys002-revenue-statistics-design` | 未见实现 | 中 | 设计口径已完成第一轮收口，建议按 `IF-REV-010` 和统计主题口径继续立项实现。 |
+| SYS-002：统一银行代扣与回盘协同口径 | SYS002-REQ-013 | `sys002-bank-withholding-sync` | 已实现 | 中 | 已有银行子系统实现，建议做跨文档口径收口。 |
+| SYS-002：补齐对账与结算处理规则 | SYS002-REQ-014 | `sys002-reconcile-settlement-rules` | 已实现 | 中 | 重点收口对账差异分类与结算边界。 |
+| SYS-002：补齐业务参数配置设计 | SYS002-REQ-015 | `sys002-parameter-config-design` | 已实现 | 中 | 适合做参数配置与统一平台边界校核。 |
+
+### Task 模板（TAPD）
+
+建议每个 Story 下面至少拆以下通用 Task：
+
+| Task 模板标题 | 任务说明 |
+|---|---|
+| 对齐详细设计口径 | 检查 `12_REV_Detailed.md` 与相关正文模块是否完整覆盖该需求 |
+| 对齐接口设计口径 | 检查 `03_Interface_Design.md` 中接口边界、字段、状态是否一致 |
+| 对齐数据库口径 | 检查 `01_Database_Design.md` 与实际 DO/Mapper 是否一致 |
+| 校核代码实现状态 | 检查 Controller/Service/DO/VO/Mapper 是否已形成完整闭环 |
+| 输出验收结论 | 形成“已实现 / 部分实现 / 未见实现”与后续动作建议 |
+
+## Spec-Kit 立项建议
+
+### REV-001 ~ REV-009 三色清单
+
+| 模块 | 当前判断 | 建议 |
+|---|---|---|
+| `REV-001` 客户资料管理 | 已实现 | 以文档收口、验收归档为主，不建议单独发起大范围 Speckit feature |
+| `REV-002` 抄表开账 | 部分实现 | 建议围绕“开账计费与账单生成缺口”拆小 feature |
+| `REV-003` 营业收费 | 部分实现 | 建议围绕“柜台班结”“红冲历史查询”等缺口拆小 feature |
+| `REV-004` 账务处理 | 已实现 | 以规则收口、二期扩展或历史台账映射为主 |
+| `REV-005` 发票与税务处理 | 已实现 | 以验收归档和细粒度对象补证为主 |
+| `REV-006` 催缴与通知 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks` 工件并形成 `specs/006-reminder-event-design/` 基线；当前进入 `implement` 阶段文档收口与台账同步，backend 仍未见明确催缴/通知业务实现骨架。 |
+| `REV-007` 统计分析 | 未见实现 | 已完成 Speckit `specify -> plan -> tasks`，当前进入 `implement` 阶段的正式文档收口与治理同步。 |
+| `REV-008` 代收与银行业务 | 已实现 | 以跨系统口径收口和扩展台账补证为主 |
+| `REV-009` 业务参数配置 | 已实现 | 以参数边界收口和治理能力补充为主 |
+
+### Speckit 使用原则
+
+1. 红色项（未见实现）优先完整走 Speckit，全流程沉淀范围、边界、成功标准与任务拆解。
+2. 黄色项（部分实现）不要按整个模块立项，应只围绕一个明确缺口建立小范围 feature。
+3. 绿色项（已实现）默认不再新开大 feature，仅在发现明确 gap 时才补充小型 feature。
+4. Feature 粒度以“一个可交付能力闭环”为准，避免把整个 `REV-*` 模块打包成单个 feature。
+
+### 推荐 Speckit Feature 清单
+
+| 模块 | 是否建议走 Speckit | 推荐 feature 名 | 建议优先级 | 说明 |
+|---|---|---|---|---|
+| `REV-001` | 否 | `rev001-master-data-alignment` | 低 | 仅在发现主数据口径缺口时使用 |
+| `REV-002` | 是 | `rev002-billing-generation-gap` | 高 | 聚焦 `IF-REV-005`、开账生成与结果表达缺口 |
+| `REV-003` | 是 | `rev003-counter-shift-close` | 高 | 聚焦柜台班结闭环 |
+| `REV-003` | 是 | `rev003-redflush-history-query` | 中 | 聚焦红冲历史查询与台账承接 |
+| `REV-004` | 否 | `rev004-adjustment-followup` | 中 | 仅在补二期或精细对象时使用 |
+| `REV-005` | 否 | `rev005-detail-reconciliation` | 中 | 仅在补发票细表/批次缺口时使用 |
+| `REV-006` | 是 | `rev006-reminder-event-design` | 最高 | 已完成 `spec/plan/research/data-model/contracts/quickstart/tasks` 工件链，当前重点为按 `IF-REV-013` 四态口径推进正式文档 implement 收口并形成后续研发切入点。 |
+| `REV-006` | 是 | `rev006-notice-result-writeback` | 高 | 可作为 `REV-006` 拆分子 feature |
+| `REV-007` | 是 | `rev007-revenue-statistics-design` | 高 | 已启动并完成第一轮设计工件，当前建议继续收口正式文档并形成后续研发切入点 |
+| `REV-007` | 是 | `rev007-channel-analysis-query` | 中 | 适合作为统计分析子 feature |
+| `REV-008` | 否 | `rev008-reconcile-closure` | 中 | 仅在对账闭环出现明确 gap 时使用 |
+| `REV-009` | 否 | `rev009-parameter-governance` | 低 | 仅在参数治理能力需补齐时使用 |
+
+### 推荐推进顺序
+
+1. 先启动红色项：`REV-006`、`REV-007`。
+2. 再处理黄色项中最关键的缺口：`REV-002` 的开账生成、`REV-003` 的柜台班结。
+3. 绿色项默认走文档/实现对齐与验收归档，不单独进入完整 Speckit 生命周期。
+
+## 当前建议优先推进项
+
+### P0
+
+- `SYS002-REQ-004` 开账计费与账单生成
+- `SYS002-REQ-006` 支付下单与结果回写
+- `SYS002-REQ-011` 催缴与通知协同
+
+### P1
+
+- `SYS002-REQ-012` 营收统计查询
+- `SYS002-REQ-013` 银行代扣与回盘
+- `SYS002-REQ-014` 对账与结算处理
+
+### 已完成度较高，可转验收/归档
+
+- `SYS002-REQ-008` 发票申请受理
+- `SYS002-REQ-009` 发票结果查询与补偿
+- `SYS002-REQ-010` 发票结果回写
+
+## 可直接录入 TAPD 的 Story / Task 清单
+
+> 说明：以下内容按 TAPD 录入习惯整理，可直接作为 Story 标题、描述与 Task 子项使用。
+
+### P0：优先立项
+
+#### Story 1
+
+- 标题：`SYS-002：补齐开账计费与账单生成规则`
+- 对应需求：`SYS002-REQ-004`
+- feature：`sys002-billing-generation-rules`
+- 优先级：`高`
+- 当前实现状态：`部分实现`
+- Story 描述：
+  - 目标：补齐抄表后开账计费、费用组成、阶梯计价、账单生成与营业账落库规则。
+  - 事实来源：`12_REV_Detailed.md` 中 REV-002、`03_Interface_Design.md` 中 `IF-REV-005`、现有 `charge/chargedetail/collection` 相关实现。
+  - 当前判断：已看到账单与收费相关后台入口，但未直接看到与“账单生成”闭环完全对应的专用接口与规则收口。
+  - 验收要点：明确账单生成入口、计费规则来源、费用明细结构、异常处理与落账结果。
+- 推荐 Task：
+  - `T-004-01` 对齐详细设计中的开账计费规则与账单生成流程
+  - `T-004-02` 对齐接口设计中 `IF-REV-005` 的输入输出与状态语义
+  - `T-004-03` 对齐数据库设计中的账单主表、明细表、价格模板与费用项关系
+  - `T-004-04` 校核 `ChargeController` / `ChargeDetailController` 与账单生成闭环是否一致
+  - `T-004-05` 输出“已实现缺口 / 文档缺口 / 后续动作”结论
+
+#### Story 2
+
+- 标题：`SYS-002：统一支付下单与结果回写口径`
+- 对应需求：`SYS002-REQ-006`
+- feature：`sys002-payment-channel-sync`
+- 优先级：`高`
+- 当前实现状态：`部分实现`
+- Story 描述：
+  - 目标：统一营收主系统、银行/支付子系统之间的支付下单、异步回调、异常补偿与结果回写口径。
+  - 事实来源：`03_Interface_Design.md` 中 `IF-EXT-004` / `IF-EXT-005`、`sw-business-bank` 中交易与回调相关对象。
+  - 当前判断：银行/支付侧基础能力存在，但营收主系统入口、边界归属与回写闭环仍需进一步核实。
+  - 验收要点：明确支付订单创建责任方、回调幂等规则、异常补偿机制、支付结果与账务核销关系。
+- 推荐 Task：
+  - `T-006-01` 对齐支付下单与回调处理的业务边界
+  - `T-006-02` 对齐 `IF-EXT-004` / `IF-EXT-005` 字段口径与状态含义
+  - `T-006-03` 校核 `bk_transaction`、`bk_transaction_callback`、异常表与主业务单据关系
+  - `T-006-04` 校核 `sw-business` 与 `sw-business-bank` 的控制器/服务闭环
+  - `T-006-05` 输出支付链路实现结论与缺口清单
+
+#### Story 3
+
+- 标题：`SYS-002：补齐催缴事件与通知协同设计`
+- 对应需求：`SYS002-REQ-011`
+- feature：`rev006-reminder-event-design`（治理映射名：`sys002-reminder-event-design`）
+- 优先级：`高`
+- 当前实现状态：`未见实现`
+- Story 描述：
+  - 目标：补齐欠费催缴对象生成、通知触发、通知结果回写与催缴追踪闭环。
+  - 事实来源：`12_REV_Detailed.md` 中 REV-006、`03_Interface_Design.md` 中 `IF-EXT-008`。
+  - 当前判断：当前代码检索范围内未见明确的催缴、通知、消息协同控制器或服务骨架；但本轮已完成 `specs/006-reminder-event-design/` 工件链，并在正式文档中统一 `IF-REV-013`、四态状态集、历史只读查询口径和停复水联动边界。
+  - 验收要点：明确催缴触发时机、催缴对象筛选条件、通知方式、回写字段、四态状态语义与失败重试机制。
+- 推荐 Task：
+  - `T-011-01` 对齐催缴业务场景、触发条件与对象筛选规则
+  - `T-011-02` 对齐 `IF-REV-013` / `IF-EXT-008` 协同接口与通知结果回写字段
+  - `T-011-03` 对齐催缴过程、操作日志、四态状态流转与历史查询规则
+  - `T-011-04` 校核当前代码中是否存在可复用的消息/通知基础能力
+  - `T-011-05` 输出是否需独立立项开发及最小实现切入点的结论
+  - `T-011-06` 执行 `make validate-file` / `make check-links` / `make validate-mermaid` 并同步 `01_Project_Progress.md`、`03_Task_Checklist.md`
+
+### P1：第二优先级
+
+#### Story 4
+
+- 标题：`SYS-002：补齐营收统计查询设计`
+- 对应需求：`SYS002-REQ-012`
+- feature：`sys002-revenue-statistics-design`
+- 优先级：`中`
+- 当前实现状态：`未见实现`
+- Story 描述：
+  - 目标：补齐营收、收费、欠费、渠道、客户维度统计查询能力与口径定义。
+  - 当前判断：文档已定义摘要级统计范围，但本轮需进一步补齐统计主题、维度、指标、`IF-REV-010` 和数据库承接口径；当前代码检索中仍未见明确统计/报表后台入口。
+- 推荐 Task：
+  - `T-012-01` 对齐统计主题、维度、指标口径
+  - `T-012-02` 对齐 `IF-REV-010` 接口与查询条件定义
+  - `T-012-03` 对齐统计视图/汇总口径与数据来源
+  - `T-012-04` 校核代码是否已有隐含统计实现或需新增模块
+  - `T-012-05` 输出统计专题立项建议和最小研发切入点
+
+#### Story 5
+
+- 标题：`SYS-002：统一银行代扣与回盘协同口径`
+- 对应需求：`SYS002-REQ-013`
+- feature：`sys002-bank-withholding-sync`
+- 优先级：`中`
+- 当前实现状态：`已实现`
+- Story 描述：
+  - 目标：统一代扣协议、批次生成、回盘明细与状态回写口径。
+  - 当前判断：银行子系统已具备代扣批次、明细、协议与应用侧入口，重点在跨文档一致性收口。
+- 推荐 Task：
+  - `T-013-01` 对齐代扣业务流程与回盘处理说明
+  - `T-013-02` 对齐银行接口字段与批次状态枚举
+  - `T-013-03` 对齐数据库对象与实现对象映射
+  - `T-013-04` 校核批次、明细、协议实现闭环
+  - `T-013-05` 输出验收与归档结论
+
+#### Story 6
+
+- 标题：`SYS-002：补齐对账与结算处理规则`
+- 对应需求：`SYS002-REQ-014`
+- feature：`sys002-reconcile-settlement-rules`
+- 优先级：`中`
+- 当前实现状态：`已实现`
+- Story 描述：
+  - 目标：补齐对账批次、差异处理、结算批次与状态流转规则。
+  - 当前判断：对账与结算后台骨架较完整，重点是规则、差异分类与边界定义收口。
+- 推荐 Task：
+  - `T-014-01` 对齐对账、差异、结算的业务规则与流程
+  - `T-014-02` 对齐状态机、差异分类与处理动作
+  - `T-014-03` 对齐数据库设计与状态枚举定义
+  - `T-014-04` 校核对账批次、差异、结算实现闭环
+  - `T-014-05` 输出规则闭环与验收建议
+
+### 验收 / 归档优先项
+
+#### Story 7
+
+- 标题：`SYS-002：补齐发票申请设计闭环`
+- 对应需求：`SYS002-REQ-008`
+- feature：`sys002-invoice-apply-design`
+- 优先级：`高`
+- 当前实现状态：`已实现`
+- 推荐 Task：
+  - `T-008-01` 对齐发票申请受理流程与字段口径
+  - `T-008-02` 对齐申请单号、受理号、幂等控制与落库规则
+  - `T-008-03` 校核接口、数据库与实现一致性
+  - `T-008-04` 输出验收与归档结论
+
+#### Story 8
+
+- 标题：`SYS-002：补齐发票结果查询与补偿规则`
+- 对应需求：`SYS002-REQ-009`
+- feature：`sys002-invoice-result-query-rules`
+- 优先级：`高`
+- 当前实现状态：`已实现`
+- 推荐 Task：
+  - `T-009-01` 对齐发票结果查询、补偿与兜底机制
+  - `T-009-02` 对齐重试次数、最近结果、错误信息等字段口径
+  - `T-009-03` 校核实现逻辑与文档规则一致性
+  - `T-009-04` 输出验收与归档结论
+
+#### Story 9
+
+- 标题：`SYS-002：统一发票结果回写口径`
+- 对应需求：`SYS002-REQ-010`
+- feature：`sys002-invoice-writeback-sync`
+- 优先级：`高`
+- 当前实现状态：`已实现`
+- 推荐 Task：
+  - `T-010-01` 对齐发票状态、票号、下载地址、红冲/作废回写字段
+  - `T-010-02` 对齐回写幂等、状态保护与异常处理规则
+  - `T-010-03` 校核回写接口、Mapper 与服务逻辑一致性
+  - `T-010-04` 输出验收与归档结论
+
+## 使用建议
+
+1. 若用于 TAPD：优先按上面的 9 个 Story 直接建单，再按对应 `T-xxx-xx` 录入 Task。
+2. 若用于 speckit：按 feature 名称逐一建立 `spec.md`，将“代码实现评估”作为 `Current State` 输入。
+3. 若用于文档治理：优先处理“部分实现 / 未见实现”的需求项，减少文档与实现偏差。

docs/design/00_Management/18_Old_Module_Number_Audit.md

@@ -0,0 +1,106 @@
+# 福建水务营收系统旧模块编号残留审计
+
+## 审计信息
+
+| 项目 | 内容 |
+|---|---|
+| 审计日期 | 2026-03-18 |
+| 审计范围 | `docs/design`、`docs/guides`、`specs` |
+| 审计目标 | 识别 `METER-004`、`INST-004`、`INST-005` 及其旧模块语义残留，并区分“必须修”“可保留历史描述”“Archive 原始资料” |
+| 审计原则 | 接口编号保留、正式模块编号纠偏、历史台账不篡改、Archive 默认只读 |
+
+## 审计口径
+
+本轮审计按以下规则判定：
+
+1. `IF-METER-004`、`IF-INST-004`、`IF-INST-005` 属于接口编号，不视为旧模块编号错误。
+2. `合同签署与电子签章能力` 作为 `INST-002 工程管理` 下的子能力表达，允许保留。
+3. 正式文档中如果仍把 `INST-004`、`INST-005`、`METER-004` 当作当前正式模块编号使用，判定为“必须修”。
+4. 管理台账、历史进度记录、既往任务记录中反映当时版本状态的内容，判定为“可保留历史描述”。
+5. `docs/design/04_Appendix/Archive/` 下原始资料默认不改，归类为“Archive 原始资料”。
+
+## 审计结论摘要
+
+| 类别 | 结论 |
+|---|---|
+| 必须修 | 0 项 |
+| 可保留历史描述 | 9 项 |
+| Archive 原始资料 | 8 项 |
+| 合法保留的接口编号/子能力表达 | 已在正式文档中复核，无需修订 |
+
+结论说明：
+
+- 当前正式设计主文档体系中，未再发现把 `METER-004`、`INST-004`、`INST-005` 当作当前正式模块编号使用的残留。
+- 正式文档中的命中项主要为接口编号引用，以及 `INST-002` 下“合同签署与电子签章能力”这一合法子能力表达。
+- 需要继续保留关注的内容主要集中在管理台账中的历史记录表述，以及 Archive 原始资料中的旧口径。
+
+## A. 必须修
+
+本轮未发现新增“必须修”项。
+
+说明：
+
+- `docs/design/01_Overview`、`docs/design/02_Detailed_Design`、`docs/design/03_Technical_Design` 已复核。
+- 当前命中均可解释为接口编号、当前子能力标题或已修正后的正确归属。
+
+## B. 可保留历史描述
+
+以下内容命中了旧编号或旧模块语义，但属于历史任务记录、阶段进度记录或当时版本状态说明，不建议直接改写历史事实：
+
+| 文件 | 位置 | 命中内容 | 判定 |
+|---|---|---|---|
+| `docs/design/00_Management/03_Task_Checklist.md` | `#L289` | `INST-001~INST-005` 覆盖范围 | 历史任务描述 |
+| `docs/design/00_Management/03_Task_Checklist.md` | `#L290` | `INST-001~INST-005` 模块补充 | 历史任务描述 |
+| `docs/design/00_Management/03_Task_Checklist.md` | `#L298` | `METER-001~METER-004` 覆盖范围 | 历史任务描述 |
+| `docs/design/00_Management/03_Task_Checklist.md` | `#L299` | `METER-001~METER-004` 模块补充 | 历史任务描述 |
+| `docs/design/00_Management/03_Task_Checklist.md` | `#L301` | `METER-004` 关键规则 | 历史任务描述 |
+| `docs/design/00_Management/03_Task_Checklist.md` | `#L1002` | `表务工单管理完整设计` | 历史命名残留 |
+| `docs/design/00_Management/01_Project_Progress.md` | `#L146` | `INST-001~INST-005` 结构补完 | 历史进度记录 |
+| `docs/design/00_Management/01_Project_Progress.md` | `#L147` | `METER-001~METER-004` 结构补完 | 历史进度记录 |
+| `docs/design/00_Management/01_Project_Progress.md` | `#L234`、`#L247` | `表务工单管理` 等旧模块语义 | 历史方案演进记录 |
+
+处理建议：
+
+- 不直接改写原记录正文。
+- 如后续需要对外输出“当前口径版台账”，应新增“历史口径说明”列或单独生成摘要，不覆盖原始进度记录。
+
+## C. Archive 原始资料
+
+以下内容位于 Archive，属于需求原文、整合草稿或原始附件，应保留原始口径：
+
+| 文件 | 位置 | 命中内容 | 判定 |
+|---|---|---|---|
+| `docs/design/04_Appendix/Archive/07_Integration/表务管理整合.md` | `#L5` | `表务工单管理系统` | 原始整合资料 |
+| `docs/design/04_Appendix/Archive/07_Integration/表务水表功能整合.md` | `#L31` | `表务工单管理系统` | 原始整合资料 |
+| `docs/design/04_Appendix/Archive/01_Requirements/营收系统_需求规格说明书.md` | `#L961` | `表务工单管理系统` | 原始需求资料 |
+| `docs/design/04_Appendix/Archive/01_Requirements/202-营业收费管理系统需求规格说明书20240415.md` | `#L1150` | `表务工单管理系统` | 原始需求资料 |
+| `docs/design/04_Appendix/Archive/01_Requirements/202-营业收费管理系统需求规格说明书20240412.md` | `#L1150` | `表务工单管理系统` | 原始需求资料 |
+| `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_需求规格说明书.md` | `#L771` | `表务工单管理系统` | 原始附件 |
+| `docs/design/04_Appendix/Archive/04_Original_Attachments/202-营业收费管理系统需求规格说明书20240415.md` | `#L955` | `表务工单管理系统` | 原始附件 |
+| `docs/design/04_Appendix/Archive/04_Original_Attachments/202-营业收费管理系统需求规格说明书20240412.md` | `#L955` | `表务工单管理系统` | 原始附件 |
+
+处理建议：
+
+- 保留原文，不在 Archive 内直接做“统一口径式”改写。
+- 若正式文档需要引用这些资料，应通过当前主文档重新释义，而不是复用旧称谓。
+
+## D. 正式文档中的合法保留项
+
+以下命中项已复核，属于当前正确表达，不应误判为旧模块编号残留：
+
+| 文件 | 典型位置 | 说明 |
+|---|---|---|
+| `docs/design/03_Technical_Design/03_Interface_Design.md` | `#L299`、`#L308`、`#L309` | `IF-METER-004`、`IF-INST-004`、`IF-INST-005` 为接口编号 |
+| `docs/design/02_Detailed_Design/01_Detailed_Design.md` | `#L529`、`#L538`、`#L539` | 主详设接口总表中的接口编号引用 |
+| `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` | `#L103`、`#L105`、`#L106` | 模块到接口的追溯引用，不是旧模块编号 |
+| `docs/design/02_Detailed_Design/14_METER_Detailed.md` | `#L53`、`#L144`、`#L189` | `METER-003` 下引用 `IF-METER-004` |
+| `docs/design/02_Detailed_Design/15_INST_Detailed.md` | `#L52`、`#L53`、`#L194`、`#L297` | `INST-002/003` 下引用 `IF-INST-004/005`，以及“合同签署与电子签章能力”子能力标题 |
+| `docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md` | `#L27`、`#L88` | 已明确挂接到 `INST-002`，接口编号保留正常 |
+| `docs/design/01_Overview/03_Summary_Design.md` | `#L938`、`#L3269`、`#L3375`、`#L3376` | 概要设计中的接口表保留接口编号正常 |
+| `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `#L197` | `REV-002` 开账链路对 `IF-METER-004` 的依赖引用正常 |
+
+## 后续建议
+
+1. 若需要对外给出“当前编号口径说明”，建议基于本清单单独输出一份“历史口径对照摘要”，不要直接改写历史台账。
+2. 后续新增管理台账时，涉及旧版本范围可在正文后追加“该条为历史版本记录”说明，降低误读。
+3. 后续如继续做全仓术语治理，可把“表务工单管理”等历史称谓纳入统一的“历史别名表”，仅做映射，不进入正式主稿。

docs/design/00_Management/README.md

@@ -20,6 +20,7 @@
 - `12_AI_Weekly_Audit_Template.md`：每周抽检模板
 - `13_AI_Weekly_Audit_2026W11.md`：首次周检记录示例
 - `14_AI_Audit_Diff_Latest.md`：自动化差异清单（P2）
+- `18_Old_Module_Number_Audit.md`：旧模块编号残留审计清单
 
 ## 使用顺序（建议）
 

docs/design/01_Overview/03_Summary_Design.md

@@ -4,7 +4,7 @@ doc_role: master_document
 authority: primary
 scope: 概要设计
 source_of_truth: true
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-12
 retrieval_priority: P0
 ---
 
@@ -32,7 +32,7 @@ retrieval_priority: P0
 | 【√】草稿 | | |
 | 【】修改稿 | | |
 | 【】正式发布 | | |
-| | **当前版本：** | **V1.6** |
+| | **当前版本：** | **V1.7** |
 | | **作者：** | **唐伟杰** |
 | | **完成日期：** | **2025-08-18** |
 
@@ -47,6 +47,7 @@ retrieval_priority: P0
 | 2025-08-01 | V1.4 | 唐伟杰 | 单点登录采用OAuth2.0+CAS协议：更新单点登录模块描述，强调基于OAuth2.0+CAS协议实现。 |
 | 2025-08-18 | V1.5 | 唐伟杰 | 架构调整：将营收业务系统中的工单、表务、报装剥离为独立子系统（SYS-005/006/007），更新目录、功能范围、子系统列表、关系图与接口定义；保留客户服务模块在营收业务系统中的作用。 |
 | 2025-08-18 | V1.6 | 唐伟杰 | 合并第三方支付能力至SYS-009"支付与银行结算子系统"，统一消息服务重编号为SYS-010；更新总体目标、功能范围、接口定义、子系统列表与相关架构图。 |
+| 2026-03-12 | V1.7 | 唐伟杰 | 对照 `Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 完成来源对齐：补充历史来源说明与引用路径，确认系统拆分、基础服务定位、外部集成与非功能约束已同步；保留当前正式系统名称、模块编号与接口编号标准，不沿用历史别名编码作为正式口径。 |
 
 <a id="sec-preface"></a>
 
@@ -111,6 +112,28 @@ retrieval_priority: P0
 - 《RuoYi-Vue-Pro技术架构文档》
 - 《Spring Cloud微服务架构设计指南》
 - 《福建水务营收系统需求规格说明书》
+- `../04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+
+## 历史来源对齐说明
+
+本主文档已对齐 `../04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 中对当前正式设计仍有效的内容，主要包括：
+
+- 子系统拆分口径：`SYS-001 ~ SYS-010` 的职责边界、基础服务分层与跨系统协同关系。
+- 业务范围口径：营收、微网厅、工单、表务、报装、发票、支付结算、消息等范围定义。
+- 架构与集成口径：外部支付、银行、税控、消息、摄像表 AI 等外部协同边界。
+- 非功能口径：达梦数据库 8.0+、物理部署、可靠性、安全与扩展性方向。
+
+以下内容仅保留在 Archive 中作为历史来源，不直接作为当前正式主文档口径：
+
+- 历史系统名称“营业收费管理系统”等旧标题写法。
+- 历史别名编码，如 `UP-SSO`、`REV-CUSTOM`、`WECHAT-*`。
+- 历史接口编号体系，如 `IF-S-*`、`IF-C-*`。
+
+当前正式口径继续统一采用：
+
+- 系统名称：`福建水务营收系统`
+- 模块编号：`UP-001`、`REV-001`、`CS-001`、`METER-001`、`INST-001`
+- 接口编号：`IF-UP-*`、`IF-REV-*`、`IF-CS-*`、`IF-METER-*`、`IF-INST-*`、`IF-EXT-*`
 
 <a id="sec-overall-design"></a>
 
@@ -414,7 +437,7 @@ graph TB
 
 **外部系统（External Systems）**
 
-- CA电子签章：用于报装资料签署、验章与存证（INST-004 签章回执接口）
+- CA电子签章：用于报装资料签署、验章与存证（当前归属 `INST-002` 工程管理）
 - 银行：托收代扣、回盘与对账（经SYS-009）
 - 支付渠道：微信/支付宝/银联聚合等（经SYS-009）
 - 发票供应商：航天/博思等税控平台（经SYS-008）
@@ -1725,7 +1748,7 @@ graph TD
 - **客户资料管理**：客户档案建立、信息维护、分组管理
 - **抄表开账**：抄表数据录入、复核确认、自动开账
 - **营业收费**：柜台收费、移动收费、在线缴费
-- **账务处理**：账务调整、退款处理、坏账管理
+- **账务处理**：一期先聚焦水量调整、金额调整、退款、冲正、坏账申请，统一经 `IF-REV-007` 承接，并按共性能力先统一、场景能力再分批推进
 - **发票管理**：发票开具、查询、重开、作废
 - **催缴管理**：欠费统计、催缴通知、停水管理
 - **统计分析**：多维度数据统计和报表分析
@@ -3243,7 +3266,7 @@ graph TD
 | IF-METER-001 | 库存查询接口 | 查询仓库库存状态和预警信息 | 工单/营收/报装系统 | HTTP/REST | 仓库编号、水表型号、库存状态 | 库存明细、预警状态、可用数量 |
 | IF-METER-002 | 领用出库接口 | 支持换表/施工水表领用出库 | 工单管理系统 | HTTP/REST | 领用单号、水表型号、领用数量、领用人 | 出库状态、库存余量、领用凭证 |
 | IF-METER-003 | 档案查询接口 | 查询水表设备档案信息 | 营收/工单/报装系统 | HTTP/REST | 水表编号、客户编号、查询类型 | 设备档案、安装历史、维修记录 |
-| IF-METER-004 | 设备入库接口 | 新水表采购入库登记 | 采购管理系统 | HTTP/REST | 水表信息、入库数量、供应商信息 | 入库结果、库存更新状态 |
+| IF-METER-004 | 集抄数据接收接口 | 接收远传抄表、异常告警并同步状态 | 物联网平台 | HTTP/REST | 设备标识、采集时间、读数值、告警信息 | 接收结果、校验状态、异常标记 |
 | IF-METER-005 | 资产调拨接口 | 仓库间水表调拨转移 | 表务管理系统 | HTTP/REST | 调出仓库、调入仓库、调拨清单 | 调拨状态、库存变更结果 |
 | IF-METER-006 | 盘点核实接口 | 定期盘点和库存核实 | 表务管理系统 | HTTP/REST | 盘点计划、盘点范围、盘点人员 | 盘点结果、差异分析、调整建议 |
 
@@ -3350,7 +3373,7 @@ graph TD
 | IF-INST-002 | 踏勘派工接口 | 现场踏勘任务派发 | 工单管理系统 | HTTP/REST | 报装单号、踏勘要求、预约时间 | 派工结果、踏勘人员、预计完成时间 |
 | IF-INST-003 | 签章接口 | 调用CA系统进行电子签章 | CA电子签章系统 | HTTP/REST | 合同文档、签章类型、签章方信息 | 签章状态、签章文档、存证信息 |
 | IF-INST-004 | 签章回执接口 | 接收CA系统签章完成回执 | CA电子签章系统 | HTTP/REST | 签章任务ID、签章结果、时间戳 | 接收确认、存档状态 |
-| IF-INST-005 | 施工派工接口 | 安装施工任务派发 | 工单管理系统 | HTTP/REST | 报装单号、施工方案、材料清单 | 派工状态、施工队伍、开工时间 |
+| IF-INST-005 | 报装归档接口 | 归档申请、合同、验收与签章回执资料 | 报装系统 | HTTP/REST | 报装单号、资料清单、签章回执、验收文档 | 归档状态、档案编号、存储位置 |
 | IF-INST-006 | 验收通水接口 | 验收合格并开通供水 | 营收业务系统 | HTTP/REST | 报装单号、验收结果、水表信息 | 开户结果、客户编号、通水状态 |
 | IF-INST-007 | 档案归档接口 | 竣工档案归档管理 | 档案管理系统 | HTTP/REST | 报装单号、竣工资料、验收文档 | 归档状态、档案编号、存储位置 |
 

docs/design/01_Overview/05_Module_Inventory.md

@@ -0,0 +1,146 @@
+---
+doc_id: OV-05-MODULE-INVENTORY
+doc_role: support_document
+authority: secondary
+scope: 总体设计-模块清单
+source_of_truth: false
+last_reviewed: 2026-03-18
+retrieval_priority: P1
+---
+
+# 福建水务营收系统模块清单
+
+## 文档定位
+
+本文档基于 `output/preview/福建水务营收系统整体架构图.html` 提炼系统分层、子系统与模块清单，用于提供：
+
+1. 总体设计层的统一模块索引；
+2. 详细设计目录的模块承接基线；
+3. 后续对齐概要设计、详细设计、接口设计与数据库设计时的编号核对入口。
+
+边界说明：
+
+- 本文档只整理模块清单与承接关系，不替代 `03_Summary_Design.md` 的正式概要口径；
+- 详细模块正文以 `../02_Detailed_Design/` 下主详设与模块正文为准；
+- 基础服务子系统 `SYS-008`、`SYS-009`、`SYS-010` 在当前仓库中主要按“协同对象 / 外部能力”表达，不在详细设计层虚增平行主稿。
+
+## 来源说明
+
+| 来源 | 用途 |
+| --- | --- |
+| `output/preview/福建水务营收系统整体架构图.html` | 提取架构图中的层级、子系统、模块与集成关系 |
+| `03_Summary_Design.md` | 核对系统名称、模块编号与当前正式口径 |
+| `../02_Detailed_Design/01_Detailed_Design.md` | 核对详细设计当前已承接的模块范围 |
+| `../02_Detailed_Design/02_Module_Traceability_Index.md` | 核对模块到接口/数据域的追溯入口 |
+
+## 分层总览
+
+| 层级 | 当前对象 |
+| --- | --- |
+| 表现层 | Web 管理端、手机抄表 APP、`SYS-004` 微网厅子系统、移动收费端 |
+| 网关层 | API 网关、负载均衡、统一认证中心、监控日志 |
+| 业务服务层 | `SYS-001` 统一平台、`SYS-002` 营收业务子系统、`SYS-003` 手机抄表 APP、`SYS-004` 微网厅子系统、`SYS-005` 工单管理子系统、`SYS-006` 表务管理子系统、`SYS-007` 报装业务子系统 |
+| 基础服务层 | 权限服务、工作流引擎、消息队列、注册/配置中心、任务调度、文件服务、`SYS-008` 发票服务子系统、`SYS-009` 支付与银行结算子系统、`SYS-010` 消息服务子系统、摄像表 AI 系统（外部） |
+| 数据层 | 达梦数据库主库、达梦数据库从库、Redis 缓存、MinIO 对象存储、备份存储 |
+
+## 子系统模块清单
+
+### SYS-001 统一平台
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `UP-001` | 单点登录模块 | OAuth2.0 + CAS、JWT 令牌认证、多种登录方式 | [11_UP_Detailed.md](../02_Detailed_Design/11_UP_Detailed.md) |
+| `UP-002` | 系统管理模块 | 用户角色、部门组织、菜单权限配置 | [11_UP_Detailed.md](../02_Detailed_Design/11_UP_Detailed.md) |
+| `UP-003` | 权限控制模块 | RBAC、菜单权限、数据权限 | [11_UP_Detailed.md](../02_Detailed_Design/11_UP_Detailed.md) |
+| `UP-004` | 租户管理模块 | 多租户数据隔离、租户配置管理 | [11_UP_Detailed.md](../02_Detailed_Design/11_UP_Detailed.md) |
+| `UP-005` | 系统监控模块 | 在线用户、性能监控、操作日志 | 当前并入统一平台运维支撑能力，在 [11_UP_Detailed.md](../02_Detailed_Design/11_UP_Detailed.md) 与技术专项中协同表达 |
+
+### SYS-002 营收业务子系统
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `REV-001` | 客户资料管理 | 客户档案、分组管理、信息变更 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-002` | 抄表开账 | 抄表录入、复核开账、异常处理 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-003` | 营业收费 | 柜台收费、移动收费、在线缴费 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-004` | 账务处理 | 调账、退款、坏账处理 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-005` | 发票管理 | 开票、查询、作废，经 `SYS-008` 协同 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-006` | 催缴管理 | 欠费统计、催缴通知、停水管理 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-007` | 统计分析 | 多维统计、报表分析 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-008` | 代收业务 | 银行代扣、聚合支付，经 `SYS-009` 协同 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `REV-009` | 业务参数配置 | 水价体系、水表参数、基础配置 | [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md) |
+| `CS-001` ~ `CS-007` | 客户服务模块群 | 账户绑定、查询、缴费、电子发票、网点、业务办理、柜面扫码支付 | [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+
+### SYS-003 手机抄表 APP
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `MOBILE-001` | 登录认证 | 机构编号、用户名密码、自动登录、令牌管理 | 当前按“移动作业端 / 抄表协同端”表达，能力散落在 [12_REV_Detailed.md](../02_Detailed_Design/12_REV_Detailed.md)、[14_METER_Detailed.md](../02_Detailed_Design/14_METER_Detailed.md) |
+| `MOBILE-002` | 首页搜索 | 多维搜索、最近记录、任务快捷入口 | 同上 |
+| `MOBILE-003` | 采集任务管理 | 任务列表、批量下载、单户采集、AI 识别、读数校验 | 同上 |
+| `MOBILE-004` | 现场上报 | 异常上报、图片与定位采集、提交工单 | 同上 |
+| `MOBILE-005` | 个人与设置 | 个人资料、偏好设置、缓存管理、安全退出 | 同上 |
+| `MOBILE-006` | 数据同步 | 任务包增量同步、离线数据上传、冲突处理 | 同上 |
+
+### SYS-004 微网厅子系统
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `WECHAT-001` | 账户绑定管理 | 微信授权、绑定解绑、多账户管理 | 当前与 `CS-001` 对齐承接于 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+| `WECHAT-002` | 信息查询服务 | 账单查询、用水历史、缴费记录、停水公告 | 当前与 `CS-002` 对齐承接于 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+| `WECHAT-003` | 在线缴费服务 | 快捷缴费、充值、多种支付方式 | 当前与 `CS-003` 对齐承接于 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+| `WECHAT-004` | 电子发票服务 | 发票查看、推送、电子发票管理 | 当前与 `CS-004` 对齐承接于 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+| `WECHAT-005` | 营业网点服务 | 网点查询、地图导航、预约服务 | 当前与 `CS-005` 对齐承接于 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+| `WECHAT-006` | 业务办理服务 | 联系方式/开票方式变更、更名过户、低保、换表、自主抄表 | 当前与 `CS-006` 对齐承接于 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md) |
+| `WECHAT-007` | 账户流水 | 历史缴费流水查询与导出 | 当前并入 `CS-002` 信息查询服务表达 |
+| `WECHAT-008` | 账号与机构管理 | 切换机构、添加解绑客户、默认客户设置 | 当前并入 `CS-001` 账户绑定管理表达 |
+
+### SYS-005 工单管理子系统
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `WORK-001` | 工单中心 | 统一受理、路由、分派、跟踪 | 当前按协同能力出现在 [13_CS_Detailed.md](../02_Detailed_Design/13_CS_Detailed.md)、[14_METER_Detailed.md](../02_Detailed_Design/14_METER_Detailed.md)、[15_INST_Detailed.md](../02_Detailed_Design/15_INST_Detailed.md) |
+| `WORK-002` | 流程引擎 | 条件路由、并行/互斥网关、回退重审 | 当前作为流程支撑能力表达，不单列详设正文 |
+| `WORK-003` | 监控预警 | 实时看板、超时预警、积压监控 | 当前并入运维/流程协同能力表达 |
+| `WORK-004` | 绩效统计 | 处理时长分析、达成率统计、考核报表 | 当前并入统计与报表能力表达 |
+
+### SYS-006 表务管理子系统
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `METER-001` | 表务基础管理 | 厂家、型号、口径、量程、检定周期等参数标准化 | [14_METER_Detailed.md](../02_Detailed_Design/14_METER_Detailed.md) |
+| `METER-002` | 仓库与库存管理 | 入库、出库、盘点、调拨、库存预警 | [14_METER_Detailed.md](../02_Detailed_Design/14_METER_Detailed.md) |
+| `METER-003` | 设备档案管理 | 唯一档案、状态流转、批次与质检记录追溯 | [14_METER_Detailed.md](../02_Detailed_Design/14_METER_Detailed.md) |
+
+### SYS-007 报装业务子系统
+
+| 模块编号 | 模块名称 | 模块职责 | 详细设计承接 |
+| --- | --- | --- | --- |
+| `INST-001` | 报装流程管理 | 端到端阶段流转、里程碑控制 | [15_INST_Detailed.md](../02_Detailed_Design/15_INST_Detailed.md) |
+| `INST-002` | 工程管理 | 进度、资源、质量、安全管理，支持合同签订与电子签章 | [15_INST_Detailed.md](../02_Detailed_Design/15_INST_Detailed.md) |
+| `INST-003` | 档案管理 | 资料归档、过程留痕、竣工档案、CA 签章/验章/存证 | [15_INST_Detailed.md](../02_Detailed_Design/15_INST_Detailed.md) |
+
+### 基础服务子系统与外部能力
+
+| 对象 | 模块职责 | 当前文档承接 |
+| --- | --- | --- |
+| `SYS-008` 发票服务子系统 | 统一开票网关、供应商适配器、发票管理、回执处理 | 概要层、接口设计、发票相关详细设计协同描述 |
+| `SYS-009` 支付与银行结算子系统 | 聚合支付、代扣业务、资金清算、安全加密 | 概要层、接口设计、收费/代收相关详细设计协同描述 |
+| `SYS-010` 消息服务子系统 | 统一消息网关、模板管理、微信通知、外部集成 | 概要层、接口设计、催缴/通知/客户服务协同描述 |
+| 摄像表 AI 系统（外部） | 水表图像识别、读数识别、API 协同 | 概要层与抄表 / 表务协同描述 |
+
+## 详细设计承接原则
+
+1. 架构图中的模块清单可作为“模块枚举基线”，但不等同于必须一一拆出平行详设文档。
+2. 当前 `02_Detailed_Design` 采用“业务域正文 + 追溯索引”的组织方式，允许多个架构层模块映射到同一详设正文。
+3. `MOBILE-*`、`WECHAT-*`、`WORK-*` 目前以“渠道能力 / 协同能力 / 支撑能力”方式承接，不单独新增正式主稿。
+4. 若后续需要把某一模块升级为独立详细设计正文，应先确认其已具备稳定边界、独立接口与核心数据域。
+
+## 与详细设计的对齐建议
+
+| 对齐对象 | 建议动作 |
+| --- | --- |
+| `../02_Detailed_Design/01_Detailed_Design.md` | 明确该主详设基于本模块清单承接哪些模块、哪些采用合并承接 |
+| `../02_Detailed_Design/02_Module_Traceability_Index.md` | 增加“架构图模块编号 → 当前详设承接位置”的映射说明 |
+| `../02_Detailed_Design/13_CS_Detailed.md` | 明确 `CS-*` 与 `WECHAT-*` 的对齐关系 |
+| `../02_Detailed_Design/14_METER_Detailed.md` | 保持 `METER-001 ~ METER-003` 与架构图一致，多余内容降为子能力章节 |
+| `../02_Detailed_Design/15_INST_Detailed.md` | 保持 `INST-001 ~ INST-003` 与架构图一致，多余内容降为子能力章节 |

docs/design/01_Overview/README.md

@@ -12,6 +12,7 @@
 | `02_System_Architecture.md` | 总体架构说明（分层、技术栈、边界） | 与主文档架构口径保持一致 |
 | `03_Summary_Design.md` | **概要设计主文档（单一真源）** | 优先维护；涉及范围变更时同步其余文档 |
 | `04_System_Diagrams.md` | 图谱文档（图文配套） | 只维护图示与图注，不重复大段正文 |
+| `05_Module_Inventory.md` | 模块清单（架构图模块枚举与详设承接映射） | 用于模块编号核对与详设对齐，不替代概要主稿 |
 
 ## 与目录外文档的关系
 
@@ -24,6 +25,7 @@
 2. `01_System_Overview.md`（查看背景与术语）
 3. `02_System_Architecture.md`（查看架构细节）
 4. `04_System_Diagrams.md`（对照图示核对一致性）
+5. `05_Module_Inventory.md`（核对子系统与模块承接关系）
 
 ## 维护规则
 

docs/design/02_Detailed_Design/01_Detailed_Design.md

@@ -98,11 +98,13 @@ retrieval_priority: P0
 12. `docs/design/03_Technical_Design/04_Security_Design.md`
 13. `docs/design/03_Technical_Design/05_Deployment_Design.md`
 14. 福建水投相关业务操作手册及需求说明资料
+15. `docs/design/01_Overview/05_Module_Inventory.md`
 
 <a id="sec-module-files"></a>
 
 ## 模块正文文件索引
 
+- 总体层模块清单与承接映射：`docs/design/01_Overview/05_Module_Inventory.md`
 - 统一平台模块正文：`docs/design/02_Detailed_Design/11_UP_Detailed.md`
 - 营收业务模块正文：`docs/design/02_Detailed_Design/12_REV_Detailed.md`
 - 客户服务模块正文：`docs/design/02_Detailed_Design/13_CS_Detailed.md`
@@ -233,10 +235,17 @@ graph TB
 |---|---|---|
 | 统一平台 | 提供统一认证、组织、权限、参数、审计与监控基础能力 | UP-001 ~ UP-004 |
 | 营收业务 | 覆盖客户、抄表、收费、账务、发票、催缴、统计、代收与业务工单 | REV-001 ~ REV-009 |
-| 表务管理 | 覆盖水表档案、表务工单、仓储、生命周期与物联网接入 | METER-001 ~ METER-004 |
-| 报装与签章 | 覆盖受理、踏勘、施工、签约、电子签章、归档 | INST-001 ~ INST-005 |
+| 表务管理 | 覆盖水表基础参数、仓储库存、设备档案以及工单和物联网同步等支撑能力 | METER-001 ~ METER-003 |
+| 报装与签章 | 覆盖报装流程管理、工程管理、档案管理及其下挂签章归档能力 | INST-001 ~ INST-003 |
 | 客户服务模块 | 覆盖账户绑定、信息查询、在线缴费、电子发票、网点服务、业务办理与柜面扫码支付 | CS-001 ~ CS-007 |
 
+### 与架构图模块清单的承接说明
+
+1. 架构图中的模块枚举基线以 `../01_Overview/05_Module_Inventory.md` 为准。
+2. 当前详细设计采用“业务域正文承接多个架构层模块”的组织方式，不强制为 `MOBILE-*`、`WECHAT-*`、`WORK-*` 单独建立平行正式主稿。
+3. `WECHAT-*` 当前按客户服务渠道视角并入 `CS-*` 体系承接；`MOBILE-*` 当前作为抄表与表务协同端能力分散承接于营收与表务正文；`WORK-*` 当前作为工单协同与流程支撑能力在客户服务、表务、报装正文中交叉引用。
+4. 若后续需要新增独立正文，必须先确认该模块已具备稳定边界、独立接口和核心数据域，并同步更新概要设计与追溯索引。
+
 <a id="sec-module-detail"></a>
 <a id="sec-platform-detail"></a>
 
@@ -322,9 +331,8 @@ graph TB
 | 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
 |---|---|---|---|
 | `METER-001` | 表务基础管理 | 水表档案、状态与参数基础管理 | [METER-001](./14_METER_Detailed.md#mod-meter-001) |
-| `METER-002` | 表务工单管理 | 换表、移表、校表、维修等工单处理 | [METER-002](./14_METER_Detailed.md#mod-meter-002) |
-| `METER-003` | 仓储与生命周期管理 | 入出库、退库、报废与生命周期追踪 | [METER-003](./14_METER_Detailed.md#mod-meter-003) |
-| `METER-004` | 物联网接入与数据同步 | 集抄与IoT数据接入、同步与异常处理 | [METER-004](./14_METER_Detailed.md#mod-meter-004) |
+| `METER-002` | 仓库与库存管理 | 入库、出库、退库、报废与库存预警 | [METER-002](./14_METER_Detailed.md#mod-meter-002) |
+| `METER-003` | 设备档案管理 | 设备主档、状态流转、工单协同与远传同步 | [METER-003](./14_METER_Detailed.md#mod-meter-003) |
 
 ## 正文入口
 
@@ -342,11 +350,9 @@ graph TB
 
 | 模块编号 | 模块名称 | 设计摘要 | 正文链接 |
 |---|---|---|---|
-| `INST-001` | 报装申请与受理 | 多入口申请受理、资料采集与流程发起 | [INST-001](./15_INST_Detailed.md#mod-inst-001) |
-| `INST-002` | 现场踏勘与方案设计 | 踏勘记录、方案编制与版本化管理 | [INST-002](./15_INST_Detailed.md#mod-inst-002) |
-| `INST-003` | 施工验收与立户通水 | 施工节点留痕、验收、立户通水协同 | [INST-003](./15_INST_Detailed.md#mod-inst-003) |
-| `INST-004` | 合同签署与电子签章 | 合同签署、签章、时间戳与存证协同 | [INST-004](./15_INST_Detailed.md#mod-inst-004) |
-| `INST-005` | 档案归档与过程留痕 | 材料归档、回执留存与过程可追溯 | [INST-005](./15_INST_Detailed.md#mod-inst-005) |
+| `INST-001` | 报装流程管理 | 申请受理、踏勘流转与方案编制 | [INST-001](./15_INST_Detailed.md#mod-inst-001) |
+| `INST-002` | 工程管理 | 施工验收、立户通水与合同签章协同 | [INST-002](./15_INST_Detailed.md#mod-inst-003) |
+| `INST-003` | 档案管理 | 材料归档、签章回执留存与过程可追溯 | [INST-003](./15_INST_Detailed.md#mod-inst-005) |
 
 ## 正文入口
 

docs/design/02_Detailed_Design/02_Module_Traceability_Index.md

@@ -44,6 +44,7 @@ retrieval_priority: P1
 2. 发现模块描述与接口/数据口径冲突时，以主详设为第一参照，并同步修订技术专项文档；
 3. 本文档仅保留“可追溯最小必要信息”，不重复搬运完整设计正文；
 4. 基础服务子系统（SYS-008/009/010）在详细设计层按接口协同描述，不在此索引中虚增平行模块。
+5. 架构图层面的完整模块枚举以 `../01_Overview/05_Module_Inventory.md` 为核对入口；本索引只保留当前详细设计实际承接的模块与必要映射说明。
 
 <a id="sec-subsystem-matrix"></a>
 
@@ -54,8 +55,22 @@ retrieval_priority: P1
 | 统一平台 | `UP-001 ~ UP-004` | [统一平台模块正文](./11_UP_Detailed.md#sec-content) | [接口设计](../03_Technical_Design/03_Interface_Design.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) |
 | 营收业务 | `REV-001 ~ REV-009` | [营收业务模块正文](./12_REV_Detailed.md#sec-content) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) |
 | 客户服务 | `CS-001 ~ CS-007` | [客户服务模块正文](./13_CS_Detailed.md#sec-content) | [接口设计](../03_Technical_Design/03_Interface_Design.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) |
-| 表务管理 | `METER-001 ~ METER-004` | [表务模块正文](./14_METER_Detailed.md#sec-content) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) |
-| 报装与签章 | `INST-001 ~ INST-005` | [报装与签章模块正文](./15_INST_Detailed.md#sec-content) | [CA 补充说明](./03_CA_Esignature_Supplement.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) |
+| 表务管理 | `METER-001 ~ METER-003` | [表务模块正文](./14_METER_Detailed.md#sec-content) | [数据库设计](../03_Technical_Design/01_Database_Design.md)、[接口设计](../03_Technical_Design/03_Interface_Design.md) |
+| 报装与签章 | `INST-001 ~ INST-003` | [报装与签章模块正文](./15_INST_Detailed.md#sec-content) | [CA 补充说明](./03_CA_Esignature_Supplement.md)、[安全设计](../03_Technical_Design/04_Security_Design.md) |
+
+## 架构图模块承接映射
+
+| 架构图对象 | 当前详设承接方式 | 说明 |
+| --- | --- | --- |
+| `UP-001 ~ UP-005` | `11_UP_Detailed.md` | `UP-005` 当前并入统一平台运维支撑能力表达 |
+| `REV-001 ~ REV-009` | `12_REV_Detailed.md` | 与营收业务主链路一一对齐 |
+| `CS-001 ~ CS-007` | `13_CS_Detailed.md` | 与客户服务正文一一对齐 |
+| `WECHAT-001 ~ WECHAT-008` | `13_CS_Detailed.md` | 当前作为渠道侧映射，不单独拆出微网厅平行详设 |
+| `MOBILE-001 ~ MOBILE-006` | `12_REV_Detailed.md` + `14_METER_Detailed.md` | 当前作为移动抄表 / 现场作业协同能力承接 |
+| `WORK-001 ~ WORK-004` | 协同承接 | 当前在客户服务、表务、报装正文中按工单 / 流程支撑能力引用 |
+| 架构图 `METER-001 ~ METER-003` | `14_METER_Detailed.md` | 当前详设已修正为与架构图一致的三段式编号，多余内容改为子能力章节 |
+| 架构图 `INST-001 ~ INST-003` | `15_INST_Detailed.md` | 当前详设已修正为与架构图一致的三段式编号，多余内容改为子能力章节 |
+| `SYS-008/009/010` | 接口与协同承接 | 当前不在详细设计目录新增平行主稿，主要在概要、接口和相关业务正文中描述 |
 
 <a id="sec-module-matrix"></a>
 
@@ -83,15 +98,12 @@ retrieval_priority: P1
 | `CS-005` | 营业网点服务 | [章节](./13_CS_Detailed.md#mod-cs-005) | 网点信息、业务范围 | `IF-CS-005` | 客户渠道 |
 | `CS-006` | 业务办理服务 | [章节](./13_CS_Detailed.md#mod-cs-006) | 办理申请、办理状态 | `IF-CS-006` | 工单系统、消息服务 |
 | `CS-007` | 柜面扫码支付 | [章节](./13_CS_Detailed.md#mod-cs-007) | 柜面订单、流水、核销状态 | `IF-CS-007` | 营业厅、`SYS-009` |
-| `METER-001` | 表务基础管理 | [章节](./14_METER_Detailed.md#mod-meter-001) | 水表档案、状态、参数 | `IF-METER-001` | 营收、报装 |
-| `METER-002` | 表务工单管理 | [章节](./14_METER_Detailed.md#mod-meter-002) | 换表/移表工单、处理结果 | `IF-METER-002` | 工单系统、移动作业 |
-| `METER-003` | 仓储与生命周期管理 | [章节](./14_METER_Detailed.md#mod-meter-003) | 库存、出入库、报废 | `IF-METER-003` | 仓储管理端 |
-| `METER-004` | 物联网接入与数据同步 | [章节](./14_METER_Detailed.md#mod-meter-004) | 远程抄表数据、异常告警 | `IF-METER-004` | IoT 平台、营收开账 |
-| `INST-001` | 报装申请与受理 | [章节](./15_INST_Detailed.md#mod-inst-001) | 申请单、资料附件 | `IF-INST-001` | 柜台、微网厅、政务 |
-| `INST-002` | 现场踏勘与方案设计 | [章节](./15_INST_Detailed.md#mod-inst-002) | 踏勘记录、方案版本 | `IF-INST-002` | 报装人员 |
-| `INST-003` | 施工验收与立户通水 | [章节](./15_INST_Detailed.md#mod-inst-003) | 施工节点、验收结果 | `IF-INST-005`（归档协同） | 表务、客户建档 |
-| `INST-004` | 合同签署与电子签章 | [章节](./15_INST_Detailed.md#mod-inst-004) | 合同、签章、存证 | `IF-INST-003`、`IF-INST-004` | 泛微 CA |
-| `INST-005` | 档案归档与过程留痕 | [章节](./15_INST_Detailed.md#mod-inst-005) | 档案、回执、过程日志 | `IF-INST-005` | 报装、档案管理 |
+| `METER-001` | 表务基础管理 | [章节](./14_METER_Detailed.md#mod-meter-001) | 基础参数、水表主档、状态 | `IF-METER-001` | 营收、报装 |
+| `METER-002` | 仓库与库存管理 | [章节](./14_METER_Detailed.md#mod-meter-002) | 库存、出入库、退库、报废 | `IF-METER-003` | 仓储管理端 |
+| `METER-003` | 设备档案管理 | [章节](./14_METER_Detailed.md#mod-meter-003) | 设备档案、工单留痕、远程同步 | `IF-METER-001`、`IF-METER-002`、`IF-METER-004` | 工单系统、移动作业、IoT 平台 |
+| `INST-001` | 报装流程管理 | [章节](./15_INST_Detailed.md#mod-inst-001) | 申请单、资料附件、踏勘方案 | `IF-INST-001`、`IF-INST-002` | 柜台、微网厅、政务、报装人员 |
+| `INST-002` | 工程管理 | [章节](./15_INST_Detailed.md#mod-inst-002) | 施工节点、验收结果、签章协同 | `IF-INST-003`、`IF-INST-004`、`IF-INST-005` | 表务、客户建档、泛微 CA |
+| `INST-003` | 档案管理 | [章节](./15_INST_Detailed.md#mod-inst-003) | 档案、回执、过程日志 | `IF-INST-005` | 报装、档案管理 |
 
 <a id="sec-maintenance"></a>
 

docs/design/02_Detailed_Design/03_CA_Esignature_Supplement.md

@@ -24,7 +24,7 @@ retrieval_priority: P1
 
 ## 文档定位与边界
 
-本文件是 `01_Detailed_Design.md` 中 “`INST-004 合同签署与电子签章`” 的专项补充文档，重点补充：
+本文件是 `01_Detailed_Design.md` 中 `INST-002 工程管理` 下“合同签署与电子签章能力”的专项补充文档，重点补充：
 
 1. 泛微 CA 接口对接边界与字段约定；
 2. 签章任务状态流转、异常补偿和运维观测点；
@@ -169,4 +169,3 @@ stateDiagram-v2
 1. 涉及 CA 字段或签名算法变更，需先更新本补充文档与接口设计文档；
 2. 发布前执行联调清单：签署成功、签署失败、回执重放、超时补偿；
 3. 发布后至少观察一个完整业务周期，确认签章成功率与回执时延稳定。
-

docs/design/02_Detailed_Design/12_REV_Detailed.md

@@ -59,7 +59,7 @@ retrieval_priority: P1
 | REV-003 营业收费 | `IF-REV-006` | `biz_charge*`、`biz_collection`、`bk_transaction*` | `SYS-009` |
 | REV-004 账务处理 | `IF-REV-007` | `biz_charge*`、`biz_operat_log*` | 财务与营业人员 |
 | REV-005 发票与税务处理 | `IF-REV-008` | `biz_invoice*`、`biz_cust_invoice` | `SYS-008` |
-| REV-006 催缴与通知 | `IF-REV-009` | `biz_charge*`、催缴结果留痕 | `SYS-010` |
+| REV-006 催缴与通知 | `IF-REV-013` | `biz_charge*`、催缴结果留痕 | `SYS-010` |
 | REV-007 统计分析 | `IF-REV-010` | 客户、抄表、收费、渠道聚合对象 | 统计分析端 |
 | REV-008 代收与银行业务 | `IF-REV-011` | `bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_*` | `SYS-009`、银行 |
 | REV-009 业务参数配置 | `IF-REV-012` | `biz_parameter_settings`、`biz_page_settings*`、`biz_price_*` | 统一平台、营收模块 |
@@ -94,6 +94,26 @@ retrieval_priority: P1
 - `biz_cust_no_rule`：客户编号规则。
 - `biz_cust_hub_marks`：集收号/集收标记关系。
 
+### 迁移补充（旧系统承接）
+
+#### 定额共享
+
+- 旧系统在“客户资料”下提供定额主客户、子客户绑定与共享清单管理能力。
+- 当前正式设计不新增并行主模型，统一归入客户与计划用水方案关系对象承接。
+- 迁移时必须至少保留主客户、子客户、绑定状态、生效时间、解除时间、备注与操作留痕，确保共享清单可查询、可解绑、可追溯。
+
+#### 定额核定
+
+- 旧系统支持对已建立共享关系的客户执行定额核定、撤销核定和共享清单联查。
+- 当前建议以客户关系对象和计划用水方案关系为主承接核定结果，不额外发明独立账务主表。
+- 核定结果迁移后应支持按客户、站点、核定状态、核定时间查询，并保留核定依据、操作人和变更留痕。
+
+#### 批量修改
+
+- 旧系统已形成“手工修改 + 模板导入修改”的双模式客户资料维护能力。
+- 当前正式设计应将其视为客户主数据治理能力的一部分，而不是临时导入工具。
+- 迁移时需明确三类口径：可批量修改字段范围、导入模板校验规则、批量修改审计留痕；历史批量修改结果至少需保留任务来源、修改字段、执行结果和失败原因。
+
 ### 接口映射
 
 - `IF-REV-001`：客户档案、账户状态、联系人与水表绑定关系查询。
@@ -133,11 +153,23 @@ flowchart TD
 
 ### 关键规则
 
-1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态。
-2. 异常抄表支持估抄、补抄、重录、人工复核。
-3. 开账按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算。
-4. 审核通过后的营业账方可进入收费、催缴和发票流程。
-5. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑，但账单生成仍归属 SYS-002。
+1. 抄表数据同时校验本次读数、上次读数、用量波动和抄表状态，只有通过校验或完成异常复核的数据才能进入开账。
+2. 异常抄表支持估抄、补抄、重录、人工复核；异常处理的目标是形成可继续开账或明确阻断的统一结论，而不是绕开开账规则单独落账。
+3. `IF-REV-005` 的正式边界是“抄表校验完成后的账单生成”，不负责收费核销、发票开具、催缴执行和统计分析。
+4. 开账计费按价格归属、价格模板、费用组成、阶梯规则、计划用水方案综合计算；价格配置缺失、费用组成不完整或规则冲突时，必须阻断生成并返回失败原因。
+5. 账单生成结果统一由 `biz_charge` 与 `biz_charge_detail` 承接：主表表达客户、账期、应收日期、账单总金额和主状态，明细表表达费用组成、用量、单价和明细金额。
+6. 特殊开账、无码客户开账、罚款类开账等非标准来源，仍纳入同一营业账主明细模型承接，通过来源类型、业务类型、依据说明和操作留痕区分，不单独扩展平行账表。
+7. 审核通过后的营业账方可进入收费、催缴和发票流程；后续链路只能消费已生成账单结果，不反向改变本接口的生成边界。
+8. 远传抄表数据可由 `SYS-006` / IoT 能力提供采集支撑，但账单生成仍归属 SYS-002。
+
+### 开账触发与结果表达
+
+- 触发前提：正式口径下可按抄表批次、指定客户范围或指定抄表任务范围组织生成；当前 backend 已落地的入口为按 `readingDataIds` 批量复核并开账，对应 `ChargeController.generateCheckChargeBatch`、`ChargeServiceImpl.generateCheckChargeBatch` 与 `ReadingDataServiceImpl.batchReCheckReadingData`。
+- 规则来源：价格归属决定客户适用的价格口径；价格模板、阶梯规则、费用组成和计划用水方案共同决定营业账主表金额与明细拆分方式。
+- 当前承接证据：`ChargeServiceImpl.generateSingleChargeWithCache` 成功路径会写入 `biz_charge` 主表、循环写入 `biz_charge_detail` 明细，并回写抄表数据开账状态，说明现有实现已具备“按抄表数据 ID 生成营业账主明细”的 backend 基础。
+- 结果表达：正式 `IF-REV-005` 应返回成功清单、失败清单、生成汇总及主明细级结果；当前 backend 返回仍为“本次复核成功X条 / 本次开账成功Y条”的字符串拼接，尚未形成结构化成功/失败结果对象。
+- 阻断与限制：价格模板不存在、费用调整配置缺失、结算方式非 `ACTUAL_USAGE` 等场景当前会直接阻断单条生成；其中固定水量、按人口数、最低消费等非实际水量结算方式仍未纳入当前实现。
+- 下游边界：`REV-002` 只负责生成营业账结果并交由后续审核/收费链路消费，不在本章节扩展收费核销、发票申请或催缴执行细节。
 
 ### 核心数据
 
@@ -156,6 +188,20 @@ flowchart TD
 - `biz_cost_component`：费用组成。
 - `biz_water_use_scheme`、`biz_water_use_scheme_tier`：计划用水方案与阶梯。
 
+### 迁移补充（旧系统承接）
+
+#### 特殊开账
+
+- 旧系统支持在非标准客户、无码客户或罚款类场景下直接开账。
+- 新系统仍以 `biz_charge`、`biz_charge_detail` 作为开账结果承载对象，不建议额外平行建设“特殊开账账表”。
+- 迁移与新建场景均需保留特殊开账来源、业务类型、经办人、依据说明、打印状态与后续收费关联，避免与普通抄表开账混淆。
+
+#### 开账记录迁移
+
+- 旧系统“开账记录”是历史查询与账务核对的核心入口，必须纳入迁移最小保留集。
+- 迁移后的开账记录应至少支持按站点、账务年月、册本、客户、抄表员、欠费状态查询，并支持统计水量、总金额及费用构成。
+- 对已收费、已作废、销户拆表、特殊开账等旧状态，不要求照搬旧表结构，但必须保留可对照的新状态映射关系。
+
 ### 接口映射
 
 - `IF-REV-004`：抄表数据提交与异常标记。
@@ -210,6 +256,26 @@ flowchart TD
 - `bk_transaction_callback`：支付回调记录。
 - `bk_transaction_exception`：支付异常记录。
 
+### 迁移补充（旧系统承接）
+
+#### 柜台结账
+
+- 旧系统将“柜台收费”和“柜台结账”拆分为两个菜单，结账阶段包含未结/已结查询、结账红冲、追加抄表和打印动作。
+- 当前设计可继续采用统一收费核销模型，但必须补出“收费记录 → 班结结果 → 打印/红冲/查询”的业务闭环，避免柜面日终处理缺口。
+- 迁移时需保留结账时间、结账人、网点、收费汇总口径和结账后红冲痕迹，保证财务对账与审计连续。
+
+#### 账单打印服务
+
+- 旧系统存在账单打印、补打、打印次数控制与打印记录查询能力。
+- 新系统不要求单独建立打印主模块，但必须明确打印模板、补打权限、打印状态与打印留痕的承接关系。
+- 对历史账单迁移，应允许基于账单主明细和打印配置恢复打印视图，避免割接后只能查账不能补打。
+
+#### 红冲记录
+
+- 旧系统支持红冲记录查询、导出与明细展开，是收费差错追溯的重要入口。
+- 当前设计可将红冲视为收费核销后的修正场景，不强制要求独立实体表，但必须提供历史只读查询口径。
+- 红冲迁移最小保留信息应包括原收费记录、红冲时间、红冲金额、原因、经办人、关联账单和后续账务状态。
+
 ### 接口映射
 
 - `IF-REV-006`：创建收费记录、执行账单核销并回写状态。
@@ -227,7 +293,9 @@ flowchart TD
 
 ### 功能说明
 
-承担水量调整、金额调整、违约金减免、退款、冲正、呆坏账申请等账务修正与审批处理能力，保证收费后账务结果可追溯、可审计。
+REV-004 一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，统一挂靠 `IF-REV-007` 作为账务处理入口，目标是在既有正式文档体系内先收敛范围、承接口径、留痕要求与审批边界。
+
+本阶段按“共性能力先统一、场景能力再分批”组织：先统一账单承接、原交易校验、结果表达、操作留痕与审批边界，再分别展开五类场景。违约金减免、分账调整、价差调整、跨周期水量、预存退款细表等内容仅作为旧系统迁移语义或后续扩展参考，不作为一期新增独立范围。
 
 ### 业务流程
 
@@ -244,26 +312,44 @@ flowchart TD
 
 ### 关键规则
 
-1. 调整类操作以营业账主明细为基础，并通过日志与审批留痕记录前后变化。
-2. 水量调整、金额调整、优惠调整等场景可引用价格模板、阶梯与优惠对象重新计算。
-3. 退款、冲正等交易修正需与原支付流水及渠道状态联动校验。
-4. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。
+1. 一期场景严格限定为水量调整、金额调整、退款、冲正、坏账申请，不扩展到其他接口族或独立账务台账重构。
+2. 所有场景均以 `biz_charge` / `biz_charge_detail` 为主承接对象，并通过 `biz_operat_log` / `biz_operat_log_detail` 记录处理依据、前后变化和责任归属。
+3. 退款、冲正必须联动 `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception` 等原支付流水及渠道状态校验，不允许仅依据账单状态直接处理。
+4. 接口结果统一返回 `resultStatus`、`writeBackStatus`，其中 `resultStatus` 表示处理结论，`writeBackStatus` 表示账单状态回写结论，两者不得混用。
+5. 审批相关内容一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 与审批边界说明，不展开完整 BPM 流程、节点、流转规则或审批回写实现细节。
+6. 对于当前未见明确独立实体表的特账、跨周期水量、退款账等对象，文档以“业务处理场景”表述，不强行落为已实现表。
 
 ### 核心数据
 
-- `biz_charge`、`biz_charge_detail`：账务调整的核心对象。
+- `biz_charge`、`biz_charge_detail`：账务调整的核心对象，承接调整前后账单主明细状态。
+- `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：退款、冲正场景的原交易校验与异常追溯对象。
 - 价格调整/优惠相关表：用于重算账单或差额追溯。
-- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕。
+- `biz_operat_log`、`biz_operat_log_detail`：操作与变更留痕，记录字段差异、处理说明、附件依据与责任归属。
 
 ### 主要场景
 
 | 场景 | 说明 | 控制要点 |
 |---|---|---|
 | 水量调整 | 更正异常水量 | 需复核原因、附件和原抄表依据 |
-| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批链路 |
-| 退款处理 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
-| 错误缴费冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
-| 呆坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批结果 |
+| 金额调整 | 更正账单金额 | 需记录依据、差异金额和审批边界 |
+| 退款 | 退回客户支付资金或预存款 | 需校验原交易、退款余额与幂等性 |
+| 冲正 | 修正误收/误核销记录 | 需关联原交易与账单状态 |
+| 坏账申请 | 对长期欠费进行分类处理 | 需结合账龄、客户状态与审批边界 |
+
+### 迁移补充（旧系统承接）
+
+| 旧账务对象 | 当前承接方式 | 迁移口径 |
+|---|---|---|
+| 预存退款 / 预存退款详情 | 作为账务处理场景承接 | 保留申请单、原支付引用、退款结果与审批留痕 |
+| 已销调整汇总 / 明细 | 作为已收费后修正场景承接 | 保留原账单、调整原因、前后差异、处理结果 |
+| 价差调整汇总 / 明细 | 作为重算与差额修正场景承接 | 保留原价格口径、新价格口径、差额和生效时间 |
+| 分账调整汇总 / 明细 | 作为费用组成重分摊场景承接 | 保留原分摊结果、调整后结果、责任人和审批链 |
+| 账单-违约金减免 | 作为滞纳金修正场景承接 | 保留减免原因、减免金额、审批结果和生效时间 |
+| 账单-呆坏账 | 作为坏账申请与生效场景承接 | 保留账龄、申请原因、审批结果、核销状态 |
+
+1. P0 阶段不要求为每一类旧账务台账都新增独立实体表，但必须在业务对象和历史查询层形成可追溯闭环。
+2. 旧系统精细台账迁移后至少保留：原单据标识、原账单标识、处理类型、处理原因、处理前后金额/水量、申请/审批/生效时间、经办人与附件依据。
+3. 与支付、发票、渠道回调强关联的处理场景，必须保留与原交易、原发票、原收费记录的关联关系，避免后续对账和审计断链。
 
 ### 接口映射
 
@@ -282,27 +368,73 @@ flowchart TD
 
 ### 功能说明
 
-负责发票申请、开票校验、开票结果回写、发票查询、作废与红冲处理，作为营收业务对发票服务的业务接入层。
+负责发票业务闭环的业务接入与状态落账，覆盖后台发票申请、开票校验、`SYS-008` 异步协同、查询兜底、结果回写、账单关联、客户侧已开票电子发票查询/下载/推送，以及后台作废与红冲处理。
 
 ### 业务流程
 
 ```mermaid
 flowchart TD
-    A[提交发票申请] --> B[校验账单与开票信息]
+    A[后台提交发票申请] --> B[校验账单、客户开票信息、税率与限额]
     B --> C{是否满足开票条件}
     C -->|否| D[返回不可开票原因]
-    C -->|是| E[生成发票申请记录]
-    E --> F[调用SYS-008发票服务]
-    F --> G[接收开票结果回写]
-    G --> H[更新发票与账单关联状态]
+    C -->|是| E[生成申请单号并写入SUBMITTED]
+    E --> F[调用SYS-008发起异步开票]
+    F --> G[记录受理号并转为PENDING]
+    G --> H[系统轮询或后台查询兜底]
+    H --> I{开票结果}
+    I -->|成功| J[回写SUCCESS并更新账单-发票关联]
+    I -->|失败| K[回写FAIL并记录失败原因]
+    J --> L[客户侧查询/下载/推送电子发票]
 ```
 
+### 状态说明
+
+- `SUBMITTED`：后台申请已受理，已完成本地校验并生成申请单。
+- `PENDING`：已提交 `SYS-008`，等待异步结果或查询补偿结果。
+- `SUCCESS`：已取得有效发票代码、号码或电子票地址，且账单关联已完成更新。
+- `FAIL`：开票失败，需保留失败原因、最近查询结果与后续人工核查依据。
+- `INVALID`：发票已作废，作为后续能力预留状态。
+- `RED_INK`：发票已红冲，作为后续能力预留状态。
+
 ### 关键规则
 
-1. 发票申请以客户信息、缴费记录、账单信息、税率配置为基础。
-2. 个人与企业开票均通过客户开票信息与税率表完成合法性校验。
-3. 发票开具、作废、红冲由 `SYS-008` 统一承接，SYS-002 负责业务上下文传递与结果落账。
-4. 电子发票可通过客户服务渠道推送或下载。
+1. 一期采用“后台申请开票 + 客户侧查询下载推送”的入口模式，客户侧不直接发起开票申请。
+2. 发票申请以客户信息、已收费未开票账单、税率配置和开票限额为基础；原始单账单不支持直接任意部分金额开票。
+3. 个人与企业开票均通过客户开票信息与税率表完成合法性校验；如需多张发票，沿用拆账/分账后的账单分别开票口径。
+4. `SYS-008` 采用“异步申请 + 查询兜底”模式，成功状态不得被后续失败查询结果覆盖。
+5. 电子发票仅在 `SUCCESS` 且存在票据文件地址时允许客户侧下载或推送。
+6. 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理，`SYS-002` 负责后台触发入口、状态校验、查询补偿、结果落账与日志留痕；当前轮次按二期范围补齐 backend 实现入口。
+
+### 后台申请入口与校验补充
+
+- 后台支持营业收费员、财务人员按单笔或批量已收费账单发起开票申请。
+- 申请时至少校验：账单收费状态、开票状态、客户开票信息完整性、票种适配性、开票限额、账单集合是否属于同一客户。
+- 企业抬头场景重点校验纳税人识别号；电子发票场景重点校验邮箱/手机号；不满足条件时直接返回不可开票原因。
+- 申请成功后生成申请单号并进入 `SUBMITTED/PENDING` 状态流转，失败校验场景不进入外部协同。
+- 幂等控制以 `applicationNo` 或 `custId + chargeIds` 为主，避免相同账单组合重复申请。
+
+### SYS-008 异步协同与查询补偿
+
+- 本地申请校验通过后，`SYS-002` 先写入 `biz_invoice` 申请记录，再向 `SYS-008` 发起异步开票请求，并记录 `sysRequestNo` 作为后续查询与回写的协同主键。
+- `SYS-008` 返回“已受理”后，发票状态转为 `PENDING`；若仅完成本地受理但尚未拿到受理号，则保留 `SUBMITTED` 并进入待补偿查询状态。
+- 查询补偿采用“回写优先、主动查询兜底”原则：`IF-EXT-007` 回写为首选结果来源，后台人工查询与系统定时补偿查询共用同一结果落账逻辑。
+- 系统补偿查询至少保留最近查询时间、下次计划查询时间、累计查询次数、最近一次返回结果摘要与异常原因，便于问题追踪和人工核查。
+- 后台按申请单号或受理号触发查询时，应同步刷新查询上下文；查询仍未取得终态时，仅更新补偿上下文，不得伪造成功或失败结论。
+
+### 终态保护与异常核查
+
+- `SUCCESS` 属于正常开票闭环终态，一旦已取得有效发票代码、发票号码或电子票据地址，后续失败查询结果不得覆盖成功状态。
+- `FAIL` 仅在 `SYS-008` 明确返回失败结论或多次补偿查询确认失败时写入，并同步保留失败原因、最近查询结果与人工核查依据。
+- 当后台人工查询、系统补偿查询与外部回写结果不一致时，应以最新有效外部凭据为准，并记录差异说明，不允许直接覆盖既有成功票据关键信息。
+- 每次提交协同、主动查询、状态变更和异常分支均应写入操作留痕，确保能够追溯责任人、触发来源、状态前后值与异常说明。
+
+### 结果回写、账单关联与客户侧消费
+
+- `IF-EXT-007` 回写成功结果时，除更新 `biz_invoice.invoice_status`、`invoice_code`、`invoice_number`、`file_url` 外，还应同步刷新账单快照、账单关联状态与推送状态初值。
+- 账单关联以 `biz_invoice.charge_id` + `charge_ids_snapshot` 记录本次开票覆盖账单集合，并同步把对应 `biz_charge.invoice_state` 更新为“开票完成”，保留失败原因与开票时间，便于账单明细、收费记录和客户侧结果统一展示。
+- 客户侧查询仅允许按本人 `custId` 访问已存在的发票记录；可通过 `invoiceId`、`applicationNo` 或 `sysRequestNo` 定位，但都必须命中同一客户名下记录。
+- 客户侧下载与推送前必须校验发票状态为 `SUCCESS` 且 `fileUrl` 非空；不满足条件时仅返回不可下载/推送原因，不得伪造文件地址。
+- 推送动作应记录推送渠道、目标邮箱/手机号与结果状态；成功后更新 `pushStatus=PUSHED`，失败则写入 `FAIL` 并保留失败原因供人工处理。
 
 ### 核心数据
 
@@ -310,16 +442,24 @@ flowchart TD
 - `biz_invoice_taxrate`：税率配置。
 - `biz_cust_invoice`：客户开票信息。
 
+### 迁移补充（旧系统承接）
+
+- 旧系统数据字典中存在“发票明细表、营业账开票表、开票配置表”等更细粒度对象。
+- 当前正式设计已明确主承接对象为 `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice`，但迁移时不能忽略旧开票明细和账单关联关系。
+- P0 阶段建议先补三类迁移口径：账单与发票的关联关系、发票申请与结果回写记录、开票配置与税率的有效期；未确认已落地的细表对象仍按“历史只读或辅助映射”处理。
+
 ### 接口映射
 
-- `IF-REV-008`：营收侧发票申请与票据状态查询。
-- `IF-CS-004`：客户侧电子发票申请入口，复用发票申请链路。
+- `IF-REV-008`：后台发票申请接口，负责单笔/批量申请、幂等控制与受理号生成。
+- `IF-REV-009`：发票结果查询接口，负责后台按申请单号/受理号查询以及系统补偿查询。
+- `IF-CS-004`：客户侧电子发票消费接口，负责已开票结果查看、下载、推送。
 - `IF-EXT-007`：发票结果回写协同接口（由发票服务侧回传）。
 
 ### 落地边界
 
-- **已落地**：发票主记录、税率配置、客户开票信息。
+- **已落地**：发票主记录、税率配置、客户开票信息，以及一期正常开票闭环所需的后台申请、查询兜底、结果回写、账单关联与客户侧电子发票消费能力。
 - **部分落地**：发票修改、开票过程留痕在后端中已有相关对象，但整套发票明细/批次类对象尚未全部确认。
+- **二期补齐**：发票作废、红冲及其查询补偿仍由 `SYS-008` 统一承接，但当前轮次补齐后台触发入口、状态流转、结果回写与日志留痕，不再仅停留于文档预留。
 - **文档先行**：发票明细、营业账开票关系等对象仍按设计能力描述，不表述为本轮已确认独立表。
 
 <a id="mod-rev-006"></a>
@@ -328,41 +468,89 @@ flowchart TD
 
 ### 功能说明
 
-针对欠费账单按账龄、金额、客户类别等规则生成催缴任务，通过短信、微信、站内通知等方式触达客户，并回写催缴结果。
+针对欠费账单按账龄、金额、客户类别等规则生成催缴任务，通过短信、微信、站内通知等方式触达客户，并回写催缴结果；本模块同时定义催缴与停复水/工单处置之间的联动边界与追溯关系，但不展开停复水内部处置流程。
 
 ### 业务流程
 
 ```mermaid
 flowchart TD
     A[生成欠费客户清单] --> B[按策略分组催缴任务]
-    B --> C[触发催缴接口]
-    C --> D[调用SYS-010消息服务]
+    B --> C[触发IF-REV-013生成催缴任务]
+    C --> D[调用IF-EXT-008协同SYS-010]
     D --> E[接收发送结果回写]
     E --> F[更新催缴状态与后续策略]
+    F --> G[按联动边界挂接停复水/工单处置]
 ```
 
 ### 关键规则
 
-1. 催缴策略以营业账状态、欠费金额、账龄分布和客户类别为基础。
-2. 自动催缴与人工催缴可并行，支持停复水等后续处置联动。
-3. 触达能力由 `SYS-010` 提供，SYS-002 负责生成待发送业务事件、催缴名单与结果回写。
-4. 当前后端中部分催缴汇总、停水明细对象未确认独立落表，文档中保持保守描述。
+1. 催缴策略以营业账状态、欠费金额、账龄分布、客户类别和渠道偏好为基础，支持按策略编码进行任务分组与频控。
+2. 自动催缴与人工催缴可并行；自动任务用于常规批量催缴，人工任务用于补发、核查或例外处置。
+3. `SYS-002` 负责催缴对象筛选、任务生成、业务事件编号、结果承接与历史查询；`SYS-010` 负责短信、微信公众号、站内信等触达执行与结果回传。
+4. `REV-006` 正式结果状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态，其中 `MANUAL_VERIFIED` 仅用于外部结果未定或需人工核查补记的场景。
+5. 停复水在本模块中仅定义联动触发条件、处置引用与追溯关系，不展开停复水内部审批、派工或现场执行流程。
+6. 当前后端中部分催缴汇总、停水明细对象未确认独立落表，文档中保持保守描述，不误写为已确认在线主表。
+
+#### 催缴对象筛选、排除与频控边界
+
+- `IF-REV-013` 任务生成前必须完成候选筛选，筛选最小维度为：欠费状态、欠费金额、账龄分组、客户类别、渠道偏好和策略编码。
+- 候选对象必须以有效欠费账单为前提；以下场景不得进入正式催缴任务：已收费核销、已作废、已进入不允许催缴的处置流程、策略规则未命中。
+- 触发类型按 `triggerType` 区分自动与人工；自动用于批量触发，人工用于补发、核查和例外补记，不改变正式接口编号与状态语义。
+- 频控以“同客户/同策略/同渠道/同账期窗口”为最小拦截单元；命中频控时允许部分阻断，并返回被跳过对象及原因摘要。
 
 ### 核心数据
 
 - `biz_charge`、`biz_charge_detail`：催缴对象来源。
 - 催缴结果与通知日志：通过业务状态与消息结果联动留痕。
 
+#### 催缴对象与规则摘要
+
+- `Reminder Candidate`：由欠费账单、客户类别、账龄分组、欠费金额、联系方式集合和命中策略编码组成，是催缴任务的输入对象。
+- `Reminder Strategy`：定义账龄规则、金额规则、客户类别规则、渠道优先级、重复触达拦截窗口和是否触发后续处置关注。
+- `Reminder Task`：一次正式催缴执行单元，至少包含 `taskNo`、`eventNo`、`strategyCode`、`channelType`、`triggerType`、`status` 和关联账单信息；正式业务接口编号固定为 `IF-REV-013`。
+- `Reminder Result`：承接 `IF-EXT-008` 回传结果后由业务侧映射的正式四态结果，最少记录 `status`、`lastCallbackTime`、`failReason` 与回传摘要。
+- `Disposal Link`：用于记录催缴结果与停水、复水、工单或人工跟进之间的关联引用，只承担追溯职责，不替代下游业务对象。
+
+#### 四态与人工核查边界
+
+- `PENDING`：已生成任务并完成外部受理或等待外部终态回传，尚未形成业务终态。
+- `SUCCESS`：外部触达结果明确成功，且业务侧已完成结果承接。
+- `FAIL`：外部返回明确失败或业务判定失败，必须记录失败原因。
+- `MANUAL_VERIFIED`：仅用于外部结果长期未定、人工核查补记或例外核销说明场景；必须留存核查说明与核查人。
+- 人工核查是状态收口手段，不得用于绕过候选筛选、排除条件或频控约束。
+
+### 迁移补充（旧系统承接）
+
+#### 催缴记录
+
+- 旧系统支持催缴记录查询、导出和明细展开，记录中包含推送内容、号码、方式、结果等信息。
+- 新系统可继续以消息协同结果和账单状态联动承接，但必须明确催缴记录查询口径，而不能仅保留“已发送/未发送”状态。
+- 历史查询最少保留客户号、账期、催缴方式、发送对象、发送时间、执行结果、关联账单、关联处置引用等字段，并兼容四态结果或其历史映射值。
+- 历史催缴记录按只读口径承接，作为查询与追溯来源，不反推为已确认在线主表。
+
+#### 停水记录
+
+- 停水记录不是孤立账务对象，应由催缴结果、业务处置和现场执行工单共同形成闭环。
+- 迁移后需支持按客户、站点、停水原因、停水时间、复水状态查询，并能追溯到对应欠费账单和工单执行结果。
+- 正式设计只定义“何时建立联动、如何保存处置引用、如何追溯关联结果”，不在 `REV-006` 中展开停复水内部流程设计。
+- 停复水关联以 `Disposal Link` 的处置引用承接，最少包含任务号、处置类型、处置引用号和建联时间。
+
+#### 预存短信
+
+- 旧系统对预存款余额不足客户提供短信推送和发送记录查询。
+- 新系统建议将其纳入催缴与通知统一策略，不再单建平行模型，但必须保留触发条件、发送内容、发送结果和补发记录。
+- 该类记录与催缴记录一样，按历史只读口径承接，不表述为新增同名在线主表。
+
 ### 接口映射
 
-- `IF-REV-009`：催缴名单生成、任务下发与执行结果返回。
+- `IF-REV-013`：催缴任务生成、任务查询与结果承接接口，负责业务侧任务生成、四态状态维护和历史查询挂接。
 - `IF-EXT-008`：消息协同结果回写接口（由 `SYS-010` 协同）。
 
 ### 落地边界
 
-- **已落地**：以营业账为基础的欠费识别与消息协同前提数据。
-- **部分落地**：催缴登记汇总、停水汇总等对象暂未在 backend 中确认独立表。
-- **文档先行**：复杂催缴台账与停复水统计仅作为业务场景保留。
+- **已落地**：以营业账为基础的欠费识别前提数据、催缴对象来源字段和消息协同边界约束。
+- **部分落地**：催缴登记汇总、停水汇总等对象暂未在 backend 中确认独立表，当前以业务事件、操作留痕和历史查询口径承接。
+- **文档先行**：复杂催缴台账、停复水统计和人工核查界面仅作为业务场景保留，不表述为 backend 已完成能力。
 
 <a id="mod-rev-007"></a>
 
@@ -370,30 +558,42 @@ flowchart TD
 
 ### 功能说明
 
-提供营收、抄表、收费、欠费、渠道、客户、工单等多维度统计分析能力，为经营分析和业务监管提供数据支撑。
+提供营收、抄表、收费、欠费、渠道、客户等多维度统计查询能力，为经营分析、业务监管和迁移核查提供统一的数据口径支撑；本模块以经营查询为主，不扩展到预测分析、专题大屏或独立 BI 平台实现。
 
 ### 关键设计
 
-1. 报表统计基于客户、账单、收费、渠道、时间、片区等维度聚合。
-2. 常用统计口径包括售水量、收费金额、欠费规模、渠道占比、客户类型分布、抄表完成率等。
-3. 导出与查询结果受数据权限控制，重点报表可采用预聚合或物化结果提升查询性能。
+1. 统计查询按“主题 + 维度 + 指标”三层口径组织，避免仅以报表名称堆砌需求。
+2. 主题范围至少包括营收汇总、收费与实收统计、欠费规模与账龄统计、客户结构统计、渠道交易统计、抄表完成率统计以及营收相关业务概览类摘要。
+3. 查询维度至少包括时间区间、账期、营业所/片区、客户类别、渠道、客户/账户、状态等，并支持必要的分组汇总。
+4. 指标口径需明确区分应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、抄表完成率等相近但不等价的统计概念。
+5. 导出与查询结果受数据权限控制；导出属于查询扩展能力，但不在本轮展开具体导出实现细节。
+6. 重点查询可按聚合视图、汇总口径或预聚合结果承接，但不将未确认存在的统计表、专题分析表或离线数仓对象写成已实现事实。
 
 ### 核心数据
 
 - 客户维度：`biz_cust`、`biz_account`。
 - 抄表维度：`biz_meter_book`、`biz_reading_data`、`biz_last_reading`。
 - 账务与收费维度：`biz_charge`、`biz_charge_detail`。
+- 收费与交易维度：`biz_collection`、`bk_transaction`。
 - 渠道维度：`bk_transaction`、`bk_payment_channel`。
+- 组织与权限维度：`system_dept`、数据权限控制结果。
+
+#### 统计主题与口径摘要
+
+- `Statistics Theme`：按经营主题组织查询，至少覆盖营收、收费、欠费、客户、渠道、抄表完成率和必要的业务概览。
+- `Statistics Dimension`：按时间、账期、营业所/片区、客户类别、渠道、客户/账户、状态等条件筛选或分组。
+- `Statistics Indicator`：至少明确应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、完成率等指标含义和单位。
+- `Aggregation Source`：统计结果以现有在线主数据聚合、视图或汇总口径承接，不反推为已存在独立统计表族。
 
 ### 接口映射
 
-- `IF-REV-010`：营收、收费、欠费、渠道、客户等统计查询接口。
+- `IF-REV-010`：营收、收费、欠费、渠道、客户等统计查询接口，承接主题查询、维度筛选、指标汇总和权限/导出边界。
 
 ### 落地边界
 
-- **已落地**：主要统计源数据在客户、抄表、收费、渠道等领域均已具备。
-- **部分落地**：部分分析结果更多依赖报表层实现，而非单独分析表。
-- **文档先行**：预测类、专题分析类深度模型暂不写成后端已实现能力。
+- **已落地**：主要统计源数据在客户、抄表、账单、收费、交易和渠道等领域均已具备，足以支撑经营统计口径设计。
+- **部分落地**：部分统计结果可能依赖聚合视图、汇总查询或报表层实现，当前未见明确的 backend 统计控制器或独立统计模型入口。
+- **文档先行**：预测类、专题分析类深度模型、BI 大屏和独立数仓能力暂不写成后端已实现能力。
 
 <a id="mod-rev-008"></a>
 
@@ -436,6 +636,20 @@ flowchart TD
 - `bk_transaction`、`bk_transaction_callback`、`bk_transaction_exception`：交易、回调、异常。
 - `biz_collection`、`biz_withholding`：代收/代扣业务主对象。
 
+### 迁移补充（旧系统承接）
+
+#### 银行托收
+
+- 旧系统“银行托收”菜单重点承接托收送盘、托收信息查询和托收结果回看。
+- 当前设计已形成 `biz_collection` + `bk_*` 渠道模型，迁移时应补出“旧托收菜单 → 托收批次/交易/回盘结果”的映射，而不是按旧菜单名平移建模。
+- 旧托收历史记录应至少保留送盘批次、客户范围、送盘结果、回盘结果和账单核销结果。
+
+#### 实时收费查询与对账
+
+- 旧系统“实时收费”更偏运营查询和渠道对账入口，不只是支付成功回写。
+- 当前建议以 `bk_transaction*` 作为主承接对象，并补充按结算日期、银行/渠道、收费结果、差异状态查询和导出能力说明。
+- 对旧“实时收费汇总/日志/明细”对象，P0 阶段先按历史只读查询口径保留，不误写为当前已落地的独立主模型。
+
 ### 接口映射
 
 - `IF-REV-011`：代扣批次、对账与结算协同入口。
@@ -467,6 +681,13 @@ flowchart TD
 - `biz_page_settings`、`biz_page_settings_detail`：页面配置。
 - `biz_price_category`、`biz_price_template`、`biz_template_dept_rel`：价格归属与模板站点关系。
 - `biz_cust_no_rule`：客户编号规则。
+ - `sys_wechat_app_settings`：微信/微网厅基础配置。
+
+### 迁移补充（旧系统承接）
+
+- 旧系统后台存在“页面配置、业务字段、微信参数、打印维护”等运营配置入口。
+- 当前建议统一按业务参数、页面配置、渠道参数与打印参数归口承接，不新增“微客服后台配置”并行主文档。
+- 迁移时需明确三类配置映射：客户/业务办理字段展示与校验规则、微信/微网厅基础参数、打印模板与补打策略；未确认已实现的高级灰度能力继续按“文档先行”处理。
 
 ### 接口映射
 

docs/design/02_Detailed_Design/13_CS_Detailed.md

@@ -4,7 +4,7 @@ doc_role: module_body
 authority: secondary
 scope: 详细设计-客户服务
 source_of_truth: false
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-18
 retrieval_priority: P1
 ---
 
@@ -13,6 +13,7 @@ retrieval_priority: P1
 ## 章节导航（精简）
 
 - [文档定位](#sec-position)
+- [架构图模块对齐说明](#sec-cs-alignment)
 - [客户服务详细设计正文](#sec-content)
   - [客户服务模块统一约束](#sec-cs-rules)
   - [接口与数据追溯矩阵](#sec-cs-trace)
@@ -30,6 +31,28 @@ retrieval_priority: P1
 
 本文档为 `01_Detailed_Design.md` 中“客户服务模块详细设计”章节的模块正文拆分稿，便于按模块独立维护。正式交付口径以主详设为准。
 
+<a id="sec-cs-alignment"></a>
+
+## 架构图模块对齐说明
+
+整体架构图中，客户渠道相关模块同时使用了 `CS-*` 与 `WECHAT-*` 两套编号：
+
+- `CS-*` 用于 `SYS-002` 营收业务子系统中的客户服务模块群表达；
+- `WECHAT-*` 用于 `SYS-004` 微网厅子系统中的渠道形态表达。
+
+当前详细设计采用“能力域优先”的承接方式，即以 `CS-*` 作为正式详细设计编号，将 `WECHAT-*` 视为渠道侧同源能力映射，不另建平行正式主稿。
+
+| 架构图模块 | 当前详设承接章节 | 说明 |
+| --- | --- | --- |
+| `WECHAT-001` 账户绑定管理 | `CS-001` | 微网厅渠道形态映射到统一账户绑定能力 |
+| `WECHAT-002` 信息查询服务 | `CS-002` | 微网厅账单、发票、流水查询能力映射 |
+| `WECHAT-003` 在线缴费服务 | `CS-003` | 微网厅渠道缴费入口映射 |
+| `WECHAT-004` 电子发票服务 | `CS-004` | 微网厅电子发票查看/推送/下载映射 |
+| `WECHAT-005` 营业网点服务 | `CS-005` | 微网厅网点查询与预约引导映射 |
+| `WECHAT-006` 业务办理服务 | `CS-006` | 微网厅线上办理入口映射 |
+| `WECHAT-007` 账户流水 | `CS-002` | 当前并入信息查询服务，不单列平行正文 |
+| `WECHAT-008` 账号与机构管理 | `CS-001` | 当前并入账户绑定与账户切换能力 |
+
 <a id="sec-content"></a>
 
 # 客户服务模块详细设计
@@ -62,7 +85,7 @@ retrieval_priority: P1
 
 <a id="mod-cs-001"></a>
 
-## CS-001 账户绑定管理
+## CS-001 账户绑定管理（对齐 WECHAT-001 / WECHAT-008）
 
 ### 功能说明
 
@@ -93,7 +116,7 @@ retrieval_priority: P1
 
 <a id="mod-cs-002"></a>
 
-## CS-002 信息查询服务
+## CS-002 信息查询服务（对齐 WECHAT-002 / WECHAT-007）
 
 ### 功能说明
 
@@ -127,7 +150,7 @@ retrieval_priority: P1
 
 <a id="mod-cs-003"></a>
 
-## CS-003 在线缴费服务
+## CS-003 在线缴费服务（对齐 WECHAT-003）
 
 ### 功能说明
 
@@ -172,7 +195,7 @@ flowchart TD
 
 <a id="mod-cs-004"></a>
 
-## CS-004 电子发票服务
+## CS-004 电子发票服务（对齐 WECHAT-004）
 
 ### 功能说明
 
@@ -204,7 +227,7 @@ flowchart TD
 
 <a id="mod-cs-005"></a>
 
-## CS-005 营业网点服务
+## CS-005 营业网点服务（对齐 WECHAT-005）
 
 ### 功能说明
 
@@ -233,7 +256,7 @@ flowchart TD
 
 <a id="mod-cs-006"></a>
 
-## CS-006 业务办理服务
+## CS-006 业务办理服务（对齐 WECHAT-006）
 
 ### 功能说明
 

docs/design/02_Detailed_Design/14_METER_Detailed.md

@@ -4,7 +4,7 @@ doc_role: module_body
 authority: secondary
 scope: 详细设计-表务管理
 source_of_truth: false
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-18
 retrieval_priority: P1
 ---
 
@@ -17,9 +17,8 @@ retrieval_priority: P1
   - [表务模块统一约束](#sec-meter-rules)
   - [接口与数据追溯矩阵](#sec-meter-trace)
   - [METER-001 表务基础管理](#mod-meter-001)
-  - [METER-002 表务工单管理](#mod-meter-002)
-  - [METER-003 仓储与生命周期管理](#mod-meter-003)
-  - [METER-004 物联网接入与数据同步](#mod-meter-004)
+  - [METER-002 仓库与库存管理](#mod-meter-002)
+  - [METER-003 设备档案管理](#mod-meter-003)
 
 <a id="sec-position"></a>
 
@@ -50,9 +49,8 @@ retrieval_priority: P1
 | METER 模块 | 关键接口 | 核心数据域（摘要） | 主要协同对象 |
 |---|---|---|---|
 | METER-001 表务基础管理 | `IF-METER-001` | `biz_meter`、`biz_meter_model`、`biz_meter_caliber`、`biz_meter_range` | 营收、报装 |
-| METER-002 表务工单管理 | `IF-METER-002` | `biz_meter_log`、`biz_process`、`biz_process_transfer` | 移动作业、工单流转 |
-| METER-003 仓储与生命周期管理 | `IF-METER-003` | `biz_meter_in_out`、`biz_meter_in_out_rel`、`biz_meter` | 仓储管理端 |
-| METER-004 物联网接入与数据同步 | `IF-METER-004` | `biz_meter_read`、`biz_reading_data`、`biz_last_reading` | IoT 平台、营收开账 |
+| METER-002 仓库与库存管理 | `IF-METER-003` | `biz_meter_in_out`、`biz_meter_in_out_rel`、`biz_meter` | 仓储管理端 |
+| METER-003 设备档案管理 | `IF-METER-001`、`IF-METER-002`、`IF-METER-004` | `biz_meter`、`biz_meter_log`、`biz_process*`、`biz_meter_read`、`biz_reading_data`、`biz_last_reading` | 工单系统、移动作业、IoT 平台、营收开账 |
 
 <a id="mod-meter-001"></a>
 
@@ -89,60 +87,16 @@ retrieval_priority: P1
 
 <a id="mod-meter-002"></a>
 
-## METER-002 表务工单管理
+## METER-002 仓库与库存管理
 
 ### 功能说明
 
-处理换表、移表、拆表、复装、校表、稽查、维修等表务工单。
-
-### 业务流程
-
-```mermaid
-flowchart TD
-    A[创建表务工单] --> B[派发现场任务]
-    B --> C[现场处理并采集结果]
-    C --> D[回写旧表/新表信息]
-    D --> E[更新水表状态与客户绑定]
-    E --> F[写入过程日志与附件]
-    F --> G[工单办结]
-```
-
-### 关键设计
-
-1. 工单类型决定必填字段、处理流程和附件要求。
-2. 换表工单需同时记录旧表拆除信息与新表安装信息。
-3. 表务工单完成后同步更新水表档案与客户绑定关系。
-
-### 核心数据
-
-- `biz_meter_log`：表务过程留痕。
-- `biz_process`：工单流程主表。
-- `biz_process_transfer`：转办与流转记录。
-- `biz_meter`：表计状态回写对象。
-
-### 接口映射
-
-- `IF-METER-002`：换表、移表、校表、维修等处理结果提交。
-- `IF-CS-006`：客户渠道办理结果与表务工单协同。
-
-### 落地边界
-
-- **已落地**：表务工单过程留痕、流程流转与状态回写能力。
-- **部分落地**：不同工单类型的细化节点主要依赖流程配置，不一定全部存在独立业务表。
-- **文档先行**：复杂多部门并行会签和跨区域协同不宣称为当前独立实现模块。
-
-<a id="mod-meter-003"></a>
-
-## METER-003 仓储与生命周期管理
-
-### 功能说明
-
-管理新表入库、领用、出库、退库、报废及全生命周期追踪。
+管理新表入库、领用、出库、退库、报废及库存预警，是架构图中“仓库与库存管理”模块的正式承接章节。
 
 ### 关键设计
 
 1. 库存动作以批次和明细双层结构记录，支持领用、退库、报废等全过程追溯。
-2. 水表生命周期状态与库存动作联动更新，避免“账上在库、现场在用”不一致。
+2. 库存状态与设备生命周期联动更新，避免“账上在库、现场在用”不一致。
 3. 报废、退库等高风险动作需保留审批或责任人留痕。
 
 ### 核心数据
@@ -158,13 +112,46 @@ flowchart TD
 
 ### 落地边界
 
-- **已落地**：出入库主明细、生命周期状态回写、动作留痕。
+- **已落地**：出入库主明细、库存状态回写、动作留痕。
 - **部分落地**：仓位优化、库龄分析等能力可能通过报表层实现，而非独立业务对象。
-- **文档先行**：跨仓调拨优化和自动补货策略仅保留设计方向。
+- **文档先行**：自动补货策略与仓网优化仅保留设计方向。
+
+<a id="mod-meter-003"></a>
+
+## METER-003 设备档案管理
+
+### 功能说明
+
+管理水表唯一电子档案、状态流转、安装历史、质检追溯，并统一承接表务工单和物联网同步相关能力。
+
+### 关键设计
+
+1. 一块水表对应唯一档案主记录，覆盖在库、在用、待检、故障、报废等状态。
+2. 设备档案同时关联安装历史、维修记录、库存动作与最近有效读数，形成全生命周期追溯闭环。
+3. 表务工单和远传同步能力属于设备档案管理下的实施态支撑能力，不再作为独立模块编号表达。
+
+### 核心数据
+
+- `biz_meter`：水表主档与状态主对象。
+- `biz_meter_log`：设备过程留痕与工单回写对象。
+- `biz_process`、`biz_process_transfer`：表务工单流程主线。
+- `biz_meter_read`、`biz_reading_data`、`biz_last_reading`：读数、状态与同步对象。
+
+### 接口映射
+
+- `IF-METER-001`：查询水表档案、状态与生命周期信息。
+- `IF-METER-002`：换表、移表、校表、维修等处理结果提交。
+- `IF-METER-004`：远传抄表、告警与状态同步接收。
+
+### 落地边界
+
+- **已落地**：设备主档、状态流转、工单留痕、远传同步与异常标记能力。
+- **部分落地**：质检批次、厂家评价、复杂设备健康评分等附属对象可能由扩展字段、附件或报表层承接。
+- **文档先行**：预测性维护和实时控制指令不作为当前正式实现口径。
 
 <a id="mod-meter-004"></a>
 
-## METER-004 物联网接入与数据同步
+### 物联网接入与数据同步能力
 
 ### 功能说明
 
@@ -208,3 +195,27 @@ flowchart TD
 - **已落地**：远传数据接入、基础校验、异常标记与读数同步。
 - **部分落地**：复杂设备诊断与厂家私有协议适配更多由外部 IoT 平台承载。
 - **文档先行**：边缘计算、实时控制指令等能力不作为当前正式实现口径。
+
+<a id="mod-meter-002-workflow"></a>
+
+### 表务工单协同能力
+
+处理换表、移表、拆表、复装、校表、稽查、维修等表务工单，是 `METER-003` 设备档案管理的实施态过程能力。
+
+#### 业务流程
+
+```mermaid
+flowchart TD
+    A[创建表务工单] --> B[派发现场任务]
+    B --> C[现场处理并采集结果]
+    C --> D[回写旧表/新表信息]
+    D --> E[更新水表状态与客户绑定]
+    E --> F[写入过程日志与附件]
+    F --> G[工单办结]
+```
+
+#### 关键规则
+
+1. 工单类型决定必填字段、处理流程和附件要求。
+2. 换表工单需同时记录旧表拆除信息与新表安装信息。
+3. 工单完成后同步更新设备档案、客户绑定关系与安装历史。

docs/design/02_Detailed_Design/15_INST_Detailed.md

@@ -4,7 +4,7 @@ doc_role: module_body
 authority: secondary
 scope: 详细设计-报装与签章
 source_of_truth: false
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-18
 retrieval_priority: P1
 ---
 
@@ -16,11 +16,9 @@ retrieval_priority: P1
 - [报装与签章详细设计正文](#sec-content)
   - [报装模块统一约束](#sec-inst-rules)
   - [接口与数据追溯矩阵](#sec-inst-trace)
-  - [INST-001 报装申请与受理](#mod-inst-001)
-  - [INST-002 现场踏勘与方案设计](#mod-inst-002)
-  - [INST-003 施工验收与立户通水](#mod-inst-003)
-  - [INST-004 合同签署与电子签章](#mod-inst-004)
-  - [INST-005 档案归档与过程留痕](#mod-inst-005)
+  - [INST-001 报装流程管理](#mod-inst-001)
+  - [INST-002 工程管理](#mod-inst-002)
+  - [INST-003 档案管理](#mod-inst-003)
 
 <a id="sec-position"></a>
 
@@ -50,19 +48,17 @@ retrieval_priority: P1
 
 | INST 模块 | 关键接口 | 核心数据域（摘要） | 主要协同对象 |
 |---|---|---|---|
-| INST-001 报装申请与受理 | `IF-INST-001` | `biz_process`、`biz_content`、`biz_content_attach` | 柜台、微网厅、政务平台 |
-| INST-002 现场踏勘与方案设计 | `IF-INST-002` | `biz_process_transfer`、`biz_business_datas` | 报装人员 |
-| INST-003 施工验收与立户通水 | `IF-INST-005` | `biz_process_meter_install`、`biz_process`、`biz_meter` | 表务、客户建档 |
-| INST-004 合同签署与电子签章 | `IF-INST-003`、`IF-INST-004` | `installation_contract`、`installation_signature`、`installation_evidence` | 泛微 CA |
-| INST-005 档案归档与过程留痕 | `IF-INST-005` | `biz_content_attach`、`installation_evidence`、过程日志 | 报装、档案管理 |
+| INST-001 报装流程管理 | `IF-INST-001`、`IF-INST-002` | `biz_process`、`biz_content`、`biz_content_attach`、`biz_process_transfer`、`biz_business_datas` | 柜台、微网厅、政务平台、报装人员 |
+| INST-002 工程管理 | `IF-INST-003`、`IF-INST-004`、`IF-INST-005` | `biz_process_meter_install`、`biz_process`、`biz_meter`、`installation_contract`、`installation_signature`、`installation_evidence` | 表务、客户建档、泛微 CA |
+| INST-003 档案管理 | `IF-INST-005` | `biz_content_attach`、`installation_evidence`、过程日志 | 报装、档案管理 |
 
 <a id="mod-inst-001"></a>
 
-## INST-001 报装申请与受理
+## INST-001 报装流程管理
 
 ### 功能说明
 
-支持新装、改造、一户一表等业务的申请受理、资料提交、受理审核与流程发起。
+承接新装、改造、一户一表等业务从申请受理到现场踏勘、方案编制的前半段主流程，是架构图中“报装流程管理”模块的正式承接章节。
 
 ### 业务流程
 
@@ -93,17 +89,18 @@ flowchart TD
 ### 接口映射
 
 - `IF-INST-001`：提交报装申请、申请资料与附件。
+- `IF-INST-002`：回填踏勘结果、方案、审核结果。
 - `IF-CS-006`：客户渠道办理入口可复用报装申请主线。
 
 ### 落地边界
 
 - **已落地**：申请受理主流程、资料与附件采集、流程实例创建。
-- **部分落地**：不同报装类型的细化受理规则更多依赖流程和参数配置。
+- **部分落地**：不同报装类型的细化受理规则、踏勘方案差异更多依赖流程和参数配置。
 - **文档先行**：`installation_application` 当前按设计态保留，不宣称为实施库既有事实表。
 
 <a id="mod-inst-002"></a>
 
-## INST-002 现场踏勘与方案设计
+### 踏勘与方案设计能力
 
 ### 功能说明
 
@@ -146,11 +143,11 @@ flowchart TD
 
 <a id="mod-inst-003"></a>
 
-## INST-003 施工验收与立户通水
+## INST-002 工程管理
 
 ### 功能说明
 
-完成施工派工、安装实施、竣工验收、立户建档和通水确认。
+承接施工派工、安装实施、竣工验收、立户通水以及合同签章协同，是架构图中“工程管理”模块的正式承接章节。
 
 ### 业务流程
 
@@ -181,6 +178,8 @@ flowchart TD
 ### 接口映射
 
 - `IF-INST-005`：归档验收资料并提交最终办结信息。
+- `IF-INST-003`：发起电子签章任务并传输合同信息。
+- `IF-INST-004`：回写签章结果、时间戳和存证信息。
 - `IF-METER-001`、`IF-METER-002`：装表与表务状态协同。
 - `IF-REV-001`：立户后客户主档进入营收主数据域。
 
@@ -192,7 +191,7 @@ flowchart TD
 
 <a id="mod-inst-004"></a>
 
-## INST-004 合同签署与电子签章
+### 合同签署与电子签章能力
 
 ### 功能说明
 
@@ -275,7 +274,7 @@ sequenceDiagram
 
 <a id="mod-inst-005"></a>
 
-## INST-005 档案归档与过程留痕
+## INST-003 档案管理
 
 ### 功能说明
 

docs/design/02_Detailed_Design/README.md

@@ -18,6 +18,11 @@
 - `14_METER_Detailed.md`：表务模块正文
 - `15_INST_Detailed.md`：报装与签章模块正文
 
+## 上游对齐基线
+
+- 总体层模块枚举与承接关系以 `../01_Overview/05_Module_Inventory.md` 作为核对入口；
+- 当架构图中的模块名称与当前详设正文命名不完全一致时，应优先补充“映射说明”，而不是直接新建平行详设文件。
+
 ## 维护原则
 
 - 详细设计应与概要设计、数据库设计、接口设计保持一致

docs/design/03_Technical_Design/01_Database_Design.md

@@ -4,7 +4,7 @@ doc_role: master_document
 authority: primary
 scope: 数据库设计
 source_of_truth: true
-last_reviewed: 2026-03-11
+last_reviewed: 2026-03-12
 retrieval_priority: P0
 ---
 
@@ -27,7 +27,7 @@ retrieval_priority: P0
 | 【 】草稿 | | |
 | 【 】修改稿 | | |
 | 【√】正式发布 | | |
-| | **当前版本：** | **V1.5** |
+| | **当前版本：** | **V1.6** |
 | | **作者：** | **唐伟杰** |
 | | **完成日期：** | **2025-08-01** |
 
@@ -40,6 +40,7 @@ retrieval_priority: P0
 | 2025-08-01 | V1.2 | 唐伟杰 | 1. 根据详细设计说明书调整目录结构，按6个子系统重新组织表结构。<br>2. 补充移动端表设计优化说明，明确移动端与Web端表复用策略。<br>3. 新增5个移动端特有表的详细设计，符合表设计优化原则。 |
 | 2025-08-01 | V1.3 | 唐伟杰 | 数据库系统变更：将OpenGauss替换为达梦数据库 8.0+，作为主力国产数据库方案。 |
 | 2025-08-01 | V1.4 | 唐伟杰 | 单点登录采用OAuth2.0协议：新增OAuth2.0相关数据表设计，包括客户端信息表、访问令牌表、刷新令牌表、授权码表。 |
+| 2026-03-12 | V1.6 | 唐伟杰 | 补充旧系统历史台账迁移与只读查询口径，明确在线主模型承接范围、历史最小保留集与迁移验收对账基线。 |
 
 <a id="sec-preface"></a>
 # 前言
@@ -52,7 +53,7 @@ retrieval_priority: P0
 - **数据库工具**: 使用 Navicat, DBeaver, DataGrip 等主流数据库管理工具。
 - **约定**:
   - **表名**: 全部小写，单词间使用下划线 `_` 分隔。业务表以 `biz_` 开头，系统管理表以 `system_` 开头。
-  - **字段名**: 全部小写，驼峰式命名（如 `userId`），与Java实体类属性保持一致。
+  - **字段名**: 全部小写，单词间使用下划线 `_` 分隔（如 `user_id`），与当前数据库主文档及主表命名口径保持一致。
   - **主键**: 统一命名为 `id`，类型为 `bigint`，自增。
   - **通用字段**: 所有表必须包含 `id`, `creator`, `create_time`, `updater`, `update_time`, `deleted`, `tenant_id` 字段。
   - **字符集**: 统一使用 `utf8mb4` 字符集。
@@ -1095,6 +1096,25 @@ retrieval_priority: P0
 | `unit_price` | 单价 |
 | `detail_amount` | 明细金额 |
 
+#### REV-002 账单生成承接口径
+
+| 对象 | 正式口径 | 承接说明 |
+| :--- | :--- | :--- |
+| `biz_charge` | 账单生成主结果对象 | 统一表达客户、账期、抄表/开账来源、账单总金额、收费状态与应缴日期，不单独发明新的在线账单主模型 |
+| `biz_charge_detail` | 账单生成明细对象 | 统一表达费用组成、用量、单价、明细金额，与主表通过 `charge_id` 建立主明细关系 |
+| `biz_price_category`、`biz_price_template`、`biz_price_adjustment_snap`、`biz_price_tier_adjustment` | 计费规则来源对象 | 用于表达价格归属、基础价格、调价快照与阶梯规则来源，支撑账单金额计算与追溯 |
+| `biz_cost_component` | 费用组成定义对象 | 用于表达水费、污水费、附加费、罚款类费用等明细分类，不将费用组成直接硬编码到主表 |
+| `biz_water_use_scheme`、`biz_water_use_scheme_tier`、`biz_exceed_water_use_scheme` | 计划用水与超计划规则对象 | 用于承接计划用水、超计划与阶梯类扩展规则，不额外发明平行的特殊开账规则表 |
+| 历史开账记录、特殊开账 | 历史只读 / 同模型承接对象 | 统一纳入 `biz_charge`、`biz_charge_detail` 与操作留痕承接，通过来源类型、业务类型、依据说明区分，不单设“特殊开账表” |
+
+> REV-002 承接口径：账单生成结果统一由 `biz_charge`、`biz_charge_detail` 承接，关键规则来源继续由 `biz_price_*`、`biz_cost_component` 与计划用水相关对象提供；当价格模板、费用组成或规则关系不完整时，应按“阻断生成”口径处理。
+>
+> 当前 backend 证据：`ChargeServiceImpl.generateSingleChargeWithCache` 成功路径已执行 `chargeMapper.insert(charge)`、`chargeDetailService.insertChargeDetail(detail)` 与 `updateReadingDataCheckState(readingDataId, 1)`，说明现有实现已能把按 `readingDataIds` 复核/开账的结果落入 `biz_charge`、`biz_charge_detail`。
+>
+> 当前承接缺口：接口层返回仍为成功条数字符串，失败阻断主要依赖日志与布尔值，且仅支持 `ACTUAL_USAGE` 结算方式；`biz_charge` / `biz_charge_detail` 的主明细结果、失败对象范围和结构化原因尚未提升为正式 `IF-REV-005` 契约返回。
+>
+> REV-004 承接口径：水量调整、金额调整、退款、冲正、坏账申请统一以 `biz_charge`、`biz_charge_detail` 作为账单主明细承接对象；当前数据库主文档不新增独立账务细表来承接一期场景。
+
 ### biz_collection / biz_withholding (托收与代扣主表)
 | 表名 | 关键字段 | 说明 |
 | :--- | :--- | :--- |
@@ -1104,17 +1124,71 @@ retrieval_priority: P0
 ### biz_invoice / biz_invoice_taxrate (发票主表与税率表)
 | 表名 | 关键字段 | 说明 |
 | :--- | :--- | :--- |
-| `biz_invoice` | `code`, `cust_id`, `charge_id`, `invoice_status`, `invoice_amount` | 发票主表 |
+| `biz_invoice` | `code`, `cust_id`, `charge_id`, `invoice_status`, `invoice_amount` | 发票主表，统一承接申请单号、账单关联、受理号、开票结果与电子票地址等核心状态 |
 | `biz_invoice_taxrate` | `tax_code`, `tax_name`, `tax_rate`, `status` | 税率基础配置 |
 
+#### REV-005 发票承接口径
+
+| 对象 | 已有字段 | 待补字段 | 仅快照/历史只读字段 |
+| :--- | :--- | :--- | :--- |
+| `biz_invoice` 发票申请/结果主对象 | `code`、`cust_id`、`charge_id`、`invoice_status`、`invoice_amount` | `application_no`、`sys_request_no`、`invoice_type`、`invoice_title`、`tax_no`、`email`、`mobile`、`source_channel`、`fail_reason`、`invoice_code`、`invoice_number`、`file_url`、`last_try_time`、`next_try_time`、`try_count`、`push_status`、`charge_ids_snapshot`、`charge_bind_status`、作废原因/备注、红冲原因/备注、原票/红票关联标识、作废/红冲申请来源、补偿查询/结果回写上下文 | 旧开票批次号、旧配置版本号、旧平台扩展回执 |
+| `biz_cust_invoice` 客户开票信息 | `cust_id`、`invoice_title`、`tax_no`、`email`、`mobile` | 企业/个人抬头类型、默认推送方式等扩展属性按后续实现补齐 | 旧抬头版本、历史修改快照 |
+| `biz_invoice_taxrate` 税率配置 | `tax_code`、`tax_name`、`tax_rate`、`status` | 税率生效区间、适用票种范围等扩展控制字段 | 旧税率版本快照 |
+| 账单-发票关系快照 | 当前主模型通过 `biz_invoice` 与 `biz_charge*` 关联承接 | `charge_ids_snapshot`、账单集合来源、客户侧身份匹配结果、操作留痕标识 | 旧营业账开票关系表、旧发票明细表 |
+
 ### biz_operat_log / biz_operat_log_detail (操作留痕表)
 | 表名 | 关键字段 | 说明 |
 | :--- | :--- | :--- |
 | `biz_operat_log` | `biz_type`, `biz_id`, `operate_user`, `operate_time` | 业务操作主日志 |
 | `biz_operat_log_detail` | `log_id`, `field_name`, `before_value`, `after_value` | 字段级变更留痕 |
 
+> REV-004 留痕口径：`biz_operat_log*` 统一承接账务处理的一期留痕，至少覆盖处理类型、目标账单、原交易引用、处理前后差异、原因说明、附件依据与操作人。
+>
 > 边界说明：旧数据字典中的“跨周期水量、特账、红冲、已销调整、呆坏账、实时收费日志”等对象，在当前 backend 范围内未全部识别到独立实体表，数据库专项中统一按业务处理场景描述，不误写为已明确落地的真实表。
 
+### 旧系统历史台账迁移与只读查询口径
+
+#### 在线主模型承接范围
+
+| 旧对象/旧菜单 | 当前主口径 | 承接方式 | 数据策略 |
+| :--- | :--- | :--- | :--- |
+| 开账记录、特殊开账 | `biz_charge`、`biz_charge_detail`、`biz_operat_log*` | 统一纳入营业账主表与明细表，特殊开账按来源类型、业务类型、依据说明留痕，不单设平行“特殊开账表” | 在线保留 |
+| 柜台收费、实时收费、代收代扣 | `biz_collection`、`biz_withholding`、`bk_transaction*`、`bk_withholding_*` | 统一纳入收费主模型与渠道交易模型，柜台班结/实时收费日志按交易结果和操作留痕归并 | 在线保留 |
+| 发票申请、开票结果、票据税率 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` | 统一纳入发票主表、税率表和客户开票信息，不为旧“营业账开票表”机械复制新在线表 | 在线保留 |
+| 微网厅业务字段、页面配置、微信参数 | `biz_business_types`、`biz_business_datas`、`biz_page_settings*`、`biz_parameter_settings`、`sys_wechat_app_settings` | 统一归并为业务类型、页面配置和渠道参数模型 | 在线保留 |
+| 办理附件、电子档案 | `biz_content`、`biz_content_attach` | 当前新增与迁移后新增资料统一按资料主表与附件表承接 | 在线保留 |
+
+#### 历史只读保留范围
+
+| 历史对象 | 当前正式口径 | 保留策略 | 查询要求 |
+| :--- | :--- | :--- | :--- |
+| 红冲记录、红冲原因、红冲前后账务快照 | 账单状态 + 账务处理场景 + 操作留痕 | 保留历史只读，不强制拆为新主库独立实体表 | 至少支持原单号、红冲单号、金额、原因、经办人、时间查询 |
+| 预存退款、已销调整、价差调整、分账调整、违约金减免、呆坏账明细 | `REV-004` 账务处理业务场景 | 旧细粒度台账以历史只读方式保留；新发生业务由流程与日志承接 | 至少支持汇总、明细、状态、审批结果和关联账单查询 |
+| 柜台结账、打印记录、补打记录 | 收费结果 + 打印/操作留痕 | 旧查询菜单作为历史只读能力保留，不单独建设新结账台账表 | 至少支持班次、营业所、柜员、打印类型、结账状态查询 |
+| 发票明细、营业账开票关系、开票配置快照 | 发票主模型 + 历史关系快照 | 旧细表和配置快照按历史只读保留；新在线模型只保留开票必需主数据 | 至少支持发票号、账单号、开票批次、配置版本和结果状态查询 |
+| 催缴记录、停水记录、预存短信记录 | 催缴/停复水/消息联动业务场景 | 旧记录菜单按历史只读保留，与 `IF-REV-013` 的任务结果、通知链路和工单处置引用分层承接，不新增同名在线主表 | 至少支持客户、账期、催缴方式、执行结果、发送对象、发送时间、关联账单、处置引用查询 |
+| 水表检定、领用、出库、退库、报废单据 | `METER-003` 生命周期场景 | 当前在线主表承接水表状态，旧单据与检定证书按历史只读保留 | 至少支持表号、仓库、单据类型、检定结论、证书编号查询 |
+
+#### 迁移验收最低对账口径
+
+| 对账主题 | 最低核对维度 | 主口径来源 | 验收要求 |
+| :--- | :--- | :--- | :--- |
+| 开账记录 | 客户数、账单数、账期、应收金额 | `biz_charge`、`biz_charge_detail` + 历史账单来源 | 支持按账期、营业所、客户类型汇总比对 |
+| 缴费记录 | 收费笔数、实收金额、渠道、核销状态 | `biz_collection`、`bk_transaction*` | 支持按渠道、日期、营业所汇总比对 |
+| 发票记录 | 开票笔数、金额、状态、票据类型 | `biz_invoice*` + 历史开票关系 | 支持按发票状态、开票日期比对 |
+| 红冲与账务调整 | 调整笔数、调整金额、处理结果 | 账务处理结果 + 历史台账 | 支持汇总与单据级差异定位 |
+| 催缴与停复水 | 通知笔数、执行结果、停复水状态 | `IF-REV-013` 任务结果 + 历史记录 | 支持按账期、客户、执行状态、处置引用比对 |
+| 电子档案 | 附件数、附件类型、关联业务单数 | `biz_content_attach` + 历史档案目录 | 支持按业务类型、上传时间、来源系统比对 |
+
+#### 设计约束
+
+- 不以“旧菜单一项对应一张新表”为原则，优先复用当前已确认的 `biz_*`、`bk_*` 在线主模型。
+- 对 backend 当前未识别到独立实体表的旧细粒度台账，仅写为“历史只读查询对象”，不误写为“已存在新在线表”。
+- 历史只读对象必须保留原系统关键标识（原单号、原客户号、原批次号或原附件标识）以支撑迁移验收与问题追溯。
+- 涉及历史附件、影像、高拍仪资料时，正式数据库设计只约束“资料元数据 + 文件引用”口径，不在本轮臆造新的文件表族。
+- `REV-006` 的正式结果状态按 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态统一，数据库设计仅约束查询与追溯口径，不反推为已存在独立催缴结果主表。
+- 停复水、复水和工单处置在本轮仅保留“关联引用 + 状态摘要 + 建链时间”三类追溯字段要求，不展开下游业务表设计。
+
 ## SYS-002 业务办理与资料表 (`biz_process*` / `biz_business_*` / `biz_content*`)
 
 | 表名 | 关键字段 | 说明 |
@@ -1140,6 +1214,8 @@ retrieval_priority: P0
 | `bk_transaction` | `trade_no`, `biz_order_no`, `channel_code`, `trade_amount`, `trade_status` | 渠道交易流水 |
 | `bk_transaction_callback` | `trade_no`, `callback_time`, `callback_status`, `raw_message` | 回调留痕 |
 | `bk_transaction_exception` | `trade_no`, `exception_code`, `exception_desc`, `handle_status` | 异常处理 |
+
+> REV-004 原交易校验口径：退款、冲正场景统一依赖 `bk_transaction*` 校验原交易存在性、状态、回调结果与异常处理状态，数据库专项不再为一期新增平行退款交易表。
 | `bk_withholding_agreement` | `agreement_no`, `cust_id`, `channel_code`, `sign_status` | 代扣签约 |
 | `bk_withholding_batch` | `batch_no`, `channel_code`, `batch_date`, `batch_status` | 代扣批次 |
 | `bk_withholding_item` | `batch_id`, `cust_id`, `charge_id`, `item_status` | 代扣明细 |
@@ -1831,6 +1907,32 @@ WHERE t.deleted = 0
 GROUP BY t.id, t.name;
 ```
 
+### REV-007 统计承接口径
+
+#### 设计定位
+
+- `REV-007` 以在线业务主数据聚合、视图或汇总口径支撑经营统计查询，不在本轮确认独立统计仓库、离线批处理表或专题分析表族。
+- 统计结果必须能够追溯到现有客户、账单、收费、交易、抄表和组织维度数据来源。
+- 当前数据库主文档仅约束“统计查询如何承接”，不反推 backend 已存在专门统计模块或已固化全部统计视图。
+
+#### 最小统计主题承接口径
+
+| 统计主题 | 主数据来源 | 最低维度要求 | 最低指标要求 | 承接方式 |
+| :--- | :--- | :--- | :--- | :--- |
+| 营收汇总 | `biz_charge`、`biz_charge_detail` | 时间、账期、营业所、客户类别 | 应收金额、账单数、用水量 | 在线聚合 / 汇总口径 |
+| 收费与实收统计 | `biz_collection`、`bk_transaction` | 时间、渠道、营业所、收费状态 | 实收金额、收费笔数、成功率 | 在线聚合 / 汇总口径 |
+| 欠费规模与账龄统计 | `biz_charge`、`biz_charge_detail` | 账期、账龄、客户类别、区域 | 欠费余额、欠费户数、账龄分布 | 在线聚合 / 汇总口径 |
+| 客户结构统计 | `biz_cust`、`biz_account` | 客户类别、区域、状态 | 客户数、账户数、活跃状态分布 | 在线聚合 / 视图口径 |
+| 渠道交易统计 | `bk_transaction`、`bk_payment_channel` | 渠道、日期、结果状态 | 交易笔数、交易金额、渠道占比 | 在线聚合 / 汇总口径 |
+| 抄表完成率统计 | `biz_meter_book`、`biz_reading_data`、`biz_last_reading` | 抄表周期、册本、片区、人员 | 应抄户数、已抄户数、完成率 | 在线聚合 / 汇总口径 |
+
+#### 设计约束
+
+- 统计查询可以由视图、临时汇总结果或聚合 SQL 承接，但未确认存在的 `stat_*`、`report_*` 或专题报表表不得写成正式已实现对象。
+- 若某类统计仅在历史资料中出现而当前主文档未形成正式口径，应先作为后续专题保留项，不直接扩写为当前正式范围。
+- 涉及历史迁移核查的统计比对时，历史来源只承担补充核对职责，不替代在线主数据统计结果。
+- 导出能力属于查询扩展能力，数据库设计不单独为导出动作臆造新的物理表。
+
 <a id="sec-index-performance"></a>
 # 索引设计与性能优化
 

docs/design/03_Technical_Design/03_Interface_Design.md

@@ -28,6 +28,7 @@ retrieval_priority: P0
 - [内部接口设计](#sec-internal-interface)
 - [数据对象与表口径](#sec-data-object)
 - [接口安全与异常处理](#sec-security-exception)
+- [历史查询与迁移校验接口口径](#sec-migration-readonly)
 - [实现状态说明](#sec-status)
 
 <a id="sec-scope"></a>
@@ -230,9 +231,15 @@ retrieval_priority: P0
 | 归属模块 | REV-006 / CS-006 |
 | 调用方向 | SYS-002 → SYS-010 |
 | 接口方式 | HTTPS REST 或 MQ |
-| 业务说明 | 发送催缴通知、办理进度通知、缴费结果通知等消息事件 |
+| 业务说明 | 承接催缴通知、办理进度通知、缴费结果通知等消息事件，返回受理结果并回传执行结果 |
 | 核心数据支撑 | `biz_charge`、`biz_process`、`biz_operat_log` |
 
+边界约束：
+- `IF-EXT-008` 只负责渠道触达执行与回执回传，不负责催缴候选对象筛选、任务生成或业务状态主控。
+- `SYS-010` 回传的渠道执行结果需由 `SYS-002` 映射为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态业务状态。
+- 当仅返回受理成功但未返回终态时，`SYS-002` 维持 `PENDING`；若长期无终态且人工核查确认，可转 `MANUAL_VERIFIED`。
+- 消息模板、供应商协议和重试细节由 `SYS-010` 管理，不在 `IF-EXT-008` 展开实现细节。
+
 ### IF-EXT-009 集抄数据接入接口
 
 | 项目 | 说明 |
@@ -261,8 +268,9 @@ retrieval_priority: P0
 | IF-REV-005 | 账单生成接口 | REV-002 | 根据抄表结果、价格模板和费用组成生成账单 | `biz_charge`、`biz_charge_detail`、`biz_price_template`、`biz_cost_component` |
 | IF-REV-006 | 缴费处理接口 | REV-003 | 创建收费记录、核销账单、回写收款结果 | `biz_collection`、`biz_charge`、`bk_transaction` |
 | IF-REV-007 | 账务调整接口 | REV-004 | 发起金额调整、退款、冲正、坏账等业务处理 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` |
-| IF-REV-008 | 发票申请接口 | REV-005 | 发起开票申请并接收票据状态回写 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` |
-| IF-REV-009 | 催缴任务接口 | REV-006 | 生成催缴名单并提交消息触达请求 | `biz_charge`、`biz_operat_log` |
+| IF-REV-008 | 发票申请接口 | REV-005 | 后台发起单笔/批量开票申请并生成受理主键 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` |
+| IF-REV-009 | 发票结果查询接口 | REV-005 | 按申请单号/受理号查询开票结果并执行补偿查询 | `biz_invoice`、`biz_operat_log` |
+| IF-REV-013 | 催缴任务生成与结果承接接口 | REV-006 | 生成催缴任务、查询任务结果并承接四态状态回写 | `biz_charge`、`biz_operat_log`、历史催缴查询口径 |
 | IF-REV-010 | 统计查询接口 | REV-007 | 查询营收、收费、欠费、渠道、客户统计结果 | 聚合视图 / 统计结果集 |
 | IF-REV-011 | 银行代收协同接口 | REV-008 | 发起代扣、回盘、对账、结算协同 | `biz_withholding`、`bk_reconcile_batch`、`bk_settlement_batch` |
 | IF-REV-012 | 业务参数配置接口 | REV-009 | 查询和维护价格模板、优惠方案、业务参数配置 | `biz_parameter_settings`、`biz_price_*`、`biz_page_settings*` |
@@ -274,7 +282,7 @@ retrieval_priority: P0
 | IF-CS-001 | 账户绑定接口 | CS-001 | 绑定、解绑、切换默认客户 | `biz_cust_app_binds`、`biz_cust` |
 | IF-CS-002 | 历史账单查询接口 | CS-002 | 查询账单、欠费、用水历史、缴费记录 | `biz_charge`、`biz_charge_detail`、`biz_reading_data` |
 | IF-CS-003 | 在线支付下单接口 | CS-003 | 创建微信/支付宝线上支付订单 | `biz_charge`、`biz_collection`、`bk_transaction` |
-| IF-CS-004 | 发票申请接口 | CS-004 | 提交电子发票申请、查询发票状态 | `biz_invoice`、`biz_cust_invoice` |
+| IF-CS-004 | 电子发票消费接口 | CS-004 | 查询、下载、推送本人已开具电子发票 | `biz_invoice`、`biz_cust_invoice` |
 | IF-CS-005 | 网点与业务办理接口 | CS-005 | 查询营业网点、预约信息、可办事项 | `biz_outlets`、`biz_business_types` |
 | IF-CS-006 | 业务办理进度接口 | CS-006 | 提交业务申请、查询办理进度与附件 | `biz_process`、`biz_process_transfer`、`biz_content_attach` |
 | IF-CS-007 | 柜面扫码支付接口 | CS-007 | 创建柜面扫码支付订单并回写结果 | `biz_collection`、`bk_transaction`、`biz_charge` |
@@ -293,19 +301,19 @@ retrieval_priority: P0
 | 接口编号 | 接口名称 | 归属模块 | 主要用途 | 主要数据对象 |
 |---------|----------|----------|----------|-------------|
 | IF-METER-001 | 水表档案查询接口 | METER-001 | 查询水表档案、状态与生命周期信息 | `biz_meter`、`biz_meter_model`、`biz_meter_caliber`、`biz_meter_range` |
-| IF-METER-002 | 表务工单处理接口 | METER-002 | 提交换表、移表、校表、维修等工单处理结果 | `biz_meter_log`、`biz_process`、`biz_process_transfer` |
-| IF-METER-003 | 库存出入库接口 | METER-003 | 处理领用、退库、报废等库存动作 | `biz_meter_in_out`、`biz_meter_in_out_rel` |
-| IF-METER-004 | 集抄数据接收接口 | METER-004 | 接收远传抄表、异常告警并同步状态 | `biz_reading_data`、`biz_meter_read`、`biz_last_reading` |
+| IF-METER-002 | 表务工单处理接口 | METER-003 | 提交换表、移表、校表、维修等工单处理结果 | `biz_meter_log`、`biz_process`、`biz_process_transfer` |
+| IF-METER-003 | 库存出入库接口 | METER-002 | 处理领用、退库、报废等库存动作 | `biz_meter_in_out`、`biz_meter_in_out_rel` |
+| IF-METER-004 | 集抄数据接收接口 | METER-003 | 接收远传抄表、异常告警并同步状态 | `biz_reading_data`、`biz_meter_read`、`biz_last_reading` |
 
 ### INST 接口清单
 
 | 接口编号 | 接口名称 | 归属模块 | 主要用途 | 主要数据对象 |
 |---------|----------|----------|----------|-------------|
 | IF-INST-001 | 报装申请提交接口 | INST-001 | 提交报装申请、附件与基础资料 | `biz_process`、`biz_content`、`biz_content_attach` |
-| IF-INST-002 | 踏勘结果回填接口 | INST-002 | 回填现场踏勘、方案与审核结果 | `biz_process_transfer`、`biz_business_datas` |
-| IF-INST-003 | 合同签署发起接口 | INST-004 | 发起电子签章任务并传输合同信息 | `installation_contract`、`installation_signature` |
-| IF-INST-004 | 签章回执接口 | INST-004 | 回写签章结果、时间戳和存证信息 | `installation_signature`、`installation_evidence` |
-| IF-INST-005 | 报装归档接口 | INST-005 | 归档申请、合同、验收与签章回执资料 | `biz_content_attach`、`installation_evidence` |
+| IF-INST-002 | 踏勘结果回填接口 | INST-001 | 回填现场踏勘、方案与审核结果 | `biz_process_transfer`、`biz_business_datas` |
+| IF-INST-003 | 合同签署发起接口 | INST-002 | 发起电子签章任务并传输合同信息 | `installation_contract`、`installation_signature` |
+| IF-INST-004 | 签章回执接口 | INST-002 | 回写签章结果、时间戳和存证信息 | `installation_signature`、`installation_evidence` |
+| IF-INST-005 | 报装归档接口 | INST-003 | 归档申请、合同、验收与签章回执资料 | `biz_content_attach`、`installation_evidence` |
 
 ## 关键内部接口说明
 
@@ -370,9 +378,21 @@ retrieval_priority: P0
 | 归属模块 | REV-002 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/revenue/charge/generate` |
-| 功能描述 | 基于抄表结果、水价模板、阶梯规则、费用组成生成账单 |
+| 功能描述 | 基于抄表结果、水价模板、阶梯规则、费用组成生成账单，并返回成功清单、失败清单与生成汇总 |
 | 核心表 | `biz_charge`、`biz_charge_detail`、`biz_price_template`、`biz_price_tier_adjustment`、`biz_cost_component` |
 
+边界约束：
+- 本接口只负责抄表校验完成后的账单生成，不直接承接收费核销、发票申请、催缴执行或统计汇总。
+- 正式请求范围可按抄表批次、客户集合或抄表任务集合组织；当前 backend 已实现入口为 `/business/charge/charge-batch` 与 `/business/charge/check-charge-batch`，请求体仅接受 `readingDataIds`。
+- 价格模板、费用组成、阶梯规则、计划用水方案等任一关键规则缺失时，应阻断生成并返回失败原因，而不是生成不完整账单。
+- 特殊开账、无码客户开账、罚款类开账等非标准来源仍沿用同一 `biz_charge` / `biz_charge_detail` 承接口径，不单设平行在线账表。
+- 当前实现仅支持 `SettleTypeEnum.ACTUAL_USAGE`；固定水量、按人口数、最低消费等结算方式暂未纳入现有开账链路。
+
+当前 backend 证据与契约缺口：
+- `ChargeServiceImpl.generateCheckChargeBatch` 已支持“批量复核 + 批量开账”，并通过 `generateSingleChargeWithCache` 写入 `biz_charge`、`biz_charge_detail`，说明主明细承接路径已存在。
+- 返回值当前为 `CommonResult<String>`，仅表达“本次复核成功X条 / 本次开账成功Y条”，尚未提供正式契约要求的成功清单、失败清单、生成汇总和主明细结果对象。
+- 单条失败当前主要以 `log.warn` + `false` 跳过处理，尚未形成可直接对外返回的结构化阻断码、失败原因集合与对象范围。
+
 ### IF-REV-006 缴费处理接口
 
 | 项目 | 说明 |
@@ -392,8 +412,14 @@ retrieval_priority: P0
 | 归属模块 | REV-004 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/revenue/accounting/adjust` |
-| 功能描述 | 发起金额调整、水量调整、退款、冲正、坏账等账务处理 |
-| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` |
+| 功能描述 | 发起水量调整、金额调整、退款、冲正、坏账申请五类账务处理，并统一返回处理结果、审批边界与账单回写状态 |
+| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log`、`bk_transaction*` |
+
+边界约束：
+- 一期仅覆盖 `USAGE`、`AMOUNT`、`REFUND`、`REVERSE`、`BAD_DEBT` 五类 `adjustType`。
+- 退款、冲正必须提供 `sourceTradeNo` 并完成原交易校验；其他场景不得误用支付流水替代业务依据。
+- 审批相关内容仅保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明，不展开 BPM 节点与审批回写实现细节。
+- `resultStatus` 与 `writeBackStatus` 必须分离表达，前者表示处理结论，后者表示账单状态回写结论。
 
 ### IF-REV-008 发票申请接口
 
@@ -402,24 +428,60 @@ retrieval_priority: P0
 | 接口编号 | IF-REV-008 |
 | 归属模块 | REV-005 |
 | 请求方式 | POST |
-| 请求路径 | `/admin-api/revenue/invoice/apply` |
-| 功能描述 | 发起电子发票或纸质发票申请，并调用 SYS-008 |
+| 请求路径 | `/business/invoice/apply` |
+| 功能描述 | 后台对已收费未开票账单发起单笔/批量开票申请，并在同一管理域内受理作废/红冲后处理入口 |
 | 核心表 | `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` |
 
 边界约束：
-- 发票开具、作废、红冲能力由 `SYS-008` 统一承接。
-- `SYS-002` 仅负责业务单据归集、申请发起与结果落账。
+- 一期仅支持后台营业收费员/财务人员发起申请，客户侧不直接调用本接口。
+- 发票开具、作废、红冲能力均由 `SYS-008` 统一承接税控侧处理，`SYS-002` 负责业务单据归集、申请发起、后台作废/红冲触发、查询补偿与结果落账。
+- 后台发票后处理沿同一管理域补充 `/business/invoice/invalidate` 与 `/business/invoice/red-ink` 两个入口，分别承接作废与红冲动作；处理结果继续通过 `IF-REV-009` 或 `IF-EXT-007` 统一收口。
+- 原始单账单不支持直接任意部分金额开票；如需多张发票，应基于拆账/分账后的账单集合申请。
 
-### IF-REV-009 催缴任务接口
+### IF-REV-009 发票结果查询接口
 
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-REV-009 |
+| 归属模块 | REV-005 |
+| 请求方式 | POST |
+| 请求路径 | `/business/invoice/query`（补偿查询：`/business/invoice/query/compensate`） |
+| 功能描述 | 后台按申请单号/受理号查询开票、作废或红冲结果，并支持系统补偿查询兜底 |
+| 核心表 | `biz_invoice`、`biz_operat_log` |
+
+### IF-REV-013 催缴任务生成与结果承接接口
+
+| 项目 | 说明 |
+|------|------|
+| 接口编号 | IF-REV-013 |
 | 归属模块 | REV-006 |
 | 请求方式 | POST |
-| 请求路径 | `/admin-api/revenue/arrears/remind-task/create` |
-| 功能描述 | 生成催缴名单、调用消息服务并回写催缴任务执行结果 |
-| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log` |
+| 请求路径 | `/admin-api/revenue/reminder/task`（查询：`/admin-api/revenue/reminder/task/query`，人工核查：`/admin-api/revenue/reminder/task/manual-verify`） |
+| 功能描述 | 基于欠费账单、催缴策略和渠道偏好生成催缴任务，查询任务状态，并承接业务侧四态结果与处置引用 |
+| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_operat_log`、历史催缴查询口径 |
+
+边界约束：
+- `IF-REV-013` 是 `REV-006` 的正式业务接口编号，不再复用 `IF-REV-009`。
+- `SYS-002` 负责催缴对象筛选、任务生成、业务事件号维护、四态状态承接和历史查询；`SYS-010` 只负责触达执行与结果回传。
+- 接口状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态，不在本轮扩展“已阅读”“已补发”等细粒度业务状态。
+- 停复水仅作为联动边界与处置引用承接项，不在本接口中展开停复水内部流程。
+
+### IF-REV-010 统计查询接口
+
+| 项目 | 说明 |
+|------|------|
+| 接口编号 | IF-REV-010 |
+| 归属模块 | REV-007 |
+| 请求方式 | POST |
+| 请求路径 | `/admin-api/revenue/statistics/query`（导出：`/admin-api/revenue/statistics/export`） |
+| 功能描述 | 面向营收经营分析场景查询统计主题、维度汇总和指标结果，并在权限范围内支持导出 |
+| 核心表 | `biz_charge`、`biz_charge_detail`、`biz_collection`、`bk_transaction`、`biz_cust`、`biz_account`、`biz_meter_book`、`biz_reading_data` |
+
+边界约束：
+- `IF-REV-010` 只承接经营统计查询，不扩展到预测分析、BI 专题大屏或独立数仓查询。
+- 统计口径按“主题 + 维度 + 指标”组织，避免仅以报表名称表达接口范围。
+- 导出属于查询扩展能力，必须受数据权限和导出权限控制。
+- 没有明确实现证据的独立统计表、专题分析表或离线汇总表不得写成既成事实。
 
 ### IF-REV-011 银行代收协同接口
 
@@ -480,17 +542,21 @@ retrieval_priority: P0
 - 支付通道、支付回调、对账流水由 `SYS-009` 负责。
 - `SYS-002` 负责校验待缴账单、生成业务订单、更新核销结果。
 
-### IF-CS-004 发票申请接口
+### IF-CS-004 电子发票消费接口
 
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-CS-004 |
 | 归属模块 | CS-004 |
 | 请求方式 | POST |
-| 请求路径 | `/app-api/customer/invoice/apply` |
-| 功能描述 | 面向客户渠道提交电子发票申请并查询开票状态 |
+| 请求路径 | `/business/invoice/customer/query`、`/business/invoice/customer/download`、`/business/invoice/customer/push` |
+| 功能描述 | 面向客户渠道查询、下载、推送本人已开具电子发票 |
 | 核心表 | `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate` |
 
+边界约束：
+- 一期客户侧仅消费已形成 `SUCCESS` 终态且具备票据地址的电子发票结果，不直接发起开票申请。
+- 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理；`IF-CS-004` 仅消费当前仍可展示、下载、推送的有效电子发票结果，不开放客户侧直接发起作废或红冲。
+
 ### IF-CS-006 业务办理进度接口
 
 | 项目 | 说明 |
@@ -529,7 +595,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-METER-002 |
-| 归属模块 | METER-002 |
+| 归属模块 | METER-003 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/meter/work-order/handle` |
 | 功能描述 | 提交换表、移表、校表、维修等工单处理结果并回写设备状态 |
@@ -540,7 +606,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-METER-003 |
-| 归属模块 | METER-003 |
+| 归属模块 | METER-002 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/meter/stock/in-out` |
 | 功能描述 | 处理领用、退库、报废等库存动作并更新生命周期状态 |
@@ -551,7 +617,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-METER-004 |
-| 归属模块 | METER-004 |
+| 归属模块 | METER-003 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/meter/iot/reading/receive` |
 | 功能描述 | 接收远传抄表、设备状态和异常告警并同步读数状态 |
@@ -573,7 +639,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-INST-002 |
-| 归属模块 | INST-002 |
+| 归属模块 | INST-001 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/installation/survey/result` |
 | 功能描述 | 回填现场踏勘结果、方案版本和审核结论 |
@@ -584,7 +650,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-INST-003 |
-| 归属模块 | INST-004 |
+| 归属模块 | INST-002 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/installation/contract/sign/initiate` |
 | 功能描述 | 发起报装合同签署流程，并与 CA 系统协同处理签章、时间戳和存证 |
@@ -595,7 +661,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-INST-004 |
-| 归属模块 | INST-004 |
+| 归属模块 | INST-002 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/installation/contract/sign/callback` |
 | 功能描述 | 回写签章结果、时间戳、存证回执与签章文件地址 |
@@ -606,7 +672,7 @@ retrieval_priority: P0
 | 项目 | 说明 |
 |------|------|
 | 接口编号 | IF-INST-005 |
-| 归属模块 | INST-005 |
+| 归属模块 | INST-003 |
 | 请求方式 | POST |
 | 请求路径 | `/admin-api/installation/archive/submit` |
 | 功能描述 | 归档申请资料、验收附件、合同文件与签章回执 |
@@ -759,6 +825,7 @@ retrieval_priority: P0
 
 | 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
 |------|------|------|------|---------------|
+| applicationNo | String | 否 | 发票申请单号 | 服务端生成，作为幂等主键之一 |
 | custId | Long | 是 | 客户 ID | `biz_invoice.cust_id` |
 | chargeIds | Array<Long> | 是 | 开票关联账单 ID 列表 | 业务单据关联 |
 | invoiceType | String | 是 | 发票类型：`ELECTRONIC`、`PAPER` | `biz_invoice.invoice_type` |
@@ -766,45 +833,182 @@ retrieval_priority: P0
 | taxNo | String | 否 | 税号 | `biz_cust_invoice.tax_no` |
 | email | String | 否 | 电子发票接收邮箱 | `biz_cust_invoice.email` |
 | mobile | String | 否 | 接收手机号 | `biz_cust_invoice.mobile` |
-| taxRateCode | String | 否 | 税率编码 | `biz_invoice_taxrate.tax_code` |
+| sourceChannel | String | 是 | 来源渠道：`COUNTER`、`FINANCE_BACKOFFICE` | 业务来源 |
+| remark | String | 否 | 申请备注 | 操作留痕 |
 
 #### 响应参数
 
 | 字段 | 类型 | 说明 | 主要来源 |
 |------|------|------|----------|
 | invoiceId | Long | 发票申请记录 ID | `biz_invoice.id` |
-| invoiceCode | String | 发票申请编号 | `biz_invoice.code` |
-| invoiceStatus | String | 状态：`INIT`、`APPLYING`、`SUCCESS`、`FAIL` | `biz_invoice.invoice_status` |
-| requestNo | String | 发往 SYS-008 的请求号 | 协同流水 |
-| fileUrl | String | 发票文件地址，成功后返回 | 结果回写 |
+| applicationNo | String | 发票申请单号 | `biz_invoice.application_no` |
+| invoiceStatus | String | 状态：`SUBMITTED`、`PENDING`、`REJECTED` | `biz_invoice.invoice_status` |
+| sysRequestNo | String | 发往 `SYS-008` 的受理号 | 协同流水 |
 | msg | String | 处理说明 | 返回消息 |
 
-### IF-REV-009 催缴任务接口
+#### 申请校验与幂等约束
+
+- 所有关联账单必须满足“已收费、未开票、未作废”。
+- 一期不支持原始单账单直接任意部分金额开票；如需多张发票，必须基于拆账/分账后的账单集合发起申请。
+- 企业抬头场景应校验 `taxNo` 完整性；电子发票场景优先校验 `email` 或 `mobile` 至少一项可用。
+- 幂等键优先使用 `applicationNo`，未传入时按 `custId + chargeIds` 组合控制重复申请。
+- 申请成功后必须创建查询补偿上下文，不依赖回调作为唯一结果来源。
+
+#### 后台作废请求参数（`/business/invoice/invalidate`）
+
+| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
+|------|------|------|------|---------------|
+| invoiceId | Long | 是 | 发票记录 ID | `biz_invoice.id` |
+| invalidReason | String | 是 | 作废原因 | `biz_invoice.invalid_reason` |
+| invalidRemark | String | 否 | 作废备注 | `biz_invoice.invalid_remark` |
+| originalInvoiceCode | String | 否 | 原发票代码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_code` |
+| originalInvoiceNumber | String | 否 | 原发票号码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_number` |
+
+#### 后台红冲请求参数（`/business/invoice/red-ink`）
+
+| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
+|------|------|------|------|---------------|
+| invoiceId | Long | 是 | 发票记录 ID | `biz_invoice.id` |
+| redInkReason | String | 是 | 红冲原因 | `biz_invoice.red_ink_reason` |
+| redInkRemark | String | 否 | 红冲备注 | `biz_invoice.red_ink_remark` |
+| originalInvoiceCode | String | 否 | 原发票代码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_code` |
+| originalInvoiceNumber | String | 否 | 原发票号码；传入时必须与当前发票记录一致 | `biz_invoice.original_invoice_number` |
+
+#### 后台作废/红冲处理约束
+
+- 作废与红冲仅允许对当前 `invoiceStatus=SUCCESS` 的记录发起；已进入 `INVALID` 或 `RED_INK` 的记录必须拒绝重复处理。
+- 后台提交作废或红冲后，应同步写入原因、备注、原票引用与触发来源，当前实现的触发来源分别为 `ADMIN_INVALIDATE`、`ADMIN_RED_INK`。
+- 作废与红冲的即时返回仅表示后台已受理本次后处理动作；最终状态仍通过 `IF-REV-009` 查询补偿或 `IF-EXT-007` 回写统一收口。
+- 后处理动作必须保留操作日志，记录触发人、目标状态、原因、备注与原发票代码/号码。
+
+### IF-REV-009 发票结果查询接口
 
 #### 请求参数
 
 | 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
 |------|------|------|------|---------------|
-| taskType | String | 是 | 任务类型：`AUTO`、`MANUAL` | 任务参数 |
-| billPeriod | String | 否 | 账期范围 | `biz_charge.bill_period` |
-| minArrearsAmount | Decimal | 否 | 最小欠费金额 | 任务筛选条件 |
-| overdueDays | Integer | 否 | 最小逾期天数 | 任务筛选条件 |
-| templateCode | String | 是 | 消息模板编码 | 模板参数 |
-| channelList | Array<String> | 是 | 发送渠道列表，如 `SMS`、`WECHAT`、`APP` | 消息参数 |
-| customerScope | Array<Long> | 否 | 指定客户范围 | `biz_charge.cust_id` |
-| operatorId | Long | 否 | 发起人 ID | 操作上下文 |
+| applicationNo | String | 否 | 发票申请单号，与 `sysRequestNo` 二选一 | `biz_invoice.application_no` |
+| sysRequestNo | String | 否 | `SYS-008` 受理号，与 `applicationNo` 二选一 | `biz_invoice.sys_request_no` |
+| querySource | String | 是 | 查询来源：`MANUAL`、`AUTO_COMPENSATE`、`CALLBACK_VERIFY` | 查询触发上下文 |
 
 #### 响应参数
 
 | 字段 | 类型 | 说明 | 主要来源 |
 |------|------|------|----------|
-| taskNo | String | 催缴任务编号 | 业务流水 |
-| generateCount | Integer | 生成催缴对象数量 | 汇总结果 |
-| sendCount | Integer | 已发送数量 | 消息结果 |
-| failCount | Integer | 发送失败数量 | 消息结果 |
-| pendingReviewCount | Integer | 待人工复核数量 | 业务判断 |
+| invoiceId | Long | 发票主记录 ID | `biz_invoice.id` |
+| applicationNo | String | 发票申请单号 | `biz_invoice.application_no` |
+| sysRequestNo | String | `SYS-008` 受理号 | `biz_invoice.sys_request_no` |
+| invoiceStatus | String | 状态：`SUBMITTED`、`PENDING`、`SUCCESS`、`FAIL`、`INVALID`、`RED_INK` | `biz_invoice.invoice_status` |
+| invoiceCode | String | 发票代码 | `biz_invoice.invoice_code` |
+| invoiceNumber | String | 发票号码 | `biz_invoice.invoice_number` |
+| fileUrl | String | 电子发票文件地址 | `biz_invoice.file_url` |
+| failReason | String | 失败原因 | `biz_invoice.fail_reason` |
+| pushStatus | String | 电子发票推送状态 | `biz_invoice.push_status` |
+| lastQueryTime | DateTime | 最近一次查询时间 | `biz_invoice.last_try_time` |
+| tryCount | Integer | 累计查询次数 | `biz_invoice.try_count` |
+| latestResult | String | 最近一次查询结果摘要 | `biz_invoice.latest_result` |
+| latestError | String | 最近一次查询异常说明 | `biz_invoice.latest_error` |
 | msg | String | 处理说明 | 返回消息 |
 
+#### 查询补偿与状态流转约束
+
+- 查询入口同时服务于后台人工查询与系统补偿查询，两类触发必须复用同一状态落账规则。
+- 当 `querySource=AUTO_COMPENSATE` 时，接口语义表示由系统补偿任务触发一次兜底查询，并刷新最近查询时间、下次计划时间与累计次数。
+- 查询结果若确认开票成功，应回写票号、票据地址与账单-发票关联状态；若仍处理中，仅维持 `PENDING` 并更新补偿上下文。
+- 对已发起作废或红冲的记录，查询结果应允许把终态更新为 `INVALID` 或 `RED_INK`，并同步刷新 `latestResult`、`latestError`、账单关联状态与后处理上下文。
+- 已进入 `SUCCESS` 的正常开票终态不得被后续失败查询结果覆盖；若外部返回异常，应记录到操作留痕并保留人工核查入口。
+
+### IF-REV-013 催缴任务生成与结果承接接口
+
+#### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
+|------|------|------|------|---------------|
+| taskNo | String | 否 | 催缴任务号；查询/人工核查时必填 | 任务主键 |
+| custId | Long | 是 | 客户标识 | `biz_charge.cust_id` |
+| chargeIds | Array<Long> | 是 | 欠费账单集合 | `biz_charge.id` |
+| billPeriod | String | 是 | 账期 | `biz_charge.bill_period` |
+| arrearsAmount | Decimal | 是 | 欠费金额汇总 | 欠费汇总结果 |
+| strategyCode | String | 是 | 命中的催缴策略编码 | 策略规则 |
+| channelType | String | 是 | 触达渠道：短信/微信公众号/站内信等 | 任务分组结果 |
+| triggerType | String | 是 | 触发方式：`AUTO` / `MANUAL` | 任务触发上下文 |
+| eventNo | String | 否 | 业务事件号；生成后返回，回写承接时作为关联键 | 协同事件主键 |
+| relatedDisposalRef | String | 否 | 关联停复水或工单引用 | 联动追溯信息 |
+| manualVerifyNote | String | 否 | 人工核查说明；仅人工核查时填写 | 核查留痕 |
+
+#### 响应参数
+
+| 字段 | 类型 | 说明 | 主要来源 |
+|------|------|------|----------|
+| taskNo | String | 催缴任务号 | 任务主键 |
+| interfaceCode | String | 固定返回 `IF-REV-013` | 接口常量 |
+| eventNo | String | 业务事件号 | 协同主键 |
+| status | String | 状态：`PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` | 任务状态 |
+| resultTime | DateTime | 最近结果时间 | 结果回写时间 |
+| failureReason | String | 失败原因 | 失败回写 |
+| resultChannel | String | 实际触达渠道 | 协同结果 |
+| relatedDisposalRef | String | 关联停复水或工单引用 | 联动追溯 |
+| msg | String | 处理说明 | 返回消息 |
+
+#### 任务生成与状态承接约束
+
+- 任务生成前必须完成欠费账单、客户类别、联系方式和策略命中校验；至少存在一个可用触达渠道。
+- 相同业务事件与同一接收对象在去重窗口内不得重复生成等效任务；若为人工补发，应显式记录 `triggerType=MANUAL`。
+- `PENDING` 表示已生成任务并发起协同，等待 `SYS-010` 回写或人工核查；`SUCCESS`、`FAIL` 由协同结果或明确失败确认触发。
+- 当外部结果长期未定、历史回执不足或人工核查已确认结果时，可将任务补记为 `MANUAL_VERIFIED`，并保留核查人和核查说明。
+- 接口返回的 `relatedDisposalRef` 仅用于追溯停复水、复水或工单处置引用，不表示本接口承担下游流程控制。
+
+#### 失败阻断与人工核查约束
+
+- 候选账单不满足欠费前提、策略编码无效或触达信息缺失时，应阻断任务生成并返回明确原因，不得写入伪成功状态。
+- 频控规则命中时允许部分阻断，必须返回被跳过对象与原因摘要，避免“全成功”误判。
+- 渠道协同超时或仅返回受理结果时，不直接判定 `FAIL`，保持 `PENDING` 并等待回执或进入人工核查流程。
+- 人工核查补记必须校验 `taskNo` 存在且 `manualVerifyNote` 非空；不满足条件时应拒绝补记并返回校验错误。
+- 人工核查仅用于状态收口，不替代 `SYS-010` 的渠道执行职责，也不扩展停复水/工单内部流程控制。
+
+### IF-REV-010 统计查询接口
+
+#### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
+|------|------|------|------|---------------|
+| themeCode | String | 是 | 统计主题编码 | 查询主题 |
+| dateFrom | Date | 是 | 开始日期 | 时间维度 |
+| dateTo | Date | 是 | 结束日期 | 时间维度 |
+| billPeriod | String | 否 | 账期 | `biz_charge.bill_period` |
+| deptId | Long | 否 | 营业所/部门 | `system_dept.id` |
+| regionCode | String | 否 | 片区/区域编码 | 区域维度 |
+| customerCategory | String | 否 | 客户类别 | 客户标签/分类 |
+| channelCode | String | 否 | 收费/交易渠道 | `bk_payment_channel.channel_code` |
+| accountId | Long | 否 | 账户标识 | `biz_account.id` |
+| custId | Long | 否 | 客户标识 | `biz_cust.id` |
+| statusSet | Array<String> | 否 | 状态集合 | 账单/收费/抄表等状态筛选 |
+| groupBy | Array<String> | 否 | 分组维度集合 | 结果分组 |
+| exportFlag | Boolean | 否 | 是否导出 | 导出控制 |
+
+#### 响应参数
+
+| 字段 | 类型 | 说明 | 主要来源 |
+|------|------|------|----------|
+| themeCode | String | 统计主题编码 | 查询主题 |
+| themeName | String | 统计主题名称 | 主题定义 |
+| dimensionSummary | Object | 查询维度摘要 | 查询条件 |
+| indicatorList | Array | 指标结果集合 | 聚合结果 |
+| indicatorList[].indicatorCode | String | 指标编码 | 指标定义 |
+| indicatorList[].indicatorName | String | 指标名称 | 指标定义 |
+| indicatorList[].indicatorValue | Decimal/String | 指标值 | 聚合结果 |
+| indicatorList[].unit | String | 指标单位 | 指标定义 |
+| groupRows | Array | 分组结果集合 | 维度分组结果 |
+| exportAllowed | Boolean | 是否允许导出 | 权限结果 |
+| msg | String | 处理说明 | 返回消息 |
+
+#### 查询主题与口径约束
+
+- 本接口至少支持营收汇总、收费与实收、欠费规模与账龄、客户结构、渠道交易、抄表完成率等主题查询。
+- 应收金额、实收金额、欠费余额、账单数、客户数、交易笔数、渠道占比、完成率等指标必须按业务含义区分，不得混写。
+- 当查询涉及历史只读口径时，历史数据仅作为补充来源或迁移核查辅助，不替代在线主数据统计结果。
+- 权限边界必须同时作用于在线查询和导出动作；不允许越过现有数据权限返回全量统计结果。
+
 ### IF-REV-011 银行代收协同接口
 
 #### 请求参数
@@ -906,30 +1110,49 @@ retrieval_priority: P0
 | list[].payStatus | String | 缴费状态 | 业务状态 |
 | list[].invoiceStatus | String | 开票状态 | `biz_invoice.invoice_status` |
 
-### IF-CS-004 发票申请接口
+### IF-CS-004 电子发票消费接口
 
-#### 请求参数
+#### 查询/下载请求参数
 
 | 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
 |------|------|------|------|---------------|
 | custId | Long | 是 | 客户 ID | `biz_invoice.cust_id` |
-| chargeIds | Array<Long> | 是 | 开票关联账单 ID | 业务单据关联 |
-| invoiceTitle | String | 是 | 发票抬头 | `biz_cust_invoice.invoice_title` |
-| taxNo | String | 否 | 税号 | `biz_cust_invoice.tax_no` |
-| email | String | 否 | 电子发票邮箱 | `biz_cust_invoice.email` |
-| mobile | String | 否 | 接收手机号 | `biz_cust_invoice.mobile` |
-| invoiceType | String | 否 | 默认 `ELECTRONIC` | `biz_invoice.invoice_type` |
+| invoiceId | Long | 否 | 发票记录 ID，三选一优先键 | `biz_invoice.id` |
+| applicationNo | String | 否 | 发票申请单号 | `biz_invoice.application_no` |
+| sysRequestNo | String | 否 | `SYS-008` 受理号 | `biz_invoice.sys_request_no` |
+
+#### 推送请求参数
+
+| 字段 | 类型 | 必填 | 说明 | 主要来源/去向 |
+|------|------|------|------|---------------|
+| custId | Long | 是 | 客户 ID | `biz_invoice.cust_id` |
+| invoiceId | Long | 是 | 发票记录 ID | `biz_invoice.id` |
+| applicationNo | String | 否 | 发票申请单号 | `biz_invoice.application_no` |
+| pushChannel | String | 是 | 推送方式：`EMAIL`、`SMS` | 推送动作 |
+| pushEmail | String | 否 | 推送邮箱，`EMAIL` 时优先使用 | 目标地址 |
+| pushMobile | String | 否 | 推送手机号，`SMS` 时优先使用 | 目标地址 |
 
 #### 响应参数
 
 | 字段 | 类型 | 说明 | 主要来源 |
 |------|------|------|----------|
-| invoiceId | Long | 发票申请 ID | `biz_invoice.id` |
-| invoiceCode | String | 发票申请编号 | `biz_invoice.code` |
+| invoiceId | Long | 发票记录 ID | `biz_invoice.id` |
+| applicationNo | String | 发票申请单号 | `biz_invoice.application_no` |
 | invoiceStatus | String | 当前状态 | `biz_invoice.invoice_status` |
-| fileUrl | String | 发票下载地址 | 结果回写 |
+| invoiceCode | String | 发票代码 | `biz_invoice.invoice_code` |
+| invoiceNumber | String | 发票号码 | `biz_invoice.invoice_number` |
+| fileUrl | String | 发票下载地址 | `biz_invoice.file_url` |
+| pushStatus | String | 推送状态：`NONE`、`PUSHED`、`FAIL` | `biz_invoice.push_status` |
+| chargeBindStatus | String | 账单关联状态：`UNBOUND`、`BOUND` | `biz_invoice.charge_bind_status` |
 | msg | String | 处理说明 | 返回消息 |
 
+#### 客户侧消费约束
+
+- 客户侧仅允许访问本人 `custId` 名下发票记录，`invoiceId`、`applicationNo`、`sysRequestNo` 任一定位成功后仍需再次校验客户归属。
+- 下载与推送前必须校验 `invoiceStatus=SUCCESS` 且 `fileUrl` 非空；已作废、已红冲或缺少电子票地址的记录一律返回不可消费原因。
+- 推送成功后回写 `pushStatus=PUSHED`；失败则更新为 `FAIL` 并记录失败原因。
+- 客户侧只消费已形成有效电子票结果的记录，不暴露后台作废、红冲入口，也不直接展示后处理请求参数。
+
 ### IF-CS-003 在线支付下单接口
 
 #### 请求参数
@@ -1199,7 +1422,7 @@ sequenceDiagram
     SYS002-->>Client: 查询订单时返回最新支付状态
 ```
 
-### 2. 电子发票申请与回写时序
+### 2. 电子发票申请、查询补偿与回写时序
 
 ```mermaid
 sequenceDiagram
@@ -1208,15 +1431,25 @@ sequenceDiagram
     participant SYS002 as SYS-002营收系统
     participant SYS008 as SYS-008发票服务
     participant Tax as 税控/开票平台
+    participant Job as 查询补偿任务
 
     Counter->>SYS002: 提交发票申请(IF-REV-008/IF-CS-004)
     SYS002->>SYS002: 校验客户、账单、开票抬头与金额
-    SYS002->>SYS002: 生成发票申请记录biz_invoice
+    SYS002->>SYS002: 生成发票申请记录biz_invoice(SUBMITTED)
     SYS002->>SYS008: 发起开票协同(IF-EXT-006)
     SYS008->>Tax: 调用税控或电子发票平台
     Tax-->>SYS008: 返回受理结果/票号/文件地址
-    SYS008-->>SYS002: 回写开票结果(IF-EXT-007)
-    SYS002->>SYS002: 更新biz_invoice状态与票据地址
+    SYS008-->>SYS002: 返回受理号或异步结果
+    SYS002->>SYS002: 记录sysRequestNo并更新为PENDING
+    alt 发票服务主动回写
+        SYS008-->>SYS002: 回写开票结果(IF-EXT-007)
+        SYS002->>SYS002: 更新biz_invoice状态、票据地址与账单关联
+    else 未收到终态结果
+        Job->>SYS002: 触发补偿查询(IF-REV-009)
+        SYS002->>SYS008: 按申请单号/受理号查询结果
+        SYS008-->>SYS002: 返回处理中/成功/失败
+        SYS002->>SYS002: 刷新查询上下文并按终态规则落账
+    end
     SYS002-->>Counter: 返回申请结果或供后续查询
 ```
 
@@ -1255,13 +1488,13 @@ sequenceDiagram
     participant SYS010 as SYS-010消息服务
     participant User as 客户
 
-    Job->>SYS002: 触发催缴任务(IF-REV-009)
+    Job->>SYS002: 触发催缴任务(IF-REV-013)
     SYS002->>SYS002: 按欠费账单、渠道偏好生成催缴名单
     SYS002->>SYS010: 提交通知下发请求(IF-EXT-008)
     SYS010->>User: 发送短信/公众号/APP消息
     User-->>SYS010: 触达回执或阅读反馈
     SYS010-->>SYS002: 回写发送结果与触达状态
-    SYS002->>SYS002: 更新催缴记录、通知状态与后续策略
+    SYS002->>SYS002: 更新催缴记录、四态状态与后续策略
     SYS002-->>Job: 返回催缴任务执行结果
 ```
 
@@ -1351,9 +1584,11 @@ sequenceDiagram
 | 催缴通知 | `templateCode` | `templateCode` | 消息模板编码 | 模板参数 |
 | 催缴通知 | `arrearsAmount` | `payload.arrearsAmount` | 欠费金额 | `biz_charge.total_amount` / 汇总结果 |
 | 催缴通知 | `billPeriod` | `payload.billPeriod` | 账期 | `biz_charge.bill_period` |
+| 催缴通知 | `strategyCode` | `payload.strategyCode` | 命中的催缴策略编码 | 任务分组结果 |
+| 催缴通知 | `triggerType` | `payload.triggerType` | 自动/人工触发方式 | 任务触发上下文 |
 | 办理进度通知 | `processCode` | `payload.processCode` | 业务办理单号 | `biz_process.code` |
 | 办理进度通知 | `processStatus` | `payload.processStatus` | 办理状态 | `biz_process.status` |
-| 发送结果回写 | `sendStatus` | `sendStatus` | 发送状态 | 消息结果 |
+| 发送结果回写 | `status` | `sendStatus` | 渠道回执由 `SYS-002` 统一映射为 `PENDING/SUCCESS/FAIL/MANUAL_VERIFIED` 四态 | 消息结果 |
 | 发送结果回写 | `reachStatus` | `reachStatus` | 触达/阅读状态 | 渠道回执 |
 | 发送结果回写 | `sendTime` | `sendTime` | 发送时间 | 消息结果 |
 | 发送结果回写 | `msg` | `resultMsg` | 结果说明 | 返回消息 |
@@ -1409,8 +1644,9 @@ sequenceDiagram
 | `1_002_006_003` | IF-REV-011 | 对账差异未处理，禁止结算确认 | 需先完成差异处置 |
 | `1_002_007_001` | IF-CS-006 | 业务办理单不存在 | 返回空结果并提示核对单号 |
 | `1_002_007_002` | IF-CS-006 | 当前节点不允许补件或重复提交 | 返回当前流程节点状态 |
-| `1_002_008_001` | IF-REV-009 / IF-EXT-008 | 消息模板不存在或目标联系方式缺失 | 记录失败原因并允许后续补发 |
+| `1_002_008_001` | IF-REV-013 / IF-EXT-008 | 消息模板不存在或目标联系方式缺失 | 记录失败原因并允许后续补发 |
 | `1_002_008_002` | IF-EXT-008 | 消息通道调用超时 | 标记待重试，不直接判定业务失败 |
+| `1_002_008_003` | IF-REV-013 | 人工核查补记缺少核查说明或关联任务不存在 | 拒绝补记并提示补齐核查上下文 |
 
 ### 幂等与状态冲突控制
 
@@ -1424,7 +1660,7 @@ sequenceDiagram
 | 发票结果回写 | IF-EXT-007 | `requestNo + invoiceStatus` | 相同发票状态重复回写仅更新回执日志 |
 | 银行批次下发 | IF-REV-011 / IF-EXT-001 | `batchNo` | 同一代扣批次禁止重复发送 |
 | 银行回盘接收 | IF-EXT-002 | `batchNo + fileSerialNo` | 同一回盘文件只处理一次 |
-| 催缴通知 | IF-REV-009 / IF-EXT-008 | `messageBizNo + templateCode + receiver` | 同一业务事件与同一接收方避免重复发送 |
+| 催缴通知 | IF-REV-013 / IF-EXT-008 | `messageBizNo + templateCode + receiver` | 同一业务事件与同一接收方避免重复发送 |
 | 业务补件 | IF-CS-006 | `processId + action + attachmentDigest` | 相同补件内容重复提交仅保留一次 |
 
 #### 状态冲突处理原则
@@ -1449,6 +1685,47 @@ sequenceDiagram
 - 外部结果晚到：允许按幂等键补写回执，但不得回退已确认成功状态。
 - 人工兜底场景：支付异常、银行回盘异常、发票状态冲突等需保留人工复核入口与操作日志。
 
+<a id="sec-migration-readonly"></a>
+## 历史查询与迁移校验接口口径
+
+### 设计原则
+
+- 历史查询接口一律只读，不承担迁移修正、补写或状态变更职责。
+- 不为迁移场景发明新的独立接口编号体系，统一挂靠既有 `IF-REV-*`、`IF-CS-*`、`IF-METER-*` 接口族扩展查询能力。
+- 对 backend 当前未识别到独立实体表的旧细粒度对象，仅要求接口返回“历史摘要 + 原始标识 + 状态映射”，不强行承诺独立在线业务对象。
+- 迁移验收接口必须同时支持“汇总对账”和“明细追溯”两类能力，避免只能看总数、无法定位差异。
+
+### 最小历史查询保留集
+
+| 查询主题 | 挂靠接口族 | 主要数据来源 | 最低返回要求 | 说明 |
+|---------|------------|--------------|--------------|------|
+| 历史账单、特殊开账 | `IF-CS-002`、`IF-REV-005` | `biz_charge*` + 历史账单来源 | 原账单号、新账单号、客户号、账期、金额、状态、来源类型 | 支撑账单迁移核查与客户侧历史查询 |
+| 缴费记录、柜台结账、实时收费 | `IF-CS-002`、`IF-REV-006`、`IF-REV-011` | `biz_collection`、`bk_transaction*` + 历史收费记录 | 原流水号、渠道、实收金额、收费时间、柜员/营业所、核销状态 | 支撑渠道对账、柜面核查和历史收据核对 |
+| 红冲与账务调整 | `IF-REV-007` | 操作留痕、流程结果 + 历史调整台账 | 调整类型、关联原单号、调整金额、原因、审批状态、处理时间 | 支撑预存退款、已销调整、价差调整、分账调整、呆坏账查询 |
+| 发票与开票关系 | `IF-REV-008`、`IF-CS-004` | `biz_invoice*` + 历史开票关系快照 | 发票号、申请单号、关联账单、票据状态、票据类型、文件地址 | 支撑发票结果核查与历史补打定位 |
+| 催缴、停复水、预存短信 | `IF-REV-013`、`IF-METER-002` | 通知结果、流程工单 + 历史催缴记录 | 客户号、账期、催缴方式、消息状态、停复水状态、执行人、执行时间、处置引用 | 支撑催缴处置闭环核查 |
+| 业务进度与电子档案 | `IF-CS-006` | `biz_process*`、`biz_content*` + 历史附件目录 | 业务单号、节点状态、处理轨迹、附件数量、附件元数据 | 支撑微网厅与柜台办理进度、电子档案查询 |
+| 水表生命周期、检定与库存流转 | `IF-METER-001`、`IF-METER-003` | `biz_meter*` + 历史仓储/检定单据 | 表号、当前状态、单据类型、仓库、检定结论、证书编号、时间 | 支撑表务迁移核查与历史作业追溯 |
+| 页面参数、业务字段、微信配置 | `IF-REV-012`、`IF-CS-006` | `biz_parameter_settings`、`biz_page_settings*`、`sys_wechat_app_settings` | 参数编码、原值、新值、启用状态、生效时间、适用渠道 | 支撑微网厅后台配置迁移核查 |
+
+### 迁移验收对账接口要求
+
+| 验收场景 | 推荐挂靠接口 | 最低查询维度 | 输出要求 |
+|---------|--------------|--------------|----------|
+| 开账迁移核对 | `IF-REV-005`、`IF-CS-002` | 账期、营业所、客户类型、账单状态 | 同时提供汇总金额/笔数与可追溯明细清单 |
+| 收费迁移核对 | `IF-REV-006`、`IF-REV-011`、`IF-CS-002` | 日期、渠道、营业所、收费状态 | 同时提供实收金额、流水数量和异常流水列表 |
+| 发票迁移核对 | `IF-REV-008`、`IF-CS-004` | 开票日期、票据类型、开票状态 | 同时提供开票汇总、失败原因和票据明细定位 |
+| 催缴与停复水核对 | `IF-REV-013`、`IF-METER-002` | 账期、催缴方式、执行状态、处理人 | 同时提供任务统计、执行明细与处置引用 |
+| 业务办理与档案核对 | `IF-CS-006` | 业务类型、流程状态、附件类型、创建时间 | 同时提供流程轨迹、附件元数据和缺失标记 |
+| 表务仓储与检定核对 | `IF-METER-001`、`IF-METER-003` | 仓库、单据类型、水表状态、检定结论 | 同时提供数量汇总和单据级追溯信息 |
+
+### 接口约束补充
+
+- 历史查询结果应优先返回原系统标识与新系统标识的映射关系，例如原单号、原批次号、原附件标识、当前业务单号。
+- 明细查询接口应支持按客户号、证件号、手机号、表号、账期、营业所、渠道、业务单号等组合检索，满足迁移验收定位需求。
+- 若历史附件不直接由当前业务服务托管，接口至少返回附件元数据、来源系统、文件引用地址和可访问状态。
+- 历史查询接口的导出能力属于查询扩展能力，不应与在线交易接口共用“状态变更”动作。
+
 <a id="sec-status"></a>
 ## 实现状态说明
 
@@ -1469,7 +1746,7 @@ sequenceDiagram
 
 - 账务调整、退款、坏账、冲正类精细接口
 - 催缴管理中针对不同通知策略和停复水联动的细分接口
-- 发票红冲、作废、补开等票据后处理接口
+- 发票补开等扩展票据后处理接口
 
 ### 文档先行
 
@@ -1478,6 +1755,7 @@ sequenceDiagram
 - 历史数据字典中大量细粒度账务台账接口
 - 未在 backend 当前扫描范围内明确识别到的独立业务对象接口
 - 特定银行或地方平台的专有报文细节
+- 历史查询与迁移校验接口在实施时所依赖的只读库、归档库或映射表物理形态
 
 ---
 

docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md

@@ -0,0 +1,245 @@
+# REV-004 账务处理一期执行手册
+
+## 1. 文档目的
+
+本文档用于将 `REV-004` 账务处理一期从“范围确认”转为“正式文档可执行修订计划”，用于指导：
+
+- 一期纳入范围与排除项确认
+- 正式主文档修订顺序
+- 最小校验动作与验收入口
+- 台账回写触发条件
+- 后续实施任务拆解方式
+
+本文档只服务于 `REV-004` 一期文档收敛与执行准备，不扩展到未确认范围，也不把 backend 代码修改作为本轮已执行内容。
+
+## 2. 范围基线
+
+本次执行范围以以下文档交集为准：
+
+1. `docs/design/01_Overview/03_Summary_Design.md`
+2. `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+3. `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+4. `docs/design/03_Technical_Design/01_Database_Design.md`
+5. `docs/design/03_Technical_Design/03_Interface_Design.md`
+
+### 2.1 一期纳入范围
+
+| 类别 | 范围 |
+| --- | --- |
+| 模块 | `REV-004` |
+| 接口 | `IF-REV-007` |
+| 场景 | 水量调整、金额调整、退款、冲正、坏账申请 |
+| 共性能力优先 | 先统一账单承接、原交易校验、结果表达、操作留痕、审批边界 |
+| 核心对象 | `biz_charge`、`biz_charge_detail`、`biz_operat_log*` |
+| 外部校验 | 原交易校验（`bk_transaction*`） |
+| 审批边界 | 只保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明，不展开完整审批流 |
+
+### 2.2 一期不纳入范围
+
+| 类别 | 不纳入内容 |
+| --- | --- |
+| 独立台账表族 | 预存退款明细表、价差调整明细表、分账调整明细表等新增细表 |
+| 非本模块接口 | `IF-REV-008`、`IF-REV-011`、`IF-CS-*`、`IF-METER-*` |
+| 泛化流程平台扩展 | 新 BPM 模型体系、新审批平台抽象 |
+| 跨模块大改 | 支付全链路重构、发票后处理重构、历史库统一改造 |
+| 本轮不做 | backend 代码实现、联调测试、worktree/tmux/Codex 执行编排 |
+
+## 3. 当前代码落点
+
+### 3.1 主业务模块
+
+| 角色 | 文件路径 |
+| --- | --- |
+| Controller | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/charge/ChargeController.java` |
+| Service 接口 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeService.java` |
+| Service 实现 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeServiceImpl.java` |
+| Mapper | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/charge/ChargeMapper.java` |
+| DO | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/charge/ChargeDO.java` |
+| 操作日志服务 | `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/operatlog/OperatLogService.java` |
+
+### 3.2 银行交易校验模块
+
+| 角色 | 目录 |
+| --- | --- |
+| 交易 Controller | `backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/admin/transaction` |
+| 交易 Service | `backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/transaction` |
+| 交易 Mapper/DO | `backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/mysql/transaction` |
+
+### 3.3 BPM 接入点
+
+| 角色 | 文件路径 |
+| --- | --- |
+| BPM API | `backend/sw-module-bpm/sw-module-bpm-api/src/main/java/cn/com/emsoft/sw/module/bpm/api/task/BpmProcessInstanceApi.java` |
+
+## 4. 当前文档差距判断
+
+### 4.1 已有基础
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md` 已具备 REV-004 账务处理章节与主要场景说明。
+- `docs/design/03_Technical_Design/03_Interface_Design.md` 已具备 `IF-REV-007` 接口定义与字段口径。
+- `docs/design/03_Technical_Design/01_Database_Design.md` 已具备 `biz_charge*`、`biz_operat_log*`、`bk_transaction*` 的主承接口径。
+- `specs/001-rev004-accounting/` 已形成范围、数据模型、场景矩阵、追溯矩阵与最小校验说明。
+
+### 4.2 一期文档缺口
+
+- 正式详细设计仍需明确“一期仅五类场景”的范围边界与排除项。
+- 执行手册仍需从代码落地视角收敛回“正式文档修订 + 最小校验 + 台账触发条件”的执行口径。
+- 正式主文档之间仍需进一步统一共性能力优先顺序、审批边界和受影响对象说明。
+- 台账文件仍需在正式文档校验通过后按触发条件更新，而不是默认同步。
+
+## 5. 一期最小文档改动方案
+
+### 5.1 正式主文档修订顺序
+
+按以下顺序执行：
+
+1. `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+2. `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+3. `docs/design/01_Overview/03_Summary_Design.md`
+4. `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+
+### 5.2 必须统一的共性口径
+
+一期必须先统一以下共性能力：
+
+- 统一入口：`IF-REV-007`
+- 统一账单承接：`biz_charge` / `biz_charge_detail`
+- 统一原交易校验：`bk_transaction*`
+- 统一留痕：`biz_operat_log` / `biz_operat_log_detail`
+- 统一结果表达：`resultStatus` / `writeBackStatus`
+- 统一审批边界：`approvalRequired` / `PENDING_APPROVAL`
+
+### 5.3 最小验收入口
+
+本轮验收仅检查：
+
+- 文档一致性
+- 计划可拆解性
+- 台账可回写性
+
+### 5.4 台账更新触发条件
+
+- 仅当正式文档重要变更完成且对应校验通过后，才更新 `docs/design/00_Management/01_Project_Progress.md`。
+- 仅当 tracked task 完成或完成条件发生实质变化时，才更新 `docs/design/00_Management/03_Task_Checklist.md`。
+- 如果正式文档未发生实质变化，可将对应台账任务标记为不适用，但必须说明理由。
+
+## 6. 文档任务拆解
+
+### 6.1 P0-1 范围与边界收敛
+
+| 项目 | 内容 | 输出 |
+| --- | --- | --- |
+| 范围收敛 | 明确一期五类场景、排除项、审批边界 | REV-004 范围基线 |
+| 共性能力排序 | 明确“共性能力先统一、场景能力再分批” | 修订顺序说明 |
+| 追溯锚点 | 明确详细设计 / 接口 / 数据库 / 执行手册的对应关系 | 追溯基线 |
+
+### 6.2 P0-2 正式文档修订
+
+| 分类 | 必做项 |
+| --- | --- |
+| 详细设计 | 更新 REV-004 一期范围、排除项、审批边界 |
+| 执行手册 | 更新执行范围、验收入口、后续组织方式 |
+| 概要设计 | 同步一期范围摘要与交叉引用 |
+| 追溯矩阵 | 回写范围与正式文档承接关系 |
+
+### 6.3 P0-3 校验与台账
+
+| 场景 | 要求 |
+| --- | --- |
+| 单文件校验 | 对修改过的正式文档执行 `make validate-file FILE=<目标文件>` |
+| 跨文档校验 | 存在交叉引用变更时执行 `make check-links` |
+| 项目进度 | 仅在重要正式文档变更校验通过后回写 |
+| 任务清单 | 仅在 tracked task 完成或完成条件变化时回写 |
+
+## 7. 评审与执行分工
+
+### 7.1 评审者负责
+
+- 确认是否超出一期范围
+- 确认审批边界是否仍停留在能力位层
+- 审核正式文档之间是否口径一致
+- 审核台账是否满足触发条件再更新
+
+### 7.2 执行者负责
+
+- 按既定顺序修订正式主文档
+- 同步 contracts / quickstart / traceability 等支撑产物
+- 执行最小校验并记录结果
+- 汇总剩余风险与下一步建议
+
+## 8. 执行顺序与最小校验
+
+### 8.1 推荐执行顺序
+
+1. 先确认 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 已形成一期统一口径，再进入执行闭环收口。
+2. 更新本执行手册，明确后续 tasks 的拆解顺序、独立验收入口、最小校验动作与台账同步条件。
+3. 如执行手册对评审步骤、校验说明或闭环顺序有实质性调整，再同步 `quickstart.md` 与 `plan.md` 的支撑表述。
+4. 仅在治理台账形成新的里程碑或 tracked task 完成条件被重新定义时，再回写 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。
+5. 每完成一组正式文档或台账修订，立即执行最小校验，确保当前增量可独立评审。
+
+### 8.2 独立验收入口
+
+US3 的独立验收只检查以下内容：
+
+1. `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` 是否明确后续任务拆解顺序：先执行手册闭环，再按正式主文档 / 支撑产物 / 台账同步三类动作推进。
+2. `docs/design/00_Management/01_Project_Progress.md` 是否记录了 REV-004 从“范围确认 / 口径对齐”进入“可执行交付闭环”的里程碑。
+3. `docs/design/00_Management/03_Task_Checklist.md` 是否记录了 REV-004 当前 tracked task 的闭环条件：执行手册更新、最小校验通过、台账按触发条件同步。
+4. 审阅者无需查看 backend 代码或额外 Archive 材料，即可判断 REV-004 后续工作可继续按 tasks 拆解推进。
+
+### 8.3 最小校验动作
+
+```bash
+make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
+make validate-file FILE=docs/design/00_Management/01_Project_Progress.md
+make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md
+make check-links
+```
+
+补充说明：
+
+- `make check-links` 仅用于确认执行手册、项目进度、任务清单之间的相对链接与引用未被破坏。
+- 本轮仍不引入 backend 构建、导出、联调或自动化测试命令。
+- 若后续进入新的正式主文档修订批次，应在该批次内补充对应目标文件的 `make validate-file FILE=<目标文件>`。
+
+## 9. 文档执行提示模板
+
+### 9.1 第一轮：先收敛范围
+
+```text
+请先只做 REV-004 一期正式文档范围收敛，不进入 backend 代码修改。
+
+范围严格限制：
+- IF-REV-007
+- 水量调整、金额调整、退款、冲正、坏账申请
+- 不新增独立账务台账表族
+
+重点输出：
+1. 一期纳入范围
+2. 一期排除项
+3. 共性能力优先顺序
+4. 审批边界
+5. 需要同步的正式文档清单
+```
+
+### 9.2 第二轮：确认后再修订正式文档
+
+```text
+按已确认的 REV-004 一期范围开始修订正式文档。
+
+要求：
+- 先改详细设计与执行手册
+- 再同步概要摘要和追溯矩阵
+- 审批只保留 approvalRequired / PENDING_APPROVAL / 边界说明
+- 不把 backend 代码实现写成本轮已完成内容
+- 每次修订后执行最小校验并汇总剩余风险
+```
+
+## 10. 验收清单
+
+- [ ] 一期范围仅保留水量调整、金额调整、退款、冲正、坏账申请
+- [ ] 独立账务细表、其他接口族、泛化 BPM 与 backend 代码实施未被带入本轮
+- [ ] 共性能力优先顺序已写清楚
+- [ ] 审批边界仅保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明
+- [ ] 正式文档修订顺序与最小验收入口已明确
+- [ ] 台账更新触发条件已明确
+- [ ] 文档改动可独立评审并可继续拆解后续任务

specs/001-rev004-accounting/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: REV-004 账务处理一期
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-13
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 本轮校验通过。
+- 规格已限定在 REV-004 一期的文档范围收敛与执行准备，不包含超范围扩写。
+- 下一步可进入 `/speckit.clarify` 或直接在确认范围后进入 `/speckit.plan`。

specs/001-rev004-accounting/checklists/scope-alignment.md

@@ -0,0 +1,64 @@
+# Scope Alignment Checklist: REV-004 账务处理一期
+
+**Purpose**: Validate whether the REV-004 scope and alignment requirements are complete, clear, consistent, and review-ready.
+**Created**: 2026-03-18
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/001-rev004-accounting/spec.md)
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+## Source & Scope
+
+- [ ] CHK001 Are the target documents and their distinct responsibilities explicitly defined without overlap or omission? [Completeness, Spec §FR-001]
+- [ ] CHK002 Are the governing source-of-truth documents clearly distinguished from reference-only materials such as Archive content? [Consistency, Spec §FR-002]
+- [ ] CHK003 Does the spec define REV-004 phase-one scope with a stable inclusion list and an equally explicit exclusion boundary? [Completeness, Spec §FR-003, Spec §FR-005]
+- [ ] CHK004 Is the rule "共性能力先统一、场景能力再分批" specified with enough detail to constrain later planning order and not just describe intent? [Clarity, Spec §FR-004]
+
+## Requirement Completeness
+
+- [ ] CHK005 Are traceability requirements defined across detailed design, interface design, and database design for every in-scope accounting scenario? [Completeness, Spec §FR-006]
+- [ ] CHK006 Are evidence retention, original-basis recording, and result write-back requirements all specified as mandatory scope elements rather than implied expectations? [Completeness, Spec §FR-007]
+- [ ] CHK007 Does the spec define when execution playbook, project progress, and task checklist updates are required and when they are intentionally not required? [Completeness, Spec §FR-008]
+- [ ] CHK008 Are the minimum validation actions required before clarify/plan/tasks complete, specific, and tied to concrete review artifacts? [Completeness, Spec §FR-011]
+
+## Requirement Clarity
+
+- [ ] CHK009 Is "一期" bounded by explicit scenario names and exclusion criteria, rather than by broad phrases that could expand during review? [Clarity, Spec §FR-003, Spec §FR-005]
+- [ ] CHK010 Is "审批仅保留能力位和边界说明" precise enough to prevent readers from inferring workflow nodes, routing rules, or BPM scope? [Clarity, Spec §FR-010]
+- [ ] CHK011 Is the phrase "文档一致性、计划可拆解性和台账可回写性" translated into objective review questions or evidence points? [Measurability, Spec §FR-009, Spec §SC-004]
+- [ ] CHK012 Does the spec avoid implementation-oriented acceptance language and keep review criteria at the user/business-document level throughout? [Clarity, Spec §FR-012]
+
+## Requirement Consistency
+
+- [ ] CHK013 Are the in-scope scenarios consistent between the user stories, functional requirements, assumptions, and plan summary? [Consistency, Spec §User Story 1, Spec §FR-003, Plan §Summary]
+- [ ] CHK014 Do the acceptance boundaries in the spec align with the plan's statement that this round excludes backend code modification? [Consistency, Spec §FR-009, Plan §Summary]
+- [ ] CHK015 Are the named core scenarios consistent across the spec and plan, given that the plan summary includes five scenarios while FR-003 lists four examples? [Conflict, Spec §FR-003, Plan §Summary]
+- [ ] CHK016 Are the requirements for traceability, validation, and ledger sync consistent between the spec and the task structure used for later execution? [Consistency, Spec §FR-008, Spec §FR-011, Tasks §Validation]
+
+## Acceptance Criteria Quality
+
+- [ ] CHK017 Can each success criterion be evaluated objectively from document content alone, without relying on reviewer intuition or external tribal knowledge? [Acceptance Criteria, Spec §SC-001, Spec §SC-002, Spec §SC-003, Spec §SC-004]
+- [ ] CHK018 Is the "5 分钟内判断范围" criterion supported by explicit requirement structure that makes such a review realistically repeatable? [Measurability, Spec §SC-002]
+- [ ] CHK019 Are acceptance scenarios mapped clearly enough to the functional requirements they are intended to validate? [Traceability, Spec §User Story 1, Spec §User Story 2, Spec §User Story 3]
+
+## Scenario Coverage
+
+- [ ] CHK020 Are primary, exclusion, exception, and governance-sync scenarios all covered in requirements, rather than only the happy-path planning narrative? [Coverage, Spec §Edge Cases, Spec §FR-008, Spec §FR-009]
+- [ ] CHK021 Are requirements defined for terminology conflicts between detailed/interface/database documents, including how the formal wording is chosen? [Coverage, Spec §Edge Cases, Spec §FR-006]
+- [ ] CHK022 Does the spec define what happens when historical materials contain finer-grained accounting scenarios than the current phase-one baseline? [Edge Case, Spec §Edge Cases]
+
+## Dependencies & Assumptions
+
+- [ ] CHK023 Are assumptions about the current main documents already covering the required accounting scenarios explicitly validated or marked for confirmation? [Assumption, Spec §Assumptions]
+- [ ] CHK024 Are dependencies on the execution playbook, governance ledgers, and constitution documented as requirements constraints rather than hidden context? [Dependency, Spec §FR-002, Plan §Technical Context]
+
+## Ambiguities & Conflicts
+
+- [ ] CHK025 Is there any unresolved ambiguity between "账务处理一期" as a document-governance scope and "后续实施计划" as a scenario-delivery scope? [Ambiguity, Spec §FR-004, Spec §FR-009]
+- [ ] CHK026 If scope is later narrowed to a single sub-scenario, do the requirements say which parts of the current baseline remain mandatory and which may be deferred? [Gap, Spec §Assumptions]
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md

@@ -0,0 +1,71 @@
+# Contract: IF-REV-007 账务调整接口
+
+## 1. 合同定位
+
+本合同用于固化 `IF-REV-007` 在 REV-004 一期中的统一接口口径，服务于后续正式接口文档修订、任务拆解与评审，不作为代码接口定义文件。
+
+## 2. 适用范围
+
+适用场景：
+- 水量调整
+- 金额调整
+- 退款
+- 冲正
+- 坏账申请
+
+不适用范围：
+- 发票申请与结果回写
+- 银行代收与结算协同
+- 新 BPM 流程模型扩展
+- 独立账务台账表族设计
+
+## 3. 请求合同
+
+| 字段 | 类型 | 必填 | 说明 | 约束 |
+|------|------|------|------|------|
+| chargeId | Long | 是 | 目标账单 ID | 必须存在于 `biz_charge.id` |
+| adjustType | String | 是 | 调整类型 | `USAGE` / `AMOUNT` / `REFUND` / `REVERSE` / `BAD_DEBT` |
+| adjustAmount | Decimal | 否 | 调整金额 | 金额类场景必填 |
+| adjustUsage | Decimal | 否 | 调整水量 | 水量类场景必填 |
+| sourceTradeNo | String | 否 | 原交易流水号 | `REFUND` / `REVERSE` 场景必填 |
+| reasonCode | String | 是 | 调整原因编码 | 需可追溯到业务字典 |
+| remark | String | 否 | 调整说明 | 进入操作留痕 |
+| attachmentList | Array<String> | 否 | 依据附件 | 进入依据引用 |
+| operatorId | Long | 是 | 操作人 ID | 必须可追溯责任归属 |
+
+## 4. 响应合同
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| adjustmentNo | String | 调整业务编号 | 用于后续追踪 |
+| chargeId | Long | 目标账单 ID | 与请求一致 |
+| resultStatus | String | 处理状态 | `SUCCESS` / `PENDING_APPROVAL` / `FAIL` |
+| writeBackStatus | String | 账单回写状态 | `SUCCESS` / `IGNORE_REPEAT` / `FAIL` |
+| approvalRequired | Boolean | 是否进入审批 | 一期仅保留能力位 |
+| msg | String | 处理说明 | 供调用方和评审使用 |
+
+## 5. 共性规则
+
+1. 所有场景必须定位到既有账单对象，不建立并行账务主对象。
+2. 所有场景必须保留处理依据、前后变化和责任归属。
+3. 退款、冲正必须校验原交易存在性、交易状态、回调结果与异常处理状态，不得只以 `bk_transaction` 主记录存在作为通过条件。
+4. 审批相关内容一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 与审批边界说明，不展开完整 BPM 流程、流程节点、流转规则或审批回写实现细节。
+5. 接口结果必须能映射到 `biz_charge*`、`bk_transaction*`、`biz_operat_log*` 三类对象。
+6. `resultStatus` 与 `writeBackStatus` 必须分离表达：前者表示业务处理结论，后者表示账单状态回写结论。
+
+## 6. 物理承接口径
+
+| 逻辑对象 | 物理承接 |
+|---------|----------|
+| 账单主对象 | `biz_charge` |
+| 账单明细 | `biz_charge_detail` |
+| 原交易校验 | `bk_transaction*` |
+| 主日志 | `biz_operat_log` |
+| 差异明细日志 | `biz_operat_log_detail` |
+
+## 7. 验收关注点
+
+- 是否所有场景都仍挂靠 `IF-REV-007`
+- 是否未引入超范围接口编号
+- 是否未把审批/BPM 细化为一期必做实现
+- 是否未误写独立账务台账表族为在线新增对象

specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md

@@ -0,0 +1,33 @@
+# Contract: REV-004 一期场景矩阵
+
+## 1. 目的
+
+用于统一 REV-004 一期各场景在输入依据、关键校验、结果表达和留痕要求上的差异，支撑后续 plan/tasks 拆解。
+
+## 2. 场景矩阵
+
+| 场景 | 主要输入 | 关键校验 | 结果表达 | 留痕重点 | 备注 |
+|------|----------|----------|----------|----------|------|
+| 水量调整 | `chargeId`、`adjustUsage`、`reasonCode` | 原抄表依据、账单状态可调 | `resultStatus`、`writeBackStatus` | 调整前后水量、依据附件 | 不新增跨周期水量独立表 |
+| 金额调整 | `chargeId`、`adjustAmount`、`reasonCode` | 差异金额合法性、账单状态可调 | `resultStatus`、`writeBackStatus` | 调整前后金额、原因、经办人 | 可涉及重算口径 |
+| 退款 | `chargeId`、`adjustAmount`、`sourceTradeNo` | 原交易存在、可退金额、幂等性 | `resultStatus`、`approvalRequired`、`writeBackStatus` | 原交易号、退款金额、处理结果 | 一期仅保留审批能力位 |
+| 冲正 | `chargeId`、`sourceTradeNo`、`reasonCode` | 原交易状态、账单状态、可冲正性 | `resultStatus`、`approvalRequired`、`writeBackStatus` | 原交易号、状态变化、处理原因 | 不强接 BPM |
+| 坏账申请 | `chargeId`、`reasonCode`、`remark` | 账龄、客户状态、业务条件 | `resultStatus`、`approvalRequired`、`writeBackStatus` | 申请原因、账单状态、审批边界 | 一期仅保留审批能力位与边界说明 |
+
+## 3. 共性能力
+
+所有场景共享以下能力：
+- 统一入口：`IF-REV-007`
+- 统一账单承接：`biz_charge` / `biz_charge_detail`
+- 统一原交易校验：`bk_transaction` / `bk_transaction_callback` / `bk_transaction_exception`
+- 统一留痕：`biz_operat_log` / `biz_operat_log_detail`
+- 统一结果表达：`resultStatus` / `writeBackStatus`（前者表示处理结论，后者表示账单回写结论）
+- 审批边界：只保留 `approvalRequired`、`PENDING_APPROVAL` 与边界说明，不展开完整 BPM 流程、节点、流转规则或审批回写实现细节
+
+## 4. 排除说明
+
+以下内容不在本矩阵覆盖范围内：
+- 独立账务细表设计
+- 发票、银行结算等其他接口族
+- backend 实施代码结构
+- 完整 BPM 审批流程定义

specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md

@@ -0,0 +1,23 @@
+# Contract: REV-004 一期追溯矩阵
+
+## 1. 目的
+
+用于建立 `spec.md`、详细设计、接口设计、数据库设计之间的稳定追溯关系，确保后续正式文档修订与任务拆解基于同一口径。
+
+## 2. 追溯矩阵
+
+| 规格需求/场景 | 详细设计承接 | 接口设计承接 | 数据库承接 | 说明 |
+|--------------|--------------|--------------|------------|------|
+| 一期纳入范围：水量调整/金额调整/退款/冲正/坏账申请 | `12_REV_Detailed.md` REV-004 场景表 | `03_Interface_Design.md` `IF-REV-007` | `biz_charge*`、`biz_operat_log*` | 五类场景统一纳入一期，排除独立账务细表扩围 |
+| 统一接口入口 | REV-004 接口映射 | `IF-REV-007` 请求/响应定义 | 账单与日志对象 | 不扩展到 `IF-REV-008`、`IF-REV-011` 等其他接口族 |
+| 原交易校验 | REV-004 关键规则 | `sourceTradeNo` 字段 | `bk_transaction*` | 退款/冲正必须联动原交易主状态、回调结果与异常处理状态 |
+| 处理结果回写 | REV-004 业务流程/关键规则 | `writeBackStatus`、`resultStatus` | `biz_charge` 状态承接 | `resultStatus` 与 `writeBackStatus` 必须分离表达 |
+| 审批边界 | 审批留痕要求 | `approvalRequired`、`PENDING_APPROVAL` | 仅能力位，无独立审批表要求 | 一期不强接 BPM，仅保留边界说明 |
+| 留痕与依据 | 操作日志与审批留痕 | `remark`、`attachmentList` | `biz_operat_log` / `biz_operat_log_detail` | 必须覆盖处理类型、原交易引用、前后差异与附件依据 |
+| 旧系统细粒度台账承接 | 迁移补充表 | 历史查询与迁移校验口径 | 历史只读 + 在线主模型 | 不误写为在线新增实体 |
+
+## 3. 使用约束
+
+- 本矩阵只服务于文档规划与后续正式主文档修订。
+- 若某条追溯关系无法在三份正式文档中对齐，应先回写正式主文档，再继续 tasks 或实施讨论。
+- Archive 与执行手册可用于核对，但不得替代正式结论。

specs/001-rev004-accounting/data-model.md

@@ -0,0 +1,167 @@
+# Data Model: REV-004 账务处理一期
+
+## 建模原则
+
+- 以逻辑实体 + 物理承接对象双层表达，避免把未确认能力误写为已落地独立表。
+- 在线主模型优先复用 `biz_charge*`、`biz_operat_log*`、`bk_transaction*`。
+- 审批相关内容仅保留能力位，不展开完整 BPM 流程模型。
+
+## 实体一：AccountingRequest（账务处理申请）
+
+### 作用
+统一承接 `IF-REV-007` 的五类场景输入：水量调整、金额调整、退款、冲正、坏账申请。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requestNo | String | 申请编号/调整业务编号 |
+| adjustType | Enum | `USAGE` / `AMOUNT` / `REFUND` / `REVERSE` / `BAD_DEBT` |
+| chargeId | Long | 目标账单 ID |
+| sourceTradeNo | String | 原交易流水号，退款/冲正场景使用 |
+| adjustAmount | Decimal | 调整金额 |
+| adjustUsage | Decimal | 调整水量 |
+| reasonCode | String | 调整原因编码 |
+| remark | String | 调整说明 |
+| attachmentList | Array<String> | 依据附件 |
+| operatorId | Long | 操作人 ID |
+| requestedAt | DateTime | 发起时间 |
+
+### 校验规则
+- `chargeId`、`adjustType`、`reasonCode`、`operatorId` 必填。
+- `REFUND` / `REVERSE` 场景必须具备 `sourceTradeNo`。
+- `adjustAmount` 与 `adjustUsage` 按场景二选一或组合使用，不允许无意义空提交。
+
+### 状态
+`submitted` → `accepted` / `rejected` → `processed` / `failed`
+
+## 实体二：AccountingResult（账务处理结果）
+
+### 作用
+统一承接处理结果、回写结果与是否需要审批。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| adjustmentNo | String | 调整业务编号 |
+| chargeId | Long | 目标账单 ID |
+| resultStatus | Enum | `SUCCESS` / `PENDING_APPROVAL` / `FAIL` |
+| writeBackStatus | Enum | `SUCCESS` / `IGNORE_REPEAT` / `FAIL` |
+| approvalRequired | Boolean | 是否进入审批 |
+| msg | String | 处理说明 |
+| processedAt | DateTime | 处理时间 |
+
+### 状态关系
+- `resultStatus` 表示业务处理结果。
+- `writeBackStatus` 表示账单回写结果。
+- `approvalRequired=true` 时允许 `resultStatus=PENDING_APPROVAL`。
+
+## 实体三：ChargeAggregate（账单聚合对象）
+
+### 作用
+作为 REV-004 调整、退款、冲正的主要业务承接对象。
+
+### 物理承接
+- `biz_charge`
+- `biz_charge_detail`
+
+### 核心字段
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| chargeId | `biz_charge.id` | 账单主键 |
+| chargeStatus | `biz_charge` | 账单状态 |
+| receivableAmount | `biz_charge` / `biz_charge_detail` | 应收金额 |
+| paidAmount | 业务汇总 | 已收金额 |
+| remainAmount | 业务汇总 | 剩余待支付金额 |
+| detailItems | `biz_charge_detail` | 费用明细集合 |
+
+### 关键关系
+- 1 个 `ChargeAggregate` 对应多条 `biz_charge_detail`。
+- 1 个 `AccountingRequest` 必须定位到 1 个 `ChargeAggregate`。
+
+## 实体四：Transaction（原交易流水）
+
+### 作用
+为退款、冲正等场景提供原交易事实依据。
+
+### 物理承接
+- `bk_transaction`
+- 关联扩展：`bk_transaction_callback`（异步回调结果核对）
+- 关联扩展：`bk_transaction_exception`（异常处理状态核对）
+
+### 核心字段
+
+| 字段 | 说明 |
+|------|------|
+| tradeNo | 渠道交易流水号 |
+| tradeStatus | 原交易状态 |
+| tradeAmount | 原交易金额 |
+| channelCode | 渠道编码 |
+| occurredAt | 交易发生时间 |
+
+### 关键规则
+- `REFUND` / `REVERSE` 必须关联 `tradeNo`。
+- 原交易状态必须满足“可退款/可冲正”业务前提。
+- 原交易校验应同时覆盖交易主状态、回调结果与异常处理状态，不得只校验交易主表存在性。
+
+## 实体五：OperationLog（操作留痕）
+
+### 作用
+记录账务处理前后变化、处理依据与责任归属。
+
+### 物理承接
+- `biz_operat_log`
+- `biz_operat_log_detail`
+
+### 核心字段
+
+| 字段 | 说明 |
+|------|------|
+| bizType | 业务类型 |
+| bizId | 业务对象 ID |
+| operateUser | 操作人 |
+| operateTime | 操作时间 |
+| remark | 处理说明 |
+| beforeValue | 调整前值 |
+| afterValue | 调整后值 |
+| fieldName | 字段级差异项 |
+
+### 关键规则
+- 所有 REV-004 一期场景都必须写入主日志。
+- 涉及金额/水量/状态变化时应写入字段级差异明细。
+
+## 实体六：AccountingEvidence（处理依据）
+
+### 作用
+统一描述原账单、原交易、附件、文字说明等处理依据。
+
+### 核心字段
+
+| 字段 | 说明 |
+|------|------|
+| evidenceType | 原账单 / 原交易 / 附件 / 说明 |
+| sourceRef | 依据引用标识 |
+| snapshotRef | 快照引用 |
+| attachmentList | 附件集合 |
+
+### 说明
+该实体是逻辑约束，不要求本阶段新增物理表；由既有对象引用、附件系统与日志共同承接。
+
+## 关系总览
+
+```text
+AccountingRequest --> ChargeAggregate
+AccountingRequest --> Transaction (REFUND/REVERSE only)
+AccountingRequest --> AccountingEvidence
+AccountingRequest --> AccountingResult
+AccountingRequest --> OperationLog
+ChargeAggregate --> biz_charge_detail (1:N)
+OperationLog --> biz_operat_log_detail (1:N)
+```
+
+## 状态与边界说明
+
+- 一期仅保留审批能力位，不定义完整审批状态机。
+- 旧系统精细账务对象如预存退款明细、价差调整明细、分账调整明细等，不作为一期新增实体表；仅保留业务场景、历史只读与日志承接口径。

specs/001-rev004-accounting/plan.md

@@ -0,0 +1,193 @@
+# Implementation Plan: REV-004 账务处理一期
+
+**Branch**: `001-rev004-accounting` | **Date**: 2026-03-13 | **Spec**: `/specs/001-rev004-accounting/spec.md`
+**Input**: Feature specification from `/specs/001-rev004-accounting/spec.md`
+
+## Summary
+
+本轮围绕 `REV-004` 账务处理一期完成文档收敛与计划设计，不直接进入 backend 代码修改。计划目标是基于既有正式文档统一一期范围、接口口径、数据库承接口径、留痕要求与审批边界，并为后续 `/speckit.tasks` 提供可直接拆解的实施顺序、验收入口与追溯依据。
+
+本次计划输出以 spec 约束为准：一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景；后续实施按“共性能力先统一、场景能力再分批”组织；验收入口限定为文档一致性、计划可拆解性与台账可回写性。
+
+## Technical Context
+
+**Primary Work Product**: REV-004 一期 planning 设计产物，包括实施计划、研究结论、数据模型、合同矩阵、评审与最小校验说明。
+**Source of Truth Documents**:
+- `specs/001-rev004-accounting/spec.md`
+- `.specify/memory/constitution.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+**Reference Sources**:
+- `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/02_Delivery_Standards.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+- `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`
+- `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+**Validation Commands**:
+- `make validate-file FILE=specs/001-rev004-accounting/spec.md`
+- `make validate-file FILE=specs/001-rev004-accounting/plan.md`
+- `make check-links`
+- `make validate-mermaid`
+**Target Scope**:
+- `REV-004` 一期范围收敛
+- `IF-REV-007` 统一接口合同
+- 详细设计 / 接口设计 / 数据库设计之间的追溯关系
+- 留痕、原交易校验、审批边界与台账动作约束
+**Project Type**: 文档治理仓库
+**Constraints**:
+- 不新增平行正式主稿
+- 不发明超出主文档范围的新业务规则
+- Archive 仅作核对与追溯来源，不替代正式结论
+- 审批仅保留能力位和边界说明，不展开完整 BPM
+- 本轮不写 backend 实施代码
+- 仓库内引用保持相对路径口径
+**Scale/Scope**: 跨文档 planning 设计，覆盖 1 个 feature spec、1 个 implementation plan、3 个合同/矩阵产物、1 份数据模型和 1 份 quickstart。
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：本轮产物落在 `specs/001-rev004-accounting/` 规划目录，后续正式落地仍回写既有主文档，不新增平行正式稿。
+- [x] **范围基线已确认**：一期范围限定为 `REV-004` 既有交集场景，统一挂靠 `IF-REV-007`，不扩展到账务平台级重构或其他接口族。
+- [x] **Archive 使用方式合规**：Archive 仅作为历史核对与范围基线来源，未直接替代正式设计结论。
+- [x] **一致性影响已列出**：已识别并约束系统名称、接口编号、账单承接对象、原交易校验对象、日志留痕对象、审批边界和验收入口。
+- [x] **校验与台账动作已规划**：已明确最小校验命令；已明确当前仅生成计划产物时暂不强制更新 `01_Project_Progress.md` / `03_Task_Checklist.md`，待正式主文档修订或任务闭环时再更新。
+
+### Post-Design Re-check
+
+- [x] 设计产物均保持“文档收敛 + 计划准备”定位，未越界到 backend 实施。
+- [x] `data-model.md` 采用逻辑实体 + 物理承接双层表达，未误写在线新增独立账务台账表族。
+- [x] `contracts/` 中所有合同均回扣 `IF-REV-007`、`biz_charge*`、`bk_transaction*`、`biz_operat_log*` 口径。
+- [x] `quickstart.md` 仅定义文档评审与最小校验步骤，未引入超范围构建或发布动作。
+- [x] 设计产物中的审批相关内容均仅保留 `approvalRequired` / `PENDING_APPROVAL` 等能力位和边界说明。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-rev004-accounting/
+├── plan.md                              # 本文件，实施计划主文件
+├── research.md                          # Phase 0 研究结论
+├── data-model.md                        # REV-004 一期逻辑实体与物理承接口径
+├── quickstart.md                        # 评审入口与最小校验步骤
+├── contracts/
+│   ├── if-rev-007-accounting-request.md # IF-REV-007 统一合同
+│   ├── rev004-scenario-matrix.md        # 五类场景矩阵
+│   └── rev004-traceability-matrix.md    # spec / 详设 / 接口 / 数据库追溯矩阵
+└── tasks.md                             # 下一阶段由 /speckit.tasks 生成
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/
+│   ├── 01_Project_Progress.md
+│   ├── 02_Delivery_Standards.md
+│   └── 03_Task_Checklist.md
+├── 01_Overview/
+│   └── 03_Summary_Design.md
+├── 02_Detailed_Design/
+│   └── 12_REV_Detailed.md
+├── 03_Technical_Design/
+│   ├── 01_Database_Design.md
+│   └── 03_Interface_Design.md
+└── 04_Appendix/Archive/
+
+.specify/memory/constitution.md
+docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
+CLAUDE.md
+```
+
+**Structure Decision**:
+- `specs/001-rev004-accounting/spec.md`：作为本 feature 的需求与验收边界总源。
+- `specs/001-rev004-accounting/plan.md`：承接当前计划阶段的实施组织、门禁与结构决策。
+- `specs/001-rev004-accounting/research.md`：沉淀范围、承接对象、审批边界、台账动作等关键选择。
+- `specs/001-rev004-accounting/data-model.md`：把统一接口、结果表达、账单承接、原交易校验、日志留痕固化为逻辑模型。
+- `specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md`：统一 `IF-REV-007` 的请求/响应与共性规则。
+- `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`：把五类场景的输入、校验、结果和留痕差异收敛成统一矩阵。
+- `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`：建立规格、详细设计、接口设计和数据库设计的稳定追溯关系。
+- `specs/001-rev004-accounting/quickstart.md`：为计划评审和后续 tasks 生成提供统一的最小校验入口。
+- `CLAUDE.md`：已通过 agent context 更新脚本同步当前计划的文档治理工作模式。
+
+## Phase 0 Research Summary
+
+1. 一期范围严格收敛到 `REV-004` + `IF-REV-007`，只覆盖水量调整、金额调整、退款、冲正、坏账申请。
+2. 后续实施先统一共性能力，再按场景分批拆解，避免不同场景各自固化状态与承接口径。
+3. 在线主模型复用 `biz_charge*`、`biz_operat_log*` 和 `bk_transaction*`，不新增独立账务台账表族。
+4. 退款/冲正必须联动原交易校验，不能只依赖账单状态。
+5. 审批/BPM 一期只保留能力位与边界说明，不强接完整审批流。
+6. 本轮验收只看文档与计划质量，不以 backend 代码完成度为前提。
+7. 最小校验以文档门禁命令为主，不引入构建、导出或代码测试步骤。
+8. 管理台账仅在正式主文档修订或任务闭环时更新，当前计划产物阶段暂不强制回写。
+
+## Phase 1 Design Outputs
+
+### Data Model
+- `data-model.md` 已定义：
+  - `AccountingRequest`
+  - `AccountingResult`
+  - `ChargeAggregate`
+  - `Transaction`
+  - `OperationLog`
+  - `AccountingEvidence`
+- 其中明确区分逻辑实体与物理承接口径，避免把历史精细台账误写为在线新增实体。
+
+### Contracts
+- `contracts/if-rev-007-accounting-request.md`
+  - 固化 `IF-REV-007` 的请求字段、响应字段、共性规则、物理承接口径与验收关注点。
+- `contracts/rev004-scenario-matrix.md`
+  - 固化五类场景的输入、校验、结果表达和留痕重点。
+- `contracts/rev004-traceability-matrix.md`
+  - 固化 `spec.md`、详设、接口设计、数据库设计之间的追溯关系。
+
+### Quickstart
+- `quickstart.md` 已给出：
+  - 范围校验
+  - 单一真源校验
+  - 追溯关系校验
+  - 审批边界校验
+  - 台账动作校验
+  - 最小校验命令
+
+### Agent Context
+- 已执行 `.specify/scripts/bash/update-agent-context.sh claude`
+- 已同步更新 `CLAUDE.md` 的 agent context。
+
+## Implementation Strategy for Next Phase
+
+下一阶段 `/speckit.tasks` 应按以下顺序拆解：
+
+1. **执行闭环收口任务**
+   - 更新执行手册中的执行顺序、独立验收入口、最小校验动作
+   - 明确 `01_Project_Progress.md` 与 `03_Task_Checklist.md` 的触发式同步条件
+   - 保证审阅者仅通过执行手册与两份治理台账即可判断后续任务可继续推进
+2. **共性能力对齐任务**
+   - 统一一期纳入/排除范围
+   - 统一 `IF-REV-007` 接口合同
+   - 统一 `biz_charge*` / `bk_transaction*` / `biz_operat_log*` 承接口径
+   - 统一 `resultStatus` / `writeBackStatus` / `approvalRequired` 表达
+3. **分场景修订任务**
+   - 水量调整
+   - 金额调整
+   - 退款
+   - 冲正
+   - 坏账申请
+4. **追溯与验收任务**
+   - 追溯矩阵复核
+   - 执行手册 / quickstart / plan / 台账之间的闭环一致性校验
+   - 文档链接 / 单文件校验
+   - 正式主文档修订落地后再决定是否更新项目进度与任务清单
+
+补充约束：
+- `quickstart.md` 负责沉淀评审步骤、最小校验命令与独立验收入口说明。
+- `01_Project_Progress.md` 仅记录新的治理里程碑或正式交付节点，不重复记录普通校验动作。
+- `03_Task_Checklist.md` 仅记录 tracked task 的完成状态与闭环条件，不承担过程性执行日志。
+
+## Complexity Tracking
+
+本计划未发生 Constitution 违规项，无需豁免说明。

specs/001-rev004-accounting/quickstart.md

@@ -0,0 +1,103 @@
+# Quickstart: REV-004 账务处理一期计划评审与最小校验
+
+## 1. 评审入口
+
+本轮目标是：
+- 完成 REV-004 一期文档范围收敛
+- 形成后续实施计划的边界、任务拆解与验收入口
+- 不直接进入 backend 代码修改
+
+本轮验收仅检查：
+- 文档一致性
+- 计划可拆解性
+- 台账可回写性
+
+## 2. 评审步骤
+
+### 步骤一：范围校验
+确认一期只覆盖以下场景：
+- 水量调整
+- 金额调整
+- 退款
+- 冲正
+- 坏账申请
+
+同时确认以下内容未被带入：
+- 新增独立账务台账表族
+- 泛化 BPM 平台扩展
+- 非 `IF-REV-007` 的跨模块接口扩围
+- backend 代码实施内容
+
+### 步骤二：单一真源校验
+对照以下正式口径：
+- `spec.md`
+- `12_REV_Detailed.md`
+- `03_Interface_Design.md`
+- `01_Database_Design.md`
+- `.specify/memory/constitution.md`
+
+确认 plan 中没有用执行手册或 Archive 直接替代正式结论。
+
+### 步骤三：追溯关系校验
+确认以下关系在计划中可直接对应：
+- 场景 → `IF-REV-007`
+- 场景 → `biz_charge` / `biz_charge_detail`
+- 退款/冲正 → `bk_transaction*`
+- 留痕 → `biz_operat_log*`
+
+### 步骤四：审批边界校验
+确认审批相关内容仅保留：
+- `approvalRequired`
+- `PENDING_APPROVAL`
+- 审批边界说明
+
+不展开：
+- 完整 BPM 流程
+- 流程节点
+- 流转规则
+- 审批回写实现细节
+
+### 步骤五：台账动作校验
+确认执行闭环已说明：
+- `01_Project_Progress.md` 只在形成新的治理里程碑或正式交付节点时更新
+- `03_Task_Checklist.md` 只在 tracked task 完成或闭环条件被重新定义时更新
+- 台账更新动作位于正式文档修订与最小校验之后，而不是默认并行执行
+
+### 步骤六：独立验收入口校验
+确认审阅者仅通过以下文件即可完成 US3 验收：
+- `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+
+并确认无需查看 backend 代码、运行态脚本或 Archive 历史附件，即可判断后续任务可继续拆解推进。
+
+### 步骤七：正式文档修订闭环校验
+若后续进入正式主文档修订，统一按以下顺序执行：
+1. 先更新执行手册中的执行顺序、验收入口、最小校验动作与台账触发条件。
+2. 再同步 `quickstart.md`、`plan.md` 等支撑产物，保持闭环表述一致。
+3. 每修改 1 份目标文档，执行对应 `make validate-file FILE=<目标文件>`。
+4. 涉及跨文档引用变更时执行 `make check-links`。
+5. 仅当里程碑成立或 tracked task 完成条件发生实质变化时，再回写两份治理台账。
+
+## 3. 最小校验命令
+
+```bash
+make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
+make validate-file FILE=docs/design/00_Management/01_Project_Progress.md
+make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md
+make check-links
+```
+
+说明：
+- 本轮校验聚焦执行手册与治理台账闭环，不再以 `spec.md` / `plan.md` 作为唯一校验对象。
+- `make check-links` 用于确认执行手册与两份治理台账之间的相对链接和引用关系正常。
+- 若后续进入新的正式主文档修订批次，应补充对应目标文件的 `make validate-file FILE=<目标文件>`。
+
+## 4. 通过标准
+
+满足以下条件即可进入下一批 tasks 执行：
+- 后续任务拆解顺序已明确：执行手册 → 支撑产物 → 台账同步
+- 独立验收入口已明确，审阅者仅需查看执行手册与两份治理台账
+- 最小校验动作已明确并可直接执行
+- 项目进度与任务清单的更新触发条件已写清楚
+- 后续工作可继续按文档修订、校验、台账同步三类动作拆解推进

specs/001-rev004-accounting/research.md

@@ -0,0 +1,56 @@
+# Phase 0 Research: REV-004 账务处理一期
+
+## Decision 1: 一期范围严格收敛到 `REV-004` + `IF-REV-007`
+- **Decision**: 一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，并以 `IF-REV-007` 作为统一账务处理入口。
+- **Rationale**: `spec.md`、`12_REV_Detailed.md`、`03_Interface_Design.md` 与 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` 对该范围已形成交集口径；继续扩展到 `IF-REV-008`、`IF-REV-011` 或 `IF-CS-*`、`IF-METER-*` 会超出一期边界。
+- **Alternatives considered**:
+  - 扩展为账务平台级改造：超范围。
+  - 按旧系统菜单全量恢复所有账务对象：不符合“保守补完”原则。
+
+## Decision 2: 先统一共性能力，再按场景分批组织后续实施计划
+- **Decision**: 后续实施计划采用“共性能力先统一、场景能力再分批”的组织方式。
+- **Rationale**: 各场景共享留痕、原始依据、结果状态、回写状态、接口与数据库口径；先统一这些共性能力，才能避免场景拆解后产生重复建模和状态不一致。
+- **Alternatives considered**:
+  - 先做退款或冲正单场景：容易固化局部口径。
+  - 所有场景并行拆分：放大一致性风险。
+
+## Decision 3: 在线主模型复用 `biz_charge*` + `biz_operat_log*`，不新增独立账务台账表族
+- **Decision**: 一期在线主模型以 `biz_charge`、`biz_charge_detail`、`biz_operat_log`、`biz_operat_log_detail` 为主承接，退款/冲正等场景按流程与留痕处理，不新建平行细表。
+- **Rationale**: `01_Database_Design.md` 已明确旧系统精细账务台账按历史只读保留，新发生业务由在线主模型与日志承接；`12_REV_Detailed.md` 也要求未识别为独立实体的对象只保留业务场景语义。
+- **Alternatives considered**:
+  - 新增预存退款/价差调整/分账调整明细表：违背一期最小闭环原则。
+  - 机械平移旧系统全部账务表：与当前正式主文档不一致。
+
+## Decision 4: 退款/冲正必须联动原交易校验
+- **Decision**: 退款、冲正等涉及原支付修正的场景，统一依赖 `bk_transaction*` 进行原交易存在性、状态与可处理性校验。
+- **Rationale**: `12_REV_Detailed.md` 要求退款、冲正与原支付流水及渠道状态联动；执行手册把“原交易存在性 / 可退金额 / 状态可调性”列为一期关键缺口。
+- **Alternatives considered**:
+  - 仅按账单状态处理：审计与对账风险高。
+  - 各场景独立定义交易校验：口径会分裂。
+
+## Decision 5: 审批/BPM 一期只保留能力位
+- **Decision**: 一期仅保留 `approvalRequired`、`PENDING_APPROVAL` 等能力位和边界说明，不展开完整审批流程、节点或流转规则，也不强接 BPM。
+- **Rationale**: `spec.md` 已明确审批相关内容本轮仅保留能力位；执行手册说明 BPM 只有在审批场景、流程 key、回写规则确认后才实接。
+- **Alternatives considered**:
+  - 一期直接实接 BPM：前提不足。
+  - 完全忽略审批：与详设、接口和规格不一致。
+
+## Decision 6: 本轮验收入口以文档与计划质量为准
+- **Decision**: 本轮验收入口限定为文档一致性、计划可拆解性与台账可回写性，不以 backend 代码完成度作为前提。
+- **Rationale**: 当前 feature 已在 clarify 中明确“文档收敛 + 生成实施计划，但先不改 backend 代码”。
+- **Alternatives considered**:
+  - 以代码落地作为本轮验收：不符合当前阶段目标。
+
+## Decision 7: Plan 阶段的最小校验以文档门禁为主
+- **Decision**: quickstart 与计划中的最小校验以 `make validate-file`、`make check-links`、`make validate-mermaid` 为主，不引入构建、导出或代码编译命令。
+- **Rationale**: Constitution 要求按文档改动范围执行最小校验；当前 plan 阶段的交付对象仍是文档设计产物。
+- **Alternatives considered**:
+  - 使用全量 `make validate` 或导出命令：成本过高，且不属于当前最小门禁。
+  - 加入 backend 构建/测试命令：超出本轮范围。
+
+## Decision 8: Project Progress / Task Checklist 仅在正式变更或任务闭环时更新
+- **Decision**: 仅生成 speckit plan/research 产物时不强制更新 `01_Project_Progress.md` 和 `03_Task_Checklist.md`；待正式主文档修订落地或任务拆解/完成时再更新。
+- **Rationale**: 台账应承载正式里程碑和任务闭环，而不是记录计划草稿流水。
+- **Alternatives considered**:
+  - 在 plan 阶段立即更新全部台账：噪音过大。
+  - 完全不考虑台账更新：不符合宪法闭环要求。

specs/001-rev004-accounting/spec.md

@@ -0,0 +1,134 @@
+# Feature Specification: REV-004 账务处理一期
+
+**Feature Branch**: `001-rev004-accounting`
+**Created**: 2026-03-13
+**Status**: Draft
+**Input**: User description: "我想先做的 REV-004"
+
+## Document Scope & Sources *(mandatory)*
+
+- **Target documents**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+  - `docs/design/00_Management/01_Project_Progress.md`
+  - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+  - `docs/design/01_Overview/03_Summary_Design.md`
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `.specify/memory/constitution.md`
+- **Reference sources**:
+  - `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+  - `docs/design/00_Management/15_Legacy_Migration_Gap_Analysis.md`
+  - `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+- **Scope decision**: In scope。该需求属于既有 `REV-004` 模块范围内的账务处理一期收敛任务，允许在现有正式文档体系内补齐范围、接口、数据口径和执行约束，并输出后续实施计划所需的边界、任务拆解与验收依据；本轮不直接进入 backend 代码修改，不包含超出一期边界的新业务域扩展。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 收敛一期范围 (Priority: P1)
+
+作为项目负责人，我需要先把 `REV-004` 一期的业务边界、纳入场景和排除项写清楚，以便团队在启动后续工作时不会把退款、冲正、坏账等事项扩展成超范围的账务重构任务。
+
+**Why this priority**: 范围不收敛会直接导致后续计划、任务和实施偏离宪法规定的“范围交集优先”。
+
+**Independent Test**: 审阅者仅通过 `12_REV_Detailed.md` 与 `REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，即可确认一期纳入范围、排除范围和关键对象是否一致。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前 `REV-004` 在多个文档中仅有摘要性描述，**When** 完成本次规格修订，**Then** 审阅者能够明确识别一期纳入场景、排除项和边界依据。
+2. **Given** 团队准备启动后续计划或执行，**When** 查阅本次规格，**Then** 不会把非一期内容误判为当前必须推进的范围。
+
+---
+
+### User Story 2 - 对齐接口与数据口径 (Priority: P2)
+
+作为方案设计与评审人员，我需要让 `REV-004` 的详细设计、接口设计和数据库设计在同一口径下表达账务处理对象、处理结果和留痕要求，以便评审时可以追溯并核对。
+
+**Why this priority**: `REV-004` 当前涉及详细设计、接口定义和数据库承接说明，若三者不一致，会直接影响后续任务分解与验收。
+
+**Independent Test**: 审阅者仅通过对照 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，即可确认账务处理场景、核心对象和留痕要求是否一致。
+
+**Acceptance Scenarios**:
+
+1. **Given** 账务处理涉及详细设计、接口和数据库三个正式文档，**When** 完成本次规格定义，**Then** 审阅者能够在三份文档之间建立稳定的追溯关系。
+
+---
+
+### User Story 3 - 形成可执行交付闭环 (Priority: P3)
+
+作为项目维护人员，我需要把 `REV-004` 的执行手册与项目管理台账同步起来，并明确后续实施计划按“共性能力先统一、场景能力再分批”的方式组织，以便后续进入 clarify、plan、tasks 阶段时，能够先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解任务并留存过程记录，而不在本轮直接进入 backend 代码修改；本轮验收入口应以文档一致性、计划可拆解性和台账可回写性为准。
+
+**Why this priority**: 没有交付闭环，`REV-004` 容易停留在文档存在但不可执行、已推进但未回写台账的状态。
+
+**Independent Test**: 审阅者仅通过检查执行手册和管理台账，即可确认 `REV-004` 的目标、完成条件、实施计划边界、共性能力优先顺序、验收入口和后续动作已被记录。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前仓库已有 `REV-004` 执行手册和相关任务记录，**When** 完成本次规格，**Then** 审阅者能够判断哪些台账需要同步、何时视为一期范围收口完成，以及后续实施计划应先覆盖哪些共性能力、再拆解哪些业务场景。
+2. **Given** 当前阶段仍以文档收敛和计划准备为主，**When** 审阅者据此验收本轮规格，**Then** 其可直接依据规格确认文档口径是否一致、后续计划是否可拆解、台账更新点是否明确，而无需以代码完成度作为前提。
+
+---
+
+### Edge Cases
+
+- 当历史资料中出现比当前主文档更细的账务场景时，必须仅作为参考来源，不得直接提升为当前一期必做范围。
+- 当接口、详细设计与数据库文档对同一账务对象使用不同名称或粒度时，必须先统一正式口径，再进入后续计划或实施。
+- 当一期范围内存在“需要审批”类表述时，本轮仅保留能力位和边界说明，不展开完整审批流程、节点或流转规则。
+- 当执行手册与项目进度台账状态不一致时，必须明确以当前主文档与本次规格确认后的口径回写台账。
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST 明确 `REV-004` 一期的目标文档清单，并说明每份文档承担的职责。
+- **FR-002**: Specification MUST 明确 `REV-004` 一期的主口径来源，包括概要、详细、接口、数据库与项目宪法。
+- **FR-003**: Specification MUST 明确 `REV-004` 一期纳入范围，包括账务调整、退款、冲正、坏账申请等当前主文档已覆盖的核心场景。
+- **FR-004**: Specification MUST 明确后续实施计划按“共性能力先统一、场景能力再分批”的方式组织：先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解实施。
+- **FR-005**: Specification MUST 明确 `REV-004` 一期不纳入范围，避免将非一期台账细化、跨模块重构或未确认能力带入本轮工作。
+- **FR-006**: Specification MUST 明确 `REV-004` 在详细设计、接口设计和数据库设计之间的追溯关系，确保核心对象和处理结果表达一致。
+- **FR-007**: Specification MUST 明确账务处理留痕、原始依据和结果回写属于本次范围内必须说明的内容。
+- **FR-008**: Specification MUST 明确执行手册、项目进度和任务清单是否需要同步更新，以及更新触发条件。
+- **FR-009**: Specification MUST 明确后续实施计划需要覆盖的边界、任务拆解和验收入口；本轮验收入口应限定为文档一致性、计划可拆解性和台账可回写性，不得把 backend 代码修改写成本轮已执行内容。
+- **FR-010**: Specification MUST 明确审批相关表述在本轮仅保留能力位和边界说明，不展开完整审批流程、节点或流转规则。
+- **FR-011**: Specification MUST 明确后续进入 clarify、plan、tasks 前必须完成的最小校验动作。
+- **FR-012**: Specification MUST 保持用户视角和业务视角表述，不将具体实现语言、接口路径、代码结构或脚本命令写成本规格的验收前提。
+
+### Key Entities *(include if feature involves data)*
+
+- **REV-004 一期范围**: 本轮允许推进的账务处理业务集合，用于约束纳入内容与排除内容。
+- **共性能力**: 在分场景实施前需要统一规划的留痕、原始依据、结果状态以及接口/数据库口径要求。
+- **账务处理场景**: 账务调整、退款、冲正、坏账申请等业务事项，是本次规格的核心业务对象。
+- **正式目标文档**: 承载 `REV-004` 设计口径的正式 Markdown 文档，用于落地单一真源。
+- **参考来源**: 用于核对历史边界、迁移差距或执行建议的辅助文档，不直接替代正式结论。
+- **留痕要求**: 对账务处理前后变化、处理依据、结果状态和责任归属的记录要求。
+- **台账更新**: 项目进度与任务清单中的记录动作，用于形成阶段性交付闭环。
+
+## Assumptions
+
+- 本次“先做 REV-004”默认指向 `REV-004` 账务处理一期的文档范围收敛，并在同一轮明确后续实施计划所需的边界、任务拆解与验收入口，而不是直接启动跨模块代码开发。
+- 后续实施计划默认采用“共性能力先统一、场景能力再分批”的组织方式：先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解。
+- 当前一期默认聚焦既有主文档已覆盖的账务处理核心场景，不额外扩大到新的独立台账体系或跨模块能力改造。
+- 若资料中出现审批相关描述，本轮默认仅保留能力位和边界说明，不细化为完整审批流程定义。
+- 若后续 clarify 阶段确认需要进一步收缩到单一子场景，本规格仍可作为 `REV-004` 一期总范围基线。
+- 本规格已完成 clarify 收敛；后续阶段应基于已确认边界继续推进 `/speckit.plan`、`/speckit.tasks`、`/speckit.analyze` 与正式文档修订。
+
+## Clarifications
+
+### Session 2026-03-13
+
+- Q: 本轮 `REV-004` 目标深度是仅做文档收敛，还是同时产出后续实施计划，或直接进入文档加 backend 一期闭环？ → A: 本轮完成文档收敛，并生成后续实施计划所需的边界、任务拆解与验收要求，但先不改 backend 代码。
+- Q: 后续实施计划应整体覆盖一期全部场景，还是按不同场景分批组织？ → A: 按“共性能力先统一、场景能力再分批”的方式组织，先统一留痕、原始依据、结果状态以及接口/数据库口径，再按账务调整、退款、冲正、坏账申请等场景拆解。
+- Q: 本轮规格的验收入口应收敛到哪一层？ → A: 以文档一致性、计划可拆解性和台账可回写性作为本轮验收入口，不以代码完成度作为前提。
+- Q: 审批相关场景在本轮应细化到什么程度？ → A: 本轮仅保留能力位和边界说明，不展开完整审批流程、节点或流转规则。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 规格中明确列出至少 4 份 `REV-004` 相关目标文档，且每份文档的职责可被审阅者独立理解。
+- **SC-002**: 审阅者在阅读规格后，可在 5 分钟内判断 `REV-004` 一期哪些场景纳入、哪些内容排除，无需再查找额外上下文才能做出范围判断。
+- **SC-003**: 审阅者可依据规格明确识别详细设计、接口设计、数据库设计与执行手册之间的追溯关系，且不存在职责重叠或空缺。
+- **SC-004**: 审阅者可依据规格直接列出后续实施计划应覆盖的边界、任务拆解与验收入口，并能独立确认本轮是否已满足文档一致性、计划可拆解性和台账可回写性三项验收条件。

specs/001-rev004-accounting/tasks.md

@@ -0,0 +1,203 @@
+# Tasks: REV-004 账务处理一期
+
+**Input**: Design documents from `/specs/001-rev004-accounting/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
+
+**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks.
+
+**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/`
+- Governance documents: `docs/design/00_Management/`
+- Archive references: `docs/design/04_Appendix/Archive/`
+- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/`
+
+## Phase 1: Setup (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set, target files, and planning artifacts before editing formal documents.
+
+- [X] T001 Read prerequisite governance documents `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/02_Delivery_Standards.md`, and `docs/design/00_Management/03_Task_Checklist.md` before formal document edits
+- [X] T002 Confirm target chapters and intended updates in `specs/001-rev004-accounting/spec.md`, `specs/001-rev004-accounting/plan.md`, `docs/design/02_Detailed_Design/12_REV_Detailed.md`, `docs/design/03_Technical_Design/03_Interface_Design.md`, and `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T003 [P] Confirm source-of-truth and allowed references using `.specify/memory/constitution.md`, `docs/design/01_Overview/03_Summary_Design.md`, `docs/design/02_Detailed_Design/12_REV_Detailed.md`, `docs/design/03_Technical_Design/03_Interface_Design.md`, and `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T004 [P] Confirm scope boundary, exclusions, traceability anchors, and impacted files in `specs/001-rev004-accounting/research.md`, `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`, `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`, and `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+
+---
+
+## Phase 2: Foundational Alignment (Blocking Prerequisites)
+
+**Purpose**: Prepare the common wording, structure, and traceability baseline that all user stories depend on.
+
+- [X] T005 Normalize common terminology, scenario names, and approval boundary wording in `specs/001-rev004-accounting/data-model.md`, `specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md`, and `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`
+- [X] T006 [P] Map shared entities and result fields from `specs/001-rev004-accounting/data-model.md` into target update notes for `docs/design/02_Detailed_Design/12_REV_Detailed.md` and `docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T007 [P] Map shared physical carriers from `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md` into target update notes for `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T008 Establish a single update checklist for validation and ledger-sync using `specs/001-rev004-accounting/quickstart.md`, `docs/design/00_Management/01_Project_Progress.md`, and `docs/design/00_Management/03_Task_Checklist.md`
+
+---
+
+## Phase 3: User Story 1 - 收敛一期范围 (Priority: P1) 🎯 MVP
+
+**Goal**: 在正式详细设计与执行手册中明确 REV-004 一期纳入范围、排除项、共性能力优先顺序与审批边界。
+
+**Independent Test**: 审阅者仅通过 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 与 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`，即可确认一期纳入场景、排除项、审批边界和“共性能力先统一、场景能力再分批”的组织方式一致。
+
+### Implementation for User Story 1
+
+- [X] T009 [US1] Update REV-004 一期范围、排除项、共性能力顺序和审批边界 in `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T010 [US1] Sync REV-004 执行范围、验收入口和后续实施组织方式 in `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T011 [P] [US1] Sync REV-004 一期范围摘要 and cross-references in `docs/design/01_Overview/03_Summary_Design.md`
+- [X] T012 [US1] Update traceability note for scoped scenarios in `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+- [X] T013 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result for `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T014 [US1] Run `make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` and capture result for `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T015 [US1] Run `make check-links` and capture cross-document link result for US1 file changes
+- [X] T016 [US1] Update important progress note in `docs/design/00_Management/01_Project_Progress.md` if US1 produces an important formal document change after validation passes
+- [X] T017 [US1] Update REV-004 scope task status in `docs/design/00_Management/03_Task_Checklist.md` if US1 completes a tracked task or materially changes its closure condition
+
+**Checkpoint**: User Story 1 is reviewable, validated, and ledger-synced independently.
+
+---
+
+## Phase 4: User Story 2 - 对齐接口与数据口径 (Priority: P2)
+
+**Goal**: 在详细设计、接口设计与数据库设计中统一 IF-REV-007、账单承接对象、原交易校验对象、结果表达和留痕对象。
+
+**Independent Test**: 审阅者仅通过对照 `docs/design/02_Detailed_Design/12_REV_Detailed.md`、`docs/design/03_Technical_Design/03_Interface_Design.md`、`docs/design/03_Technical_Design/01_Database_Design.md`，即可确认 REV-004 的核心场景、请求/响应字段、物理承接口径和追溯关系一致。
+
+### Implementation for User Story 2
+
+- [X] T018 [US2] Update REV-004 scenario rules, result fields, and log requirements in `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T019 [US2] Update IF-REV-007 request/response, approval boundary, and acceptance notes in `docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T020 [US2] Update REV-004 physical carrier wording for `biz_charge*`, `bk_transaction*`, and `biz_operat_log*` in `docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T021 [P] [US2] Sync shared entity and field mapping notes in `specs/001-rev004-accounting/data-model.md`
+- [X] T022 [P] [US2] Sync contract details and scenario matrix notes in `specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md` and `specs/001-rev004-accounting/contracts/rev004-scenario-matrix.md`
+- [X] T023 [US2] Update traceability rows for interface/database alignment in `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+- [X] T024 [US2] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result for US2 detailed design changes
+- [X] T025 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture result for interface design changes
+- [X] T026 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture result for database design changes
+- [X] T027 [US2] Run `make check-links` and capture cross-document link result for US2 file changes
+- [X] T028 [US2] Update important progress note in `docs/design/00_Management/01_Project_Progress.md` if US2 produces an important formal document change after validation passes
+- [X] T029 [US2] Update REV-004 interface/database alignment task status in `docs/design/00_Management/03_Task_Checklist.md` if US2 completes a tracked task or materially changes its closure condition
+
+**Checkpoint**: User Story 2 is reviewable and validated independently.
+
+---
+
+## Phase 5: User Story 3 - 形成可执行交付闭环 (Priority: P3)
+
+**Goal**: 在执行手册与管理台账中固化 REV-004 的后续实施顺序、验收入口、最小校验动作与台账更新触发条件。
+
+**Independent Test**: 审阅者仅通过 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`、`docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md`，即可确认 REV-004 后续 tasks 的拆解依据、验收入口、最小校验动作和台账同步方式已经明确。
+
+### Implementation for User Story 3
+
+- [X] T030 [US3] Update REV-004 execution sequence, independent acceptance entry, and validation steps in `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T031 [US3] Record REV-004 planning milestone and next-step entry in `docs/design/00_Management/01_Project_Progress.md` if US3 forms an important governance or formal delivery milestone
+- [X] T032 [US3] Update REV-004 tracked checklist items and completion criteria in `docs/design/00_Management/03_Task_Checklist.md` if US3 completes or materially redefines a tracked task
+- [X] T033 [P] [US3] Sync quick review and validation wording in `specs/001-rev004-accounting/quickstart.md`
+- [X] T034 [P] [US3] Sync task-splitting and closure assumptions in `specs/001-rev004-accounting/plan.md`
+- [X] T035 [US3] Run `make validate-file FILE=docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` and capture result for execution playbook changes
+- [X] T036 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and capture result for project progress changes
+- [X] T037 [US3] Run `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture result for task checklist changes
+- [X] T038 [US3] Run `make check-links` and capture cross-document link result for US3 file changes
+
+**Checkpoint**: All planned document updates are independently reviewable, validated, and ledger-synced.
+
+---
+
+## Final Phase: Polish & Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [X] T039 [P] Re-check source-of-truth alignment across `docs/design/02_Detailed_Design/12_REV_Detailed.md`, `docs/design/03_Technical_Design/03_Interface_Design.md`, `docs/design/03_Technical_Design/01_Database_Design.md`, and `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md`
+- [X] T040 [P] Re-check relative links, traceability rows, and Mermaid consistency across `docs/design/01_Overview/03_Summary_Design.md`, `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/03_Task_Checklist.md`, and `specs/001-rev004-accounting/contracts/rev004-traceability-matrix.md`
+- [X] T041 Prepare final change summary with modified files, validation results, remaining risks, and next-step suggestions in the final response for `/specs/001-rev004-accounting/tasks.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1: Setup**: No dependencies; MUST finish before document updates.
+- **Phase 2: Foundational Alignment**: Depends on Phase 1; MUST finish before story implementation.
+- **US1 (P1)**: Starts after Phase 2; defines the MVP scope baseline.
+- **US2 (P2)**: Starts after US1 scope wording is stable, because interface/database alignment depends on agreed scenario scope.
+- **US3 (P3)**: Starts after US1 and US2, because ledger closure depends on settled scope and aligned formal documents.
+- **Final Phase**: Depends on all selected user stories being complete.
+
+### Within Each User Story
+
+- Update formal target documents before syncing contracts, quickstart, or traceability notes.
+- Complete content edits before running validation commands.
+- Complete validation before writing progress or checklist ledger entries.
+- Complete ledger sync before final cross-cutting closure.
+
+### User Story Completion Order
+
+- `US1 → US2 → US3`
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel after `T001` and `T002`.
+- `T006` and `T007` can run in parallel after `T005`.
+- In US1, `T010` and `T011` can run in parallel after `T009`.
+- In US2, `T021` and `T022` can run in parallel after `T018` / `T019` / `T020` complete.
+- In US3, `T033` and `T034` can run in parallel after `T030` / `T031` / `T032` are scoped.
+- In the final phase, `T039` and `T040` can run in parallel.
+
+---
+
+## Parallel Execution Examples
+
+### User Story 1
+
+```text
+# After T009 completes, run in parallel:
+- T010 Update docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md
+- T011 Update docs/design/01_Overview/03_Summary_Design.md
+```
+
+### User Story 2
+
+```text
+# After T018/T019/T020 complete, run in parallel:
+- T021 Sync specs/001-rev004-accounting/data-model.md
+- T022 Sync specs/001-rev004-accounting/contracts/if-rev-007-accounting-request.md and rev004-scenario-matrix.md
+```
+
+### User Story 3
+
+```text
+# After core US3 updates are planned, run in parallel:
+- T033 Sync specs/001-rev004-accounting/quickstart.md
+- T034 Sync specs/001-rev004-accounting/plan.md
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 only)
+
+先完成 US1，把 REV-004 一期范围、排除项、审批边界和共性能力顺序稳定下来。只要 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 与 `docs/guides/REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md` 已可独立评审并完成最小校验，就可以形成第一版可评审增量。
+
+### Incremental Delivery
+
+1. 完成 US1，锁定一期边界。
+2. 完成 US2，打通详细设计、接口设计、数据库设计的一致口径。
+3. 完成 US3，补齐执行手册与台账闭环。
+4. 完成 Final Phase，做全局复核与结果汇总。
+
+### Notes
+
+- 每个任务都必须保持单一真源模型，不得把 Archive 直接当成正式输出。
+- 本 feature 未要求 TDD 或新增自动化测试，因此本任务列表不生成代码测试任务。
+- `make check-links` 在多个故事中重复出现，是因为每个故事都要求独立可验收。
+- 若后续正式文档未实际修改，可在执行时将对应台账更新任务标记为不适用，但必须先给出理由。

specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md

@@ -0,0 +1,68 @@
+# Contract: IF-REV-008 发票申请接口
+
+## 1. 合同定位
+
+本合同用于固化 REV-005 一期后台发票申请 / 单笔与批量开票接口口径，服务于后续正式接口文档修订、任务拆解与 backend 实施。
+
+## 2. 适用范围
+
+适用场景：
+- 后台营业收费员 / 财务人员发起单笔开票
+- 后台按已收费账单集合批量发起开票
+- 生成发票申请记录并提交 `SYS-008`
+
+不适用范围：
+- 客户侧直接申请开票
+- 原始单账单直接任意部分金额开票
+- 复杂拆分/合并开票策略配置
+
+## 3. 请求合同
+
+| 字段 | 类型 | 必填 | 说明 | 约束 |
+|------|------|------|------|------|
+| applicationNo | String | 否 | 发票申请单号 | 服务端生成，作为幂等主键之一 |
+| chargeIds | Array<Long> | 是 | 关联账单 ID 列表 | 所有账单必须已收费且未开票 |
+| custId | Long | 是 | 客户 ID | 必须存在可用开票信息 |
+| invoiceType | String | 是 | 发票类型 | `ELECTRONIC` / `PAPER` |
+| invoiceTitle | String | 是 | 发票抬头 | 来自 `biz_cust_invoice` 或后台确认输入 |
+| taxNo | String | 否 | 纳税人识别号 | 企业抬头场景建议必填 |
+| email | String | 否 | 接收邮箱 | 电子发票场景优先使用 |
+| mobile | String | 否 | 接收手机号 | 推送或通知场景使用 |
+| sourceChannel | String | 是 | 来源渠道 | `COUNTER` / `FINANCE_BACKOFFICE` |
+| remark | String | 否 | 申请备注 | 进入操作留痕 |
+
+## 4. 响应合同
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| invoiceId | Long | 发票申请记录 ID | 对应 `biz_invoice.id` |
+| applicationNo | String | 发票申请单号 | 后续查询与幂等主键 |
+| invoiceStatus | String | 当前状态 | `SUBMITTED` / `PENDING` / `REJECTED` |
+| sysRequestNo | String | `SYS-008` 受理号 | 异步查询主键 |
+| msg | String | 处理说明 | 不可开票时返回明确原因 |
+
+## 5. 共性规则
+
+1. 所有账单必须处于“已收费、未开票、未作废”状态。
+2. 一期不支持对原始单账单直接任意部分金额开票。
+3. 如需多张发票，需来源于拆账/分账后的账单集合。
+4. 幂等控制可采用 `applicationNo` 或 `custId + chargeIds` 组合。
+5. 申请成功后必须生成查询补偿任务，不可依赖回调作为唯一结果来源。
+6. 所有申请动作必须写入操作留痕。
+
+## 6. 物理承接口径
+
+| 逻辑对象 | 物理承接 |
+|---------|----------|
+| 发票申请主对象 | `biz_invoice` |
+| 客户开票信息 | `biz_cust_invoice` |
+| 税率配置 | `biz_invoice_taxrate` |
+| 关联账单 | `biz_charge*` |
+| 操作留痕 | `biz_operat_log*` |
+
+## 7. 验收关注点
+
+- 是否支持后台单笔 / 批量已收费账单开票
+- 是否拒绝原始单账单直接部分金额开票
+- 是否生成申请单号与查询主键
+- 是否与 `SYS-008` 查询兜底模式一致

specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md

@@ -0,0 +1,65 @@
+# Contract: IF-REV-009 发票结果查询与客户侧消费接口
+
+## 1. 合同定位
+
+本合同用于固化 REV-005 一期发票结果查询、查询兜底补偿以及客户侧查看/下载/推送已开票电子发票的统一口径。
+
+## 2. 适用范围
+
+适用场景：
+- 后台按申请单号 / 受理号查询发票最终状态
+- 系统定时轮询 `SYS-008` 获取开票结果
+- 客户侧查看已开具电子发票
+- 客户侧下载、推送电子发票
+
+不适用范围：
+- 客户侧直接发起开票申请
+- 发票作废 / 红冲全流程深度处理
+
+## 3. 查询请求合同
+
+| 字段 | 类型 | 必填 | 说明 | 约束 |
+|------|------|------|------|------|
+| applicationNo | String | 否 | 发票申请单号 | 与 `sysRequestNo` 二选一 |
+| sysRequestNo | String | 否 | 外部受理号 | 与 `applicationNo` 二选一 |
+| custId | Long | 否 | 客户 ID | 客户侧查询时使用 |
+| querySource | String | 是 | 查询来源 | `SYSTEM_JOB` / `ADMIN` / `CUSTOMER` |
+| pushEmail | String | 否 | 推送邮箱 | 客户侧推送时使用 |
+
+## 4. 查询响应合同
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| invoiceId | Long | 发票记录 ID | 对应 `biz_invoice.id` |
+| applicationNo | String | 发票申请单号 | 幂等主键 |
+| invoiceStatus | String | 发票状态 | `PENDING` / `SUCCESS` / `FAIL` / `INVALID` / `RED_INK` |
+| invoiceCode | String | 发票代码 | 成功后返回 |
+| invoiceNumber | String | 发票号码 | 成功后返回 |
+| fileUrl | String | 电子票下载地址 | 成功后返回 |
+| failReason | String | 失败原因 | 失败时返回 |
+| pushStatus | String | 推送状态 | `NONE` / `PUSHED` / `FAIL` |
+| lastQueryTime | DateTime | 最近查询时间 | 用于补偿追踪 |
+
+## 5. 共性规则
+
+1. 查询兜底是开票结果获取的必备路径，不可省略。
+2. 已成功开票状态不得被后续失败结果覆盖。
+3. 客户侧只允许查询、下载、推送属于当前客户的已开票电子发票。
+4. 下载/推送前必须校验发票状态为 `SUCCESS` 且存在 `fileUrl`。
+5. 查询补偿任务需记录 `lastTryTime`、`nextTryTime`、`tryCount` 等信息。
+
+## 6. 物理承接口径
+
+| 逻辑对象 | 物理承接 |
+|---------|----------|
+| 发票结果主对象 | `biz_invoice` |
+| 客户查询身份与资料 | `biz_cust_invoice` |
+| 查询补偿与结果留痕 | `biz_invoice` 扩展字段 + `biz_operat_log*` |
+| 账单发票摘要展示 | `biz_charge*` + 历史关系快照 |
+
+## 7. 验收关注点
+
+- 是否支持后台按申请单号 / 受理号查询结果
+- 是否支持系统任务轮询补偿
+- 是否支持客户侧查看、下载、推送已开票电子发票
+- 是否避免客户侧越权查询和重复推送

specs/002-rev005-invoice-flow/data-model.md

@@ -0,0 +1,170 @@
+# Data Model: REV-005 发票业务流实现
+
+## 建模原则
+
+- 以“逻辑实体 + 现有在线主表承接 + 历史关系快照”三层表达，避免把旧系统全部 IV_* 细表误写为当前已落地在线表。
+- 后台开票、客户侧查询下载、`SYS-008` 查询兜底、结果回写统一围绕单一发票申请主线建模。
+- 一期不支持原始单账单直接任意部分开票，但关系模型需兼容拆账/分账后的多账单、多发票映射扩展。
+
+## 实体一：InvoiceApplication（发票申请单）
+
+### 作用
+统一承接后台单笔/批量已收费账单的发票申请输入，是 `IF-REV-008` 的主业务对象。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| applicationNo | String | 发票申请单号 / 协同请求号 |
+| chargeIds | Array<Long> | 关联账单 ID 列表 |
+| custId | Long | 客户 ID |
+| invoiceType | Enum | `ELECTRONIC` / `PAPER` |
+| invoiceTitle | String | 发票抬头 |
+| taxNo | String | 纳税人识别号 |
+| invoiceAmount | Decimal | 本次申请开票总金额 |
+| receiverEmail | String | 电子票接收邮箱 |
+| receiverMobile | String | 电子票接收手机号 |
+| sourceChannel | Enum | `COUNTER` / `FINANCE_BACKOFFICE` |
+| applyStatus | Enum | `SUBMITTED` / `ACCEPTED` / `REJECTED` |
+| appliedAt | DateTime | 申请时间 |
+
+### 校验规则
+- `chargeIds`、`custId`、`invoiceType`、`invoiceTitle` 必填。
+- 账单必须满足“已收费、未开票、未作废”。
+- 原始单账单不允许直接任意部分金额开票；如需多张发票应来源于拆账/分账后的账单集合。
+- 对同一账单组合的重复申请需按 `applicationNo` 或 `custId + chargeIds` 做幂等控制。
+
+### 物理承接
+- 主承接：`biz_invoice`
+- 关联输入：`biz_cust_invoice`、`biz_charge*`
+
+## 实体二：InvoiceRecord（发票记录）
+
+### 作用
+描述发票服务受理、开具成功/失败、票号回写、电子票文件地址等结果信息。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| invoiceId | Long | 发票记录 ID |
+| applicationNo | String | 对应申请单号 |
+| sysRequestNo | String | `SYS-008` 受理号 / 外部请求号 |
+| invoiceStatus | Enum | `PENDING` / `SUCCESS` / `FAIL` / `INVALID` / `RED_INK` |
+| invoiceCode | String | 发票代码 |
+| invoiceNumber | String | 发票号码 |
+| invoiceDate | DateTime | 开票日期 |
+| fileUrl | String | 电子发票下载地址 |
+| failReason | String | 开票失败原因 |
+| pushStatus | Enum | `NONE` / `PUSHED` / `FAIL` |
+| updatedAt | DateTime | 最近状态更新时间 |
+
+### 状态关系
+- `PENDING` 表示已提交给 `SYS-008` 但尚未确认最终结果。
+- `SUCCESS` 后允许客户侧查询、下载、推送电子发票。
+- `FAIL` 记录失败原因并进入异常核查或人工重试。
+
+### 物理承接
+- 主承接：`biz_invoice`
+- 历史参照：旧 `IV_INVOICE_INFOS`
+
+## 实体三：ChargeInvoiceRelation（账单-发票关联）
+
+### 作用
+承接账单与发票的映射关系，支持单票对应多账单、拆账后分别开票和后续合并开票扩展。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| relationId | Long | 关联记录 ID |
+| chargeId | Long | 账单 ID |
+| invoiceId | Long | 发票 ID |
+| applicationNo | String | 申请单号 |
+| relationType | Enum | `FULL_AMOUNT` / `SPLIT_BILL` / `MERGED_BILL` |
+| invoiceAmount | Decimal | 当前账单对应开票金额 |
+| relationStatus | Enum | `PENDING` / `BOUND` / `FAILED` |
+| snapshotVersion | String | 开票配置/税率快照版本 |
+
+### 关键规则
+- 一期默认 `relationType=FULL_AMOUNT` 或 `SPLIT_BILL`（来自拆账后的账单），不支持对原始单账单直接自由部分金额开票。
+- 发票成功后必须把关系状态更新为 `BOUND`，并可供账单详情查询。
+
+### 物理承接
+- 在线主承接：`biz_invoice` + 历史关系快照
+- 历史参照：旧 `IV_CHARGE_INVOICES`、`IV_CHARGE_INVOICE_MAPPINGS`
+
+## 实体四：InvoiceQueryTask（开票查询补偿任务）
+
+### 作用
+支持异步申请后的轮询查询、超时补偿和人工兜底查询，是“查询兜底”模式的核心对象。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| queryTaskId | Long | 查询任务 ID |
+| applicationNo | String | 申请单号 |
+| sysRequestNo | String | 外部受理号 |
+| lastTryTime | DateTime | 最后一次查询时间 |
+| nextTryTime | DateTime | 下一次查询时间 |
+| tryCount | Integer | 已查询次数 |
+| queryStatus | Enum | `WAITING` / `RUNNING` / `DONE` / `FAILED` |
+| latestResult | String | 最近一次查询结果摘要 |
+| latestError | String | 最近一次查询错误 |
+
+### 关键规则
+- 申请成功后默认生成查询任务。
+- 查询到终态后任务进入 `DONE`。
+- 查询异常不应覆盖已成功开票状态，只记录异常并等待人工或系统补偿。
+
+### 物理承接
+- 主承接：`biz_invoice` 扩展字段或关联查询日志对象
+- 历史参照：旧发票表中的 `last_try_time`、`next_try_time`、`try_count`
+
+## 实体五：InvoiceResultWriteBack（结果回写）
+
+### 作用
+统一描述 `SYS-008` 查询结果或主动回传结果进入营收域后的状态变更、幂等控制和操作留痕。
+
+### 核心字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| writeBackNo | String | 回写流水号 |
+| applicationNo | String | 申请单号 |
+| invoiceStatus | Enum | 发票状态 |
+| writeBackStatus | Enum | `SUCCESS` / `IGNORE_REPEAT` / `FAIL` |
+| invoiceCode | String | 发票代码 |
+| invoiceNumber | String | 发票号码 |
+| fileUrl | String | 下载地址 |
+| rawPayload | String | 原始回写/查询响应 |
+| processedAt | DateTime | 处理时间 |
+| processedBy | String | 系统任务 / 人工处理人 |
+
+### 关键规则
+- 按 `applicationNo + invoiceStatus` 做幂等控制。
+- 已成功开票后收到失败结果，不覆盖成功状态，转入异常核查。
+- 所有回写处理必须记录到操作留痕对象。
+
+### 物理承接
+- 主承接：`biz_invoice` + `biz_operat_log*`
+
+## 关系总览
+
+```text
+InvoiceApplication --> InvoiceRecord
+InvoiceApplication --> ChargeInvoiceRelation
+InvoiceApplication --> InvoiceQueryTask
+InvoiceRecord --> InvoiceResultWriteBack
+ChargeInvoiceRelation --> biz_charge* (N:1)
+InvoiceApplication --> biz_cust_invoice
+InvoiceApplication --> biz_invoice_taxrate
+InvoiceResultWriteBack --> biz_operat_log*
+```
+
+## 状态与边界说明
+
+- 一期默认后台申请、客户侧结果消费，不定义客户侧直接申请状态机。
+- 作废、红冲作为 REV-005 后续能力保留在数据模型中，但 implement 时优先保证正常开票闭环。
+- 旧发票明细、营业账开票关系、配置快照对象在当前阶段仅作为历史参照和追溯来源，不表述为已确认新增在线独立表。

specs/002-rev005-invoice-flow/plan.md

@@ -0,0 +1,185 @@
+# Implementation Plan: REV-005 发票业务流实现
+
+**Branch**: `002-rev005-invoice-flow` | **Date**: 2026-03-16 | **Spec**: `/specs/002-rev005-invoice-flow/spec.md`
+**Input**: Feature specification from `/specs/002-rev005-invoice-flow/spec.md`
+
+## Summary
+
+本轮围绕 `REV-005` 发票业务流补齐从已收费账单到电子发票结果落账的业务闭环，形成可直接指导 backend 实施与正式文档修订的 planning 产物。计划目标是在既有 `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate` 基础上，明确发票申请、后台批量/单笔开票、`SYS-008` 异步协同与查询兜底、结果回写、账单-发票关联、客户侧查询下载推送的实现口径。
+
+本次计划输出以 spec 澄清结果为准：一期采用“后台开票 + 客户侧查询下载”模式；`SYS-008` 对接采用“异步申请 + 轮询查询兜底”；不支持原始单账单直接任意部分金额开票，如需多张发票沿用老系统拆账/分账后的账单分别开票；正式主文档需回写 `12_REV_Detailed.md`、`03_Interface_Design.md` 与 `01_Database_Design.md`，backend 侧则在现有 `InvoiceController.java`、`InvoiceServiceImpl.java` 基础上扩展业务接口与服务能力。
+
+## Technical Context
+
+**Primary Work Product**: REV-005 planning 设计产物，包括实施计划、研究结论、数据模型、接口合同与最小校验说明。
+**Source of Truth Documents**:
+- `specs/002-rev005-invoice-flow/spec.md`
+- `.specify/memory/constitution.md`
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+**Reference Sources**:
+- `docs/guides/BACKEND_CURRENT_STATUS.md`
+- `docs/guides/BACKEND_TABLE_MAPPING.md`
+- `docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md`
+- `docs/design/04_Appendix/Archive/02_Manuals/福建水投微网厅操作手册.md`
+- `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`
+**Validation Commands**:
+- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`
+- `make check-links`
+- `make validate-mermaid`
+**Target Scope**:
+- `REV-005` 正式详细设计补充
+- `IF-REV-008`（后台发票申请/开具）与 `IF-CS-004`（客户侧查询下载）口径收敛
+- 新增 `IF-REV-009` 发票结果查询/补偿查询口径
+- `biz_invoice*`、`biz_cust_invoice`、账单-发票关联与历史关系快照的承接口径
+- backend 发票业务 Service/Controller 扩展边界
+**Project Type**: 文档治理仓库（同时为 backend 实施提供 planning 输入）
+**Constraints**:
+- 不新增平行正式主稿
+- 不发明超出主文档与老系统交集的新业务规则
+- Archive 仅作核对与追溯来源，不替代正式结论
+- 一期默认后台开票，客户侧不直接申请开票
+- 一期不支持原始单账单直接任意部分金额开票
+- `SYS-008` 结果获取采用查询兜底，不假设回调可用
+- 本轮 implement 先完成正常开票闭环收口，再在二期补齐作废/红冲的正式文档、backend 入口、状态流转与结果落账
+- 仓库内引用保持相对路径口径
+**Scale/Scope**: 跨文档 + backend 实施 planning，覆盖 1 个 feature spec、1 个 implementation plan、1 份 research、1 份 data-model、2 份 contracts、1 份 quickstart，并为后续 tasks/implement 提供输入。
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：本轮 planning 产物落在 `specs/002-rev005-invoice-flow/`，正式口径将回写既有 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`，不新增平行正式稿。
+- [x] **范围基线已确认**：`REV-005` 在 `12_REV_Detailed.md`、`03_Interface_Design.md`、旧系统操作手册、数据字典中均有明确发票管理/电子发票交集口径，可直接推进；原始单账单任意部分开票未作为一期主能力纳入。
+- [x] **Archive 使用方式合规**：Archive 仅作为老系统能力、字段与菜单口径来源，正式结论仍以当前主文档与 spec 澄清结果为准。
+- [x] **一致性影响已列出**：已识别 `IF-REV-008` / `IF-CS-004` / 发票查询补偿接口编号、`biz_invoice*` 承接口径、旧“回调”改为“查询兜底”、后台/客户侧入口边界等一致性项。
+- [x] **校验与台账动作已规划**：已明确正式文档最小校验命令；plan 阶段仅生成 planning 产物，不强制更新 `01_Project_Progress.md` / `03_Task_Checklist.md`，待正式主文档修订或任务闭环后再回写。
+
+### Post-Design Re-check
+
+- [x] 设计产物保持“主文档修订 + backend 实施 planning”定位，没有绕开单一真源另写平行正式稿。
+- [x] `data-model.md` 采用逻辑实体 + 现有物理承接 + 历史关系快照三层表达，没有把旧系统全部细表表述为当前已落地在线表。
+- [x] `contracts/` 中接口合同统一回扣后台开票、客户侧查询下载、`SYS-008` 查询兜底与幂等回写口径。
+- [x] `quickstart.md` 仅定义评审入口、最小校验与 backend 验证建议，不引入超范围部署/发布动作。
+- [x] 结果获取方式统一为“异步申请 + 查询兜底”，不再保留与航信接口事实冲突的“直接回调”口径。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-rev005-invoice-flow/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   ├── if-rev-008-invoice-application.md
+│   └── if-rev-009-invoice-query.md
+└── tasks.md
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/
+│   ├── 01_Project_Progress.md
+│   ├── 02_Delivery_Standards.md
+│   └── 03_Task_Checklist.md
+├── 02_Detailed_Design/
+│   └── 12_REV_Detailed.md
+├── 03_Technical_Design/
+│   ├── 01_Database_Design.md
+│   └── 03_Interface_Design.md
+└── 04_Appendix/Archive/
+
+backend/sw-business/sw-business-server/
+├── src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java
+└── src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java
+```
+
+**Structure Decision**:
+- `specs/002-rev005-invoice-flow/spec.md`：作为 REV-005 范围、澄清结果与验收边界总源。
+- `specs/002-rev005-invoice-flow/plan.md`：承接当前计划阶段的实施组织、门禁与结构决策。
+- `specs/002-rev005-invoice-flow/research.md`：沉淀异步查询兜底、后台/客户侧边界、老系统对齐与物理承接口径等关键选择。
+- `specs/002-rev005-invoice-flow/data-model.md`：固化发票申请、发票记录、账单发票关联、查询补偿与结果回写对象。
+- `specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md`：统一后台发票申请/批量开票合同。
+- `specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md`：统一查询兜底、结果查询与客户侧查询下载合同。
+- `specs/002-rev005-invoice-flow/quickstart.md`：提供文档评审、最小校验与 backend 验证入口。
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`：后续正式补充 REV-005 业务规则、状态流转和旧系统对齐说明。
+- `docs/design/03_Technical_Design/03_Interface_Design.md`：后续正式补充 `IF-REV-008`、`IF-REV-009` 与客户侧查询下载口径。
+- `docs/design/03_Technical_Design/01_Database_Design.md`：后续正式补充 `biz_invoice*`、账单-发票关联快照与历史关系承接口径。
+- `InvoiceController.java` / `InvoiceServiceImpl.java`：后续实现阶段扩展后台申请、查询、回写与批量开票能力，不再仅限配置 CRUD。
+
+## Phase 0 Research Summary
+
+1. 一期采用“后台开票 + 客户侧查询下载推送”的入口策略，后台营业收费员/财务人员负责申请和开具，客户侧不直接发起开票申请。
+2. `SYS-008` 对接采用“异步申请 + 轮询查询兜底”模式，适配航信等不提供稳定回调的开票服务现状。
+3. 一期不支持原始单账单直接任意部分金额开票；如需多张发票，沿用老系统拆账/分账后分别开票的口径，并保留批量开票能力。
+4. 当前 backend 已有 `InvoiceController.java`、`InvoiceServiceImpl.java`，但实际只覆盖开票配置/模板 CRUD，未实现发票申请、查询、回写、账单关联闭环。
+5. 在线主模型以 `biz_invoice`、`biz_invoice_taxrate`、`biz_cust_invoice` 为主承接，旧“营业账开票表/发票明细表/开票配置快照”按历史关系快照或辅助映射处理，不机械复制旧表族。
+6. 正式文档应同时对齐当前主文档、旧系统操作手册与数据字典，避免只保留“申请 + 回写”而遗漏老系统已有的查询、下载、批量开票与结果导出语义。
+
+## Phase 1 Design Outputs
+
+### Data Model
+- `data-model.md` 已定义：
+  - `InvoiceApplication`
+  - `InvoiceRecord`
+  - `ChargeInvoiceRelation`
+  - `InvoiceQueryTask`
+  - `InvoiceResultWriteBack`
+- 其中明确区分逻辑实体、现有在线主表承接与历史关系快照，兼容后续合并开票/拆账开票扩展。
+
+### Contracts
+- `contracts/if-rev-008-invoice-application.md`
+  - 固化后台发票申请/批量开票的请求字段、响应字段、校验规则与幂等口径。
+- `contracts/if-rev-009-invoice-query.md`
+  - 固化查询兜底、结果补偿查询、客户侧查询下载的请求/响应与状态表达。
+
+### Quickstart
+- `quickstart.md` 已给出：
+  - 范围校验
+  - 老系统对齐校验
+  - 文档最小校验命令
+  - backend 实施前的现状核对点
+  - 后续 tasks/implement 的最小验收入口
+
+### Agent Context
+- 仓库内未找到 `.specify/scripts/**/update-agent-context.sh`；本轮不执行自动 agent context 更新脚本。
+- 后续若补齐该脚本，可按仓库统一约定再执行一次上下文同步。
+
+## Implementation Strategy for Next Phase
+
+下一阶段 `/speckit.tasks` 应按以下顺序拆解：
+
+1. **正式文档收敛任务**
+   - 更新 `12_REV_Detailed.md` 中 REV-005 场景、状态机、入口边界、老系统对齐说明
+   - 更新 `03_Interface_Design.md` 中 `IF-REV-008`、`IF-REV-009` 与客户侧查询下载口径
+   - 更新 `01_Database_Design.md` 中 `biz_invoice*`、账单-发票关联快照和查询补偿字段说明
+2. **backend 基础扩展任务**
+   - 为现有 `InvoiceController.java` / `InvoiceServiceImpl.java` 增加后台申请、查询、结果写回、批量开票能力
+   - 增加与账单、客户开票信息、税率配置的校验联动
+3. **`SYS-008` 协同与补偿任务**
+   - 发票申请协同调用
+   - 查询兜底任务与幂等回写
+   - 失败原因与异常核查留痕
+4. **客户侧结果消费任务**
+   - 查询已开发票状态
+   - 下载/推送电子发票
+   - 与后台开票状态保持一致
+5. **校验与闭环任务**
+   - 文档 `make validate-file` / `make check-links` / `make validate-mermaid`
+   - backend 核心流程验证
+   - 必要时回写 `01_Project_Progress.md` 与 `03_Task_Checklist.md`
+
+## Complexity Tracking
+
+本计划未发生 Constitution 违规项，无需豁免说明。

specs/002-rev005-invoice-flow/quickstart.md

@@ -0,0 +1,111 @@
+# Quickstart: REV-005 发票业务流计划评审与最小校验
+
+## 1. 评审入口
+
+本轮目标是：
+- 明确 REV-005 一期发票业务流范围与老系统对齐口径
+- 形成 backend 可实施的接口、数据模型与查询兜底方案
+- 为后续 `/speckit.tasks` 与 `/speckit.implement` 提供直接输入
+
+本轮验收重点检查：
+- 范围与老系统操作手册是否一致
+- 发票申请 / 查询兜底 / 结果回写 / 客户侧消费口径是否闭环
+- planning 产物是否可直接拆解为 backend 开发任务
+
+## 2. 评审步骤
+
+### 步骤一：范围校验
+确认一期只覆盖以下核心能力：
+- 后台发票申请
+- 后台单笔 / 批量开票
+- `SYS-008` 异步协同与查询兜底
+- 发票结果回写与账单关联
+- 客户侧查看 / 下载 / 推送已开票电子发票
+
+同时确认以下内容未被带入：
+- 客户侧直接申请开票
+- 原始单账单任意部分金额开票
+- 复杂拆分合并开票策略一次性做深
+- 与税务局直接对接的细节实现
+
+### 步骤二：老系统对齐校验
+对照以下来源：
+- `营收系统_用户操作手册.md`
+- `福建水投微网厅操作手册.md`
+- `营收数据字典.md`
+
+确认 planning 已吸收以下能力语义：
+- 发票查询
+- 发票开具
+- 批量开票
+- 电子发票查看/下载/推送
+- 拆账/分账后分别开票
+
+### 步骤三：单一真源校验
+对照以下正式口径：
+- `spec.md`
+- `12_REV_Detailed.md`
+- `03_Interface_Design.md`
+- `01_Database_Design.md`
+- `.specify/memory/constitution.md`
+
+确认 planning 没有让 Archive 直接替代正式设计结论。
+
+### 步骤四：查询兜底校验
+确认以下口径已统一：
+- 提交申请后先生成申请单号 / 外部受理号
+- 通过查询接口轮询获取开票结果
+- 幂等回写以申请单号和状态为主键
+- 已成功状态不得被后续失败结果覆盖
+
+### 步骤五：backend 现状核对
+确认当前 backend 发票模块仍主要是配置 CRUD：
+- `InvoiceController.java`
+- `InvoiceServiceImpl.java`
+
+并确认后续 implement 需要新增：
+- 申请接口
+- 查询接口
+- 结果回写/补偿查询逻辑
+- 账单/客户开票信息/税率校验联动
+
+### 步骤六：正式文档修订闭环校验
+后续进入正式主文档修订时，统一按以下顺序执行：
+1. 先更新 `12_REV_Detailed.md` 的业务规则与状态机。
+2. 再更新 `03_Interface_Design.md` 的接口合同与时序。
+3. 再更新 `01_Database_Design.md` 的承接口径与关系快照说明。
+4. 每修改 1 份目标文档，执行对应 `make validate-file FILE=<目标文件>`。
+5. 涉及跨文档引用变更时执行 `make check-links`。
+6. 涉及图表或时序图时执行 `make validate-mermaid`。
+
+## 3. 最小校验命令
+
+```bash
+make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md
+make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md
+make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md
+make check-links
+make validate-mermaid
+```
+
+说明：
+- 当前 plan 阶段以正式文档门禁为主，不强制执行 backend 构建或测试。
+- backend 相关验证将在 `/speckit.implement` 阶段展开。
+
+## 4. backend 实施前建议核对点
+
+在进入 implement 之前，至少补充核对以下对象：
+- 账单对象：`biz_charge*`
+- 发票主对象：`biz_invoice`
+- 客户开票信息：`biz_cust_invoice`
+- 税率配置：`biz_invoice_taxrate`
+- 操作留痕：`biz_operat_log*`
+- 现有发票 Controller / Service / Mapper / DO / ReqVO / RespVO
+
+## 5. 通过标准
+
+满足以下条件即可进入下一批 tasks 拆解：
+- 一期范围、老系统对齐边界、查询兜底策略已明确
+- 接口合同和数据模型能直接支撑 backend 任务拆解
+- 最小校验动作已明确并可执行
+- 后续正式文档修订与 backend 实施边界已分清

specs/002-rev005-invoice-flow/research.md

@@ -0,0 +1,50 @@
+# Phase 0 Research: REV-005 发票业务流实现
+
+## Decision 1: 一期入口采用“后台开票 + 客户侧查询下载推送”
+- **Decision**: 一期由后台营业收费员/财务人员发起发票申请与开具；客户侧仅支持查看、下载、推送已开具的电子发票，不直接发起开票申请。
+- **Rationale**: `营收系统_用户操作手册.md` 明确存在后台【发票管理】-【发票开具】与【发票查询】入口，同时微网厅操作手册更偏向电子发票查看/推送能力；该分层最贴近老系统且风险最低。
+- **Alternatives considered**:
+  - 后台与客户侧都直接发起开票申请：会显著扩大一期鉴权、重复申请与渠道联动范围。
+  - 仅后台开票、客户侧不提供结果消费：与老系统电子发票查看/下载口径不符。
+
+## Decision 2: `SYS-008` 采用“异步申请 + 查询兜底”协同模式
+- **Decision**: 提交开票申请后先返回受理号/申请单号，系统通过定时或主动查询接口获取最终开票结果，不假设发票服务一定通过回调返回。
+- **Rationale**: 航信类发票平台常见能力是异步受理 + 查询结果；spec clarifications 已明确该模式，且旧数据字典中也存在 `last_try_time`、`next_try_time`、`try_count` 等查询补偿字段痕迹。
+- **Alternatives considered**:
+  - 仅依赖回调：与当前外部接口现实不符，容易导致状态悬挂。
+  - 纯同步开票：不适配电子发票平台与批量开票场景。
+
+## Decision 3: 一期不支持原始单账单直接任意部分开票
+- **Decision**: 若需要多张发票，沿用老系统拆账/分账后的账单分别开票；后台可保留单笔或批量选择已收费账单发起开票，但不开放对原始单账单直接输入部分金额开票。
+- **Rationale**: 老系统操作手册说明“多张发票”更多依赖分账/拆账结果，数据字典虽然存在映射表和金额字段，但未把“自由部分开票”表达为一期主流程能力；该约束能降低状态和金额校验复杂度。
+- **Alternatives considered**:
+  - 直接支持任意部分金额开票：需额外引入余额、累计开票金额、明细拆分与冲突控制。
+  - 完全不考虑多票场景：会偏离老系统业务口径。
+
+## Decision 4: 在线主模型复用 `biz_invoice` / `biz_cust_invoice` / `biz_invoice_taxrate`
+- **Decision**: 当前在线主模型以 `biz_invoice`、`biz_cust_invoice`、`biz_invoice_taxrate` 为主承接发票申请、客户开票资料与税率配置；旧“营业账开票表”“发票明细表”“开票配置表快照”等细粒度对象按历史只读关系快照或辅助映射处理。
+- **Rationale**: `01_Database_Design.md` 与 `BACKEND_TABLE_MAPPING.md` 已明确当前在线主承接对象，且 backend 现状确实已有发票主表和配置服务；机械复制旧表族会与当前主文档冲突。
+- **Alternatives considered**:
+  - 全量恢复旧 IV_* 表族：超出当前主文档与现状。
+  - 只保留 `biz_invoice` 不表达关联快照：无法满足老系统查询与审计定位需求。
+
+## Decision 5: backend 现状仅覆盖开票配置 CRUD，REV-005 需扩展业务闭环
+- **Decision**: 后续 implement 阶段在现有 `InvoiceController.java`、`InvoiceServiceImpl.java` 基础上扩展业务接口与服务，不另起平行模块。
+- **Rationale**: 当前 Controller/Service 仅包含 `/business/invoice/create|update|delete|get|page|list` 等配置 CRUD 与模板枚举查询，尚未实现账单校验、申请单生成、SYS-008 协同、查询补偿与结果回写。
+- **Alternatives considered**:
+  - 直接新增独立发票业务模块：会造成配置与业务双轨并行。
+  - 在当前基础上只补接口文档不改后端：无法支撑后续 implement。
+
+## Decision 6: 正式文档需同时对齐当前主文档与老系统操作手册
+- **Decision**: `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 后续修订时，除对齐主文档既有口径外，还需显式吸收老系统操作手册中的“发票查询、下载、打印、批量开票、电子发票查看/推送”等稳定能力。
+- **Rationale**: 仅依据当前主文档容易把 REV-005 收窄成“申请 + 回写”，而老系统实际交付口径已经包含后台开票、客户侧查看下载与批量处理。
+- **Alternatives considered**:
+  - 只看主文档：会遗漏老系统既有稳定业务能力。
+  - 只看操作手册：会偏离当前主文档和在线模型口径。
+
+## Decision 7: plan 阶段校验以文档门禁为主，backend 只做现状核对
+- **Decision**: 当前 plan 阶段的最小校验仍以 `make validate-file`、`make check-links`、`make validate-mermaid` 为主，backend 只需核实现有 Controller/Service 的能力边界，不引入构建或测试作为当前阶段门禁。
+- **Rationale**: 本阶段交付物仍是 planning 设计产物；代码实现验证应在 `/speckit.implement` 阶段展开。
+- **Alternatives considered**:
+  - 现在就引入 backend 构建/测试：会打断 planning 输出节奏。
+  - 完全忽略 backend 现状：会导致后续任务拆解失真。

specs/002-rev005-invoice-flow/spec.md

@@ -0,0 +1,202 @@
+# Feature Specification: REV-005 发票业务流实现
+
+**Feature Branch**: `002-rev005-invoice-flow`
+**Created**: 2026-03-16
+**Status**: Verification Pending
+**Input**: 实现 REV-005 发票业务流核心功能：发票申请、开票校验、调用 SYS-008 发票服务、接收开票结果回写、更新发票与账单关联状态。
+
+---
+
+## Document Scope & Sources
+
+- **Target documents**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`（REV-005 章节补充）
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`（IF-REV-008 发票申请接口、IF-REV-009 发票查询接口定义）
+  - Backend: `backend/sw-business/sw-business-server` 新增 Service/Controller
+
+- **Primary source of truth**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 定义
+  - `docs/guides/BACKEND_CURRENT_STATUS.md`
+  - `docs/guides/BACKEND_TABLE_MAPPING.md`
+
+- **Reference sources**:
+  - Archive: `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+  - Existing: `InvoiceController.java`, `InvoiceServiceImpl.java`
+
+- **Scope decision**: 在已有基础数据层（开票配置、客户开票信息、税率配置）之上，补齐发票申请、开具、结果回写的完整业务流程。
+
+---
+
+## User Scenarios & Testing
+
+### User Story 1 - 发票申请与校验 (Priority: P1)
+
+营业收费员或财务人员通过后台系统提交发票申请，系统校验账单状态、开票信息完整性和开票限额，生成发票申请记录。客户侧一期不直接发起开票申请，仅支持查询、下载、推送已开具的电子发票。
+
+**Why this priority**: 发票申请是业务流程入口，必须优先实现。
+
+**Independent Test**: 验证发票申请接口可接收申请，校验规则生效，申请记录正确落库。
+
+**Acceptance Scenarios**:
+
+1. **Given** 账单已缴费且未开票，客户开票信息完整，**When** 提交发票申请，**Then** 生成发票申请记录，返回申请单号
+2. **Given** 账单未缴费，**When** 提交发票申请，**Then** 拒绝申请，提示"账单未缴费不可开票"
+3. **Given** 账单已开票，**When** 提交发票申请，**Then** 拒绝申请，提示"账单已开票"
+4. **Given** 开票金额超过限额，**When** 提交发票申请，**Then** 拒绝申请，提示"超过开票限额"
+5. **Given** 同一原始账单被要求直接拆分为多次部分开票，**When** 提交发票申请，**Then** 拒绝直接部分开票，并提示需先按老系统口径完成拆账/分账后再分别开票
+
+---
+
+### User Story 2 - 调用发票服务开票 (Priority: P1)
+
+系统根据申请记录调用 SYS-008 发票服务完成开票，采用“异步申请 + 查询兜底”模式记录受理结果并主动查询最终状态。
+
+**Why this priority**: 核心开票能力，必须实现与外部系统的对接。
+
+**Independent Test**: 验证系统可正确组装开票参数，调用外部服务，处理返回结果。
+
+**Acceptance Scenarios**:
+
+1. **Given** 发票申请已校验通过，**When** 调用 SYS-008 开票接口，**Then** 正确传递账单、客户、税率信息
+2. **Given** 外部服务返回开票成功，**When** 系统通过查询获取结果并回写状态，**Then** 更新发票状态为"已开票"，记录发票代码号码
+3. **Given** 外部服务返回开票失败，**When** 系统通过查询获取结果并回写状态，**Then** 更新发票状态为"开票失败"，记录失败原因
+4. **Given** 外部服务超时，**When** 发起查询，**Then** 可查询开票结果状态
+
+---
+
+### User Story 3 - 发票结果回写与关联 (Priority: P2)
+
+开票成功后更新账单发票状态，建立发票与账单关联，支持电子发票推送。
+
+**Why this priority**: 保证账单与发票数据一致性，支持后续查询和下载。
+
+**Independent Test**: 验证开票结果正确回写账单状态，关联关系可查。
+
+**Acceptance Scenarios**:
+
+1. **Given** 开票成功，**When** 回写结果，**Then** 账单发票状态更新，建立 invoice-charge 关联
+2. **Given** 电子发票生成，**When** 客户请求下载，**Then** 返回电子发票文件或下载链接
+3. **Given** 发票已关联账单，**When** 查询账单详情，**Then** 显示关联的发票信息
+
+---
+
+### User Story 4 - 发票作废与红冲 (Priority: P3)
+
+对已成功开具的发票提供后台作废与红冲入口，由 `SYS-008` 承接税控侧处理，`SYS-002` 负责发起申请、校验状态、查询补偿、结果回写与账单关联状态同步；客户侧仍仅消费有效电子发票结果，不直接发起作废或红冲。
+
+**Why this priority**: 作废与红冲属于已开票后的后处理能力，依赖正常开票闭环，但必须在本轮二期中形成正式设计与 backend 实现入口。
+
+**Independent Test**: 验证后台可对满足条件的成功发票发起作废或红冲；`SYS-008` 返回结果后，发票状态正确更新为 `INVALID` 或 `RED_INK`，并保留原票关联、失败原因与操作日志。
+
+**Acceptance Scenarios**:
+
+1. **Given** 发票状态为 `SUCCESS` 且未作废、未红冲，**When** 后台发起作废申请，**Then** 系统校验通过并调用 `SYS-008`，成功后将发票状态更新为 `INVALID`
+2. **Given** 发票状态为 `SUCCESS` 且业务要求通过红字发票冲销，**When** 后台发起红冲申请，**Then** 系统校验通过并调用 `SYS-008`，成功后将发票状态更新为 `RED_INK`
+3. **Given** 发票已处于 `INVALID` 或 `RED_INK`，**When** 再次发起作废或红冲，**Then** 系统拒绝重复处理并返回明确原因
+4. **Given** `SYS-008` 未立即返回终态，**When** 系统执行主动查询或补偿查询，**Then** 保持处理中上下文并在取得终态后统一落账
+
+---
+
+### Edge Cases
+
+- 外部发票服务不可用时的降级处理
+- 重复提交同一账单的发票申请（幂等控制）
+- 开票过程中账单状态发生变化
+- 拆账/分账后的多账单分别开票与原始单账单直接部分开票的边界判定
+
+---
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: 系统 MUST 提供后台发票申请接口，接收账单ID、开票类型（普票/专票）等参数，并支持单笔或批量选择已收费账单发起开票
+- **FR-002**: 系统 MUST 校验账单状态（已缴费、未开票）
+- **FR-003**: 系统 MUST 校验客户开票信息完整性
+- **FR-004**: 系统 MUST 校验开票限额
+- **FR-005**: 系统 MUST 生成发票申请记录，包含申请单号、状态、时间戳
+- **FR-006**: 系统 MUST 调用 SYS-008 发票服务完成开票
+- **FR-007**: 系统 MUST 支持通过定时查询获取异步开票结果（轮询 SYS-008 查询接口）
+- **FR-008**: 系统 MUST 更新发票状态（申请中/已开票/开票失败）
+- **FR-009**: 系统 MUST 建立发票与账单的关联关系，并保留兼容老系统拆账/分账后分别开票及后续合并开票扩展的映射能力
+- **FR-010**: 系统 MUST 支持客户侧查询、下载、推送已开具的电子发票，但一期不开放客户侧直接申请开票
+- **FR-011**: 系统 MUST 记录关键操作日志（申请、查询、开票、结果回写、客户侧查询/下载/推送、作废、红冲），并保留触发来源、状态前后值与失败原因
+- **FR-012**: 系统 MUST 提供后台发票作废入口，仅允许对已开票成功且未作废、未红冲的发票发起作废
+- **FR-013**: 系统 MUST 提供后台发票红冲入口，仅允许对已开票成功且未红冲的发票发起红字冲销，并保留原票关联信息
+- **FR-014**: 系统 MUST 通过查询补偿或结果回写统一落账作废/红冲终态，并同步更新发票状态、失败原因和账单发票关联状态
+
+### Key Entities
+
+- **发票申请单** (InvoiceApplication): 申请单号、账单ID、客户ID、申请金额、开票类型、状态
+- **发票记录** (InvoiceRecord): 发票ID、申请单号、发票代码、发票号码、开票日期、金额、状态
+- **账单发票关联** (ChargeInvoiceRelation): 账单ID、发票ID、关联类型（全额/拆账后分别开票/后续合并扩展）
+- **开票查询记录** (InvoiceQueryLog): 查询ID、申请单号、查询时间、查询结果、处理状态
+
+---
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: 发票申请接口响应时间 < 500ms（不包含外部服务调用）
+- **SC-002**: 发票申请校验通过率 > 95%（正常业务场景）
+- **SC-003**: 开票结果回写成功率 > 99%
+- **SC-004**: 电子发票下载成功率 > 99%
+- **SC-005**: 操作日志完整率 100%（所有关键操作均有日志）
+
+### Business Outcomes
+
+- 营业收费员可通过系统完成发票申请到开票的全流程
+- 客户可通过渠道查询和下载电子发票
+- 财务人员可追溯发票开具全过程
+
+---
+
+## Dependencies & Assumptions
+
+### Dependencies
+
+- SYS-008 发票服务接口已定义（IF-REV-008）
+- 基础数据层已实现（biz_invoice, biz_cust_invoice, biz_invoice_taxrate）
+- 账单系统（REV-003）已实现
+
+### Assumptions
+
+- SYS-008 提供标准 REST 接口供调用
+- 电子发票文件由 SYS-008 生成并提供下载链接
+- 开票限额在配置中预定义
+
+### Scope Exclusions
+
+- 不实现发票的物理打印功能
+- 不实现与税务局的直接对接（由 SYS-008 承接）
+- 不实现复杂的发票拆分合并逻辑（MVP 版本）
+
+---
+
+## Risks & Mitigation
+
+| 风险 | 影响 | 缓解措施 |
+|-----|-----|---------|
+| SYS-008 接口未就绪 | 无法联调 | 先实现 Mock 接口，定义好契约 |
+| 发票状态同步异常 | 数据不一致 | 实现补偿机制，支持对账查询 |
+| 并发开票冲突 | 重复开票 | 幂等控制，唯一申请单号 |
+
+---
+
+## Clarifications
+
+### Session 2026-03-16
+
+- **Q1**: SYS-008 发票服务结果获取方式 → **A**: 采用"异步+查询兜底"模式。提交开票申请后返回受理号，系统通过定时轮询查询结果接口获取开票状态（航信发票接口不支持回调，需主动查询）。
+- **Q2**: 一期是否支持一张原始账单直接分多次部分开票 → **A**: 不支持对原始单账单直接任意部分金额开票；如需多张发票，沿用老系统口径，通过拆账/分账后的账单分别开票，并保留批量开票能力。
+- **Q3**: 一期开放给哪些使用入口 → **A**: 采用“后台开票 + 客户侧查询下载”模式。后台营业收费员/财务人员负责申请和开具，客户侧仅支持查看、下载、推送已开票结果，不直接发起开票申请。
+
+---
+
+## Next Steps
+
+1. 在可用测试或联调环境中补充 SC-001 的响应时延采样，记录样本量、平均值、P95 与“排除外部调用”的统计口径。
+2. 为 SC-002 ~ SC-004 准备样本集与统计表，将申请通过率、回写成功率、查询/下载/推送成功率沉淀到 `specs/002-rev005-invoice-flow/verification.md`。
+3. 抽取 SC-005 运行态日志样本，核对操作人、客户、状态与日志内容是否与实现态矩阵一致。
+4. 继续跟踪 `biz_invoice` 物理 DDL / migration 来源，并在提测前明确联调、落库与批量后处理风险。

specs/002-rev005-invoice-flow/tasks.md

@@ -0,0 +1,221 @@
+# Tasks: REV-005 发票业务流实现
+
+**Input**: Design documents from `/specs/002-rev005-invoice-flow/`
+**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/if-rev-008-invoice-application.md`, `contracts/if-rev-009-invoice-query.md`, `quickstart.md`
+
+**Validation**: 正式文档修改必须执行对应 `make validate-file`；涉及跨文档引用执行 `make check-links`；涉及 Mermaid/时序图执行 `make validate-mermaid`；backend 实现阶段需补充最小编译或等价流程验证，并将结果沉淀到 `specs/002-rev005-invoice-flow/verification.md`。
+
+**Current Calibration**: 当前分支不满足 `.specify/scripts/bash/check-prerequisites.sh` 的 feature-branch 命名要求，因此本文件基于现有 `spec.md`、`plan.md`、`research.md`、`data-model.md`、`contracts/`、`quickstart.md` 手工重建。`[x]` 表示仓库内已有实现或证据，`[ ]` 表示仍待补齐的收口任务。
+
+**Organization**: 任务按用户故事分组，确保每个故事都可以独立实现、独立验证、独立评审；Final Phase 仅保留跨故事收口事项。
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: 可并行执行（不同文件、无未完成依赖）
+- **[Story]**: 所属用户故事（`[US1]`、`[US2]`、`[US3]`、`[US4]`）
+- 每条任务都包含明确文件路径，便于直接执行
+
+## Path Conventions
+
+- 正式设计文档：`docs/design/02_Detailed_Design/`、`docs/design/03_Technical_Design/`
+- 管理台账：`docs/design/00_Management/`
+- planning 产物：`specs/002-rev005-invoice-flow/`
+- backend 发票模块：`backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/`
+
+---
+
+## Phase 1: Scope & Source Confirmation (Shared Foundation)
+
+**Purpose**: 确认本轮单一真源、影响范围与 backend 触点，避免后续任务偏离已收敛口径。
+
+- [x] T001 确认 `specs/002-rev005-invoice-flow/spec.md`、`plan.md`、`research.md`、`data-model.md`、`contracts/if-rev-008-invoice-application.md`、`contracts/if-rev-009-invoice-query.md`、`quickstart.md` 作为 REV-005 任务拆解直接输入
+- [x] T002 确认 `docs/design/00_Management/01_Project_Progress.md`、`docs/design/00_Management/02_Delivery_Standards.md`、`docs/design/00_Management/03_Task_Checklist.md` 与 `.specify/memory/constitution.md` 作为治理约束输入
+- [x] T003 [P] 确认正式目标文档 `docs/design/02_Detailed_Design/12_REV_Detailed.md`、`docs/design/03_Technical_Design/03_Interface_Design.md`、`docs/design/03_Technical_Design/01_Database_Design.md` 的 REV-005 章节为主落点
+- [x] T004 [P] 确认 backend 主触点 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`、`service/invoice/InvoiceService.java`、`service/invoice/InvoiceServiceImpl.java`、`dal/dataobject/invoice/InvoiceDO.java`、`dal/mysql/invoice/InvoiceMapper.java`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: 先统一跨故事共享的状态、接口、数据承接和校验输出口径。
+
+- [x] T005 对齐 `specs/002-rev005-invoice-flow/spec.md`、`plan.md`、`verification.md` 与 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中的共享状态口径 `SUBMITTED/PENDING/SUCCESS/FAIL/INVALID/RED_INK`
+- [x] T006 对齐 `specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md`、`contracts/if-rev-009-invoice-query.md` 与 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-008`、`IF-REV-009`、客户侧消费边界的接口职责
+- [x] T007 对齐 `specs/002-rev005-invoice-flow/data-model.md`、`docs/design/03_Technical_Design/01_Database_Design.md`、`backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`、`dal/mysql/invoice/InvoiceMapper.java` 的共享数据承接口径
+- [x] T008 对齐 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`、`service/invoice/InvoiceService.java`、`service/invoice/InvoiceServiceImpl.java` 的共享路由和服务骨架
+- [x] T009 [P] 对齐 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java`、`InvoiceApplyRespVO.java`、`InvoiceQueryReqVO.java`、`InvoiceQueryRespVO.java`、`InvoiceWriteBackReqVO.java`、`InvoiceCustomerQueryReqVO.java`、`InvoicePushReqVO.java` 的公共请求/响应承接
+- [x] T010 [P] 核对 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/custinvoice/CustInvoiceController.java`、`service/custinvoice/CustInvoiceServiceImpl.java`、`controller/admin/invoicetaxrate/InvoiceTaxrateController.java`、`service/invoicetaxrate/InvoiceTaxrateServiceImpl.java` 的客户开票信息与税率依赖
+- [x] T011 对齐 `specs/002-rev005-invoice-flow/verification.md`、`docs/design/00_Management/01_Project_Progress.md`、`docs/design/00_Management/03_Task_Checklist.md` 的校验沉淀和台账回写出口
+
+---
+
+## Phase 3: User Story 1 - 发票申请与校验 (Priority: P1) 🎯 MVP
+
+**Goal**: 实现后台单笔/批量发票申请入口，完成账单状态、客户开票信息、税率和限额校验，并生成发票申请记录。
+
+**Independent Test**: 后台提交已收费未开票账单时能生成申请单号；未缴费、已开票、原始单账单直接部分开票等场景被正确拦截；正式文档与接口合同保持一致。
+
+### Implementation for User Story 1
+
+- [x] T012 [US1] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的后台申请入口、校验规则、批量开票和“禁止原始单账单直接任意部分开票”说明
+- [x] T013 [US1] 更新 `specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md` 中后台申请的请求字段、响应字段、幂等口径和失败提示
+- [x] T014 [US1] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-008` 的后台申请/批量开票接口定义
+- [x] T015 [US1] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台发票申请入口
+- [x] T016 [US1] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java` 与 `service/invoice/InvoiceServiceImpl.java` 实现申请单号生成、账单/客户/税率校验和申请记录落库
+- [x] T017 [P] [US1] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java` 与 `InvoiceApplyRespVO.java` 承接 `chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`taxNo`、`email`、`mobile`、`sourceChannel`、`remark`
+- [x] T018 [P] [US1] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 与 `dal/mysql/invoice/InvoiceMapper.java` 承接 `applicationNo`、申请状态、受理号等字段映射
+- [x] T019 [US1] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 与 `docs/design/03_Technical_Design/03_Interface_Design.md` 的 `make validate-file` 校验结果，固化申请链路文档证据
+- [x] T020 [US1] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `backend/sw-business/sw-business-server/pom.xml` 范围内的最小编译结果，固化申请链路代码证据
+- [x] T021 [US1] 更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md` 同步 US1 收口结果
+- [ ] T022 [US1] 在 `specs/002-rev005-invoice-flow/verification.md` 补充“重复申请”“开票过程中账单状态变化”“原始单账单直接部分开票被拒绝”的样本记录与结论
+
+**Checkpoint**: 后台申请与校验链路可独立评审，`IF-REV-008` 与 REV-005 详细设计保持一致。
+
+---
+
+## Phase 4: User Story 2 - 调用 SYS-008 开票并查询兜底 (Priority: P1)
+
+**Goal**: 实现提交开票申请后的异步协同、受理号记录、定时/主动查询兜底，并保证成功状态不被后续失败结果覆盖。
+
+**Independent Test**: 发票申请成功后生成受理号与查询上下文；查询接口可按申请单号/受理号返回结果；查询异常不会覆盖既有成功状态。
+
+### Implementation for User Story 2
+
+- [x] T023 [US2] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的 `SYS-008` 异步协同、查询补偿、终态保护和异常核查流程
+- [x] T024 [US2] 更新 `specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md` 中后台查询、系统补偿查询和客户侧消费前置规则
+- [x] T025 [US2] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中 `IF-REV-009` 的查询与补偿查询接口定义
+- [x] T026 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台查询与补偿查询入口
+- [x] T027 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java` 与 `service/invoice/InvoiceServiceImpl.java` 实现 `SYS-008` 申请提交、受理号记录和按申请单号/受理号查询
+- [x] T028 [P] [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryReqVO.java` 与 `InvoiceQueryRespVO.java` 承接 `applicationNo`、`sysRequestNo`、`querySource`
+- [x] T029 [P] [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 与 `dal/mysql/invoice/InvoiceMapper.java` 承接 `lastTryTime`、`nextTryTime`、`tryCount`、`latestResult`、`latestError`
+- [x] T030 [US2] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现成功终态保护和查询来源留痕
+- [x] T031 [US2] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `docs/design/02_Detailed_Design/12_REV_Detailed.md`、`docs/design/03_Technical_Design/03_Interface_Design.md` 与 `backend/sw-business/sw-business-server/pom.xml` 的查询链路校验结果
+- [x] T032 [US2] 更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md` 同步 US2 收口结果
+- [ ] T033 [US2] 在 `specs/002-rev005-invoice-flow/verification.md` 补充 `SYS-008` 不可用、受理超时、补偿查询重试等异常样本与结论
+
+**Checkpoint**: `SYS-008` 异步协同与查询兜底链路可独立演示，`IF-REV-009` 口径已稳定。
+
+---
+
+## Phase 5: User Story 3 - 结果回写、账单关联与客户侧消费 (Priority: P2)
+
+**Goal**: 实现开票结果回写、账单-发票关联状态更新，以及客户侧查看/下载/推送已开具电子发票。
+
+**Independent Test**: 开票成功后账单与发票建立关联；客户侧仅能查看属于当前客户且已开具的电子发票；下载/推送前必须校验 `SUCCESS + fileUrl`。
+
+### Implementation for User Story 3
+
+- [x] T034 [US3] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 REV-005 的结果回写、账单关联、客户侧查看/下载/推送规则
+- [x] T035 [US3] 更新 `docs/design/03_Technical_Design/01_Database_Design.md` 中 `biz_invoice`、账单-发票关系快照、客户查询身份与操作留痕承接口径
+- [x] T036 [US3] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 中客户侧查看、下载、推送电子发票的请求/响应约束
+- [x] T037 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加结果回写、客户侧查询、下载、推送接口
+- [x] T038 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java` 与 `service/invoice/InvoiceServiceImpl.java` 实现结果回写、账单关联和客户侧消费逻辑
+- [x] T039 [P] [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`、`InvoiceCustomerQueryReqVO.java`、`InvoicePushReqVO.java` 承接回写与客户侧消费字段
+- [x] T040 [P] [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 与 `dal/mysql/invoice/InvoiceMapper.java` 承接 `invoiceCode`、`invoiceNumber`、`fileUrl`、`pushStatus`、关联状态字段
+- [x] T041 [US3] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java` 实现客户归属校验和 `SUCCESS + fileUrl` 前置校验
+- [x] T042 [US3] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `docs/design/03_Technical_Design/01_Database_Design.md`、`docs/design/03_Technical_Design/03_Interface_Design.md` 与 `backend/sw-business/sw-business-server/pom.xml` 的结果回写/客户消费链路校验结果
+- [x] T043 [US3] 更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md` 同步 US3 收口结果
+- [ ] T044 [US3] 在 `specs/002-rev005-invoice-flow/verification.md` 补充 SC-003 与 SC-004 所需的回写、查询、下载、推送样本统计和结论
+
+**Checkpoint**: 发票结果回写、账单关联和客户侧电子票消费链路可以独立评审并验证。
+
+---
+
+## Phase 6: User Story 4 - 发票作废与红冲 (Priority: P3)
+
+**Goal**: 在一期正常开票闭环基础上，补齐后台发票作废与红冲的正式文档、接口入口、状态校验、`SYS-008` 协同、查询补偿与结果落账能力。
+
+**Independent Test**: 后台可对满足条件的 `SUCCESS` 发票发起作废或红冲；接口、详细设计与 backend 实现口径一致；最小编译与文档校验通过。
+
+### Implementation for User Story 4
+
+- [x] T045 [US4] 更新 `specs/002-rev005-invoice-flow/spec.md` 与 `specs/002-rev005-invoice-flow/plan.md`，将作废/红冲从“后续预留”提升为当前 REV-005 二期范围
+- [x] T046 [US4] 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 明确作废与红冲的触发入口、状态流转、原票约束、账单联动与日志要求
+- [x] T047 [US4] 更新 `docs/design/03_Technical_Design/03_Interface_Design.md` 明确后台作废/红冲接口、请求响应字段、查询补偿与客户侧消费边界
+- [x] T048 [US4] 更新 `docs/design/03_Technical_Design/01_Database_Design.md` 标注作废/红冲所需承接字段、原票关联与失败原因口径
+- [x] T049 [US4] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java` 增加后台作废与红冲接口
+- [x] T050 [US4] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java` 与 `service/invoice/InvoiceServiceImpl.java` 实现作废、红冲、原票校验、查询补偿与日志留痕
+- [x] T051 [P] [US4] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java` 与 `InvoiceRedInkReqVO.java` 承接原因、备注、原票关联等字段
+- [x] T052 [P] [US4] 更新 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 与 `dal/mysql/invoice/InvoiceMapper.java` 承接作废/红冲状态、原票关联、失败原因与查询上下文
+- [x] T053 [US4] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `docs/design/02_Detailed_Design/12_REV_Detailed.md`、`docs/design/03_Technical_Design/03_Interface_Design.md` 与 `backend/sw-business/sw-business-server/pom.xml` 的作废/红冲链路校验结果
+- [x] T054 [US4] 更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md` 同步 US4 收口结果
+- [ ] T055 [US4] 在 `specs/002-rev005-invoice-flow/verification.md` 补充作废/红冲运行态日志样本，并跟进 `biz_invoice` 物理 DDL / migration 来源风险的后续结论
+
+**Checkpoint**: 作废与红冲已从“预留”升级为可评审、可编译验证的二期能力入口。
+
+---
+
+## Final Phase: Cross-Cutting Closure
+
+**Purpose**: 完成仓库级一致性复核、成功标准证据补齐和最终交付总结。
+
+- [x] T056 [P] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `make check-links` 对 `docs/design/02_Detailed_Design/12_REV_Detailed.md`、`docs/design/03_Technical_Design/03_Interface_Design.md`、`docs/design/03_Technical_Design/01_Database_Design.md` 的交叉引用校验结果
+- [x] T057 [P] 在 `specs/002-rev005-invoice-flow/verification.md` 记录 `make validate-mermaid` 对 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 与 `docs/design/03_Technical_Design/03_Interface_Design.md` 的 Mermaid 校验结果
+- [x] T058 在 `specs/002-rev005-invoice-flow/verification.md` 固化 `biz_invoice` 物理 DDL / migration 来源交叉核查结果与剩余风险
+- [x] T059 在 `specs/002-rev005-invoice-flow/verification.md` 固化 SC-005“关键动作 ↔ 日志写入点”矩阵，并回扣 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`
+- [ ] T060 在 `specs/002-rev005-invoice-flow/verification.md` 补充 `/business/invoice/apply` 的 SC-001 响应时延采样口径、命令和结果
+- [ ] T061 在 `specs/002-rev005-invoice-flow/verification.md` 补充 SC-002 正常业务场景的发票申请通过率样本统计、分组和结论
+- [ ] T062 在 `specs/002-rev005-invoice-flow/verification.md` 补充 SC-003 开票结果回写成功率的样本统计、失败分类和结论
+- [ ] T063 在 `specs/002-rev005-invoice-flow/verification.md` 补充 SC-004 客户侧查询/下载/推送成功率的样本统计、拦截原因和结论
+- [x] T064 在 `specs/002-rev005-invoice-flow/spec.md` 更新 `Status` 与 `Next Steps`，使其与 `specs/002-rev005-invoice-flow/tasks.md`、`verification.md` 的当前完成度一致
+- [x] T065 在 `specs/002-rev005-invoice-flow/tasks.md`、`specs/002-rev005-invoice-flow/verification.md`、`docs/design/00_Management/01_Project_Progress.md`、`docs/design/00_Management/03_Task_Checklist.md` 汇总最终交付说明、剩余风险与下一步建议
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Scope & Source Confirmation**: 无依赖；必须先完成，作为单一真源与范围边界基线
+- **Foundational**: 依赖 Scope & Source Confirmation；必须在用户故事前完成
+- **US1**: 依赖 Foundational；是 MVP 最小闭环入口
+- **US2**: 依赖 US1；复用申请单号、受理号和基础申请链路
+- **US3**: 依赖 US2；复用终态结果、查询补偿和电子票结果
+- **US4**: 依赖 US3；在正常开票闭环基础上补齐后处理能力
+- **Final Phase**: 依赖所有已选择的用户故事完成
+
+### Within Each User Story
+
+- 先更新正式文档与合同，再更新 backend 接口与服务
+- 先补请求/响应对象与数据映射，再实现服务逻辑
+- 先固化文档/代码验证证据，再更新管理台账
+- 运行态样本、统计口径与 Success Criteria 证据在该故事完成后补齐
+
+### Parallel Opportunities
+
+- `T003` 与 `T004` 可并行确认正式文档与 backend 触点
+- `T009` 与 `T010` 可并行确认 VO 及外部依赖对象
+- US1 中 `T017` 与 `T018` 可并行
+- US2 中 `T028` 与 `T029` 可并行
+- US3 中 `T039` 与 `T040` 可并行
+- US4 中 `T051` 与 `T052` 可并行
+- Final Phase 中 `T056` 与 `T057` 可并行
+- Final Phase 中 `T060`、`T061`、`T062`、`T063` 可在样本准备完成后并行统计
+
+---
+
+## Implementation Strategy
+
+### MVP First
+
+1. 先完成 Shared Foundation，统一文档、接口、数据和台账出口。
+2. 优先交付 **US1 发票申请与校验**，形成后台最小受理入口。
+3. 再交付 **US2 异步协同与查询兜底**，完成 `SYS-008` 结果获取闭环。
+4. 再交付 **US3 结果回写、账单关联与客户侧消费**，形成一期完整业务闭环。
+5. 最后交付 **US4 作废与红冲**，补齐二期后处理入口。
+6. 进入 Final Phase，集中补齐 Success Criteria 量化证据和最终交付摘要。
+
+### Independent Test Criteria by Story
+
+- **US1**: 后台发票申请成功生成申请单号，非法账单/原始单账单直接部分开票被拦截
+- **US2**: 查询接口可按申请单号或受理号返回结果，成功终态不被失败覆盖
+- **US3**: 结果回写后账单与发票关联可查，客户侧只能查看并下载/推送本人已开票电子票
+- **US4**: 后台可发起作废/红冲，终态正确更新为 `INVALID` 或 `RED_INK`，且保留原票关系、失败原因与日志留痕
+
+### Notes
+
+- 本任务清单已修复旧版 `T057 ~ T061` 在 US4 与 Final Phase 重号的问题。
+- 本任务清单保留当前仓库真实完成度：现有实现与已落账证据标记为 `[x]`，待补统计与运行态样本标记为 `[ ]`。
+- `specs/002-rev005-invoice-flow/verification.md` 是 SC-001 ~ SC-005 证据的唯一落点；若当前环境无法完成统计验证，至少要明确样本口径、缺口和风险。
+- `docs/design/04_Appendix/Archive/` 仅用于核对与追溯，不作为正式主稿替代来源。
+- 由于当前分支为 `dev/rev004-implementation`，本次 `/speckit.tasks` 按现有 artifacts 手工推进，而非依赖 feature-branch prerequisite 脚本。

specs/002-rev005-invoice-flow/verification.md

@@ -0,0 +1,705 @@
+# REV-005 验证记录
+
+## 1. 验证范围
+
+本记录用于沉淀 `REV-005` 当前已完成的发票业务闭环验证证据，覆盖以下范围：
+
+- US1：后台发票申请与校验
+- US2：`SYS-008` 异步协同与查询兜底
+- US3：结果回写、账单关联与客户侧电子发票消费
+- US4：后台作废与红冲二期入口
+
+当前验证结论以已执行命令、已完成文档修订、最小编译验证和范围边界复核为主；`spec.md` 中 `SC-001 ~ SC-005` 的性能/统计指标尚未形成专门压测脚本或批量样本统计，本文件先记录现有证据、缺口与后续建议。
+
+## 2. 已执行验证命令与结果
+
+| 类别 | 命令 | 结果 | 说明 |
+|------|------|------|------|
+| 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` | 通过 | 已用于验证发票数据承接口径 |
+| 文档单文件校验 | `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` | 通过 | 已用于验证客户侧查询/下载/推送与作废/红冲接口边界文档 |
+| 文档单文件校验 | `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` | 通过 | 已用于验证 REV-005 二期作废/红冲详细设计修订 |
+| backend 最小编译 | `mvn -f backend/sw-business/sw-business-server/pom.xml -DskipTests compile` | 通过 | 已用于验证 REV-005 US3/US4 代码可编译 |
+| 仓库交叉引用校验 | `make check-links` | 通过 | 当前链接检查输出为“所有链接检查通过” |
+| Mermaid 语法校验 | `make validate-mermaid` | 通过 | 当前 Mermaid 验证输出为“所有 mermaid 图表语法验证通过” |
+| 验收资产复核 | 仓库关键字检索（`SC-001`、`SC-002`、`SC-003`、`SC-004`、`样本统计`、`压测脚本`、`P95`） | 未发现现成统计资产 | 当前仓库内暂未定位到可直接复用的压测脚本、统计脚本或样本台账，SC-001 ~ SC-004 仍需在测试或联调环境补充专项证据 |
+
+## 3. Success Criteria 对照
+
+### SC-001 发票申请接口响应时间 < 500ms（不包含外部服务调用）
+
+- **当前状态**：待补充专项验证（实现态证据已补强）
+- **现有证据**：backend 最小编译通过，后台申请接口与校验链路已实现
+- **实现态补充证据**：`InvoiceController.applyInvoice` 已固定暴露 `/business/invoice/apply` 入口；`InvoiceApplyReqVO` 强制要求 `chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`sourceChannel`；`InvoiceServiceImpl.applyInvoice` 当前同步执行的仅包括账单去重排序、幂等单号生成、客户/客户开票信息/账单/税率校验、`InvoiceDO` 落库与操作日志写入，并未在该方法内直接同步调用外部 `SYS-008`，而是通过生成 `sysRequestNo`、写入 `PENDING` 状态后结束本地受理流程。
+- **缺口说明**：尚未执行接口响应时延采样，也未沉淀固定样本、环境与统计结果
+- **后续建议**：在可用测试环境中对 `/business/invoice/apply` 执行最小样本压测或定点采样，至少记录样本量、平均值、P95、排除外部调用口径
+- **建议统计口径**：仅统计 `SYS-002` 本地受理、账单/客户/税率/限额校验、申请记录落库等内部处理时延；明确剔除 `SYS-008` 外部接口等待时间；结果表至少记录样本时间、样本环境、请求体摘要、平均值、P95、最大值与异常样本说明
+
+### SC-002 发票申请校验通过率 > 95%（正常业务场景）
+
+- **当前状态**：待补充样本统计（实现态证据已补强）
+- **现有证据**：已实现账单收费状态、开票状态、客户开票信息、税率配置、开票限额、幂等控制等校验规则
+- **实现态补充证据**：`validateCustInvoice` 已明确拦截“客户未维护开票信息”“客户开票信息不存在”“发票抬头不一致”“税号不一致”“电子发票缺少邮箱/手机号”等场景；`validateCharges` 已明确拦截“账单不存在”“账单与客户不匹配”“仅已收费账单允许申请开票”“存在已开票账单”；`validateInvoiceTaxrate` 会拦截缺少可用税率配置；`applyInvoice` 对同一 `applicationNo` 或 `custId + chargeIds` 组合会直接返回既有申请，因此幂等命中样本应单列说明，不能混入正常成功率分母。
+- **缺口说明**：尚未基于真实或模拟样本形成“正常场景通过率”统计
+- **后续建议**：准备覆盖正常账单、已开票账单、未缴费账单、限额超限账单等样本集，按样本分组输出通过/拦截统计
+- **建议统计口径**：将样本分为“正常业务场景”和“规则拦截场景”两组；SC-002 仅统计正常业务场景的申请成功率，结果表至少记录样本总数、成功数、失败数、失败原因分类，并单列幂等命中、原始单账单直接部分开票拦截等非正常场景说明
+
+### SC-003 开票结果回写成功率 > 99%
+
+- **当前状态**：待补充样本统计（实现态证据已补强）
+- **现有证据**：已实现结果回写、成功终态保护、账单状态联动、失败原因留痕
+- **实现态补充证据**：`writeBackInvoice` 已支持按 `applicationNo` / `sysRequestNo` 定位发票，统一回写 `invoiceStatus`、`invoiceCode`、`invoiceNumber`、`fileUrl`、`pushStatus`、`latestResult`、`latestError` 与 `failReason`，并调用 `syncChargeInvoiceState` 做账单联动；若当前记录已是 `SUCCESS` 且收到非成功回写，会命中“成功终态保护”分支，仅刷新查询上下文与日志，不覆盖既有成功结果；`queryInvoice` 与 `/query/compensate` 复用 `refreshQueryContext`，可为回写失败、超时与补偿查询样本提供统一追溯键。
+- **缺口说明**：尚未基于批量样本统计回写成功率
+- **后续建议**：在联调或测试环境中按申请单号、受理号建立样本集，统计回写请求总量、成功量、失败量与失败原因分类
+- **建议统计口径**：按“回写请求总量”“业务成功落账量”“业务失败量”“因成功终态保护而不覆盖原状态量”四类指标统计；失败样本需区分外部返回失败、查询超时、账单联动异常、数据缺失等分类，并保留申请单号/受理号映射以便追溯
+
+### SC-004 电子发票下载成功率 > 99%
+
+- **当前状态**：待补充样本统计（实现态证据已补强）
+- **现有证据**：已实现仅 `SUCCESS + fileUrl` 可下载/推送的前置校验，客户归属校验与推送状态回写已落地
+- **实现态补充证据**：`getRequiredCustomerInvoice` 已要求 `custId` 必填，且 `invoiceId`、`applicationNo`、`sysRequestNo` 至少提供一个定位键，并会拦截“未找到当前客户可访问的电子发票”；`validateDownloadableInvoice` 已明确拦截“当前发票状态不可下载或推送”“电子发票文件地址不存在”；`pushInvoice` 仅支持 `EMAIL`、`SMS` 两类渠道，并分别校验邮箱/手机号是否可用，成功后会更新 `pushStatus`、`latestResult` 并记录渠道与目标。
+- **缺口说明**：尚未形成客户侧下载成功率样本统计
+- **后续建议**：在具备有效电子票文件地址的样本下，统计查询、下载、推送三类动作成功率，并区分“无权限”“无文件”“非成功终态”等拦截原因
+- **建议统计口径**：以具备有效 `SUCCESS + fileUrl` 条件的样本作为成功率分母，同时单独记录被权限校验、文件缺失、非成功终态拦截的请求量；建议分别输出“客户查询成功率”“下载成功率”“推送成功率”三个子指标，避免把前置拦截与真实下载失败混为一类
+
+### SC-005 操作日志完整率 100%（所有关键操作均有日志）
+
+- **当前状态**：实现态证据已补齐，运行态样本待抽查
+- **现有证据**：`InvoiceServiceImpl` 已通过统一 `recordInvoiceOperatLog` 入口写入关键动作日志，并由 `OperatLogService.createOperatLog` 承接操作人、客户标识与日志内容上下文
+- **关键动作 ↔ 日志写入点矩阵**：
+
+| 关键动作 | 业务入口 | 日志写入点 | 说明 |
+|------|------|------|------|
+| 发票申请 / 提交 SYS-008 开票申请 | `applyInvoice` | `recordInvoiceOperatLog(invoice, "提交SYS-008开票申请...")` | 记录申请受理与受理号 |
+| 后台查询结果 | `queryInvoice` → `refreshQueryContext` | `recordInvoiceOperatLog(invoice, "发票查询补偿，来源：...")` | 普通查询与补偿查询复用同一留痕点，依赖 `querySource` 区分 |
+| 结果回写 | `writeBackInvoice` | `recordInvoiceOperatLog(invoice, "回写发票结果...")` | 成功/失败终态更新后统一留痕 |
+| 成功终态保护 | `writeBackInvoice` | `recordInvoiceOperatLog(invoice, "收到回写结果但因成功终态保护未覆盖原状态...")` | 记录保护分支未覆盖原状态的原因 |
+| 客户侧查询 | `queryCustomerInvoice` → `refreshCustomerQueryContext` | `recordInvoiceOperatLog(invoice, "发票查询补偿，来源：CUSTOMER_QUERY...")` | 记录客户侧查询动作 |
+| 客户侧下载 | `downloadInvoice` | `recordInvoiceOperatLog(invoice, "客户侧下载电子发票")` | 记录电子发票下载动作 |
+| 客户侧推送 | `pushInvoice` | `recordInvoiceOperatLog(invoice, "客户侧推送电子发票...")` | 记录推送渠道与目标 |
+| 后台作废 | `invalidateInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 |
+| 后台红冲 | `redInkInvoice` | `recordInvoiceOperatLog(invoice, buildPostProcessLog(...))` | 记录原因、备注与原票代码/号码 |
+
+- **缺口说明**：尚未在测试或联调环境按上述矩阵逐项抽取实际日志样本，当前仍缺运行态日志记录证据
+- **DDL/迁移跟进结论**：已交叉核查 `backend/sql`、Archive 数据库设计、`sql/lhc_数据库设计.md` 与 `BACKEND_TABLE_MAPPING.md`；当前仍未定位到与 `InvoiceDO` 最新字段完全一致的 `biz_invoice` 物理 DDL / migration 脚本，现有同名历史对象更偏开票配置表，US4 的物理落库链路仍需继续结合实际数据库变更记录确认。
+- **后续建议**：按矩阵至少抽取申请、补偿查询、结果回写、客户下载、客户推送、作废、红冲各 1 条日志样本，核对操作人、客户、状态与日志内容是否一致
+
+### 待补样本记录模板（不含实际结果）
+
+#### T060 / SC-001 响应时延记录模板
+
+| 采样时间 | 环境 | 接口 | 样本量 | 平均值(ms) | P95(ms) | 最大值(ms) | 是否剔除 `SYS-008` 等待 | 异常样本说明 |
+|------|------|------|------:|------:|------:|------:|------|------|
+| 待补 | 待补 | `/business/invoice/apply` | 待补 | 待补 | 待补 | 待补 | 是 / 否（待补） | 待补 |
+
+- **待补说明**：采样时需同步记录请求体摘要（账单数、开票类型、客户类型）与测试环境配置，避免不同批次结果不可比。
+
+#### T061 / SC-002 申请通过率记录模板
+
+| 样本分组 | 样本总数 | 成功数 | 失败数 | 失败原因分类 | 统计口径说明 |
+|------|------:|------:|------:|------|------|
+| 正常业务场景 | 待补 | 待补 | 待补 | 待补 | 仅统计应当成功的申请样本 |
+| 规则拦截场景 | 待补 | 待补 | 待补 | 待补 | 单独记录，不计入 SC-002 分母 |
+
+- **待补说明**：建议至少覆盖正常账单、已开票账单、未缴费账单、限额超限账单、幂等命中、原始单账单直接部分开票拦截等样本。
+
+#### T062 / SC-003 回写成功率记录模板
+
+| 回写批次 | 回写请求总量 | 业务成功落账量 | 业务失败量 | 成功终态保护量 | 失败原因分类 | 追溯主键 |
+|------|------:|------:|------:|------:|------|------|
+| 待补 | 待补 | 待补 | 待补 | 待补 | 待补 | `applicationNo` / `sysRequestNo`（待补） |
+
+- **待补说明**：失败原因建议至少区分外部返回失败、查询超时、账单联动异常、数据缺失；同一批次需保留申请单号与受理号映射关系。
+
+#### T063 / SC-004 客户侧查询/下载/推送成功率记录模板
+
+| 动作类型 | 样本总数 | 成功数 | 失败数 | 前置拦截数 | 失败/拦截原因分类 | 统计口径说明 |
+|------|------:|------:|------:|------:|------|------|
+| 客户查询 | 待补 | 待补 | 待补 | 待补 | 待补 | 仅统计客户侧查询动作 |
+| 发票下载 | 待补 | 待补 | 待补 | 待补 | 待补 | 分母建议取具备 `SUCCESS + fileUrl` 条件的样本 |
+| 发票推送 | 待补 | 待补 | 待补 | 待补 | 待补 | 单列推送渠道与目标类型 |
+
+- **待补说明**：需区分“无权限”“无文件”“非成功终态”等前置拦截，不建议与真实下载/推送失败混算。
+
+#### T055 / SC-005 运行态日志抽样模板
+
+| 动作类型 | 样本来源 | 操作人/客户 | 状态前后值 | 日志摘要 | 结果 |
+|------|------|------|------|------|------|
+| 发票申请 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 查询补偿 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 结果回写 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 客户下载 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 客户推送 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 后台作废 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| 后台红冲 | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+- **待补说明**：样本抽取时需能回扣到 `recordInvoiceOperatLog` / `OperatLogService.createOperatLog` 的实现态矩阵，并保留查询来源、渠道、原票代码/号码等关键上下文。
+- **DDL 跟进说明**：与日志样本同步收口时，还需补记本轮核查结论：当前仓库仍未定位到与 `InvoiceDO` 当前模型完全对齐的 `biz_invoice` 物理 DDL / migration 来源；若联调环境已完成数据库变更，应同时记录变更单号、脚本路径或 DBA 提供的物理表结构证明。
+
+### 待补样本执行入口清单
+
+| 对应待办 | 接口/合同 | 当前请求路径 | Controller 入口 | Service 入口 | 说明 |
+|------|------|------|------|------|------|
+| `T060` / `T061` | `IF-REV-008` | `/business/invoice/apply` | `InvoiceController.applyInvoice` | `InvoiceService.applyInvoice` / `InvoiceServiceImpl.applyInvoice` | 用于申请时延采样与正常/拦截样本统计 |
+| `T062` | `IF-REV-009` | `/business/invoice/query`、`/business/invoice/query/compensate`、`/business/invoice/write-back` | `InvoiceController.queryInvoice`、`compensateQueryInvoice`、`writeBackInvoice` | `InvoiceService.queryInvoice`、`writeBackInvoice` / `InvoiceServiceImpl.queryInvoice`、`writeBackInvoice` | 用于查询补偿、回写成功率与成功终态保护样本 |
+| `T063` | `IF-CS-004` | `/business/invoice/customer/query`、`/business/invoice/customer/download`、`/business/invoice/customer/push` | `InvoiceController.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` | `InvoiceService.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` / `InvoiceServiceImpl.queryCustomerInvoice`、`downloadInvoice`、`pushInvoice` | 用于客户查询、下载、推送成功率统计 |
+| `T055` | `IF-REV-008`、`IF-REV-009`、`IF-CS-004`、`IF-EXT-007` | `/business/invoice/apply`、`/business/invoice/query`、`/business/invoice/customer/*`、`/business/invoice/invalidate`、`/business/invoice/red-ink` | `InvoiceController.applyInvoice`、`queryInvoice`、`queryCustomerInvoice`、`downloadInvoice`、`pushInvoice`、`invalidateInvoice`、`redInkInvoice` | `InvoiceServiceImpl.applyInvoice`、`queryInvoice`、`writeBackInvoice`、`queryCustomerInvoice`、`downloadInvoice`、`pushInvoice`、`invalidateInvoice`、`redInkInvoice` | 用于运行态日志抽样与动作-日志矩阵回扣 |
+
+- **执行说明**：当前仓库正式文档与 backend `InvoiceController` 的实现入口统一使用 `/business/invoice/*` 路径；若后续联调环境存在网关前缀或转发规则，应在样本记录中额外注明映射关系。
+- **本地验证入口排查结论**：当前仓库 `quickstart.md` 未提供可直接复用的 `curl` / Postman / HTTP 脚本来采集 `T055`、`T060 ~ T063` 的真实样本；现阶段可直接依赖的入口主要是接口设计、`InvoiceController` 路径声明与 `InvoiceService(Impl)` 调用链，真实样本仍需在可用测试或联调环境手工执行并回填。
+
+### 最小请求模板（待联调填真实值）
+
+- **用途说明**：以下 JSON 仅作为 `T055`、`T060 ~ T063` 的最小请求体草稿，用于后续在测试或联调环境手工发起请求并回填真实样本。
+- **填写约束**：示例中的 `applicationNo`、`sysRequestNo`、`invoiceId`、`chargeIds`、`custId` 等值均为占位符，执行前必须替换为环境中的真实数据。
+
+#### `/business/invoice/apply`
+
+```json
+{
+  "chargeIds": [10001],
+  "custId": 1024,
+  "invoiceType": "ELECTRONIC",
+  "invoiceTitle": "福建水务测试客户",
+  "sourceChannel": "COUNTER"
+}
+```
+
+- **最小必填字段来源**：`chargeIds`、`custId`、`invoiceType`、`invoiceTitle`、`sourceChannel`
+- **可选补充字段**：`applicationNo`（幂等单号）、`taxNo`、`email`、`mobile`、`remark`
+
+#### `/business/invoice/query`
+
+```json
+{
+  "applicationNo": "APP-REV005-001",
+  "querySource": "MANUAL"
+}
+```
+
+- **最小必填字段来源**：`querySource`
+- **定位建议**：`applicationNo`、`sysRequestNo` 二选一至少补一个真实定位键，避免联调时无法唯一定位申请记录
+
+#### `/business/invoice/query/compensate`
+
+```json
+{
+  "applicationNo": "APP-REV005-001",
+  "querySource": "AUTO_COMPENSATE"
+}
+```
+
+- **最小必填字段来源**：`querySource`
+- **说明**：controller 会按补偿查询语义覆盖 `querySource`，但请求体仍建议显式传入 `AUTO_COMPENSATE`
+
+#### `/business/invoice/write-back`
+
+```json
+{
+  "applicationNo": "APP-REV005-001",
+  "invoiceStatus": "SUCCESS"
+}
+```
+
+- **最小必填字段来源**：`invoiceStatus`
+- **定位建议**：`applicationNo`、`sysRequestNo` 二选一至少补一个真实定位键；若为成功样本，建议同步补 `invoiceCode`、`invoiceNumber`、`fileUrl`
+
+#### `/business/invoice/customer/query`
+
+```json
+{
+  "custId": 1024,
+  "invoiceId": 2048
+}
+```
+
+- **最小 Bean Validation 字段**：`custId`
+- **定位建议**：联调时应至少补 `applicationNo`、`sysRequestNo`、`invoiceId` 之一；上例默认使用 `invoiceId` 作为定位键
+
+#### `/business/invoice/customer/download`
+
+```json
+{
+  "custId": 1024,
+  "invoiceId": 2048
+}
+```
+
+- **最小 Bean Validation 字段**：`custId`
+- **定位建议**：与客户查询一致，联调时应至少补 `applicationNo`、`sysRequestNo`、`invoiceId` 之一
+
+#### `/business/invoice/customer/push`
+
+```json
+{
+  "custId": 1024,
+  "invoiceId": 2048,
+  "pushChannel": "EMAIL",
+  "pushEmail": "test@example.com"
+}
+```
+
+- **最小必填字段来源**：`custId`、`invoiceId`、`pushChannel`
+- **渠道补充说明**：`pushChannel=EMAIL` 时建议同时补 `pushEmail`；`pushChannel=SMS` 时建议同时补 `pushMobile`
+
+#### `/business/invoice/invalidate`
+
+```json
+{
+  "invoiceId": 2048,
+  "invalidReason": "测试作废样本"
+}
+```
+
+- **最小必填字段来源**：`invoiceId`、`invalidReason`
+- **可选补充字段**：`invalidRemark`、`originalInvoiceCode`、`originalInvoiceNumber`
+
+#### `/business/invoice/red-ink`
+
+```json
+{
+  "invoiceId": 2048,
+  "redInkReason": "测试红冲样本"
+}
+```
+
+- **最小必填字段来源**：`invoiceId`、`redInkReason`
+- **可选补充字段**：`redInkRemark`、`originalInvoiceCode`、`originalInvoiceNumber`
+
+### 执行命令草稿与样本采集顺序
+
+- **使用原则**：以下命令仅作为测试或联调环境的执行草稿，不包含真实环境地址、鉴权信息与业务主键；执行前需替换 `${BASE_URL}`、`${TOKEN}`、`${APPLICATION_NO}`、`${SYS_REQUEST_NO}`、`${INVOICE_ID}`、`${CUST_ID}`、`${CHARGE_ID}` 等占位符。
+- **结果约束**：命令执行后的真实响应、日志截图、统计数值不得预填，需在拿到实际结果后回填到本文件对应模板。
+
+#### 通用命令头草稿
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/apply" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"chargeIds":[${CHARGE_ID}],"custId":${CUST_ID},"invoiceType":"ELECTRONIC","invoiceTitle":"福建水务测试客户","sourceChannel":"COUNTER"}'
+```
+
+- **说明**：若联调环境存在网关前缀、灰度路由、租户头或其他鉴权头，应在执行记录中一并注明。
+
+#### T060 / T061：申请时延与通过率采样顺序
+
+1. 使用正常账单样本执行 `/business/invoice/apply`，记录请求时间、响应时间、`applicationNo` 与是否命中正常受理。
+2. 复用同一命令替换不同样本，分别覆盖已开票、未缴费、限额超限、幂等命中、原始单账单直接部分开票等场景。
+3. 将正常业务场景样本汇总到 `T061 / SC-002` 表，将规则拦截场景单独归类，不计入 SC-002 分母。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/apply" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"chargeIds":[${CHARGE_ID}],"custId":${CUST_ID},"invoiceType":"ELECTRONIC","invoiceTitle":"福建水务测试客户","sourceChannel":"COUNTER"}'
+```
+
+#### T062：回写成功率采样顺序
+
+1. 先对已申请样本执行 `/business/invoice/query`，确认当前状态与 `sysRequestNo`。
+2. 对已拿到税控结果的样本执行 `/business/invoice/write-back`，分别覆盖成功回写、失败回写、成功终态保护三类场景。
+3. 若存在查询兜底场景，再执行 `/business/invoice/query/compensate`，补录补偿查询命中情况与失败分类。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/query" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"applicationNo":"${APPLICATION_NO}","querySource":"MANUAL"}'
+
+curl -X POST "${BASE_URL}/business/invoice/write-back" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"applicationNo":"${APPLICATION_NO}","invoiceStatus":"SUCCESS"}'
+
+curl -X POST "${BASE_URL}/business/invoice/query/compensate" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"applicationNo":"${APPLICATION_NO}","querySource":"AUTO_COMPENSATE"}'
+```
+
+#### T063：客户侧查询 / 下载 / 推送采样顺序
+
+1. 先执行 `/business/invoice/customer/query`，确认客户归属与发票定位键可用。
+2. 对满足 `SUCCESS + fileUrl` 的样本执行 `/business/invoice/customer/download`。
+3. 在同一批样本上继续执行 `/business/invoice/customer/push`，按 `EMAIL`、`SMS` 等渠道分别统计。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/customer/query" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID}}'
+
+curl -X POST "${BASE_URL}/business/invoice/customer/download" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID}}'
+
+curl -X POST "${BASE_URL}/business/invoice/customer/push" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"custId":${CUST_ID},"invoiceId":${INVOICE_ID},"pushChannel":"EMAIL","pushEmail":"test@example.com"}'
+```
+
+#### T055：运行态日志抽样顺序
+
+1. 任选一组完整样本，按“申请 → 查询/补偿 → 回写 → 客户查询/下载/推送 → 作废或红冲”顺序执行。
+2. 每执行一步立即在日志系统或数据库中抽取对应操作日志，核对操作人、客户标识、状态前后值与日志摘要。
+3. 作废与红冲建议分别至少准备 1 条独立成功样本，避免同一张票重复处理导致统计混淆。
+
+```bash
+curl -X POST "${BASE_URL}/business/invoice/invalidate" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"invoiceId":${INVOICE_ID},"invalidReason":"测试作废样本"}'
+
+curl -X POST "${BASE_URL}/business/invoice/red-ink" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"invoiceId":${INVOICE_ID},"redInkReason":"测试红冲样本"}'
+```
+
+- **日志抽样补充要求**：若运行态日志需经 Kibana、数据库表或应用日志文件检索取得，应在样本记录中额外注明检索入口、检索条件与截图/导出附件位置。
+
+### 当天联调最小执行卡片
+
+适用场景：当天已经拿到可用环境、鉴权信息和最小样本，目标不是重新梳理设计，而是直接补 `T060`、`T061`、`T062`、`T063`、`T055` 的真实证据。
+
+#### 开始前只确认 6 件事
+
+| 检查项 | 最低要求 |
+|------|------|
+| `BASE_URL` | 已确认实际网关地址和前缀 |
+| `TOKEN` | 已确认可访问 `/business/invoice/*` 的鉴权信息 |
+| 正常申请样本 | 至少 1 组可成功申请的 `custId + chargeIds` |
+| 规则拦截样本 | 至少 2 组，如未缴费、已开票、限额超限或重复申请 |
+| 成功发票样本 | 至少 1 组能进入 `SUCCESS + fileUrl` |
+| 日志入口 | 已确认日志查询入口或数据库检索方式 |
+
+#### 当天最小执行顺序
+
+| 顺序 | 动作 | 目标待办 | 最少产出 |
+|------|------|------|------|
+| 1 | 执行 `/business/invoice/apply` 正常样本和拦截样本 | `T060`、`T061` | 响应时间、`applicationNo`、成功/拦截分类 |
+| 2 | 对成功申请样本执行 `/business/invoice/query` | `T062` | `sysRequestNo`、当前状态、查询结果 |
+| 3 | 执行 `/business/invoice/write-back`，至少覆盖 `SUCCESS` 和 1 类失败 | `T062` | 回写结果、失败分类、是否命中成功终态保护 |
+| 4 | 对兜底样本执行 `/business/invoice/query/compensate` | `T062` | 补偿查询结果 |
+| 5 | 对 `SUCCESS + fileUrl` 样本执行客户侧查询/下载/推送 | `T063` | 查询结果、下载结果、推送结果 |
+| 6 | 对成功样本执行作废或红冲，并立即抽取日志 | `T055` | 后处理结果、状态前后值、日志样本 |
+
+#### 当天必须回填的 5 个位置
+
+| 待办 | 回填位置 | 最低回填要求 |
+|------|------|------|
+| `T060` | `SC-001` 响应时延表 | 样本量、平均值、P95、最大值 |
+| `T061` | `SC-002` 申请通过率表 | 正常样本与拦截样本分组统计 |
+| `T062` | `SC-003` 回写成功率表 | 成功量、失败量、失败分类、保护量 |
+| `T063` | `SC-004` 客户侧消费表 | 查询/下载/推送三类统计 |
+| `T055` | `SC-005` 日志抽样表 | 至少 1 条关键动作日志样本 |
+
+#### 当天结束前的收口判断
+
+- 若已拿到真实样本，但还没回填正式表格：不要关闭 `tasks.md` 中对应待办。
+- 若已回填表格，但没有请求报文、响应报文或日志截图：仍视为证据不完整。
+- 只有“样本已拿到 + 表格已回填 + 附件已留存”同时满足，才建议勾掉对应任务。
+
+#### 当天可直接复制的变量模板
+
+```bash
+export BASE_URL="https://your-host"
+export TOKEN="replace-with-real-token"
+
+export CUST_ID="1024"
+export CHARGE_ID="10001"
+export INVOICE_ID="2048"
+
+export APPLICATION_NO="APP-REV005-001"
+export SYS_REQUEST_NO="SYS008-APP-REV005-001"
+
+export PUSH_EMAIL="test@example.com"
+export PUSH_MOBILE="13800000000"
+```
+
+#### 当天可直接复制的最小命令组
+
+```bash
+# 1. 申请
+curl -X POST "${BASE_URL}/business/invoice/apply" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"chargeIds\":[${CHARGE_ID}],\"custId\":${CUST_ID},\"invoiceType\":\"ELECTRONIC\",\"invoiceTitle\":\"福建水务测试客户\",\"sourceChannel\":\"COUNTER\"}"
+
+# 2. 查询
+curl -X POST "${BASE_URL}/business/invoice/query" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"applicationNo\":\"${APPLICATION_NO}\",\"querySource\":\"MANUAL\"}"
+
+# 3. 回写成功
+curl -X POST "${BASE_URL}/business/invoice/write-back" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"applicationNo\":\"${APPLICATION_NO}\",\"sysRequestNo\":\"${SYS_REQUEST_NO}\",\"invoiceStatus\":\"SUCCESS\",\"invoiceCode\":\"FPDM001\",\"invoiceNumber\":\"FPHM001\",\"fileUrl\":\"https://example.com/invoice.pdf\"}"
+
+# 4. 补偿查询
+curl -X POST "${BASE_URL}/business/invoice/query/compensate" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"applicationNo\":\"${APPLICATION_NO}\",\"querySource\":\"AUTO_COMPENSATE\"}"
+
+# 5. 客户侧查询 / 下载 / 推送
+curl -X POST "${BASE_URL}/business/invoice/customer/query" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"custId\":${CUST_ID},\"invoiceId\":${INVOICE_ID}}"
+
+curl -X POST "${BASE_URL}/business/invoice/customer/download" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"custId\":${CUST_ID},\"invoiceId\":${INVOICE_ID}}"
+
+curl -X POST "${BASE_URL}/business/invoice/customer/push" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"custId\":${CUST_ID},\"invoiceId\":${INVOICE_ID},\"pushChannel\":\"EMAIL\",\"pushEmail\":\"${PUSH_EMAIL}\"}"
+
+# 6. 作废 / 红冲
+curl -X POST "${BASE_URL}/business/invoice/invalidate" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"invoiceId\":${INVOICE_ID},\"invalidReason\":\"测试作废样本\"}"
+
+curl -X POST "${BASE_URL}/business/invoice/red-ink" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"invoiceId\":${INVOICE_ID},\"redInkReason\":\"测试红冲样本\"}"
+```
+
+#### 单日执行记录表
+
+| 时间 | 执行动作 | 样本主键 | 响应摘要 | 日志是否已取到 | 已回填位置 |
+|------|------|------|------|------|------|
+| 待补 | apply | `applicationNo` / `chargeId` | 待补 | 待补 | `T060/T061` |
+| 待补 | query | `applicationNo` / `sysRequestNo` | 待补 | 待补 | `T062` |
+| 待补 | write-back | `applicationNo` / `sysRequestNo` | 待补 | 待补 | `T062` |
+| 待补 | compensate | `applicationNo` / `sysRequestNo` | 待补 | 待补 | `T062` |
+| 待补 | customer query | `invoiceId` / `custId` | 待补 | 待补 | `T063` |
+| 待补 | download | `invoiceId` / `custId` | 待补 | 待补 | `T063` |
+| 待补 | push | `invoiceId` / `custId` | 待补 | 待补 | `T063` |
+| 待补 | invalidate / red-ink | `invoiceId` | 待补 | 待补 | `T055` |
+
+### 联调补录清单（按顺序执行）
+
+| 步骤 | 对应待办 | 执行动作 | 主要输入 | 预期产出 | 回填位置 |
+|------|------|------|------|------|------|
+| 1 | `T060`、`T061` | 准备正常样本与规则拦截样本，执行 `/business/invoice/apply` | `BASE_URL`、鉴权头、`custId`、`chargeIds`、账单分组清单 | 响应报文、耗时、`applicationNo`、成功/拦截结论 | `T060 / SC-001`、`T061 / SC-002` 模板 |
+| 2 | `T062` | 对步骤 1 成功样本执行 `/business/invoice/query`，确认当前状态与 `sysRequestNo` | `applicationNo` 或 `sysRequestNo` | 查询结果、受理号、当前状态 | `T062 / SC-003` 模板 |
+| 3 | `T062` | 执行 `/business/invoice/write-back`，覆盖成功、失败、成功终态保护样本 | `applicationNo` / `sysRequestNo`、`invoiceStatus` | 回写结果、失败分类、成功终态保护命中情况 | `T062 / SC-003` 模板 |
+| 4 | `T062` | 对兜底样本执行 `/business/invoice/query/compensate` | `applicationNo` / `sysRequestNo` | 补偿查询结果、失败分类、补偿是否命中 | `T062 / SC-003` 模板 |
+| 5 | `T063` | 执行 `/business/invoice/customer/query`，确认客户归属与发票定位键有效 | `custId`、`invoiceId` / `applicationNo` / `sysRequestNo` | 查询结果、客户归属校验结论 | `T063 / SC-004` 模板 |
+| 6 | `T063` | 对 `SUCCESS + fileUrl` 样本执行 `/business/invoice/customer/download` | `custId`、`invoiceId` | 下载结果、前置拦截/真实失败分类 | `T063 / SC-004` 模板 |
+| 7 | `T063` | 对同批样本执行 `/business/invoice/customer/push`，按渠道分别采样 | `custId`、`invoiceId`、`pushChannel` | 推送结果、渠道分类、失败原因 | `T063 / SC-004` 模板 |
+| 8 | `T055` | 基于已成功样本执行 `/business/invoice/invalidate` 与 `/business/invoice/red-ink` | `invoiceId`、作废/红冲原因 | 后处理结果、日志抽样、状态前后值 | `T055 / SC-005` 模板 |
+| 9 | `T055` | 从日志系统、数据库表或应用日志文件提取关键动作留痕 | 检索入口、检索条件、时间窗口 | 日志截图/导出件、操作人/客户/状态核对结果 | `T055 / SC-005` 模板 |
+
+- **执行顺序约束**：步骤 2 ~ 4 依赖步骤 1 至少生成一批成功申请样本；步骤 6 ~ 8 依赖样本已达到 `SUCCESS` 且可定位到目标发票。
+- **补录原则**：每完成一步就即时回填对应表格，不要等全部联调结束后再集中补录，避免申请单号、受理号、日志检索条件丢失。
+- **证据留存建议**：除表格外，建议同时保留请求报文、响应报文、日志截图和必要的数据库查询结果，统一按 `applicationNo` 或 `sysRequestNo` 归档。
+
+### 联调日报 / 回填模板
+
+#### 日报头模板
+
+| 字段 | 填写说明 |
+|------|------|
+| 联调日期 | 填写当天日期 |
+| 联调环境 | 如 SIT / UAT / 联调环境名称 |
+| 执行人 | 填写执行人 |
+| 服务版本 | 填写分支、构建号或部署批次 |
+| 网关地址 | 填写实际调用入口，若有前置网关前缀需写明 |
+| 鉴权方式 | 如 Bearer Token、租户头、会话信息 |
+| 样本范围 | 填写当日使用的账单、客户、发票样本范围 |
+
+#### 当日执行摘要模板
+
+| 对应待办 | 是否执行 | 样本量 | 成功样本 | 失败/拦截样本 | 产出附件 |
+|------|------|------:|------:|------:|------|
+| `T060` / SC-001 响应时延 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T061` / SC-002 申请通过率 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T062` / SC-003 回写成功率 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T063` / SC-004 客户侧消费成功率 | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T055` / SC-005 日志抽样 | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+#### 样本回填索引模板
+
+| 样本标识 | `applicationNo` | `sysRequestNo` | `invoiceId` | 对应步骤 | 回填表格位置 | 备注 |
+|------|------|------|------|------|------|------|
+| 样本 A | 待补 | 待补 | 待补 | 步骤 1 ~ 9（按实际填写） | `T060/T061/T062/T063/T055`（按实际填写） | 待补 |
+| 样本 B | 待补 | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+#### 风险与阻塞模板
+
+| 分类 | 现象 | 影响待办 | 临时处理 | 后续动作 |
+|------|------|------|------|------|
+| 环境 | 待补 | 待补 | 待补 | 待补 |
+| 数据 | 待补 | 待补 | 待补 | 待补 |
+| 接口 | 待补 | 待补 | 待补 | 待补 |
+| 日志 | 待补 | 待补 | 待补 | 待补 |
+
+#### 当日结论模板
+
+- **已完成回填**：待补
+- **未完成原因**：待补
+- **是否影响 `Verification Pending` 状态**：待补
+- **次日建议动作**：待补
+
+- **使用说明**：建议每次联调结束后先填写本节，再同步更新前文 `T055`、`T060 ~ T063` 的正式统计表，避免日报与正式验证记录脱节。
+
+### 联调前置检查清单
+
+| 检查项 | 核对内容 | 当前状态 |
+|------|------|------|
+| 环境地址 | 已确认 `${BASE_URL}`、网关前缀、服务版本与部署批次 | 待补 |
+| 鉴权信息 | 已确认 Bearer Token、租户头、会话信息或其他鉴权方式 | 待补 |
+| 样本数据 | 已准备正常样本、规则拦截样本、成功发票样本、作废样本、红冲样本 | 待补 |
+| 主键映射 | 已确认 `custId`、`chargeIds`、`applicationNo`、`sysRequestNo`、`invoiceId` 的映射关系 | 待补 |
+| 日志入口 | 已确认 Kibana、数据库表或应用日志文件的检索入口 | 待补 |
+| 回填责任 | 已确认谁负责日报填写、谁负责正式表格回填、谁负责附件归档 | 待补 |
+| 归档路径 | 已确认请求报文、响应报文、截图与日志附件的归档位置 | 待补 |
+
+- **执行要求**：未完成上述检查前，不建议直接开始批量联调，避免后续出现样本无法回溯、日志无法检索或统计口径不一致的问题。
+- **建议时点**：每轮联调开始前先更新本清单；若环境、样本或鉴权方式发生变化，应重新复核并更新时间。
+
+### 最终联调执行顺序与完成判定清单
+
+| 顺序 | 对应待办 | 完成标志 | 可勾选条件 |
+|------|------|------|------|
+| 1 | `T060` | 已形成一批申请时延样本 | 已记录 `/business/invoice/apply` 的样本量、平均值、P95、最大值，并注明是否剔除 `SYS-008` 等待 |
+| 2 | `T061` | 已形成正常场景与拦截场景分组统计 | 已区分正常业务场景与规则拦截场景，且正常场景成功/失败统计可追溯到样本主键 |
+| 3 | `T062` | 已形成查询、回写、补偿查询三类结果统计 | 已记录回写请求总量、业务成功落账量、业务失败量、成功终态保护量，并保留失败分类 |
+| 4 | `T063` | 已形成客户查询、下载、推送三类统计 | 已分别记录查询、下载、推送样本量、成功数、失败/前置拦截分类，并保留渠道与定位键 |
+| 5 | `T055` | 已形成关键动作日志样本 | 已抽取申请、查询/补偿、回写、客户下载、客户推送、作废、红冲至少各 1 条日志样本，并能回扣动作矩阵 |
+
+#### 建议最终执行顺序
+
+1. 先完成 `T060`，确保申请入口、环境耗时与基础样本可用。
+2. 再完成 `T061`，把同批申请样本分成“正常业务场景 / 规则拦截场景”两组。
+3. 基于成功申请样本推进 `T062`，补齐查询、回写与补偿查询链路统计。
+4. 仅在样本达到 `SUCCESS + fileUrl` 后推进 `T063`，避免把前置条件不满足的样本误计为下载失败。
+5. 最后完成 `T055`，对上述链路中已成功执行的样本逐项抽取日志，形成最终运行态留痕证据。
+
+#### 单项完成判定模板
+
+| 待办 | 是否已拿到真实样本 | 是否已回填正式表格 | 是否已留存附件 | 是否满足勾选条件 | 备注 |
+|------|------|------|------|------|------|
+| `T060` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T061` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T062` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T063` | 待补 | 待补 | 待补 | 待补 | 待补 |
+| `T055` | 待补 | 待补 | 待补 | 待补 | 待补 |
+
+- **勾选原则**：只有当“真实样本已拿到 + 正式统计表已回填 + 附件已留存”三项同时满足时，对应待办才建议从 `tasks.md` 标记为完成。
+- **收口顺序**：建议按 `T060 → T061 → T062 → T063 → T055` 顺序逐项关闭，避免后置任务缺少前置样本支撑。
+
+### 剩余工作摘要（可直接引用）
+
+- **当前状态**：REV-005 已完成 US1 ~ US4 的实现态闭环与文档侧验证准备，当前处于 `Verification Pending`，剩余工作全部集中在 `T055`、`T060 ~ T063` 的真实联调取证与结果回填。
+- **剩余待办**：
+  1. `T060`：补 `/business/invoice/apply` 的真实响应时延样本与统计结果。
+  2. `T061`：补正常业务场景与规则拦截场景的申请通过率统计。
+  3. `T062`：补查询、回写、补偿查询链路的成功率与失败分类统计。
+  4. `T063`：补客户查询、下载、推送三类动作的成功率与前置拦截分类。
+  5. `T055`：补申请、查询/补偿、回写、客户下载/推送、作废、红冲的运行态日志样本。
+- **完成条件**：上述待办均需满足“真实样本已拿到、正式统计表已回填、附件已留存”三项条件后，方可在 `tasks.md` 中关闭。
+- **建议对外口径**：**REV-005 当前已具备提测前文档与验证准备条件，剩余工作不在于设计或实现补充，而在于测试/联调环境下补齐运行态统计与日志证据。**
+
+## 4. US4 二期实现结论
+
+当前已在以下正式文档与实现文件中明确：
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `specs/002-rev005-invoice-flow/spec.md`
+- `specs/002-rev005-invoice-flow/plan.md`
+- `specs/002-rev005-invoice-flow/tasks.md`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceRedInkReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`
+
+当前结论如下：
+
+1. 发票作废、红冲仍由 `SYS-008` 统一承接税控侧处理。
+2. `SYS-002` 已补齐后台作废 `/business/invoice/invalidate` 与红冲 `/business/invoice/red-ink` 入口，并通过专门请求 VO 承接原因、备注与原发票代码/号码。
+3. 当前实现仅允许对 `SUCCESS` 发票发起作废或红冲；若传入 `originalInvoiceCode`、`originalInvoiceNumber`，必须与当前发票记录一致，重复处理会被拦截。
+4. `InvoiceDO` 与 `01_Database_Design.md` 已补齐作废原因/备注、红冲原因/备注、原发票代码/号码与 `postProcessSource` 等承接口径；service 会同步写入 `latestResult`、`latestError`、账单关联状态与操作日志。
+5. 当前剩余风险主要集中在物理表结构/DDL 来源未在仓库内定位、批量作废/红冲能力未覆盖，以及缺少端到端联调样本。
+
+## 5. 当前已完成文件
+
+### 正式文档
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+
+### spec/planning 产物
+
+- `specs/002-rev005-invoice-flow/spec.md`
+- `specs/002-rev005-invoice-flow/plan.md`
+- `specs/002-rev005-invoice-flow/research.md`
+- `specs/002-rev005-invoice-flow/data-model.md`
+- `specs/002-rev005-invoice-flow/contracts/if-rev-008-invoice-application.md`
+- `specs/002-rev005-invoice-flow/contracts/if-rev-009-invoice-query.md`
+- `specs/002-rev005-invoice-flow/tasks.md`
+- `specs/002-rev005-invoice-flow/verification.md`
+
+### backend 相关实现
+
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/InvoiceController.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceApplyRespVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceCustomerQueryReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceInvalidateReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoicePushReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceQueryRespVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceRedInkReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/invoice/vo/InvoiceWriteBackReqVO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/invoice/InvoiceMapper.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceService.java`
+- `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/invoice/InvoiceServiceImpl.java`
+
+## 6. 剩余风险
+
+1. `SC-001 ~ SC-005` 尚缺可重复执行的专项测量脚本或统计记录。
+2. 当前 `make validate-mermaid` 输出仅覆盖仓库现有扫描范围，若后续扩展更多图表文件，仍需复核目标文件是否全部纳入。
+3. 当前仓库内尚未定位到与 `backend/sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/invoice/InvoiceDO.java` 当前模型对应的 `biz_invoice` 物理 DDL 或迁移脚本；已核查 `backend/sql`、Archive 数据库设计与 `sql/lhc_数据库设计.md`，现有同名 `biz_invoice` 更偏开票配置表，作废/红冲新增字段的物理落库仍需结合实际数据库变更链路确认。
+4. 作废/红冲当前以单笔后台入口为主，尚未覆盖批量后处理、`SYS-008` 端到端联调样本与自动化回归验证。
+
+## 7. 下一步建议
+
+1. 若继续推进一期验收，优先补 `SC-001 ~ SC-005` 的专项统计与样本口径。
+2. 若继续推进 US4，优先确认 `biz_invoice` 物理 DDL/迁移脚本来源，并补批量作废/红冲与联调样本，而不是继续重复扩展已完成的请求对象或数据承接口径。
+3. 若准备提测或评审，可直接引用本文件作为当前已完成验证、US4 二期实现范围与剩余风险摘要。
+
+## 8. 当前交付摘要
+
+### 8.1 已完成交付
+
+1. REV-005 的 US1 ~ US4 已完成正式文档、spec/planning 产物与 backend 最小实现闭环，并已补齐最小编译、文档校验、链接校验与 Mermaid 校验证据。
+2. `spec.md`、`tasks.md`、`verification.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 当前已统一到“实现闭环基本完成、量化验收证据待补”的一致状态。
+3. 当前仓库已明确可直接用于评审/提测前范围说明的结论：正常开票闭环与作废/红冲最小入口已形成正式实现范围，SC-005 实现态日志追溯矩阵已补齐。
+
+### 8.2 当前未闭环事项
+
+1. `T055`、`T060`、`T061`、`T062`、`T063` 仍未完成，分别对应运行态日志抽样、SC-001 响应时延、SC-002 申请通过率、SC-003 回写成功率、SC-004 客户侧查询/下载/推送成功率等专项统计证据。
+2. `biz_invoice` 物理 DDL / migration 来源仍未在仓库中定位，US4 的物理落库链路、批量后处理与端到端联调样本仍需继续跟踪。
+
+### 8.3 建议引用口径
+
+- 若当前需要向评审或提测说明 REV-005 状态，建议统一表述为：**REV-005 已完成 US1 ~ US4 的实现态闭环与最小校验，当前处于 Verification Pending，剩余工作主要是补 SC-001 ~ SC-005 的运行态样本与专项统计证据。**

specs/003-rev006-reminder-event-design/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: REV-006 催缴事件与通知协同设计
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-18
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation result: pass on first review.
+- No unresolved clarification markers remain.
+- Spec is ready for `/speckit.plan`; `/speckit.clarify` is optional rather than required.

specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md

@@ -0,0 +1,102 @@
+# Contract: REV-006 催缴事件与通知协同
+
+## 1. Formal Interface Allocation
+
+| Interface | Role | Direction |
+|---|---|---|
+| `IF-REV-013` | `REV-006` 催缴任务生成、任务查询、结果承接的正式业务接口 | `SYS-002` 内部正式业务接口 |
+| `IF-EXT-008` | `SYS-002` 与 `SYS-010` 的消息触达协同接口 | `SYS-002 -> SYS-010` 发送，`SYS-010 -> SYS-002` 回写 |
+
+约束：
+
+- `IF-REV-009` 继续保留给 `REV-005` 发票结果查询，不得再用于 `REV-006`。
+- `IF-REV-013` 是本 feature 新增的正式业务接口编号。
+
+## 2. IF-REV-013 Business Contract
+
+### Purpose
+
+统一承接催缴任务生成、任务状态查询和业务侧结果查看，不承担消息平台内部发送逻辑。
+
+### Request Shape
+
+| Field | Meaning | Required |
+|---|---|---|
+| `taskNo` | 催缴任务号 | 查询时是；生成时否 |
+| `custId` | 客户标识 | 是 |
+| `chargeIds` | 账单集合 | 是 |
+| `billPeriod` | 账期 | 是 |
+| `arrearsAmount` | 欠费金额 | 是 |
+| `strategyCode` | 催缴策略编码 | 是 |
+| `channelType` | 触达渠道 | 是 |
+| `triggerType` | 触发方式 | 是 |
+| `eventNo` | 业务事件号 | 生成后返回；回写承接时是 |
+
+### Response Shape
+
+| Field | Meaning |
+|---|---|
+| `taskNo` | 催缴任务号 |
+| `interfaceCode` | 固定为 `IF-REV-013` |
+| `status` | `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` |
+| `resultTime` | 最近结果时间 |
+| `failureReason` | 失败原因 |
+| `relatedDisposalRef` | 关联停复水或工单引用 |
+
+## 3. IF-EXT-008 Collaboration Contract
+
+### Outbound to SYS-010
+
+| Field | Meaning |
+|---|---|
+| `eventNo` | 业务事件号 |
+| `taskNo` | 催缴任务号 |
+| `custId` | 客户标识 |
+| `receiver` | 接收目标 |
+| `channelType` | 触达渠道 |
+| `templateCode` | 消息模板编码 |
+| `arrearsAmount` | 欠费金额 |
+| `billPeriod` | 账期 |
+| `triggerType` | 自动/人工 |
+
+### Writeback from SYS-010
+
+| Field | Meaning |
+|---|---|
+| `eventNo` | 业务事件号 |
+| `status` | `SUCCESS` / `FAIL` / `PENDING` |
+| `failureReason` | 失败原因 |
+| `resultChannel` | 实际触达渠道 |
+| `resultTime` | 结果时间 |
+
+### Manual Verification Supplement
+
+当外部结果长期未定或与业务侧核查结论不一致时，由 `SYS-002` 将任务状态补记为 `MANUAL_VERIFIED`，并保留核查人和核查说明。
+
+## 4. State Contract
+
+| State | Meaning | Allowed Source |
+|---|---|---|
+| `PENDING` | 已生成任务，等待协同结果或人工核查 | `SYS-002` |
+| `SUCCESS` | 已确认触达成功 | `SYS-010` 回写 |
+| `FAIL` | 已确认发送失败 | `SYS-010` 回写或失败确认 |
+| `MANUAL_VERIFIED` | 经过人工核查后补记为有效结果 | `SYS-002` 人工核查 |
+
+## 5. History Query Contract
+
+历史查询最小字段集必须支持：
+
+- 客户号
+- 账期
+- 催缴方式
+- 执行结果
+- 发送时间
+- 发送对象
+- 关联账单
+- 关联停复水/工单引用
+
+该查询合同用于：
+
+- 正式设计中的历史只读口径
+- 迁移验收对账
+- 后续催缴与停复水核查

specs/003-rev006-reminder-event-design/data-model.md

@@ -0,0 +1,159 @@
+# Data Model: REV-006 催缴事件与通知协同设计
+
+## 1. Reminder Candidate
+
+### Purpose
+
+表示进入催缴评估范围的欠费账单或客户对象集合，是催缴任务生成的输入对象。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `custId` | 客户标识 | 必填；关联客户主档 |
+| `chargeId` | 账单标识 | 必填；关联欠费账单 |
+| `billPeriod` | 账期 | 必填；用于催缴分组和历史查询 |
+| `arrearsAmount` | 欠费金额 | 必填；用于策略匹配 |
+| `agingBucket` | 欠费账龄分组 | 必填；用于策略筛选 |
+| `customerCategory` | 客户类别 | 必填；用于差异化催缴 |
+| `contactChannelSet` | 可用联系方式集合 | 至少存在一个有效触达渠道 |
+| `strategyCode` | 命中的催缴策略编码 | 必填；来源于策略规则 |
+
+### Relationships
+
+- 来自 `biz_charge` / `biz_charge_detail`
+- 关联客户主档与联系方式
+- 可生成一个或多个 `Reminder Task`
+
+## 2. Reminder Strategy
+
+### Purpose
+
+定义催缴对象筛选、任务分组、触达渠道和频控约束的业务规则。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `strategyCode` | 策略编码 | 唯一 |
+| `agingRule` | 账龄匹配规则 | 必填 |
+| `amountRule` | 金额匹配规则 | 必填 |
+| `customerCategoryRule` | 客户类别匹配规则 | 可为空；为空表示通用 |
+| `channelPriority` | 触达渠道优先级 | 必填；至少 1 个渠道 |
+| `dedupeWindow` | 重复触达拦截窗口 | 必填 |
+| `escalationFlag` | 是否触发后续处置关注 | 必填 |
+
+### Relationships
+
+- 一个 `Reminder Strategy` 可匹配多个 `Reminder Candidate`
+- 一个 `Reminder Strategy` 可驱动多个 `Reminder Task`
+
+## 3. Reminder Task
+
+### Purpose
+
+表示一次正式催缴执行单元，负责承接业务触发、协同下发和结果回写。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `taskNo` | 催缴任务号 | 唯一；正式业务主键 |
+| `interfaceCode` | 正式接口编号 | 固定使用 `IF-REV-013` |
+| `eventNo` | 业务事件号 | 唯一；用于与 `SYS-010` 协同 |
+| `custId` | 客户标识 | 必填 |
+| `chargeId` | 账单标识 | 必填 |
+| `strategyCode` | 策略编码 | 必填 |
+| `channelType` | 触达渠道 | 必填；短信/微信公众号/站内信等 |
+| `triggerType` | 触发方式 | 必填；自动/人工 |
+| `status` | 当前任务状态 | 必填；`PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` |
+| `sourceType` | 任务来源 | 必填；系统任务/人工补发/核查回补 |
+| `createdTime` | 创建时间 | 必填 |
+| `lastResultTime` | 最近结果时间 | 可为空；初次发送前为空 |
+
+### State Transitions
+
+| From | To | Condition |
+|---|---|---|
+| 新建 | `PENDING` | 已生成任务并发起协同 |
+| `PENDING` | `SUCCESS` | 收到成功回写 |
+| `PENDING` | `FAIL` | 收到失败回写或确认失败 |
+| `PENDING` | `MANUAL_VERIFIED` | 人工核查后确认结果 |
+| `FAIL` | `MANUAL_VERIFIED` | 人工核查补记结果 |
+
+### Relationships
+
+- 由一个 `Reminder Candidate` 和一个 `Reminder Strategy` 组合产生
+- 关联一个或多个 `Reminder Result`
+- 可关联一个 `Disposal Link`
+
+## 4. Reminder Result
+
+### Purpose
+
+表示 `SYS-010` 回传或人工核查得到的触达结果。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `eventNo` | 业务事件号 | 必填；与 `Reminder Task` 对应 |
+| `status` | 结果状态 | 必填；仅允许四态 |
+| `failureReason` | 失败原因 | `FAIL` 时必填 |
+| `resultChannel` | 实际触达渠道 | 必填 |
+| `resultTime` | 结果时间 | 必填 |
+| `verifiedBy` | 核查人 | `MANUAL_VERIFIED` 时必填 |
+| `verifiedNote` | 核查说明 | `MANUAL_VERIFIED` 时建议填写 |
+
+### Relationships
+
+- 归属于一个 `Reminder Task`
+- 结果会回写到任务状态与历史查询记录
+
+## 5. Reminder History Record
+
+### Purpose
+
+为历史查询和迁移验收提供最小保留信息集合。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `custId` | 客户标识 | 必填 |
+| `billPeriod` | 账期 | 必填 |
+| `channelType` | 催缴方式 | 必填 |
+| `messageContentRef` | 触达内容引用 | 必填；可为模板或摘要引用 |
+| `receiver` | 接收目标 | 必填；手机号/OpenID/站内信对象 |
+| `status` | 执行结果 | 必填；使用四态或历史映射值 |
+| `sendTime` | 发送时间 | 必填 |
+| `operatorSource` | 操作来源 | 必填；自动/人工/历史迁移 |
+| `relatedChargeId` | 关联账单 | 必填 |
+| `relatedDisposalRef` | 关联处置引用 | 可为空；用于停复水/工单追溯 |
+
+### Relationships
+
+- 可由 `Reminder Task` 和 `Reminder Result` 聚合生成
+- 同时承接历史催缴记录、停水记录、预存短信记录的查询口径
+
+## 6. Disposal Link
+
+### Purpose
+
+记录催缴结果与停水、复水、工单或人工处置之间的追溯关系。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `eventNo` | 关联业务事件号 | 必填 |
+| `disposalType` | 处置类型 | 必填；停水/复水/工单/人工跟进 |
+| `triggerCondition` | 触发条件摘要 | 必填 |
+| `disposalRefNo` | 下游处置引用号 | 可为空；未创建时为空 |
+| `disposalStatus` | 下游处置状态 | 可为空；仅作追溯，不定义内部流程 |
+| `linkedTime` | 建立关联时间 | 必填 |
+
+### Relationships
+
+- 一个 `Reminder Task` 最多关联一个当前生效的 `Disposal Link`
+- 不替代下游业务对象，只做引用和追溯

specs/003-rev006-reminder-event-design/plan.md

@@ -0,0 +1,109 @@
+# Implementation Plan: REV-006 催缴事件与通知协同设计
+
+**Branch**: `003-rev006-reminder-event-design` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/spec.md)
+**Input**: Feature specification from `/specs/003-rev006-reminder-event-design/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+本 feature 用于补齐 `REV-006` 在正式文档体系中的设计闭环，重点收口催缴对象生成、催缴任务触发、`SYS-010` 消息协同结果回写、停复水联动边界以及历史查询最小保留集。实施方式以修订既有主文档和治理台账为主，不进入 backend 代码实现；同时将现有接口冲突纠正为 `REV-006` 使用新的独立正式接口编号，发票查询继续保留 `IF-REV-009`。
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace this section with the real project context.
+  For this repository, prefer documenting document-system context rather than
+  inventing software implementation context.
+-->
+
+**Primary Work Product**: Markdown 设计文档、接口/数据库专题文档、管理台账文档
+**Source of Truth Documents**:
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/04_Writing_Guide.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/AGENTS.md`
+**Reference Sources**:
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/guides/BACKEND_CURRENT_STATUS.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/guides/BACKEND_TABLE_MAPPING.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+ - `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/04_Appendix/Archive/01_Requirements/`
+**Validation Commands**:
+ - `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`
+ - `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`
+ - `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`
+ - `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+ - `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md`
+ - `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md`
+ - `make check-links`
+**Target Scope**:
+ - `12_REV_Detailed.md` 中 `REV-006` 正文、流程、规则、落地边界
+ - `03_Interface_Design.md` 中 `REV-006` 与 `SYS-010` 的接口编号、接口定义、时序、映射表、异常码、幂等策略
+ - `01_Database_Design.md` 中催缴/停复水/预存短信历史只读口径与在线主模型承接边界
+ - `15_SYS002_Requirement_Breakdown.md` 中实现评估和 Story/Task 建议
+ - `01_Project_Progress.md`、`03_Task_Checklist.md` 的治理回写
+**Project Type**: 文档治理仓库
+**Constraints**:
+ - 不新增平行正式主稿，所有正式内容回写既有主文档
+ - 不臆造 backend 已实现事实，只能写“已实现 / 部分实现 / 文档先行 / 历史只读”
+ - 仓库内引用保持相对路径
+ - 停复水只定义联动边界，不展开内部处置流程
+ - `REV-006` 必须使用独立正式接口编号，不再复用 `IF-REV-009`
+ - 催缴结果状态固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`
+**Scale/Scope**: 跨文档专题收口，涉及详细设计、接口设计、数据库设计与治理台账四类文档
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：改动落点限定为 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 与治理台账，不新增平行正式稿。
+- [x] **范围基线已确认**：`REV-006` 已存在于 `03_Summary_Design.md`、`12_REV_Detailed.md` 和 `15_SYS002_Requirement_Breakdown.md`，本轮仅补齐既有范围内的设计与接口口径，不引入超范围新模块。
+- [x] **Archive 使用方式合规**：Archive 仅用于核对旧“催缴记录/停水记录/预存短信”来源与历史只读口径，不直接作为正式结论输出。
+- [x] **一致性影响已列出**：受影响项包括 `REV-006` 接口编号、结果状态术语、催缴/停复水边界、历史只读查询口径、时序图与映射表。
+- [x] **校验与台账动作已规划**：已规划单文件校验、链接校验，并要求同步更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Optional: document entities/traceability objects
+├── quickstart.md        # Optional: validation or review quickstart
+├── contracts/           # Optional: interface or section-level artifacts
+└── tasks.md             # Phase 2 output (/speckit.tasks command)
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/
+├── 01_Overview/
+├── 02_Detailed_Design/
+├── 03_Technical_Design/
+└── 04_Appendix/Archive/
+
+README.md
+AGENTS.md
+.specify/templates/
+```
+
+**Structure Decision**:
+ - 更新 `docs/design/02_Detailed_Design/12_REV_Detailed.md`：补齐 `REV-006` 详细设计正文与落地边界。
+ - 更新 `docs/design/03_Technical_Design/03_Interface_Design.md`：修正接口编号冲突，补齐 `REV-006` 正式接口、协同时序、异常码和幂等策略。
+ - 更新 `docs/design/03_Technical_Design/01_Database_Design.md`：明确在线承接与历史只读查询口径，不把旧菜单机械映射为新表。
+ - 更新 `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`：同步实现评估、TAPD/Speckit 建议和后续任务入口。
+ - 更新 `docs/design/00_Management/01_Project_Progress.md` 与 `docs/design/00_Management/03_Task_Checklist.md`：完成治理闭环。
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| 无 | - | - |

specs/003-rev006-reminder-event-design/quickstart.md

@@ -0,0 +1,57 @@
+# Quickstart: REV-006 催缴事件与通知协同设计
+
+## 目标
+
+本 quickstart 用于指导评审者和文档维护者快速完成 `REV-006` 设计补齐的检查，不涉及 backend 实施。
+
+## 步骤 1：阅读规格与研究结论
+
+1. 阅读 `spec.md`，确认三项澄清已固定：
+   - 停复水仅定义联动边界
+   - `REV-006` 使用独立接口编号 `IF-REV-013`
+   - 结果状态固定为四态
+2. 阅读 `research.md`，确认所有关键设计决策已有依据和备选方案说明。
+
+## 步骤 2：执行文档改动时的目标落点
+
+1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐 `REV-006`：
+   - 任务生成规则
+   - 结果回写规则
+   - 停复水联动边界
+   - 历史查询最小保留集
+2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`：
+   - 新增或替换 `IF-REV-013`
+   - 保留 `IF-EXT-008`
+   - 删除 `REV-006` 对 `IF-REV-009` 的错误引用
+3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`：
+   - 明确在线主模型和历史只读查询口径
+4. 在治理台账中回写：
+   - `01_Project_Progress.md`
+   - `03_Task_Checklist.md`
+
+## 步骤 3：建议校验命令
+
+```bash
+make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md
+make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md
+make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md
+make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
+make validate-file FILE=docs/design/00_Management/01_Project_Progress.md
+make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md
+make check-links
+```
+
+## 步骤 4：验收检查点
+
+- `REV-006` 不再复用 `IF-REV-009`
+- 正式文档中统一使用四态结果集
+- 停复水只写联动边界，不扩写内部流程
+- 历史“催缴记录 / 停水记录 / 预存短信”不被误写成新在线主表
+- 台账和正式文档同步更新
+
+## 步骤 5：本轮实现摘要
+
+- 已完成 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 的正式文档回写。
+- `REV-006` 的正式业务接口编号已固定为 `IF-REV-013`，`IF-REV-009` 继续保留给 `REV-005` 发票结果查询。
+- 催缴结果已统一为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态；数据库与历史查询口径同步收口。
+- 已执行并通过全部单文件校验与 `make check-links`。

specs/003-rev006-reminder-event-design/research.md

@@ -0,0 +1,58 @@
+# Phase 0 Research: REV-006 催缴事件与通知协同设计
+
+## 决策 1：`REV-006` 使用新的独立正式接口编号
+
+- **Decision**: `REV-006` 使用新的独立正式接口编号 `IF-REV-013` 作为“催缴任务生成与结果查询/回写承接”的正式业务接口编号；`IF-REV-009` 保留给 `REV-005` 发票结果查询。
+- **Rationale**:
+  - 当前 `03_Interface_Design.md` 已明确 `IF-REV-009` 属于 `REV-005` 发票结果查询，继续复用会造成接口总表、异常码、幂等策略和时序图冲突。
+  - 现有 `IF-REV-*` 编号已经覆盖到 `IF-REV-012`，顺延 `IF-REV-013` 是最小改动且最不易误解的做法。
+  - 该决策能直接消除 `12_REV_Detailed.md` 中 `REV-006` 与接口主文档的冲突口径。
+- **Alternatives considered**:
+  - 继续复用 `IF-REV-009`：被否决，因为与发票查询主口径冲突。
+  - 暂不落编号，只写业务能力：被否决，因为会推迟核心冲突到实施阶段。
+  - 改用 `IF-EXT-*`：被否决，因为 `REV-006` 的业务接口主责仍属于 `SYS-002`，`IF-EXT-008` 只适用于与 `SYS-010` 的外部协同。
+
+## 决策 2：催缴结果状态固定为四态
+
+- **Decision**: `REV-006` 正式状态集固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。
+- **Rationale**:
+  - 四态足以覆盖“待回写/待核查”“成功触达”“失败”“人工核查确认”四类评审和实施必需场景。
+  - 过少状态会导致补偿与人工核查无法落地；过多状态会在当前未实现阶段引入不必要的细粒度设计。
+  - 四态同时便于后续接口、数据库和台账统一。
+- **Alternatives considered**:
+  - 两态（成功/失败）：无法表达未回写和人工核查状态。
+  - 三态（待处理/成功/失败）：无法区分人工核查后的确认结果。
+  - 更细状态（已送达/已阅读/已补发）：当前阶段超出设计收口所需。
+
+## 决策 3：停复水仅定义联动边界，不展开内部流程
+
+- **Decision**: 本 feature 仅定义催缴结果与停复水之间的联动边界、触发条件、查询字段和追溯关系，不展开停复水内部处置流程、审批节点或现场执行细节。
+- **Rationale**:
+  - 停复水属于后续业务处置链，深入展开会把当前专题扩展到工单/现场作业子系统。
+  - 当前 `REV-006` 的首要目标是把催缴闭环范围和责任边界收口，而不是设计全部后置处置流程。
+  - 这样既能满足历史查询和审计追溯，又不破坏范围控制。
+- **Alternatives considered**:
+  - 把停复水完整流程纳入 `REV-006`：被否决，因为会扩大到非本轮范围。
+  - 完全不写停复水联动：被否决，因为会留下历史查询和后续处置链断点。
+
+## 决策 4：历史“催缴记录/停水记录/预存短信”按历史只读口径承接
+
+- **Decision**: 旧系统“催缴记录、停水记录、预存短信记录”继续按历史只读查询对象承接，不新增同名在线主表；在线主模型以 `biz_charge`、操作留痕和消息协同结果为主。
+- **Rationale**:
+  - `01_Database_Design.md` 已对这些对象给出“历史只读保留”口径，且当前 backend 未见明确独立表族。
+  - 直接新增同名新表会违反“不得臆造已实现事实”和“单一真源”的原则。
+  - 历史只读策略既能满足迁移验收，也不影响后续按业务链逐步演进。
+- **Alternatives considered**:
+  - 为每个旧菜单新增在线主表：被否决，因为没有实现证据且破坏当前主模型。
+  - 完全不保留历史查询口径：被否决，因为不满足迁移验收和追溯要求。
+
+## 决策 5：`REV-006` 与 `SYS-010` 的职责分界
+
+- **Decision**: `SYS-002/REV-006` 负责催缴对象筛选、任务分组、业务事件生成、状态承接、历史查询和处置关联；`SYS-010` 负责短信、微信公众号、站内信等触达执行与结果回传。
+- **Rationale**:
+  - 该分界与 `03_Interface_Design.md` 中跨系统协同表一致。
+  - 业务筛选和状态归属留在 `SYS-002`，能保证催缴逻辑与账单口径一致。
+  - 触达能力放在 `SYS-010`，避免 `REV-006` 越权扩展到消息平台实现。
+- **Alternatives considered**:
+  - 让 `SYS-010` 负责催缴对象筛选：被否决，因为会削弱营收主系统对账单规则的控制。
+  - 让 `SYS-002` 直接承担全部消息发送：被否决，因为与既有系统边界不一致。

specs/003-rev006-reminder-event-design/spec.md

@@ -0,0 +1,141 @@
+# Feature Specification: REV-006 催缴事件与通知协同设计
+
+**Feature Branch**: `003-rev006-reminder-event-design`
+**Created**: 2026-03-18
+**Status**: Draft
+**Input**: User description: "为 REV-006 催缴与通知补齐 spec-kit 规格，明确催缴任务生成、消息协同结果回写、停复水联动和历史查询边界"
+
+## Document Scope & Sources *(mandatory)*
+
+- **Target documents**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/design/00_Management/01_Project_Progress.md`
+  - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/design/00_Management/04_Writing_Guide.md`
+  - `AGENTS.md`
+- **Reference sources**:
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/guides/BACKEND_CURRENT_STATUS.md`
+  - `docs/guides/BACKEND_TABLE_MAPPING.md`
+  - `docs/design/04_Appendix/Archive/01_Requirements/`
+  - `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+- **Scope decision**: In scope. This feature is limited to补齐 `REV-006` 的正式设计口径、接口边界、数据承接边界和后续任务拆解依据；不扩展到 `SYS-010` 的内部实现，不重写其他 `REV-*` 模块，不新建平行正式主稿。
+
+## Clarifications
+
+### Session 2026-03-18
+
+- Q: 停水/复水联动在本 feature 中应细化到什么程度？ → A: 只定义催缴与停复水的联动边界、触发条件、追溯关系，不展开停复水内部流程。
+- Q: `REV-006` 是否应继续复用 `IF-REV-009`？ → A: 为 `REV-006` 新增独立正式接口编号，发票查询继续保留 `IF-REV-009`。
+- Q: `REV-006` 的催缴结果应采用哪组正式状态？ → A: 采用 4 个正式状态：`PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 定义催缴闭环范围 (Priority: P1)
+
+作为文档维护者，我需要把 `REV-006` 的催缴生成、消息触达、结果回写和后续处置边界写清楚，使评审者能明确该模块到底负责什么、不负责什么，并据此开展后续设计与研发；其中停复水仅定义联动边界，不展开内部处置流程。
+
+**Why this priority**: `REV-006` 当前在仓库内被判定为“未见实现”，如果范围和边界不先收敛，后续 `plan/tasks` 会直接失焦。
+
+**Independent Test**: 单独评审 `12_REV_Detailed.md` 中 `REV-006` 章节，应能独立回答“催缴任务如何产生、结果如何回写、停复水与工单如何衔接、哪些内容不在本轮范围内”。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前 `REV-006` 只有概要级描述， **When** 评审者阅读更新后的详细设计， **Then** 能明确催缴对象来源、任务生成维度、自动与人工催缴边界以及停复水联动触发入口。
+2. **Given** 后续需要把 `REV-006` 拆成开发任务， **When** 维护者依据该规格开展计划拆解， **Then** 不需要再回到 Archive 才能判断本轮范围和排除项。
+
+---
+
+### User Story 2 - 统一消息协同与结果回写口径 (Priority: P2)
+
+作为接口与系统集成评审者，我需要看到 `SYS-002` 与 `SYS-010` 之间关于催缴事件、触达结果、失败重试和状态回写的统一口径，并为 `REV-006` 使用独立正式接口编号和明确的 4 态结果集，以便避免与发票查询接口混淆。
+
+**Why this priority**: `REV-006` 的业务价值高度依赖消息协同结果，若回写与状态语义不清，会直接影响催缴结果查询、后续催办和停复水判断。
+
+**Independent Test**: 单独评审接口设计相关章节，应能独立确认触发方、回写方、关键状态、失败语义和查询/补偿责任分界。
+
+**Acceptance Scenarios**:
+
+1. **Given** `SYS-002` 需要向 `SYS-010` 发送催缴事件， **When** 评审者查看规格， **Then** 能明确独立接口编号、事件生成条件、发送前置校验和最小回写字段集。
+2. **Given** 消息发送失败或结果迟迟未回写， **When** 评审者查看规格， **Then** 能明确 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 的适用边界，以及重试/补偿归属和人工核查入口。
+
+---
+
+### User Story 3 - 明确历史查询与停复水联动边界 (Priority: P3)
+
+作为后续实施和验收人员，我需要知道催缴记录、预存短信、停水记录等历史口径如何在当前体系中承接，避免为了追求“完整”而无依据地新增平行模型。
+
+**Why this priority**: 旧系统相关对象较多，如果不先定义“最小保留集”和联动边界，后续很容易把历史菜单直接平移成新模块。
+
+**Independent Test**: 单独检查规格中的迁移/历史查询要求，应能判断哪些历史信息必须可查、哪些仅保留映射说明、哪些应转交工单或外部协同模块承接。
+
+**Acceptance Scenarios**:
+
+1. **Given** 需要追查某次催缴或停水处置历史， **When** 评审者阅读规格， **Then** 能明确最少需要保留的查询字段与关联对象。
+2. **Given** Archive 中存在旧“停水记录”“预存短信”等入口， **When** 评审者执行范围判断， **Then** 能明确这些内容在新体系中属于催缴协同能力还是外部协同能力，而不是新增独立正式模块。
+
+---
+
+### Edge Cases
+
+- 当欠费账单满足多条催缴策略时，如何确定任务分组、优先级和避免重复触达？
+- 当 `SYS-010` 返回失败、超时或迟迟不回写时，如何稳定映射到 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`，而不再扩展更多细分状态？
+- 当同一客户既存在催缴事件又进入停水/复水处置时，如何保证催缴记录与工单处置链路可追溯但不互相覆盖状态，且本 feature 不承担停复水内部流程定义？
+- 当旧系统存在催缴记录、停水记录、预存短信历史数据，但当前后端未见独立表族时，如何定义最小保留查询口径而不臆造新模型？
+- 当 `REV-006` 改用独立正式接口编号后，如何保证 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 和管理台账同步更新且不保留旧冲突口径？
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST identify `REV-006` 的精确目标文档，并说明每份文档承担的职责。
+- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 作为本 feature 的主约束来源。
+- **FR-003**: Specification MUST record that the feature is in scope only for `REV-006` 的设计与任务拆解准备，不扩展到 `SYS-010` 内部实现或其他 `REV-*` 模块重写。
+- **FR-004**: Specification MUST preserve the single-source-of-truth model and MUST NOT introduce a new parallel formal design document for reminder/notice capability.
+- **FR-005**: Specification MUST define reminder object sources based on overdue billing data and customer attributes, including at minimum arrears status, amount, aging, customer category, and applicable reminder strategy dimensions.
+- **FR-006**: Specification MUST define the business flow for reminder generation, task grouping, message dispatch request, result writeback, and follow-up handling.
+- **FR-007**: Specification MUST distinguish automatic reminder, manual reminder, and subsequent disposal linkage, including what belongs to `SYS-002`, what is coordinated by `SYS-010`, and what is handled through downstream disposal processes.
+- **FR-008**: Specification MUST define exactly four formal result states for reminder collaboration: `PENDING`, `SUCCESS`, `FAIL`, and `MANUAL_VERIFIED`, with unambiguous transition intent and usage boundaries.
+- **FR-008a**: Specification MUST require a dedicated formal interface identifier for `REV-006` reminder task generation and result handling, and MUST prohibit continued reuse of `IF-REV-009` for this feature because `IF-REV-009` remains reserved for invoice result query.
+- **FR-009**: Specification MUST define the minimum historical query retention scope for reminder records, stop-water related records, and prepaid-balance reminder events, including the fields needed to trace content, channel, target, time, result, operator/source, and related billing object.
+- **FR-010**: Specification MUST define how stop-water and recovery handling relate to reminder outcomes without collapsing them into the same business object, and MUST limit this feature to linkage conditions and traceability rather than internal disposal workflow details.
+- **FR-011**: Specification MUST state the exclusions for this feature, including that historical menu names and Archive structures are reference material only and not direct targets for formal document reconstruction.
+- **FR-012**: Specification MUST capture cross-document consistency impacts for interfaces, data retention, terminology, result states, and downstream ledger updates.
+- **FR-013**: Specification MUST list the validation actions required after document updates, including single-file validation for impacted docs and link consistency checks.
+- **FR-014**: Specification MUST state that formal document changes under this feature require synchronized updates to `01_Project_Progress.md` and `03_Task_Checklist.md`.
+
+### Assumptions
+
+- 本 feature 以正式文档补齐和后续立项准备为目标，默认不在本轮直接修改 backend 代码。
+- `SYS-010` 继续作为消息发送能力提供方，`SYS-002` 负责业务事件生成、状态承接和历史查询口径。
+- `REV-006` 将在正式文档中使用新的独立接口编号；现有 `IF-REV-009` 继续保留给发票结果查询，不再混用。
+- 催缴结果状态默认收敛为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED` 四态，本轮不再细分为“已送达”“已阅读”“已补发”等更细粒度状态。
+- 旧系统“催缴记录”“预存短信”“停水记录”等历史入口默认先按查询能力和映射口径承接，不默认要求新建同名独立主表。
+- 停水/复水属于后续业务处置链的一部分，本 feature 只要求定义与催缴结果的联动边界、触发条件和追溯关系，不展开其内部节点、审批或执行流程。
+
+### Key Entities *(include if feature involves data)*
+
+- **Reminder Candidate**: 满足欠费、账龄、客户类别等条件、可进入催缴流程的账单或客户对象集合。
+- **Reminder Strategy**: 决定催缴触发条件、分组规则、触达渠道和优先级的业务规则集。
+- **Reminder Task**: 一次可追溯的催缴执行单元，包含催缴对象、触达渠道、生成来源、执行状态和后续处置指向。
+- **Reminder Result**: 由消息协同或人工核查产生的结果记录，反映发送状态、失败原因、回写时间和后续动作建议。
+- **Reminder History Record**: 支撑历史查询的最小记录集合，至少覆盖触达内容、目标对象、渠道、发送时间、结果状态、关联账单和操作来源。
+- **Disposal Link**: 催缴结果与停水、复水、工单或人工处置之间的关联关系，用于追溯后续业务动作，但不替代下游业务对象。
+- **Ledger Update**: 当 `REV-006` 正式文档完成补齐后，需要同步回写到项目进度和任务清单的治理记录。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 评审者可在 5 分钟内从规格中定位 `REV-006` 的目标文档、主约束来源、范围边界和排除项。
+- **SC-002**: 规格中覆盖至少 3 类独立可评审场景：催缴任务生成、消息结果回写、历史查询/停复水联动。
+- **SC-003**: `REV-006` 的状态语义、协同边界和历史查询最小保留集在规格中均有明确表述，且不存在未解析的 `[NEEDS CLARIFICATION]` 标记。
+- **SC-004**: 后续执行 `/speckit.plan` 时，规划者无需新增范围澄清即可把工作拆分为文档对齐、接口补齐、数据口径补齐和台账更新四类任务。
+- **SC-005**: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查而无需二次猜测。

specs/003-rev006-reminder-event-design/tasks.md

@@ -0,0 +1,187 @@
+# Tasks: REV-006 催缴事件与通知协同设计
+
+**Input**: Design documents from `/specs/003-rev006-reminder-event-design/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
+
+**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks.
+
+**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g. [US1], [US2], [US3])
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/`
+- Governance documents: `docs/design/00_Management/`
+- Archive references: `docs/design/04_Appendix/Archive/`
+- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/`
+
+## Phase 1: Scope & Source Confirmation (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set and impact boundary before editing.
+
+- [X] T001 Confirm target documents and exact `REV-006` touchpoints in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/spec.md`
+- [X] T002 Confirm governing source-of-truth and allowed reference sources in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/plan.md`
+- [X] T003 [P] Record final scope judgment for `REV-006` and exclusions in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/research.md`
+- [X] T004 [P] Identify cross-document impacts for `IF-REV-013`、四态结果集、停复水联动边界和历史只读口径 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md`
+
+---
+
+## Phase 2: Foundational Alignment (Blocking Prerequisites)
+
+**Purpose**: Prepare the cross-document baseline that all user stories depend on.
+
+- [X] T005 Consolidate `REV-006` decisions, entities, and contract fields from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/research.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/data-model.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/contracts/rev006-interface-contract.md`
+- [X] T006 [P] Cross-check current conflicting references to `IF-REV-009` and `REV-006` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T007 [P] Cross-check historical-only retention rules for 催缴记录/停水记录/预存短信 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+- [X] T008 Confirm ledger update expectations for this feature in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`
+
+---
+
+## Phase 3: User Story 1 - 定义催缴闭环范围 (Priority: P1) 🎯 MVP
+
+**Goal**: 让 `12_REV_Detailed.md` 中的 `REV-006` 章节具备完整的催缴对象生成、任务分组、停复水联动边界和落地边界说明。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-006` 章节，应能明确催缴对象来源、策略维度、自动/人工触发边界、停复水只做联动边界、不展开内部流程。
+
+### Implementation for User Story 1
+
+- [X] T009 [US1] Update `REV-006` 功能说明、业务流程、关键规则和落地边界 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T010 [P] [US1] Add `Reminder Candidate`、`Reminder Strategy`、`Reminder Task`、`Disposal Link` 对应的数据与规则摘要 to `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T011 [P] [US1] Sync `REV-006` implementation assessment and Story notes in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T012 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result
+- [X] T013 [US1] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture result
+
+**Checkpoint**: User Story 1 is reviewable and confirms the `REV-006` business boundary without depending on interface redesign.
+
+---
+
+## Phase 4: User Story 2 - 统一消息协同与结果回写口径 (Priority: P2)
+
+**Goal**: 在接口主文档中为 `REV-006` 建立独立正式接口编号、四态结果集、`SYS-002 ↔ SYS-010` 协同字段和异常/幂等规则。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`，应能确认 `IF-REV-013` 的职责、`IF-EXT-008` 的协同边界、四态状态语义以及不再复用 `IF-REV-009`。
+
+### Implementation for User Story 2
+
+- [X] T014 [US2] Replace `REV-006` 对 `IF-REV-009` 的错误引用 with `IF-REV-013` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T015 [US2] Add `IF-REV-013` formal interface definition, request/response shape, and responsibility boundary in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T016 [P] [US2] Update `IF-EXT-008` collaboration contract, state semantics, idempotency, exception codes, and timing diagrams in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T017 [P] [US2] Sync `REV-006` interface mapping, interface numbering, and state terminology in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T018 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture result
+- [X] T019 [US2] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result after interface sync
+
+**Checkpoint**: User Story 2 is reviewable and fully expresses the `REV-006` interface and integration contract independently.
+
+---
+
+## Phase 5: User Story 3 - 明确历史查询与停复水联动边界 (Priority: P3)
+
+**Goal**: 在数据库和治理文档中收口历史只读查询口径、迁移验收字段和停复水联动追溯边界。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md` 与治理台账，应能确认旧“催缴记录/停水记录/预存短信”不被误写为新在线主表，同时查询字段和对账口径完整。
+
+### Implementation for User Story 3
+
+- [X] T020 [US3] Update historical read-only retention and online-model boundary for 催缴记录/停水记录/预存短信 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T021 [P] [US3] Add minimum query fields, traceability expectations, and disposal-link wording for `REV-006` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T022 [P] [US3] Sync feature completion, implementation status, and follow-up recommendations in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T023 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` with the `REV-006` design closure milestone
+- [X] T024 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` with the `REV-006` tracked-task closure status
+- [X] T025 [US3] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture result
+- [X] T026 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture result
+
+**Checkpoint**: User Story 3 is reviewable and confirms the historical-query and ledger-governance closure independently.
+
+---
+
+## Final Phase: Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [X] T027 [P] Re-check source-of-truth alignment across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T028 [P] Run `make check-links` after all document changes and capture result
+- [X] T029 Prepare final summary with modified files, validation results, remaining risks, and next-step suggestions in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/003-rev006-reminder-event-design/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1: Scope & Source Confirmation**: No dependencies; MUST finish before content edits
+- **Phase 2: Foundational Alignment**: Depends on Phase 1; MUST finish before user story work
+- **Phase 3: User Story 1**: Depends on Phase 2
+- **Phase 4: User Story 2**: Depends on Phase 2 and should follow User Story 1 because interface mapping must align with the finalized `REV-006` business scope
+- **Phase 5: User Story 3**: Depends on Phase 2 and should follow User Story 2 because database and ledger wording must use the finalized interface numbering and state terms
+- **Final Phase**: Depends on all selected user stories being complete
+
+### Within Each User Story
+
+- Update target documents before syncing supporting or governance documents
+- Complete content edits before validation
+- Complete validation before ledger updates are marked done
+- Complete ledger sync before final summary
+
+### User Story Completion Order
+
+`US1 -> US2 -> US3`
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel after source confirmation
+- `T006` and `T007` can run in parallel during foundational alignment
+- In `US1`, `T010` and `T011` can run in parallel after `T009`
+- In `US2`, `T016` and `T017` can run in parallel after `T014` and `T015`
+- In `US3`, `T021` and `T022` can run in parallel after `T020`
+- `T027` and `T028` can run in parallel during final closure
+
+## Parallel Execution Examples
+
+### User Story 1
+
+```text
+Run in parallel after T009:
+- T010 [P] [US1] Add data/rule summaries in 12_REV_Detailed.md
+- T011 [P] [US1] Sync implementation assessment in 15_SYS002_Requirement_Breakdown.md
+```
+
+### User Story 2
+
+```text
+Run in parallel after T014 and T015:
+- T016 [P] [US2] Update IF-EXT-008 contract, states, exceptions, diagrams
+- T017 [P] [US2] Sync interface mapping back into 12_REV_Detailed.md
+```
+
+### User Story 3
+
+```text
+Run in parallel after T020:
+- T021 [P] [US3] Add query-field and traceability wording in 01_Database_Design.md
+- T022 [P] [US3] Sync feature completion notes in 15_SYS002_Requirement_Breakdown.md
+```
+
+## Implementation Strategy
+
+### MVP First
+
+先完成 `US1`，因为 `12_REV_Detailed.md` 的业务边界是所有后续接口和数据库收口的前提。只要 `US1` 完成并通过校验，就可以先交付一版可评审的 `REV-006` 业务范围说明。
+
+### Incremental Delivery
+
+1. 完成 `US1`，锁定业务边界和排除项
+2. 完成 `US2`，锁定接口编号、协同边界和四态结果集
+3. 完成 `US3`，锁定历史只读口径、迁移验收字段和治理台账闭环
+4. 最后统一执行全局一致性检查和链接校验
+
+### Notes
+
+- 每个 story 都可以独立评审，不要求一次性改完全部文档
+- 所有任务都必须回写既有正式文档，不能新建平行正式稿
+- Archive 只作为核对来源，不直接替代主文档
+- 验证和台账同步不是可选项

specs/004-rev007-revenue-statistics-design/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: REV-007 营收统计查询设计
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-18
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 当前规格基于现有正式主文档、治理台账和检索结论生成；`REV-007` 默认按“设计先行、实现待立项”处理。

specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md

@@ -0,0 +1,68 @@
+# Contract: REV-007 营收统计查询设计
+
+## 1. Formal Interface Allocation
+
+| Interface | Role | Direction |
+|---|---|---|
+| `IF-REV-010` | `REV-007` 统计主题查询、指标汇总和结果导出边界的正式业务接口 | `SYS-002` 内部正式业务接口 |
+
+约束：
+
+- `IF-REV-010` 保持为 `REV-007` 的正式接口编号，不新增新的统计接口编号。
+- 本接口只承接经营统计查询，不扩展到 BI 专题、预测分析或独立数据仓库查询。
+
+## 2. Statistics Themes
+
+`IF-REV-010` 本轮至少覆盖以下主题：
+
+- 营收汇总
+- 收费与实收统计
+- 欠费规模与账龄统计
+- 客户结构统计
+- 渠道交易统计
+- 抄表完成率统计
+- 业务概览类工单/办理量摘要（仅限营收业务相关概览）
+
+## 3. Request Contract
+
+| Field | Meaning | Required |
+|---|---|---|
+| `themeCode` | 统计主题编码 | 是 |
+| `dateFrom` | 开始日期 | 是 |
+| `dateTo` | 结束日期 | 是 |
+| `billPeriod` | 账期 | 否 |
+| `deptId` | 营业所/部门 | 否 |
+| `regionCode` | 片区/区域编码 | 否 |
+| `customerCategory` | 客户类别 | 否 |
+| `channelCode` | 收费/交易渠道 | 否 |
+| `statusSet` | 状态集合 | 否 |
+| `groupBy` | 分组维度集合 | 否 |
+| `exportFlag` | 是否导出 | 否 |
+
+## 4. Response Contract
+
+| Field | Meaning |
+|---|---|
+| `themeCode` | 统计主题编码 |
+| `themeName` | 统计主题名称 |
+| `dimensionSummary` | 查询维度摘要 |
+| `indicatorList` | 指标结果集合 |
+| `indicatorList[].indicatorCode` | 指标编码 |
+| `indicatorList[].indicatorName` | 指标名称 |
+| `indicatorList[].indicatorValue` | 指标值 |
+| `indicatorList[].unit` | 单位 |
+| `groupRows` | 分组结果集合 |
+| `exportAllowed` | 是否允许导出 |
+| `msg` | 结果说明 |
+
+## 5. Data Boundary Contract
+
+- 统计结果基于现有在线业务主数据、视图或汇总口径承接。
+- 没有明确实现证据的独立统计表、专题报表表或离线数仓对象不得写成既成事实。
+- 当历史查询口径参与对账或对比时，只能作为补充来源，不替代在线主数据统计口径。
+
+## 6. Permission and Export Contract
+
+- 查询结果必须受现有数据权限控制。
+- 导出属于查询扩展能力，必须在权限允许范围内执行。
+- 本轮只定义“是否允许导出”和导出边界，不展开导出实现细节。

specs/004-rev007-revenue-statistics-design/data-model.md

@@ -0,0 +1,135 @@
+# Data Model: REV-007 营收统计查询设计
+
+## 1. Statistics Theme
+
+### Purpose
+
+定义 `REV-007` 支持的统计主题，是统计查询的一级分类。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `themeCode` | 统计主题编码 | 唯一 |
+| `themeName` | 统计主题名称 | 必填 |
+| `scopeDescription` | 范围说明 | 必填；说明包含与排除项 |
+| `indicatorSet` | 指标集合 | 至少 1 个核心指标 |
+| `dimensionSet` | 维度集合 | 至少 1 个查询维度 |
+| `exportAllowed` | 是否允许导出 | 必填 |
+
+### Relationships
+
+- 一个 `Statistics Theme` 包含多个 `Statistics Indicator`
+- 一个 `Statistics Theme` 可复用多个 `Statistics Dimension`
+- 一个 `Statistics Theme` 由一个 `Statistics Query Contract` 承接
+
+## 2. Statistics Dimension
+
+### Purpose
+
+定义统计查询的筛选维度和分组维度。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `dimensionCode` | 维度编码 | 唯一 |
+| `dimensionName` | 维度名称 | 必填 |
+| `dimensionType` | 维度类型 | 必填；时间/组织/客户/渠道/状态等 |
+| `filterMode` | 查询方式 | 必填；范围/枚举/模糊/精确 |
+| `groupable` | 是否支持分组 | 必填 |
+| `sourceFieldRef` | 来源字段引用 | 必填；来源表或视图字段 |
+
+### Relationships
+
+- 可被多个 `Statistics Theme` 复用
+- 可映射到一个或多个 `Aggregation Source`
+
+## 3. Statistics Indicator
+
+### Purpose
+
+定义统计结果中返回的核心业务指标。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `indicatorCode` | 指标编码 | 唯一 |
+| `indicatorName` | 指标名称 | 必填 |
+| `indicatorMeaning` | 指标含义 | 必填；避免同名不同义 |
+| `unit` | 单位 | 可为空；金额/笔数/户数/百分比等 |
+| `aggregationRule` | 聚合规则 | 必填；求和/计数/占比/完成率 |
+| `sourceMetricRef` | 来源指标引用 | 必填 |
+
+### Relationships
+
+- 归属于一个或多个 `Statistics Theme`
+- 依赖一个或多个 `Aggregation Source`
+
+## 4. Statistics Query Contract
+
+### Purpose
+
+描述 `IF-REV-010` 的输入条件、输出摘要、权限控制和导出边界。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `interfaceCode` | 接口编号 | 固定为 `IF-REV-010` |
+| `themeCode` | 统计主题编码 | 必填 |
+| `queryConditionSet` | 查询条件集合 | 必填 |
+| `resultIndicatorSet` | 输出指标集合 | 必填 |
+| `permissionScope` | 权限范围 | 必填；数据权限/导出权限 |
+| `exportConstraint` | 导出约束 | 必填 |
+
+### Relationships
+
+- 一个 `Statistics Query Contract` 服务一个 `Statistics Theme`
+- 引用多个 `Statistics Dimension` 和 `Statistics Indicator`
+
+## 5. Aggregation Source
+
+### Purpose
+
+表示统计结果依赖的在线业务数据来源、视图或汇总口径。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `sourceCode` | 来源编码 | 唯一 |
+| `sourceName` | 来源名称 | 必填 |
+| `sourceType` | 来源类型 | 必填；在线表/视图/汇总口径 |
+| `primaryObjects` | 主数据对象 | 必填 |
+| `retentionBoundary` | 承接口径边界 | 必填；说明是否仅逻辑口径 |
+| `implementationStatus` | 实现状态说明 | 必填；不得夸大为已存在独立表 |
+
+### Relationships
+
+- 支撑多个 `Statistics Indicator`
+- 可映射到多个 `Statistics Dimension`
+
+## 6. Statistics Governance Record
+
+### Purpose
+
+用于在治理台账中记录 `REV-007` 的设计状态、实现评估和后续建议。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `requirementCode` | 对应需求编号 | 固定为 `SYS002-REQ-012` |
+| `featureName` | Speckit feature 名称 | 必填 |
+| `designStatus` | 设计状态 | 必填；设计收口中/已收口 |
+| `implementationStatus` | 实现评估 | 必填；当前为未见实现 |
+| `nextAction` | 后续动作 | 必填 |
+| `validationRecord` | 校验记录 | 必填；引用本轮校验动作 |
+
+### Relationships
+
+- 关联 `01_Project_Progress.md`
+- 关联 `03_Task_Checklist.md`
+- 关联 `15_SYS002_Requirement_Breakdown.md`

specs/004-rev007-revenue-statistics-design/plan.md

@@ -0,0 +1,98 @@
+# Implementation Plan: REV-007 营收统计查询设计
+
+**Branch**: `004-rev007-revenue-statistics-design` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md)
+**Input**: Feature specification from `/specs/004-rev007-revenue-statistics-design/spec.md`
+
+## Summary
+
+本 feature 面向 `REV-007` 统计分析模块的正式文档补齐，重点收口三类内容：1）在 [12_REV_Detailed.md](/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md) 中明确统计主题、查询维度、核心指标与排除项；2）在 [03_Interface_Design.md](/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md) 中补齐 `IF-REV-010` 的查询边界、输入输出与权限导出约束；3）在 [01_Database_Design.md](/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md) 中明确统计数据承接口径、视图/汇总边界与“未见实现”的保守表述，并同步治理台账。
+
+## Technical Context
+
+**Primary Work Product**: Markdown 正式设计文档、管理台账、Speckit 规格/计划工件
+**Source of Truth Documents**:
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+- `docs/design/00_Management/04_Writing_Guide.md`
+- `AGENTS.md`
+**Reference Sources**:
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `docs/guides/BACKEND_CURRENT_STATUS.md`
+- `docs/guides/BACKEND_TABLE_MAPPING.md`
+- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+- `docs/design/04_Appendix/Archive/01_Requirements/`
+**Validation Commands**:
+- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`
+- `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md`
+- `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md`
+- `make check-links`
+**Target Scope**: `REV-007` 统计分析相关章节、`IF-REV-010` 相关接口章节、数据库统计承接口径章节与治理台账
+**Project Type**: 文档治理仓库
+**Constraints**:
+- 不新增平行正式稿
+- 不臆造 backend 已实现的统计入口
+- Archive 仅作来源核对
+- 使用相对路径与现有正式编号体系
+- 不把预测分析、BI 专题或独立数仓实现写成本轮既成事实
+**Scale/Scope**: 跨详细设计、接口设计、数据库设计与治理台账的中等规模文档收口
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：本次改动将优先落在 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` 及治理台账，而不是新增平行正式稿。
+- [x] **范围基线已确认**：`REV-007` 已存在于 `SYS-002` 营收业务模块中，当前仅补齐统计查询正式口径，不扩展到独立 BI/预测分析范围。
+- [x] **Archive 使用方式合规**：Archive 仅作为统计主题和历史口径的参考来源，不直接替代主文档结论。
+- [x] **一致性影响已列出**：受影响项包括统计主题名称、指标口径、`IF-REV-010` 边界、数据库统计承接口径、实现状态表述与治理台账。
+- [x] **校验与台账动作已规划**：已明确单文件校验与 `make check-links`，并计划同步更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Optional: document entities/traceability objects
+├── quickstart.md        # Optional: validation or review quickstart
+├── contracts/           # Optional: interface or section-level artifacts
+└── tasks.md             # Phase 2 output (/speckit.tasks command)
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/
+├── 01_Overview/
+├── 02_Detailed_Design/
+├── 03_Technical_Design/
+└── 04_Appendix/Archive/
+
+README.md
+AGENTS.md
+.specify/templates/
+```
+
+**Structure Decision**: [Document the exact files to be updated and the reason each file is in scope]
+**Structure Decision**:
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`：补齐 `REV-007` 的业务范围、统计主题、维度、指标和排除项。
+- `docs/design/03_Technical_Design/03_Interface_Design.md`：补齐 `IF-REV-010` 的正式接口定义、查询主题、输入输出与权限导出边界。
+- `docs/design/03_Technical_Design/01_Database_Design.md`：补齐统计承接口径、视图/汇总边界、历史与现状保守口径。
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`：同步 `SYS002-REQ-012` 的实现评估和后续建议。
+- `docs/design/00_Management/01_Project_Progress.md`：记录本轮 `REV-007` 设计收口进展。
+- `docs/design/00_Management/03_Task_Checklist.md`：同步 tracked-task 闭环记录。
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| 无 | - | - |

specs/004-rev007-revenue-statistics-design/quickstart.md

@@ -0,0 +1,58 @@
+# Quickstart: REV-007 营收统计查询设计
+
+## 目标
+
+本 quickstart 用于指导评审者和文档维护者快速完成 `REV-007` 统计查询设计补齐的检查，不涉及 backend 实施。
+
+## 步骤 1：阅读规格与计划结论
+
+1. 阅读 `spec.md`，确认本轮范围只覆盖 `REV-007` 的正式设计收口，不扩展到预测分析或独立 BI 专题。
+2. 阅读 `research.md`，确认以下决策已固定：
+   - `REV-007` 保持使用 `IF-REV-010`
+   - 统计范围收敛为经营查询
+   - 统计口径按“主题 + 维度 + 指标”组织
+   - 数据承接口径以在线主数据聚合和视图/汇总口径为主
+
+## 步骤 2：执行文档改动时的目标落点
+
+1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐：
+   - 统计主题清单
+   - 维度与指标口径
+   - 导出与权限边界
+   - 排除项与文档先行边界
+2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`：
+   - 补齐 `IF-REV-010` 的正式接口定义
+   - 明确查询条件、输出主题、权限和导出边界
+3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`：
+   - 明确统计数据来源、视图/汇总口径和保守承接口径
+4. 在治理台账中回写：
+   - `15_SYS002_Requirement_Breakdown.md`
+   - `01_Project_Progress.md`
+   - `03_Task_Checklist.md`
+
+## 步骤 3：建议校验命令
+
+```bash
+make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md
+make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md
+make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md
+make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
+make validate-file FILE=docs/design/00_Management/01_Project_Progress.md
+make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md
+make check-links
+```
+
+## 步骤 4：验收检查点
+
+- `REV-007` 的统计主题、维度和指标口径不再停留在摘要级表述
+- `IF-REV-010` 的输入输出、权限与导出边界已明确
+- 数据库主文档未把统计承接口径误写为已存在独立统计表族
+- 治理台账明确保持“设计收口推进中，代码入口未见明确实现”的真实结论
+- 正式文档与台账同步更新
+
+## 步骤 5：本轮实现摘要
+
+- 已完成 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`15_SYS002_Requirement_Breakdown.md`、`01_Project_Progress.md`、`03_Task_Checklist.md` 的正式文档回写。
+- `REV-007` 已在正式文档中明确按“主题 + 维度 + 指标”组织统计查询，`IF-REV-010` 的输入输出、权限和导出边界已补齐。
+- 数据库主文档已明确统计承接口径以在线主数据聚合、视图或汇总口径为主，不臆造独立统计表或离线数仓能力。
+- 已执行并通过全部单文件校验与 `make check-links`。

specs/004-rev007-revenue-statistics-design/research.md

@@ -0,0 +1,56 @@
+# Phase 0 Research: REV-007 营收统计查询设计
+
+## 决策 1：`REV-007` 保持 `IF-REV-010` 作为正式统计查询接口
+
+- **Decision**: `REV-007` 继续使用 `IF-REV-010` 作为正式统计查询接口编号，不新增新的 `IF-*` 编号。
+- **Rationale**:
+  - 当前正式接口总表已为 `REV-007` 预留 `IF-REV-010`，问题在于内容过薄，而不是编号错误。
+  - 继续沿用现有编号可以避免与 `REV-006` 那类编号冲突治理混在一起。
+  - 本轮重点是补齐统计主题、查询维度和输出口径，而不是重做接口编号体系。
+- **Alternatives considered**:
+  - 新增 `IF-REV-014`：否决，因为没有编号冲突，新增会制造不必要扰动。
+  - 保持“仅总表项，不补详细定义”：否决，因为不足以支撑后续实现与评审。
+
+## 决策 2：统计范围收敛为经营查询，不扩展到预测与 BI 专题
+
+- **Decision**: `REV-007` 正式设计仅覆盖经营统计查询，包括营收、收费、欠费、客户、渠道、抄表完成率和必要的业务概览类统计；预测分析、专题大屏、独立 BI/数仓能力不纳入本轮正式范围。
+- **Rationale**:
+  - 当前正式详细设计和需求拆解都只给出了经营查询级别的描述。
+  - backend 现状未见明确统计分析实现入口，过度扩展会直接变成新需求。
+  - 先收口“标准查询口径”更符合“设计先行、实现待立项”的保守策略。
+- **Alternatives considered**:
+  - 把趋势预测、经营驾驶舱、大屏分析一并纳入：否决，因为超出现有正式范围。
+  - 只保留一句“营收统计查询”：否决，因为无法指导后续实现或立项。
+
+## 决策 3：统计结果按“主题 + 维度 + 指标”三层口径组织
+
+- **Decision**: `REV-007` 的正式设计按“统计主题、查询维度、核心指标”三层组织，不直接写死复杂报表清单。
+- **Rationale**:
+  - 当前文档缺的是统计口径框架，而不是具体报表枚举。
+  - 三层结构便于在详细设计、接口设计和数据库设计之间保持一致表达。
+  - 后续若扩展某类专题报表，也能在既有三层口径下继续补充。
+- **Alternatives considered**:
+  - 直接罗列大量报表名称：否决，因为容易脱离现有实现依据。
+  - 只写主题不写维度/指标：否决，因为口径仍然过空。
+
+## 决策 4：数据库承接口径以在线主数据聚合和视图/汇总口径为主
+
+- **Decision**: `REV-007` 在数据库设计中只约束“基于现有在线业务表聚合的视图/汇总口径”，不确认独立统计表或离线数仓对象。
+- **Rationale**:
+  - 当前数据库主文档只有一般性“统计分析视图”片段，未见 `REV-007` 专项统计表族。
+  - backend 也未见明确统计模块，因此写成独立统计表会超出证据范围。
+  - 以聚合视图/统计结果集描述可以满足设计收口，同时保持保守。
+- **Alternatives considered**:
+  - 臆造 `stat_*` 或 `report_*` 表：否决，因为没有实现或正式主文档证据。
+  - 完全不写数据库承接口径：否决，因为接口与详设无法闭环。
+
+## 决策 5：治理台账明确保持“设计收口完成，代码入口未见实现”
+
+- **Decision**: `REV-007` 在治理台账中的当前实现判断保持“未见实现”，但增加“设计收口已完成”的状态说明。
+- **Rationale**:
+  - 现有 `15_SYS002_Requirement_Breakdown.md` 已明确该模块未见实现。
+  - 文档补齐不应被误读为 backend 已完成统计能力。
+  - 这种表述更适合后续立项与排期管理。
+- **Alternatives considered**:
+  - 直接改成“部分实现”：否决，因为暂无明确代码入口证据。
+  - 只写“未见实现”不提设计进展：否决，因为无法体现本轮交付价值。

specs/004-rev007-revenue-statistics-design/spec.md

@@ -0,0 +1,129 @@
+# Feature Specification: REV-007 营收统计查询设计
+
+**Feature Branch**: `004-rev007-revenue-statistics-design`
+**Created**: 2026-03-18
+**Status**: Draft
+**Input**: User description: "docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-007 统计分析的设计补齐，明确统计主题、指标口径、查询维度、接口边界、历史/现状承接与治理台账同步"
+
+## Document Scope & Sources *(mandatory)*
+
+- **Target documents**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/design/00_Management/01_Project_Progress.md`
+  - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/design/00_Management/04_Writing_Guide.md`
+  - `AGENTS.md`
+- **Reference sources**:
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/guides/BACKEND_CURRENT_STATUS.md`
+  - `docs/guides/BACKEND_TABLE_MAPPING.md`
+  - `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+  - `docs/design/04_Appendix/Archive/01_Requirements/`
+- **Scope decision**: In scope. 本 feature 仅补齐 `REV-007` 的正式设计口径、接口边界、统计主题与指标维度、数据库承接口径及治理台账同步；不扩展到 BI 专题、预测模型、独立数仓实现或新增平行正式主稿。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 收口统计业务范围 (Priority: P1)
+
+作为文档维护者，我需要把 `REV-007` 的统计主题、查询维度、核心指标和边界限制写清楚，使评审者能够明确哪些统计属于营收主系统正式范围，哪些只保留为后续专题或报表层能力。
+
+**Why this priority**: 当前 `REV-007` 在详细设计中只有摘要级描述，如果不先收口统计范围，后续接口、数据库和实现评估都会失焦。
+
+**Independent Test**: 单独评审 `12_REV_Detailed.md` 中 `REV-007` 章节，应能明确统计主题、维度、典型指标、导出边界和排除项。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前 `REV-007` 只有简短说明， **When** 评审者阅读补齐后的详细设计， **Then** 能独立回答营收统计包含哪些主题、按哪些维度查询以及不包含哪些专题分析。
+2. **Given** 后续需要把统计设计转为研发任务， **When** 维护者依据该规格拆解工作， **Then** 不需要再回到 Archive 才能判断本轮的主题、指标和排除项。
+
+---
+
+### User Story 2 - 统一接口与数据承接口径 (Priority: P2)
+
+作为接口与数据设计评审者，我需要看到 `IF-REV-010` 的查询边界、输入条件、输出主题和数据库承接口径，使统计查询不再停留在“聚合视图/统计结果集”这种过于抽象的表述。
+
+**Why this priority**: 统计设计的核心风险在于接口口径与数据来源不清，容易把在线交易表、历史查询和报表专题混写在一起。
+
+**Independent Test**: 单独评审接口主文档和数据库主文档，应能确认 `IF-REV-010` 的查询主题、筛选条件、最小返回要求和数据来源边界。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看接口设计， **When** 阅读 `IF-REV-010` 章节， **Then** 能明确统计主题、输入维度、输出指标摘要和权限/导出边界。
+2. **Given** 评审者查看数据库设计， **When** 阅读统计分析相关章节， **Then** 能明确哪些统计依赖在线主数据聚合、哪些仅作为视图或汇总口径描述，且不误写为已存在独立统计表族。
+
+---
+
+### User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+作为后续立项和实施跟踪人员，我需要在治理台账中看到 `REV-007` 的当前实现判断、正式收口结果和后续建议，避免重复把同一统计能力误判为“已实现”或“已设计完成”。
+
+**Why this priority**: `15_SYS002_Requirement_Breakdown.md` 已把 `REV-007` 评为“未见实现”，正式文档补齐后需要同步治理口径，否则后续跟踪会失真。
+
+**Independent Test**: 单独检查治理台账，应能明确 `REV-007` 当前属于“设计收口完成、实现仍未见明确入口”的状态，并能看到后续建议。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看需求拆解与实现评估文档， **When** 阅读 `SYS002-REQ-012` 对应内容， **Then** 能明确设计补齐结果、当前实现状态和下一步建议。
+2. **Given** 项目需要记录本轮重要文档动作， **When** 查看项目进度与任务清单， **Then** 能定位 `REV-007` 的设计收口记录和校验结果。
+
+---
+
+### Edge Cases
+
+- 当某类统计主题只在历史需求或 Archive 中出现，而当前主文档未形成正式口径时，应如何判定为本轮正式范围还是后续专题保留项？
+- 当统计查询需要同时覆盖在线业务数据与历史只读口径时，如何保持“查询可追溯”但不误写为新增独立统计主表？
+- 当不同统计主题共享维度但指标含义不同，例如“收费金额”“实收金额”“应收金额”“欠费余额”时，如何避免同名不同义的口径冲突？
+- 当当前 backend 未见明确统计控制器或报表入口时，如何如实表达“设计已补齐、实现未见入口”的状态，而不把文档收口误写成已实现能力？
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST identify the exact target documents for `REV-007` design closure and ledger sync.
+- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` as the main source-of-truth documents for this feature.
+- **FR-003**: Specification MUST record that the feature is in scope only for `REV-007` formal design closure and follow-up implementation preparation, not for independent BI platform, data warehouse, or predictive analytics implementation.
+- **FR-004**: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal statistics design document.
+- **FR-005**: Specification MUST define the main statistics themes for `REV-007`, including at minimum revenue, billing, payment, arrears, customer, channel, meter-reading completion, and operational work-order related summary topics where applicable.
+- **FR-006**: Specification MUST define the query dimensions and filtering scope for `REV-007`, including at minimum time, bill period, region/department, customer category, channel, account/customer, and status-oriented filters where relevant.
+- **FR-007**: Specification MUST define the key indicators or result sets for the supported themes, and MUST distinguish similar but non-equivalent concepts such as receivable amount, actual collected amount, arrears balance, transaction count, and completion rate.
+- **FR-008**: Specification MUST define the formal boundary of `IF-REV-010`, including request conditions, output themes, permission/export constraints, and what remains outside this interface.
+- **FR-009**: Specification MUST define the database-side retention and aggregation boundary for `REV-007`, clarifying what is based on existing online business data aggregation, what may be expressed as views or summary results, and what must not be written as confirmed standalone statistics tables without evidence.
+- **FR-010**: Specification MUST define exclusions for `REV-007`, including predictive models,专题深度分析、跨系统经营大屏专题、以及无实现证据的独立报表引擎能力。
+- **FR-011**: Specification MUST capture cross-document consistency impacts for statistics terminology, indicators, interface numbering, data sources, implementation status wording, and ledger updates.
+- **FR-012**: Specification MUST list the validation actions required after document updates, including single-file validation for impacted docs and link consistency checks.
+- **FR-013**: Specification MUST state that formal document changes under this feature require synchronized updates to `01_Project_Progress.md` and `03_Task_Checklist.md`.
+- **FR-014**: Specification MUST record the current implementation judgment for `REV-007` as “设计补齐中 / 代码入口未见明确实现” unless stronger evidence is found during later phases.
+
+### Assumptions
+
+- 本 feature 以正式文档补齐和后续研发立项准备为目标，默认不在本轮直接修改 backend 代码。
+- `IF-REV-010` 继续作为 `REV-007` 的正式统计查询接口编号，不新发明新的 `IF-*` 编号体系。
+- 当前 backend 检索范围内未见明确统计/报表控制器或服务骨架，因此本轮默认按“设计先行、实现待立项”处理。
+- 统计查询主要依托现有在线业务主数据聚合与汇总结果承接，本轮不臆造独立统计仓库、离线批处理或专题分析引擎。
+- 导出能力属于统计查询的扩展能力，应受权限控制，但不要求本轮展开具体导出实现细节。
+
+### Key Entities *(include if feature involves data)*
+
+- **Statistics Theme**: 统计主题，如营收、收费、欠费、客户、渠道、抄表完成率、工单概览等查询域。
+- **Statistics Dimension**: 统计维度，如时间、账期、片区、营业所、客户类别、渠道、状态、人员或册本。
+- **Statistics Indicator**: 统计指标，如应收金额、实收金额、欠费余额、客户数、账单数、完成率、渠道占比等。
+- **Statistics Query Contract**: `IF-REV-010` 的输入条件、输出摘要、权限与导出边界定义。
+- **Aggregation Source**: 支撑统计结果的在线业务表、视图或汇总口径来源。
+- **Ledger Update**: 当 `REV-007` 文档收口后，需要同步回写到项目进度和任务清单的治理记录。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 评审者可在 5 分钟内从规格中定位 `REV-007` 的目标文档、统计主题范围、核心维度与排除项。
+- **SC-002**: 规格中至少覆盖 3 类独立可评审内容：统计业务范围、`IF-REV-010` 接口边界、数据库承接口径/实现评估。
+- **SC-003**: 规格明确区分至少 5 个核心指标或口径，并避免“应收/实收/欠费/笔数/完成率”混写。
+- **SC-004**: 后续执行 `/speckit.plan` 时，规划者无需再补充范围澄清即可将工作拆分为详细设计补齐、接口补齐、数据库口径补齐和治理台账同步四类任务。
+- **SC-005**: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查。

specs/004-rev007-revenue-statistics-design/tasks.md

@@ -0,0 +1,177 @@
+# Tasks: REV-007 营收统计查询设计
+
+**Input**: Design documents from `/specs/004-rev007-revenue-statistics-design/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/
+
+**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks.
+
+**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g. [US1], [US2], [US3])
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/`
+- Governance documents: `docs/design/00_Management/`
+- Archive references: `docs/design/04_Appendix/Archive/`
+- Runtime guidance: `README.md`, `AGENTS.md`, `.specify/templates/`
+
+## Phase 1: Scope & Source Confirmation (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set and impact boundary before editing.
+
+- [X] T001 Confirm target documents and exact `REV-007` touchpoints in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/spec.md`
+- [X] T002 Confirm governing source-of-truth and allowed reference sources in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/plan.md`
+- [X] T003 [P] Record final scope judgment for `REV-007` themes, exclusions, and implementation-status wording in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/research.md`
+- [X] T004 [P] Identify cross-document impacts for `IF-REV-010`、统计主题、指标口径、数据库承接口径和治理台账 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md`
+
+---
+
+## Phase 2: Foundational Alignment (Blocking Prerequisites)
+
+**Purpose**: Prepare the cross-document baseline that all user stories depend on.
+
+- [X] T005 Consolidate `REV-007` decisions, entities, and contract fields from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/research.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/data-model.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/contracts/rev007-interface-contract.md`
+- [X] T006 [P] Cross-check current sparse `REV-007` and `IF-REV-010` references in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T007 [P] Cross-check current database statistics wording and existing “统计分析视图” placeholder in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T008 Confirm ledger update expectations for this feature in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`
+
+---
+
+## Phase 3: User Story 1 - 收口统计业务范围 (Priority: P1) 🎯 MVP
+
+**Goal**: 让 `12_REV_Detailed.md` 中的 `REV-007` 章节具备完整的统计主题、查询维度、核心指标、导出边界和排除项说明。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-007` 章节，应能明确统计主题、维度、指标与不在本轮范围的专题分析项。
+
+### Implementation for User Story 1
+
+- [X] T009 [US1] Update `REV-007` 功能说明、关键设计、核心数据和落地边界 in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T010 [P] [US1] Add `Statistics Theme`、`Statistics Dimension`、`Statistics Indicator` 对应的主题/维度/指标摘要 to `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T011 [P] [US1] Sync `REV-007` implementation assessment and Story notes in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T012 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result
+- [X] T013 [US1] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture result
+
+**Checkpoint**: User Story 1 is reviewable and confirms the `REV-007` business scope without depending on interface/database redesign.
+
+---
+
+## Phase 4: User Story 2 - 统一接口与数据承接口径 (Priority: P2)
+
+**Goal**: 在接口和数据库主文档中为 `REV-007` 建立清晰的 `IF-REV-010` 查询边界、输入输出要求与统计数据承接口径。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` 与 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`，应能确认 `IF-REV-010` 的职责、统计主题、维度、指标与数据库保守承接口径。
+
+### Implementation for User Story 2
+
+- [X] T014 [US2] Add `IF-REV-010` formal interface definition, request/response shape, and permission/export boundary in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T015 [P] [US2] Update statistics themes, dimension terminology, and data-source wording in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [X] T016 [US2] Update statistical aggregation boundary, view/summary wording, and implementation-status constraints in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`
+- [X] T017 [P] [US2] Sync `REV-007` interface mapping and data-source terminology back into `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [X] T018 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture result
+- [X] T019 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture result
+- [X] T020 [US2] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture result after interface/data sync
+
+**Checkpoint**: User Story 2 is reviewable and fully expresses `IF-REV-010` and the database-side aggregation boundary independently.
+
+---
+
+## Phase 5: User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+**Goal**: 在治理台账中收口 `REV-007` 的设计进度、实现状态和后续建议，保持“设计补齐中、代码入口未见明确实现”的真实结论。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` 与 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`，应能确认 `REV-007` 的治理记录已同步。
+
+### Implementation for User Story 3
+
+- [X] T021 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` with `REV-007` design-closure result, implementation status, and follow-up recommendation
+- [X] T022 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` with the `REV-007` design closure milestone
+- [X] T023 [US3] Update `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` with the `REV-007` tracked-task closure status
+- [X] T024 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture result after governance sync
+- [X] T025 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture result
+
+**Checkpoint**: User Story 3 is reviewable and confirms governance closure independently.
+
+---
+
+## Final Phase: Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [X] T026 [P] Re-check source-of-truth alignment across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/01_Database_Design.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [X] T027 [P] Run `make check-links` after all document changes and capture result
+- [X] T028 Prepare final summary with modified files, validation results, remaining risks, and next-step suggestions in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/004-rev007-revenue-statistics-design/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1: Scope & Source Confirmation**: No dependencies; MUST finish before content edits
+- **Phase 2: Foundational Alignment**: Depends on Phase 1; MUST finish before user story work
+- **Phase 3: User Story 1**: Depends on Phase 2
+- **Phase 4: User Story 2**: Depends on Phase 2 and should follow User Story 1 because interface/data wording must align with the finalized statistics scope
+- **Phase 5: User Story 3**: Depends on Phase 2 and should follow User Story 2 because governance wording must use the finalized interface and data-source terminology
+- **Final Phase**: Depends on all selected user stories being complete
+
+### Within Each User Story
+
+- Update target documents before syncing supporting or governance documents
+- Complete content edits before validation
+- Complete validation before ledger updates are marked done
+- Complete ledger sync before final summary
+
+### User Story Completion Order
+
+`US1 -> US2 -> US3`
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel after source confirmation
+- `T006` and `T007` can run in parallel during foundational alignment
+- In `US1`, `T010` and `T011` can run in parallel after `T009`
+- In `US2`, `T015` and `T017` can run in parallel after `T014` and `T016`
+- `T026` and `T027` can run in parallel during final closure
+
+## Parallel Execution Examples
+
+### User Story 1
+
+```text
+Run in parallel after T009:
+- T010 [P] [US1] Add theme/dimension/indicator summaries in 12_REV_Detailed.md
+- T011 [P] [US1] Sync implementation assessment in 15_SYS002_Requirement_Breakdown.md
+```
+
+### User Story 2
+
+```text
+Run in parallel after T014 and T016:
+- T015 [P] [US2] Update statistics terminology and data-source wording in 03_Interface_Design.md
+- T017 [P] [US2] Sync interface/data wording back into 12_REV_Detailed.md
+```
+
+## Implementation Strategy
+
+### MVP First
+
+先完成 `US1`，因为 `12_REV_Detailed.md` 中的统计主题、维度和指标边界是后续接口和数据库收口的前提。只要 `US1` 完成，就能先交付一版可评审的 `REV-007` 业务范围说明。
+
+### Incremental Delivery
+
+1. 完成 `US1`，锁定统计业务范围和排除项
+2. 完成 `US2`，锁定 `IF-REV-010` 与数据库承接口径
+3. 完成 `US3`，锁定治理台账和实现状态表述
+4. 最后统一执行全局一致性检查和链接校验
+
+### Notes
+
+- 每个 story 都可以独立评审，不要求一次性改完全部文档
+- 所有任务都必须回写既有正式文档，不能新建平行正式稿
+- Archive 只作为核对来源，不直接替代主文档
+- 验证和台账同步不是可选项

specs/005-rev002-billing-generation-gap/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: REV-002 开账计费与账单生成缺口补齐
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-18
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 当前规格基于现有正式主文档、治理台账和检索结论生成；`REV-002` 默认按“部分实现，但账单生成闭环仍需进一步收口”处理。

specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md

@@ -0,0 +1,53 @@
+# Contract: REV-002 开账计费与账单生成缺口补齐
+
+## 1. Formal Interface Allocation
+
+| Interface | Role | Direction |
+|---|---|---|
+| `IF-REV-005` | `REV-002` 开账计费与账单生成的正式业务接口 | `SYS-002` 内部正式业务接口 |
+
+约束：
+
+- `IF-REV-005` 保持为 `REV-002` 的正式账单生成接口编号，不新增新的开账生成接口编号。
+- 本接口只承接开账计费与账单生成，不扩展到收费核销、发票申请或催缴触发。
+
+## 2. Request Contract
+
+| Field | Meaning | Required |
+|---|---|---|
+| `billPeriod` | 账期 | 是 |
+| `readingBatchNo` | 抄表批次号 | 否 |
+| `customerIds` | 客户集合 | 否 |
+| `meterReadIds` | 抄表任务集合 | 否 |
+| `dueDate` | 应收截止日期 | 是 |
+| `operatorId` | 发起人 | 否 |
+
+补充约束：
+
+- 请求前提是抄表数据已通过校验或异常复核允许进入开账。
+- 至少应提供批次、客户范围或抄表任务范围中的一种有效筛选条件。
+
+## 3. Response Contract
+
+| Field | Meaning |
+|---|---|
+| `generateCount` | 成功生成账单数量 |
+| `successList` | 成功明细集合 |
+| `successList[].chargeId` | 账单主键 |
+| `successList[].chargeCode` | 账单编号 |
+| `successList[].custId` | 客户标识 |
+| `successList[].totalAmount` | 账单总金额 |
+| `failureList` | 失败明细集合 |
+| `failureList[].reason` | 失败原因 |
+
+## 4. Result Boundary Contract
+
+- 账单生成结果统一以 `biz_charge` 作为主结果、`biz_charge_detail` 作为明细结果承接。
+- 特殊开账、无码客户开账或罚款类开账应通过来源类型、业务类型或依据说明纳入统一账单主模型，不单独发明平行主表。
+- 账单生成成功后只表达“已生成营业账”的结果边界，后续收费、催缴、开票由下游模块继续承接。
+
+## 5. Exception Contract
+
+- 当价格模板、阶梯规则、费用组成、计划用水方案或必要来源数据缺失时，应阻断生成并返回失败原因。
+- 失败语义必须与现有抄表开账类错误码口径一致，不得仅写日志而不在接口结果中表达。
+- 异常复核、估抄、补抄、重录等场景只定义“是否允许进入生成”边界，不展开具体实现细节。

specs/005-rev002-billing-generation-gap/data-model.md

@@ -0,0 +1,137 @@
+# Data Model: REV-002 开账计费与账单生成缺口补齐
+
+## 1. Billing Trigger
+
+### Purpose
+
+定义从抄表校验结果进入开账计费流程的正式触发条件。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `billPeriod` | 账期 | 必填 |
+| `readingBatchNo` | 抄表批次号 | 可为空 |
+| `meterReadIds` | 抄表任务集合 | 至少存在批次或任务范围 |
+| `validatedFlag` | 是否已通过校验 | 必填；未校验不得生成 |
+| `dueDate` | 应收截止日期 | 必填 |
+| `operatorId` | 发起人 | 可为空 |
+
+### Relationships
+
+- 来源于 `biz_meter_read`、`biz_reading_data`、`biz_last_reading`
+- 可触发一个或多个 `Billing Result`
+
+## 2. Billing Rule Source
+
+### Purpose
+
+定义账单生成过程依赖的价格和费用规则来源。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `priceCategoryCode` | 价格归属编码 | 必填 |
+| `priceTemplateCode` | 价格模板编码 | 必填 |
+| `tierRuleRef` | 阶梯规则引用 | 可为空；按场景适用 |
+| `costComponentSet` | 费用组成集合 | 至少 1 项 |
+| `waterUseSchemeRef` | 计划用水方案引用 | 可为空；按场景适用 |
+| `ruleEffectiveFlag` | 规则是否完整有效 | 必填；无效时阻断生成 |
+
+### Relationships
+
+- 一个 `Billing Rule Source` 可服务多个 `Billing Trigger`
+- 一个 `Billing Rule Source` 可生成多个 `Charge Detail`
+
+## 3. Billing Result
+
+### Purpose
+
+定义账单生成后的主结果表达。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `chargeId` | 账单主键 | 唯一 |
+| `chargeCode` | 账单编号 | 唯一 |
+| `custId` | 客户标识 | 必填 |
+| `accountId` | 账户标识 | 可为空；按账户体系承接 |
+| `billPeriod` | 账期 | 必填 |
+| `totalAmount` | 账单总金额 | 必填 |
+| `sourceType` | 来源类型 | 必填；普通开账/特殊开账等 |
+| `chargeStatus` | 账单状态 | 必填 |
+| `dueDate` | 应收截止日期 | 必填 |
+
+### Relationships
+
+- 由一个 `Billing Trigger` 触发产生
+- 包含多个 `Charge Detail`
+- 后续可流转到收费、催缴、发票等下游模块
+
+## 4. Charge Detail
+
+### Purpose
+
+定义营业账明细中的费用组成表达。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `chargeId` | 所属账单 ID | 必填 |
+| `costComponentCode` | 费用组成代码 | 必填 |
+| `usageAmount` | 用量 | 可为空；按费用项适用 |
+| `unitPrice` | 单价 | 可为空；按费用项适用 |
+| `detailAmount` | 明细金额 | 必填 |
+| `detailRemark` | 明细说明 | 可为空 |
+
+### Relationships
+
+- 归属于一个 `Billing Result`
+- 引用一个 `Billing Rule Source`
+
+## 5. Billing Exception Result
+
+### Purpose
+
+定义账单生成失败时的正式异常返回表达。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `reasonCode` | 失败原因编码 | 必填 |
+| `reasonText` | 失败说明 | 必填 |
+| `relatedCustomer` | 相关客户 | 可为空 |
+| `relatedMeterRead` | 相关抄表任务 | 可为空 |
+| `blockingFlag` | 是否阻断生成 | 固定为是 |
+
+### Relationships
+
+- 与一个 `Billing Trigger` 关联
+- 不生成 `Billing Result`
+
+## 6. Billing Governance Record
+
+### Purpose
+
+用于在治理台账中记录 `REV-002` 的设计状态、实现评估和后续建议。
+
+### Key Fields
+
+| Field | Description | Rule |
+|---|---|---|
+| `requirementCode` | 对应需求编号 | 固定为 `SYS002-REQ-004` |
+| `featureName` | Speckit feature 名称 | 必填 |
+| `designStatus` | 设计状态 | 必填；设计收口中/已收口 |
+| `implementationStatus` | 实现评估 | 必填；当前为部分实现 |
+| `nextAction` | 后续动作 | 必填 |
+| `validationRecord` | 校验记录 | 必填 |
+
+### Relationships
+
+- 关联 `01_Project_Progress.md`
+- 关联 `03_Task_Checklist.md`
+- 关联 `15_SYS002_Requirement_Breakdown.md`

specs/005-rev002-billing-generation-gap/plan.md

@@ -0,0 +1,123 @@
+# Implementation Plan: REV-002 开账计费与账单生成缺口补齐
+
+**Branch**: `005-rev002-billing-generation-gap` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md)
+**Input**: Feature specification from `/specs/005-rev002-billing-generation-gap/spec.md`
+
+**Note**: 本计划面向文档治理仓库，交付对象是正式设计文档与治理台账的收口，而不是业务代码实现。
+
+## Summary
+
+本 feature 聚焦 `REV-002` 中“抄表校验后到账单生成”的文档缺口补齐，目标是在不扩展到收费核销、发票、催缴和统计分析的前提下，统一 `IF-REV-005` 的业务边界、账单生成规则、结果表达、`biz_charge` / `biz_charge_detail` 承接口径，以及治理台账中的“部分实现”结论。
+
+## Technical Context
+
+**Primary Work Product**: 正式 Markdown 设计文档、治理台账、speckit 规划工件
+**Source of Truth Documents**:
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+**Reference Sources**:
+- `docs/guides/BACKEND_CURRENT_STATUS.md`
+- `docs/guides/BACKEND_TABLE_MAPPING.md`
+- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+- `docs/design/04_Appendix/Archive/01_Requirements/`
+**Validation Commands**:
+- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`
+- `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md`
+- `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md`
+- `make check-links`
+**Target Scope**: `REV-002` 相关详细设计、接口设计、数据库设计与治理台账的交叉收口
+**Project Type**: 文档治理仓库
+**Constraints**:
+- 不新增平行正式稿，只修改既有主文档和治理文档
+- 不凭空新增业务规则、接口编号、账单主模型或独立表族
+- `IF-REV-005` 继续作为正式账单生成接口编号
+- 正式文档使用中文，仓库内链接使用相对路径
+- 治理结论保持“部分实现，账单生成闭环仍需继续校核”的真实状态
+**Scale/Scope**: 跨 6 个正式文档的中等范围一致性修订
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：本次只修改既有主文档与治理文档，不新增平行正式稿。
+- [x] **范围基线已确认**：`REV-002` 属于既有 `SYS-002` 营收业务范围，且本轮仅收口开账计费与账单生成缺口，不跨入 `REV-003` 收费核销或其他模块。
+- [x] **Archive 使用方式合规**：Archive 与 guides 仅用于核对现状、术语和数据口径，正式结论以主文档回写为准。
+- [x] **一致性影响已列出**：受影响项包括 `IF-REV-005` 编号语义、账单生成结果表述、`biz_charge` / `biz_charge_detail` 承接口径、特殊开账承接方式、治理台账中的实现状态文字。
+- [x] **校验与台账动作已规划**：已规划单文件校验与 `make check-links`，并纳入 `01_Project_Progress.md`、`03_Task_Checklist.md`、`15_SYS002_Requirement_Breakdown.md` 的同步更新。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/005-rev002-billing-generation-gap/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   └── rev002-billing-contract.md
+└── tasks.md
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/
+│   ├── 01_Project_Progress.md
+│   ├── 03_Task_Checklist.md
+│   └── 15_SYS002_Requirement_Breakdown.md
+├── 01_Overview/
+│   └── 03_Summary_Design.md
+├── 02_Detailed_Design/
+│   └── 12_REV_Detailed.md
+├── 03_Technical_Design/
+│   ├── 01_Database_Design.md
+│   └── 03_Interface_Design.md
+└── 04_Appendix/Archive/
+```
+
+**Structure Decision**:
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`：补齐 `REV-002` 的触发前提、规则来源、结果表达、特殊开账统一模型和排除项。
+- `docs/design/03_Technical_Design/03_Interface_Design.md`：补齐 `IF-REV-005` 的请求前提、输出语义、失败/阻断语义，以及与后续收费链路的边界。
+- `docs/design/03_Technical_Design/01_Database_Design.md`：明确 `biz_charge`、`biz_charge_detail`、价格模板、阶梯规则、费用组成和历史开账/特殊开账的正式承接口径。
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`：保持“部分实现”判断，同时记录本轮文档收口成果与后续建议。
+- `docs/design/00_Management/01_Project_Progress.md`：记录本轮 `REV-002` 文档治理动作与校验结果。
+- `docs/design/00_Management/03_Task_Checklist.md`：登记本轮任务闭环状态。
+
+## Phase 0 Research Output
+
+- `research.md` 已固定 5 项关键决策：
+  - `IF-REV-005` 继续作为正式账单生成接口
+  - 范围只收口“抄表校验后到账单生成”
+  - 账单结果统一由 `biz_charge` + `biz_charge_detail` 承接
+  - 异常语义统一为“阻断生成 + 返回失败原因”
+  - 治理台账继续保持“部分实现”
+
+## Phase 1 Design Output
+
+- `data-model.md`：定义 `Billing Trigger`、`Billing Rule Source`、`Billing Result`、`Charge Detail`、`Billing Exception Result`、`Billing Governance Record`
+- `contracts/rev002-billing-contract.md`：定义 `IF-REV-005` 的 request / response / result boundary / exception contract
+- `quickstart.md`：给出目标落点、建议校验命令与验收检查点
+- `AGENTS.md`：已执行 `./.specify/scripts/bash/update-agent-context.sh codex`，完成 agent context 更新
+
+## Post-Design Constitution Check
+
+- [x] 主文档承载策略未偏离，所有设计输出都指向既有正式文档修订
+- [x] 范围仍限定在 `REV-002` 账单生成闭环，不涉及跨模块扩写
+- [x] Archive 与 guides 仅用于佐证，不直接生成正式结论
+- [x] 一致性影响已沉淀到 data model、contract 与 quickstart，可直接支撑下一步 `tasks.md`
+- [x] 校验与台账动作已被明确列入 quickstart 与后续任务拆解基础
+
+## Complexity Tracking
+
+本次计划无宪法豁免项。

specs/005-rev002-billing-generation-gap/quickstart.md

@@ -0,0 +1,51 @@
+# Quickstart: REV-002 开账计费与账单生成缺口补齐
+
+## 目标
+
+本 quickstart 用于指导评审者和文档维护者快速完成 `REV-002` 开账计费与账单生成缺口补齐的检查，不涉及 backend 实施。
+
+## 步骤 1：阅读规格与计划结论
+
+1. 阅读 `spec.md`，确认本轮范围只覆盖 `IF-REV-005`、开账规则、结果表达、数据库承接口径与治理同步。
+2. 阅读 `research.md`，确认以下决策已固定：
+   - `IF-REV-005` 保持为正式账单生成接口
+   - 开账生成闭环只覆盖“抄表校验后到账单生成”
+   - 账单结果统一由 `biz_charge` + `biz_charge_detail` 承接
+   - 异常采用“阻断生成 + 返回失败原因”的口径
+
+## 步骤 2：执行文档改动时的目标落点
+
+1. 在 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 补齐：
+   - 开账计费规则来源
+   - 账单生成结果表达
+   - 特殊开账与异常边界
+   - 排除项与文档先行边界
+2. 在 `docs/design/03_Technical_Design/03_Interface_Design.md`：
+   - 补齐 `IF-REV-005` 的正式接口定义
+   - 明确请求条件、输出结果和异常语义
+3. 在 `docs/design/03_Technical_Design/01_Database_Design.md`：
+   - 明确 `biz_charge`、`biz_charge_detail` 与价格规则对象的承接口径
+4. 在治理台账中回写：
+   - `15_SYS002_Requirement_Breakdown.md`
+   - `01_Project_Progress.md`
+   - `03_Task_Checklist.md`
+
+## 步骤 3：建议校验命令
+
+```bash
+make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md
+make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md
+make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md
+make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
+make validate-file FILE=docs/design/00_Management/01_Project_Progress.md
+make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md
+make check-links
+```
+
+## 步骤 4：验收检查点
+
+- `REV-002` 的开账规则和结果表达不再停留在摘要级表述
+- `IF-REV-005` 的请求输出和异常语义已明确
+- 数据库主文档未把特殊开账误写为平行在线主表
+- 治理台账明确保持“部分实现，账单生成闭环仍需继续校核”的真实结论
+- 正式文档与台账同步更新

specs/005-rev002-billing-generation-gap/research.md

@@ -0,0 +1,56 @@
+# Phase 0 Research: REV-002 开账计费与账单生成缺口补齐
+
+## 决策 1：`IF-REV-005` 继续作为正式账单生成接口
+
+- **Decision**: `REV-002` 继续使用 `IF-REV-005` 作为正式账单生成接口编号，不新增新的 `IF-*` 编号。
+- **Rationale**:
+  - 当前正式接口总表和接口章节都已使用 `IF-REV-005`，缺的是闭环内容而不是编号本身。
+  - 保持现有编号可以减少与其他模块编号治理的耦合。
+  - 本轮重点是补齐规则、结果表达和数据库承接口径。
+- **Alternatives considered**:
+  - 新增新的账单生成接口编号：否决，因为没有编号冲突，只会制造额外扰动。
+  - 维持总表项不补详细定义：否决，因为不足以支撑后续实现和评审。
+
+## 决策 2：开账生成闭环仅覆盖“抄表校验后到账单生成”
+
+- **Decision**: 本 feature 的正式范围只覆盖从抄表校验结果进入开账计费、生成营业账及其结果表达的闭环，不扩展到收费核销、发票申请、催缴或统计分析链路。
+- **Rationale**:
+  - 当前缺口明确聚焦在 `IF-REV-005` 和账单生成规则。
+  - 收费、发票、催缴都已有单独模块和接口编号，不应混入本轮。
+  - 先收口“账单生成前后边界”更有利于后续对实现进行准确评估。
+- **Alternatives considered**:
+  - 把收费核销一起纳入：否决，因为会扩大到 `REV-003`。
+  - 把发票和催缴后续链路一起写入：否决，因为超出当前缺口范围。
+
+## 决策 3：账单结果以 `biz_charge` + `biz_charge_detail` 主明细表达
+
+- **Decision**: 账单生成结果统一以 `biz_charge` 作为主表、`biz_charge_detail` 作为明细表承接，不新增平行“特殊开账表”或独立账单结果模型。
+- **Rationale**:
+  - 数据库主文档已明确 `biz_charge*` 是开账结果承接口径。
+  - 当前 backend 也已见 `charge/chargedetail` 相关入口。
+  - 这样既能覆盖普通开账，也能把特殊开账作为来源类型或业务类型扩展纳入统一表达。
+- **Alternatives considered**:
+  - 单独新增“特殊开账表”：否决，因为没有正式主文档或实现证据支持。
+  - 仅描述账单主表、不写明细关系：否决，因为会削弱费用组成表达。
+
+## 决策 4：异常与阻断场景采用“阻断生成 + 返回失败原因”的口径
+
+- **Decision**: 当价格模板、阶梯规则、费用组成或必要来源数据缺失时，`IF-REV-005` 采用“阻断生成 + 返回失败原因”的统一异常语义。
+- **Rationale**:
+  - 现有接口主文档已经有 `1_002_002_003` 这类错误码线索。
+  - 对账单生成而言，缺规则时继续生成不符合正式业务口径。
+  - 统一异常语义有助于详细设计、接口设计和治理文档表达一致。
+- **Alternatives considered**:
+  - 自动降级生成部分账单：否决，因为缺乏正式依据且风险高。
+  - 只在日志中记录、不在接口返回中表达：否决，因为不利于评审和实现。
+
+## 决策 5：治理台账保持“部分实现，闭环未完全收口”
+
+- **Decision**: `REV-002` 的当前实现判断继续保持“部分实现”，但增加“账单生成规则与结果表达已完成文档收口”的说明。
+- **Rationale**:
+  - 当前治理台账已明确部分实现，且 backend 未见完整“账单生成专用闭环接口”证据。
+  - 文档补齐不应被误读为实现已完成。
+  - 这种表述更利于后续继续校核实现入口与缺口。
+- **Alternatives considered**:
+  - 改成“已实现”：否决，因为证据不足。
+  - 保持“部分实现”但不提设计进展：否决，因为无法体现本轮交付价值。

specs/005-rev002-billing-generation-gap/spec.md

@@ -0,0 +1,130 @@
+# Feature Specification: REV-002 开账计费与账单生成缺口补齐
+
+**Feature Branch**: `005-rev002-billing-generation-gap`
+**Created**: 2026-03-18
+**Status**: Draft
+**Input**: User description: "docs/design/02_Detailed_Design/12_REV_Detailed.md 中 REV-002 开账计费与账单生成缺口补齐，明确 IF-REV-005 的业务边界、账单生成规则、结果表达、数据承接口径与治理台账同步"
+
+## Document Scope & Sources *(mandatory)*
+
+- **Target documents**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/design/00_Management/01_Project_Progress.md`
+  - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/03_Technical_Design/01_Database_Design.md`
+  - `docs/design/01_Overview/03_Summary_Design.md`
+  - `docs/design/00_Management/04_Writing_Guide.md`
+  - `AGENTS.md`
+- **Reference sources**:
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/guides/BACKEND_CURRENT_STATUS.md`
+  - `docs/guides/BACKEND_TABLE_MAPPING.md`
+  - `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
+  - `docs/design/04_Appendix/Archive/01_Requirements/`
+- **Scope decision**: In scope. 本 feature 仅补齐 `REV-002` 中“开账计费与账单生成”缺口，重点收口 `IF-REV-005`、计费规则来源、账单生成结果表达、数据承接口径和治理台账同步；不扩展到整个抄表采集链路、收费核销链路或新增平行正式主稿。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 收口开账生成规则 (Priority: P1)
+
+作为文档维护者，我需要把 `REV-002` 的开账计费规则、账单生成触发条件、费用组成和结果表达写清楚，使评审者能够明确“抄表数据如何转为营业账”和“账单生成结果如何表达”。
+
+**Why this priority**: 当前 `REV-002` 已具备抄表与开账摘要，但“IF-REV-005` 的闭环规则和结果表达”仍偏概括，后续接口、数据库和实现评估都依赖这部分先收口。
+
+**Independent Test**: 单独评审 `12_REV_Detailed.md` 中 `REV-002` 相关章节，应能明确账单生成入口、价格规则来源、费用组成、异常处理和生成结果表达。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前文档只说明“按价格模板和费用组成计费”， **When** 评审者阅读补齐后的详细设计， **Then** 能明确开账计费的输入、规则来源、结果对象和后续流转边界。
+2. **Given** 后续需要将账单生成闭环拆为研发任务， **When** 维护者依据该规格拆解工作， **Then** 不需要再回到 Archive 才能判断本轮正式范围和排除项。
+
+---
+
+### User Story 2 - 统一 IF-REV-005 与数据承接口径 (Priority: P2)
+
+作为接口与数据设计评审者，我需要看到 `IF-REV-005` 的输入输出、状态语义、异常口径和数据库承接口径，使账单生成不再停留在“生成账单”这种过于抽象的描述。
+
+**Why this priority**: `REV-002` 当前被评为“部分实现”，核心风险就在于接口闭环和数据承接口径不够清楚，容易导致文档与已有 `charge/chargedetail` 实现映射失真。
+
+**Independent Test**: 单独评审接口主文档和数据库主文档，应能确认 `IF-REV-005` 的查询/生成边界、结果字段语义和 `biz_charge*` 承接口径。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看接口设计， **When** 阅读 `IF-REV-005` 章节， **Then** 能明确请求条件、生成结果、异常语义和状态表达。
+2. **Given** 评审者查看数据库设计， **When** 阅读开账与账单相关章节， **Then** 能明确 `biz_charge`、`biz_charge_detail`、价格模板和费用组成在账单生成中的承接关系。
+
+---
+
+### User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+作为后续立项和实施跟踪人员，我需要在治理台账中看到 `REV-002` 的当前缺口、设计收口结果和后续建议，避免继续把“部分实现”的范围说得过宽或过窄。
+
+**Why this priority**: `15_SYS002_Requirement_Breakdown.md` 已明确 `REV-002` 的开账计费与账单生成为高优先缺口，文档收口后必须同步治理结论。
+
+**Independent Test**: 单独检查治理台账，应能明确 `REV-002` 当前属于“文档收口后仍为部分实现”的状态，并能看到后续建议。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看需求拆解与实现评估文档， **When** 阅读 `SYS002-REQ-004` 对应内容， **Then** 能明确设计收口结果、当前实现状态和下一步建议。
+2. **Given** 项目需要记录本轮重要文档动作， **When** 查看项目进度与任务清单， **Then** 能定位 `REV-002` 的开账计费规则收口记录和校验结果。
+
+---
+
+### Edge Cases
+
+- 当抄表数据存在异常复核、估抄、补抄或重录场景时，账单生成规则如何保持正式文档口径一致，而不展开实现细节？
+- 当特殊开账、无码客户开账或罚款类开账进入同一账单主模型时，如何定义结果表达而不误写为独立平行主表？
+- 当价格模板、阶梯规则、费用组成缺失或冲突时，如何在接口和详细设计中统一表达“阻断生成”的异常语义？
+- 当当前 backend 已有 `charge/chargedetail` 入口但未见明确“专用账单生成闭环接口”证据时，如何如实表达“部分实现”而不夸大为完整闭环？
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST identify the exact target documents for `REV-002` billing-generation closure and ledger sync.
+- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md` as the main source-of-truth documents for this feature.
+- **FR-003**: Specification MUST record that the feature is in scope only for `IF-REV-005` business boundary, billing-rule source, result expression, database-side retention, and governance sync, not for the entire meter-reading or payment domain.
+- **FR-004**: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal document for billing generation.
+- **FR-005**: Specification MUST define the billing-generation trigger path from validated reading result to charge creation, including rule sources such as price category, price template, tier rule, cost component, and water-use scheme where applicable.
+- **FR-006**: Specification MUST define the minimum result expression for generated charge outputs, including master/detail relationship, period, customer/account linkage, amount composition, and downstream handoff boundary.
+- **FR-007**: Specification MUST define the formal boundary of `IF-REV-005`, including request preconditions, output result semantics, exception semantics, and what remains outside the interface.
+- **FR-008**: Specification MUST define how abnormal reading and special-billing scenarios relate to the normal billing flow without requiring a new standalone online billing model.
+- **FR-009**: Specification MUST define the database-side retention and mapping boundary for billing generation, clarifying the role of `biz_charge`、`biz_charge_detail` and related pricing objects.
+- **FR-010**: Specification MUST define exclusions for this feature, including payment write-off, invoice issuance, reminder follow-up, and unrelated statistics/reporting concerns.
+- **FR-011**: Specification MUST capture cross-document consistency impacts for `IF-REV-005`, billing terminology, result-state wording, historical “特殊开账/开账记录”承接 and governance wording.
+- **FR-012**: Specification MUST list the validation actions required after document updates, including single-file validation for impacted docs and link consistency checks.
+- **FR-013**: Specification MUST state that formal document changes under this feature require synchronized updates to `01_Project_Progress.md` and `03_Task_Checklist.md`.
+- **FR-014**: Specification MUST record the current implementation judgment for this gap as “部分实现，需进一步收口账单生成闭环” unless stronger evidence is found later.
+
+### Assumptions
+
+- 本 feature 以正式文档补齐和后续研发立项准备为目标，默认不在本轮直接修改 backend 代码。
+- `IF-REV-005` 继续作为 `REV-002` 的正式账单生成接口编号，不新发明新的 `IF-*` 编号体系。
+- 当前 backend 已见 `charge/chargedetail/collection` 相关入口，因此本轮默认按“部分实现，闭环未完全收口”处理。
+- 账单生成结果主要由 `biz_charge`、`biz_charge_detail` 和价格/费用规则对象承接，本轮不臆造新的独立账单主模型。
+- 特殊开账属于营业账主模型下的来源类型或业务类型扩展，不默认要求新建平行表族。
+
+### Key Entities *(include if feature involves data)*
+
+- **Billing Trigger**: 从抄表校验结果进入开账计费的正式触发条件集合。
+- **Billing Rule Source**: 价格归属、价格模板、阶梯规则、费用组成和计划用水方案等规则来源。
+- **Billing Result**: 账单生成后的主单/明细结果表达，包括账期、客户、金额组成和状态边界。
+- **Billing Query Contract**: `IF-REV-005` 的输入条件、输出结果和异常语义定义。
+- **Charge Master/Detail Mapping**: `biz_charge` 与 `biz_charge_detail` 的正式承接口径。
+- **Ledger Update**: 当 `REV-002` 文档收口后，需要同步回写到项目进度和任务清单的治理记录。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 评审者可在 5 分钟内从规格中定位 `REV-002` 的目标文档、开账计费边界、规则来源和排除项。
+- **SC-002**: 规格中至少覆盖 3 类独立可评审内容：开账规则闭环、`IF-REV-005` 接口边界、数据库承接口径/实现评估。
+- **SC-003**: 规格明确区分至少 5 项关键生成口径或结果要素，如账期、客户/账户、应收金额、费用组成、主明细关系、异常阻断语义。
+- **SC-004**: 后续执行 `/speckit.plan` 时，规划者无需再补充范围澄清即可将工作拆分为详细设计补齐、接口补齐、数据库口径补齐和治理台账同步四类任务。
+- **SC-005**: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查。

specs/005-rev002-billing-generation-gap/tasks.md

@@ -0,0 +1,126 @@
+# Tasks: REV-002 开账计费与账单生成缺口补齐
+
+**Input**: Design documents from `/specs/005-rev002-billing-generation-gap/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md
+
+**Validation**: Validation tasks are NOT optional in this repository. Every document change task set MUST include the applicable validation and ledger-sync tasks.
+
+**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Phase 1: Scope & Source Confirmation (Shared Foundation)
+
+**Purpose**: Confirm the source-of-truth set, scope boundaries, and cross-document impact before editing.
+
+- [x] T001 Confirm target documents and target sections in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/spec.md`
+- [x] T002 Confirm authoritative sources and allowed reference inputs in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/plan.md`
+- [x] T003 [P] Confirm fixed decisions for `IF-REV-005`、账单结果承接和异常语义 in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/research.md`
+- [x] T004 [P] Confirm entities, contract fields, and validation commands in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/data-model.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/contracts/rev002-billing-contract.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/quickstart.md`
+
+---
+
+## Phase 2: User Story 1 - 收口开账生成规则 (Priority: P1) 🎯 MVP
+
+**Goal**: 补齐 `REV-002` 详细设计中的开账触发前提、规则来源、结果表达、特殊开账统一模型和排除项。
+
+**Independent Test**: 单独评审 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-002` 章节，应能明确账单生成入口、价格规则来源、费用组成、异常阻断语义和下游边界。
+
+### Implementation for User Story 1
+
+- [x] T005 [US1] Read `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/02_Delivery_Standards.md`, `docs/design/00_Management/03_Task_Checklist.md`, and `docs/design/02_Detailed_Design/12_REV_Detailed.md` before editing
+- [x] T006 [US1] Update `docs/design/02_Detailed_Design/12_REV_Detailed.md` to define `REV-002` billing trigger path, billing rule sources, result expression, special-billing inclusion, and explicit exclusions
+- [x] T007 [US1] Sync `REV-002` wording in `docs/design/01_Overview/03_Summary_Design.md` only if detailed-design terms or boundaries need matching references
+- [x] T008 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and capture the result in work notes
+- [x] T009 [US1] Run `make check-links` if `docs/design/02_Detailed_Design/12_REV_Detailed.md` headings, anchors, or cross-document links changed and capture the result in work notes
+
+**Checkpoint**: `REV-002` detailed design is independently reviewable and no longer stops at summary-level billing wording.
+
+---
+
+## Phase 3: User Story 2 - 统一 IF-REV-005 与数据承接口径 (Priority: P2)
+
+**Goal**: 统一接口主文档和数据库主文档中的 `IF-REV-005`、账单结果承接和异常边界口径。
+
+**Independent Test**: 单独评审 `docs/design/03_Technical_Design/03_Interface_Design.md` 与 `docs/design/03_Technical_Design/01_Database_Design.md`，应能明确请求条件、结果语义、异常阻断逻辑以及 `biz_charge` / `biz_charge_detail` 承接口径。
+
+### Implementation for User Story 2
+
+- [x] T010 [US2] Update `docs/design/03_Technical_Design/03_Interface_Design.md` to define `IF-REV-005` request preconditions, response semantics, exception semantics, and boundary with downstream charging flow
+- [x] T011 [US2] Update `docs/design/03_Technical_Design/01_Database_Design.md` to align `biz_charge`, `biz_charge_detail`, pricing-rule objects, and historical/special billing retention with the approved `REV-002` model
+- [x] T012 [P] [US2] Sync numbering, terminology, and cross-references between `docs/design/03_Technical_Design/03_Interface_Design.md` and `docs/design/03_Technical_Design/01_Database_Design.md`
+- [x] T013 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and capture the result in work notes
+- [x] T014 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` and capture the result in work notes
+- [x] T015 [US2] Run `make check-links` after interface/database cross-reference updates and capture the result in work notes
+
+**Checkpoint**: `IF-REV-005` and database retention are independently reviewable and use one consistent billing-generation model.
+
+---
+
+## Phase 4: User Story 3 - 同步治理与实现评估结论 (Priority: P3)
+
+**Goal**: 在治理台账中回写 `REV-002` 本轮设计收口结果，并保持“部分实现”的真实实现评估。
+
+**Independent Test**: 单独评审治理文档，应能明确本轮已完成的是文档收口，不是 backend 闭环实现完成，并能看到后续建议与校验记录。
+
+### Implementation for User Story 3
+
+- [x] T016 [US3] Update `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` to retain the `部分实现` judgment and add this round's design-closure result and next-step recommendation
+- [x] T017 [US3] Update `docs/design/00_Management/01_Project_Progress.md` to record the `REV-002` documentation alignment action and validation outcome
+- [x] T018 [US3] Update `docs/design/00_Management/03_Task_Checklist.md` to reflect the completed `REV-002` document-maintenance tasks
+- [x] T019 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and capture the result in work notes
+- [x] T020 [US3] Run `make validate-file FILE=docs/design/00_Management/01_Project_Progress.md` and `make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md` and capture the results in work notes
+
+**Checkpoint**: Governance documents are independently reviewable and preserve the correct “部分实现” narrative.
+
+---
+
+## Final Phase: Cross-Cutting Closure
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [x] T021 [P] Re-check source-of-truth alignment across `docs/design/02_Detailed_Design/12_REV_Detailed.md`, `docs/design/03_Technical_Design/03_Interface_Design.md`, `docs/design/03_Technical_Design/01_Database_Design.md`, and `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [x] T022 [P] Re-check relative links, stable anchors, and numbering consistency across all modified files with `make check-links`
+- [x] T023 Prepare final summary from `/Volumes/Dpan/github/fujian_water_biz_doc/specs/005-rev002-billing-generation-gap/quickstart.md` and actual validation results, including modified files, remaining risks, and next-step suggestions
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1**: No dependencies; MUST finish before document edits
+- **User Story 1**: Depends on Phase 1 and provides the billing-rule baseline for later phases
+- **User Story 2**: Depends on User Story 1 wording being stable
+- **User Story 3**: Depends on User Story 1 and User Story 2 conclusions being fixed
+- **Final Phase**: Depends on all selected user stories being complete
+
+### Within Each User Story
+
+- Read required governance and target docs before editing
+- Complete target document edits before terminology and reference sync
+- Complete content edits before validation
+- Complete validation before governance ledgers are considered closed
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel during foundation review
+- `T012` can run in parallel with validation preparation once interface and database edits are drafted
+- `T021` and `T022` can run in parallel during final closure
+
+## Implementation Strategy
+
+- **MVP first**: 先完成 User Story 1，使 `REV-002` 详细设计具备独立评审价值
+- **Incremental delivery**: 再完成 User Story 2 收口接口与数据库，最后完成 User Story 3 的治理同步
+- **Validation-first closure**: 每个 story 完成后立即执行对应校验，再推进下一阶段，避免跨文档口径回滚
+
+## Notes
+
+- 本 feature 只做文档治理，不默认修改 backend 代码
+- 不得新发明 `IF-*` 编号或“特殊开账平行主表”
+- Archive 仅用于核对来源，不直接替代正式结论
+- `specs/001-rev004-accounting/checklists/scope-alignment.md` 与本轮无关，不应纳入本 feature 变更

specs/006-reminder-event-design/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: REV-006 催缴与通知事件设计收口
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-18
+**Feature**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validated against `spec.md` on 2026-03-18; no outstanding clarification markers or blocking quality gaps were found.
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

specs/006-reminder-event-design/contracts/if-ext-008.md

@@ -0,0 +1,74 @@
+# Contract: IF-EXT-008 消息触达协同接口
+
+## 1. 合同定位
+
+- 接口编号：`IF-EXT-008`
+- 归属模块：`REV-006 / CS-006`
+- 责任系统：`SYS-010`
+- 调用方：`SYS-002`
+- 合同类型：外部协同接口设计合同
+
+## 2. 业务职责
+
+`IF-EXT-008` 负责：
+
+- 承接 `SYS-002` 传入的通知任务
+- 按短信、微信公众号、站内信等渠道执行触达
+- 返回受理结果，并在后续回传最终执行结果或失败摘要
+
+`IF-EXT-008` 不负责：
+
+- 生成催缴候选对象
+- 定义催缴业务状态体系
+- 决定停复水或工单联动流程
+
+## 3. 输入合同
+
+| 字段 | 说明 | 约束 |
+|------|------|------|
+| eventNo | 业务事件号 | 必填 |
+| taskNo | 催缴任务号 | 必填 |
+| channelType | 渠道类型 | 必填 |
+| receiver | 触达对象 | 必填 |
+| messageTemplateCode | 消息模板编码 | 必填 |
+| messageParams | 模板参数 | 可为空对象 |
+| priority | 优先级 | 可选 |
+| callbackUrlOrMode | 结果回传方式 | 必填 |
+
+## 4. 输出合同
+
+### 4.1 受理返回
+
+| 字段 | 说明 |
+|------|------|
+| accepted | 是否受理 |
+| externalRequestNo | 外部请求号 |
+| acceptedTime | 受理时间 |
+| rejectReason | 拒绝原因 |
+
+### 4.2 结果回传
+
+| 字段 | 说明 |
+|------|------|
+| eventNo | 业务事件号 |
+| taskNo | 催缴任务号 |
+| deliveryStatus | 渠道执行结果 |
+| deliveryTime | 执行时间 |
+| externalResultCode | 外部结果码 |
+| externalResultMessage | 外部结果说明 |
+
+## 5. 边界合同
+
+1. `SYS-010` 的执行结果不直接定义 `REV-006` 业务态，而是由 `SYS-002` 映射为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。
+2. 若仅返回受理成功、未返回终态，则 `SYS-002` 维持 `PENDING`。
+3. 若外部长时间无终态回写，业务侧可通过人工核查进入 `MANUAL_VERIFIED`。
+4. 渠道模板、供应商协议与重试细节由 `SYS-010` 管理，不在 `REV-006` 正式设计中展开。
+
+## 6. 失败与补偿语义
+
+| 场景 | 协同要求 |
+|------|----------|
+| 渠道受理失败 | 立即回传拒绝原因，由 `SYS-002` 视情况转 `FAIL` |
+| 发送成功 | 回传成功结果，由 `SYS-002` 转 `SUCCESS` |
+| 发送失败 | 回传失败摘要，由 `SYS-002` 转 `FAIL` |
+| 无终态回写 | 允许保留 `PENDING`，由人工补记收口 |

specs/006-reminder-event-design/contracts/if-rev-013.md

@@ -0,0 +1,114 @@
+# Contract: IF-REV-013 催缴任务生成与结果承接接口
+
+## 1. 合同定位
+
+- 接口编号：`IF-REV-013`
+- 归属模块：`REV-006`
+- 责任系统：`SYS-002`
+- 协同系统：`SYS-010`
+- 合同类型：业务接口设计合同
+
+## 2. 业务职责
+
+`IF-REV-013` 负责：
+
+- 基于欠费账单、策略与渠道偏好生成催缴任务
+- 查询催缴任务状态与历史催缴记录
+- 承接消息协同后的业务侧四态状态
+- 记录人工核查补记和处置引用
+
+`IF-REV-013` 不负责：
+
+- 短信、微信、站内信等渠道实际发送
+- 停复水内部审批、派工和现场执行
+- 扩展五态以上的细粒度业务状态
+
+## 3. 输入合同
+
+### 3.1 任务生成
+
+| 字段 | 说明 | 约束 |
+|------|------|------|
+| strategyCode | 催缴策略编码 | 必填 |
+| triggerType | 触发类型 | 自动 / 人工 |
+| candidateList | 催缴候选对象集合 | 至少 1 条 |
+| channelPreference | 渠道优先级 | 至少 1 项 |
+| operator | 操作人或任务来源 | 人工触发时必填 |
+
+### 3.2 任务查询
+
+| 字段 | 说明 | 约束 |
+|------|------|------|
+| taskNo | 催缴任务号 | 与条件查询二选一 |
+| custId | 客户标识 | 可选 |
+| billPeriod | 账期 | 可选 |
+| status | 任务状态 | 仅允许四态 |
+| channelType | 渠道类型 | 可选 |
+
+### 3.3 人工核查
+
+| 字段 | 说明 | 约束 |
+|------|------|------|
+| taskNo | 催缴任务号 | 必填 |
+| verifyResult | 人工核查结果 | 当前固定映射 `MANUAL_VERIFIED` |
+| verifyNote | 核查说明 | 必填 |
+| disposalRefNo | 关联处置引用号 | 可选 |
+| operator | 核查人 | 必填 |
+
+## 4. 输出合同
+
+### 4.1 任务生成返回
+
+| 字段 | 说明 |
+|------|------|
+| interfaceCode | 固定返回 `IF-REV-013` |
+| taskNo | 生成的催缴任务号 |
+| eventNo | 业务事件号 |
+| status | 初始状态，固定为 `PENDING` |
+| taskCount | 本次生成任务数 |
+| skippedReasonSummary | 被排除对象摘要 |
+
+### 4.2 状态查询返回
+
+| 字段 | 说明 |
+|------|------|
+| taskNo | 催缴任务号 |
+| eventNo | 业务事件号 |
+| status | `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` |
+| channelType | 当前渠道 |
+| receiver | 触达对象 |
+| sendTime | 发送发起时间 |
+| lastCallbackTime | 最近回写时间 |
+| failReason | 失败原因 |
+| disposalRefs | 关联处置引用 |
+
+## 5. 业务规则合同
+
+1. 催缴对象必须来源于有效欠费账单，不得把已收费、已作废或已进入不允许催缴流程的账单纳入任务。
+2. 同一候选对象在频控窗口内不得重复生成同策略、同渠道的正式任务。
+3. 正式状态只允许四态，不扩展其他临时枚举值。
+4. 历史催缴、停水、预存短信记录按只读查询口径挂接，不表述为新建平行在线主表。
+5. 处置引用只承担追溯职责，不在本接口中展开停复水或工单内部流程。
+
+## 6. 失败与阻断语义
+
+| 场景 | 阻断要求 | 返回语义 |
+|------|----------|----------|
+| 候选账单不满足欠费前提 | 阻断生成 | 返回排除原因摘要 |
+| 策略编码无效 | 阻断生成 | 返回策略校验失败 |
+| 频控规则命中 | 可部分阻断 | 返回被跳过对象与原因 |
+| 外部结果未定 | 不强制失败 | 保持 `PENDING` 或经人工核查转 `MANUAL_VERIFIED` |
+| 外部明确失败 | 回写失败 | 更新为 `FAIL` 并记录原因 |
+
+## 7. 可追溯字段最小集
+
+- `taskNo`
+- `eventNo`
+- `strategyCode`
+- `channelType`
+- `triggerType`
+- `status`
+- `failReason`
+- `receiver`
+- `sendTime`
+- `disposalRefNo`

specs/006-reminder-event-design/data-model.md

@@ -0,0 +1,125 @@
+# Data Model: REV-006 催缴与通知事件设计收口
+
+## 1. Reminder Candidate
+
+**说明**: 催缴任务的输入对象，由欠费账单和客户上下文组合形成。  
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| candidateId | String | 候选对象标识 | 可由任务生成阶段派生，不要求独立持久化主键 |
+| custId | String | 客户标识 | 必填 |
+| accountId | String | 账户标识 | 必填 |
+| chargeIds | List<String> | 命中的欠费账单集合 | 至少 1 条 |
+| billPeriods | List<String> | 账期集合 | 必填 |
+| arrearsAmount | Decimal | 欠费总金额 | 必须大于 0 |
+| agingBucket | String | 账龄分组 | 必填 |
+| custCategory | String | 客户类别 | 必填 |
+| preferredChannels | List<String> | 渠道偏好 | 至少 1 个渠道 |
+| strategyCode | String | 命中的催缴策略编码 | 必填 |
+| frequencyWindow | String | 频控窗口 | 用于重复触达拦截 |
+
+**关系**:
+
+- 一个 `Reminder Candidate` 可生成一个或多个 `Reminder Task`
+- `Reminder Candidate` 来源于 `biz_charge`、`biz_charge_detail` 等营业账对象
+
+## 2. Reminder Strategy
+
+**说明**: 约束候选对象筛选、任务分组和渠道优先级的规则集合。  
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| strategyCode | String | 策略编码 | 唯一 |
+| strategyName | String | 策略名称 | 必填 |
+| agingRule | String | 账龄规则 | 必填 |
+| amountRule | String | 金额规则 | 必填 |
+| custCategoryRule | String | 客户类别规则 | 可为空，表示不限 |
+| channelPriority | List<String> | 渠道优先级 | 至少 1 项 |
+| frequencyControl | String | 频控规则 | 必填 |
+| disposalAttentionFlag | Boolean | 是否关注后续处置 | 必填 |
+
+**状态转换**:
+
+- 启用
+- 停用
+
+## 3. Reminder Task
+
+**说明**: 正式催缴执行单元，是 `IF-REV-013` 的核心业务对象。  
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| taskNo | String | 催缴任务号 | 唯一、必填 |
+| eventNo | String | 业务事件号 | 唯一、必填 |
+| strategyCode | String | 策略编码 | 必填 |
+| channelType | String | 执行渠道 | 必填 |
+| triggerType | String | 触发类型 | 自动 / 人工 |
+| status | String | 当前状态 | 仅允许 `PENDING` / `SUCCESS` / `FAIL` / `MANUAL_VERIFIED` |
+| chargeIds | List<String> | 关联账单 | 至少 1 条 |
+| receiver | String | 触达对象 | 可为手机号、微信标识或站内账号 |
+| sendTime | Datetime | 发送发起时间 | 可空，待触发后填写 |
+| lastCallbackTime | Datetime | 最近结果回写时间 | 可空 |
+| failReason | String | 失败原因 | `FAIL` 时建议记录 |
+| manualVerifyNote | String | 人工核查说明 | `MANUAL_VERIFIED` 时建议记录 |
+
+**状态转换**:
+
+1. 新建任务后进入 `PENDING`
+2. 外部触达成功后进入 `SUCCESS`
+3. 外部明确失败后进入 `FAIL`
+4. 外部结果长期未定或人工补记后进入 `MANUAL_VERIFIED`
+
+## 4. Reminder Result
+
+**说明**: 承接 `SYS-010` 回写结果与业务侧最终状态语义。  
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| taskNo | String | 对应任务号 | 必填 |
+| eventNo | String | 对应事件号 | 必填 |
+| status | String | 四态结果 | 必填 |
+| channelType | String | 渠道类型 | 必填 |
+| externalResultCode | String | 外部结果码 | 可空 |
+| externalResultMessage | String | 外部结果说明 | 可空 |
+| failReason | String | 业务失败原因 | `FAIL` 时可必填 |
+| callbackTime | Datetime | 回写时间 | 必填 |
+| sourceSystem | String | 回写来源系统 | 默认 `SYS-010` |
+
+## 5. Disposal Link
+
+**说明**: 催缴任务与停水、复水、工单、人工跟进之间的追溯引用。  
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| taskNo | String | 关联催缴任务号 | 必填 |
+| disposalType | String | 处置类型 | 停水 / 复水 / 工单 / 人工跟进 |
+| disposalRefNo | String | 处置引用号 | 必填 |
+| disposalStatus | String | 处置状态摘要 | 可空 |
+| linkedAt | Datetime | 建联时间 | 必填 |
+| note | String | 追溯说明 | 可空 |
+
+## 6. Governance Record
+
+**说明**: 用于治理台账登记本轮设计收口结论与后续研发建议。  
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+| reqCode | String | 需求编号 | 固定为 `SYS002-REQ-011` |
+| featureName | String | Speckit feature 名称 | 固定为 `rev006-reminder-event-design` |
+| implementationStatus | String | 当前实现判断 | `未见实现` |
+| docStatus | String | 文档状态 | 设计已收口 / 待同步 / 待验证 |
+| nextAction | String | 后续动作 | 研发立项 / 文档补证 / 治理同步 |
+| evidenceRefs | List<String> | 证据来源 | 必填 |
+
+## 7. 关系总览
+
+```text
+Reminder Strategy
+  -> Reminder Candidate
+  -> Reminder Task
+Reminder Task
+  -> Reminder Result
+  -> Disposal Link
+Governance Record
+  -> 引用 Reminder Task / Reminder Result 的设计结论与实现判断
+```

specs/006-reminder-event-design/plan.md

@@ -0,0 +1,150 @@
+# Implementation Plan: REV-006 催缴与通知事件设计收口
+
+**Branch**: `006-reminder-event-design` | **Date**: 2026-03-18 | **Spec**: [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md)
+**Input**: Feature specification from `/specs/006-reminder-event-design/spec.md`
+
+## Summary
+
+本次计划聚焦 `REV-006` 的正式文档收口，而非直接编写 backend 业务代码。目标是在既有主文档中补齐催缴对象生成规则、`IF-REV-013` / `IF-EXT-008` 的职责边界、四态结果语义、历史查询与处置追溯口径，并同步治理台账，使后续研发可基于统一口径继续立项。
+
+目标文档包括：
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+
+## Technical Context
+
+**Primary Work Product**: Markdown 正式设计文档、治理台账与 Speckit 规划工件  
+**Source of Truth Documents**:
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+- `AGENTS.md`
+
+**Reference Sources**:
+
+- `docs/guides/BACKEND_CURRENT_STATUS.md`
+- `docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md`
+- `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+
+**Validation Commands**:
+
+- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`
+- `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `make check-links`
+- `make validate-mermaid`
+
+**Target Scope**:
+
+- 收口 `REV-006` 详细设计章节
+- 收口 `IF-REV-013` 与 `IF-EXT-008` 承接口径
+- 回写 `SYS002-REQ-011` 的状态判断、后续研发切入点与治理结论
+- 规划 `01_Project_Progress.md` 与 `03_Task_Checklist.md` 的同步更新动作
+
+**Project Type**: 文档治理仓库  
+**Constraints**:
+
+- 不新增平行正式稿，只回写既有主文档或治理文档
+- 不臆造 backend 已实现能力
+- Archive 仅作为来源核对，不直接替代正式口径
+- 编号、术语、相对路径、Mermaid 图与正文必须一致
+- 正式系统名称统一为“福建水务营收系统”
+
+**Scale/Scope**: 跨文档设计收口与治理同步，覆盖详设、接口、管理台账三类文档
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **主文档归属已确认**：本次改动只落在 `12_REV_Detailed.md`、`03_Interface_Design.md`、`15_SYS002_Requirement_Breakdown.md` 及管理台账，不新增平行正式稿。
+- [x] **范围基线已确认**：`REV-006` 已同时出现在 `03_Summary_Design.md`、`12_REV_Detailed.md` 与 Archive 范围内，属于可直接推进的交集范围。
+- [x] **Archive 使用方式合规**：Archive 仅作为旧系统催缴记录、停水记录、预存短信场景的来源核对，不直接作为正式文档替身。
+- [x] **一致性影响已列出**：受影响项包括 `REV-006` 模块编号、`IF-REV-013` / `IF-EXT-008` 编号边界、四态状态集、催缴/停复水术语、历史查询口径与 Mermaid 流程图。
+- [x] **校验与台账动作已规划**：已明确单文件校验、全仓链接校验、Mermaid 校验，并规划同步更新 `01_Project_Progress.md` 与 `03_Task_Checklist.md`。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-reminder-event-design/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│   ├── if-rev-013.md
+│   └── if-ext-008.md
+└── tasks.md
+```
+
+### Repository Touchpoints
+
+```text
+docs/design/
+├── 00_Management/01_Project_Progress.md
+├── 00_Management/03_Task_Checklist.md
+├── 00_Management/15_SYS002_Requirement_Breakdown.md
+├── 01_Overview/03_Summary_Design.md
+├── 02_Detailed_Design/12_REV_Detailed.md
+├── 03_Technical_Design/03_Interface_Design.md
+└── 04_Appendix/Archive/
+```
+
+**Structure Decision**:
+
+- `12_REV_Detailed.md`：承载 `REV-006` 的业务流程、规则、核心数据与落地边界
+- `03_Interface_Design.md`：承载 `IF-REV-013` / `IF-EXT-008` 的业务接口定义与边界说明
+- `15_SYS002_Requirement_Breakdown.md`：承载 `SYS002-REQ-011` 的实现判断、建议粒度与推进说明
+- `01_Project_Progress.md`：登记本轮正式文档收口动作与验证结果
+- `03_Task_Checklist.md`：登记 `REV-006` 相关治理任务的完成状态
+
+## Phase 0: Outline & Research
+
+### Research Inputs
+
+- 既有 `REV-006` 章节是否已足够承载催缴对象生成、四态结果和联动边界
+- `IF-REV-013` / `IF-EXT-008` 的职责拆分是否与 `SYS-002` / `SYS-010` 边界一致
+- 当前 backend 未见实现骨架的结论，如何在正式文档与治理台账中保守表达
+
+### Phase 0 Deliverable
+
+- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/research.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/research.md)
+
+### Research Conclusion
+
+- 无额外 `NEEDS CLARIFICATION` 留存。
+- 计划阶段可直接以“文档先行、实现待立项”为结论进入设计与合同化表达。
+
+## Phase 1: Design & Contracts
+
+### Planned Artifacts
+
+- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md)
+- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md)
+- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-ext-008.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-ext-008.md)
+- [/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md)
+
+### Design Decisions
+
+- 以“催缴候选对象 -> 催缴任务 -> 消息协同 -> 四态回写 -> 处置追溯”的业务链路组织文档，而非按旧系统页面零散堆砌。
+- 历史催缴、停水、预存短信统一按“历史只读查询口径”承接，不额外承诺独立在线主表。
+- 合同化产物只描述接口业务语义、字段边界和责任划分，不写成 backend API 已实现证明。
+
+## Post-Design Constitution Check
+
+- [x] **主文档归属保持不变**：Phase 1 产物用于规划与任务拆解，正式结论仍回流既有主文档。
+- [x] **范围未外溢**：设计仍限定在 `REV-006` 催缴与通知收口，不扩展到停复水审批或独立消息中心建设。
+- [x] **Archive 仍为引用源**：未把 Archive 内容直接升级为独立正式稿。
+- [x] **一致性风险已收敛**：四态状态集、接口编号、协同边界和历史查询术语已统一。
+- [x] **校验闭环已具备**：已有明确验证命令、管理台账更新点和后续 tasks 拆解基础。
+
+## Complexity Tracking
+
+本次计划无宪章违例项，无需额外豁免。

specs/006-reminder-event-design/quickstart.md

@@ -0,0 +1,69 @@
+# Quickstart: REV-006 催缴与通知事件设计收口
+
+## 1. 使用目标
+
+本 quickstart 用于指导评审者或文档维护者快速完成 `REV-006` 的正式文档收口验证，不用于验证 backend 运行功能。
+
+## 2. 建议执行顺序
+
+1. 打开 [spec.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md)，确认范围、四态状态和治理结论。
+2. 对照 [plan.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/plan.md)，确认本轮只修改既有主文档与管理台账。
+3. 对照 [data-model.md](/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md)，检查催缴候选对象、任务、结果和处置引用的最小字段是否齐全。
+4. 对照 `contracts/if-rev-013.md` 与 `contracts/if-ext-008.md`，确认 `SYS-002` / `SYS-010` 分工、输入输出和失败语义一致。
+
+## 3. 正式文档修订检查点
+
+- `12_REV_Detailed.md`
+  - 是否写清催缴对象来源、策略分组、频控和四态状态
+  - 是否明确停复水/工单只作为联动边界和追溯引用
+- `03_Interface_Design.md`
+  - 是否统一 `IF-REV-013` 为正式业务接口编号
+  - 是否区分 `IF-REV-013` 与 `IF-EXT-008` 的责任边界
+- `15_SYS002_Requirement_Breakdown.md`
+  - 是否保持 `SYS002-REQ-011` 为“未见实现”
+  - 是否明确“文档已收口，backend 未见明确实现骨架”
+- `01_Project_Progress.md` / `03_Task_Checklist.md`
+  - 是否登记本轮文档收口与验证动作
+
+## 4. 最小验证命令
+
+```bash
+make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md
+make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md
+make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md
+make check-links
+make validate-mermaid
+```
+
+## 5. 完成判定
+
+满足以下条件即可进入 `/speckit.tasks`：
+
+- `REV-006` 的业务规则、接口边界、历史查询和处置追溯口径已统一
+- `SYS002-REQ-011` 的实现判断与后续研发切入点已写入治理台账
+- 验证命令已纳入计划，且无新增平行正式稿
+
+## 6. 2026-03-19 实施结果
+
+### 已完成文档
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- `docs/design/00_Management/01_Project_Progress.md`
+- `docs/design/00_Management/03_Task_Checklist.md`
+
+### 验证结果
+
+- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`：通过，0 个问题
+- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`：通过，0 个问题
+- `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`：通过，0 个问题
+- `make check-links`：通过，当前检查范围内未发现断链
+- `make check-mermaid-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`：已确认目标文件存在 6 个 Mermaid 图表
+- `make validate-mermaid`：已执行两次，但在当前环境下未返回最终结果；结合 Makefile 逻辑，该目标只校验仓库根目录 `*.md`，未直接覆盖本轮主要修改文件，后续如需全仓 Mermaid 终态结果，应单独排查该目标在当前环境中的阻塞原因
+
+### 当前结论
+
+- `REV-006` 已完成 implement 阶段的正式文档二次收口
+- `SYS002-REQ-011` 继续维持“未见实现”，但 Speckit 工件链、正式文档口径与治理台账已对齐
+- 当前剩余风险不是文档口径缺失，而是后续 backend 立项与 `make validate-mermaid` 全仓目标在本环境中的执行阻塞

specs/006-reminder-event-design/research.md

@@ -0,0 +1,46 @@
+# Phase 0 Research: REV-006 催缴与通知事件设计收口
+
+## Decision 1: 以既有主文档承载 `REV-006` 收口
+
+**Decision**: 正式设计收口继续落在 `12_REV_Detailed.md`、`03_Interface_Design.md` 与 `15_SYS002_Requirement_Breakdown.md`，不新建平行正式稿。  
+**Rationale**: `REV-006` 已在概要、详设、接口与治理台账中具备入口，当前问题是规则与边界不够收敛，而不是缺少载体。继续使用主文档符合单一真源原则。  
+**Alternatives considered**:
+
+- 新建独立“催缴设计说明书”：会制造平行正式稿，违背宪章。
+- 仅在 spec 工件中描述：无法替代正式交付文档与治理台账。
+
+## Decision 2: `SYS-002` 与 `SYS-010` 按“业务侧任务控制 / 渠道侧触达执行”分界
+
+**Decision**: `SYS-002` 负责催缴对象筛选、任务生成、事件编号、四态状态承接、历史查询与处置引用；`SYS-010` 负责短信、微信、站内信等渠道触达及结果回传。  
+**Rationale**: 该分界已在 `12_REV_Detailed.md` 与 `03_Interface_Design.md` 形成一致表达，能够避免“催缴任务生成”和“消息发送执行”职责混写。  
+**Alternatives considered**:
+
+- 由 `SYS-010` 同时负责催缴任务控制：会让外部系统承担业务主控，不符合现有模块分工。
+- 由 `SYS-002` 同时负责所有消息发送：会弱化 `IF-EXT-008` 的外部协同边界。
+
+## Decision 3: 正式状态集固定为四态
+
+**Decision**: `REV-006` 状态集固定为 `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`。  
+**Rationale**: 四态已在详设与接口文档中同步表达，且足以覆盖受理中、成功、失败、人工补记三类核心语义。增加更多细粒度状态会放大实现假设。  
+**Alternatives considered**:
+
+- 增加“已阅读”“已补发”等状态：超出当前正式口径，也缺少 backend 证据支持。
+- 仅保留成功/失败二态：不足以表达异步回写与人工核查场景。
+
+## Decision 4: 历史催缴、停水、预存短信按只读查询口径承接
+
+**Decision**: 旧系统催缴记录、停水记录、预存短信记录统一作为历史查询和追溯范围承接，不默认扩展为新系统已确认在线主表。  
+**Rationale**: 当前 backend 未确认独立催缴台账、停水汇总表等实体；保守表达可同时满足迁移查询需求和事实一致性。  
+**Alternatives considered**:
+
+- 直接定义新在线主表：缺少代码和数据库证据。
+- 完全忽略历史场景：会让迁移核查、客户历史查询和处置追溯失去正式口径。
+
+## Decision 5: 当前实施结论维持“文档已收口，backend 未见明确实现骨架”
+
+**Decision**: 计划阶段保留 `SYS002-REQ-011` 为“未见实现”，并把本轮产出定位为文档收口和后续研发立项输入。  
+**Rationale**: 现有治理文档已经给出相同结论，且当前未检索到明确的 `Reminder/Message/Notice` controller/service 骨架。  
+**Alternatives considered**:
+
+- 升级为“部分实现”：会放大现有消息协同或历史查询描述，和证据不匹配。
+- 直接按“已实现”处理：与仓库现状冲突。

specs/006-reminder-event-design/spec.md

@@ -0,0 +1,126 @@
+# Feature Specification: REV-006 催缴与通知事件设计收口
+
+**Feature Branch**: `006-reminder-event-design`
+**Created**: 2026-03-18
+**Status**: Ready for Planning
+**Input**: User description: "rev006-reminder-event-design"
+
+## Document Scope & Sources *(mandatory)*
+
+- **Target documents**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/design/00_Management/01_Project_Progress.md`
+  - `docs/design/00_Management/03_Task_Checklist.md`
+- **Primary source of truth**:
+  - `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+  - `docs/design/03_Technical_Design/03_Interface_Design.md`
+  - `docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+  - `docs/design/01_Overview/03_Summary_Design.md`
+  - `AGENTS.md`
+- **Reference sources**:
+  - `docs/guides/BACKEND_CURRENT_STATUS.md`
+  - `docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md`
+  - `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
+- **Scope decision**: In scope. 本 feature 聚焦 `REV-006` 催缴与通知的正式设计收口，补齐催缴对象生成、任务分组、`IF-REV-013` / `IF-EXT-008` 协同边界、四态状态语义、历史查询口径、停复水/工单联动追溯和后续研发立项输入；不在本轮直接承诺 backend 已落地催缴业务实现。
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - 收口催缴任务生成规则 (Priority: P1)
+
+作为文档维护者，我需要把 `REV-006` 的催缴触发时机、催缴对象筛选条件、策略分组规则和四态状态定义写清楚，使评审者能够明确欠费账单如何进入催缴任务，以及哪些场景属于自动催缴、人工补发或人工核查补记。
+
+**Why this priority**: 当前 `REV-006` 已有第一轮场景描述，但后续研发立项仍依赖更清晰的触发规则、筛选条件和状态语义。
+
+**Independent Test**: 单独评审 `12_REV_Detailed.md` 中 `REV-006` 章节，应能明确催缴对象来源、触发规则、四态状态和人工核查边界。
+
+**Acceptance Scenarios**:
+
+1. **Given** 当前文档只概括“按策略分组催缴任务”， **When** 评审者阅读补齐后的详细设计， **Then** 能明确欠费账单、账龄、金额、客户类别、渠道偏好和频控规则如何形成催缴对象与任务。
+2. **Given** 后续需要据此拆解研发任务， **When** 维护者依据该规格评估实现切入点， **Then** 能区分自动催缴、人工补发、人工核查补记和停复水联动的边界。
+
+---
+
+### User Story 2 - 统一 IF-REV-013 与消息协同边界 (Priority: P2)
+
+作为接口设计评审者，我需要看到 `IF-REV-013` 和 `IF-EXT-008` 的职责分工、请求输出、回写字段和四态结果承接口径，使 `SYS-002` 与 `SYS-010` 的边界不再停留在抽象表述。
+
+**Why this priority**: `REV-006` 的核心风险在于业务筛选、任务状态承接和外部通知执行边界不清，容易出现“任务生成”和“消息发送”职责混写。
+
+**Independent Test**: 单独评审接口主文档和需求拆解台账，应能确认 `IF-REV-013` 的业务侧职责、`IF-EXT-008` 的外部协同职责以及四态回写字段。
+
+**Acceptance Scenarios**:
+
+1. **Given** 评审者查看接口设计， **When** 阅读 `IF-REV-013` 章节， **Then** 能明确任务生成、任务查询、人工核查和结果承接的请求路径、字段与状态语义。
+2. **Given** 评审者查看需求拆解文档， **When** 阅读 `SYS002-REQ-011` 对应内容， **Then** 能明确当前属于“设计已收口、实现未见骨架”的状态，而不是误判为已实现。
+
+---
+
+### User Story 3 - 形成治理与研发切入结论 (Priority: P3)
+
+作为后续立项和治理跟踪人员，我需要在台账和进度记录中看到 `REV-006` 的当前结论、最小实现切入点和校验动作，避免文档收口后仍无法指导后续研发排期。
+
+**Why this priority**: `REV-006` 当前在治理台账中属于未见实现，需要通过本轮 feature 明确“文档先行、实现待立项”的真实结论和后续切入点。
+
+**Independent Test**: 单独检查治理文档，应能定位 `REV-006` 当前状态、最小研发切入点、台账同步动作和验证要求。
+
+**Acceptance Scenarios**:
+
+1. **Given** 项目需要安排后续研发排期， **When** 查看需求拆解和项目进度， **Then** 能明确 `REV-006` 当前是设计收口完成、backend 未见明确实现骨架、可继续立项推进的状态。
+2. **Given** 本轮完成正式文档修订， **When** 查看进度与任务清单， **Then** 能定位本次 `REV-006` 文档治理动作及其最小校验结果。
+
+---
+
+### Edge Cases
+
+- 当欠费账单已被收费、作废或进入其他处置流程时，催缴对象是否仍可进入任务生成，文档必须如何表达排除条件？
+- 当 `SYS-010` 只返回发送受理结果而未立即返回终态时，四态状态如何在 `SYS-002` 侧保持一致？
+- 当旧系统存在催缴记录、停水记录和预存短信等历史查询场景，但当前 backend 未确认独立落表时，文档如何保持“历史只读承接”而不误写为现成在线表？
+- 当人工核查补记场景发生时，哪些字段必须记录核查说明、关联任务号和后续处置引用？
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Specification MUST identify the exact target documents for `REV-006` reminder-event alignment and governance sync.
+- **FR-002**: Specification MUST identify `12_REV_Detailed.md`、`03_Interface_Design.md`、`15_SYS002_Requirement_Breakdown.md` as the main source-of-truth set for this feature.
+- **FR-003**: Specification MUST record that this feature is in scope only for reminder-candidate generation, task rules, `IF-REV-013` / `IF-EXT-008` interface boundary, four-state result semantics, historical query boundary, and governance sync.
+- **FR-004**: Specification MUST preserve the single-source-of-truth model and MUST NOT create a parallel formal design document for `REV-006`.
+- **FR-005**: Specification MUST define reminder-candidate selection conditions, including arrears status, aging, amount, customer category, channel preference, strategy grouping, and frequency-control boundary.
+- **FR-006**: Specification MUST define the formal four-state reminder result set as `PENDING`、`SUCCESS`、`FAIL`、`MANUAL_VERIFIED`, including the intended meaning of each state.
+- **FR-007**: Specification MUST define the exact business boundary of `IF-REV-013`, including task generation, task query, manual verification, result acceptance, and historical query support.
+- **FR-008**: Specification MUST define the external collaboration boundary of `IF-EXT-008`, clarifying that `SYS-010` is responsible for channel delivery while `SYS-002` retains business-side task and state control.
+- **FR-009**: Specification MUST define the minimum write-back and traceability fields for reminder results, including task number, event number, strategy code, channel type, trigger type, status, failure reason, and disposal reference.
+- **FR-010**: Specification MUST define how reminder results link to stop-water, restore-water, work-order, or manual follow-up references without expanding those downstream internal workflows.
+- **FR-011**: Specification MUST define historical query and export expectations for reminder records, including customer, bill period, reminder channel, target receiver, send time, execution result, related bills, and disposal references.
+- **FR-012**: Specification MUST explicitly capture the current implementation judgment as “文档已收口，backend 未见明确催缴/通知业务实现骨架” unless stronger evidence is found later.
+- **FR-013**: Specification MUST identify the minimum validation actions after document updates, including affected file validation, link checks, and Mermaid checks where flows are updated.
+- **FR-014**: Specification MUST state that important formal document changes under this feature require synchronized updates to `01_Project_Progress.md` and `03_Task_Checklist.md`.
+
+### Assumptions
+
+- 本 feature 以正式文档收口和后续研发立项准备为目标，默认不在本轮直接承诺 backend 业务代码实现。
+- `IF-REV-013` 继续作为 `REV-006` 的正式业务接口编号，不复用其他 `IF-REV-*` 编号。
+- `SYS-010` 负责短信、微信公众号、站内信等触达执行；`SYS-002` 保留催缴对象筛选、任务生成、四态状态承接和历史查询职责。
+- 当前 backend 中未见明确的 `Reminder/Message/Notice` 业务控制器或服务骨架，因此实现状态保持“未见实现”。
+- 催缴记录、停复水记录和预存短信等历史场景在本轮按“历史只读查询口径”承接，不默认要求新建平行在线主表。
+
+### Key Entities *(include if feature involves data)*
+
+- **Reminder Candidate**: 由欠费账单、账龄、欠费金额、客户类别、联系方式和命中策略组成的催缴输入对象。
+- **Reminder Strategy**: 定义账龄规则、金额规则、客户类别规则、渠道优先级、频控策略和后续联动关注条件的策略对象。
+- **Reminder Task**: 一次正式催缴执行单元，至少包含 `taskNo`、`eventNo`、`strategyCode`、`channelType`、`triggerType`、`status` 和关联账单集合。
+- **Reminder Result**: 催缴任务的四态结果及其失败原因、执行时间、外部回写摘要和业务侧处置引用。
+- **Disposal Link**: 催缴结果与停复水、工单、人工核查等后续处置之间的追溯引用对象。
+- **Governance Record**: 用于在需求拆解、项目进度和任务清单中登记本轮 `REV-006` 收口结论和后续研发建议的治理记录。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 评审者可在 5 分钟内从规格中定位 `REV-006` 的目标文档、催缴对象生成规则、接口边界和排除项。
+- **SC-002**: 规格中至少覆盖 3 类独立可评审内容：催缴任务生成规则、`IF-REV-013` / `IF-EXT-008` 边界、治理与研发切入结论。
+- **SC-003**: 规格明确区分至少 6 项关键任务或结果要素，如 `taskNo`、`eventNo`、`strategyCode`、`channelType`、`triggerType`、`status`、失败原因、处置引用。
+- **SC-004**: 后续执行 `/speckit.plan` 时，规划者无需再补充范围澄清即可将工作拆分为详细设计收口、接口收口、治理同步和实现切入点评估四类任务。
+- **SC-005**: 规格明确列出全部必要验证动作，审阅者可直接据此执行至少 4 项文档校验或一致性检查。

specs/006-reminder-event-design/tasks.md

@@ -0,0 +1,164 @@
+# Tasks: REV-006 催缴与通知事件设计收口
+
+**Input**: Design documents from `/specs/006-reminder-event-design/`
+**Prerequisites**: `plan.md` (required), `spec.md` (required), `research.md`, `data-model.md`, `contracts/`, `quickstart.md`
+
+**Validation**: Validation tasks are NOT optional in this repository. Every document change task set includes applicable validation and ledger-sync tasks.
+
+**Organization**: Tasks are grouped by user story so each document-maintenance slice can be completed, reviewed, and validated independently.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (`US1`, `US2`, `US3`)
+- Every task names the exact file path to update or validate
+
+## Phase 1: Setup
+
+**Purpose**: Confirm the working boundary, source-of-truth set, and impacted files before editing formal documents.
+
+- [x] T001 Confirm target files and impacted chapters in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/spec.md`
+- [x] T002 Confirm source-of-truth and allowed references in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/plan.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/research.md`
+- [x] T003 [P] Confirm entity and contract inputs in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-ext-008.md`
+- [x] T004 [P] Confirm governance sync targets in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+
+---
+
+## Phase 2: Foundational
+
+**Purpose**: Establish the shared editing baseline that all user stories depend on.
+
+- [x] T005 Normalize `REV-006`, `IF-REV-013`, `IF-EXT-008`, and four-state terminology alignment notes in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/plan.md`
+- [x] T006 Identify exact `REV-006` anchors, Mermaid scope, and cross-reference touchpoints in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [x] T007 Map governance evidence and current implementation conclusion for `SYS002-REQ-011` in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+
+---
+
+## Phase 3: User Story 1 - 收口催缴任务生成规则 (Priority: P1) 🎯 MVP
+
+**Goal**: 补齐 `REV-006` 在详细设计中的催缴对象生成、策略分组、频控边界、四态状态和历史只读承接口径。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-006` 章节，应能明确催缴对象来源、排除条件、四态状态、人工核查边界和停复水联动追溯关系。
+
+### Implementation for User Story 1
+
+- [x] T008 [US1] Update `REV-006` rules, candidate selection, frequency-control, and exclusion conditions in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [x] T009 [US1] Sync `Reminder Candidate`, `Reminder Task`, `Reminder Result`, and `Disposal Link` field coverage in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` using `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/data-model.md`
+- [x] T010 [US1] Align historical reminder, stop-water, and prestored-message read-only boundary wording in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- [x] T011 [US1] Run `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md`
+- [x] T012 [US1] Run `make validate-mermaid` for `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md` flow updates and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md`
+
+**Checkpoint**: User Story 1 is reviewable and validated independently.
+
+---
+
+## Phase 4: User Story 2 - 统一 IF-REV-013 与消息协同边界 (Priority: P2)
+
+**Goal**: 在接口主文档中统一 `IF-REV-013` 与 `IF-EXT-008` 的职责分工、输入输出、四态回写和失败阻断语义。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`，应能区分 `SYS-002` 的业务任务控制职责与 `SYS-010` 的渠道触达职责，并定位最小回写字段。
+
+### Implementation for User Story 2
+
+- [x] T013 [US2] Update `IF-REV-013` business boundary, request paths, and state semantics in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [x] T014 [US2] Update `IF-EXT-008` collaboration boundary, acceptance/callback semantics, and failure mapping in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`
+- [x] T015 [US2] [P] Sync minimum traceability fields and manual-verify/write-back semantics in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md` using `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/contracts/if-rev-013.md`
+- [x] T016 [US2] Run `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md`
+- [x] T017 [US2] Run `make check-links` after interface document updates and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md`
+
+**Checkpoint**: User Story 2 is reviewable and validated independently.
+
+---
+
+## Phase 5: User Story 3 - 形成治理与研发切入结论 (Priority: P3)
+
+**Goal**: 在需求拆解和管理台账中沉淀 `REV-006` 的当前状态、最小研发切入点、文档收口动作和验证结论。
+
+**Independent Test**: 单独评审 `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`、`/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`、`/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`，应能定位 `SYS002-REQ-011` 的“未见实现”判断、本轮文档收口和后续研发建议。
+
+### Implementation for User Story 3
+
+- [x] T018 [US3] Update `SYS002-REQ-011` implementation judgment, evidence wording, and next-step recommendation in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [x] T019 [US3] Update the REV-006 change record and validation summary in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`
+- [x] T020 [US3] Update the REV-006 governance completion items in `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`
+- [x] T021 [US3] Run `make validate-file FILE=docs/design/00_Management/15_SYS002_Requirement_Breakdown.md` and record the result in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md`
+- [x] T022 [US3] Re-check that `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md` and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md` reflect the same REV-006 closure status
+
+**Checkpoint**: User Story 3 is reviewable and validated independently.
+
+---
+
+## Final Phase: Polish & Cross-Cutting Concerns
+
+**Purpose**: Ensure repository-wide consistency after all story slices are complete.
+
+- [x] T023 [P] Re-check `REV-006`, `IF-REV-013`, `IF-EXT-008`, and four-state terminology consistency across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/15_SYS002_Requirement_Breakdown.md`
+- [x] T024 [P] Re-check relative links, anchors, and Mermaid consistency across `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/03_Technical_Design/03_Interface_Design.md`, `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/01_Project_Progress.md`, and `/Volumes/Dpan/github/fujian_water_biz_doc/docs/design/00_Management/03_Task_Checklist.md`
+- [x] T025 Prepare final delivery summary and remaining-risk note in `/Volumes/Dpan/github/fujian_water_biz_doc/specs/006-reminder-event-design/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup**: No dependencies; must finish before document edits
+- **Foundational**: Depends on Setup and must finish before user story execution
+- **US1**: Depends on Foundational and is the MVP slice
+- **US2**: Depends on US1 terminology and boundary baseline
+- **US3**: Depends on US1 and US2 conclusions so governance wording can reflect final design state
+- **Final Phase**: Depends on all selected user stories being complete
+
+### User Story Dependency Graph
+
+```text
+US1 -> US2 -> US3
+ \______________-> Final Phase
+```
+
+### Within Each User Story
+
+- Update target document content before running validation
+- Complete validation before marking governance sync as done
+- Complete ledger sync before final cross-check
+
+## Parallel Execution Examples
+
+### US1
+
+```text
+T008 -> T009
+T010 can run after T008 in parallel with T009
+```
+
+### US2
+
+```text
+T013 -> T014
+T015 can run in parallel once T013 and T014 establish the final interface wording
+```
+
+### US3
+
+```text
+T019 and T020 can run in parallel after T018
+```
+
+## Implementation Strategy
+
+### MVP First
+
+先完成 US1，只收口 `12_REV_Detailed.md` 的 `REV-006` 规则与状态语义，形成最小可评审增量。
+
+### Incremental Delivery
+
+1. 用 US1 固化催缴对象、四态状态和历史只读边界。
+2. 用 US2 固化 `IF-REV-013` / `IF-EXT-008` 的接口职责与回写语义。
+3. 用 US3 回写治理台账和后续研发切入点。
+4. 最后统一做跨文档一致性复核和交付摘要。
+
+## Notes
+
+- 所有任务均保持“主文档单一真源”原则，不新增平行正式稿。
+- Archive 只用于核对来源，不作为正式结论直接输出。
+- 本任务清单面向文档实施，不默认包含 backend 代码开发任务。