Source Analysis — Document Templates

Used by Phase B1 (pipeline mode). Read this file when producing the source-analysis document set. Each section below is the template for the corresponding numbered file under port-{name}/source-analysis/ (wiki pages via wiki 读写 API（见 TERMINOLOGY）).

01-source-overview.md

## Source Overview

- **Project**: {name}
- **Language / Runtime**: {e.g. Python 3.11}
- **Framework**: {e.g. FastAPI}
- **Feature scope**: {description of what's being ported}
- **Source files**: {N}
- **Source LOC**: {L}
- **Source modules**: {list of distinct functional areas}

02-public-api.md

Document every public interface:

## Public API

| Method / Endpoint | Input Schema   | Output Schema   | Errors               | Notes           |
| ----------------- | -------------- | --------------- | --------------------- | --------------- |
| POST /auth/login  | `{email, pw}`  | `{token, user}` | 400, 401, 429, 500    | Rate limited    |
| GET /users/:id    | path param     | `User` object   | 401, 403, 404         | Auth required   |

03-data-model.md

## Data Model

### Entity: User
| Field       | Type       | Constraints         |
| ----------- | ---------- | ------------------- |
| id          | UUID       | PK, not null        |
| email       | string     | unique, not null    |
| password    | string     | hashed, not null    |
| created_at  | datetime   | not null            |

### Relationships
- User 1—N Session
- User N—M Role

04-business-logic.md

Capture every business rule, validation, edge case, and state transition from the source. Write each rule as an executable assertion:

## Business Logic

### Login
- RULE-01: Valid credentials → return JWT + user object
- RULE-02: Invalid password → 401 "Invalid credentials"
- RULE-03: Non-existent email → 401 "Invalid credentials" (same message, no enumeration)
- RULE-04: 5 failed attempts in 1 min → 429 + lock for 15 min
- RULE-05: Locked account + valid password → 423 "Account locked"

### Edge Cases
- Empty email → 400 "Email is required"
- Email > 254 chars → 400 "Email too long"
- Password < 8 chars → 400 "Password too short"

05-error-handling.md

## Error Handling

| Error Code | HTTP Status | Message              | Source Condition      |
| ---------- | ----------- | -------------------- | --------------------- |
| AUTH_001   | 400         | Email is required    | empty email           |
| AUTH_002   | 401         | Invalid credentials  | wrong email or pw     |
| AUTH_003   | 429         | Too many attempts    | rate limit exceeded   |
| AUTH_004   | 423         | Account locked       | locked out            |

10-fidelity-baseline.md

This is the master inventory used by verify at the end. Every source behavior is listed as a checkable item:

## Fidelity Baseline

| ID         | Behavior                            | Type         | Source Test          | Chunk        |
| ---------- | ----------------------------------- | ------------ | -------------------- | ------------ |
| FID-001    | Login with valid credentials        | happy path   | test_login_ok        | chunk-auth   |
| FID-002    | Login with invalid password         | error path   | test_login_bad_pw    | chunk-auth   |
| FID-003    | Login with empty email              | edge case    | test_login_empty     | chunk-auth   |
| FID-004    | Rate limiting after 5 attempts      | error path   | test_rate_limit      | chunk-auth   |

Each FID-* item maps to a Chunk column — this drives the DAG node decomposition. Behaviors in the same chunk are ported together. The Source Test column traces back to the original test for the verify stage.

3.7 KiB Raw Permalink Blame History Unescape Escape