前台用户 · 开放 API 文档

请求与响应约定（务必先读）

• 接口前缀：/api/plugins/frontuser/ext/**；本页所有接口均为一次同步请求-响应，由平台代执行。
• 响应是裸 JSON，不套 {code,data,message} 壳： list → {items,limit,offset}、get → {id,data,created_at,updated_at}、 create/update → {id,data}、delete → {deleted:1}；出错是 {"error":"..."}。
• PUT / PATCH 是整条覆盖，不是字段合并：只改一个字段也要传完整对象，否则其余字段被抹掉。
• 鉴权：前台用户用 POST /api/plugins/frontuser/users/login 返回的 ppk_ 令牌（7 天，仅本插件有效）， 放在 Authorization: Bearer <token>；管理端用平台令牌。
• 三层权限：L0 文档层公开只读；L1 读需身份；L2 写/删除仅插件归属人与后台管理员（普通用户 403）。
• 作用域：plugin = 全插件共享；caller = 每人一份数据岛（管理员跨岛可读全部）。
• 平台对 phone / mobile / tel / email / mail / id_card 强制脱敏，返回值带星号，请勿把脱敏值原样写回。
• 分页：limit（默认 20，上限 200）、offset；q 对整条 data 做模糊匹配。

数据模型（17 个集合 / 84 个端点）

安全设计（平台 1.11.59+）：写保护由平台按 op + scope 强制校验 —— scope:plugin 的 create / update / delete 仅归属人与后台管理员可调用，与 level 无关； L1 只降低读的门槛。普通用户写自己的数据请用 scope:caller。

隐私提示：member_cards / handlings / settings 是 L1 读的共享集合， 平台会返回全量记录。本插件前台用 q=user_id 做服务端过滤； 切勿在这些集合存放密码、密钥、身份证号等高敏信息。

接口目录（实时读取平台 catalog）

调用示例

一键脚本（推荐：只需改一行令牌）

整段保存为 try.py 后 python try.py；会依次跑完 6 步并打印每步的 HTTP 状态。已实测 6 步全部 200。

import json, urllib.request, urllib.error, random, string
BASE = "https://cfapi.aog.cc"
P = "/api/plugins/frontuser"
ADMIN = "<管理员令牌>"   # ← 只改这一行：换成你的 rap_ API Key

def call(method, path, body=None, token=None):
    data = json.dumps(body, ensure_ascii=False).encode() if body is not None else None
    h = {"Content-Type": "application/json"}
    if token: h["Authorization"] = "Bearer " + token
    req = urllib.request.Request(BASE + path, data=data, headers=h, method=method)
    try:
        with urllib.request.urlopen(req, timeout=20) as r:
            return r.status, json.loads(r.read().decode())
    except urllib.error.HTTPError as e:
        return e.code, json.loads(e.read().decode())

u  = "demo_" + "".join(random.choices(string.ascii_lowercase, k=5))
pw = "Demo123456"
print("1 注册     ", call("POST", P + "/users/register", {"username": u, "password": pw})[0])
s, d = call("POST", P + "/users/login", {"username": u, "password": pw})
ppk = d["data"]["token"]
print("2 登录     ", s, "ppk_ 长度", len(ppk))
print("3 读资料   ", call("GET", P + "/ext/profiles?limit=1", token=ppk))
s, d = call("POST", P + "/ext/profiles", {"user_id": 1, "username": u, "nick": "初始化"}, ppk)
rid = d["id"]
body = {"user_id": 1, "username": u, "nick": "小明", "gender": "male", "mode": "focus",
        "phone": "", "email": "", "tags": [], "social": {}, "bio": "", "updated_at": 0}
print("4 整条覆盖 ", call("PUT", P + "/ext/profiles/" + rid, body, ppk)[0])
print("5 建等级   ", call("POST", P + "/ext/levels",
      {"key": "lv6", "name": "至尊", "value": 6, "min_points": 50000,
       "benefits": ["全部权益"], "sort": 6}, ADMIN)[0])
print("6 提 BUG   ", call("POST", "/api/bugs",
      {"title": "连通性自检", "description": "来自一键脚本", "severity": "low",
       "plugin_code": "frontuser", "category": "文档"}, ADMIN)[0])

分步示例（curl，需手工替换占位符）

# 1) 注册
curl -X POST https://cfapi.aog.cc/api/plugins/frontuser/users/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","password":"Demo123456"}'

# 2) 登录，取 ppk_ 令牌（把返回值里的 data.token 填到下面 ppk_... 处）
curl -X POST https://cfapi.aog.cc/api/plugins/frontuser/users/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","password":"Demo123456"}'

# 3) 读我的资料（裸 JSON，注意没有 data 壳）
curl 'https://cfapi.aog.cc/api/plugins/frontuser/ext/profiles?limit=1' \
  -H 'Authorization: Bearer ppk_...'

# 4) 幂等保存：先 list 拿自己的 id 替换 <id>，再 PUT 整条覆盖（不要每次 POST）
curl -X PUT 'https://cfapi.aog.cc/api/plugins/frontuser/ext/profiles/<id>' \
  -H 'Authorization: Bearer ppk_...' -H 'Content-Type: application/json' \
  -d '{"user_id":1,"username":"demo","nick":"小明","gender":"male","mode":"focus","phone":"","email":"","tags":[],"social":{},"bio":"","updated_at":0}'

# 5) 管理端：创建用户等级（需管理员令牌）
curl -X POST 'https://cfapi.aog.cc/api/plugins/frontuser/ext/levels' \
  -H 'Authorization: Bearer <管理员令牌>' -H 'Content-Type: application/json' \
  -d '{"key":"lv6","name":"至尊","value":6,"min_points":50000,"benefits":["全部权益"],"sort":6}'

# 6) 提交 BUG 反馈到平台 BUG 仓库
curl -X POST 'https://cfapi.aog.cc/api/bugs' \
  -H 'Authorization: Bearer <平台令牌>' -H 'Content-Type: application/json' \
  -d '{"title":"问题描述","description":"复现步骤","severity":"high","plugin_code":"frontuser","category":"服务端"}'

平台 1.11.59 修复与仍存限制

已修复并实测通过：L1 写越权（现按 op + scope 强制校验）、重复注册 500→409、 插件用户自助接口、管理端用户接口、用户列表分页/搜索/注册时间。

• 仍存：跨岛列表实测未返回 caller_sub（平台声明已加，线上未见）；插件继续在资料里写 user_id 关联，并兼容 caller_sub。
• 设计约束（已适配）：plugin 集合读返回全量 → 个人信息放 caller 或按 q 服务端过滤； update 整条覆盖 → 读→改→整条写回；记录 ID 不可自定义、无 upsert → 用业务唯一键 + q 查询。
• 能力缺口：PATCH /users/{id} 只接受固定字段（username / display_name / email / password / status）， 不持久化任意扩展字段；分组、等级、特权等业务属性仍由插件 members 集合承载。
• 能力缺口：管理员仍不能直写指定用户的数据岛；BUG 回执查询仍需 bug.manage。
• 强制脱敏：读回掩码不要原样写回，本插件对敏感字段使用本地明文缓存 + 整条覆盖。