worldquant-alpha-system/frontend/src/research/FeaturesPage.tsx

import { ResearchList, ResearchDetail } from "./ResearchList";
import { useEffect, useRef, useState } from "react";
import {
  Banner,
  Button,
  Input,
  Pagination,
  TextArea,
  Toast,
} from "@douyinfe/semi-ui-19";
import { ResearchInput } from "../ai/ResearchInput";
import { IconAIEditLevel3 } from "@douyinfe/semi-icons";
import { api, post } from "../api";
import type { PageContext, UIAction } from "../ai/types";
import { TemplateEditor } from "./TemplateEditor";
import { ResearchSelect } from "./ResearchSelect";
import { blankTemplate } from "./workspaceTypes";
import type { Asset, InputSnapshot, Template } from "./workspaceTypes";
import "./workspace.css";

type Feature = {
  name: string;
  hypothesis: string;
  input_ids: string[];
  steps: { name: string; rationale: string; expression: string }[];
  template: Template | null;
};
type FeatureAsset = Omit<Asset, "content"> & { content: Feature };
const blank = (): Feature => ({
  name: "新特征方案",
  hypothesis: "",
  input_ids: [],
  steps: [],
  template: blankTemplate(),
});
export function FeaturesPage({
  active,
  onAction,
  onContext,
  action,
}: {
  active: boolean;
  action?: UIAction | null;
  onAction: (action: UIAction) => void;
  onContext: (context: PageContext) => void;
}) {
  const [detailOpen, setDetailOpen] = useState(false);
  const [draft, setDraft] = useState<Feature>(blank);
  const [asset, setAsset] = useState<FeatureAsset | null>(null);
  const [items, setItems] = useState<FeatureAsset[]>([]);
  const [inputs, setInputs] = useState<InputSnapshot[]>([]);
  const [versions, setVersions] = useState<{ version: number }[]>([]);
  const [page, setPage] = useState(1);
  const [total, setTotal] = useState(0);
  const [q, setQ] = useState("");
  const [busy, setBusy] = useState("");
  const [error, setError] = useState("");
  const [revision, setRevision] = useState(0);
  useEffect(() => {
    if (!active) return;
    const controller = new AbortController();
    Promise.all([
      api<{ items: FeatureAsset[]; total: number }>(
        `/research/assets?kind=feature&q=${encodeURIComponent(q)}&offset=${(page - 1) * 25}`,
        { signal: controller.signal },
      ),
      api<{ items: InputSnapshot[] }>("/research/inputs", {
        signal: controller.signal,
      }),
    ])
      .then(([list, fixed]) => {
        setItems(list.items);
        setTotal(list.total);
        setInputs(fixed.items);
      })
      .catch((e) => {
        if (!controller.signal.aborted) setError(e.message);
      });
    return () => controller.abort();
  }, [active, page, q, revision]);
  useEffect(() => {
    if (active) onContext({ page: "features", research_asset_id: asset?.id });
  }, [active, asset?.id, onContext]);
  const handled = useRef(0);
  useEffect(() => {
    if (
      !active ||
      action?.type !== "open_feature" ||
      handled.current === action.nonce
    )
      return;
    handled.current = action.nonce;
    void run("load", async () =>
      load(
        await api(
          `/research/assets/${action.asset_id}${action.version ? `?version=${action.version}` : ""}`,
        ),
      ),
    );
  }, [active, action]);
  async function load(item: FeatureAsset) {
    setDetailOpen(true);
    setAsset(item);
    setDraft(item.content);
    setVersions(await api(`/research/assets/${item.id}/versions`));
  }
  async function run(name: string, work: () => Promise<void>) {
    setBusy(name);
    setError("");
    try {
      await work();
    } catch (e) {
      setError((e as Error).message);
    } finally {
      setBusy("");
    }
  }
  async function save() {
    const saved = await api<FeatureAsset>(
      `/research/assets${asset ? `/${asset.id}` : ""}`,
      {
        method: asset ? "PUT" : "POST",
        body: JSON.stringify({
          kind: "feature",
          version: asset?.version,
          content: draft,
        }),
      },
    );
    await load(saved);
    setRevision((n) => n + 1);
    return saved;
  }
  return (
    <section className="research-workspace research-list-page">
      {error && !detailOpen && <Banner type="danger" description={error} />}
      <ResearchList
        resetKey={JSON.stringify([q, page])}
        label="特征方案"
        filters={
          <Input
            aria-label="搜索特征方案"
            placeholder="搜索方案"
            value={q}
            onChange={(v) => {
              setQ(v);
              setPage(1);
            }}
          />
        }
        actions={
          <Button
            theme="solid"
            onClick={() => {
              setAsset(null);
              setDraft(blank());
              setVersions([]);
              setDetailOpen(true);
            }}
          >
            新建特征方案
          </Button>
        }
        pagination={
          <>
            <span>共 {total} 个方案</span>
            {total > 0 && (
              <Pagination
                size="small"
                currentPage={page}
                pageSize={25}
                total={total}
                onPageChange={setPage}
              />
            )}
          </>
        }
      >
        <table className="research-table">
          <thead>
            <tr>
              <th>方案名称</th>
              <th>版本</th>
              <th>经济假设</th>
              <th>固定输入</th>
              <th>处理步骤</th>
            </tr>
          </thead>
          <tbody>
            {items.map((item) => (
              <tr key={item.id}>
                <td>
                  <Button
                    theme="borderless"
                    onClick={() => void run("load", () => load(item))}
                  >
                    {item.name}
                  </Button>
                </td>
                <td>v{item.version}</td>
                <td>{item.content.hypothesis || "—"}</td>
                <td>{item.content.input_ids.length}</td>
                <td>{item.content.steps.length}</td>
              </tr>
            ))}
          </tbody>
        </table>
        {!items.length && (
          <p className="research-list-empty">
            暂无特征方案，请新建方案或调整筛选条件。
          </p>
        )}
      </ResearchList>
      <ResearchDetail
        width="min(100vw, max(640px, 60vw))"
        title={asset ? asset.name : "新建特征方案"}
        visible={active && detailOpen}
        onClose={() => setDetailOpen(false)}
      >
        {error && <Banner type="danger" description={error} />}
        <div className="research-main">
          <div className="inline-actions">
            {asset && (
              <>
                <span>版本</span>
                <ResearchSelect
                  label="特征方案版本"
                  value={asset.version}
                  optionList={versions.map((v) => ({
                    value: v.version,
                    label: `v${v.version}`,
                  }))}
                  onChange={(v) =>
                    void run("load", async () => {
                      await load(
                        await api(`/research/assets/${asset.id}?version=${v}`),
                      );
                    })
                  }
                />
              </>
            )}
          </div>
          <label>
            方案名称
            <Input
              aria-label="特征方案名称"
              value={draft.name}
              onChange={(name) => setDraft({ ...draft, name })}
            />
          </label>
          <section className="research-ai-section">
            <h4>
              <IconAIEditLevel3 aria-hidden="true" />
              经济假设
            </h4>
            <ResearchInput
              maxLength={10000}
              label="特征经济假设"
              value={draft.hypothesis}
              onChange={(hypothesis) => setDraft({ ...draft, hypothesis })}
              placeholder="描述特征的经济含义、处理方式和预期信号…"
              references={inputs
                .filter((i) => draft.input_ids.includes(i.id))
                .map((i) => ({
                  id: i.id,
                  name: `${i.dataset_id} · ${i.scope.region}/${i.scope.universe}/D${i.scope.delay} · ${i.field_ids.length} 字段 · ${i.id}`,
                }))}
              disabled={!!busy}
              busy={busy === "generate"}
              canSubmit={!!draft.input_ids.length}
              submitLabel="AI 生成新方案"
              sendHotKey="shift+enter"
              onSubmit={() =>
                void run("generate", async () => {
                  await load(
                    await post<FeatureAsset>("/research/generate", {
                      name: draft.name,
                      hypothesis: draft.hypothesis,
                      input_ids: draft.input_ids,
                      method: "feature",
                    }),
                  );
                  setRevision((n) => n + 1);
                })
              }
              prompts={["研究字段的时序变化，构建具有经济解释的特征"]}
              hint={
                draft.input_ids.length
                  ? "生成处理步骤与输出模板，保留假设供继续迭代。"
                  : "请先在下方关联固定输入。"
              }
            />
          </section>
          <label>
            固定输入
            <ResearchSelect
              label="特征固定输入"
              multiple
              filter
              value={draft.input_ids}
              optionList={inputs.map((i) => ({
                value: i.id,
                label: `${i.dataset_id} · ${i.scope.region}/${i.scope.universe}/D${i.scope.delay} · ${i.field_ids.length} 字段 · ${i.id.slice(0, 8)}`,
              }))}
              onChange={(v) => setDraft({ ...draft, input_ids: v as string[] })}
            />
          </label>
          {inputs
            .filter((i) => draft.input_ids.includes(i.id))
            .map((i) => (
              <details key={i.id}>
                <summary>{i.dataset_id} 的固定字段</summary>
                <p className="muted">{i.field_ids.join("、")}</p>
              </details>
            ))}
          <div className="section-toolbar">
            <h3>处理与迭代步骤</h3>
            <Button
              onClick={() =>
                setDraft({
                  ...draft,
                  steps: [
                    ...draft.steps,
                    { name: "", rationale: "", expression: "" },
                  ],
                })
              }
            >
              添加处理步骤
            </Button>
          </div>
          {draft.steps.map((step, index) => (
            <div className="research-card" key={index}>
              <label>
                步骤 {index + 1}
                <Input
                  aria-label={`步骤 ${index + 1} 名称`}
                  value={step.name}
                  onChange={(name) =>
                    setDraft({
                      ...draft,
                      steps: draft.steps.map((s, i) =>
                        i === index ? { ...s, name } : s,
                      ),
                    })
                  }
                />
              </label>
              <label>
                理由
                <TextArea
                  aria-label={`步骤 ${index + 1} 理由`}
                  value={step.rationale}
                  onChange={(rationale) =>
                    setDraft({
                      ...draft,
                      steps: draft.steps.map((s, i) =>
                        i === index ? { ...s, rationale } : s,
                      ),
                    })
                  }
                />
              </label>
              <label>
                候选表达式
                <TextArea
                  aria-label={`步骤 ${index + 1} 表达式`}
                  value={step.expression}
                  onChange={(expression) =>
                    setDraft({
                      ...draft,
                      steps: draft.steps.map((s, i) =>
                        i === index ? { ...s, expression } : s,
                      ),
                    })
                  }
                />
              </label>
              <Button
                type="danger"
                theme="borderless"
                onClick={() =>
                  setDraft({
                    ...draft,
                    steps: draft.steps.filter((_, i) => i !== index),
                  })
                }
              >
                删除此步骤
              </Button>
            </div>
          ))}
          <h3>输出模板</h3>
          <TemplateEditor
            value={draft.template || blankTemplate()}
            inputs={inputs.filter((i) => draft.input_ids.includes(i.id))}
            onChange={(template) => setDraft({ ...draft, template })}
          />
          <div className="inline-actions">
            <Button
              theme="solid"
              loading={busy === "save"}
              disabled={Boolean(busy)}
              onClick={() =>
                void run("save", async () => {
                  await save();
                  Toast.success("特征方案版本已保存");
                })
              }
            >
              保存特征方案
            </Button>
            <Button
              disabled={Boolean(busy)}
              loading={busy === "convert"}
              onClick={() =>
                void run("convert", async () => {
                  const fixed = await save();
                  const template = await post<Asset>(
                    `/research/features/${fixed.id}/template`,
                    { version: fixed.version },
                  );
                  onAction({
                    type: "open_template",
                    asset_id: template.id,
                    version: template.version,
                    nonce: Date.now(),
                  });
                })
              }
            >
              保存并转为模板
            </Button>
          </div>
          <p className="research-hint">
            保存步骤不会计算原始时间序列。转换后的模板保留此方案的完整版本，回测前仍需展开校验并确认候选。
          </p>
        </div>
      </ResearchDetail>
    </section>
  );
}