shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

business-feature-docs

在docs/business-features/{Module}/中创建或更新EasyPlatform业务功能文档。当被要求记录某个功能、创建模块文档、更新功能文档或添加详细的功能规范时使用。触发词包括“feature docs”、“business feature documentation”、“module documentation”、“document feature”、“update feature docs”。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包
<!-- SOURCE OF TRUTH: docs/templates/skills/business-feature-docs/SKILL.md --> <!-- Synced to: .claude/skills/ and .github/skills/ -->

EasyPlatform Business Feature Documentation

Generate comprehensive business feature documentation following the GOLD STANDARD template pattern.

GOLD STANDARD Reference: docs/features/README.ExampleFeature1.md (Example App) Template File: docs/templates/detailed-feature-docs-template.md

Output Structure

All documentation MUST be placed in the correct folder structure:

docs/
├── BUSINESS-FEATURES.md              # Master index (UPDATE if new module)
└── business-features/
    ├── {Module}/                     # Module folder
    │   ├── README.md                 # Complete module documentation
    │   ├── INDEX.md                  # Navigation hub
    │   ├── API-REFERENCE.md          # Endpoint documentation
    │   ├── TROUBLESHOOTING.md        # Issue resolution guide
    │   └── detailed-features/
    │       ├── README.{FeatureName}.md     # Deep dive (~1000 lines)
    │       └── README.{FeatureName}.ai.md  # AI companion (~300 lines)
    └── ...

MANDATORY 26-SECTION STRUCTURE

All feature documentation in detailed-features/ MUST follow this section order:

| # | Section | Stakeholder Focus | | --- | -------------------------- | ---------------------- | | 1 | Executive Summary | PO, BA | | 2 | Business Value | PO, BA | | 3 | Business Requirements | PO, BA | | 4 | Business Rules | BA, Dev | | 5 | Process Flows | BA, Dev, Architect | | 6 | Design Reference | BA, UX, Dev | | 7 | System Design | Dev, Architect | | 8 | Architecture | Dev, Architect | | 9 | Domain Model | Dev, Architect | | 10 | API Reference | Dev, Architect | | 11 | Frontend Components | Dev | | 12 | Backend Controllers | Dev | | 13 | Cross-Service Integration | Dev, Architect | | 14 | Security Architecture | Dev, Architect | | 15 | Performance Considerations | Dev, Architect, DevOps | | 16 | Implementation Guide | Dev | | 17 | Test Specifications | QA | | 18 | Test Data Requirements | QA | | 19 | Edge Cases Catalog | QA, Dev | | 20 | Regression Impact | QA | | 21 | Troubleshooting | Dev, QA, DevOps | | 22 | Operational Runbook | DevOps | | 23 | Roadmap and Dependencies | PO, BA | | 24 | Related Documentation | All | | 25 | Glossary | PO, BA | | 26 | Version History | All |

Phase 1: Module Detection & Context Gathering

Step 1.1: Identify Target Module

Determine which module the feature belongs to by:

  1. User explicitly specifies module name
  2. Feature name/domain implies module
  3. Search codebase for feature-related entities/commands

Step 1.2: Read Existing Documentation

Before creating new docs, read existing structure:

1. Read docs/BUSINESS-FEATURES.md (master index)
2. Read docs/business-features/{Module}/INDEX.md (if exists)
3. Read docs/business-features/{Module}/README.md (if exists)
4. Identify what already exists vs what needs creation/update

Step 1.3: Codebase Analysis

Gather evidence from source code:

  • Entities: src/Services/{Module}/{Module}.Domain/Entities/
  • Commands: src/Services/{Module}/{Module}.Application/UseCaseCommands/
  • Queries: src/Services/{Module}/{Module}.Application/UseCaseQueries/
  • Controllers: src/Services/{Module}/{Module}.Service/Controllers/
  • Frontend: src/Frontend/apps/playground-{module}/ or src/Frontend/libs/apps-domains/

Phase 2: Key Format Examples

Quick Navigation by Role

| Role                 | Priority Sections                                                   | Key Concerns                                   |
| -------------------- | ------------------------------------------------------------------- | ---------------------------------------------- |
| **Product Owner**    | Executive Summary, Business Value, Roadmap                          | ROI, scope, timeline, dependencies             |
| **Business Analyst** | Business Requirements, Business Rules, Process Flows                | Requirements traceability, acceptance criteria |
| **Developer**        | Architecture, Domain Model, API Reference, Implementation Guide     | Code patterns, integration points              |
| **Tech Architect**   | System Design, Architecture, Cross-Service Integration, Performance | System design, scalability, tech debt          |
| **QA Engineer**      | Test Specifications, Test Data Requirements, Edge Cases Catalog     | Test coverage, automation feasibility          |
| **QC Analyst**       | All sections                                                        | Evidence verification, documentation accuracy  |
| **DevOps**           | Operational Runbook, Troubleshooting, Performance                   | Deployment, monitoring, incident response      |

Business Requirements (FR-XX)

#### FR-{MOD}-01: {Requirement Title}

| Aspect          | Details                           |
| --------------- | --------------------------------- |
| **Description** | {What this requirement enables}   |
| **Scope**       | {Who can use / affected entities} |
| **Validation**  | {Business rules and constraints}  |
| **Priority**    | {P0/P1/P2/P3}                     |
| **Evidence**    | `{FilePath}:{LineRange}`          |

User Stories (US-XX)

#### US-{MOD}-01: {Story Title}

**As a** {role}
**I want** {goal/desire}
**So that** {benefit/value}

**Acceptance Criteria**:

- [ ] AC-01: {Criterion with evidence reference}
- [ ] AC-02: {Criterion with evidence reference}

**Related Requirements**: FR-{MOD}-01, FR-{MOD}-02
**Evidence**: `{FilePath}:{LineRange}`

Business Value

### Value Proposition

| Value Type      | Description                | Impact  | Quantification                 |
| --------------- | -------------------------- | ------- | ------------------------------ |
| Revenue         | {Revenue impact}           | {H/M/L} | {$ or % if available}          |
| Efficiency      | {Time/cost savings}        | {H/M/L} | {Hours/costs saved}            |
| User Experience | {UX improvement}           | {H/M/L} | {NPS/satisfaction improvement} |
| Compliance      | {Regulatory/audit benefit} | {H/M/L} | {Risk reduction}               |

Business Rules

### Validation Rules

| Rule ID     | Rule        | Condition        | Action        | Evidence        |
| ----------- | ----------- | ---------------- | ------------- | --------------- |
| BR-{MOD}-01 | {Rule name} | {When condition} | {Then action} | `{File}:{Line}` |

### State Transitions

| From State | Event    | To State | Conditions   | Evidence        |
| ---------- | -------- | -------- | ------------ | --------------- |
| Draft      | Activate | Active   | {Conditions} | `{File}:{Line}` |

Technical Decisions Log

### Technical Decisions Log

| Decision         | Date   | Options Considered | Chosen   | Rationale | Evidence        |
| ---------------- | ------ | ------------------ | -------- | --------- | --------------- |
| {Decision title} | {Date} | {Option A, B}      | {Chosen} | {Why}     | `{File}:{Line}` |

### Technical Debt

| Item        | Severity | Impact   | Remediation Plan | Evidence        |
| ----------- | -------- | -------- | ---------------- | --------------- |
| {Debt item} | H/M/L    | {Impact} | {Plan}           | `{File}:{Line}` |

Test Specifications (TC-XX)

Test Summary Table (MANDATORY):

| Category    | P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low) |  Total  |
| ----------- | :-----------: | :-------: | :---------: | :------: | :-----: |
| {Category1} |      {N}      |    {N}    |     {N}     |   {N}    |   {N}   |
| **Total**   |    **{N}**    |  **{N}**  |   **{N}**   | **{N}**  | **{N}** |

Test Case Format:

#### TC-{MOD}-001: {Test Name} [P0]

**Acceptance Criteria**:

- ✅ {Passing criteria 1}
- ✅ {Passing criteria 2}

**GIVEN** {initial context}
**WHEN** {action performed}
**THEN** {expected outcome}

**Edge Cases**:

- ❌ {Invalid scenario} → {Expected error/behavior}

**Evidence**: `{FilePath}:{LineRange}`

Edge Cases Catalog

### Input Validation Edge Cases

| ID    | Scenario     | Input         | Expected Behavior | Evidence        |
| ----- | ------------ | ------------- | ----------------- | --------------- |
| EC-01 | Empty string | `""`          | Validation error  | `{File}:{Line}` |
| EC-02 | Max length   | `{256 chars}` | Truncate/Error    | `{File}:{Line}` |

### Business Logic Edge Cases

| ID    | Scenario   | Condition   | Expected Behavior | Evidence        |
| ----- | ---------- | ----------- | ----------------- | --------------- |
| EC-10 | {Scenario} | {Condition} | {Behavior}        | `{File}:{Line}` |

Operational Runbook

### Deployment Checklist

- [ ] Database migrations applied
- [ ] Configuration values verified
- [ ] Health checks passing
- [ ] Smoke tests executed
- [ ] Rollback plan ready

### Monitoring

| Metric     | Alert Threshold | Dashboard       | Escalation |
| ---------- | --------------- | --------------- | ---------- |
| Error Rate | >1%             | {Dashboard URL} | {Team}     |

Evidence Verification Protocol

## Evidence Verification Protocol

### Verification Summary

| Category              | Total Claims | Verified | Stale   | Missing | Last Verified |
| --------------------- | ------------ | -------- | ------- | ------- | ------------- |
| Business Requirements | {N}          | {N}      | {N}     | {N}     | {Date}        |
| Architecture          | {N}          | {N}      | {N}     | {N}     | {Date}        |
| Test Specifications   | {N}          | {N}      | {N}     | {N}     | {Date}        |
| **Total**             | **{N}**      | **{N}**  | **{N}** | **{N}** |               |

### Evidence Verification Table

| Claim ID    | Claim   | File     | Documented Lines | Actual Lines | Status     | Verified By |
| ----------- | ------- | -------- | ---------------- | ------------ | ---------- | ----------- |
| FR-{MOD}-01 | {Claim} | `{File}` | L{X}-{Y}         | L{X}-{Y}     | ✅ Verified | {Name/Date} |

### Audit Trail

| Date   | Action               | Reviewer | Notes   |
| ------ | -------------------- | -------- | ------- |
| {Date} | Initial verification | {Name}   | {Notes} |

Security Architecture

### Authorization Matrix

| Role    | View  | Create | Edit  | Delete | Special Permissions |
| ------- | :---: | :----: | :---: | :----: | ------------------- |
| Admin   |   ✅   |   ✅    |   ✅   |   ✅    | Full access         |
| Manager |   ✅   |   ✅    |   ✅   |   ❌    | Company scope       |
| User    |   ✅   |   ❌    |   ❌   |   ❌    | Own data only       |

### Data Protection

| Data Type | Protection        | Evidence        |
| --------- | ----------------- | --------------- |
| PII       | Encrypted at rest | `{File}:{Line}` |

Glossary

## Glossary

| Term      | Definition                                  | Context      |
| --------- | ------------------------------------------- | ------------ |
| {Term}    | {Definition for non-technical stakeholders} | {Where used} |
| {Acronym} | {Full form and meaning}                     | {Where used} |

Phase 2.5: AI Companion Generation

Generate AI-agent optimized companion file alongside the comprehensive documentation.

Output: docs/business-features/{Module}/detailed-features/README.{FeatureName}.ai.md Template: docs/templates/detailed-feature-docs-template.ai.md

AI Companion Structure (10 Sections, ~260 lines)

| Section | Content | Source from Full Doc | | --------------- | ---------------------------------- | ------------------------- | | Context | Purpose, entities, service | Executive Summary | | File Locations | Exact paths to all key files | Implementation Guide | | Domain Model | Properties, expressions | Domain Model | | API Contracts | Endpoints, request/response shapes | API Reference | | Business Rules | Validation, state transitions | Business Rules | | Patterns | Required ✅ / Anti-patterns ❌ | Architecture | | Integration | Events, dependencies | Cross-Service Integration | | Security | Authorization matrix | Security Architecture | | Test Scenarios | Key GIVEN/WHEN/THEN cases | Test Specifications | | Quick Reference | Decision tree, code snippets | Implementation Guide |

Compression Rules

  1. Tables over prose - Convert paragraphs to table rows
  2. Paths over descriptions - File:Line over "located in..."
  3. Signatures over examples - { id: string } → { entity: Dto } over full code
  4. Decisions over explanations - What to do, not why

AI Companion Quality Check

  • [ ] File size ≤300 lines
  • [ ] All file paths are exact and current
  • [ ] API contracts include request/response shapes
  • [ ] Business rules have evidence references
  • [ ] Patterns section has ✅/❌ markers
  • [ ] Evidence chain preserved from full doc

Phase 3: Master Index Update

After creating/updating module docs, update docs/BUSINESS-FEATURES.md:

  1. Read current content
  2. Verify module is listed in the "Detailed Module Documentation" table
  3. Add link if missing: 
    | **{Module}** | [Description] | [View Details](./business-features/{Module}/README.md) |

Anti-Hallucination Protocols

EVIDENCE_CHAIN_VALIDATION

  • Every feature claim MUST have code reference with file path and line numbers
  • Read actual source files before documenting
  • Never assume behavior without code evidence

ACCURACY_CHECKPOINT

Before writing any documentation:

  • "Have I read the actual code?"
  • "Are my line number references accurate?"
  • "Can I provide a code snippet as evidence?"

Quality Checklist

  • [ ] All 26 mandatory sections present in correct order
  • [ ] Quick Navigation by Role included
  • [ ] Executive Summary with key capabilities
  • [ ] Business Value with ROI analysis
  • [ ] User Stories with acceptance criteria (US-XX format)
  • [ ] Business Requirements use FR-{MOD}-XX format
  • [ ] Business Rules with state transitions
  • [ ] Process Flows with diagrams
  • [ ] System Design with technical decisions log
  • [ ] Security Architecture with authorization matrix
  • [ ] Performance Considerations with targets
  • [ ] Implementation Guide with code examples
  • [ ] Test Summary table with P0-P3 counts
  • [ ] Test Data Requirements and fixtures
  • [ ] Edge Cases Catalog (validation, business, concurrency)
  • [ ] Regression Impact analysis
  • [ ] Test cases use TC-{MOD}-XXX format with GIVEN/WHEN/THEN
  • [ ] Acceptance criteria use ✅/❌ markers
  • [ ] Troubleshooting uses Symptoms/Causes/Resolution format
  • [ ] Operational Runbook with deployment checklist
  • [ ] Roadmap and Dependencies
  • [ ] Evidence Verification Protocol with audit trail
  • [ ] Glossary for non-technical stakeholders
  • [ ] Version History table at end
  • [ ] All code references verified with actual files
  • [ ] ASCII diagrams for architecture
  • [ ] Master index (BUSINESS-FEATURES.md) updated

AI Companion Checklist

  • [ ] AI companion file created at README.{FeatureName}.ai.md
  • [ ] AI companion ≤300 lines
  • [ ] File locations section complete with exact paths
  • [ ] API contracts include request/response shapes
  • [ ] All evidence references preserved from full doc
  • [ ] Patterns section has required (✅) and anti-patterns (❌)