docs: 更新 HTTP 错误码、用户积分、占卜运行及用户资料协议文档

2026-04-10 16:45:45 +08:00
parent 1bc8bc6a27
commit 17ef460391
78 changed files with 18680 additions and 25 deletions
@@ -0,0 +1,122 @@
+# Flutter App Development Guidelines
+
+> Best practices for Flutter app development in this project.
+
+---
+
+## Overview
+
+This directory contains guidelines for Flutter app development. Fill in each file with your project's specific conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | Filled |
+| [State Management](./state-management.md) | BLoC/Cubit, repository pattern, DI | Filled |
+| [Error Handling](./error-handling.md) | ApiProblem, error parsing, l10n mapping | Filled |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Filled |
+| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | Filled |
+
+---
+
+## How These Guidelines Were Filled
+
+Each guideline file was populated based on:
+
+1. **Existing codebase patterns** from `apps/lib/`
+2. **AGENTS.md rules** from `apps/AGENTS.md`
+3. **Real code examples** from `features/auth/`, `core/logging/`, etc.
+
+---
+
+## Quick Start
+
+### Directory Structure
+
+- **Feature modules**: `features/<feature>/data/` + `features/<feature>/presentation/`
+- **Core infrastructure**: `core/` (cross-feature)
+- **Shared widgets**: `shared/widgets/`
+- **Data layer**: `data/` (infrastructure only, not feature repositories)
+
+### State Management
+
+- **Pattern**: `ChangeNotifier` + immutable state
+- **State**: Use `copyWith` pattern
+- **DI**: Singleton blocs/repositories via ServiceLocator
+
+### Error Handling
+
+- **Format**: RFC 7807 (`ApiProblem`)
+- **Mapping**: Error code → l10n key
+- **Global**: 401 handled via `AuthBloc.handleUnauthorized401()`
+
+### Logging
+
+- **Library**: Custom `Logger` class
+- **Module path**: `features.<feature>.<component>`
+- **Error**: Always log with `error`, `stackTrace`, `message`
+- **Forbidden**: PII, tokens, passwords
+
+### Quality
+
+- **Colors**: Semantic colors from `Theme.of(context).colorScheme`
+- **Spacing**: Use `AppSpacing` / `AppRadius` tokens
+- **Tests**: Unit, widget, integration tests for critical flows
+
+---
+
+## Key Principles
+
+### Layer Boundaries
+
+1. **Presentation** → **Repository** (via interface)
+2. **Repository** → **Core/Infrastructure** (via DI)
+3. **Core** → **Nothing** (foundation layer)
+4. **Shared** → **Core** (for utilities)
+5. **Feature** → **Core** + **Shared** (for cross-cutting concerns)
+
+### Data Layer Boundary (Must)
+
+- `data/` = infrastructure abstractions (cache/network/storage)
+- `features/<feature>/data/` = feature business repositories/models
+- **NEVER** mix these boundaries
+
+### Error Code Contract (Must)
+
+- **Single source of truth**: `docs/protocols/common/http-error-codes.md`
+- **Frontend mapping**: Error code → l10n key
+- **Backend updates → Frontend mapping updates** (must stay in sync)
+
+---
+
+## Common Anti-Patterns
+
+### ❌ Do NOT:
+
+1. Hardcode colors (`Color(0xFF...)`, `Colors.blue`)
+2. Hardcode spacing (`Padding(padding: EdgeInsets.all(16.0))`)
+3. Place feature repositories in shared `data/`
+4. Import feature data layer from other features
+5. Create new second-level directories under `lib/`
+6. Use `print()` instead of Logger
+7. Log PII/tokens/passwords
+8. Catch exceptions without logging
+
+---
+
+## Architecture Decision Records
+
+When making architectural decisions, document:
+
+1. **Context**: What problem are we solving?
+2. **Decision**: What approach did we choose?
+3. **Consequences**: What are the trade-offs?
+
+Add new ADRs to this directory if needed.
+
+---
+
+**Language**: All documentation should be written in **English**.