docs: align documentation with Tencent Cloud architecture

AGENTS.md

@@ -1,24 +1,74 @@
 # Repository Reality
 
-- This repository currently contains only `软件系统说明.docx`; no source code, package manifest, lockfile, CI workflow, or existing agent instruction files were present when this file was written.
-- Treat the Word document as the only verified source of truth. Do not invent build, test, lint, deploy, or startup commands until executable config is added to the repo.
-- If code appears later, re-audit the repo and update this file from executable config before relying on the document alone.
+- This repository now contains the WeChat Mini Program, the uniapp/Vue 3 admin console, a Tencent Cloud SCF HTTP backend, deployment docs, and design/planning references.
+- Current backend implementation lives in `server/` and targets Tencent Cloud HTTP Function + TencentDB MySQL + COS.
+- The previous WeChat Cloud Development function directories have been removed from the active architecture.
+- Do not treat older planning/review documents as current implementation truth unless they explicitly say they are current.
 
 # Verified System Scope
 
-- Product scope from `软件系统说明.docx`: a WeChat Mini Program connects to a beauty device over BLE 5.0 GATT, cloud services run on Tencent Cloud IoT + SCF + MySQL + Redis, and the admin console is `uniapp + Vue 3 + uView Plus` deployed as H5/static hosting.
-- Mini Program side is described as WeChat native (`WXML` / `WXSS` / `JS`), not `uniapp`.
-- Admin console is separate from the Mini Program. Do not merge those frontend assumptions when future code is added.
+- Mini Program: native WeChat `WXML` / `WXSS` / `JS` under `miniprogram/`.
+- Device communication: BLE 5.0 GATT via `miniprogram/services/ble.js`.
+- Mini Program cloud API: HTTPS requests through `miniprogram/utils/request.js` to the configured API base in `miniprogram/config/env.js`.
+- Backend: Tencent Cloud HTTP Function, package root uses executable `server/scf_bootstrap` to start `node scripts/local-server.js` on port `9000`.
+- Database: TencentDB MySQL schema in `server/sql/schema.sql`.
+- Storage: Tencent COS for firmware/admin H5 artifacts.
+- Admin console: uniapp + Vue 3 under `admin-console/`, H5 build can be uploaded to COS.
+
+# Current Deployment Facts
+
+- Test API base is configured as `https://1426323813-ilxkhlxf4p.ap-guangzhou.tencentscf.com` in both Mini Program and admin console test configs.
+- SCF function name used during deployment: `jw-beauty-api`.
+- SCF is an HTTP function, not an event function. Use `scf_bootstrap`, not `index.main_handler`, for this function type.
+- SCF must be attached to the TencentDB VPC/subnet when using the database private endpoint.
+- Real secrets must remain in local `.env` or SCF environment variables. Never commit `server/.env`.
 
 # Integration Facts Worth Preserving
 
-- BLE frame format in the document: header `0xAA 0x55`, then length, type, payload, XOR checksum.
-- BLE services in the document: `FFE0` device info, `FFE1` data communication, `FFE2` OTA.
-- MQTT topics in the document: `$iot/{product_id}/{device_name}/telemetry` and `$iot/{product_id}/{device_name}/event`.
-- Cloud data model names called out in the document: `users`, `devices`, `bindings`, `subscriptions`, `sessions`, `treatment_records`, `pd_data`, `operation_logs`.
+- BLE frame format implemented in code: header `0xAA 0x55`, length, type, payload, XOR checksum over header/length/type/payload.
+- BLE services in the document/code: `FFE0` device info, `FFE1` data communication, `FFE2` OTA.
+- Device binding is two-phase: backend bind request creates pending token, Mini Program sends BLE bind, device returns bind success, Mini Program confirms backend binding.
+- Device commands are queued in MySQL `device_commands`; Mini Program pulls pending commands and executes BLE commands.
+- Current main cloud path is HTTPS API through the Mini Program, not MQTT/IoT direct device-cloud communication.
+
+# User Profile / Login Reality
+
+- `wx.login()` only provides a code for backend `openid/session_key` exchange.
+- The current login page uses `wx.getUserProfile()` to request WeChat's official profile authorization popup and then stores returned nickname/avatar if WeChat provides them.
+- WeChat may still return masked values such as `微信用户` and default avatar. This is platform policy, not a backend bug.
+- If reliable nickname/avatar capture becomes required, use the newer `chooseAvatar` + `input type="nickname"` flow, but that is not the current requested UX.
+- Phone number authorization is scaffolded through `open-type="getPhoneNumber"` and backend `/api/v1/user/phone`, currently hidden in the login UI.
+
+# Build And Deploy Commands
+
+Backend local:
+
+```bash
+cd server
+npm install
+npm run db:init
+npm start
+```
+
+Admin H5:
+
+```bash
+cd admin-console
+npm install
+npm run build:h5
+npm run deploy:cos
+```
+
+Mini Program BLE frame test:
+
+```bash
+cd miniprogram
+node scripts/test-ble-frame.js
+```
 
 # Working Rules For Future Sessions
 
-- When asked to implement code in this repo, first confirm whether source files have been added since this file was created; right now there is nothing to edit except documentation.
-- If implementation details are needed beyond the document, state that they are unspecified instead of guessing architecture, package layout, or command lines.
-- Prefer updating this file only after verifying new facts from checked-in config or code, not from assumptions.
+- Use current executable config and code as the source of truth before relying on older planning docs.
+- Do not reintroduce `wx.cloud`, WeChat Cloud Development functions, or MQTT unless the architecture is explicitly changed again.
+- Do not commit `.env`, cloud credentials, database passwords, signed COS URLs, or generated build artifacts.
+- Before committing, check `git status --short` and scan staged files for secret-looking values.