106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
|
# 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.
|