feat(admin-frontend): 补齐用户节点与订单运营工作台
新增用户高级筛选、批量操作与更多行级动作，支持邮件、 CSV、封禁恢复、订单分配、邀请查看、流量记录与重置流量 增强节点管理页的分页、父子筛选、跨页勾选、批量修改与 单节点置顶，并补齐后端批量更新 host、group_ids、rate 修复订单佣金状态误判问题，新增真实佣金筛选与行级确认， 同时优化仪表盘排行悬浮详情展示 补充 admin-frontend 独立 Dockerfile、Caddy 配置与 GHCR 发布工作流，支持通过独立镜像部署管理前端
This commit is contained in:
yinjianm
+11
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"status": "completed",
|
||||
"completed": 5,
|
||||
"failed": 0,
|
||||
"pending": 0,
|
||||
"total": 5,
|
||||
"done": 5,
|
||||
"percent": 100,
|
||||
"current": "用户管理高级筛选与批量操作已完成，等待后续需求",
|
||||
"updated_at": "2026-04-24 22:12:00"
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
{
|
||||
"updatedAt": "2026-04-24T14:00:16.000Z",
|
||||
"version": 1,
|
||||
"source": "manual",
|
||||
"originCommand": "generic-r2",
|
||||
"verifyMode": "test-first",
|
||||
"reviewerFocus": [
|
||||
"高级筛选弹窗是否覆盖用户给出的字段并保持 Apple 化后台视觉节奏",
|
||||
"批量操作的作用范围是否明确且不会误把“筛选结果”降级成仅当前页数据"
|
||||
],
|
||||
"testerFocus": [
|
||||
"用户列表是否能基于高级筛选条件重新请求真实 /user/fetch",
|
||||
"批量发送邮件、导出 CSV、批量封禁与恢复正常是否按 selected/filtered/all 作用域提交正确 payload",
|
||||
"后端 /user/ban 是否兼容 banned=0 并支撑恢复正常"
|
||||
],
|
||||
"ui": {
|
||||
"required": true,
|
||||
"designContract": true,
|
||||
"sourcePriority": [
|
||||
"requirements.md",
|
||||
".helloagents/DESIGN.md",
|
||||
"hello-ui"
|
||||
],
|
||||
"styleAdvisor": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"focus": []
|
||||
},
|
||||
"visualValidation": {
|
||||
"required": true,
|
||||
"reason": "用户管理页本轮新增高级筛选弹窗、批量邮件弹窗与批量操作入口，需要确认筛选结构、作用域提示和工作台节奏与既有 Apple 化后台契约一致。",
|
||||
"screens": [
|
||||
"#/users desktop"
|
||||
],
|
||||
"states": [
|
||||
"用户管理默认加载完成态",
|
||||
"高级筛选弹窗展开态",
|
||||
"批量邮件弹窗展开态",
|
||||
"已勾选用户后的批量操作可用态"
|
||||
]
|
||||
}
|
||||
},
|
||||
"advisor": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"focus": [],
|
||||
"preferredSources": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,63 @@
|
||||
# admin-frontend 用户管理高级筛选与批量操作 — 实施规划
|
||||
|
||||
## 目标与范围
|
||||
- 将现有用户管理页从“基础搜索 + 两个快捷筛选”升级为“基础筛选 + 高级筛选 + 批量操作”的真实运营工作台。
|
||||
- 保持当前 Apple 化后台节奏，不引入厚重的筛选面板或新的视觉体系。
|
||||
|
||||
## 架构与实现策略
|
||||
- 前端拆分为三层：
|
||||
- `UsersView.vue`：只负责页面装配、表格渲染与弹层挂载
|
||||
- `useUsersManagement.ts`：承接用户页状态、筛选、批量操作与列表刷新逻辑
|
||||
- `UserAdvancedFilterDialog.vue` / `UserBatchMailDialog.vue`：分别承接高级筛选与批量邮件输入
|
||||
- 工具层统一收敛到 `src/utils/users.ts`：
|
||||
- 高级筛选字段定义
|
||||
- 字段 → 后端过滤条件映射
|
||||
- 流量/时间/状态等值转换
|
||||
- 已生效筛选摘要生成
|
||||
- API 层补齐用户批量操作封装：
|
||||
- `exportUsersCsv`
|
||||
- `sendUsersMail`
|
||||
- `batchUpdateUserBan`
|
||||
- 后端最小改动放在 `App\Http\Controllers\V2\Admin\UserController::ban`：
|
||||
- 现有 `/user/ban` 默认仍保持“批量封禁”
|
||||
- 新增兼容 `banned=0|1`，以支持“批量恢复正常”
|
||||
|
||||
## 完成定义
|
||||
- 用户页工具条新增“高级筛选”入口，并可查看已生效筛选摘要。
|
||||
- 高级筛选至少支持以下字段：
|
||||
- 邮箱 / 用户 ID / 订阅 / 流量 / 已用流量 / 在线设备 / 到期时间 / UUID / Token / 账号状态 / 备注
|
||||
- 用户表格支持勾选用户，并能从批量操作菜单触发“发送邮件 / 导出 CSV / 批量封禁 / 恢复正常”。
|
||||
- 未勾选用户时，批量操作自动作用于当前筛选结果；无筛选条件时明确提示会作用于全部用户。
|
||||
- 后端 `user/ban` 支持 `banned=0`，前端“恢复正常”可真实落库。
|
||||
|
||||
## 文件结构
|
||||
- `.helloagents/plans/202604242200_admin-frontend-user-advanced-filter-batch-ops/*`
|
||||
- `admin-frontend/src/api/admin.ts`
|
||||
- `admin-frontend/src/types/api.d.ts`
|
||||
- `admin-frontend/src/utils/users.ts`
|
||||
- `admin-frontend/src/views/users/UsersView.vue`
|
||||
- `admin-frontend/src/views/users/UsersView.scss`
|
||||
- `admin-frontend/src/views/users/useUsersManagement.ts`
|
||||
- `admin-frontend/src/views/users/UserAdvancedFilterDialog.vue`
|
||||
- `admin-frontend/src/views/users/UserBatchMailDialog.vue`
|
||||
- `app/Http/Controllers/V2/Admin/UserController.php`
|
||||
|
||||
## UI / 设计约束
|
||||
- 首屏继续保持黑底标题区，不额外加营销式视觉层。
|
||||
- 高级筛选弹窗采用白色内容面、清晰的条件分组和轻量边框，靠结构区分复杂度，而不是靠重阴影或渐变。
|
||||
- 批量操作入口采用克制型下拉菜单，贴近用户截图中的纯文本操作列表。
|
||||
- 已生效筛选摘要使用轻量胶囊标签呈现，帮助用户快速理解当前列表上下文。
|
||||
|
||||
## 风险与验证
|
||||
- 风险 1：高级筛选字段多、值类型混合，若直接散落在视图中容易出现映射漂移，因此统一收口到 `src/utils/users.ts`。
|
||||
- 风险 2：批量操作的“作用范围”容易误伤全部用户，因此前端必须在执行前展示目标范围。
|
||||
- 风险 3：批量恢复正常依赖后端接口补齐 `banned=0` 语义，若不改后端只能伪实现，因此必须做最小后端兼容。
|
||||
- 验证方式：
|
||||
- `npm run build`
|
||||
- 代码级视觉自检：高级筛选弹窗、批量邮件弹窗、用户列表批量操作入口
|
||||
- 批量恢复正常逻辑代码自检：前后端 payload 一致
|
||||
|
||||
## 决策记录
|
||||
- [2026-04-24] 高级筛选采用独立弹窗而不是在工具条横向堆叠字段，以匹配用户截图并控制后台密度。
|
||||
- [2026-04-24] 批量操作默认优先使用“已勾选用户 > 当前筛选结果 > 全部用户”的三段式作用域规则。
|
||||
- [2026-04-24] 批量恢复正常沿用 `/user/ban` 现有路由，通过 `banned=0|1` 扩展语义，避免新开重复接口。
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
# admin-frontend 用户管理高级筛选与批量操作 — 需求
|
||||
|
||||
确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
|
||||
|
||||
## 核心目标
|
||||
- 在 `admin-frontend` 的用户管理页补齐“高级筛选”能力，支持按照多个条件组合筛选用户。
|
||||
- 高级筛选字段需覆盖用户提供截图中的核心字段：邮箱、用户 ID、订阅、流量、已用流量、在线设备、到期时间、UUID、Token、账号状态、备注。
|
||||
- 在用户管理页接入“对筛选结果执行批量操作”的工作流，至少支持：
|
||||
- 发送邮件
|
||||
- 导出 CSV
|
||||
- 批量封禁
|
||||
- 批量恢复正常（用户本轮确认追加）
|
||||
|
||||
## 功能边界
|
||||
- 必须保留现有用户管理基础能力：搜索、快捷状态筛选、订阅筛选、创建用户、行级编辑/复制/重置密钥/封禁/删除。
|
||||
- 必须新增“高级筛选”弹窗或等价工作流，允许添加多条筛选条件，并将筛选结果回流到用户列表。
|
||||
- 批量操作应明确作用范围：
|
||||
- 若已勾选用户，则作用于已勾选用户
|
||||
- 若未勾选但存在筛选条件，则作用于当前筛选结果
|
||||
- 若既未勾选也无筛选条件，则作用于全部用户，并给出明确确认
|
||||
- 批量邮件需提供主题与正文输入界面，不接受无内容直接发送。
|
||||
- 批量恢复正常必须真实生效，不接受只在前端伪装状态。
|
||||
|
||||
## 非目标
|
||||
- 本轮不重做用户编辑抽屉结构。
|
||||
- 本轮不重构用户管理后端查询架构，只在现有接口能力基础上做最小必要扩展。
|
||||
- 本轮不新增复杂图表或统计卡片。
|
||||
|
||||
## 技术约束
|
||||
- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`，目录限定在 `admin-frontend/` 与最小必要的 Laravel 管理端控制器。
|
||||
- 用户列表真相源为 `App\Http\Controllers\V2\Admin\UserController`。
|
||||
- 前端用户接口继续走：
|
||||
- `GET /user/fetch`
|
||||
- `POST /user/update`
|
||||
- `POST /user/resetSecret`
|
||||
- `POST /user/destroy`
|
||||
- `POST /user/dumpCSV`
|
||||
- `POST /user/sendMail`
|
||||
- `POST /user/ban`
|
||||
- 视觉需遵循 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md`：黑色首屏 + 白色工作台 + 蓝色单一强调，不引入另一套后台皮肤。
|
||||
|
||||
## 质量要求
|
||||
- 高级筛选需贴近截图中的“条件卡片 + 字段选择 + 多条件叠加”体验，而不是只追加一排新的下拉框。
|
||||
- 批量操作入口需清晰可发现，但不压过主列表的日常使用节奏。
|
||||
- 用户页至少补齐“高级筛选已生效”的可见反馈，避免用户不知道当前列表为何被过滤。
|
||||
- 最终至少完成一次 `admin-frontend` 构建验证，并留下视觉验收与交付证据。
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
# admin-frontend 用户管理高级筛选与批量操作 — 任务分解
|
||||
|
||||
## 任务列表
|
||||
- [x] 任务1：补齐本轮方案与合同产物（涉及文件：`.helloagents/plans/202604242200_admin-frontend-user-advanced-filter-batch-ops/*`；完成标准：存在需求、方案、任务、合同与状态文件；验证方式：文件检查）
|
||||
- [x] 任务2：扩展用户筛选工具层与批量操作 API（涉及文件：`admin-frontend/src/utils/users.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/api/admin.ts`；完成标准：前端可构造高级筛选与批量操作 payload；验证方式：`npm run build`）
|
||||
- [x] 任务3：重构用户管理页并新增高级筛选 / 批量邮件组件（涉及文件：`admin-frontend/src/views/users/*`；完成标准：用户页支持高级筛选、勾选、多种批量操作；验证方式：`npm run build`）
|
||||
- [x] 任务4：补齐批量恢复正常后端兼容（涉及文件：`app/Http/Controllers/V2/Admin/UserController.php`；完成标准：`/user/ban` 支持 `banned=0|1`；验证方式：代码检查 + `npm run build` 间接通过）
|
||||
- [x] 任务5：完成验证与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/context.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`、`.helloagents/sessions/master/default/STATE.md`；完成标准：构建通过、知识库更新、证据落盘；验证方式：命令输出 + 证据文件）
|
||||
|
||||
## 进度
|
||||
- [x] 已确认本轮除截图中的三项批量操作外，再额外补“批量恢复正常”。
|
||||
- [x] 已完成高级筛选弹窗、批量操作菜单、批量邮件弹窗与前后端批量恢复链路。
|
||||
- [x] 已完成 `npm run build` 构建验证，待输出最终交付摘要。
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"status": "completed",
|
||||
"completed": 4,
|
||||
"failed": 0,
|
||||
"pending": 0,
|
||||
"total": 4,
|
||||
"done": 4,
|
||||
"percent": 100,
|
||||
"current": "用户更多操作复刻已完成，等待后续需求",
|
||||
"updated_at": "2026-04-24 22:45:00"
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
{
|
||||
"updatedAt": "2026-04-24T14:36:00.000Z",
|
||||
"version": 1,
|
||||
"source": "manual",
|
||||
"originCommand": "generic-r2",
|
||||
"verifyMode": "test-first",
|
||||
"reviewerFocus": [
|
||||
"用户更多操作菜单是否按截图顺序与交互意图完成复刻",
|
||||
"跨页筛选联动是否对用户可见且能明确清除"
|
||||
],
|
||||
"testerFocus": [
|
||||
"分配订单是否可直接预填邮箱打开抽屉",
|
||||
"TA的订单是否跳转订单页并按 user_id 生效",
|
||||
"TA的邀请是否形成可用的用户结果视图",
|
||||
"TA的流量记录与重置流量是否都走真实链路"
|
||||
],
|
||||
"ui": {
|
||||
"required": true,
|
||||
"designContract": true,
|
||||
"sourcePriority": [
|
||||
"requirements.md",
|
||||
".helloagents/DESIGN.md",
|
||||
"hello-ui"
|
||||
],
|
||||
"styleAdvisor": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"focus": []
|
||||
},
|
||||
"visualValidation": {
|
||||
"required": true,
|
||||
"reason": "本轮要补齐用户更多操作菜单与多个复用弹层/跳转联动，需要确认用户页菜单密度、订单页筛选提示和弹窗挂载都符合既有后台设计契约。",
|
||||
"screens": [
|
||||
"#/users desktop",
|
||||
"#/subscriptions/orders desktop"
|
||||
],
|
||||
"states": [
|
||||
"用户更多操作菜单展开态",
|
||||
"用户页分配订单抽屉展开态",
|
||||
"用户页流量记录弹窗展开态",
|
||||
"订单页按指定用户过滤态"
|
||||
]
|
||||
}
|
||||
},
|
||||
"advisor": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"focus": [],
|
||||
"preferredSources": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
# admin-frontend 用户管理更多操作复刻 — 实施规划
|
||||
|
||||
## 目标与范围
|
||||
- 把用户管理行级“更多操作”从当前的基础维护菜单升级为更完整的运营工作台菜单。
|
||||
- 以“复用现有抽屉 / 弹窗 / 页面”为主，不重复造轮子。
|
||||
|
||||
## 架构与实现策略
|
||||
- 用户页继续以 `UsersView.vue + useUsersManagement.ts` 为主入口。
|
||||
- 新增 `useUserScopedActions.ts` 负责：
|
||||
- 用户页作用域跳转
|
||||
- 订单分配抽屉预填
|
||||
- 流量记录弹窗状态
|
||||
- 邀请结果视图的路由筛选
|
||||
- 用户流量重置调用
|
||||
- 复用组件策略：
|
||||
- `OrderAssignDrawer.vue`：支持预填邮箱
|
||||
- `TrafficLogDialog.vue`：直接挂到用户页
|
||||
- `OrdersView.vue`：读取路由 query 并自动追加用户过滤
|
||||
- 后端优先复用现有 `traffic-reset/reset-user`，避免再开新接口。
|
||||
|
||||
## 完成定义
|
||||
- 用户页“更多操作”菜单补齐目标操作项，并按截图相近顺序展示。
|
||||
- `分配订单` 可直接打开抽屉，邮箱已回填。
|
||||
- `TA的订单` 可跳转到 `#/subscriptions/orders`，并自动按 `user_id` 过滤。
|
||||
- `TA的邀请` 可在用户页自动切换到“当前用户邀请结果”视图，并允许一键清除。
|
||||
- `TA的流量记录` 可打开流量日志弹窗。
|
||||
- `重置流量` 可调用真实后端接口并在成功后刷新用户列表。
|
||||
|
||||
## 风险与验证
|
||||
- 风险 1：用户页与订单页的跨页筛选若无可见提示，容易造成理解偏差，因此需要补齐筛选提示与清除入口。
|
||||
- 风险 2：用户更多操作继续堆进 `useUsersManagement.ts` 容易过大，因此拆分 `useUserScopedActions.ts`。
|
||||
- 风险 3：重置流量若重新发明接口会增加回归面，因此优先复用 `traffic-reset/reset-user`。
|
||||
- 验证方式：
|
||||
- `npm run build`
|
||||
- 代码自检：用户菜单完整性、订单页 query 过滤、流量重置调用链、邀请筛选可清除
|
||||
|
||||
## 决策记录
|
||||
- [2026-04-24] `分配订单` 直接复用现有订单分配抽屉，并通过 prop 预填用户邮箱。
|
||||
- [2026-04-24] `TA的订单` 采用跳页 + 自动过滤，而不是在用户页内塞第二套订单列表。
|
||||
- [2026-04-24] `TA的邀请` 在当前用户页复用筛选结果视图，不额外新建邀请独立页面。
|
||||
@@ -0,0 +1,41 @@
|
||||
# admin-frontend 用户管理更多操作复刻 — 需求
|
||||
|
||||
确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
|
||||
|
||||
## 核心目标
|
||||
- 在 `admin-frontend` 的用户管理“更多操作”菜单中，继续复刻旧后台的用户级操作项。
|
||||
- 本轮目标菜单项包括：
|
||||
- 编辑
|
||||
- 分配订单
|
||||
- 复制订阅 URL
|
||||
- 重置 UUID 及订阅 URL
|
||||
- TA 的订单
|
||||
- TA 的邀请
|
||||
- TA 的流量记录
|
||||
- 重置流量
|
||||
- 删除
|
||||
|
||||
## 功能边界
|
||||
- `分配订单` 必须直接在用户页打开可用的订单分配抽屉，并预填当前用户邮箱。
|
||||
- `TA的订单` 必须跳转到订单管理页，并自动按当前用户过滤订单。
|
||||
- `TA的邀请` 必须进入“邀请了哪些用户”的结果视图，不接受只弹提示。
|
||||
- `TA的流量记录` 必须直接打开现有流量记录弹窗。
|
||||
- `重置流量` 必须调用真实后端链路，不接受只在前端重置显示值。
|
||||
- 保留本轮上一阶段已交付的高级筛选与批量操作能力，不得回退。
|
||||
|
||||
## 非目标
|
||||
- 本轮不重做用户管理整体布局。
|
||||
- 本轮不新增完整“邀请管理”独立页面，只需要让“TA的邀请”形成可用结果视图。
|
||||
- 本轮不重构订单管理与流量日志页面主体结构，只做最小必要联动。
|
||||
|
||||
## 技术约束
|
||||
- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
|
||||
- 前端改动集中在 `admin-frontend/src/views/users/*`、必要的订单页联动与 API 封装。
|
||||
- 流量重置优先复用现有后端 `traffic-reset/reset-user` 能力，不重复发明新接口。
|
||||
- 视觉继续遵循 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md`。
|
||||
|
||||
## 质量要求
|
||||
- “更多操作”菜单的文案顺序与操作节奏尽量贴近用户截图。
|
||||
- 用户点击某项操作后，必须形成明确结果：打开抽屉 / 打开弹窗 / 跳转并带筛选 / 成功提示。
|
||||
- 订单页与用户页的联动筛选必须可见、可清除，不能让用户陷入“看不出为什么被过滤”的状态。
|
||||
- 最终至少完成一次 `admin-frontend` 构建验证，并同步知识库与验收证据。
|
||||
@@ -0,0 +1,12 @@
|
||||
# admin-frontend 用户管理更多操作复刻 — 任务分解
|
||||
|
||||
## 任务列表
|
||||
- [x] 任务1：补齐本轮方案与合同产物（涉及文件：`.helloagents/plans/202604242236_admin-frontend-user-more-actions/*`；完成标准：存在需求、方案、任务、合同与状态文件；验证方式：文件检查）
|
||||
- [x] 任务2：扩展用户页更多操作状态与复用链路（涉及文件：`admin-frontend/src/views/users/*`；完成标准：菜单补齐并接通订单/邀请/流量/重置流量动作；验证方式：`npm run build`）
|
||||
- [x] 任务3：补齐订单页路由筛选联动与预填订单分配抽屉（涉及文件：`admin-frontend/src/views/subscriptions/OrdersView.vue`、`admin-frontend/src/views/subscriptions/OrderAssignDrawer.vue`；完成标准：用户订单跳转可见且可清除；验证方式：`npm run build`）
|
||||
- [x] 任务4：完成验证与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/context.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`、`.helloagents/sessions/master/default/STATE.md`；完成标准：构建通过、知识库更新、证据落盘；验证方式：命令输出 + 证据文件）
|
||||
|
||||
## 进度
|
||||
- [x] 已确认按完整复刻方案推进更多操作。
|
||||
- [x] 已完成用户页菜单、跳页筛选联动与真实流量重置。
|
||||
- [x] 已完成 `npm run build` 构建验证，待输出最终交付摘要。
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"status": "completed",
|
||||
"completed": 4,
|
||||
"failed": 0,
|
||||
"pending": 0,
|
||||
"total": 4,
|
||||
"done": 4,
|
||||
"percent": 100,
|
||||
"current": "admin-frontend GHCR 发布与 compose 接入已完成，等待用户后续动作",
|
||||
"updated_at": "2026-04-24 23:05:00"
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
{
|
||||
"updatedAt": "2026-04-24T14:50:00.000Z",
|
||||
"version": 1,
|
||||
"source": "manual",
|
||||
"originCommand": "generic-r2",
|
||||
"verifyMode": "test-first",
|
||||
"reviewerFocus": [
|
||||
"admin-frontend 镜像链路是否与主应用镜像链路解耦且不互相污染",
|
||||
"compose 分支新增 admin 服务后镜像名、端口和访问路径是否一致"
|
||||
],
|
||||
"testerFocus": [
|
||||
"vite 输出目录是否可在容器构建时切换到 dist",
|
||||
"admin-frontend Dockerfile 是否能独立构建静态镜像",
|
||||
"GitHub Actions workflow 与 compose.yaml 是否都能通过 YAML 解析"
|
||||
],
|
||||
"ui": {
|
||||
"required": false,
|
||||
"designContract": false,
|
||||
"sourcePriority": [
|
||||
"requirements.md"
|
||||
],
|
||||
"styleAdvisor": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"focus": []
|
||||
},
|
||||
"visualValidation": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"screens": [],
|
||||
"states": []
|
||||
}
|
||||
},
|
||||
"advisor": {
|
||||
"required": false,
|
||||
"reason": "",
|
||||
"focus": [],
|
||||
"preferredSources": []
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
# admin-frontend GHCR 自动构建与 compose 接入 — 实施规划
|
||||
|
||||
## 目标与范围
|
||||
- 让 `admin-frontend` 从“仓内前端目录”升级为“可独立构建、可独立分发、可独立部署”的静态前端镜像。
|
||||
- 保持当前主应用镜像发布链路不变，同时补一条面向前端的独立 GHCR 发布通道。
|
||||
- 让 `compose` 分支可直接拉起独立 `admin` 服务，对外暴露单独端口。
|
||||
|
||||
## 架构与实现策略
|
||||
- 构建链路：
|
||||
- 在 `admin-frontend/` 下新增独立 Dockerfile，采用 `Node -> Caddy` 多阶段构建。
|
||||
- 通过环境变量把容器构建输出切到 `dist`，避免影响当前仓内 `public/assets/admin` 输出。
|
||||
- 发布链路：
|
||||
- 新增单独的 GitHub Actions workflow，仅在 `admin-frontend/**` 或 workflow 自身变更时触发。
|
||||
- 镜像发布到 `ghcr.io/<owner>/xboard-admin-frontend`，标签策略与主应用保持一致：分支、sha、`new`、`latest`。
|
||||
- 运行链路：
|
||||
- 通过 Caddy 在容器内提供静态资源，根路径自动重定向到 `/assets/admin/`。
|
||||
- `compose` 分支新增 `admin` 服务，直接拉取 GHCR 镜像并暴露 `7002:80`。
|
||||
|
||||
## 完成定义
|
||||
- `admin-frontend` 本地可通过 Dockerfile 正常构建镜像。
|
||||
- GitHub Actions 可在 push 后自动构建并推送 `admin-frontend` 镜像到 GHCR。
|
||||
- `compose` 分支的 `compose.yaml` 已包含独立 `admin` 服务，且镜像名与端口配置正确。
|
||||
- `npm run build` 与 workflow/compose 语法检查通过。
|
||||
|
||||
## 风险与验证
|
||||
- 风险 1：`vite.config.ts` 目前默认输出到仓根 `public/assets/admin`，容器构建若不切换输出目录会污染镜像构建路径，因此必须引入可覆写输出目录。
|
||||
- 风险 2：若前端服务直接暴露 `/` 而未处理 `/assets/admin/`，现有资源前缀会失配，因此需要容器内重定向和静态路径兜底。
|
||||
- 风险 3：当前仓库已有大量未提交业务改动，不能直接切换分支修改 `compose.yaml`，需在独立 worktree 中处理 `compose` 分支文件。
|
||||
- 验证方式：
|
||||
- `npm run build`
|
||||
- `docker build -f admin-frontend/Dockerfile admin-frontend`
|
||||
- `python -c "import yaml; ..."` 检查 workflow 与 compose YAML
|
||||
|
||||
## 决策记录
|
||||
- [2026-04-24] 采用独立 `admin` 服务，并按用户确认暴露单独端口，不内嵌回 Laravel 主服务容器。
|
||||
- [2026-04-24] 采用独立 workflow，而不是把前端镜像构建塞进现有后端 `docker-publish.yml`，以降低耦合和回归面。
|
||||
- [2026-04-24] 前端运行时采用 Caddy 提供静态资源并做 `/ -> /assets/admin/` 重定向，兼容当前 `base: '/assets/admin/'`。
|
||||
@@ -0,0 +1,31 @@
|
||||
# admin-frontend GHCR 自动构建与 compose 接入 — 需求
|
||||
|
||||
确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
|
||||
|
||||
## 核心目标
|
||||
- 为 `admin-frontend` 增加独立的 Docker 构建与 GitHub Actions 发布链路。
|
||||
- 在代码提交后，自动构建 `admin-frontend` 镜像并推送到 GHCR。
|
||||
- 按用户已确认的方案，把 `compose` 分支的 `compose.yaml` 增加独立 `admin` 服务，并暴露独立访问端口。
|
||||
|
||||
## 功能边界
|
||||
- 镜像必须只面向 `admin-frontend/` 构建，不混入 Laravel 主应用镜像逻辑。
|
||||
- GHCR 发布链路需支持与主仓当前镜像发布策略并存，不能破坏现有后端 `docker-publish.yml`。
|
||||
- 新增的 `admin` 服务需直接引用 GHCR 镜像，不走本地 `build:`。
|
||||
- `admin` 服务需可独立访问，并保留把 `/assets/admin/` 继续挂到反向代理的能力。
|
||||
|
||||
## 非目标
|
||||
- 本轮不改造 Laravel 主应用 Dockerfile。
|
||||
- 本轮不重做 `admin-frontend` 的业务代码与视觉界面。
|
||||
- 本轮不处理 GitHub Secrets 之外的外部部署脚本。
|
||||
|
||||
## 技术约束
|
||||
- `admin-frontend` 仍使用 `Vue 3 + TypeScript + Vite`。
|
||||
- 本地现有构建输出 `../public/assets/admin` 不能被破坏；容器构建需使用独立输出目录。
|
||||
- 发布目标为 GHCR，多架构与登录方式尽量沿用现有主仓工作流模式。
|
||||
- 视觉与前端基线继续遵循 `apple/DESIGN.md`，但本轮主要产出为工程/部署配置。
|
||||
|
||||
## 质量要求
|
||||
- `admin-frontend` 镜像需可直接运行并稳定提供静态资源。
|
||||
- 工作流命名、镜像命名与标签策略需清晰，不和主应用镜像冲突。
|
||||
- `compose.yaml` 中新增服务后，配置语义应一眼可读，端口、镜像名和用途明确。
|
||||
- 最终至少完成一次 `admin-frontend` 构建验证与工作流 YAML 语法级自检。
|
||||
@@ -0,0 +1,13 @@
|
||||
# admin-frontend GHCR 自动构建与 compose 接入 — 任务分解
|
||||
|
||||
## 任务列表
|
||||
- [x] 任务1：补齐本轮方案与合同产物（涉及文件：`.helloagents/plans/202604242250_admin-frontend-ghcr-compose/*`；完成标准：存在需求、方案、任务、合同与状态文件；验证方式：文件检查）
|
||||
- [x] 任务2：实现 `admin-frontend` 独立 Docker 构建链路（涉及文件：`admin-frontend/Dockerfile`、`admin-frontend/Caddyfile`、`admin-frontend/.dockerignore`、`admin-frontend/vite.config.ts`；完成标准：可输出独立静态镜像；验证方式：`npm run build` + `ADMIN_BUILD_OUT_DIR=dist npm run build`，本地 `docker build` 因环境缺少 docker CLI 未执行）
|
||||
- [x] 任务3：新增前端 GHCR 发布 workflow（涉及文件：`.github/workflows/admin-frontend-docker-publish.yml`；完成标准：push 后可自动构建并推送前端镜像；验证方式：YAML 解析 + 工作流自检）
|
||||
- [x] 任务4：在 compose 分支接入独立 `admin` 服务并完成知识库同步（涉及文件：`compose.yaml`（compose 分支 worktree）、`.helloagents/CHANGELOG.md`、`.helloagents/context.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/sessions/master/default/STATE.md`；完成标准：`compose` 分支文件完成接入且知识库已更新；验证方式：YAML 解析 + 文件检查）
|
||||
|
||||
## 进度
|
||||
- [x] 已确认采用独立 `admin` 服务，并在 compose 分支暴露单独端口。
|
||||
- [x] 已完成方案包、前端镜像构建链路与 GHCR workflow 编排。
|
||||
- [x] 已完成 compose 分支 `compose.yaml` 接入与 YAML 语法校验。
|
||||
- [x] 已完成 `npm run build` 与 `ADMIN_BUILD_OUT_DIR=dist npm run build` 验证；本地 `docker build` 因环境缺少 `docker` 命令未执行。
|
||||
Reference in New Issue
Block a user