docs: clarify in-memory client contracts

README.md

@@ -117,7 +117,7 @@ _, err = client.RunActions(ctx, []mijia.ActionRequest{
 
 ## 高级 Device
 
-`NewDevice` 可通过 `DeviceSelector.DID` 或 `DeviceSelector.Name` 选择设备；名称匹配到多个设备时会返回 `MultipleDevicesFoundError`。设备描述默认缓存到认证文件所在目录，每次成功的 `Get`、`Set`、`RunAction` 后默认等待 `500ms`。
+`NewDevice` 可通过 `DeviceSelector.DID` 或 `DeviceSelector.Name` 选择设备；名称匹配到多个设备时会返回 `MultipleDevicesFoundError`。通过文件认证的 `NewClient` 默认把设备描述缓存到认证文件所在目录；`NewClientWithAuthData` 默认不启用缓存，调用方需要在创建 `Device` 时传入 `WithDeviceCacheDir` 才会缓存。每次成功的 `Get`、`Set`、`RunAction` 后默认等待 `500ms`。
 
 ```go
 device, err := mijia.NewDevice(ctx, client, mijia.DeviceSelector{DID: "设备 DID"})
@@ -149,6 +149,7 @@ device, err := mijia.NewDevice(
 	client,
 	mijia.DeviceSelector{Name: "客厅灯"},
 	mijia.WithDeviceDelay(0),
+	// 使用 NewClientWithAuthData 时，显式指定目录才能缓存设备描述。
 	mijia.WithDeviceCacheDir("./miot-cache"),
 	mijia.WithDeviceHTTPClient(http.DefaultClient),
 )

auth.go

@@ -85,6 +85,13 @@ func (data AuthData) complete() bool {
 	return data.UA != "" && data.Ssecurity != "" && data.UserID != "" && data.CUserID != "" && data.ServiceToken != ""
 }
 
+func (data AuthData) zero() bool {
+	return data.UA == "" && data.DeviceID == "" && data.PassO == "" && data.Psecurity == "" &&
+		data.Nonce == "" && data.Ssecurity == "" && data.PassToken == "" && data.UserID == "" &&
+		data.CUserID == "" && data.ServiceToken == "" && data.YetAnotherServiceToken == "" &&
+		data.ExpireTime == 0 && data.SaveTime == 0 && len(data.Extra) == 0
+}
+
 func (data AuthData) yetAnotherServiceToken() string {
 	if data.YetAnotherServiceToken != "" {
 		return data.YetAnotherServiceToken
@@ -143,26 +150,29 @@ func (client *Client) loadAuthData() error {
 }
 
 func (client *Client) ensureIdentity() {
-	client.updateAuthData(func(authData *AuthData) {
+	client.setAuthData(client.authDataWithIdentity(client.AuthData()))
-		if authData.PassO == "" {
+}
-			authData.PassO = randomString(16, "0123456789abcdef")
+
-		}
+func (client *Client) authDataWithIdentity(authData AuthData) AuthData {
-		if authData.DeviceID == "" {
+	if authData.PassO == "" {
-			authData.DeviceID = randomString(16, "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-")
+		authData.PassO = randomString(16, "0123456789abcdef")
-		}
+	}
-		if authData.UA != "" {
+	if authData.DeviceID == "" {
-			return
+		authData.DeviceID = randomString(16, "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-")
-		}
+	}
-		countryCode := "CN"
+	if authData.UA != "" {
-		if parts := strings.Split(client.locale, "_"); len(parts) == 2 {
+		return authData
-			countryCode = parts[1]
+	}
-		}
+	countryCode := "CN"
-		id1 := randomString(40, "0123456789ABCDEF")
+	if parts := strings.Split(client.locale, "_"); len(parts) == 2 {
-		id2 := randomString(32, "0123456789ABCDEF")
+		countryCode = parts[1]
-		id3 := randomString(32, "0123456789ABCDEF")
+	}
-		id4 := randomString(40, "0123456789ABCDEF")
+	id1 := randomString(40, "0123456789ABCDEF")
-		authData.UA = fmt.Sprintf("Android-15-11.0.701-Xiaomi-23046RP50C-OS2.0.212.0.VMYCNXM-%s-%s-%s-%s-SmartHome-MI_APP_STORE-%s|%s|%s-64", id1, countryCode, id3, id2, id1, id4, authData.PassO)
+	id2 := randomString(32, "0123456789ABCDEF")
-	})
+	id3 := randomString(32, "0123456789ABCDEF")
+	id4 := randomString(40, "0123456789ABCDEF")
+	authData.UA = fmt.Sprintf("Android-15-11.0.701-Xiaomi-23046RP50C-OS2.0.212.0.VMYCNXM-%s-%s-%s-%s-SmartHome-MI_APP_STORE-%s|%s|%s-64", id1, countryCode, id3, id2, id1, id4, authData.PassO)
+	return authData
 }
 
 func randomString(length int, alphabet string) string {
@@ -177,9 +187,37 @@ func randomString(length int, alphabet string) string {
 }
 
 func (client *Client) saveAuthData() error {
-	authData := client.updateAuthData(func(authData *AuthData) {
+	authData := client.AuthData()
-		authData.SaveTime = time.Now().UnixMilli()
+	authData.SaveTime = time.Now().UnixMilli()
-	})
+	if err := client.writeAuthData(authData); err != nil {
+		return err
+	}
+	client.setAuthData(authData)
+	return nil
+}
+
+func (client *Client) commitAuthData(authData AuthData) error {
+	if !authData.complete() {
+		return fmt.Errorf("incomplete auth data")
+	}
+	authData.SaveTime = time.Now().UnixMilli()
+	if client.authPath != "" {
+		if err := client.writeAuthData(authData); err != nil {
+			return err
+		}
+	} else if client.authDataChanged != nil {
+		if err := client.authDataChanged(authData.clone()); err != nil {
+			return fmt.Errorf("persist changed auth data: %w", err)
+		}
+	}
+	client.setAuthData(authData)
+	return nil
+}
+
+func (client *Client) writeAuthData(authData AuthData) error {
+	if client.authPath == "" {
+		return nil
+	}
 	payload, err := json.MarshalIndent(authData, "", "  ")
 	if err != nil {
 		return fmt.Errorf("encode auth data: %w", err)
@@ -283,18 +321,19 @@ func (value *stringOrNumber) UnmarshalJSON(payload []byte) error {
 func (client *Client) Login(ctx context.Context) (AuthData, error) {
 	client.loginMu.Lock()
 	defer client.loginMu.Unlock()
+	candidate := client.authDataWithIdentity(client.AuthData())
 
-	location, refreshed, err := client.getLocation(ctx)
+	location, refreshedAuthData, err := client.getLocation(ctx, candidate)
 	if err != nil {
 		return AuthData{}, err
 	}
-	if refreshed {
+	if refreshedAuthData != nil {
-		if err := client.saveAuthData(); err != nil {
+		if err := client.commitAuthData(*refreshedAuthData); err != nil {
 			return AuthData{}, err
 		}
 		return client.AuthData(), nil
 	}
-	loginData, err := client.getQRLoginData(ctx, location)
+	loginData, err := client.getQRLoginData(ctx, location, candidate)
 	if err != nil {
 		return AuthData{}, err
 	}
@@ -316,14 +355,14 @@ func (client *Client) Login(ctx context.Context) (AuthData, error) {
 			}
 		}
 	}
-	return client.completeQRLogin(ctx, loginData)
+	return client.completeQRLogin(ctx, loginData, candidate)
 }
 
-func (client *Client) getLocation(ctx context.Context) (url.Values, bool, error) {
+func (client *Client) getLocation(ctx context.Context, authData AuthData) (url.Values, *AuthData, error) {
 	httpClient := client.newSession()
 	serviceURL, err := url.Parse(client.serviceLoginURL)
 	if err != nil {
-		return nil, false, fmt.Errorf("parse service login URL: %w", err)
+		return nil, nil, fmt.Errorf("parse service login URL: %w", err)
 	}
 	query := serviceURL.Query()
 	query.Set("_json", "true")
@@ -332,55 +371,54 @@ func (client *Client) getLocation(ctx context.Context) (url.Values, bool, error)
 	serviceURL.RawQuery = query.Encode()
 	request, err := http.NewRequestWithContext(ctx, http.MethodGet, serviceURL.String(), nil)
 	if err != nil {
-		return nil, false, err
+		return nil, nil, err
 	}
-	client.setLoginHeaders(request, true)
+	client.setLoginHeaders(request, authData, true)
 	var data serviceLoginData
 	if err := client.doLoginRequestWithClient(httpClient, request, false, &data); err != nil {
-		return nil, false, err
+		return nil, nil, err
 	}
 	if data.Location == "" {
-		return nil, false, &LoginError{Code: data.Code, Message: "登录响应缺少 location"}
+		return nil, nil, &LoginError{Code: data.Code, Message: "登录响应缺少 location"}
 	}
 	if data.Code == 0 {
 		refreshRequest, err := http.NewRequestWithContext(ctx, http.MethodGet, data.Location, nil)
 		if err != nil {
-			return nil, false, err
+			return nil, nil, err
 		}
-		client.setLoginHeaders(refreshRequest, false)
+		client.setLoginHeaders(refreshRequest, authData, false)
 		response, err := httpClient.Do(refreshRequest)
 		if err != nil {
-			return nil, false, fmt.Errorf("refresh login token: %w", err)
+			return nil, nil, fmt.Errorf("refresh login token: %w", err)
 		}
 		body, readErr := readHTTPResponse(response)
 		response.Body.Close()
 		if readErr != nil {
-			return nil, false, fmt.Errorf("read token refresh response: %w", readErr)
+			return nil, nil, fmt.Errorf("read token refresh response: %w", readErr)
 		}
 		if response.StatusCode != http.StatusOK {
-			return nil, false, &LoginError{Code: response.StatusCode, Message: string(body)}
+			return nil, nil, &LoginError{Code: response.StatusCode, Message: string(body)}
 		}
 		if string(body) != "ok" {
-			return nil, false, &LoginError{Code: -1, Message: string(body)}
+			return nil, nil, &LoginError{Code: -1, Message: string(body)}
 		}
-		candidate := client.AuthData()
+		candidate := authData
 		serviceTokenReceived := updateAuthDataFromCookies(&candidate, httpClient, response.Request.URL)
 		candidate.Ssecurity = data.Ssecurity
 		if !serviceTokenReceived || !candidate.complete() {
-			return nil, false, fmt.Errorf("%w: %w", ErrReauthenticationRequired, &LoginError{Code: -1, Message: "刷新Token响应认证信息不完整"})
+			return nil, nil, fmt.Errorf("%w: %w", ErrReauthenticationRequired, &LoginError{Code: -1, Message: "刷新Token响应认证信息不完整"})
 		}
 		candidate.ExpireTime = time.Now().Add(30 * 24 * time.Hour).UnixMilli()
-		client.setAuthData(candidate)
+		return nil, &candidate, nil
-		return nil, true, nil
 	}
 	locationURL, err := url.Parse(data.Location)
 	if err != nil {
-		return nil, false, fmt.Errorf("parse login location: %w", err)
+		return nil, nil, fmt.Errorf("parse login location: %w", err)
 	}
-	return locationURL.Query(), false, nil
+	return locationURL.Query(), nil, nil
 }
 
-func (client *Client) getQRLoginData(ctx context.Context, location url.Values) (qrLoginData, error) {
+func (client *Client) getQRLoginData(ctx context.Context, location url.Values, authData AuthData) (qrLoginData, error) {
 	location.Set("theme", "")
 	location.Set("bizDeviceType", "")
 	location.Set("_hasLogo", "false")
@@ -395,7 +433,7 @@ func (client *Client) getQRLoginData(ctx context.Context, location url.Values) (
 	if err != nil {
 		return qrLoginData{}, err
 	}
-	client.setLoginHeaders(request, false)
+	client.setLoginHeaders(request, authData, false)
 	var data qrLoginData
 	if err := client.doLoginRequest(request, true, &data); err != nil {
 		return qrLoginData{}, err
@@ -406,7 +444,7 @@ func (client *Client) getQRLoginData(ctx context.Context, location url.Values) (
 	return data, nil
 }
 
-func (client *Client) completeQRLogin(ctx context.Context, loginData qrLoginData) (AuthData, error) {
+func (client *Client) completeQRLogin(ctx context.Context, loginData qrLoginData, authData AuthData) (AuthData, error) {
 	pollContext, cancel := context.WithTimeout(ctx, qrLoginTimeout)
 	defer cancel()
 	httpClient := client.newSession()
@@ -414,7 +452,7 @@ func (client *Client) completeQRLogin(ctx context.Context, loginData qrLoginData
 	if err != nil {
 		return AuthData{}, err
 	}
-	client.setLoginHeaders(request, false)
+	client.setLoginHeaders(request, authData, false)
 	var data longPollData
 	if err := client.doLoginRequestWithClient(httpClient, request, true, &data); err != nil {
 		if errors.Is(err, context.DeadlineExceeded) {
@@ -426,7 +464,7 @@ func (client *Client) completeQRLogin(ctx context.Context, loginData qrLoginData
 	if err != nil {
 		return AuthData{}, err
 	}
-	client.setLoginHeaders(callback, false)
+	client.setLoginHeaders(callback, authData, false)
 	response, err := httpClient.Do(callback)
 	if err != nil {
 		return AuthData{}, fmt.Errorf("complete login callback: %w", err)
@@ -439,7 +477,7 @@ func (client *Client) completeQRLogin(ctx context.Context, loginData qrLoginData
 	if response.StatusCode < 200 || response.StatusCode >= 300 {
 		return AuthData{}, &LoginError{Code: response.StatusCode, Message: "登录回调失败"}
 	}
-	candidate := client.AuthData()
+	candidate := authData
 	candidate.Ssecurity = ""
 	candidate.UserID = ""
 	candidate.CUserID = ""
@@ -455,8 +493,7 @@ func (client *Client) completeQRLogin(ctx context.Context, loginData qrLoginData
 		return AuthData{}, &LoginError{Code: -1, Message: "登录回调认证信息不完整"}
 	}
 	candidate.ExpireTime = time.Now().Add(30 * 24 * time.Hour).UnixMilli()
-	client.setAuthData(candidate)
+	if err := client.commitAuthData(candidate); err != nil {
-	if err := client.saveAuthData(); err != nil {
 		return AuthData{}, err
 	}
 	return client.AuthData(), nil
@@ -496,8 +533,7 @@ func (client *Client) doLoginRequestWithClient(httpClient *http.Client, request
 	return nil
 }
 
-func (client *Client) setLoginHeaders(request *http.Request, withCookies bool) {
+func (client *Client) setLoginHeaders(request *http.Request, authData AuthData, withCookies bool) {
-	authData := client.AuthData()
 	request.Header.Set("User-Agent", authData.UA)
 	request.Header.Set("Connection", "keep-alive")
 	request.Header.Set("Accept-Encoding", "gzip")
@@ -549,14 +585,14 @@ func (client *Client) refreshToken(ctx context.Context) error {
 	if available {
 		return nil
 	}
-	_, refreshed, err := client.getLocation(ctx)
+	_, refreshedAuthData, err := client.getLocation(ctx, client.AuthData())
 	if err != nil {
 		return err
 	}
-	if !refreshed {
+	if refreshedAuthData == nil {
 		return fmt.Errorf("%w: %w", ErrReauthenticationRequired, &LoginError{Code: -1, Message: "刷新Token失败，请重新登录"})
 	}
-	if err := client.saveAuthData(); err != nil {
+	if err := client.commitAuthData(*refreshedAuthData); err != nil {
 		return err
 	}
 	return nil

auth_test.go

@@ -305,7 +305,7 @@ func TestQRLoginTimeoutDoesNotRequireReauthentication(t *testing.T) {
 	defer cancel()
 
 	client := testClient(t, http.DefaultClient)
-	_, err := client.completeQRLogin(ctx, qrLoginData{LP: "https://example.invalid/long-poll"})
+	_, err := client.completeQRLogin(ctx, qrLoginData{LP: "https://example.invalid/long-poll"}, client.AuthData())
 	var loginErr *LoginError
 	if !errors.As(err, &loginErr) {
 		t.Fatalf("completeQRLogin() error = %v, want LoginError", err)
@@ -513,7 +513,7 @@ func TestQRLoginRejectsIncompleteCallbackWithoutSaving(t *testing.T) {
 	defer server.Close()
 
 	client := testClient(t, server.Client())
-	_, err := client.completeQRLogin(context.Background(), qrLoginData{LP: server.URL + "/lp"})
+	_, err := client.completeQRLogin(context.Background(), qrLoginData{LP: server.URL + "/lp"}, client.AuthData())
 	var loginErr *LoginError
 	if !errors.As(err, &loginErr) {
 		t.Fatalf("completeQRLogin() error = %v, want LoginError", err)

client.go

@@ -24,7 +24,10 @@ const (
 	availabilityTTL        = 60 * time.Second
 )
 
-type Option func(*Client) error
+type ClientOption func(*Client) error
+
+// Option is kept as an alias for compatibility with existing callers.
+type Option = ClientOption
 
 // WithHTTPClient configures the HTTP transport used by the client.
 func WithHTTPClient(httpClient *http.Client) Option {
@@ -58,6 +61,8 @@ func WithQRWriter(writer io.Writer) Option {
 
 type Client struct {
 	authPath        string
+	deviceCacheDir  string
+	authDataChanged func(AuthData) error
 	authMu          sync.RWMutex
 	authData        AuthData
 	loginMu         sync.Mutex
@@ -80,8 +85,38 @@ func NewClient(authPath string, options ...Option) (*Client, error) {
 	if err != nil {
 		return nil, err
 	}
+	client, err := newClient(options...)
+	if err != nil {
+		return nil, err
+	}
+	client.authPath = resolvedPath
+	client.deviceCacheDir = filepath.Dir(resolvedPath)
+	if err := client.loadAuthData(); err != nil {
+		return nil, err
+	}
+	client.ensureIdentity()
+	return client, nil
+}
+
+// NewClientWithAuthData creates a client whose authentication state is kept in memory.
+// Zero AuthData is accepted for QR login; non-zero AuthData must be complete.
+func NewClientWithAuthData(authData AuthData, options ...ClientOption) (*Client, error) {
+	if !authData.zero() && !authData.complete() {
+		return nil, fmt.Errorf("incomplete auth data")
+	}
+	client, err := newClient(options...)
+	if err != nil {
+		return nil, err
+	}
+	if !authData.zero() {
+		authData = client.authDataWithIdentity(authData)
+	}
+	client.setAuthData(authData)
+	return client, nil
+}
+
+func newClient(options ...ClientOption) (*Client, error) {
 	client := &Client{
-		authPath:        resolvedPath,
 		httpClient:      http.DefaultClient,
 		baseURL:         defaultBaseURL,
 		loginURL:        defaultLoginURL,
@@ -97,14 +132,27 @@ func NewClient(authPath string, options ...Option) (*Client, error) {
 			return nil, err
 		}
 	}
-	if err := client.loadAuthData(); err != nil {
-		return nil, err
-	}
-	client.ensureIdentity()
 	client.initSession()
 	return client, nil
 }
 
+// WithAuthDataChanged configures synchronous persistence for in-memory auth updates.
+// The callback runs under the client's internal login serialization and must not
+// use Client directly or indirectly, including by waiting for a goroutine, future,
+// channel, or hook whose completion may call Client. It should perform only bounded,
+// standalone persistence and return. The callback and Client callers must obey lock
+// ordering: neither may hold a lock needed by the other. Returning an error leaves
+// authentication unchanged.
+func WithAuthDataChanged(callback func(AuthData) error) ClientOption {
+	return func(client *Client) error {
+		if callback == nil {
+			return fmt.Errorf("auth data changed callback must not be nil")
+		}
+		client.authDataChanged = callback
+		return nil
+	}
+}
+
 func resolveAuthPath(authPath string) (string, error) {
 	if authPath == "" {
 		home, err := os.UserHomeDir()

device.go

@@ -498,7 +498,24 @@ type cacheMethod struct {
 
 type propertyCache struct {
 	PropertySpec
-	Method cacheMethod `json:"method"`
+	Method    cacheMethod `json:"method"`
+	rwPresent bool
+}
+
+func (cache *propertyCache) UnmarshalJSON(data []byte) error {
+	type propertyCacheAlias propertyCache
+	decoded := struct {
+		*propertyCacheAlias
+		RW *string `json:"rw"`
+	}{propertyCacheAlias: (*propertyCacheAlias)(cache)}
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return err
+	}
+	cache.rwPresent = decoded.RW != nil
+	if decoded.RW != nil {
+		cache.RW = *decoded.RW
+	}
+	return nil
 }
 
 type actionCache struct {
@@ -536,6 +553,9 @@ func decodeDeviceInfo(data []byte, model string) (DeviceInfo, error) {
 
 	info := DeviceInfo{Name: cache.Name, Model: cache.Model}
 	for _, cachedProperty := range cache.Properties {
+		if !cachedProperty.rwPresent {
+			return DeviceInfo{}, fmt.Errorf("property %q is missing access metadata", cachedProperty.Name)
+		}
 		property := cachedProperty.PropertySpec
 		if property.SIID == 0 {
 			property.SIID = cachedProperty.Method.SIID
@@ -572,7 +592,7 @@ func validateDeviceInfo(info *DeviceInfo, model string) error {
 	properties := make(map[propertyID]PropertySpec, len(info.Properties))
 	for index, property := range info.Properties {
 		if strings.TrimSpace(property.Name) == "" || !validPropertyType(property.Type) ||
-			(property.RW != "r" && property.RW != "w" && property.RW != "rw") || property.SIID <= 0 || property.PIID <= 0 {
+			(property.RW != "" && property.RW != "r" && property.RW != "w" && property.RW != "rw") || property.SIID <= 0 || property.PIID <= 0 {
 			return fmt.Errorf("property %d is invalid", index)
 		}
 		properties[propertyID{siid: property.SIID, piid: property.PIID}] = property
@@ -599,7 +619,7 @@ func NewDevice(ctx context.Context, client *Client, selector DeviceSelector, opt
 	if client == nil {
 		return nil, errors.New("client must not be nil")
 	}
-	config := deviceConfig{httpClient: client.session(), cacheDir: filepath.Dir(client.authPath), delay: 500 * time.Millisecond}
+	config := deviceConfig{httpClient: client.session(), cacheDir: client.deviceCacheDir, delay: 500 * time.Millisecond}
 	for _, option := range options {
 		if option != nil {
 			if err := option(&config); err != nil {

device_test.go

@@ -104,6 +104,15 @@ func loadSpecFixture(t *testing.T) []byte {
 	return fixture
 }
 
+func loadNonControllableSpecFixture(t *testing.T) []byte {
+	t.Helper()
+	fixture, err := os.ReadFile("testdata/miot-spec-non-controllable.html")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return fixture
+}
+
 func TestGetDeviceInfoParsesSpecAndCaches(t *testing.T) {
 	testServer := newDeviceTestServer(t, loadSpecFixture(t), nil)
 	httpClient := testServer.server.Client()
@@ -171,6 +180,41 @@ func TestParseDeviceInfoRejectsUnknownActionInput(t *testing.T) {
 	}
 }
 
+func TestGetDeviceInfoPreservesNonControllableProperties(t *testing.T) {
+	testServer := newDeviceTestServer(t, loadNonControllableSpecFixture(t), nil)
+	cacheDir := t.TempDir()
+	info, err := GetDeviceInfo(context.Background(), testServer.server.Client(), "test.sensor.v1", cacheDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(info.Properties) != 2 || info.Properties[0].Name != "event" || info.Properties[0].RW != "" || info.Properties[1].Name != "command" || info.Properties[1].RW != "" {
+		t.Fatalf("properties = %#v", info.Properties)
+	}
+	if len(info.Actions) != 1 || len(info.Actions[0].Inputs) != 1 || !reflect.DeepEqual(info.Actions[0].Inputs[0], info.Properties[1]) {
+		t.Fatalf("actions = %#v", info.Actions)
+	}
+
+	testServer.fixture = nil
+	cached, err := GetDeviceInfo(context.Background(), testServer.server.Client(), "test.sensor.v1", cacheDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cached.Properties) != 2 || cached.Properties[0].RW != "" || cached.Properties[1].RW != "" ||
+		len(cached.Actions) != 1 || len(cached.Actions[0].Inputs) != 1 || !reflect.DeepEqual(cached.Actions[0].Inputs[0], cached.Properties[1]) || testServer.specCalls != 1 {
+		t.Fatalf("cached = %#v, spec calls = %d", cached, testServer.specCalls)
+	}
+}
+
+func TestDeviceRejectsGetSetForNonControllableProperty(t *testing.T) {
+	device := Device{properties: map[string]PropertySpec{"event": {Name: "event", Type: "string", SIID: 2, PIID: 1}}}
+	if _, err := device.Get(context.Background(), "event"); err == nil || !strings.Contains(err.Error(), "不可读取") {
+		t.Fatalf("Get() error = %v", err)
+	}
+	if err := device.Set(context.Background(), "event", "value"); err == nil || !strings.Contains(err.Error(), "不可写入") {
+		t.Fatalf("Set() error = %v", err)
+	}
+}
+
 func TestDeviceActionsDeepCopyInputs(t *testing.T) {
 	device := Device{actions: map[string]ActionSpec{"toggle": {Inputs: []PropertySpec{{Range: []json.Number{"1", "2"}, ValueList: []ValueListItem{{Value: "1"}}}}}}}
 	actions := device.Actions()
@@ -282,6 +326,35 @@ func TestVersion2DeviceInfoCacheTrustsActionWithoutInputs(t *testing.T) {
 	}
 }
 
+func TestVersion2DeviceInfoCacheRequiresPropertyAccessField(t *testing.T) {
+	for _, test := range []struct {
+		name      string
+		property  string
+		wantCalls int
+	}{
+		{name: "missing", property: `{"name":"power","type":"bool","siid":2,"piid":1}`, wantCalls: 1},
+		{name: "explicit empty", property: `{"name":"power","type":"bool","rw":"","siid":2,"piid":1}`},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			fixture := loadSpecFixture(t)
+			if test.wantCalls == 0 {
+				fixture = nil
+			}
+			testServer := newDeviceTestServer(t, fixture, nil)
+			cacheDir := t.TempDir()
+			cache := fmt.Sprintf(`{"version":2,"model":"test.light.v1","properties":[%s],"actions":[]}`, test.property)
+			if err := os.WriteFile(filepath.Join(cacheDir, "test.light.v1.json"), []byte(cache), 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			info, err := GetDeviceInfo(context.Background(), testServer.server.Client(), "test.light.v1", cacheDir)
+			if err != nil || testServer.specCalls != test.wantCalls || len(info.Properties) == 0 {
+				t.Fatalf("GetDeviceInfo() = %#v, %v, calls=%d, want calls=%d", info, err, testServer.specCalls, test.wantCalls)
+			}
+		})
+	}
+}
+
 func TestStaleDeviceInfoCacheRefreshFailureIncludesBothErrors(t *testing.T) {
 	testServer := newDeviceTestServer(t, []byte("unavailable"), nil)
 	testServer.status = http.StatusServiceUnavailable
@@ -529,6 +602,40 @@ func TestNewDeviceDefaults(t *testing.T) {
 	}
 }
 
+func TestNewDeviceMemoryClientDefaultsToNoCache(t *testing.T) {
+	testServer := newDeviceTestServer(t, loadSpecFixture(t), []string{`{"homelist":[{"id":"10","uid":1}]}`, `{"device_info":[{"did":"a","model":"test.light.v1"}],"has_more":false}`})
+	client, err := NewClientWithAuthData(testAuthData(), WithHTTPClient(testServer.server.Client()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	client.baseURL = testServer.server.URL
+	client.availability = true
+	client.availabilityValid = true
+	client.availabilityAt = time.Now()
+
+	workingDirectory := t.TempDir()
+	previousWorkingDirectory, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(workingDirectory); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := os.Chdir(previousWorkingDirectory); err != nil {
+			t.Errorf("restore working directory: %v", err)
+		}
+	})
+
+	if _, err := NewDevice(context.Background(), client, DeviceSelector{DID: "a"}, WithDeviceDelay(0)); err != nil {
+		t.Fatal(err)
+	}
+	cachePath := filepath.Join(workingDirectory, "test.light.v1.json")
+	if _, err := os.Stat(cachePath); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("memory client default cache stat error = %v, want not exist", err)
+	}
+}
+
 func TestDeviceGetSetAndAction(t *testing.T) {
 	testServer := newDeviceTestServer(t, loadSpecFixture(t), []string{
 		`{"homelist":[{"id":"10","uid":1}]}`, `{"device_info":[{"did":"a","name":"Lamp","model":"test.light.v1"}],"has_more":false}`,
@@ -678,7 +785,8 @@ func TestDeviceGetManyReturnsTransportError(t *testing.T) {
 }
 func TestDeviceGetManyValidatesBeforeNetwork(t *testing.T) {
 	device, testServer := fixtureDeviceWithServer(t, nil)
-	tests := [][]string{{"power", "power"}, {"power", "missing"}, {"power", "write-only"}}
+	device.properties["no-access"] = PropertySpec{Name: "no-access", Type: "bool", SIID: 2, PIID: 4}
+	tests := [][]string{{"power", "power"}, {"power", "missing"}, {"power", "write-only"}, {"power", "no-access"}}
 	for _, names := range tests {
 		if results, err := device.GetMany(context.Background(), names); err == nil || results != nil {
 			t.Fatalf("GetMany(%v) = %#v, %v", names, results, err)

docs/compose/reports/mijia-go-api.md

@@ -30,6 +30,8 @@ commits: none
 - 单次请求使用同一认证快照，因为签名、Cookie 和响应解密不能混用不同代 token。
 - 设备 spec 缓存同时兼容 Go 顶层标识和 Python `method` 格式，因为两个实现默认共享认证目录和缓存文件名。
 - 整数规格校验使用精确十进制/有理数比较，因为 `float64` 无法安全表达 `2^53` 以上整数。
+- 内存认证的同步持久化回调保留在登录串行区内，以确保并发登录/刷新严格有序且回调失败时不安装候选认证。把回调移到所有内部锁外会允许旧回调在新认证提交后覆盖外部状态；票据或 worker 若同步等待，调用者持有回调所需锁时仍会形成 ABBA。因此公共契约明确要求回调和 Client 调用遵守锁顺序，而不是承诺任意应用锁安全。
+- 文件客户端默认把设备 spec 缓存在认证文件目录；内存客户端默认不缓存，只有显式 `WithDeviceCacheDir` 才写入 spec 文件。
 
 ## Usage
 
@@ -56,6 +58,8 @@ auth, err := client.Login(ctx)
 - `gofmt -w *.go`
 - `go test -count=1 ./...`：通过
 - `go vet ./...`：通过
+- `go test ./... -count=20`：通过
+- `go test -race ./...`：通过
 - 独立规格审查和逐阶段代码质量审查均通过。
 - 测试覆盖固定加密向量、gzip/大小限制、QR 与静默刷新、本地加密 HTTP 端点、分页异常、精确大整数、MIoT HTML 变体、Python 缓存迁移和 context 取消。
 

memory_auth_test.go

@@ -0,0 +1,384 @@
+package mijia
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+var errAuthDataChanged = errors.New("auth data changed callback failed")
+
+func TestNewClientWithAuthDataAcceptsCompleteAndZeroData(t *testing.T) {
+	complete := completeAuthData()
+	complete.Extra = map[string]string{"cookie": "original"}
+
+	client, err := NewClientWithAuthData(complete)
+	if err != nil {
+		t.Fatal(err)
+	}
+	complete.Extra["cookie"] = "caller changed"
+	if got := client.AuthData().Extra["cookie"]; got != "original" {
+		t.Fatalf("stored extra cookie = %q, want original", got)
+	}
+	if client.authPath != "" {
+		t.Fatalf("authPath = %q, want empty in memory mode", client.authPath)
+	}
+
+	emptyClient, err := NewClientWithAuthData(AuthData{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if authData := emptyClient.AuthData(); authData.UA != "" || authData.Extra != nil {
+		t.Fatalf("empty client auth data = %#v, want zero value", authData)
+	}
+}
+
+func TestNewClientWithAuthDataRejectsPartialData(t *testing.T) {
+	_, err := NewClientWithAuthData(AuthData{UA: "agent"})
+	if err == nil || !strings.Contains(err.Error(), "incomplete") {
+		t.Fatalf("error = %v, want incomplete auth data error", err)
+	}
+}
+
+func TestNewClientWithAuthDataGeneratesMissingIdentityWithoutMutatingInput(t *testing.T) {
+	input := completeAuthData()
+	input.DeviceID = ""
+	input.PassO = ""
+
+	client, err := NewClientWithAuthData(input)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if input.DeviceID != "" || input.PassO != "" {
+		t.Fatalf("caller auth data mutated: %#v", input)
+	}
+	stored := client.AuthData()
+	if stored.DeviceID == "" || stored.PassO == "" {
+		t.Fatalf("stored identity not generated: %#v", stored)
+	}
+}
+
+func TestWithAuthDataChangedRejectsNil(t *testing.T) {
+	_, err := NewClientWithAuthData(AuthData{}, WithAuthDataChanged(nil))
+	if err == nil || !strings.Contains(err.Error(), "must not be nil") {
+		t.Fatalf("error = %v, want nil callback error", err)
+	}
+}
+
+func TestNewClientWithAuthDataDoesNotAccessFilesystem(t *testing.T) {
+	home := filepath.Join(t.TempDir(), "must-not-exist")
+	t.Setenv("HOME", home)
+
+	if _, err := NewClientWithAuthData(AuthData{}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(home); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("home stat error = %v, want not exist", err)
+	}
+}
+
+func TestMemoryRefreshCallsChangedCallbackWithClone(t *testing.T) {
+	client, callbackAuth, server := newMemoryRefreshClient(t, func(authData AuthData) error {
+		authData.Extra["callback"] = "changed"
+		return nil
+	})
+	defer server.Close()
+
+	if err := client.refreshToken(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if callbackAuth.ServiceToken != "new-token" || callbackAuth.CUserID != "new-c-user" {
+		t.Fatalf("callback auth = %#v", callbackAuth)
+	}
+	stored := client.AuthData()
+	if stored.ServiceToken != "new-token" || stored.CUserID != "new-c-user" {
+		t.Fatalf("stored auth = %#v", stored)
+	}
+	if stored.Extra["callback"] != "original" {
+		t.Fatalf("stored callback extra = %q, want original", stored.Extra["callback"])
+	}
+}
+
+func TestMemoryRefreshCallbackFailureRollsBack(t *testing.T) {
+	client, _, server := newMemoryRefreshClient(t, func(AuthData) error { return errAuthDataChanged })
+	defer server.Close()
+	before := client.AuthData()
+
+	err := client.refreshToken(context.Background())
+	if !errors.Is(err, errAuthDataChanged) {
+		t.Fatalf("refreshToken() error = %v, want %v", err, errAuthDataChanged)
+	}
+	if after := client.AuthData(); after.ServiceToken != before.ServiceToken || after.CUserID != before.CUserID || after.Ssecurity != before.Ssecurity {
+		t.Fatalf("auth changed after callback failure: before=%#v after=%#v", before, after)
+	}
+}
+
+func TestMemoryRefreshCallbackCanReadCurrentAuth(t *testing.T) {
+	var client *Client
+	client, _, server := newMemoryRefreshClient(t, func(AuthData) error {
+		if current := client.AuthData(); current.ServiceToken != "service-token" {
+			return errors.New("new auth data installed before callback completed")
+		}
+		return nil
+	})
+	defer server.Close()
+
+	if err := client.refreshToken(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestMemoryRefreshCallbackCanPersistIndependently(t *testing.T) {
+	persistencePath := filepath.Join(t.TempDir(), "persisted-auth.json")
+	client, _, server := newMemoryRefreshClient(t, func(authData AuthData) error {
+		payload, err := authData.MarshalJSON()
+		if err != nil {
+			return err
+		}
+		return os.WriteFile(persistencePath, payload, 0o600)
+	})
+	defer server.Close()
+
+	if err := client.refreshToken(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	payload, err := os.ReadFile(persistencePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var persisted AuthData
+	if err := persisted.UnmarshalJSON(payload); err != nil {
+		t.Fatal(err)
+	}
+	if persisted.ServiceToken != "new-token" || persisted.CUserID != "new-c-user" {
+		t.Fatalf("persisted auth = %#v", persisted)
+	}
+}
+
+func TestMemoryRefreshPersistsGeneratedIdentity(t *testing.T) {
+	initial := completeAuthData()
+	initial.DeviceID = ""
+	initial.PassO = ""
+	var changed AuthData
+	client, err := NewClientWithAuthData(initial, WithAuthDataChanged(func(authData AuthData) error {
+		changed = authData.clone()
+		return nil
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	server := configureRefreshServer(t, client)
+	defer server.Close()
+
+	if err := client.refreshToken(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if changed.DeviceID == "" || changed.PassO == "" {
+		t.Fatalf("persisted identity not generated: %#v", changed)
+	}
+}
+
+func TestFreshMemoryClientQRLoginPersistsThroughCallback(t *testing.T) {
+	var changed AuthData
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		switch request.URL.Path {
+		case "/serviceLogin":
+			deviceID, deviceErr := request.Cookie("deviceId")
+			passO, passOErr := request.Cookie("pass_o")
+			if request.UserAgent() == "" || deviceErr != nil || deviceID.Value == "" || passOErr != nil || passO.Value == "" {
+				http.Error(writer, "missing generated login identity", http.StatusBadRequest)
+				return
+			}
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":70016,"location":"`+server.URL+`/prepare"}`)
+		case "/loginUrl":
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":0,"loginUrl":"https://qr.example/login","lp":"`+server.URL+`/lp"}`)
+		case "/lp":
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":0,"ssecurity":"`+testSsecurity+`","passToken":"pass","userId":"user","cUserId":"c-user","location":"`+server.URL+`/callback"}`)
+		case "/callback":
+			http.SetCookie(writer, &http.Cookie{Name: "serviceToken", Value: "service", Path: "/"})
+			_, _ = io.WriteString(writer, "ok")
+		default:
+			http.NotFound(writer, request)
+		}
+	}))
+	defer server.Close()
+
+	client, err := NewClientWithAuthData(AuthData{}, WithHTTPClient(server.Client()), WithQRWriter(io.Discard), WithAuthDataChanged(func(authData AuthData) error {
+		changed = authData.clone()
+		return nil
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	client.serviceLoginURL = server.URL + "/serviceLogin"
+	client.loginURL = server.URL + "/loginUrl"
+
+	authData, err := client.Login(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !authData.complete() || authData.DeviceID == "" || changed.ServiceToken != "service" {
+		t.Fatalf("login auth = %#v, callback auth = %#v", authData, changed)
+	}
+}
+
+func TestFreshMemoryClientQRLoginCallbackFailureKeepsZeroAuthData(t *testing.T) {
+	var client *Client
+	var callbackCalls int
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		switch request.URL.Path {
+		case "/serviceLogin":
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":70016,"location":"`+server.URL+`/prepare"}`)
+		case "/loginUrl":
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":0,"loginUrl":"https://qr.example/login","lp":"`+server.URL+`/lp"}`)
+		case "/lp":
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":0,"ssecurity":"`+testSsecurity+`","passToken":"pass","userId":"user","cUserId":"c-user","location":"`+server.URL+`/callback"}`)
+		case "/callback":
+			http.SetCookie(writer, &http.Cookie{Name: "serviceToken", Value: "service", Path: "/"})
+			_, _ = io.WriteString(writer, "ok")
+		default:
+			http.NotFound(writer, request)
+		}
+	}))
+	defer server.Close()
+
+	var err error
+	client, err = NewClientWithAuthData(AuthData{}, WithHTTPClient(server.Client()), WithQRWriter(io.Discard), WithAuthDataChanged(func(AuthData) error {
+		callbackCalls++
+		if current := client.AuthData(); !reflect.DeepEqual(current, AuthData{}) {
+			t.Fatalf("auth data installed before callback completed: %#v", current)
+		}
+		return errAuthDataChanged
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	client.serviceLoginURL = server.URL + "/serviceLogin"
+	client.loginURL = server.URL + "/loginUrl"
+
+	_, err = client.Login(context.Background())
+	if !errors.Is(err, errAuthDataChanged) {
+		t.Fatalf("Login() error = %v, want %v", err, errAuthDataChanged)
+	}
+	if callbackCalls != 1 {
+		t.Fatalf("auth data changed callback calls = %d, want 1", callbackCalls)
+	}
+	if authData := client.AuthData(); !reflect.DeepEqual(authData, AuthData{}) {
+		t.Fatalf("auth data after callback failure = %#v, want exact zero value", authData)
+	}
+}
+
+func TestFileRefreshPersistenceFailureRollsBack(t *testing.T) {
+	directory := t.TempDir()
+	authPath := filepath.Join(directory, "auth.json")
+	initial := completeAuthData()
+	payload, err := initial.MarshalJSON()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(authPath, payload, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	client, err := NewClient(authPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Remove(authPath); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Mkdir(authPath, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	server := configureRefreshServer(t, client)
+	defer server.Close()
+	before := client.AuthData()
+
+	if err := client.refreshToken(context.Background()); err == nil {
+		t.Fatal("refreshToken() error = nil, want persistence failure")
+	}
+	if after := client.AuthData(); after.ServiceToken != before.ServiceToken || after.CUserID != before.CUserID || after.Ssecurity != before.Ssecurity {
+		t.Fatalf("auth changed after file persistence failure: before=%#v after=%#v", before, after)
+	}
+}
+
+func TestNewClientFileModeCompatibility(t *testing.T) {
+	authPath := filepath.Join(t.TempDir(), "auth.json")
+	want := completeAuthData()
+	want.Extra = map[string]string{"custom": "preserved"}
+	payload, err := want.MarshalJSON()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(authPath, payload, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	client, err := NewClient(authPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := client.AuthData()
+	if got.ServiceToken != want.ServiceToken || got.Extra["custom"] != "preserved" {
+		t.Fatalf("loaded auth = %#v", got)
+	}
+}
+
+func newMemoryRefreshClient(t *testing.T, callback func(AuthData) error) (*Client, *AuthData, *httptest.Server) {
+	t.Helper()
+	captured := new(AuthData)
+	client, err := NewClientWithAuthData(completeAuthData(), WithAuthDataChanged(func(authData AuthData) error {
+		*captured = authData.clone()
+		return callback(authData)
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	server := configureRefreshServer(t, client)
+	return client, captured, server
+}
+
+func configureRefreshServer(t *testing.T, client *Client) *httptest.Server {
+	t.Helper()
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+		switch request.URL.Path {
+		case "/v2/message/v2/check_new_msg":
+			_, _ = io.WriteString(writer, `{"code":-10030,"message":"expired"}`)
+		case "/serviceLogin":
+			_, _ = io.WriteString(writer, `&&&START&&&{"code":0,"location":"`+server.URL+`/refresh","ssecurity":"`+testSsecurity+`"}`)
+		case "/refresh":
+			http.SetCookie(writer, &http.Cookie{Name: "serviceToken", Value: "new-token", Path: "/"})
+			http.SetCookie(writer, &http.Cookie{Name: "cUserId", Value: "new-c-user", Path: "/"})
+			_, _ = io.WriteString(writer, "ok")
+		default:
+			http.NotFound(writer, request)
+		}
+	}))
+	client.baseURL = server.URL
+	client.serviceLoginURL = server.URL + "/serviceLogin"
+	client.availabilityValid = false
+	return server
+}
+
+func completeAuthData() AuthData {
+	return AuthData{
+		UA:           "test-agent",
+		DeviceID:     "device-id",
+		PassO:        "pass-o",
+		Ssecurity:    testSsecurity,
+		PassToken:    "pass-token",
+		UserID:       "user",
+		CUserID:      "c-user",
+		ServiceToken: "service-token",
+		Extra:        map[string]string{"callback": "original"},
+	}
+}

testdata/miot-spec-non-controllable.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html>
+<body>
+<script data-page="app" type="application/json">{"props":{"product":{"name":"Test Sensor","model":"test.sensor.v1"},"i18n":{"zh_cn":{}},"tree":{"services":[{"iid":2,"type":"sensor","properties":[{"iid":1,"type":"event","description":"Event","format":"string","access":["notify"]},{"iid":2,"type":"command","description":"Command","format":"uint8","access":[],"valueRange":[0,10,1]}],"actions":[{"iid":1,"type":"execute","description":"Execute","in":[2]}]}]}}}</script>
+</body>
+</html>