diff --git a/openspec/changes/chg_0007_lite_demo_restore/proposal.md b/openspec/changes/chg_0007_lite_demo_restore/proposal.md new file mode 100644 index 0000000..a682ec7 --- /dev/null +++ b/openspec/changes/chg_0007_lite_demo_restore/proposal.md @@ -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 参考实现) \ No newline at end of file diff --git a/openspec/changes/chg_0007_lite_demo_restore/spec.md b/openspec/changes/chg_0007_lite_demo_restore/spec.md new file mode 100644 index 0000000..30e20e6 --- /dev/null +++ b/openspec/changes/chg_0007_lite_demo_restore/spec.md @@ -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 `` 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 { + const db = getDb(); + const { rows } = await db.query( + `SELECT * FROM book_shop_book WHERE f_delete_mark = 0 ORDER BY f_creator_time DESC` + ); + return rows; + } + // ... +} +``` + +实体字段定义用 interface + 静态类型,不引入 TypeORM 装饰器。 + +## 非目标 + +- 复杂搜索 / 筛选 / 分页(用最朴素的全表 list,演示用) +- 上传 / 图片字段(demo 不需要) +- 单元测试(仅 e2e) +- i18n / 多语言 \ No newline at end of file diff --git a/openspec/changes/chg_0007_lite_demo_restore/tasks.md b/openspec/changes/chg_0007_lite_demo_restore/tasks.md new file mode 100644 index 0000000..75c3da5 --- /dev/null +++ b/openspec/changes/chg_0007_lite_demo_restore/tasks.md @@ -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(): T `) +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)。 \ No newline at end of file diff --git a/openspec/changes/chg_0007_lite_demo_restore/testcases.map.yaml b/openspec/changes/chg_0007_lite_demo_restore/testcases.map.yaml new file mode 100644 index 0000000..53ac88b --- /dev/null +++ b/openspec/changes/chg_0007_lite_demo_restore/testcases.map.yaml @@ -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 \ No newline at end of file diff --git a/openspec/changes/chg_0007_lite_demo_restore/testcases.md b/openspec/changes/chg_0007_lite_demo_restore/testcases.md new file mode 100644 index 0000000..461384b --- /dev/null +++ b/openspec/changes/chg_0007_lite_demo_restore/testcases.md @@ -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:, f_price:"99.99"}` + 2. POST `post /books/Product/Remove` with `{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:}` +- 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 `