Add a scaffold script that replaces the bq prefix with the new project name.

Co-authored-by: Cursor <cursoragent@cursor.com>

doc/项目文档/基础应用/会话(session).md

@@ -0,0 +1,67 @@
+# 会话
+
+## 目录
+
+- [功能定义](#功能定义)
+- [使用示例](#使用示例)
+- [时序](#时序)
+  - [凭证变化](#凭证变化)
+
+## 功能定义
+
+会话负责登录凭证的保存、读取和清除，并在凭证变化后通知界面。`AUTH_CHANGED` 只表示凭证变了，不是领域事件。登录是否成功由安全模块的 `LoginResult` 决定。
+
+| 入口 | 文件 | 定义 |
+|---|---|---|
+| `TokenStore.save(token)` | `src/app/session/token_store.ts` | 写入凭证并调用 `notifyAuthChanged` |
+| `TokenStore.get()` | 同上 | 读出凭证；没有则返回 `null` |
+| `TokenStore.remove()` | 同上 | 清除凭证并调用 `notifyAuthChanged` |
+| `TokenStore.has()` | 同上 | 当前是否持有凭证 |
+| `hasSession()` | `src/app/session/auth_session.ts` | 从根容器取出 `TokenStore` 并调用 `has()` |
+| `useAuthenticated()` | `src/app/session/use_authenticated.ts` | 订阅 `AUTH_CHANGED`，得到当前是否已登录 |
+| `notifyAuthChanged()` | `src/app/session/auth_event.ts` | 发出 `AUTH_CHANGED` |
+| `subscribeAuth(listener)` | 同上 | 登记 `AUTH_CHANGED` 的监听，并返回取消函数 |
+
+## 使用示例
+
+安全模块在登录成功后写入凭证，登出时清除。文件：`src/features/security/application/security_application.ts`。
+
+```ts
+async login(credentials: AuthCredentials): Promise<void> {
+  const result = await this.repository.login(credentials);
+  this.tokenStore.save(result.accessToken);
+}
+
+async logout(): Promise<void> {
+  this.tokenStore.remove();
+}
+```
+
+路由用 `hasSession()` 判断能否进入。文件：`src/app/routes/layouts/auth.layout.tsx`。
+
+```ts
+const policy = decideRoutePolicy('require-auth', hasSession(), url.pathname, url.search);
+```
+
+## 时序
+
+### 凭证变化
+
+```mermaid
+sequenceDiagram
+  participant TokenStore
+  participant notifyAuthChanged
+  participant subscribeAuth
+  participant useAuthenticated
+  participant hasSession
+
+  useAuthenticated->>subscribeAuth: subscribeAuth(sync)
+  TokenStore->>TokenStore: save(token)
+  TokenStore->>notifyAuthChanged: notifyAuthChanged()
+  notifyAuthChanged->>subscribeAuth: AUTH_CHANGED
+  subscribeAuth->>useAuthenticated: sync()
+  useAuthenticated->>hasSession: hasSession()
+  hasSession->>TokenStore: has()
+```
+
+`TokenStore.save` 和 `TokenStore.remove` 改完本地凭证后调用 `notifyAuthChanged`。`notifyAuthChanged` 发出 `AUTH_CHANGED`。`useAuthenticated` 事先通过 `subscribeAuth` 登记 `sync`，收到事件后再次调用 `hasSession`。`hasSession` 只调用 `TokenStore.has`。