jackyu66gitandCursor
2fb1dfee14
Archive the differentiated YuXinGu product docs, AI engineering system, design contract, and Go/Vue scaffold. Next execution prioritizes Cece-parity over early innovation (see .ai/product/STRATEGY.md). Co-authored-by: Cursor <cursoragent@cursor.com>
50 lines
994 B
Markdown
50 lines
994 B
Markdown
# API — Golden Rules
|
|
|
|
## Style
|
|
|
|
- REST only for public HTTP.
|
|
- Never use POST for pure queries (use GET).
|
|
- Verbs: GET / POST / PUT / DELETE.
|
|
- Prefix: `/api/v1`.
|
|
|
|
## Envelope (mandatory — never invent alternatives)
|
|
|
|
Success:
|
|
|
|
```json
|
|
{ "code": 0, "message": "success", "data": {} }
|
|
```
|
|
|
|
Error:
|
|
|
|
```json
|
|
{ "code": 10001, "message": "user not found" }
|
|
```
|
|
|
|
Forbidden shapes: `{ success: true }`, `{ ok: true }`, bare arrays as root.
|
|
|
|
## Error codes
|
|
|
|
- Start business codes at **10000**.
|
|
- 0 = success.
|
|
- Ranges: 1xxxx general/auth, 2xxxx profile, 3xxxx report/scale, 4xxxx order/membership, 5xxxx AI/companion.
|
|
|
|
## Pagination
|
|
|
|
Query: `page`, `page_size`
|
|
Data:
|
|
|
|
```json
|
|
{ "list": [], "total": 0, "page": 1, "page_size": 20 }
|
|
```
|
|
|
|
## Auth
|
|
|
|
- Bearer token in `Authorization` header when required.
|
|
- Resource ownership checked in service layer.
|
|
|
|
## Docs
|
|
|
|
- Public route changes update `proto/openapi.yaml` in the same change set.
|
|
- Do not invent endpoints that are not in OpenAPI / task spec.
|