docs: add PATCH identity endpoint doc + BCP 47 alias reference

2026-05-22 08:56:07 +08:00
parent e1619c724a
commit 2b025a014e
3 changed files with 635 additions and 3 deletions
--- a/docs_v1.0/API_WORKSPACE/modules/07_identity.md
+++ b/docs_v1.0/API_WORKSPACE/modules/07_identity.md
@@ -74,6 +74,66 @@ Delete an identity permanently.

 ---

+### `PATCH /api/v1/identity/:identity_uuid`
+
+**Auth**: Required
+**Scope**: identity-level
+
+Partially update an identity. Only provided fields are modified. The `name` field is a display label and may repeat across identities (removed UNIQUE constraint). Aliases for multilingual display are stored in `metadata.aliases` (see BCP 47 reference below).
+
+#### Request (JSON, all fields optional)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | New display name |
+| `metadata` | object | Merged into existing metadata. Use `"aliases"` key for locale-tagged names |
+| `status` | string | `"confirmed"`, `"pending"`, or `"skipped"` |
+| `identity_type` | string | `"people"`, `"brand"`, `"object"`, `"concept"`, etc. |
+
+#### Example
+
+```bash
+# Update name and add aliases
+curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Smith",
+    "metadata": {
+      "aliases": [
+        {"locale": "en", "name": "John Smith"},
+        {"locale": "zh-TW", "name": "約翰·史密斯"},
+        {"locale": "ja", "name": "ジョン・スミス"}
+      ]
+    }
+  }'
+
+# Update status only
+curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
+  -H "X-API-Key: $KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "confirmed"}'
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
+  "updated_fields": ["name", "metadata"]
+}
+```
+
+#### Error Responses
+
+| HTTP | When |
+|------|------|
+| `400` | No fields to update or invalid UUID format |
+| `404` | Identity not found |
+
+---
+
 ### `GET /api/v1/identity/:identity_uuid/files`

 **Auth**: Required
@@ -225,7 +285,7 @@ curl -s "$API/api/v1/identities/search?q=Cary" -H "X-API-Key: $KEY"

 Upload an identity.json file to create or update an identity. Accepts the same format as the identity.json files stored on disk.

-If an identity with the same `name` already exists, it will be updated with the new values.
+If an identity with the same `identity_uuid` already exists, it will be updated with the new values.

 #### Request

@@ -330,7 +390,63 @@ curl -s "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
 |----------------|-------|
 | `content-type` | `image/jpeg` or `image/png` |

+---

+## Alias System (BCP 47 Locale Tags)
+
+Identity aliases support multilingual display names. Aliases are stored in `metadata.aliases` as an array of `{locale, name}` objects.
+
+### BCP 47 Locale Tags Reference
+
+| Locale | Tag | Example |
+|--------|-----|---------|
+| English | `en` | John Smith |
+| Traditional Chinese | `zh-TW` | 約翰·史密斯 |
+| Simplified Chinese | `zh-CN` | 约翰·史密斯 |
+| Japanese | `ja` | ジョン・スミス |
+| Korean | `ko` | 존 스미스 |
+| Cantonese | `yue` | 約翰·史密夫 |
+| French | `fr` | John Smith (French spelling) |
+| Spanish | `es` | Juan Smith |
+| Arabic | `ar` | جون سميث |
+| Russian | `ru` | Джон Смит |
+| Thai | `th` | จอห์น สมิธ |
+
+BCP 47 is the IETF standard for language tags. Format: `language` (e.g. `en`, `ja`) or `language-Region` (e.g. `zh-TW`, `zh-CN`). Region suffix distinguishes regional variants.
+
+### Frontend Display Logic
+
+```javascript
+function getDisplayName(identity, preferredLocale) {
+  // 1. Exact locale match
+  const match = identity.metadata?.aliases?.find(a => a.locale === preferredLocale);
+  if (match) return match.name;
+
+  // 2. Language-only match (zh-TW → zh)
+  const lang = preferredLocale.split('-')[0];
+  const langMatch = identity.metadata?.aliases?.find(a => a.locale.startsWith(lang));
+  if (langMatch) return langMatch.name;
+
+  // 3. Fallback to identity.name
+  return identity.name;
+}
+```
+
+### Updating Aliases via PATCH
+
+```json
+PATCH /api/v1/identity/:identity_uuid
+{
+  "metadata": {
+    "aliases": [
+      {"locale": "en", "name": "John Smith"},
+      {"locale": "zh-TW", "name": "約翰·史密斯"}
+    ]
+  }
+}
+```
+
+This **replaces** the entire `aliases` array. To add to existing aliases, include all existing entries in the request.

 ---
-*Updated: 2026-05-19 12:49:24*
+*Updated: 2026-05-22
--- a/docs_v1.0/doc_wasm/modules/07_identity.md
+++ b/docs_v1.0/doc_wasm/modules/07_identity.md
@@ -225,7 +225,7 @@ curl -s "$API/api/v1/identities/search?q=Cary" -H "X-API-Key: $KEY"

 Upload an identity.json file to create or update an identity. Accepts the same format as the identity.json files stored on disk.

-If an identity with the same `name` already exists, it will be updated with the new values.
+If an identity with the same `identity_uuid` already exists, it will be updated with the new values.

 #### Request