luo/one-pipe-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: One Pipe System

Browse Source 
完整的管理系统，包含账户管理、卡片管理、套餐管理、财务管理等功能模块。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
sexygoat
2026-01-22 16:35:33 +08:00
commit 222e5bb11a
495 changed files with 145440 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

456
openspec/AGENTS.md Normal file
View File

@@ -0,0 +1,456 @@
# OpenSpec Instructions
Instructions for AI coding assistants using OpenSpec for spec-driven development.
## TL;DR Quick Checklist
- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
- Decide scope: new capability vs modify existing capability
- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
- Validate: `openspec validate [change-id] --strict` and fix issues
- Request approval: Do not start implementation until proposal is approved
## Three-Stage Workflow
### Stage 1: Creating Changes
Create proposal when you need to:
- Add features or functionality
- Make breaking changes (API, schema)
- Change architecture or patterns
- Optimize performance (changes behavior)
- Update security patterns
Triggers (examples):
- "Help me create a change proposal"
- "Help me plan a change"
- "Help me create a proposal"
- "I want to create a spec proposal"
- "I want to create a spec"
Loose matching guidance:
- Contains one of: `proposal`, `change`, `spec`
- With one of: `create`, `plan`, `make`, `start`, `help`
Skip proposal for:
- Bug fixes (restore intended behavior)
- Typos, formatting, comments
- Dependency updates (non-breaking)
- Configuration changes
- Tests for existing behavior
**Workflow**
1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
### Stage 2: Implementing Changes
Track these steps as TODOs and complete them one by one.
1. **Read proposal.md** - Understand what's being built
2. **Read design.md** (if exists) - Review technical decisions
3. **Read tasks.md** - Get implementation checklist
4. **Implement tasks sequentially** - Complete in order
5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
### Stage 3: Archiving Changes
After deployment, create separate PR to:
- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
- Update `specs/` if capabilities changed
- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
- Run `openspec validate --strict` to confirm the archived change passes checks
## Before Any Task
**Context Checklist:**
- [ ] Read relevant specs in `specs/[capability]/spec.md`
- [ ] Check pending changes in `changes/` for conflicts
- [ ] Read `openspec/project.md` for conventions
- [ ] Run `openspec list` to see active changes
- [ ] Run `openspec list --specs` to see existing capabilities
**Before Creating Specs:**
- Always check if capability already exists
- Prefer modifying existing specs over creating duplicates
- Use `openspec show [spec]` to review current state
- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
### Search Guidance
- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
- Show details:
- Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
- Change: `openspec show <change-id> --json --deltas-only`
- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
## Quick Start
### CLI Commands
```bash
# Essential commands
openspec list # List active changes
openspec list --specs # List specifications
openspec show [item] # Display change or spec
openspec validate [item] # Validate changes or specs
openspec archive <change-id> [--yes|-y] # Archive after deployment (add --yes for non-interactive runs)
# Project management
openspec init [path] # Initialize OpenSpec
openspec update [path] # Update instruction files
# Interactive mode
openspec show # Prompts for selection
openspec validate # Bulk validation mode
# Debugging
openspec show [change] --json --deltas-only
openspec validate [change] --strict
```
### Command Flags
- `--json` - Machine-readable output
- `--type change|spec` - Disambiguate items
- `--strict` - Comprehensive validation
- `--no-interactive` - Disable prompts
- `--skip-specs` - Archive without spec updates
- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
## Directory Structure
```
openspec/
├── project.md # Project conventions
├── specs/ # Current truth - what IS built
│ └── [capability]/ # Single focused capability
│ ├── spec.md # Requirements and scenarios
│ └── design.md # Technical patterns
├── changes/ # Proposals - what SHOULD change
│ ├── [change-name]/
│ │ ├── proposal.md # Why, what, impact
│ │ ├── tasks.md # Implementation checklist
│ │ ├── design.md # Technical decisions (optional; see criteria)
│ │ └── specs/ # Delta changes
│ │ └── [capability]/
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
│ └── archive/ # Completed changes
```
## Creating Change Proposals
### Decision Tree
```
New request?
├─ Bug fix restoring spec behavior? → Fix directly
├─ Typo/format/comment? → Fix directly
├─ New feature/capability? → Create proposal
├─ Breaking change? → Create proposal
├─ Architecture change? → Create proposal
└─ Unclear? → Create proposal (safer)
```
### Proposal Structure
1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
2. **Write proposal.md:**
```markdown
# Change: [Brief description of change]
## Why
[1-2 sentences on problem/opportunity]
## What Changes
- [Bullet list of changes]
- [Mark breaking changes with **BREAKING**]
## Impact
- Affected specs: [list capabilities]
- Affected code: [key files/systems]
```
3. **Create spec deltas:** `specs/[capability]/spec.md`
```markdown
## ADDED Requirements
### Requirement: New Feature
The system SHALL provide...
#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result
## MODIFIED Requirements
### Requirement: Existing Feature
[Complete modified requirement]
## REMOVED Requirements
### Requirement: Old Feature
**Reason**: [Why removing]
**Migration**: [How to handle]
```
If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
4. **Create tasks.md:**
```markdown
## 1. Implementation
- [ ] 1.1 Create database schema
- [ ] 1.2 Implement API endpoint
- [ ] 1.3 Add frontend component
- [ ] 1.4 Write tests
```
5. **Create design.md when needed:**
Create `design.md` if any of the following apply; otherwise omit it:
- Cross-cutting change (multiple services/modules) or a new architectural pattern
- New external dependency or significant data model changes
- Security, performance, or migration complexity
- Ambiguity that benefits from technical decisions before coding
Minimal `design.md` skeleton:
```markdown
## Context
[Background, constraints, stakeholders]
## Goals / Non-Goals
- Goals: [...]
- Non-Goals: [...]
## Decisions
- Decision: [What and why]
- Alternatives considered: [Options + rationale]
## Risks / Trade-offs
- [Risk] → Mitigation
## Migration Plan
[Steps, rollback]
## Open Questions
- [...]
```
## Spec File Format
### Critical: Scenario Formatting
**CORRECT** (use #### headers):
```markdown
#### Scenario: User login success
- **WHEN** valid credentials provided
- **THEN** return JWT token
```
**WRONG** (don't use bullets or bold):
```markdown
- **Scenario: User login** ❌
**Scenario**: User login ❌
### Scenario: User login ❌
```
Every requirement MUST have at least one scenario.
### Requirement Wording
- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
### Delta Operations
- `## ADDED Requirements` - New capabilities
- `## MODIFIED Requirements` - Changed behavior
- `## REMOVED Requirements` - Deprecated features
- `## RENAMED Requirements` - Name changes
Headers matched with `trim(header)` - whitespace ignored.
#### When to use ADDED vs MODIFIED
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
Authoring a MODIFIED requirement correctly:
1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
Example for RENAMED:
```markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`
```
## Troubleshooting
### Common Errors
**"Change must have at least one delta"**
- Check `changes/[name]/specs/` exists with .md files
- Verify files have operation prefixes (## ADDED Requirements)
**"Requirement must have at least one scenario"**
- Check scenarios use `#### Scenario:` format (4 hashtags)
- Don't use bullet points or bold for scenario headers
**Silent scenario parsing failures**
- Exact format required: `#### Scenario: Name`
- Debug with: `openspec show [change] --json --deltas-only`
### Validation Tips
```bash
# Always use strict mode for comprehensive checks
openspec validate [change] --strict
# Debug delta parsing
openspec show [change] --json | jq '.deltas'
# Check specific requirement
openspec show [spec] --json -r 1
```
## Happy Path Script
```bash
# 1) Explore current state
openspec spec list --long
openspec list
# Optional full-text search:
# rg -n "Requirement:|Scenario:" openspec/specs
# rg -n "^#|Requirement:" openspec/changes
# 2) Choose change id and scaffold
CHANGE=add-two-factor-auth
mkdir -p openspec/changes/$CHANGE/{specs/auth}
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
# 3) Add deltas (example)
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
## ADDED Requirements
### Requirement: Two-Factor Authentication
Users MUST provide a second factor during login.
#### Scenario: OTP required
- **WHEN** valid credentials are provided
- **THEN** an OTP challenge is required
EOF
# 4) Validate
openspec validate $CHANGE --strict
```
## Multi-Capability Example
```
openspec/changes/add-2fa-notify/
├── proposal.md
├── tasks.md
└── specs/
├── auth/
│ └── spec.md # ADDED: Two-Factor Authentication
└── notifications/
└── spec.md # ADDED: OTP email notification
```
auth/spec.md
```markdown
## ADDED Requirements
### Requirement: Two-Factor Authentication
...
```
notifications/spec.md
```markdown
## ADDED Requirements
### Requirement: OTP Email Notification
...
```
## Best Practices
### Simplicity First
- Default to <100 lines of new code
- Single-file implementations until proven insufficient
- Avoid frameworks without clear justification
- Choose boring, proven patterns
### Complexity Triggers
Only add complexity with:
- Performance data showing current solution too slow
- Concrete scale requirements (>1000 users, >100MB data)
- Multiple proven use cases requiring abstraction
### Clear References
- Use `file.ts:42` format for code locations
- Reference specs as `specs/auth/spec.md`
- Link related changes and PRs
### Capability Naming
- Use verb-noun: `user-auth`, `payment-capture`
- Single purpose per capability
- 10-minute understandability rule
- Split if description needs "AND"
### Change ID Naming
- Use kebab-case, short and descriptive: `add-two-factor-auth`
- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
## Tool Selection Guide
| Task | Tool | Why |
|------|------|-----|
| Find files by pattern | Glob | Fast pattern matching |
| Search code content | Grep | Optimized regex search |
| Read specific files | Read | Direct file access |
| Explore unknown scope | Task | Multi-step investigation |
## Error Recovery
### Change Conflicts
1. Run `openspec list` to see active changes
2. Check for overlapping specs
3. Coordinate with change owners
4. Consider combining proposals
### Validation Failures
1. Run with `--strict` flag
2. Check JSON output for details
3. Verify spec file format
4. Ensure scenarios properly formatted
### Missing Context
1. Read project.md first
2. Check related specs
3. Review recent archives
4. Ask for clarification
## Quick Reference
### Stage Indicators
- `changes/` - Proposed, not yet built
- `specs/` - Built and deployed
- `archive/` - Completed changes
### File Purposes
- `proposal.md` - Why and what
- `tasks.md` - Implementation steps
- `design.md` - Technical decisions
- `spec.md` - Requirements and behavior
### CLI Essentials
```bash
openspec list # What's in progress?
openspec show [item] # View details
openspec validate --strict # Is it correct?
openspec archive <change-id> [--yes|-y] # Mark complete (add --yes for automation)
```
Remember: Specs are truth. Changes are proposals. Keep them in sync.

34
openspec/changes/add-customer-account-management/proposal.md Normal file
View File

@@ -0,0 +1,34 @@
# Change: 客户账户管理功能
## Why
运营平台需要统一查看和管理所有客户（包括代理商和企业客户）的账户佣金情况，包括佣金总额、可提现金额、待入账金额、已提现金额等财务数据。目前系统缺少集中的客户账户财务视图，运营人员无法高效地了解客户的佣金和提现状况。
## What Changes
- 新增客户账户管理页面（`src/views/finance/customer-account/index.vue`）
- 提供客户账户列表查询功能，支持按客户账号、客户名称、客户类型筛选
- 展示客户的佣金相关财务数据：
- 佣金总额
- 可提现金额
- 待入账金额
- 已提现金额
- 提现次数
- 最后提现时间
- 提供查看客户账户详情功能
- 提供查看客户流水记录功能（入口）
- 添加国际化支持（中英文）
- 添加路由配置（财务模块下）
## Impact
- 新增规范：`specs/customer-account-management/spec.md`
- 新增文件：
- `src/views/finance/customer-account/index.vue`
- 修改文件：
- `src/router/routes/asyncRoutes.ts`（添加路由）
- `src/router/routesAlias.ts`（添加路由别名）
- `src/locales/langs/zh.json`（添加中文翻译）
- `src/locales/langs/en.json`（添加英文翻译）
- `docs/功能.md`（文档更新）
- 依赖模块：
- Element Plus 组件（ElTable, ElForm, ElDialog 等）
- 现有的 ArtTable 组件
- 后端 API（待对接）

144
openspec/changes/add-customer-account-management/specs/customer-account-management/spec.md Normal file
View File

@@ -0,0 +1,144 @@
# 客户账户管理规范
## ADDED Requirements
### Requirement: 客户账户列表查询
系统 SHALL 提供客户账户列表查询功能，运营人员可以查看所有客户的账户财务信息。
#### Scenario: 查询所有客户账户
- **WHEN** 运营人员访问客户账户管理页面
- **THEN** 系统显示所有客户账户列表，包含以下字段：
- 客户账号
- 客户名称
- 客户类型（代理商/企业客户）
- 佣金总额
- 可提现金额
- 待入账金额
- 已提现金额
- 提现次数
- 最后提现时间
#### Scenario: 按客户账号搜索
- **WHEN** 运营人员在搜索框输入客户账号并点击查询
- **THEN** 系统返回匹配该账号的客户记录
#### Scenario: 按客户名称搜索
- **WHEN** 运营人员在搜索框输入客户名称并点击查询
- **THEN** 系统返回名称包含该关键词的客户记录
#### Scenario: 按客户类型筛选
- **WHEN** 运营人员选择客户类型（代理商或企业客户）并点击查询
- **THEN** 系统返回该类型的所有客户记录
#### Scenario: 组合条件搜索
- **WHEN** 运营人员同时使用多个搜索条件（如账号 + 类型）并点击查询
- **THEN** 系统返回同时满足所有条件的客户记录
#### Scenario: 重置搜索条件
- **WHEN** 运营人员点击重置按钮
- **THEN** 系统清空所有搜索条件并显示完整列表
### Requirement: 分页功能
系统 SHALL 支持客户账户列表的分页展示，以提高大数据量下的性能和用户体验。
#### Scenario: 默认分页显示
- **WHEN** 运营人员首次访问页面
- **THEN** 系统默认显示第 1 页，每页 20 条记录
#### Scenario: 切换页码
- **WHEN** 运营人员点击分页器的页码
- **THEN** 系统跳转到对应页面并加载数据
#### Scenario: 调整每页显示数量
- **WHEN** 运营人员选择不同的每页显示数量（10/20/50/100）
- **THEN** 系统重新加载数据并按新的数量显示
#### Scenario: 显示总记录数
- **WHEN** 数据加载完成后
- **THEN** 分页器显示总记录数
### Requirement: 客户账户详情查看
系统 SHALL 提供客户账户详情查看功能，展示客户的完整财务信息。
#### Scenario: 打开详情对话框
- **WHEN** 运营人员点击某个客户的"查看详情"按钮
- **THEN** 系统弹出详情对话框，展示以下信息：
- 客户账号
- 客户名称
- 客户类型
- 联系电话
- 佣金总额
- 可提现金额
- 待入账金额
- 已提现金额
- 提现次数
- 最后提现时间
- 注册时间
- 备注
#### Scenario: 关闭详情对话框
- **WHEN** 运营人员点击对话框关闭按钮或遮罩层
- **THEN** 系统关闭详情对话框
### Requirement: 客户流水记录入口
系统 SHALL 提供客户流水记录查看入口，方便运营人员查看客户的佣金流水明细。
#### Scenario: 触发流水记录查看
- **WHEN** 运营人员点击某个客户的"流水记录"按钮
- **THEN** 系统导航到该客户的流水记录页面或打开流水记录对话框
### Requirement: 数据展示样式
系统 SHALL 使用不同的视觉样式区分不同类型的数据，提升可读性。
#### Scenario: 客户类型标签样式
- **WHEN** 列表或详情中显示客户类型
- **THEN** 代理商显示为绿色标签，企业客户显示为蓝色标签
#### Scenario: 金额颜色区分
- **WHEN** 列表或详情中显示金额数据
- **THEN** 可提现金额使用绿色高亮，待入账金额使用橙色高亮
#### Scenario: 金额格式化
- **WHEN** 系统显示金额数据
- **THEN** 金额显示为货币格式，保留两位小数，前缀人民币符号"¥"
### Requirement: 国际化支持
系统 SHALL 支持中英文双语界面，所有文案通过国际化文件管理。
#### Scenario: 中文界面显示
- **WHEN** 系统语言设置为中文
- **THEN** 所有界面文案显示为中文
#### Scenario: 英文界面显示
- **WHEN** 系统语言设置为英文
- **THEN** 所有界面文案显示为英文
### Requirement: 数据权限控制
系统 SHALL 根据运营人员的权限角色，控制其可见的客户账户范围。
#### Scenario: 管理员权限
- **WHEN** 管理员访问客户账户页面
- **THEN** 系统显示所有客户账户
#### Scenario: 普通运营人员权限
- **WHEN** 普通运营人员访问客户账户页面
- **THEN** 系统仅显示其权限范围内的客户账户
### Requirement: 异常处理与用户反馈
系统 SHALL 在操作过程中提供清晰的用户反馈和错误处理。
#### Scenario: 查询成功反馈
- **WHEN** 用户执行搜索操作且成功返回结果
- **THEN** 系统显示成功消息提示
#### Scenario: 查询失败处理
- **WHEN** API 请求失败或超时
- **THEN** 系统显示错误消息，并提示用户重试
#### Scenario: 数据加载状态
- **WHEN** 系统正在加载数据
- **THEN** 显示加载动画或骨架屏，防止用户误操作
#### Scenario: 空数据提示
- **WHEN** 查询结果为空
- **THEN** 系统显示"暂无数据"提示

51
openspec/changes/add-customer-account-management/tasks.md Normal file
View File

@@ -0,0 +1,51 @@
# 实现任务清单
## 1. 前端页面实现
- [x] 1.1 创建客户账户管理页面组件 `src/views/finance/customer-account/index.vue`
- [x] 1.1.1 实现搜索表单（客户账号、客户名称、客户类型）
- [x] 1.1.2 实现数据表格展示（使用 ArtTable）
- [x] 1.1.3 实现分页功能
- [x] 1.1.4 实现详情对话框
- [x] 1.1.5 添加操作按钮（查看详情、流水记录）
- [x] 1.2 添加路由配置
- [x] 1.2.1 在 `src/router/routes/asyncRoutes.ts` 中添加路由
- [x] 1.2.2 在 `src/router/routesAlias.ts` 中添加路由别名
- [x] 1.3 添加国际化支持
- [x] 1.3.1 在 `src/locales/langs/zh.json` 中添加中文文案
- [x] 1.3.2 在 `src/locales/langs/en.json` 中添加英文文案
## 2. API 集成（待实现）
- [ ] 2.1 创建 API 模块 `src/api/modules/customerAccountApi.ts`
- [ ] 2.1.1 实现客户账户列表查询接口
- [ ] 2.1.2 实现客户账户详情查询接口
- [ ] 2.1.3 实现客户流水记录查询接口
- [ ] 2.2 定义 TypeScript 类型
- [ ] 2.2.1 定义客户账户数据类型 `CustomerAccount`
- [ ] 2.2.2 定义搜索参数类型 `CustomerAccountSearchParams`
- [ ] 2.2.3 定义流水记录类型 `CustomerAccountFlow`
- [ ] 2.3 替换页面中的模拟数据为真实 API 调用
## 3. 流水记录功能（待实现）
- [ ] 3.1 创建流水记录子页面或对话框
- [ ] 3.2 实现流水记录列表展示
- [ ] 3.3 实现流水记录筛选和分页
## 4. 权限控制（待实现）
- [ ] 4.1 配置页面访问权限（后台权限系统）
- [ ] 4.2 添加按钮级权限控制（如需要）
## 5. 测试与优化
- [ ] 5.1 单元测试（工具函数、业务逻辑）
- [ ] 5.2 集成测试（API 调用）
- [ ] 5.3 性能优化（大数据量处理）
- [ ] 5.4 用户体验优化（加载状态、错误处理）
## 6. 文档更新
- [x] 6.1 更新 `docs/功能.md` 功能列表
## 当前状态
- ✅ 第 1 阶段（前端页面框架）已完成，使用模拟数据
- ⏳ 第 2 阶段（API 集成）待实现
- ⏳ 第 3 阶段（流水记录）待实现
- ⏳ 第 4 阶段（权限控制）待实现
- ⏳ 第 5 阶段（测试优化）待实现

40
openspec/changes/add-permission-management/proposal.md Normal file
View File

@@ -0,0 +1,40 @@
# Change: 权限管理功能
## Why
系统需要完整的权限管理能力，允许管理员对系统的菜单权限、按钮权限和 API 权限进行统一管理。当前虽然已有权限相关的 API 接口（`docs/部分API.md`），但缺少前端的权限管理界面，导致运营人员无法直观地配置和管理权限体系。
## What Changes
- 新增权限管理页面（`src/views/system/permission/index.vue`）
- 完整实现权限 CRUD 功能
- 支持权限树形展示（菜单、按钮、API 三级结构）
- 提供权限搜索和筛选功能
- 支持权限状态管理（启用/禁用）
- 添加国际化支持（中英文）
- 添加路由配置
- 创建权限 API 模块（已完成）
- `src/api/modules/permission.ts`
- `src/types/api/permission.ts`
## Impact
- 新增规范：`specs/permission-management/spec.md`
- 新增文件：
- `src/views/system/permission/index.vue` (权限管理页面)
- `src/api/modules/permission.ts` (✅ 已创建)
- `src/types/api/permission.ts` (✅ 已创建)
- 修改文件：
- `src/router/routes/asyncRoutes.ts` (添加权限管理路由)
- `src/router/routesAlias.ts` (添加路由别名)
- `src/locales/langs/zh.json` (添加中文翻译)
- `src/locales/langs/en.json` (添加英文翻译)
- `src/api/modules/index.ts` (✅ 已导出 PermissionService)
- `src/types/api/index.ts` (✅ 已导出权限类型)
- 依赖接口（参考 `docs/部分API.md`）：
- 权限列表 (GET /api/permissions)
- 创建权限 (POST /api/permissions)
- 删除权限 (DELETE /api/permissions/:id)
- 获取权限详情 (GET /api/permissions/:id)
- 更新权限 (PUT /api/permissions/:id)
- 获取权限树 (GET /api/permissions/tree)
- 关联模块：
- 角色管理：分配权限时使用权限树
- 平台账号管理：账号通过角色获得权限

206
openspec/changes/add-permission-management/specs/permission-management/spec.md Normal file
View File

@@ -0,0 +1,206 @@
# 权限管理规范
## ADDED Requirements
### Requirement: 权限列表展示
系统 SHALL 提供权限列表展示功能，以树形表格形式展示系统的完整权限结构。
#### Scenario: 展示权限树形列表
- **WHEN** 管理员访问权限管理页面
- **THEN** 系统以树形表格展示所有权限，包含以下字段：
- 权限名称
- 权限标识（permissionCode）
- 权限类型（菜单/按钮/API）
- 父级权限（如有）
- 菜单路径（menu类型）
- 图标（menu类型）
- 排序序号
- 状态（启用/禁用）
- 创建时间
- 操作按钮
#### Scenario: 按权限名称搜索
- **WHEN** 管理员在搜索框输入权限名称并点击查询
- **THEN** 系统返回名称包含该关键词的权限记录，保持树形结构
#### Scenario: 按权限标识搜索
- **WHEN** 管理员在搜索框输入权限标识并点击查询
- **THEN** 系统返回匹配该标识的权限记录及其父级权限
#### Scenario: 按权限类型筛选
- **WHEN** 管理员选择权限类型（菜单/按钮/API）并点击查询
- **THEN** 系统返回该类型的所有权限，保持树形结构
#### Scenario: 按权限状态筛选
- **WHEN** 管理员选择权限状态（启用/禁用）并点击查询
- **THEN** 系统返回该状态的所有权限
#### Scenario: 重置搜索条件
- **WHEN** 管理员点击重置按钮
- **THEN** 系统清空所有搜索条件并显示完整权限树
### Requirement: 新增权限
系统 SHALL 提供新增权限功能，允许管理员创建新的菜单、按钮或 API 权限。
#### Scenario: 打开新增权限对话框
- **WHEN** 管理员点击"新增权限"按钮
- **THEN** 系统弹出新增权限对话框，包含以下字段：
- 权限名称（必填）
- 权限标识（必填，唯一）
- 权限类型（必选：菜单/按钮/API）
- 父级权限（可选，树形选择）
- 菜单路径（权限类型为菜单时必填）
- 菜单图标（权限类型为菜单时可选）
- 排序序号（可选，数字）
- 状态（启用/禁用，默认启用）
- 描述（可选）
#### Scenario: 成功创建权限
- **WHEN** 管理员填写完整信息并点击确定
- **THEN** 系统验证数据有效性，创建权限记录，关闭对话框，刷新权限列表，显示成功提示
#### Scenario: 权限标识重复
- **WHEN** 管理员输入已存在的权限标识并提交
- **THEN** 系统显示"权限标识已存在"错误提示，不创建记录
#### Scenario: 必填字段校验
- **WHEN** 管理员未填写必填字段并提交
- **THEN** 系统高亮显示未填写的必填字段，显示"请填写必填项"提示
### Requirement: 编辑权限
系统 SHALL 提供编辑权限功能，允许管理员修改已有权限的信息。
#### Scenario: 打开编辑权限对话框
- **WHEN** 管理员点击某个权限的"编辑"按钮
- **THEN** 系统弹出编辑对话框，预填充该权限的当前信息
#### Scenario: 成功更新权限
- **WHEN** 管理员修改信息并点击确定
- **THEN** 系统验证数据有效性，更新权限记录，关闭对话框，刷新列表，显示成功提示
#### Scenario: 不允许修改权限标识为重复值
- **WHEN** 管理员修改权限标识为已存在的其他标识并提交
- **THEN** 系统显示"权限标识已存在"错误提示，不更新记录
### Requirement: 删除权限
系统 SHALL 提供删除权限功能，允许管理员删除不再使用的权限。
#### Scenario: 删除单个权限（无子权限）
- **WHEN** 管理员点击某个无子权限的"删除"按钮并确认
- **THEN** 系统删除该权限记录，刷新列表，显示成功提示
#### Scenario: 删除权限前二次确认
- **WHEN** 管理员点击"删除"按钮
- **THEN** 系统弹出确认对话框，提示"确定要删除该权限吗？此操作不可撤销"
#### Scenario: 删除有子权限的权限
- **WHEN** 管理员尝试删除有子权限的权限
- **THEN** 系统提示"该权限下存在子权限，请先删除子权限"，不执行删除
#### Scenario: 删除已分配给角色的权限
- **WHEN** 管理员尝试删除已分配给角色的权限
- **THEN** 系统提示"该权限已分配给角色，请先从角色中移除该权限"，不执行删除
#### Scenario: 取消删除操作
- **WHEN** 管理员在确认对话框中点击取消
- **THEN** 系统关闭对话框，不删除权限
### Requirement: 批量删除权限
系统 SHALL 提供批量删除权限功能，允许管理员一次性删除多个权限。
#### Scenario: 选择多个权限并删除
- **WHEN** 管理员选中多个无子权限的权限并点击"批量删除"按钮并确认
- **THEN** 系统删除所有选中的权限，刷新列表，显示成功提示（如"成功删除 3 个权限"）
#### Scenario: 批量删除包含有子权限的权限
- **WHEN** 管理员选中的权限中包含有子权限的权限
- **THEN** 系统仅删除无子权限的权限，提示"部分权限存在子权限，已跳过删除"
### Requirement: 权限状态管理
系统 SHALL 提供权限状态切换功能，允许管理员启用或禁用权限。
#### Scenario: 切换权限状态
- **WHEN** 管理员点击权限的状态开关
- **THEN** 系统更新该权限的状态（启用↔禁用），刷新列表，显示成功提示
#### Scenario: 禁用父级权限
- **WHEN** 管理员禁用有子权限的权限
- **THEN** 系统同时禁用其所有子权限，提示"已同时禁用 X 个子权限"
### Requirement: 权限树形展示
系统 SHALL 以树形结构展示权限的层级关系，支持展开/折叠操作。
#### Scenario: 默认展开第一级
- **WHEN** 管理员首次访问权限管理页面
- **THEN** 系统默认展开第一级权限，其余层级折叠
#### Scenario: 展开/折叠权限节点
- **WHEN** 管理员点击权限节点的展开/折叠图标
- **THEN** 系统展开或折叠该节点的子权限
#### Scenario: 展开全部权限
- **WHEN** 管理员点击"全部展开"按钮
- **THEN** 系统展开所有权限节点
#### Scenario: 折叠全部权限
- **WHEN** 管理员点击"全部折叠"按钮
- **THEN** 系统折叠所有权限节点，仅显示第一级
### Requirement: 权限类型可视化区分
系统 SHALL 使用不同的视觉样式区分权限类型，提升可读性。
#### Scenario: 权限类型标签样式
- **WHEN** 列表中显示权限类型
- **THEN** 菜单权限显示为蓝色标签，按钮权限显示为绿色标签，API权限显示为橙色标签
#### Scenario: 权限类型图标
- **WHEN** 权限为菜单类型且配置了图标
- **THEN** 在权限名称前显示对应的菜单图标
### Requirement: 权限详情查看
系统 SHALL 提供权限详情查看功能，展示权限的完整信息。
#### Scenario: 查看权限详情
- **WHEN** 管理员点击权限的"查看"按钮
- **THEN** 系统弹出详情对话框，展示权限的所有字段信息，包括创建时间、更新时间等
### Requirement: 国际化支持
系统 SHALL 支持中英文双语界面，所有文案通过国际化文件管理。
#### Scenario: 中文界面显示
- **WHEN** 系统语言设置为中文
- **THEN** 所有界面文案显示为中文
#### Scenario: 英文界面显示
- **WHEN** 系统语言设置为英文
- **THEN** 所有界面文案显示为英文
### Requirement: 访问权限控制
系统 SHALL 限制权限管理页面的访问权限，仅超级管理员可访问。
#### Scenario: 超级管理员访问
- **WHEN** 超级管理员访问权限管理页面
- **THEN** 系统正常显示权限管理界面
#### Scenario: 普通管理员访问
- **WHEN** 普通管理员尝试访问权限管理页面
- **THEN** 系统显示"403 无权访问"页面或重定向到首页
### Requirement: 异常处理与用户反馈
系统 SHALL 在操作过程中提供清晰的用户反馈和错误处理。
#### Scenario: 操作成功反馈
- **WHEN** 用户执行新增/编辑/删除操作成功
- **THEN** 系统显示成功消息提示（如"权限创建成功"）
#### Scenario: API 请求失败处理
- **WHEN** API 请求失败或超时
- **THEN** 系统显示错误消息，并提示用户重试
#### Scenario: 数据加载状态
- **WHEN** 系统正在加载权限数据
- **THEN** 显示加载动画或骨架屏，防止用户误操作
#### Scenario: 空数据提示
- **WHEN** 权限列表为空
- **THEN** 系统显示"暂无权限数据，点击新增按钮创建权限"提示

67
openspec/changes/add-permission-management/tasks.md Normal file
View File

@@ -0,0 +1,67 @@
# 实现任务清单
## 1. API 模块实现
- [x] 1.1 创建权限类型定义 `src/types/api/permission.ts`
- [x] 1.2 创建权限 API 模块 `src/api/modules/permission.ts`
- [x] 权限列表查询
- [x] 权限树查询
- [x] 权限详情查询
- [x] 创建权限
- [x] 更新权限
- [x] 删除权限
- [x] 批量删除权限
- [x] 更新权限状态
- [x] 1.3 导出权限服务和类型
## 2. 前端页面实现
- [ ] 2.1 创建权限管理页面组件 `src/views/system/permission/index.vue`
- [ ] 2.1.1 实现权限列表展示（树形表格）
- [ ] 2.1.2 实现搜索表单（权限名称、权限标识、权限类型）
- [ ] 2.1.3 实现新增权限功能（对话框表单）
- [ ] 2.1.4 实现编辑权限功能
- [ ] 2.1.5 实现删除权限功能（含确认）
- [ ] 2.1.6 实现批量删除功能
- [ ] 2.1.7 实现权限状态切换（启用/禁用）
- [ ] 2.1.8 实现分页功能
- [ ] 2.2 添加路由配置
- [ ] 2.2.1 在 `src/router/routes/asyncRoutes.ts` 中添加权限管理路由
- [ ] 2.2.2 在 `src/router/routesAlias.ts` 中添加路由别名
- [ ] 2.3 添加国际化支持
- [ ] 2.3.1 在 `src/locales/langs/zh.json` 中添加中文文案
- [ ] 2.3.2 在 `src/locales/langs/en.json` 中添加英文文案
## 3. 权限类型支持
- [ ] 3.1 实现菜单权限展示和配置
- [ ] 3.2 实现按钮权限展示和配置
- [ ] 3.3 实现 API 权限展示和配置
- [ ] 3.4 实现权限树形结构选择组件（可复用于角色分配）
## 4. 数据验证与交互优化
- [ ] 4.1 表单字段验证
- [ ] 权限名称必填
- [ ] 权限标识必填且唯一
- [ ] 权限类型必选
- [ ] 4.2 用户体验优化
- [ ] 加载状态提示
- [ ] 操作成功/失败消息提示
- [ ] 删除前二次确认
- [ ] 空数据提示
## 5. 权限控制
- [ ] 5.1 配置页面访问权限（仅超级管理员可访问）
- [ ] 5.2 添加按钮级权限控制（新增、编辑、删除等）
## 6. 测试与优化
- [ ] 6.1 功能测试（CRUD 操作）
- [ ] 6.2 树形结构展示测试
- [ ] 6.3 权限树选择组件测试
- [ ] 6.4 性能优化（大数据量情况）
- [ ] 6.5 异常处理测试
## 当前状态
- ✅ 第 1 阶段（API 模块）已完成
- ⏳ 第 2 阶段（前端页面）待实现
- ⏳ 第 3 阶段（权限类型）待实现
- ⏳ 第 4 阶段（验证优化）待实现
- ⏳ 第 5 阶段（权限控制）待实现
- ⏳ 第 6 阶段（测试优化）待实现

40
openspec/changes/add-platform-account-management/proposal.md Normal file
View File

@@ -0,0 +1,40 @@
# Change: 平台账号管理功能
## Why
系统需要完整的平台账号管理能力，允许超级管理员管理平台内部的运营和管理人员账号。虽然后端已提供完整的平台账号 API（参考 `docs/部分API.md`），但缺少前端管理界面，导致管理员无法通过界面直观地管理平台账号、分配角色和控制账号状态。
## What Changes
- 新增平台账号管理页面（`src/views/system/platform-account/index.vue`）
- 完整实现平台账号 CRUD 功能
- 支持平台账号列表查询和筛选
- 提供角色分配功能（为账号分配/移除角色）
- 支持修改账号密码
- 支持启用/禁用账号
- 添加国际化支持（中英文）
- 添加路由配置
- 平台账号 API 模块已完善（已补全缺失接口）
## Impact
- 新增规范：`specs/platform-account-management/spec.md`
- 新增文件：
- `src/views/system/platform-account/index.vue` (平台账号管理页面)
- 修改文件：
- `src/router/routes/asyncRoutes.ts` (添加平台账号管理路由)
- `src/router/routesAlias.ts` (添加路由别名)
- `src/locales/langs/zh.json` (添加中文翻译)
- `src/locales/langs/en.json` (添加英文翻译)
- 依赖接口（参考 `docs/部分API.md`）：
- 平台账号列表 (GET /api/platform-accounts)
- 新增平台账号 (POST /api/platform-accounts)
- 删除平台账号 (DELETE /api/platform-accounts/:id)
- 获取平台账号详情 (GET /api/platform-accounts/:id)
- 编辑平台账号 (PUT /api/platform-accounts/:id)
- 修改密码 (POST /api/platform-accounts/:id/password)
- 获取账号角色 (GET /api/platform-accounts/:id/roles)
- 分配角色 (POST /api/platform-accounts/:id/roles)
- 移除角色 (DELETE /api/platform-accounts/:id/roles)
- 启用/禁用账号 (PUT /api/platform-accounts/:id/status)
- 依赖模块：
- `src/api/modules/account.ts` (✅ 已补全所有接口)
- 角色管理：获取角色列表用于分配
- 权限系统：控制页面访问权限

241
openspec/changes/add-platform-account-management/specs/platform-account-management/spec.md Normal file
View File

@@ -0,0 +1,241 @@
# 平台账号管理规范
## ADDED Requirements
### Requirement: 平台账号列表展示
系统 SHALL 提供平台账号列表展示功能，以表格形式展示所有平台内部账号。
#### Scenario: 展示账号列表
- **WHEN** 超级管理员访问平台账号管理页面
- **THEN** 系统以表格展示所有平台账号，包含以下字段：
- 账号ID
- 账号名称
- 用户名（登录名）
- 手机号
- 邮箱
- 角色列表
- 状态（启用/禁用）
- 创建时间
- 最后登录时间
- 操作按钮
#### Scenario: 按账号名称搜索
- **WHEN** 管理员在搜索框输入账号名称并点击查询
- **THEN** 系统返回名称包含该关键词的账号记录
#### Scenario: 按用户名搜索
- **WHEN** 管理员在搜索框输入用户名并点击查询
- **THEN** 系统返回用户名包含该关键词的账号记录
#### Scenario: 按状态筛选
- **WHEN** 管理员选择账号状态（启用/禁用）并点击查询
- **THEN** 系统返回该状态的所有账号
#### Scenario: 重置搜索条件
- **WHEN** 管理员点击重置按钮
- **THEN** 系统清空所有搜索条件并显示完整列表
### Requirement: 新增平台账号
系统 SHALL 提供新增平台账号功能，允许管理员创建新的平台运营或管理账号。
#### Scenario: 打开新增账号对话框
- **WHEN** 管理员点击"新增账号"按钮
- **THEN** 系统弹出新增账号对话框，包含以下字段：
- 账号名称（必填）
- 用户名（必填，唯一，作为登录名）
- 密码（必填，需符合强度要求）
- 确认密码（必填，需与密码一致）
- 手机号（必填，格式验证）
- 邮箱（可选，格式验证）
- 状态（启用/禁用，默认启用）
- 备注（可选）
#### Scenario: 成功创建账号
- **WHEN** 管理员填写完整信息并点击确定
- **THEN** 系统验证数据有效性，创建账号记录，关闭对话框，刷新列表，显示成功提示
#### Scenario: 用户名重复
- **WHEN** 管理员输入已存在的用户名并提交
- **THEN** 系统显示"用户名已存在"错误提示，不创建记录
#### Scenario: 密码强度不足
- **WHEN** 管理员输入不符合强度要求的密码并提交
- **THEN** 系统显示"密码强度不足，至少8位且包含字母、数字"错误提示
#### Scenario: 确认密码不一致
- **WHEN** 管理员输入的确认密码与密码不一致并提交
- **THEN** 系统显示"两次输入的密码不一致"错误提示
#### Scenario: 必填字段校验
- **WHEN** 管理员未填写必填字段并提交
- **THEN** 系统高亮显示未填写的必填字段，显示"请填写必填项"提示
### Requirement: 编辑平台账号
系统 SHALL 提供编辑平台账号功能，允许管理员修改已有账号的基本信息。
#### Scenario: 打开编辑账号对话框
- **WHEN** 管理员点击某个账号的"编辑"按钮
- **THEN** 系统弹出编辑对话框，预填充该账号的当前信息（不包含密码）
#### Scenario: 成功更新账号
- **WHEN** 管理员修改信息并点击确定
- **THEN** 系统验证数据有效性，更新账号记录，关闭对话框，刷新列表，显示成功提示
#### Scenario: 编辑时不允许修改用户名为重复值
- **WHEN** 管理员修改用户名为已存在的其他用户名并提交
- **THEN** 系统显示"用户名已存在"错误提示，不更新记录
#### Scenario: 编辑时不显示密码
- **WHEN** 管理员打开编辑对话框
- **THEN** 密码字段不显示，系统提示"如需修改密码请使用修改密码功能"
### Requirement: 删除平台账号
系统 SHALL 提供删除平台账号功能，允许管理员删除不再使用的账号。
#### Scenario: 删除账号
- **WHEN** 管理员点击某个账号的"删除"按钮并确认
- **THEN** 系统删除该账号记录，刷新列表，显示成功提示
#### Scenario: 删除前二次确认
- **WHEN** 管理员点击"删除"按钮
- **THEN** 系统弹出确认对话框，提示"确定要删除账号 XXX 吗？此操作不可撤销"
#### Scenario: 禁止删除当前登录账号
- **WHEN** 管理员尝试删除自己当前登录的账号
- **THEN** 系统提示"不能删除当前登录账号"，不执行删除
#### Scenario: 取消删除操作
- **WHEN** 管理员在确认对话框中点击取消
- **THEN** 系统关闭对话框，不删除账号
### Requirement: 查看平台账号详情
系统 SHALL 提供账号详情查看功能，展示账号的完整信息。
#### Scenario: 查看账号详情
- **WHEN** 管理员点击账号的"查看详情"按钮
- **THEN** 系统弹出详情对话框，展示账号的所有字段信息，包括：
- 基本信息（账号名称、用户名、手机号、邮箱）
- 角色信息（已分配的角色列表）
- 状态信息（当前状态、创建时间、更新时间、最后登录时间）
- 备注信息
### Requirement: 修改账号密码
系统 SHALL 提供修改账号密码功能，允许管理员重置平台账号的登录密码。
#### Scenario: 打开修改密码对话框
- **WHEN** 管理员点击账号的"修改密码"按钮
- **THEN** 系统弹出修改密码对话框，包含以下字段：
- 新密码（必填，需符合强度要求）
- 确认新密码（必填，需与新密码一致）
#### Scenario: 成功修改密码
- **WHEN** 管理员输入符合要求的新密码并点击确定
- **THEN** 系统更新账号密码，关闭对话框，显示"密码修改成功"提示
#### Scenario: 新密码强度不足
- **WHEN** 管理员输入不符合强度要求的新密码并提交
- **THEN** 系统显示"密码强度不足，至少8位且包含字母、数字"错误提示
#### Scenario: 确认密码不一致
- **WHEN** 管理员输入的确认密码与新密码不一致并提交
- **THEN** 系统显示"两次输入的密码不一致"错误提示
### Requirement: 角色分配管理
系统 SHALL 提供角色分配功能，允许管理员为平台账号分配或移除角色。
#### Scenario: 打开角色分配对话框
- **WHEN** 管理员点击账号的"分配角色"按钮
- **THEN** 系统弹出角色分配对话框，显示：
- 当前账号已分配的角色列表（可移除）
- 可分配的角色列表（多选框）
#### Scenario: 为账号添加角色
- **WHEN** 管理员选中一个或多个角色并点击确定
- **THEN** 系统为该账号添加选中的角色，刷新角色列表，显示成功提示
#### Scenario: 从账号移除角色
- **WHEN** 管理员在已分配角色列表中移除某个角色并点击确定
- **THEN** 系统从该账号移除该角色，刷新角色列表，显示成功提示
#### Scenario: 显示角色权限说明
- **WHEN** 管理员在角色列表中查看某个角色
- **THEN** 系统显示该角色的描述和主要权限说明
#### Scenario: 至少保留一个角色
- **WHEN** 管理员尝试移除账号的所有角色
- **THEN** 系统提示"账号至少需要保留一个角色"，不允许全部移除
### Requirement: 账号状态管理
系统 SHALL 提供账号状态切换功能，允许管理员启用或禁用平台账号。
#### Scenario: 切换账号状态
- **WHEN** 管理员点击账号的状态开关
- **THEN** 系统更新该账号的状态（启用↔禁用），刷新列表，显示成功提示
#### Scenario: 禁用账号后登录限制
- **WHEN** 账号被禁用后，该账号尝试登录
- **THEN** 系统拒绝登录，提示"账号已被禁用，请联系管理员"
#### Scenario: 禁止禁用当前登录账号
- **WHEN** 管理员尝试禁用自己当前登录的账号
- **THEN** 系统提示"不能禁用当前登录账号"，不执行禁用
### Requirement: 分页功能
系统 SHALL 支持平台账号列表的分页展示，以提高大数据量下的性能和用户体验。
#### Scenario: 默认分页显示
- **WHEN** 管理员首次访问页面
- **THEN** 系统默认显示第 1 页，每页 20 条记录
#### Scenario: 切换页码
- **WHEN** 管理员点击分页器的页码
- **THEN** 系统跳转到对应页面并加载数据
#### Scenario: 调整每页显示数量
- **WHEN** 管理员选择不同的每页显示数量（10/20/50/100）
- **THEN** 系统重新加载数据并按新的数量显示
#### Scenario: 显示总记录数
- **WHEN** 数据加载完成后
- **THEN** 分页器显示总记录数
### Requirement: 国际化支持
系统 SHALL 支持中英文双语界面，所有文案通过国际化文件管理。
#### Scenario: 中文界面显示
- **WHEN** 系统语言设置为中文
- **THEN** 所有界面文案显示为中文
#### Scenario: 英文界面显示
- **WHEN** 系统语言设置为英文
- **THEN** 所有界面文案显示为英文
### Requirement: 访问权限控制
系统 SHALL 限制平台账号管理页面的访问权限，仅超级管理员可访问。
#### Scenario: 超级管理员访问
- **WHEN** 超级管理员访问平台账号管理页面
- **THEN** 系统正常显示平台账号管理界面
#### Scenario: 普通管理员访问
- **WHEN** 普通管理员尝试访问平台账号管理页面
- **THEN** 系统显示"403 无权访问"页面或重定向到首页
### Requirement: 异常处理与用户反馈
系统 SHALL 在操作过程中提供清晰的用户反馈和错误处理。
#### Scenario: 操作成功反馈
- **WHEN** 用户执行新增/编辑/删除/密码修改/角色分配操作成功
- **THEN** 系统显示成功消息提示（如"账号创建成功"）
#### Scenario: API 请求失败处理
- **WHEN** API 请求失败或超时
- **THEN** 系统显示错误消息，并提示用户重试
#### Scenario: 数据加载状态
- **WHEN** 系统正在加载账号数据
- **THEN** 显示加载动画或骨架屏，防止用户误操作
#### Scenario: 空数据提示
- **WHEN** 账号列表为空
- **THEN** 系统显示"暂无账号数据，点击新增按钮创建账号"提示

79
openspec/changes/add-platform-account-management/tasks.md Normal file
View File

@@ -0,0 +1,79 @@
# 实现任务清单
## 1. API 模块实现
- [x] 1.1 补全平台账号 API 接口（已在 `src/api/modules/account.ts` 中完成）
- [x] 平台账号列表查询
- [x] 创建平台账号
- [x] 更新平台账号
- [x] 删除平台账号
- [x] 获取账号详情
- [x] 获取账号角色
- [x] 分配角色
- [x] 移除角色
- [x] 修改密码
- [x] 启用/禁用账号
## 2. 前端页面实现
- [ ] 2.1 创建平台账号管理页面组件 `src/views/system/platform-account/index.vue`
- [ ] 2.1.1 实现账号列表展示（表格）
- [ ] 2.1.2 实现搜索表单（账号名称、用户名、状态）
- [ ] 2.1.3 实现新增账号功能（对话框表单）
- [ ] 2.1.4 实现编辑账号功能
- [ ] 2.1.5 实现删除账号功能（含确认）
- [ ] 2.1.6 实现账号详情查看
- [ ] 2.1.7 实现修改密码功能
- [ ] 2.1.8 实现角色分配功能（对话框+多选）
- [ ] 2.1.9 实现账号状态切换（启用/禁用）
- [ ] 2.1.10 实现分页功能
- [ ] 2.2 添加路由配置
- [ ] 2.2.1 在 `src/router/routes/asyncRoutes.ts` 中添加平台账号管理路由
- [ ] 2.2.2 在 `src/router/routesAlias.ts` 中添加路由别名
- [ ] 2.3 添加国际化支持
- [ ] 2.3.1 在 `src/locales/langs/zh.json` 中添加中文文案
- [ ] 2.3.2 在 `src/locales/langs/en.json` 中添加英文文案
## 3. 角色分配功能
- [ ] 3.1 实现角色选择组件或对话框
- [ ] 3.2 显示账号当前拥有的角色
- [ ] 3.3 支持添加角色（多选）
- [ ] 3.4 支持移除已分配的角色
- [ ] 3.5 实时更新角色列表
## 4. 密码管理功能
- [ ] 4.1 实现修改密码对话框
- [ ] 4.2 密码强度验证（长度、复杂度）
- [ ] 4.3 确认密码校验
- [ ] 4.4 修改成功后提示
## 5. 数据验证与交互优化
- [ ] 5.1 表单字段验证
- [ ] 账号名称必填
- [ ] 用户名必填且唯一
- [ ] 密码强度校验
- [ ] 手机号格式验证
- [ ] 邮箱格式验证
- [ ] 5.2 用户体验优化
- [ ] 加载状态提示
- [ ] 操作成功/失败消息提示
- [ ] 删除前二次确认
- [ ] 空数据提示
## 6. 权限控制
- [ ] 6.1 配置页面访问权限（仅超级管理员可访问）
- [ ] 6.2 添加按钮级权限控制（新增、编辑、删除等）
## 7. 测试与优化
- [ ] 7.1 功能测试（CRUD 操作）
- [ ] 7.2 角色分配功能测试
- [ ] 7.3 密码修改功能测试
- [ ] 7.4 状态切换功能测试
- [ ] 7.5 异常处理测试
## 当前状态
- ✅ 第 1 阶段（API 模块）已完成
- ⏳ 第 2 阶段（前端页面）待实现
- ⏳ 第 3 阶段（角色分配）待实现
- ⏳ 第 4 阶段（密码管理）待实现
- ⏳ 第 5 阶段（验证优化）待实现
- ⏳ 第 6 阶段（权限控制）待实现
- ⏳ 第 7 阶段（测试优化）待实现

182
openspec/project.md Normal file
View File

@@ -0,0 +1,182 @@
# Project Context
## Purpose
物联网管理后台系统 (Internet of Things Admin)，用于运营平台和代理商管理。
主要目标：
- 提供运营人员和代理商的统一管理平台
- 管理物联网卡（号卡）的全生命周期
- 处理代理商体系的分佣和财务管理
- 提供设备和网卡的资产管理能力
- 支持批量操作和数据导入导出
## Tech Stack
- **前端框架**: Vue 3.5+ (Composition API)
- **编程语言**: TypeScript 5.6+
- **构建工具**: Vite 6.1+
- **UI 组件库**: Element Plus 2.8+
- **状态管理**: Pinia 3.0+ (with persistedstate plugin)
- **路由管理**: Vue Router 4.4+
- **HTTP 客户端**: Axios 1.7+
- **图表可视化**: ECharts 5.4+
- **富文本编辑器**: WangEditor 5.1+ / md-editor-v3
- **Excel 处理**: XLSX 0.18+
- **工具库**: VueUse 11.0+, crypto-js, file-saver, qrcode.vue
## Project Conventions
### Code Style
- **代码规范**: ESLint 9.x + Prettier 3.x
- **样式规范**: Stylelint 16.x (SCSS, Vue)
- **提交规范**: Commitizen + cz-git (conventional commits)
- **Git Hooks**: Husky + lint-staged (自动格式化和检查)
- **命名约定**:
- 组件: PascalCase (如 `ArtBarChart.vue`)
- 文件: camelCase 或 kebab-case
- API 文件: 以 `Api` 结尾 (如 `menuApi.ts`, `usersApi.ts`)
### Architecture Patterns
- **组件架构**: 基于 Vue 3 Composition API
- **状态管理**: Pinia stores，支持持久化
- **路由守卫**: 基于角色的权限控制
- **API 模块化**: 按业务模块组织 API (modules 目录)
- **样式方案**: SCSS + CSS Variables (支持主题切换：light/dark/system)
- **布局模式**: 支持多种布局 (vertical/horizontal/mixed/dual_column)
### Testing Strategy
- **单元测试**: Vitest + @vue/test-utils
- 优先测试：工具函数、复杂业务逻辑、状态管理
- 覆盖率目标：核心模块 > 80%
- **E2E 测试**: Playwright (待引入)
- 优先场景：登录流程、关键业务流程（充值、分配等）
- **代码检查**: pre-commit 时自动运行 ESLint 和 Stylelint
- **类型检查**: TypeScript strict mode，构建时进行类型检查
### Git Workflow
- **分支策略**: GitHub Flow (简化版)
- `master`: 主分支，始终保持可部署状态
- `feature/*`: 功能分支，从 master 创建
- `fix/*`: 修复分支，从 master 创建
- `hotfix/*`: 紧急修复，从 master 创建
- **提交规范**: Conventional Commits
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具链更新
- **代码审查**: 建议 PR review 后合并
## Domain Context
### 业务领域
物联网卡管理系统，面向运营人员和代理商。
### 核心概念
- **平台角色**: 区分不同账号职责（运营/管理员等）
- **客户角色**: 决定客户的能力边界
- **代理商体系**: 多级代理商管理，支持分佣
- **企业客户**: 只能登录企业端的客户账号
- **号卡/网卡**: 物联网SIM卡，通过 ICCID 标识
- **套餐**: 流量套餐，可分配给代理商
- **设备**: 与网卡绑定的物联网设备
- **佣金模板**: 预设的分佣规则，方便分配产品时使用
### 主要业务模块
#### 1. 账号管理
- **平台角色**: 用以区分不同账号职责
- **平台账号**: 管理平台/运营账号
- **客户角色**: 决定客户能力边界
- **代理商管理**: 创建代理商及管理特定代理商账号
- **企业客户管理**: 创建企业管理账号（只能登录企业端，依赖客户角色）
- **客户账号管理**: 管理客户（代理商+企业客户）的账号，支持解绑手机等操作
#### 2. 账户管理
- **客户账户**: 查看账号下全部客户账号的佣金情况及提现情况
- **佣金提现**: 管理全部的提现申请
- **佣金提现设置**: 设置提现参数（生效最新一条）
- **我的账户**: 获取当前登录账号的佣金相关数据
#### 3. 我的设置
- **收款商户设置**: 设置支付参数
- **开发能力管理**: 获取开发能力对接参数及管理
- **分佣模板**: 创建及管理分佣模板，方便给代理分配产品时设置分佣规则
#### 4. 商品管理
- **号卡管理**: 新增管理号卡商品，管理基础信息
- **号卡分配**: 为特定代理分配号卡商品，同时设置佣金模式
- **套餐系列管理**: 新增及管理套餐系列
- **套餐管理**: 新增及管理套餐（只能看到自己的/管理员可以看到全部）
- **套餐分配**: 为直级代理分配套餐同时设置佣金模式
#### 5. 资产管理
- **单卡信息**:
- 通过 ICCID 查询单卡相关信息
- 支持操作：套餐充值、停复机、流量详情、更改过期时间、转新卡、停复机记录、往期订单、增减流量、变更钱包余额、充值支付密码、续充、设备操作
- **网卡管理**: 查询网卡信息，提供相关批量操作入口
- **设备管理**: 查看设备信息，提供相关操作入口，查看/修改设备卡信息，设备相关操作
- **资产分配**:
- 为特定代理分配网卡，只支持批量操作
- 批量分配分为两种：设备批量分配、网卡批量分配
- 网卡批量分配时，若网卡有设备信息，会把该卡所属设备及网卡都分配过去
- **换卡申请**: 管理客户提交的换卡申请，处理换卡申请，填充新的 ICCID
#### 6. 批量操作
- **网卡导入**: 批量导入 ICCID，查看导入任务情况
- **设备导入**: 批量导入设备及 ICCID 关系，查看导入任务情况
- **线下批量充值**: 查看批量充值记录，提供批量充值 Excel 导入
- **换卡通知**: 可单独/批量新建换卡通知，查看换卡通知记录
#### 7. 登录模块
- 用以登录平台（根据账号属性做权限控制）
## Important Constraints
### 技术约束
- Node.js 版本要求: >= 20.19.0
- 浏览器兼容性: 现代浏览器（Chrome、Firefox、Safari、Edge）
- 构建输出: ES Module
### 业务约束
- **权限控制**: 严格的基于角色的访问控制 (RBAC)
- **数据隔离**: 代理商只能查看自己及下级的数据
- **佣金计算**: 需要准确的佣金计算和分配逻辑
- **批量操作**: 需要异步任务处理机制，防止超时
- **ICCID 唯一性**: 物联网卡的 ICCID 必须唯一
### 安全约束
- 敏感操作需要二次确认
- 财务相关操作需要审计日志
- 密码需要加密存储和传输
## External Dependencies
### 后端 API
- 主要通过 Axios 与后端 RESTful API 交互
- API 基础路径配置在环境变量中
- API 文档托管在 Apifox (详见 `docs/部分API.md`)
- **API 模块划分**:
- `账号相关`: 账号 CRUD、角色分配
- `权限`: 权限 CRUD、权限树
- `平台账号`: 平台账号管理、密码修改、启用/禁用
- `角色`: 角色 CRUD、权限分配、状态管理
- `认证`: 登录、登出、Token 刷新、用户信息
- **请求/响应约定**:
- 统一使用 RESTful 风格
- 分页列表返回: `ModelXxxPageResult`
- 详情返回: `ModelXxxResponse`
- 创建请求: `ModelCreateXxxRequest`
- 更新请求: `ModelUpdateXxxParams`
### 第三方服务
- **支付服务**: 收款商户设置中配置
- **短信服务**: 用于手机验证码
- **物联网卡供应商 API**: 用于卡片操作（停复机、充值等）
### UI 依赖
- Element Plus Icons
- 自定义图标字体 (iconfont)
- ECharts 图表库