1# OpenKara Context23This glossary captures domain language for OpenKara. Product docs, contracts, and implementation discussions must use the same terms.45## Language67**Remote Repository (远程资料库)**:8A registered OpenKara library. A remote provider stores its database and media artifacts. The user opens it through a local working copy.9_Avoid_: Remote library, remote song library, cloud folder1011**Remote Provider**:12
A storage service. It hosts a **Remote Repository**. Examples are Google Drive, Dropbox, and WebDAV.
13_Avoid_: Cloud account, backend
14
15**Remote Repository Location**:
16The provider-specific folder, path, or URL. A remote provider stores a **Remote Repository** there.
17_Avoid_: Locator, root, cloud folder
18
19**Local Working Copy**:
20The local cached copy of a **Remote Repository**. OpenKara opens and edits it.
21_Avoid_: Local mirror, cache
22
23**Repository Credentials**:
24The OAuth tokens or WebDAV username and password. They let OpenKara access a **Remote Repository**.
25_Avoid_: Login, account
26
27**Reauthorize Repository (重新授权)**:
28The recovery action. It renews OpenKara's permission to access an existing **Remote Repository**. It does not change the repository location.
29_Avoid_: Reconnect provider, update credentials, login again
30
31**Relocate Repository**:
32The confirmed recovery action. It replaces a **Remote Repository Location**. The user moved the same repository in the remote provider.
33_Avoid_: Reauthorize, overwrite old repository, connect new repository
34
35**Remote Revision**:
36The provider revision marker. OpenKara uses it to detect whether the remote database changed outside the current local working copy.
37_Avoid_: Version, timestamp
38
39**Refresh Repository**:
40The action. It updates a **Local Working Copy** from the current **Remote Repository** state.
41_Avoid_: Sync, force resync
42
43**Publish Changes**:
44The action. It writes local database or media changes from a **Local Working Copy** to a **Remote Repository**.
45_Avoid_: Sync, upload database
46
47**Publish Song**:
48The action. It puts one song and its required karaoke artifacts in a **Remote Repository**.
49_Avoid_: Sync song
50
51**Mirror Local Library**:
52The one-time action. It initializes a **Remote Repository** from an existing local library.
53_Avoid_: Sync local library
54
55**Disconnect Repository**:
56The action. It removes a repository from OpenKara on the current device. It does not delete the repository contents.
57_Avoid_: Delete library, remove data
58
59**Delete Repository**:
60The destructive action. It deletes repository contents from their storage location. For a **Remote Repository**, it deletes the provider-hosted repository contents.
61_Avoid_: Disconnect, remove registration
62
63**Pre-Mutation Refresh**:
64The automatic refresh. OpenKara performs it before a local edit. The remote revision is newer than the local working copy.
65_Avoid_: Conflict merge, background sync
66
67**Pre-Publish Conflict**:
68A safety stop. It occurs when the remote revision changes after the local edit. This happens before OpenKara publishes the result.
69_Avoid_: Sync failure, upload error
70
71## Relationships
72
73- A **Remote Repository** belongs to exactly one **Remote Provider** account and one **Remote Repository Location**.
74- A **Remote Repository** has one **Local Working Copy** on each device. The device opens it.
75- A **Local Working Copy** records the last known **Remote Revision**. This prevents conflicts.
76-**Repository Credentials** grant access to a **Remote Repository**. They are not the repository itself.
77-**Reauthorize Repository** updates **Repository Credentials** for the same **Remote Repository**. It must not change the **Remote Repository Location**.
78-**Relocate Repository** updates the registered **Remote Repository Location** after explicit confirmation. It does not delete or overwrite contents at the old location.
79- After **Relocate Repository**, OpenKara keeps the existing **Local Working Copy** directory. It immediately performs **Refresh Repository** from the new location. It records the new **Remote Revision**.
80-**Relocate Repository** only accepts a location. The location must already contain a valid OpenKara repository. An empty location belongs to new repository creation or mirroring. It does not belong to relocation.
81-**Refresh Repository** reads from a **Remote Repository** into a **Local Working Copy**.
82-**Publish Changes** writes from a **Local Working Copy** into a **Remote Repository**.
83-**Mirror Local Library** creates initial **Remote Repository** contents from a local library.
84-**Disconnect Repository** removes OpenKara's local registration and credentials. It leaves repository contents in place.
85-**Delete Repository** removes repository contents and then disconnects the repository from OpenKara.
86- A **Pre-Mutation Refresh** can proceed automatically. The system did not apply the user edit yet.
87- A **Pre-Publish Conflict** stops publication. The remote database is newer than the finished local edit. If OpenKara publishes the edit, it could overwrite another device.
88
89## Example dialogue
90
91> **Dev:** "If sync fails, do we reconnect the remote repository?"
92> **Domain expert:** "Only if access expired. If the remote revision changed, refresh the local working copy first. If credentials expired, reauthorize the repository."
93
94## Flagged ambiguities
95
96- People used "Remote library" to mean both the user's karaoke library and the provider-hosted database/media container. Resolved: use **Remote Repository (远程资料库)**. The database also lives remotely.
97- People used "Sync" for both remote-to-local and local-to-remote. Resolved: use **Refresh Repository** for remote-to-local. Use **Publish Changes** for local-to-remote.
98- People treated "Remove" and "delete" as similar Settings actions. Resolved: **Disconnect Repository** preserves repository contents. **Delete Repository** deletes them from storage.
99- People treated "Reconnect provider" and "update credentials" as separate user recovery actions. Resolved: use **Reauthorize Repository (重新授权)** for both OAuth renewal and WebDAV credential renewal. The remote repository location must not change.
100- "Overwrite the old one" during reauthorization means OpenKara replaces its registered remote location. It does not delete or write over data at the old remote location. Resolved: call this **Relocate Repository**. It requires explicit confirmation with a cancel path.
101- People used remote revision conflicts as one broad failure class. Resolved: **Pre-Mutation Refresh** is automatic. **Pre-Publish Conflict** is a user-visible safety stop.
