# 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

```markdown
## 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:

```markdown
## 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

```markdown
## 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:

```markdown
## 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

```markdown
## 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:

```markdown
## 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.