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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 22:46:06 +08:00
commit bc84c95a89
128 changed files with 9700 additions and 0 deletions
--- a/doc/项目文档/功能模块/安全模块/安全模块(security).md
+++ b/doc/项目文档/功能模块/安全模块/安全模块(security).md
@@ -0,0 +1,124 @@
+# 安全模块
+
+## 目录
+
+- [模块目录结构](#模块目录结构)
+- [功能定义](#功能定义)
+- [核心业务层](#核心业务层)
+  - [SecurityViewModel](#securityviewmodel)
+- [核心模型](#核心模型)
+- [核心业务](#核心业务)
+  - [登录](#登录)
+
+## 模块目录结构
+
+```text
+src/features/security/
+├── application/
+│   └── security_application.ts
+├── domain/
+│   ├── entities/
+│   │   ├── auth_credentials.ts
+│   │   ├── register_credentials.ts
+│   │   ├── login_result.ts
+│   │   └── user.ts
+│   ├── enum/
+│   │   └── auth_enum.ts
+│   └── repositories/
+│       └── i_security_repository.ts
+├── i18n/
+├── infra/
+│   └── persistence/
+│       └── security_repository.ts
+├── presentation/
+│   ├── profile/
+│   └── security/
+└── security.ts
+```
+
+`security.ts` 导入文案和 `SecurityRepository`。`profile` 页面没有用例。
+
+## 功能定义
+
+安全模块提供身份用例。
+
+- `login(credentials)`：校验身份，得到 `LoginResult`。用例再把其中的访问凭证写入会话。
+- `register(credentials)`：注册一个用户。
+- `logout()`：清除会话中的凭证。
+
+这些方法在 `SecurityApplication`。端口方法名不带 `remote`。
+
+## 核心业务层
+
+### SecurityViewModel
+
+登录与注册页的状态。文件：`src/features/security/presentation/security/security_view_model.ts`。继承 `PageViewModel`。
+
+状态：`activeTab`、`isLoading`、`errorMessage`、`loginForm`、`registerForm`。
+
+| 方法 | 说明 |
+|---|---|
+| `switchTab(tab: AuthEnum): void` | 在 `LOGIN` 与 `REGISTER` 之间切换，并清空 `errorMessage` |
+| `submit(): Promise<boolean>` | 表单已经由领域对象判定有效后，登录调用 `login`，注册调用 `register` |
+| `dispose(): void` | 清空 `errorMessage` |
+
+`submit` 在 `isValid` 不为真时，用 `validationErrorKey` 取出文案并返回 `false`。登录成功返回 `true`。注册成功后切回 `LOGIN` 并返回 `false`。
+
+## 核心模型
+
+| 类型 | 文件 | 定义 |
+|---|---|---|
+| `AuthCredentials` | `src/features/security/domain/entities/auth_credentials.ts` | 登录凭证。用户名不少于 3 个字符，密码不少于 6 个字符 |
+| `RegisterCredentials` | `src/features/security/domain/entities/register_credentials.ts` | 注册凭证。在登录凭证上增加一次确认密码，两次密码必须相同 |
+| `User` | `src/features/security/domain/entities/user.ts` | 用户。持有 `id`、`username`、`roles` |
+| `LoginResult` | `src/features/security/domain/entities/login_result.ts` | 一次成功的登录。持有 `User` 和 `accessToken` |
+| `ISecurityRepository` | `src/features/security/domain/repositories/i_security_repository.ts` | `login` 返回 `LoginResult`，`register` 接收 `RegisterCredentials` |
+
+```mermaid
+classDiagram
+  class AuthCredentials {
+    username
+    password
+    isValid
+    validationErrorKey
+  }
+  class RegisterCredentials {
+    confirmPassword
+    isValid
+    validationErrorKey
+  }
+  class User {
+    id
+    username
+    roles
+    hasPermission(permission)
+  }
+  class LoginResult {
+    user
+    accessToken
+  }
+  AuthCredentials <|-- RegisterCredentials
+  LoginResult --> User
+```
+
+`User.hasPermission` 在角色包含 `admin` 或指定权限时返回真。登录失败不产生 `LoginResult`。
+
+## 核心业务
+
+### 登录
+
+```mermaid
+sequenceDiagram
+  participant SecurityViewModel
+  participant SecurityApplication
+  participant ISecurityRepository
+  participant LoginResult
+  participant TokenStore
+
+  SecurityViewModel->>SecurityApplication: login(credentials)
+  SecurityApplication->>ISecurityRepository: login(credentials)
+  ISecurityRepository-->>SecurityApplication: LoginResult
+  SecurityApplication->>TokenStore: save(accessToken)
+```
+
+`SecurityViewModel.submit` 在 `activeTab` 为 `LOGIN` 时调用 `login`。仓储返回的是 `User` 和 `accessToken`，不是未标明类型的用户字段。用例只把 `accessToken` 交给 `TokenStore.save`。`AUTH_CHANGED` 是会话发出的界面通知，不是领域事件。通知怎样到达页面，见 [会话](../../基础应用/会话(session).md)。