chg_0007: lite_demo_restore 提案 — 补回 lite-react book/shop demo 模块(TypeORM-free)
Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
1 parent
5c27b0fd39
commit
1c2f3ba234
5 files changed
+371
No files matched your search
@@ -0,0 +1,66 @@
|
||||
---
|
||||
change_id: chg_0007
|
||||
status: proposed
|
||||
owner: pm@team
|
||||
stakeholders: [pd, tm, qa, dev]
|
||||
priority: P2
|
||||
target_release: v0.3
|
||||
created: 2026-09-28
|
||||
skip_coverage: false
|
||||
---
|
||||
|
||||
# chg_0007 lite-react demo restoration
|
||||
|
||||
## Why
|
||||
|
||||
chg_0001 起骨架时,sandbox agent 没找到 `ssw-jnpf-lite-react` skill(容器内
|
||||
`~/.claude/skills/` 软链断裂,见 learnings §A-1),改为手写最小 NestJS 骨架,
|
||||
**丢了 skill 自带的 book/shop/dashboard demo 模块**。chg_0003 起 G-1 cache、
|
||||
G-2 一键派单、A-2 prep 脚本把这条断链补上;但**工作区里 book/shop 这两个
|
||||
MVP 演示模块至今未补**——
|
||||
|
||||
- 新人按 `git clone` 跟到本仓库,看不到一个完整的"实体 CRUD + 鉴权 + 软删"
|
||||
参考实现,只能看 LMS(chg_0006)/ experiment(chg_0005),两者都是 DTH
|
||||
业务特定形态,与通用 lite-react 模板不完全一致。
|
||||
- `HOWTO_MODULE.md` 引用的 demo 用例是 `book` + `shop`,缺失这两个文件让
|
||||
HOWTO 描述与实际工作区对不上。
|
||||
- 后续 chg(如 SP-3 课程内容 SP-4 LMS 高级特性)很可能需要"通用业务模块"
|
||||
形态作为参照。
|
||||
|
||||
## Scope
|
||||
|
||||
**做**:
|
||||
1. 把 `~/.claude/skills/ssw-jnpf-lite-react/src/backend/src/books/` 4 文件
|
||||
(book.entity.ts / book.service.ts / book.controller.ts / books.module.ts)
|
||||
**改写为 TypeORM-free 形态**(按 LMS 的 `getDb()` + pglite 直查模式),落到
|
||||
`src/backend/src/books/`。
|
||||
2. 同上处理 `shop/` 模块 → `src/backend/src/shop/`(product.entity/service/controller + shop.module.ts)。
|
||||
3. 前端 `src/frontend/src/views/{Book,Product}.tsx` 复制 skill 模板(已用 React + axios,
|
||||
与本仓库前端栈一致),并加 `src/frontend/src/api/{book,product}.ts`。
|
||||
4. `src/backend/src/app.module.ts` 注册 BooksModule + ShopModule;
|
||||
`src/frontend/src/App.tsx` 加 2 条 Route;`seed.service.ts` 加 2 条菜单。
|
||||
5. `src/backend/src/common/pglite/init.ts` 加 `book_shop_book` + `book_shop_product` 两张表 + 种子(每表 3 行)。
|
||||
6. 写 `tests/e2e/dth_lite_demo.test.sh`(≥ 6 case,覆盖 list/create/update/delete + 软删 + 鉴权重定向)。
|
||||
|
||||
**不做**:
|
||||
- 不复制 skill 的 sys/UserManage/RoleManage/MenuManage(dth 已有简化 auth,不引入 RBAC 套件)
|
||||
- 不复制 skill 的 typeorm 依赖(dth 后端只用 pglite,遵循 chg_0006 LMS 模式)
|
||||
- 不动 experiment / LMS / auth(契约红线)
|
||||
- 不做前端 Dashboard 实时数据(保留 skill 静态 Dashboard.tsx,不引入图表库)
|
||||
|
||||
## Impact
|
||||
|
||||
影响 capability:`lite_demo`(**新建** capability,openspec/specs/lite_demo/spec.md 后续从 chg 归档合并)。
|
||||
|
||||
## Acceptance
|
||||
|
||||
- `bash openspec/scripts/check_spec_coverage.sh` gap=0
|
||||
- `tests/e2e/dth_lite_demo.test.sh` 全部 PASS(≥ 6 case / ≥ 12 断言)
|
||||
- `tsc --noEmit` 0 错误(dth 后端范围内)
|
||||
- 后端启动后 `curl /books/Book` 与 `curl /books/Product` 返回 200 + JSON 数组
|
||||
|
||||
## Related
|
||||
|
||||
- `docs/superpowers/learnings/2026-09-28-dispatch-session.md` §A-1(skill 软链断裂)
|
||||
- `~/.claude/skills/ssw-jnpf-lite-react/HOWTO_MODULE.md`(demo 用例的源)
|
||||
- `openspec/changes/chg_0006_lms_bootstrap/`(TypeORM-free 参考实现)
|
||||
@@ -0,0 +1,112 @@
|
||||
# Spec: lite_demo
|
||||
|
||||
## Requirement
|
||||
|
||||
THE SYSTEM SHALL expose two generic CRUD modules(`books` + `shop`)with typeORM-free persistence
|
||||
(pglite 直接查询),aREST interface shaped after JNPF(`/api/.../List` / `getInfo` / `Create` /
|
||||
`Update` / `Remove`),with a flexible column schema(`f_*` 前缀 + `f_id` varchar(50) + `f_delete_mark` 软删)
|
||||
so that 新人 / demo 走查 即可得到"业务模块从零到跑通"的全套参考实现。
|
||||
|
||||
## ADDED Scenarios
|
||||
|
||||
### S1 books module book CRUD list
|
||||
|
||||
- **WHEN** client `GET /books/Book/List` with admin token
|
||||
- **THEN** response is 200 + JSON array, each row includes `f_id` / `f_title` / `f_author` / `f_isbn` / `f_price` / `f_stock` / `f_creator_user_id`
|
||||
- **AND** rows with `f_delete_mark=1` are excluded
|
||||
- **AND** non-admin token returns 600 (not 200)
|
||||
|
||||
### S2 books module book create
|
||||
|
||||
- **WHEN** client `POST /books/Book/Create` with admin token + body `{f_title,f_f_category?}`
|
||||
- **THEN** response is 200 + JSON `{code:200,msg:...,data:{id}}`
|
||||
- **AND** a new row exists in `book_shop_book` with `f_delete_mark=0`
|
||||
- **AND** non-admin token returns 600
|
||||
|
||||
### S3 shop module product CRUD list
|
||||
|
||||
- **WHEN** client `GET /books/Product/List` with admin token
|
||||
- **THEN** response is 200 + JSON array, each row includes `f_id` / `f_name` / `f_sku` / `f_category` / `f_price` / `f_stock`
|
||||
- **AND** rows with `f_delete_mark=1` are excluded
|
||||
- **AND** non-admin token returns 600
|
||||
|
||||
### S4 shop module product update + soft delete
|
||||
|
||||
- **WHEN** client `POST /books/Product/Update {id, f_price:99.99}` then `POST /books/Product/Remove {id}`
|
||||
- **THEN** update response is 200 + JSON `{code:200,msg:...,data:{}}`
|
||||
- **AND** remove response is 200 + JSON `{code:200,msg:...,data:{}}`
|
||||
- **AND** subsequent `GET /books/Product/List` no longer includes the row
|
||||
|
||||
### S5 menu + route wiring
|
||||
|
||||
- **WHEN** client opens `/books/Book` after admin login
|
||||
- **THEN** the menu `/books/Book` is visible (from `seed.service.ts menus[]`)
|
||||
- **AND** the frontend route `<Route path="/books/Book">` exists in `App.tsx`
|
||||
- **AND** `Book.tsx` renders without 404
|
||||
|
||||
### S6 init schema + seed
|
||||
|
||||
- **WHEN** backend first starts (PGlite init runs)
|
||||
- **THEN** `book_shop_book` table has columns matching `book.entity.ts` (id/title/author/isbn/category/price/stock/creator_user_id/creator_time/delete_mark)
|
||||
- **AND** `book_shop_product` table has columns matching `product.entity.ts`
|
||||
- **AND** `book_shop_book` has 3 seed rows, `book_shop_product` has 3 seed rows
|
||||
|
||||
## UX / Interaction
|
||||
|
||||
- 后端无 UI 变化
|
||||
- 前端 `Book.tsx` / `Product.tsx`:列表页 + 新建/编辑表单对话框(弹窗)
|
||||
- 风格对齐现有 `Dotheme.tsx`,不引入新 UI 库
|
||||
|
||||
## 实施细节(写死给沙盒)
|
||||
|
||||
### 模块命名(与 HOWTO_MODULE.md §零 一字不差)
|
||||
|
||||
```
|
||||
业务名:图书超市
|
||||
→ appCode = books
|
||||
→ 文件夹 = src/backend/src/books/
|
||||
→ 表名 = book_shop_book # JNPF 表名规则 {appCode}_{Entity_lower}
|
||||
→ 端点 Entity = Book
|
||||
→ urlAddress = books/Book
|
||||
→ 守卫 MODKEY = 'books/Book'
|
||||
→ 前端 Route = /books/Book
|
||||
→ 前端视图文件 = Book.tsx
|
||||
→ 前端 api 文件 = api/book.ts
|
||||
|
||||
业务名:超市
|
||||
→ appCode = books (复用 books appCode,表名前缀仍为 book_shop_)
|
||||
→ Entity = Product
|
||||
→ urlAddress = books/Product
|
||||
→ 前端视图文件 = Product.tsx
|
||||
→ 前端 api 文件 = api/product.ts
|
||||
```
|
||||
|
||||
**注**:本仓库后端鉴权简化(仅 admin/non-admin 二值,无 RBAC),所有 CRUD 用 admin token 调通即可;
|
||||
前端菜单按 urlAddress 注册。
|
||||
|
||||
### TypeORM-free 模板(参照 chg_0006 LMS 的 students.service.ts)
|
||||
|
||||
```typescript
|
||||
import { getDb } from '../common/pglite/init';
|
||||
|
||||
@Injectable()
|
||||
export class BooksService {
|
||||
async list(): Promise<BookRow[]> {
|
||||
const db = getDb();
|
||||
const { rows } = await db.query<BookRow>(
|
||||
`SELECT * FROM book_shop_book WHERE f_delete_mark = 0 ORDER BY f_creator_time DESC`
|
||||
);
|
||||
return rows;
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
实体字段定义用 interface + 静态类型,不引入 TypeORM 装饰器。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 复杂搜索 / 筛选 / 分页(用最朴素的全表 list,演示用)
|
||||
- 上传 / 图片字段(demo 不需要)
|
||||
- 单元测试(仅 e2e)
|
||||
- i18n / 多语言
|
||||
@@ -0,0 +1,78 @@
|
||||
# Tasks (DAG)
|
||||
|
||||
- id: T1
|
||||
type: architect
|
||||
depends_on: []
|
||||
output: docs/dth/lite-demo/design.md
|
||||
verification: doc 包含 2 个子模块引用、TypeORM-free 选型理由、与 LMS 一致性说明
|
||||
|
||||
- id: T2
|
||||
type: implementer
|
||||
depends_on: [T1]
|
||||
output: |
|
||||
src/backend/src/books/{book.entity.ts,book.service.ts,book.controller.ts,books.module.ts}
|
||||
src/backend/src/shop/{product.entity.ts,product.service.ts,product.controller.ts,shop.module.ts}
|
||||
src/backend/src/common/pglite/init.ts (append 2 tables + seeds)
|
||||
verification:
|
||||
- 文件存在
|
||||
- tsc --noEmit 0 错误(dth 后端范围)
|
||||
- 实体字段名严格遵循 f_ 前缀 + f_id varchar(50) + f_delete_mark int
|
||||
|
||||
- id: T3
|
||||
type: implementer
|
||||
depends_on: [T2]
|
||||
output: |
|
||||
src/frontend/src/views/{Book,Product}.tsx
|
||||
src/frontend/src/api/{book,product}.ts
|
||||
src/frontend/src/App.tsx (add 2 routes)
|
||||
src/backend/src/app.module.ts (register BooksModule + ShopModule)
|
||||
src/backend/src/sys/seed.service.ts (add 2 menus if file exists, else skip)
|
||||
verification:
|
||||
- 后端启动后 curl /books/Book/List + /books/Product/List 返回 200(admin token)
|
||||
- 前端 vite build 0 错误
|
||||
- 菜单数据能在 boot.py 输出
|
||||
|
||||
- id: T4
|
||||
type: tester
|
||||
depends_on: [T3]
|
||||
output: tests/e2e/dth_lite_demo.test.sh
|
||||
verification:
|
||||
- 8 case (S1×2 case, S2×2 case, S3×1 case, S4×2 case, S5×1 case)
|
||||
- 全 PASS
|
||||
|
||||
- id: T5
|
||||
type: qa
|
||||
depends_on: [T4]
|
||||
output: |
|
||||
PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh # gap=0
|
||||
cd src/backend && npx tsc --noEmit # 0 error
|
||||
bash tests/e2e/dth_lite_demo.test.sh # 全 PASS
|
||||
bash tests/e2e/dth_lms.test.sh # chg_0006 回归
|
||||
bash tests/e2e/dth_experiment.test.sh # chg_0002 回归
|
||||
verification:
|
||||
- gap=0
|
||||
- tsc 0 error
|
||||
- 3 个 e2e 全 PASS
|
||||
|
||||
## 依赖关系拓扑
|
||||
|
||||
```
|
||||
T1 (architect) → T2 (backend impl) → T3 (frontend wiring) → T4 (e2e tests) → T5 (qa gate)
|
||||
```
|
||||
|
||||
## 实施步骤约定
|
||||
|
||||
每个 T 完成后必须:
|
||||
1. 在 sandbox 分支上阶段性 git commit(`feat(<scope>): T<n> <short-desc>`)
|
||||
2. 不跳过 git commit 进入下一个 T
|
||||
3. 遇到 npm install / tsc 错误,停下来报告 host,不要硬改 tsconfig
|
||||
|
||||
## 预计耗时
|
||||
|
||||
- T1: 5 min(仅 1 个 md)
|
||||
- T2: 20 min(8 后端文件 + pglite init 拓展)
|
||||
- T3: 15 min(2 前端 view + 2 api + 路由 + 模块注册)
|
||||
- T4: 15 min(8 case e2e 脚本)
|
||||
- T5: 10 min(4 个门禁跑 + 修可能的小问题)
|
||||
|
||||
合计 ~65 min。建议 timeoutSec=4500(75 min)。
|
||||
@@ -0,0 +1,26 @@
|
||||
# spec: lite_demo@chg_0007
|
||||
scenarios:
|
||||
- id: S1
|
||||
cases: [C1_books_list_admin, C2_books_list_nonadmin_600]
|
||||
- id: S2
|
||||
cases: [C3_books_create_admin, C4_books_create_nonadmin_600]
|
||||
- id: S3
|
||||
cases: [C5_shop_list_admin]
|
||||
- id: S4
|
||||
cases: [C6_shop_update_then_soft_delete, C7_shop_remove]
|
||||
- id: S5
|
||||
cases: [C8_menu_and_route_wiring]
|
||||
gate:
|
||||
blocking_gap_tolerance: 0
|
||||
implementation_files:
|
||||
- src/backend/src/books/
|
||||
- src/backend/src/shop/
|
||||
- src/backend/src/common/pglite/init.ts
|
||||
- src/backend/src/app.module.ts
|
||||
- src/frontend/src/views/Book.tsx
|
||||
- src/frontend/src/views/Product.tsx
|
||||
- src/frontend/src/api/book.ts
|
||||
- src/frontend/src/api/product.ts
|
||||
- src/frontend/src/App.tsx
|
||||
test_files:
|
||||
- tests/e2e/dth_lite_demo.test.sh
|
||||
@@ -0,0 +1,89 @@
|
||||
### C1_books_list_admin
|
||||
- Scenario: S1
|
||||
- Type: e2e
|
||||
- Priority: P0
|
||||
- Given: backend running, admin token, 3 books seeded
|
||||
- When: GET `post /books/Book/List` with admin token
|
||||
- Then: response 200 + JSON array, length >= 3
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C2_books_list_nonadmin_600
|
||||
- Scenario: S1
|
||||
- Type: e2e
|
||||
- Priority: P1
|
||||
- Given: backend running, no admin token
|
||||
- When: GET `post /books/Book/List` without token
|
||||
- Then: response code 600 (auth fail)
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C3_books_create_admin
|
||||
- Scenario: S2
|
||||
- Type: e2e
|
||||
- Priority: P0
|
||||
- Given: backend running, admin token
|
||||
- When: POST `post /books/Book/Create` with body `{f_title:"测试书",f_author:"测试",f_isbn:"9787123456789",f_category:"计算机",f_price:"99.00",f_stock:10}`
|
||||
- Then: response 200, body has `code:200`, `data.id` is non-empty
|
||||
- And: subsequent list length increased by 1, new row visible
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C4_books_create_nonadmin_600
|
||||
- Scenario: S2
|
||||
- Type: e2e
|
||||
- Priority: P1
|
||||
- Given: backend running, no admin token
|
||||
- When: POST `post /books/Book/Create` with same body
|
||||
- Then: response code 600
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C5_shop_list_admin
|
||||
- Scenario: S3
|
||||
- Type: e2e
|
||||
- Priority: P0
|
||||
- Given: backend running, admin token, 3 products seeded
|
||||
- When: GET `post /books/Product/List` with admin token
|
||||
- Then: response 200 + JSON array, length >= 3
|
||||
- And: each row has fields `f_id/f_name/f_sku/f_category/f_price/f_stock`
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C6_shop_update_then_soft_delete
|
||||
- Scenario: S4
|
||||
- Type: e2e
|
||||
- Priority: P0
|
||||
- Given: backend running, admin token, at least 1 product
|
||||
- When:
|
||||
1. POST `post /books/Product/Update` with `{id:<seed-id>, f_price:"99.99"}`
|
||||
2. POST `post /books/Product/Remove` with `{id:<same-id>}`
|
||||
- Then:
|
||||
- update response code 200
|
||||
- remove response code 200
|
||||
- subsequent list does NOT include the removed id
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C7_shop_remove
|
||||
- Scenario: S4
|
||||
- Type: e2e
|
||||
- Priority: P1
|
||||
- Given: backend running, admin token
|
||||
- When: POST `post /books/Product/Remove` with body `{id:<existing-id>}`
|
||||
- Then: response code 200
|
||||
- And: row in DB has `f_delete_mark=1`
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
|
||||
### C8_menu_and_route_wiring
|
||||
- Scenario: S5
|
||||
- Type: e2e
|
||||
- Priority: P1
|
||||
- Given: backend running, seed.service executed
|
||||
- When: curl seed endpoint /data-reveal
|
||||
- Then: response includes menus array with entries `urlAddress:"books/Book"` and `urlAddress:"books/Product"`
|
||||
- And: frontend file `src/frontend/src/App.tsx` contains `<Route path="/books/Book"` and `<Route path="/books/Product"`
|
||||
- And: files `src/frontend/src/views/Book.tsx` and `Product.tsx` exist
|
||||
- Automated: true
|
||||
- Bound Task: T4
|
||||
Reference in new issue
Block a user