# PROJECT: AI文件夹 (AI File Folder)
# VERSION: 4.1
# Optimized for AI agent consumption.

BASE_URL = https://ai.guangsuan.com
AUTH = ?key= parameter (required for all API endpoints)
KEY = ask admin for the key (do NOT share in public)
USAGE = ?action=xxx&file=yyy&key=<your-key>
SCOPE = /docs/ only; path traversal blocked
DIRECT_ACCESS = /docs/<path> (no auth, Nginx serves directly)
CONFLICT = 409 error when file already exists (pick a different name)

=== ENDPOINTS ===

[1] api_list  GET
  List files in docs/.
  PARAMS: dir=<subdir>  ext=<ext1,ext2>
  AUTH: ?key= required
  RESPONSE: {"files":[{"name","path","url","is_dir","size","mtime","ext"}]}
  curl -s "BASE/?action=api_list&key=<your-key>"

[2] api_read  GET
  Read text file content.
  PARAMS: file=<path>
  AUTH: ?key= required
  RESPONSE: {"success":true,"file":"<path>","content":"<text>","size":<bytes>}
  curl -s "BASE/?action=api_read&file=notes.md&key=<your-key>"

[3] api_download  GET
  Download any file as binary.
  PARAMS: file=<path>
  AUTH: ?key= required
  RESPONSE: application/octet-stream
  curl -s "BASE/?action=api_download&file=report.pdf&key=<your-key>" -o out.pdf

[4] api_create  POST
  Create a new text file. Returns 409 if file exists.
  BODY (form-encoded): file=<path>&content=<text>
  AUTH: ?key= required
  SUCCESS: {"success":true,"file":"<path>"}
  CONFLICT (409): {"error":"File already exists","file":"<path>","suggestion":"Choose a different filename to avoid overwriting other projects."}
  curl -s -X POST "BASE/?action=api_create&key=<your-key>" -d "file=notes.md&content=hello"

[5] api_upload  POST
  Upload a file via multipart. Returns 409 if file exists.
  BODY (multipart): file=<@local_path>  path=<target_dir/>
  AUTH: ?key= required
  SUCCESS: {"success":true,"file":"<path>","url":"https://ai.guangsuan.com/docs/<path>","size":<bytes>}
  CONFLICT (409): {"error":"File already exists","file":"<path>","suggestion":"Choose a different filename."}
  MAX_SIZE: 100MB
  curl -s "BASE/?action=api_upload&key=<your-key>" -F "file=@local.pdf" -F "path=subdir/"

[6] api_move  POST  -- DISABLED (403)
[7] api_rename  POST  -- RESTRICTED (backup format only)
[8] api_delete  GET  -- DISABLED (403)

[9] api_mkdir  GET
  Create a directory.
  PARAMS: path=<name>
  AUTH: ?key= required
  RESPONSE: {"success":true,"path":"<name>"}
  curl -s "BASE/?action=api_mkdir&path=my-dir&key=<your-key>"

[10] DIRECT FILE ACCESS  GET  (no auth)
  Access files directly via Nginx. No key needed.
  URL: https://ai.guangsuan.com/docs/<path>
  Examples: /docs/notes.md  /docs/subdir/report.pdf

=== QUICKSTART ===
# Ask admin for API key, then:\n  KEY=<your-key>
  curl -s "https://ai.guangsuan.com/?action=api_list&key=$KEY"
  curl -s -X POST "https://ai.guangsuan.com/?action=api_create&key=$KEY" -d "file=test.md&content=hello"
  curl -s "https://ai.guangsuan.com/?action=api_read&file=test.md&key=$KEY"
  curl -s "https://ai.guangsuan.com/docs/test.md"  # direct access, no auth